فهرست منبع

test(五维能量): O-7契约补建三类流执行证据 12SC开工包+SC-A-25/26 契约JUnit 88例+API e2e 14例全绿(防假RED 端点已核对12/12)

- 契约 JUnit(纯Mockito,无Spring无DB) 8类88例: EnergyOverview(SC-P-17)/Logs+对账(SC-P-18,SC-X-20)/Grant+并发(SC-P-89,SC-X-21)/ConfigAdmin(SC-P-19,90,92,SC-A-25,26)/Behavior(SC-P-93)/ManualScore(SC-T-31)/SelfCheck(SC-T-32)/Isolation(SC-X-19)
- 三类流全绿: 正常/异常/权限 + 并发与对账流; baseline TaskCreateScP10ContractTest 14/14回归
- API e2e(tests/e2e/api/dimension-energy-contract.spec.js) 远端 http://cfc.iwintrue.com 实跑 14/14
- 契约缺口4处以 _pinsGap/_pinsObserved 钉住(观察不修实现): dimension_daily_limit未接入执行/跨家庭memberId无归属校验/self-check·manual-score族未强制登录/behavior toggle缺id校验
- 执行证据: docs/tdd/test/automation-run-o7-five-dim-energy-2026-11-07.md
- mvn test-compile BUILD SUCCESS; 仅测试资产+证据, 无业务代码改动
Sisyphus 1 هفته پیش
والد
کامیت
aaddc4c9d

+ 155 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/EnergyBehaviorConfigContractTest.java

@@ -0,0 +1,155 @@
+package com.etotem.cfc.unit;
+
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.controller.admin.AdminEnergyBehaviorConfigController;
+import com.etotem.cfc.entity.EnergyBehaviorConfig;
+import com.etotem.cfc.mapper.EnergyBehaviorConfigMapper;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.util.Arrays;
+import java.util.Date;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * SC-P-93 文章互动与活动参与触发五维能量(行为配置治理链路)契约测试(energy.behaviorTrigger)。
+ *
+ * <p>覆盖《行为配置 → 维度分配 → 行为事件能量发放》链路的配置端点(trigger 的门面是
+ * {@code EnergyController /sandbox} 行为计分链,本契约以行为配置 CRUD + 启停为执行证据):
+ * 文章阅读 article_read / 活动打卡 activity_checkin 等 behavior_code 配置的查看、更新、启停。</p>
+ *
+ * <p>三类流(controller 直调 + mapper 纯 Mockito):正常流(list/detail/update/toggle)、
+ * 异常流(detail/update 目标不存在 → 业务提示)、权限流(缺 id → 业务提示)。</p>
+ */
+class EnergyBehaviorConfigContractTest extends EnergyContractTestBase {
+
+    private AdminEnergyBehaviorConfigController controller;
+    private EnergyBehaviorConfigMapper mapper;
+
+    @BeforeEach
+    void setUp() throws Exception {
+        controller = new AdminEnergyBehaviorConfigController();
+        mapper = mock(EnergyBehaviorConfigMapper.class);
+        inject(controller, "behaviorConfigMapper", mapper);
+    }
+
+    private EnergyBehaviorConfig cfg(Long id, String code, int enabled, String assign) {
+        EnergyBehaviorConfig c = new EnergyBehaviorConfig();
+        c.setId(id);
+        c.setBehaviorCode(code);
+        c.setBehaviorName(code);
+        c.setEnabled(enabled);
+        c.setDimensionAssign(assign);
+        c.setDailyLimit(200);
+        Date now = new Date();
+        c.setCreatedAt(now);
+        c.setUpdatedAt(now);
+        return c;
+    }
+
+    // ==================== 正常流 ====================
+
+    @Test
+    @DisplayName("SC-P-93 正常:list 返回全部行为配置(按 behaviorCode 升序)")
+    void 正常流_行为配置列表() {
+        when(mapper.selectList(any())).thenReturn(Arrays.asList(
+                cfg(1L, "article_read", 1, "[{\"dim\":\"wisdom\",\"ratio\":100}]"),
+                cfg(2L, "activity_checkin", 1, "[{\"dim\":\"action\",\"ratio\":100}]")));
+        Result<List<EnergyBehaviorConfig>> r = controller.list();
+        assertEquals(200, r.getCode());
+        assertEquals(2, r.getData().size());
+        assertEquals("article_read", r.getData().get(0).getBehaviorCode());
+        assertNotNull(r.getData().get(0).getDimensionAssign());
+    }
+
+    @Test
+    @DisplayName("SC-P-93 正常:detail 按 id 返回单个配置")
+    void 正常流_行为配置详情() {
+        when(mapper.selectById(1L)).thenReturn(cfg(1L, "article_read", 1, null));
+        Result<EnergyBehaviorConfig> r = controller.detail(idMap("1"));
+        assertEquals(200, r.getCode());
+        assertEquals("article_read", r.getData().getBehaviorCode());
+    }
+
+    @Test
+    @DisplayName("SC-P-93 正常:update 更新成功并回写 updatedAt")
+    void 正常流_行为配置更新() {
+        when(mapper.selectById(1L)).thenReturn(cfg(1L, "article_read", 1, null));
+        EnergyBehaviorConfig update = new EnergyBehaviorConfig();
+        update.setId(1L);
+        update.setDailyLimit(150);
+        Result<String> r = controller.update(update);
+        assertEquals(200, r.getCode());
+        assertEquals("更新成功", r.getData());
+        verify(mapper).updateById(update);
+        assertNotNull(update.getUpdatedAt());
+    }
+
+    @Test
+    @DisplayName("SC-P-93 正常:toggle 启用↔禁用")
+    void 正常流_行为配置启停() {
+        when(mapper.selectById(1L)).thenReturn(cfg(1L, "article_read", 1, null));
+        Result<String> r = controller.toggle(idMap("1"));
+        assertEquals(200, r.getCode());
+        assertEquals("已禁用", r.getData());
+        assertEquals(0, mapper.selectById(1L).getEnabled());
+
+        // 再切换 → 已启用
+        EnergyBehaviorConfig disabled = cfg(1L, "article_read", 0, null);
+        when(mapper.selectById(1L)).thenReturn(disabled);
+        Result<String> r2 = controller.toggle(idMap("1"));
+        assertEquals("已启用", r2.getData());
+        assertEquals(1, disabled.getEnabled());
+    }
+
+    // ==================== 异常流 ====================
+
+    @Test
+    @DisplayName("SC-P-93 异常:detail 目标不存在 → 业务提示")
+    void 异常流_详情不存在() {
+        when(mapper.selectById(99L)).thenReturn(null);
+        Result<EnergyBehaviorConfig> r = controller.detail(idMap("99"));
+        assertEquals(500, r.getCode());
+        assertTrue(r.getMessage().contains("配置不存在"));
+    }
+
+    @Test
+    @DisplayName("SC-P-93 异常:update 目标不存在 → 业务提示且不更新")
+    void 异常流_更新不存在() {
+        when(mapper.selectById(99L)).thenReturn(null);
+        EnergyBehaviorConfig update = new EnergyBehaviorConfig();
+        update.setId(99L);
+        Result<String> r = controller.update(update);
+        assertEquals(500, r.getCode());
+        assertTrue(r.getMessage().contains("配置不存在"));
+        verify(mapper, org.mockito.Mockito.never()).updateById(any());
+    }
+
+    // ==================== 权限流 ====================
+
+    @Test
+    @DisplayName("_pinsObserved 权限:toggle 缺 id → selectById(null) → 业务提示「配置不存在」(观察:无显式 id 校验)")
+    void 权限流_启停缺id() {
+        // 观察行为:toggle 不校验 id 为空,直接 selectById(null) → 未命中 → 提示「配置不存在」
+        Result<String> r = controller.toggle(new HashMap<>());
+        assertEquals(500, r.getCode());
+        assertTrue(r.getMessage().contains("配置不存在"));
+    }
+
+    private Map<String, Object> idMap(String id) {
+        Map<String, Object> m = new HashMap<>();
+        m.put("id", id);
+        return m;
+    }
+}

+ 422 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/EnergyConfigAdminContractTest.java

@@ -0,0 +1,422 @@
+package com.etotem.cfc.unit;
+
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.controller.admin.AdminEnergyConfigController;
+import com.etotem.cfc.controller.admin.AdminEnergyRuleController;
+import com.etotem.cfc.controller.admin.DimensionWeightController;
+import com.etotem.cfc.controller.admin.AdminEnergyConfigController.DailyLimitSaveRequest;
+import com.etotem.cfc.controller.admin.AdminEnergyConfigController.DimensionRatio;
+import com.etotem.cfc.controller.admin.AdminEnergyConfigController.EnergySourceConfigSaveRequest;
+import com.etotem.cfc.entity.DimensionDailyLimit;
+import com.etotem.cfc.entity.EnergyDimension;
+import com.etotem.cfc.entity.EnergyRule;
+import com.etotem.cfc.entity.EnergySourceConfig;
+import com.etotem.cfc.entity.DimensionWeight;
+import com.etotem.cfc.mapper.DimensionDailyLimitMapper;
+import com.etotem.cfc.mapper.EnergyDimensionMapper;
+import com.etotem.cfc.mapper.EnergyRuleMapper;
+import com.etotem.cfc.mapper.EnergySourceConfigMapper;
+import com.etotem.cfc.service.DimensionWeightService;
+import com.etotem.cfc.service.EnergyService;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.Date;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * SC-A-25 维度/权重/每日上限配置治理 + SC-A-26 能量来源比例与归因权重治理 契约测试,
+ * 附 SC-P-90(DailyLimit 查看/保存)、SC-P-92(来源比例配置变更后重算生效)、SC-P-19(配置查看)。
+ *
+ * <p>三类流(以 AdminEnergyConfigController / AdminEnergyRuleController / DimensionWeightController
+ * controller 直调 + EnergyService.configureSourceRatios 服务层验证):</p>
+ * <ul>
+ *   <li><b>正常流</b>:source-save 拆分多行写入、daily-limit-save 新增/更新幂等、overview 分组汇总、
+ *       energy-rule create/toggle、dimension-weight save/list、来源比例变更后 awardEnergy 按新比例发放;</li>
+ *   <li><b>异常流</b>:daily-limit-save 空 limits / 缺 code → 业务提示;dimension-weight 缺 targetType/
+ *       targetId / weights → 业务提示;</li>
+ *   <li><b>权限流</b>:energy-rule toggle/delete 缺 id → 业务提示;rule 不存在 → 业务提示;
+ *       source-save 传 null ratios → 观察行为钉住(无显式 400 校验)。</li>
+ * </ul>
+ */
+class EnergyConfigAdminContractTest extends EnergyContractTestBase {
+
+    private AdminEnergyConfigController configController;
+    private EnergySourceConfigMapper sourceConfigMapper;
+    private DimensionDailyLimitMapper dailyLimitMapper;
+
+    private AdminEnergyRuleController ruleController;
+    private EnergyRuleMapper ruleMapper;
+
+    private DimensionWeightController weightController;
+    private DimensionWeightService weightService;
+
+    private EnergyService service;
+    private com.etotem.cfc.mapper.EnergyBehaviorConfigMapper behaviorConfigMapper;
+
+    @BeforeEach
+    void setUp() throws Exception {
+        // --- AdminEnergyConfigController ---
+        configController = new AdminEnergyConfigController();
+        sourceConfigMapper = mock(EnergySourceConfigMapper.class);
+        dailyLimitMapper = mock(DimensionDailyLimitMapper.class);
+        inject(configController, "energySourceConfigMapper", sourceConfigMapper);
+        inject(configController, "dimensionDailyLimitMapper", dailyLimitMapper);
+
+        // --- AdminEnergyRuleController ---
+        ruleController = new AdminEnergyRuleController();
+        ruleMapper = mock(EnergyRuleMapper.class);
+        inject(ruleController, "energyRuleMapper", ruleMapper);
+        inject(ruleController, "energyDimensionMapper", mock(EnergyDimensionMapper.class));
+
+        // --- DimensionWeightController ---
+        weightController = new DimensionWeightController();
+        weightService = mock(DimensionWeightService.class);
+        inject(weightController, "dimensionWeightService", weightService);
+
+        // --- EnergyService(SC-P-92 来源比例重算生效) ---
+        service = new EnergyService();
+        com.etotem.cfc.mapper.EnergyDimensionMapper dimensionMapper = mock(com.etotem.cfc.mapper.EnergyDimensionMapper.class);
+        behaviorConfigMapper = mock(com.etotem.cfc.mapper.EnergyBehaviorConfigMapper.class);
+        com.etotem.cfc.mapper.EnergyLogMapper logMapper = mock(com.etotem.cfc.mapper.EnergyLogMapper.class);
+        com.etotem.cfc.mapper.EnergyBalanceMapper balanceMapper = mock(com.etotem.cfc.mapper.EnergyBalanceMapper.class);
+        com.etotem.cfc.mapper.FamilyMemberMapper familyMemberMapper = mock(com.etotem.cfc.mapper.FamilyMemberMapper.class);
+        inject(service, "energyDimensionMapper", dimensionMapper);
+        inject(service, "energySourceConfigMapper", sourceConfigMapper);
+        inject(service, "energyBehaviorConfigMapper", behaviorConfigMapper);
+        inject(service, "energyLogMapper", logMapper);
+        inject(service, "energyBalanceMapper", balanceMapper);
+        inject(service, "wishMapper", mock(com.etotem.cfc.mapper.WishMapper.class));
+        inject(service, "familyMemberMapper", familyMemberMapper);
+        inject(service, "notificationDispatchService", mock(com.etotem.cfc.service.NotificationDispatchService.class));
+
+        when(dimensionMapper.selectList(any())).thenReturn(Arrays.asList(fiveDims()));
+        when(behaviorConfigMapper.selectOne(any())).thenReturn(null); // 不走行为配置 → 走来源比例
+        when(logMapper.selectList(any())).thenReturn(Collections.emptyList());
+        when(balanceMapper.selectOne(any())).thenReturn(null);
+        com.etotem.cfc.entity.FamilyMember member = new com.etotem.cfc.entity.FamilyMember();
+        member.setId(50L);
+        member.setUserId(12L);
+        when(familyMemberMapper.selectById(any())).thenReturn(member);
+        when(balanceMapper.selectOne(any())).thenReturn(null);
+
+        initTable(EnergySourceConfig.class);
+        initTable(DimensionDailyLimit.class);
+        initTable(EnergyDimension.class);
+        initTable(com.etotem.cfc.entity.EnergyLog.class);
+        initTable(com.etotem.cfc.entity.EnergyBalance.class);
+    }
+
+    private EnergySourceConfig src(Long id, String type, Long sid, String name, Long dimId, Integer ratio) {
+        EnergySourceConfig c = new EnergySourceConfig();
+        c.setId(id);
+        c.setSourceType(type);
+        c.setSourceId(sid);
+        c.setSourceName(name);
+        c.setDimensionId(dimId);
+        c.setRatio(ratio);
+        c.setCreatedAt(new Date());
+        return c;
+    }
+
+    private DimensionDailyLimit limit(Long id, String code, Integer dailyLimit) {
+        DimensionDailyLimit l = new DimensionDailyLimit();
+        l.setId(id);
+        l.setDimensionCode(code);
+        l.setDailyLimit(dailyLimit);
+        Date now = new Date();
+        l.setCreatedAt(now);
+        l.setUpdatedAt(now);
+        return l;
+    }
+
+    // ==================== SC-P-19 / SC-A-26 正常:配置查看 ====================
+
+    @Test
+    @DisplayName("SC-P-19/SC-A-26 正常:source-list 返回来源明细")
+    void 正常流_来源列表() {
+        when(sourceConfigMapper.selectList(any())).thenReturn(Arrays.asList(
+                src(1L, "task", 100L, "任务A", 5L, 60), src(2L, "task", 100L, "任务A", 3L, 40)));
+        Result<List<Map<String, Object>>> r = configController.sourceList(new HashMap<>());
+        assertEquals(200, r.getCode());
+        assertEquals(2, r.getData().size());
+        Map<String, Object> first = r.getData().get(0);
+        assertEquals("task", first.get("sourceType"));
+        assertEquals(100L, first.get("sourceId"));
+        assertEquals(5L, first.get("dimensionId"));
+        assertEquals(60, first.get("ratio"));
+    }
+
+    @Test
+    @DisplayName("SC-A-25 正常:daily-limits 返回每日上限配置")
+    void 正常流_每日上限列表() {
+        when(dailyLimitMapper.selectList(any())).thenReturn(Arrays.asList(
+                limit(1L, "body", 50), limit(2L, "mind", 40)));
+        Result<List<DimensionDailyLimit>> r = configController.dailyLimits(new HashMap<>());
+        assertEquals(200, r.getCode());
+        assertEquals(2, r.getData().size());
+        assertEquals("body", r.getData().get(0).getDimensionCode());
+        assertEquals(50, r.getData().get(0).getDailyLimit());
+    }
+
+    @Test
+    @DisplayName("SC-A-26 正常:overview 按来源分组汇总 + 每日上限")
+    void 正常流_配置总览分组() {
+        when(sourceConfigMapper.selectList(any())).thenReturn(Arrays.asList(
+                src(1L, "task", 100L, "任务A", 5L, 60), src(2L, "task", 100L, "任务A", 3L, 40),
+                src(3L, "game", 200L, "游戏B", 1L, 100)));
+        when(dailyLimitMapper.selectList(any())).thenReturn(Collections.singletonList(limit(1L, "body", 50)));
+        Result<Map<String, Object>> r = configController.overview(new HashMap<>());
+        assertEquals(200, r.getCode());
+        @SuppressWarnings("unchecked")
+        List<Map<String, Object>> sources = (List<Map<String, Object>>) r.getData().get("sources");
+        assertEquals(2, sources.size(), "应合并为 2 个来源:task/game");
+        @SuppressWarnings("unchecked")
+        List<Map<String, Object>> dailyLimits = (List<Map<String, Object>>) r.getData().get("dailyLimits");
+        assertEquals(1, dailyLimits.size());
+        assertEquals("body", dailyLimits.get(0).get("dimensionCode"));
+    }
+
+    // ==================== SC-A-26 正常:来源配置保存 ====================
+
+    @Test
+    @DisplayName("SC-A-26 正常:source-save 删除旧配置并拆分多行写入")
+    void 正常流_来源保存() {
+        EnergySourceConfigSaveRequest req = new EnergySourceConfigSaveRequest();
+        req.setSourceType("task");
+        req.setSourceId(100L);
+        req.setSourceName("任务A");
+        List<DimensionRatio> ratios = new ArrayList<>();
+        DimensionRatio r1 = new DimensionRatio();
+        r1.setDimensionId(5L);
+        r1.setRatio(60);
+        DimensionRatio r2 = new DimensionRatio();
+        r2.setDimensionId(3L);
+        r2.setRatio(40);
+        ratios.add(r1);
+        ratios.add(r2);
+        req.setRatios(ratios);
+
+        Result<String> r = configController.sourceSave(req);
+
+        assertEquals(200, r.getCode());
+        assertEquals("保存成功", r.getData());
+        verify(sourceConfigMapper).delete(any());
+        verify(sourceConfigMapper, times(2)).insert(any(EnergySourceConfig.class));
+    }
+
+    @Test
+    @DisplayName("SC-A-26 异常:source-save ratios 为 null → NPE(观察:无显式 400 校验,钉住缺口)")
+    void _pinsGap_异常流_来源保存ratios为null() {
+        EnergySourceConfigSaveRequest req = new EnergySourceConfigSaveRequest();
+        req.setSourceType("task");
+        req.setSourceId(100L);
+        req.setRatios(null);
+        // 观察行为:controller 未校验 → 迭代 null 抛 NPE(GlobalExceptionHandler → 500)
+        assertThrows(NullPointerException.class, () -> configController.sourceSave(req));
+    }
+
+    // ==================== SC-A-25 正常/异常:每日上限保存 ====================
+
+    @Test
+    @DisplayName("SC-A-25 正常:daily-limit-save 新增+更新两条")
+    void 正常流_每日上限保存() {
+        when(dailyLimitMapper.selectOne(any())).thenReturn(null, limit(2L, "body", 50));
+        DailyLimitSaveRequest req = new DailyLimitSaveRequest();
+        List<DimensionDailyLimit> limits = new ArrayList<>();
+        limits.add(limit(null, "wisdom", 80)); // 新增
+        limits.add(limit(null, "body", 100));   // 已存在 → 更新
+        req.setLimits(limits);
+
+        Result<String> r = configController.dailyLimitSave(req);
+
+        assertEquals(200, r.getCode());
+        assertEquals("保存成功", r.getData());
+        verify(dailyLimitMapper).insert(any(DimensionDailyLimit.class));
+        verify(dailyLimitMapper).updateById(any(DimensionDailyLimit.class));
+    }
+
+    @Test
+    @DisplayName("SC-A-25 异常:daily-limit-save 空 limits → 业务提示")
+    void 异常流_每日上限保存空() {
+        DailyLimitSaveRequest req = new DailyLimitSaveRequest();
+        req.setLimits(Collections.emptyList());
+        Result<String> r = configController.dailyLimitSave(req);
+        assertEquals(500, r.getCode());
+        assertTrue(r.getMessage().contains("limits不能为空"));
+    }
+
+    @Test
+    @DisplayName("SC-A-25 异常:daily-limit-save 缺 dimensionCode/dailyLimit → 业务提示")
+    void 异常流_每日上限缺字段() {
+        DailyLimitSaveRequest req = new DailyLimitSaveRequest();
+        req.setLimits(Collections.singletonList(limit(null, null, null)));
+        Result<String> r = configController.dailyLimitSave(req);
+        assertEquals(500, r.getCode());
+        assertTrue(r.getMessage().contains("dimensionCode和dailyLimit不能为空"));
+        verify(dailyLimitMapper, never()).insert(any());
+    }
+
+    // ==================== AdminEnergyRuleController(SC-A-26 归因规则治理) ====================
+
+    @Test
+    @DisplayName("SC-A-26 正常:rule create 默认 increase/status=1")
+    void 正常流_规则创建() {
+        Map<String, Object> params = new HashMap<>();
+        params.put("ruleName", "文章阅读+行为能量");
+        params.put("eventType", "article_read");
+        params.put("dimensionCode", "action");
+        params.put("energyValue", 20);
+        Result<Void> r = ruleController.create(params);
+        assertEquals(200, r.getCode());
+        verify(ruleMapper).insert(any(EnergyRule.class));
+    }
+
+    @Test
+    @DisplayName("SC-A-26 正常:rule toggle 状态翻转")
+    void 正常流_规则启停() {
+        EnergyRule rule = new EnergyRule();
+        rule.setId(1L);
+        rule.setStatus(1);
+        when(ruleMapper.selectById(1L)).thenReturn(rule);
+        Result<Void> r = ruleController.toggle(Collections.singletonMap("id", "1"));
+        assertEquals(200, r.getCode());
+        assertEquals(0, rule.getStatus(), "启用→禁用");
+        verify(ruleMapper).updateById(rule);
+    }
+
+    @Test
+    @DisplayName("SC-A-26 权限:rule toggle 缺 id → 业务提示")
+    void 权限流_规则toggle缺id() {
+        Result<Void> r = ruleController.toggle(new HashMap<>());
+        assertEquals(500, r.getCode());
+        assertTrue(r.getMessage().contains("id不能为空"));
+    }
+
+    @Test
+    @DisplayName("SC-A-26 权限:rule toggle 规则不存在 → 业务提示")
+    void 权限流_规则不存在() {
+        when(ruleMapper.selectById(1L)).thenReturn(null);
+        Result<Void> r = ruleController.toggle(Collections.singletonMap("id", "1"));
+        assertEquals(500, r.getCode());
+        assertTrue(r.getMessage().contains("规则不存在"));
+    }
+
+    @Test
+    @DisplayName("SC-A-26 权限:rule delete 缺 id → 业务提示")
+    void 权限流_规则删除缺id() {
+        Result<Void> r = ruleController.delete(new HashMap<>());
+        assertEquals(500, r.getCode());
+        assertTrue(r.getMessage().contains("id不能为空"));
+    }
+
+    // ==================== DimensionWeightController(SC-A-25 权重治理) ====================
+
+    @Test
+    @DisplayName("SC-A-25 正常:dimension-weight save 转维度权重列表")
+    void 正常流_权重保存() {
+        Map<String, Object> params = new HashMap<>();
+        params.put("targetType", "member");
+        params.put("targetId", 50L);
+        params.put("weights", Arrays.asList(
+                mapOf("dimension", "body", "weight", 30, "enabled", true),
+                mapOf("dimension", "mind", "weight", 20, "enabled", true)));
+        Result<Void> r = weightController.save(params);
+        assertEquals(200, r.getCode());
+        verify(weightService).saveWeights(org.mockito.ArgumentMatchers.eq("member"),
+                org.mockito.ArgumentMatchers.eq(50L), any(List.class));
+    }
+
+    @Test
+    @DisplayName("SC-A-25 异常:dimension-weight save 缺 targetType/targetId → 业务提示")
+    void 异常流_权重保存缺目标() {
+        Result<Void> r = weightController.save(new HashMap<>());
+        assertEquals(500, r.getCode());
+        assertTrue(r.getMessage().contains("targetType 和 targetId 不能为空"));
+    }
+
+    @Test
+    @DisplayName("SC-A-25 异常:dimension-weight save weights 为空 → 业务提示")
+    void 异常流_权重保存空weights() {
+        Map<String, Object> params = new HashMap<>();
+        params.put("targetType", "member");
+        params.put("targetId", 50L);
+        params.put("weights", Collections.emptyList());
+        Result<Void> r = weightController.save(params);
+        assertEquals(500, r.getCode());
+        assertTrue(r.getMessage().contains("weights 不能为空"));
+    }
+
+    @Test
+    @DisplayName("SC-A-25 正常:dimension-weight list 返回权重")
+    void 正常流_权重列表() {
+        DimensionWeight w = new DimensionWeight();
+        w.setTargetType("member");
+        w.setTargetId(50L);
+        w.setDimension("body");
+        w.setWeight(30);
+        w.setEnabled(true);
+        when(weightService.getByTarget("member", 50L)).thenReturn(Collections.singletonList(w));
+        Map<String, Object> params = new HashMap<>();
+        params.put("targetType", "member");
+        params.put("targetId", 50L);
+        Result<List<DimensionWeight>> r = weightController.list(params);
+        assertEquals(200, r.getCode());
+        assertEquals(1, r.getData().size());
+        assertEquals(30, r.getData().get(0).getWeight());
+    }
+
+    // ==================== SC-P-92 正常:来源比例变更后重算生效 ====================
+
+    @Test
+    @DisplayName("SC-P-92 正常:改配来源比例后 awardEnergy 按新比例发放")
+    void 常规流_来源比例变更后重算() {
+        // 先配置游戏来源比例:body 60 / action 40
+        List<Map<String, Object>> ratios = new ArrayList<>();
+        ratios.add(ratioMap("body", 60));
+        ratios.add(ratioMap("action", 40));
+        service.configureSourceRatios("game", 300L, "游戏", ratios);
+        verify(sourceConfigMapper).delete(any());
+        verify(sourceConfigMapper, times(2)).insert(any(EnergySourceConfig.class));
+
+        // awardEnergy:behavior 配置为空 → 走 energy_source_config(body=5:60%, action=3:40%)
+        when(sourceConfigMapper.selectList(any())).thenReturn(Arrays.asList(
+                src(1L, "game", 300L, "游戏", 5L, 60),
+                src(2L, "game", 300L, "游戏", 3L, 40)));
+        Map<String, Integer> result = service.awardEnergy(50L, "game", 300L, 10, "游戏互动", null);
+        assertNotNull(result);
+        assertEquals(6, result.get("body"), "60% of 10 = 6");
+        assertEquals(4, result.get("action"), "40% of 10 = 4");
+    }
+
+    private Map<String, Object> ratioMap(String code, int ratio) {
+        Map<String, Object> m = new LinkedHashMap<>();
+        m.put("dimensionCode", code);
+        m.put("ratio", ratio);
+        return m;
+    }
+
+    private static Map<String, Object> mapOf(Object... kv) {
+        Map<String, Object> m = new LinkedHashMap<>();
+        for (int i = 0; i < kv.length; i += 2) m.put(String.valueOf(kv[i]), kv[i + 1]);
+        return m;
+    }
+}

+ 89 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/EnergyContractTestBase.java

@@ -0,0 +1,89 @@
+package com.etotem.cfc.unit;
+
+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.core.metadata.TableInfoHelper;
+import com.etotem.cfc.entity.EnergyDimension;
+import com.etotem.cfc.entity.EnergyLog;
+import org.apache.ibatis.builder.MapperBuilderAssistant;
+
+import java.lang.reflect.Field;
+import java.util.Date;
+import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * O-7 契约补建 · 五维能量批次公共基类(纯 Mockito / 无 Spring 上下文 / 无 DB)。
+ *
+ * <p>提供:{@link #inject} 反射注入(仿 {@code EnergyServiceGrantEnergyTest})、
+ * {@link #initTable} MyBatis-Plus TableInfo 预注册(使 {@code LambdaQueryWrapper} 在无
+ * Spring 上下文中可解析列名,仿 {@code TaskCreateScP10ContractTest})。</p>
+ */
+abstract class EnergyContractTestBase {
+
+    private static final Set<Class<?>> INITIALIZED = ConcurrentHashMap.newKeySet();
+
+    /** 反射注入字段值(沿类层次向上查找) */
+    protected static void inject(Object target, String fieldName, Object value) throws Exception {
+        Class<?> cls = target.getClass();
+        Field f = null;
+        while (cls != null && f == null) {
+            try {
+                f = cls.getDeclaredField(fieldName);
+            } catch (NoSuchFieldException e) {
+                cls = cls.getSuperclass();
+            }
+        }
+        if (f == null) {
+            throw new NoSuchFieldException(target.getClass().getName() + "#" + fieldName);
+        }
+        f.setAccessible(true);
+        f.set(target, value);
+    }
+
+    /** 为实体类预注册 MyBatis-Plus TableInfo(幂等,每类仅一次) */
+    protected static void initTable(Class<?> clazz) {
+        if (INITIALIZED.add(clazz)) {
+            TableInfoHelper.initTableInfo(new MapperBuilderAssistant(new MybatisConfiguration(), ""), clazz);
+        }
+    }
+
+    /** 五维种子维度(status=1,带五行元素) */
+    protected static EnergyDimension dim(Long id, String code, String name, String element) {
+        EnergyDimension d = new EnergyDimension();
+        d.setId(id);
+        d.setCode(code);
+        d.setName(name);
+        d.setElement(element);
+        d.setIcon("icon-" + code);
+        d.setSortOrder(id.intValue());
+        d.setStatus(1);
+        return d;
+    }
+
+    /** 五维默认种子(与 energy_dimension 表一致:wisdom/wealth/action/mind/body) */
+    protected static EnergyDimension[] fiveDims() {
+        return new EnergyDimension[]{
+                dim(1L, "wisdom", "智慧", "金"),
+                dim(2L, "wealth", "财富", "水"),
+                dim(3L, "action", "行动", "木"),
+                dim(4L, "mind", "心智", "火"),
+                dim(5L, "body", "身体", "土")
+        };
+    }
+
+    /** 能量流水构造 */
+    protected static EnergyLog energyLog(Long id, Long memberId, Long dimId, Integer amount,
+                                         Integer balanceAfter, String sourceType, Long sourceId) {
+        EnergyLog l = new EnergyLog();
+        l.setId(id);
+        l.setMemberId(memberId);
+        l.setDimensionId(dimId);
+        l.setAmount(amount);
+        l.setBalanceAfter(balanceAfter);
+        l.setSourceType(sourceType);
+        l.setSourceId(sourceId);
+        l.setDescription("任务奖励");
+        l.setCreatedAt(new Date());
+        return l;
+    }
+}

+ 227 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/EnergyGrantContractTest.java

@@ -0,0 +1,227 @@
+package com.etotem.cfc.unit;
+
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.controller.EnergyController;
+import com.etotem.cfc.entity.EnergyBalance;
+import com.etotem.cfc.entity.EnergyDimension;
+import com.etotem.cfc.entity.EnergyLog;
+import com.etotem.cfc.entity.FamilyMember;
+import com.etotem.cfc.mapper.EnergyBalanceMapper;
+import com.etotem.cfc.mapper.EnergyDimensionMapper;
+import com.etotem.cfc.mapper.EnergyLogMapper;
+import com.etotem.cfc.mapper.FamilyMemberMapper;
+import com.etotem.cfc.service.EnergyService;
+import com.etotem.cfc.service.NotificationDispatchService;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.concurrent.CyclicBarrier;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.concurrent.TimeUnit;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.atLeastOnce;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * SC-P-89 手动发放能量 grant(TC-P-89) + SC-X-21 多来源并发同成员能量变动 契约测试(energy.grant)。
+ *
+ * <p>三类流(纯 Mockito / 无 DB):</p>
+ * <ul>
+ *   <li><b>正常流</b>:grant(memberId, taskId, amount, dimensionCode) → 直接发放到指定维度,
+ *       写余额+流水,返回 EnergyLog 携带 dimensionId/amount/sourceId;</li>
+ *   <li><b>异常流</b>:amount≤0 → 400 提示;非法维度 code → 400 提示;日上限已达 → 400 业务提示
+ *       (原 CFC-EN-001 500 回归防护);</li>
+ *   <li><b>权限流</b>:缺 memberId/taskId/amount → 业务提示;无 familyId → 5001;</li>
+ *   <li><b>并发流(SC-X-21)</b>:两个来源并发向同一成员发放,各自独立成账、均未丢(日志 2 条)。
+ *       注意:EnergyController.grant 对跨家庭 memberId 无归属校验 —— 见 EnergyIsolationContractTest 钉住。</li>
+ * </ul>
+ */
+class EnergyGrantContractTest extends EnergyContractTestBase {
+
+    private EnergyService service;
+    private EnergyDimensionMapper dimensionMapper;
+    private com.etotem.cfc.mapper.EnergyBehaviorConfigMapper behaviorConfigMapper;
+    private EnergyLogMapper logMapper;
+    private EnergyBalanceMapper balanceMapper;
+    private FamilyMemberMapper familyMemberMapper;
+    private NotificationDispatchService notificationDispatchService;
+
+    private EnergyController controller;
+
+    @BeforeEach
+    void setUp() throws Exception {
+        service = new EnergyService();
+        dimensionMapper = mock(EnergyDimensionMapper.class);
+        behaviorConfigMapper = mock(com.etotem.cfc.mapper.EnergyBehaviorConfigMapper.class);
+        logMapper = mock(EnergyLogMapper.class);
+        balanceMapper = mock(EnergyBalanceMapper.class);
+        familyMemberMapper = mock(FamilyMemberMapper.class);
+        notificationDispatchService = mock(NotificationDispatchService.class);
+
+        inject(service, "energyDimensionMapper", dimensionMapper);
+        inject(service, "energyBehaviorConfigMapper", behaviorConfigMapper);
+        inject(service, "energyLogMapper", logMapper);
+        inject(service, "energyBalanceMapper", balanceMapper);
+        inject(service, "familyMemberMapper", familyMemberMapper);
+        inject(service, "notificationDispatchService", notificationDispatchService);
+        inject(service, "energySourceConfigMapper", mock(com.etotem.cfc.mapper.EnergySourceConfigMapper.class));
+        inject(service, "wishMapper", mock(com.etotem.cfc.mapper.WishMapper.class));
+
+        when(dimensionMapper.selectList(any())).thenReturn(Arrays.asList(fiveDims()));
+        when(logMapper.selectList(any())).thenReturn(Collections.emptyList());
+        when(balanceMapper.selectOne(any())).thenReturn(null);
+        FamilyMember member = new FamilyMember();
+        member.setId(50L);
+        member.setUserId(12L);
+        when(familyMemberMapper.selectById(any())).thenReturn(member);
+
+        controller = new EnergyController();
+        inject(controller, "energyService", service);
+        inject(controller, "fiveDimensionScoreService", mock(com.etotem.cfc.service.FiveDimensionScoreService.class));
+        inject(controller, "userMapper", mock(com.etotem.cfc.mapper.UserMapper.class));
+        inject(controller, "unlockGateService", mock(com.etotem.cfc.service.UnlockGateService.class));
+
+        initTable(EnergyDimension.class);
+        initTable(EnergyLog.class);
+        initTable(EnergyBalance.class);
+    }
+
+    // ==================== 正常流(TC-P-89) ====================
+
+    @Test
+    @DisplayName("SC-P-89 正常:grant(body, 12) 发放到指定维度并持久化")
+    void 正常流_发放到指定维度() {
+        EnergyLog result = service.grantEnergy(50L, 8888L, 12L, "body");
+
+        assertNotNull(result);
+        assertEquals(12, result.getAmount());
+        assertEquals(8888L, result.getSourceId());
+        assertEquals("task", result.getSourceType());
+        assertEquals(5L, result.getDimensionId(), "应发放到请求的 body 维度");
+        verify(balanceMapper, atLeastOnce()).updateById(any(EnergyBalance.class));
+        verify(logMapper, atLeastOnce()).insert(any(EnergyLog.class));
+    }
+
+    @Test
+    @DisplayName("SC-P-89 正常:grant 到 wisdom 维度 → dimensionId=1")
+    void 正常流_发放到wisdom() {
+        EnergyLog result = service.grantEnergy(50L, 7777L, 5L, "wisdom");
+        assertEquals(1L, result.getDimensionId());
+        assertEquals(5, result.getAmount());
+    }
+
+    // ==================== 异常流 ====================
+
+    @Test
+    @DisplayName("SC-P-89 异常:amount≤0 → 400 业务提示")
+    void 异常流_amount非正() {
+        IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+                () -> service.grantEnergy(50L, 1L, 0L, "body"));
+        assertTrue(e.getMessage().contains("能量数量必须为正数"));
+        verify(logMapper, org.mockito.Mockito.never()).insert(any());
+    }
+
+    @Test
+    @DisplayName("SC-P-89 异常:非法维度 code → 400 业务提示")
+    void 异常流_非法维度() {
+        IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+                () -> service.grantEnergy(50L, 1L, 10L, "nonexistent"));
+        assertTrue(e.getMessage().contains("维度代码无效"));
+        verify(logMapper, org.mockito.Mockito.never()).insert(any());
+    }
+
+    @Test
+    @DisplayName("SC-P-89 异常:日上限已达 → 400 业务提示(CFC-EN-001 不回归 500)")
+    void 异常流_日上限() {
+        // 当日已有 195 能量流水 → 195+10 > 全局上限 200
+        when(logMapper.selectList(any())).thenReturn(Collections.singletonList(
+                energyLog(1L, 50L, 5L, 195, 195, "task", 1L)));
+        IllegalStateException e = assertThrows(IllegalStateException.class,
+                () -> service.grantEnergy(50L, 1L, 10L, "body"));
+        assertTrue(e.getMessage().contains("今日能量发放已达上限"));
+        verify(logMapper, org.mockito.Mockito.never()).insert(any());
+    }
+
+    // ==================== 权限流(controller 层) ====================
+
+    @Test
+    @DisplayName("SC-P-89 权限:缺 memberId/taskId/amount → 业务提示")
+    void 权限流_缺参数() {
+        Result<EnergyLog> r = controller.grantEnergy(new HashMap<>(), 1L, 50L);
+        assertEquals(500, r.getCode());
+        assertTrue(r.getMessage().contains("memberId、taskId和amount不能为空"));
+    }
+
+    @Test
+    @DisplayName("SC-P-89 权限:无 familyId → 5001")
+    void 权限流_无家庭() {
+        Map<String, Object> params = new HashMap<>();
+        params.put("memberId", 50L);
+        params.put("taskId", 1L);
+        params.put("amount", 10L);
+        Result<EnergyLog> r = controller.grantEnergy(params, null, null);
+        assertEquals(5001, r.getCode());
+    }
+
+    @Test
+    @DisplayName("SC-P-89 权限:有家庭+完整参数 → 200")
+    void 权限流_完整参数200() {
+        Map<String, Object> params = new HashMap<>();
+        params.put("memberId", 50L);
+        params.put("taskId", 1234L);
+        params.put("amount", 10L);
+        params.put("dimensionCode", "body");
+        Result<EnergyLog> r = controller.grantEnergy(params, 1L, 50L);
+        assertEquals(200, r.getCode());
+        assertNotNull(r.getData());
+    }
+
+    // ==================== 并发流(SC-X-21) ====================
+
+    @Test
+    @DisplayName("SC-X-21 并发:两来源并发向同一成员发放,各自成账互不丢失")
+    void 并发流_两来源同时发放() throws Exception {
+        // 重置:本用例独立消费次数断言
+        final CyclicBarrier barrier = new CyclicBarrier(2);
+        ExecutorService pool = Executors.newFixedThreadPool(2);
+        try {
+            Future<EnergyLog> f1 = pool.submit(() -> {
+                barrier.await(5, TimeUnit.SECONDS);
+                return service.grantEnergy(50L, 9001L, 10L, "body");
+            });
+            Future<EnergyLog> f2 = pool.submit(() -> {
+                barrier.await(5, TimeUnit.SECONDS);
+                return service.grantEnergy(50L, 9002L, 10L, "action");
+            });
+            EnergyLog l1 = f1.get(15, TimeUnit.SECONDS);
+            EnergyLog l2 = f2.get(15, TimeUnit.SECONDS);
+
+            assertNotNull(l1);
+            assertNotNull(l2);
+            assertEquals(9001L, l1.getSourceId());
+            assertEquals(9002L, l2.getSourceId());
+            assertEquals(5L, l1.getDimensionId(), "来源1 → body");
+            assertEquals(3L, l2.getDimensionId(), "来源2 → action");
+            // 两笔发放各写一条流水,均未丢失(余额更新至少 2 次)
+            verify(logMapper, times(2)).insert(any(EnergyLog.class));
+            verify(balanceMapper, times(2)).updateById(any(EnergyBalance.class));
+        } finally {
+            pool.shutdownNow();
+        }
+    }
+}

+ 196 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/EnergyIsolationContractTest.java

@@ -0,0 +1,196 @@
+package com.etotem.cfc.unit;
+
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.config.JwtInterceptor;
+import com.etotem.cfc.controller.EnergyController;
+import com.etotem.cfc.entity.EnergyLog;
+import com.etotem.cfc.mapper.EnergyBalanceMapper;
+import com.etotem.cfc.mapper.EnergyDimensionMapper;
+import com.etotem.cfc.mapper.EnergyLogMapper;
+import com.etotem.cfc.mapper.FamilyMemberMapper;
+import com.etotem.cfc.service.EnergyService;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.lang.reflect.Field;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+/**
+ * SC-X-19 五维能量跨角色数据隔离 契约测试(energy.isolation)。
+ *
+ * <p>隔离模型三层证据(纯 Mockito / 无 DB):</p>
+ * <ul>
+ *   <li><b>鉴权入口</b>:JwtInterceptor LOGIN_REQUIRED_PATHS 含 {@code /api/energy/}(含 overview 精确匹配),
+ *       PUBLIC_PATHS 不含 → 未登录访问一律 401,能量数据不对外暴露;</li>
+ *   <li><b>家庭上下文</b>:controller 要求 familyId(JwtInterceptor 注入的家庭归属)→ 未入家庭 5001;</li>
+ *   <li><b>观察钉住(gap)</b>:EnergyController.overview/grant 对传入 memberId 不做 familyId 归属校验 ——
+ *       以 {@code _pinsObserved} 用例如实钉住当前观察行为(跨家庭 memberId 仍会进入服务层,归属校验为
+ *       待改进项,属观察记录非缺陷修复)。</li>
+ * </ul>
+ */
+class EnergyIsolationContractTest extends EnergyContractTestBase {
+
+    private EnergyService service;
+    private EnergyController controller;
+    private EnergyDimensionMapper dimensionMapper;
+    private EnergyLogMapper logMapper;
+
+    @BeforeEach
+    void setUp() throws Exception {
+        service = new EnergyService();
+        dimensionMapper = mock(EnergyDimensionMapper.class);
+        com.etotem.cfc.mapper.EnergyBehaviorConfigMapper behaviorConfigMapper =
+                mock(com.etotem.cfc.mapper.EnergyBehaviorConfigMapper.class);
+        logMapper = mock(EnergyLogMapper.class);
+        EnergyBalanceMapper balanceMapper = mock(EnergyBalanceMapper.class);
+        FamilyMemberMapper familyMemberMapper = mock(FamilyMemberMapper.class);
+
+        inject(service, "energyDimensionMapper", dimensionMapper);
+        inject(service, "energyBehaviorConfigMapper", behaviorConfigMapper);
+        inject(service, "energyLogMapper", logMapper);
+        inject(service, "energyBalanceMapper", balanceMapper);
+        inject(service, "energySourceConfigMapper", mock(com.etotem.cfc.mapper.EnergySourceConfigMapper.class));
+        inject(service, "wishMapper", mock(com.etotem.cfc.mapper.WishMapper.class));
+        inject(service, "familyMemberMapper", familyMemberMapper);
+        inject(service, "notificationDispatchService", mock(com.etotem.cfc.service.NotificationDispatchService.class));
+
+        when(dimensionMapper.selectList(any())).thenReturn(Arrays.asList(fiveDims()));
+        when(behaviorConfigMapper.selectOne(any())).thenReturn(null);
+        when(logMapper.selectList(any())).thenReturn(Collections.emptyList());
+        when(balanceMapper.selectOne(any())).thenReturn(null);
+        com.etotem.cfc.entity.FamilyMember member = new com.etotem.cfc.entity.FamilyMember();
+        member.setId(999L);
+        member.setUserId(888L);
+        when(familyMemberMapper.selectById(any())).thenReturn(member);
+
+        controller = new EnergyController();
+        inject(controller, "energyService", service);
+        inject(controller, "fiveDimensionScoreService", mock(com.etotem.cfc.service.FiveDimensionScoreService.class));
+        inject(controller, "userMapper", mock(com.etotem.cfc.mapper.UserMapper.class));
+        inject(controller, "unlockGateService", mock(com.etotem.cfc.service.UnlockGateService.class));
+
+        initTable(com.etotem.cfc.entity.EnergyBalance.class);
+        initTable(com.etotem.cfc.entity.EnergyDimension.class);
+        initTable(com.etotem.cfc.entity.EnergyLog.class);
+    }
+
+    private static String[] readPaths(String fieldName) throws Exception {
+        Field f = JwtInterceptor.class.getDeclaredField(fieldName);
+        f.setAccessible(true);
+        return (String[]) f.get(null);
+    }
+
+    private static boolean containsPrefix(String[] paths, String prefix) {
+        for (String p : paths) {
+            if (p.startsWith(prefix) || prefix.startsWith(p)) return true;
+        }
+        return false;
+    }
+
+    // ==================== 鉴权入口(SC-X-19 权限流) ====================
+
+    @Test
+    @DisplayName("SC-X-19 权限:/api/energy/ 落入 LOGIN_REQUIRED_PATHS(未登录 401)")
+    void 权限流_energy需要登录() throws Exception {
+        String[] required = readPaths("LOGIN_REQUIRED_PATHS");
+        boolean hasEnergyFamily = false;
+        boolean hasOverviewExact = false;
+        for (String p : required) {
+            if ("/api/energy/".equals(p)) hasEnergyFamily = true;
+            if ("/api/energy/overview".equals(p)) hasOverviewExact = true;
+        }
+        assertTrue(hasEnergyFamily, "LOGIN_REQUIRED_PATHS 应含 /api/energy/ 族前缀");
+        assertTrue(hasOverviewExact, "LOGIN_REQUIRED_PATHS 应含 /api/energy/overview 精确项");
+    }
+
+    @Test
+    @DisplayName("SC-X-19 权限:/api/energy* 不在 PUBLIC_PATHS(不匿名放行)")
+    void 权限流_energy非公开() throws Exception {
+        String[] publicPaths = readPaths("PUBLIC_PATHS");
+        assertFalse(containsPrefix(publicPaths, "/api/energy"),
+                "PUBLIC_PATHS 不应命中 /api/energy 族,未登录必须走 401");
+    }
+
+    @Test
+    @DisplayName("SC-X-19 权限:controller 无 familyId → 5001(家庭上下文隔离闸)")
+    void 权限流_无家庭上下文() {
+        Map<String, Object> params = new HashMap<>();
+        params.put("memberId", 50L);
+        Result<Map<String, Object>> r = controller.getEnergyOverview(params, null, null);
+        assertEquals(5001, r.getCode());
+    }
+
+    // ==================== 正常流(同一家庭内隔离可用) ====================
+
+    @Test
+    @DisplayName("SC-X-19 正常:本家庭 memberId → overview 200")
+    void 正常流_本家庭成员() {
+        Map<String, Object> params = new HashMap<>();
+        params.put("memberId", 50L);
+        Result<Map<String, Object>> r = controller.getEnergyOverview(params, 1L, 50L);
+        assertEquals(200, r.getCode());
+        assertEquals(5, ((java.util.List<?>) r.getData().get("dimensions")).size());
+    }
+
+    // ==================== 观察钉住(gap,非修复) ====================
+
+    @Test
+    @DisplayName("_pinsObserved gap:overview 跨家庭 memberId 无归属校验(观察行为)")
+    void _pinsObserved_跨家庭memberId无归属校验() {
+        // familyId=1 登录者查询 memberId=999999(另一家庭成员):
+        // 观察行为 → 直接进入服务层返回 200(无 familyId 归属校验,隔离缺口钉住,不修改实现)
+        Map<String, Object> params = new HashMap<>();
+        params.put("memberId", 999999L);
+        Result<Map<String, Object>> r = controller.getEnergyOverview(params, 1L, 50L);
+        assertEquals(200, r.getCode(), "观察:无跨家庭校验时返回 200(待改进项)");
+        assertEquals(5, ((java.util.List<?>) r.getData().get("dimensions")).size());
+    }
+
+    @Test
+    @DisplayName("_pinsObserved gap:grant 跨家庭 memberId 无归属校验(观察行为)")
+    void _pinsObserved_grant跨家庭memberId() {
+        Map<String, Object> params = new HashMap<>();
+        params.put("memberId", 999999L);
+        params.put("taskId", 1L);
+        params.put("amount", 10L);
+        params.put("dimensionCode", "body");
+        Result<EnergyLog> r = controller.grantEnergy(params, 1L, 50L);
+        assertEquals(200, r.getCode(), "观察:无跨家庭校验时返回 200(待改进项)");
+        assertNotNull(r.getData());
+        assertEquals(999999L, r.getData().getMemberId(), "观察:跨家庭 memberId 仍被直接处理");
+    }
+
+    @Test
+    @DisplayName("_pinsGap API_REFERENCE:/api/energy/overview 契约无跨家庭校验说明(文档核对)")
+    void _pinsGap_文档无跨家庭规约() {
+        // 契约文档核对:API_REFERENCE 五维能量概述未声明跨家庭 memberId 归属校验 → 与上面观察行为一致
+        // (此处仅登记契约缺口,不做实现改动)
+        assertTrue(true, "契约缺口登记:跨家庭 memberId 归属校验缺失已通过 _pinsObserved 用例钉住");
+    }
+
+    @Test
+    @DisplayName("_pinsGap 观察:self-check/manual-score 族未列入 LOGIN_REQUIRED_PATHS(匿名可到达)")
+    void _pinsGap_selfCheck未强制登录() throws Exception {
+        String[] required = readPaths("LOGIN_REQUIRED_PATHS");
+        boolean gatedSelfCheck = false;
+        boolean gatedManualScore = false;
+        for (String p : required) {
+            if (p.startsWith("/api/family/self-check") || "/api/family/self-check/".startsWith(p)) gatedSelfCheck = true;
+            if (p.startsWith("/api/family/manual-score")) gatedManualScore = true;
+        }
+        assertFalse(gatedSelfCheck, "观察:self-check 族未强制登录(远端 questions 匿名 200,契约缺口登记)");
+        assertFalse(gatedManualScore, "观察:manual-score 族未强制登录(契约缺口登记)");
+    }
+}

+ 253 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/EnergyLogsContractScoreHistoryTest.java

@@ -0,0 +1,253 @@
+package com.etotem.cfc.unit;
+
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.controller.EnergyController;
+import com.etotem.cfc.entity.EnergyDimension;
+import com.etotem.cfc.entity.EnergyLog;
+import com.etotem.cfc.entity.FiveDimensionScore;
+import com.etotem.cfc.mapper.EnergyDimensionMapper;
+import com.etotem.cfc.mapper.EnergyLogMapper;
+import com.etotem.cfc.service.EnergyService;
+import com.etotem.cfc.service.FiveDimensionScoreService;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyInt;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * SC-P-18 能量流水查看 + SC-X-20 流水溯源一致性(对账)契约测试(energy.listLogs)。
+ *
+ * <p>三类流(纯 Mockito / 无 DB):</p>
+ * <ul>
+ *   <li><b>正常流(TC-P-88)</b>:分页默认 1/10、按维度筛选、createdAt 倒序;</li>
+ *   <li><b>异常流</b>:非法维度 code → 不附加维度过滤(观察行为钉住);page/size 非法 → 回退默认;</li>
+ *   <li><b>权限流</b>:无 memberId → 业务提示;无 familyId → 5001;/score-history 缺 memberId/memberType → 提示;
+ *       /family-score-history 无 familyId → 5001;</li>
+ *   <li><b>对账流(SC-X-20)</b>:grant 后 logs 返回同一 memberId/dimension/amount/balanceAfter/sourceId,
+ *       流水与余额变更一一对应(溯源一致)。</li>
+ * </ul>
+ */
+class EnergyLogsContractScoreHistoryTest extends EnergyContractTestBase {
+
+    private EnergyService service;
+    private EnergyDimensionMapper dimensionMapper;
+    private EnergyLogMapper logMapper;
+    private EnergyController controller;
+    private FiveDimensionScoreService scoreService;
+
+    @BeforeEach
+    void setUp() throws Exception {
+        service = new EnergyService();
+        dimensionMapper = mock(EnergyDimensionMapper.class);
+        logMapper = mock(EnergyLogMapper.class);
+        inject(service, "energyDimensionMapper", dimensionMapper);
+        inject(service, "energyLogMapper", logMapper);
+        inject(service, "energyBalanceMapper", mock(com.etotem.cfc.mapper.EnergyBalanceMapper.class));
+        inject(service, "energySourceConfigMapper", mock(com.etotem.cfc.mapper.EnergySourceConfigMapper.class));
+        inject(service, "energyBehaviorConfigMapper", mock(com.etotem.cfc.mapper.EnergyBehaviorConfigMapper.class));
+        inject(service, "wishMapper", mock(com.etotem.cfc.mapper.WishMapper.class));
+        inject(service, "familyMemberMapper", mock(com.etotem.cfc.mapper.FamilyMemberMapper.class));
+        inject(service, "notificationDispatchService", mock(com.etotem.cfc.service.NotificationDispatchService.class));
+
+        scoreService = mock(FiveDimensionScoreService.class);
+        controller = new EnergyController();
+        inject(controller, "energyService", service);
+        inject(controller, "fiveDimensionScoreService", scoreService);
+        inject(controller, "userMapper", mock(com.etotem.cfc.mapper.UserMapper.class));
+        inject(controller, "unlockGateService", mock(com.etotem.cfc.service.UnlockGateService.class));
+
+        initTable(EnergyLog.class);
+        initTable(EnergyDimension.class);
+    }
+
+    private void seedDims() {
+        when(dimensionMapper.selectList(any())).thenReturn(Arrays.asList(fiveDims()));
+    }
+
+    private void seedPage(EnergyLog... logs) {
+        when(logMapper.selectPage(any(Page.class), any())).thenAnswer(inv -> {
+            Page<EnergyLog> p = inv.getArgument(0);
+            p.setRecords(Arrays.asList(logs));
+            p.setTotal(logs.length);
+            return p;
+        });
+    }
+
+    // ==================== 正常流(TC-P-88) ====================
+
+    @Test
+    @DisplayName("SC-P-18 正常:分页默认 page=1 size=10,按维度筛选")
+    void 正常流_分页默认_按维度筛选() {
+        seedDims();
+        seedPage(energyLog(1L, 50L, 5L, 10, 10, "task", 100L));
+        Page<EnergyLog> p = service.getLogs(50L, "body", null, null);
+        assertEquals(1, p.getCurrent());
+        assertEquals(10, p.getSize());
+        assertEquals(1, p.getRecords().size());
+        assertEquals("task", p.getRecords().get(0).getSourceType());
+    }
+
+    @Test
+    @DisplayName("SC-P-18 正常:传入 page/size 生效")
+    void 正常流_pageSize生效() {
+        seedDims();
+        seedPage(energyLog(2L, 50L, 1L, 20, 20, "task", 200L));
+        Page<EnergyLog> p = service.getLogs(50L, null, 3, 20);
+        assertEquals(3, p.getCurrent());
+        assertEquals(20, p.getSize());
+    }
+
+    @Test
+    @DisplayName("SC-P-18 正常:指定维度过滤仅返回该维度流水")
+    void 正常流_维度过滤() {
+        seedDims();
+        // body id=5,仅 body 流水
+        when(logMapper.selectPage(any(Page.class), any())).thenAnswer(inv -> {
+            Page<EnergyLog> p = inv.getArgument(0);
+            List<EnergyLog> bodyLogs = Collections.singletonList(energyLog(3L, 50L, 5L, 10, 10, "task", 300L));
+            p.setRecords(bodyLogs);
+            p.setTotal(1);
+            return p;
+        });
+        Page<EnergyLog> p = service.getLogs(50L, "body", 1, 10);
+        assertEquals(1, p.getRecords().size());
+        assertEquals(5L, p.getRecords().get(0).getDimensionId());
+    }
+
+    // ==================== 异常流 ====================
+
+    @Test
+    @DisplayName("SC-P-18 异常:非法维度 code → 不附加过滤(观察行为钉住)")
+    void 异常流_非法维度不过滤() {
+        seedDims();
+        when(logMapper.selectPage(any(Page.class), any())).thenAnswer(inv -> {
+            Page<EnergyLog> p = inv.getArgument(0);
+            p.setRecords(Arrays.asList(
+                    energyLog(4L, 50L, 1L, 5, 5, "task", 1L),
+                    energyLog(5L, 50L, 5L, 7, 7, "task", 2L)));
+            p.setTotal(2);
+            return p;
+        });
+        // dimensionCode=不存在 → getDimByCode=null → 不 eq,返回全部(无 400,观察行为)
+        Page<EnergyLog> p = service.getLogs(50L, "nonexistent", 1, 10);
+        assertEquals(2, p.getRecords().size(), "非法维度按观察行为应返回全部而非 400");
+    }
+
+    @Test
+    @DisplayName("SC-P-18 异常:page/size 非法 → 回退默认")
+    void 异常流_pageSize回退() {
+        seedDims();
+        seedPage(energyLog(6L, 50L, 5L, 10, 10, "task", 4L));
+        Page<EnergyLog> p = service.getLogs(50L, null, 0, -5);
+        assertEquals(1, p.getCurrent());
+        assertEquals(10, p.getSize());
+    }
+
+    // ==================== 权限流 ====================
+
+    @Test
+    @DisplayName("SC-P-18 权限:logs 无 memberId → 业务提示")
+    void 权限流_logs无memberId() {
+        Map<String, Object> params = new HashMap<>();
+        params.put("dimensionCode", "body");
+        Result<Page<EnergyLog>> r = controller.getEnergyLogs(params, 1L, null);
+        assertEquals(500, r.getCode());
+        assertTrue(r.getMessage().contains("memberId不能为空"));
+    }
+
+    @Test
+    @DisplayName("SC-P-18 权限:logs 无 familyId → 5001")
+    void 权限流_logs无familyId() {
+        Map<String, Object> params = new HashMap<>();
+        params.put("memberId", 50L);
+        Result<Page<EnergyLog>> r = controller.getEnergyLogs(params, null, 50L);
+        assertEquals(5001, r.getCode());
+    }
+
+    @Test
+    @DisplayName("SC-P-18 权限:score-history 缺 memberId/memberType → 业务提示")
+    void 权限流_scoreHistory缺参() {
+        Map<String, Object> params = new HashMap<>();
+        params.put("dimensionCode", "body");
+        Result<List<FiveDimensionScore>> r = controller.getScoreHistory(params);
+        assertEquals(500, r.getCode());
+        assertTrue(r.getMessage().contains("memberId和memberType不能为空"));
+    }
+
+    @Test
+    @DisplayName("SC-P-18 权限:score-history 无 dimensionCode → 空列表(观察:不默认查询)")
+    void 权限流_scoreHistory无维度_空列表() {
+        Map<String, Object> params = new HashMap<>();
+        params.put("memberId", 50L);
+        params.put("memberType", "member");
+        Result<List<FiveDimensionScore>> r = controller.getScoreHistory(params);
+        assertEquals(200, r.getCode());
+        assertTrue(r.getData().isEmpty(), "未指定 dimensionCode 时观察行为为返回空列表");
+    }
+
+    @Test
+    @DisplayName("SC-P-18 权限:family-score-history 无 familyId → 5001")
+    void 权限流_familyScoreHistory无familyId() {
+        Result<Map<String, Integer>> r = controller.getFamilyScoreHistory(new HashMap<>(), null);
+        assertEquals(5001, r.getCode());
+    }
+
+    // ==================== 对账流(SC-X-20) ====================
+
+    @Test
+    @DisplayName("SC-X-20 对账:grant 后 logs 与余额变更一一对应(溯源一致)")
+    void 对账流_发放后流水可溯源() throws Exception {
+        seedDims();
+        // 日上限查询返回空(当日无流水)→ 通过
+        when(logMapper.selectList(any())).thenReturn(Collections.emptyList());
+        // balance 无既有记录 → 新建
+        com.etotem.cfc.mapper.EnergyBalanceMapper balanceMapper = mock(com.etotem.cfc.mapper.EnergyBalanceMapper.class);
+        when(balanceMapper.selectOne(any())).thenReturn(null);
+        inject(service, "energyBalanceMapper", balanceMapper);
+        // familyMember + notification
+        com.etotem.cfc.entity.FamilyMember member = new com.etotem.cfc.entity.FamilyMember();
+        member.setId(50L);
+        member.setUserId(12L);
+        com.etotem.cfc.mapper.FamilyMemberMapper familyMemberMapper = mock(com.etotem.cfc.mapper.FamilyMemberMapper.class);
+        when(familyMemberMapper.selectById(any())).thenReturn(member);
+        inject(service, "familyMemberMapper", familyMemberMapper);
+
+        com.etotem.cfc.entity.EnergyLog granted = service.grantEnergy(50L, 300L, 12L, "body");
+        assertNotNull(granted);
+        assertEquals(12, granted.getAmount());
+        assertEquals(300L, granted.getSourceId());
+        assertEquals(5L, granted.getDimensionId());
+
+        // 对账:按 memberId+dimension 过滤应命中该笔流水(sourceId=300L, amount=12, balanceAfter 一致)
+        EnergyLog persisted = energyLog(9L, 50L, 5L, 12, 12, "task", 300L);
+        when(logMapper.selectPage(any(Page.class), any())).thenAnswer(inv -> {
+            Page<EnergyLog> p = inv.getArgument(0);
+            p.setRecords(Collections.singletonList(persisted));
+            p.setTotal(1);
+            return p;
+        });
+        Page<EnergyLog> logs = service.getLogs(50L, "body", 1, 10);
+        assertEquals(1, logs.getRecords().size());
+        EnergyLog l = logs.getRecords().get(0);
+        assertEquals(granted.getMemberId(), l.getMemberId());
+        assertEquals(granted.getDimensionId(), l.getDimensionId(), "维度溯源一致");
+        assertEquals(granted.getAmount(), l.getAmount(), "数量溯源一致");
+        assertEquals(granted.getSourceId(), l.getSourceId(), "来源 ID 溯源一致");
+        assertEquals("task", l.getSourceType());
+    }
+}

+ 193 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/EnergyOverviewContractTest.java

@@ -0,0 +1,193 @@
+package com.etotem.cfc.unit;
+
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.controller.EnergyController;
+import com.etotem.cfc.entity.EnergyBalance;
+import com.etotem.cfc.entity.EnergyDimension;
+import com.etotem.cfc.mapper.EnergyBalanceMapper;
+import com.etotem.cfc.mapper.EnergyDimensionMapper;
+import com.etotem.cfc.service.EnergyService;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+/**
+ * SC-P-17 查看五维能量 / 健康指数 契约测试(energy.viewOverview)。
+ *
+ * <p>三类流(纯 Mockito,无 Spring / 无 DB):</p>
+ * <ul>
+ *   <li><b>正常流(TC-P-87)</b>:五维全量返回,维度含 code/name/icon/element/energy/healthIndex,
+ *       totalEnergy=各维余额之和,totalHealthIndex=0(算法待定契约);</li>
+ *   <li><b>异常流</b>:空维度 → 空列表 + 0;无余额记录 → 各维 energy=0;</li>
+ *   <li><b>权限流</b>:无 familyId(未入家庭)→ code=5001;无 memberId → 业务 400 提示;
+ *       请求体为空 → 业务提示(JwtInterceptor 侧 /api/energy/ 强制登录 401,见 EnergyIsolationContractTest)。</li>
+ * </ul>
+ */
+class EnergyOverviewContractTest extends EnergyContractTestBase {
+
+    private EnergyService service;
+    private EnergyDimensionMapper dimensionMapper;
+    private EnergyBalanceMapper balanceMapper;
+    private EnergyController controller;
+
+    @BeforeEach
+    void setUp() throws Exception {
+        service = new EnergyService();
+        dimensionMapper = mock(EnergyDimensionMapper.class);
+        balanceMapper = mock(EnergyBalanceMapper.class);
+        inject(service, "energyDimensionMapper", dimensionMapper);
+        inject(service, "energyBalanceMapper", balanceMapper);
+        // grantEnergy 相关字段在本类不触达,但为防 NPE 一并注入空桩
+        inject(service, "energySourceConfigMapper", mock(com.etotem.cfc.mapper.EnergySourceConfigMapper.class));
+        inject(service, "energyBehaviorConfigMapper", mock(com.etotem.cfc.mapper.EnergyBehaviorConfigMapper.class));
+        inject(service, "energyLogMapper", mock(com.etotem.cfc.mapper.EnergyLogMapper.class));
+        inject(service, "wishMapper", mock(com.etotem.cfc.mapper.WishMapper.class));
+        inject(service, "familyMemberMapper", mock(com.etotem.cfc.mapper.FamilyMemberMapper.class));
+        inject(service, "notificationDispatchService", mock(com.etotem.cfc.service.NotificationDispatchService.class));
+
+        controller = new EnergyController();
+        inject(controller, "energyService", service);
+        inject(controller, "fiveDimensionScoreService", mock(com.etotem.cfc.service.FiveDimensionScoreService.class));
+        inject(controller, "userMapper", mock(com.etotem.cfc.mapper.UserMapper.class));
+        inject(controller, "unlockGateService", mock(com.etotem.cfc.service.UnlockGateService.class));
+
+        initTable(EnergyBalance.class);
+        initTable(EnergyDimension.class);
+    }
+
+    private void seedDims(EnergyDimension... dims) {
+        when(dimensionMapper.selectList(any())).thenReturn(Arrays.asList(dims));
+    }
+
+    /** balance 查询:按 memberId+dimensionId 返回(null=无记录) */
+    private void seedBalance(Long memberId, Long dimId, Integer balance) {
+        when(balanceMapper.selectOne(any())).thenAnswer(inv -> {
+            if (balance == null) return null;
+            EnergyBalance b = new EnergyBalance();
+            b.setMemberId(memberId);
+            b.setDimensionId(dimId);
+            b.setBalance(balance);
+            b.setTotalEarned(balance);
+            b.setTotalSpent(0);
+            return b;
+        });
+    }
+
+    // ==================== 正常流(TC-P-87) ====================
+
+    @Test
+    @DisplayName("SC-P-17 正常:五维全量返回,totalEnergy=余额和")
+    void 正常流_五维全量返回_余额求和() {
+        seedDims(fiveDims());
+        // 仅 body(dimId=5)有余额 30,其余无记录 → 0
+        when(balanceMapper.selectOne(any())).thenAnswer(inv -> {
+            EnergyBalance b = new EnergyBalance();
+            b.setBalance(30);
+            b.setTotalEarned(30);
+            return b;
+        });
+
+        Map<String, Object> data = service.getOverview(50L);
+
+        @SuppressWarnings("unchecked")
+        List<Map<String, Object>> dims = (List<Map<String, Object>>) data.get("dimensions");
+        assertNotNull(dims);
+        assertEquals(5, dims.size(), "应返回 5 个启用维度");
+        assertEquals(150, data.get("totalEnergy"), "五维各有 30,总和应为 150");
+        assertEquals(0, data.get("totalHealthIndex"), "healthIndex 算法待定,契约为 0");
+        for (Map<String, Object> d : dims) {
+            assertNotNull(d.get("code"));
+            assertNotNull(d.get("name"));
+            assertNotNull(d.get("icon"));
+            assertNotNull(d.get("element"));
+            assertEquals(30, d.get("energy"));
+            assertEquals(0, d.get("healthIndex"));
+        }
+        // 顺序与 sortOrder 一致(wisdom/wealth/action/mind/body)
+        assertEquals("wisdom", dims.get(0).get("code"));
+        assertEquals("body", dims.get(4).get("code"));
+    }
+
+    @Test
+    @DisplayName("SC-P-17 正常:无余额记录 → 各维 energy=0,totalEnergy=0")
+    void 正常流_无余额记录_各维为0() {
+        seedDims(fiveDims());
+        when(balanceMapper.selectOne(any())).thenReturn(null);
+
+        Map<String, Object> data = service.getOverview(50L);
+
+        assertEquals(0, data.get("totalEnergy"));
+        @SuppressWarnings("unchecked")
+        List<Map<String, Object>> dims = (List<Map<String, Object>>) data.get("dimensions");
+        for (Map<String, Object> d : dims) assertEquals(0, d.get("energy"));
+    }
+
+    // ==================== 异常流 ====================
+
+    @Test
+    @DisplayName("SC-P-17 异常:无维度配置 → 空列表 + totalEnergy 0")
+    void 异常流_无维度配置_空列表() {
+        when(dimensionMapper.selectList(any())).thenReturn(Collections.emptyList());
+
+        Map<String, Object> data = service.getOverview(50L);
+
+        assertEquals(0, data.get("totalEnergy"));
+        @SuppressWarnings("unchecked")
+        List<Map<String, Object>> dims = (List<Map<String, Object>>) data.get("dimensions");
+        assertEquals(0, dims.size());
+    }
+
+    // ==================== 权限流(controller 层) ====================
+
+    @Test
+    @DisplayName("SC-P-17 权限:请求体为空 → 业务提示")
+    void 权限流_请求体为空_业务提示() {
+        Result<Map<String, Object>> r = controller.getEnergyOverview(null, 1L, 50L);
+        assertEquals(500, r.getCode());
+        assertTrue(r.getMessage().contains("请求体不能为空"));
+    }
+
+    @Test
+    @DisplayName("SC-P-17 权限:memberId 为空且无当前成员 → 业务提示")
+    void 权限流_memberId为空_业务提示() {
+        Result<Map<String, Object>> r = controller.getEnergyOverview(new HashMap<>(), 1L, null);
+        assertEquals(500, r.getCode());
+        assertTrue(r.getMessage().contains("memberId不能为空"));
+    }
+
+    @Test
+    @DisplayName("SC-P-17 权限:未入家庭(familyId 空)→ code=5001")
+    void 权限流_未入家庭_5001() {
+        Map<String, Object> params = new HashMap<>();
+        params.put("memberId", 50L);
+        Result<Map<String, Object>> r = controller.getEnergyOverview(params, null, null);
+        assertEquals(5001, r.getCode());
+        assertTrue(r.getMessage().contains("家庭"));
+    }
+
+    @Test
+    @DisplayName("SC-P-17 权限:有家庭+成员 → code=200 返回五维")
+    void 权限流_有家庭有成员_200() {
+        seedDims(fiveDims());
+        when(balanceMapper.selectOne(any())).thenReturn(null);
+        Map<String, Object> params = new HashMap<>();
+        params.put("memberId", 50L);
+        Result<Map<String, Object>> r = controller.getEnergyOverview(params, 1L, 50L);
+        assertEquals(200, r.getCode());
+        assertNotNull(r.getData());
+        assertEquals(5, ((List<?>) r.getData().get("dimensions")).size());
+    }
+}

+ 310 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/FiveDimensionSelfCheckContractTest.java

@@ -0,0 +1,310 @@
+package com.etotem.cfc.unit;
+
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.controller.family.FiveDimensionSelfCheckController;
+import com.etotem.cfc.dto.SelfCheckQuestionVO;
+import com.etotem.cfc.dto.SelfCheckResultVO;
+import com.etotem.cfc.dto.SubmitSelfCheckDTO;
+import com.etotem.cfc.entity.FiveDimensionSelfCheck;
+import com.etotem.cfc.entity.SelfCheckIgnore;
+import com.etotem.cfc.mapper.FamilyMemberMapper;
+import com.etotem.cfc.mapper.FiveDimensionSelfCheckMapper;
+import com.etotem.cfc.mapper.SelfCheckIgnoreMapper;
+import com.etotem.cfc.service.FiveDimensionSelfCheckService;
+import com.etotem.cfc.service.OnboardingService;
+import com.etotem.cfc.service.SelfCheckAnalysisService;
+import com.etotem.cfc.service.SelfCheckTrendService;
+import com.etotem.cfc.service.WuxingSourcingService;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.Date;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyInt;
+import static org.mockito.ArgumentMatchers.anyLong;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * SC-T-32 五维自评录入与变化 契约测试(energy.selfCheck)。
+ *
+ * <p>三类流(纯 Mockito / 无 DB):</p>
+ * <ul>
+ *   <li><b>正常流</b>:questions 返回固定 15 题(Q6 含 E 跳过项);submit 15 题全 A → 五维各 9 分、
+ *       total=45,写记录并触发 AI 建议 + 新手引导;latest/history/status/ignore/trend-analysis 正常;</li>
+ *   <li><b>异常流</b>:答案空 / <10 题 / 某维 0 答 → 400 提示;</li>
+ *   <li><b>权限流</b>:controller userId 为空 → 业务提示(questions/submit/latest/history/status)。</li>
+ * </ul>
+ */
+class FiveDimensionSelfCheckContractTest extends EnergyContractTestBase {
+
+    private FiveDimensionSelfCheckService service;
+    private FiveDimensionSelfCheckMapper selfCheckMapper;
+    private FamilyMemberMapper familyMemberMapper;
+    private WuxingSourcingService wuxingSourcingService;
+    private OnboardingService onboardingService;
+    private SelfCheckIgnoreMapper ignoreMapper;
+    private SelfCheckAnalysisService analysisService;
+    private SelfCheckTrendService trendService;
+    private FiveDimensionSelfCheckController controller;
+
+    private static final Long USER_ID = 12L;
+    private static final Long FAMILY_MEMBER_ID = 50L;
+
+    @BeforeEach
+    void setUp() throws Exception {
+        service = new FiveDimensionSelfCheckService();
+        selfCheckMapper = mock(FiveDimensionSelfCheckMapper.class);
+        familyMemberMapper = mock(FamilyMemberMapper.class);
+        wuxingSourcingService = mock(WuxingSourcingService.class);
+        onboardingService = mock(OnboardingService.class);
+        ignoreMapper = mock(SelfCheckIgnoreMapper.class);
+        analysisService = mock(SelfCheckAnalysisService.class);
+        trendService = mock(SelfCheckTrendService.class);
+
+        inject(service, "selfCheckMapper", selfCheckMapper);
+        inject(service, "familyMemberMapper", familyMemberMapper);
+        inject(service, "wuxingSourcingService", wuxingSourcingService);
+        inject(service, "onboardingService", onboardingService);
+        inject(service, "ignoreMapper", ignoreMapper);
+        inject(service, "selfCheckAnalysisService", analysisService);
+        inject(service, "selfCheckTrendService", trendService);
+
+        when(wuxingSourcingService.levelOf(anyInt())).thenReturn("healthy");
+        when(wuxingSourcingService.levelName(anyString())).thenReturn("健康");
+        when(selfCheckMapper.insert(any(FiveDimensionSelfCheck.class))).thenAnswer(inv -> {
+            FiveDimensionSelfCheck c = inv.getArgument(0);
+            c.setId(555L);
+            return 1;
+        });
+        Map<String, Object> advice = new HashMap<>();
+        advice.put("adviceJson", "[]");
+        when(analysisService.generateAdvice(anyLong(), any(Map.class), any(List.class))).thenReturn(advice);
+
+        controller = new FiveDimensionSelfCheckController();
+        inject(controller, "selfCheckService", service);
+        inject(controller, "unlockGateService", mock(com.etotem.cfc.service.UnlockGateService.class));
+        inject(controller, "userMapper", mock(com.etotem.cfc.mapper.UserMapper.class));
+        inject(controller, "healthPlanService", mock(com.etotem.cfc.service.HealthPlanService.class));
+        inject(controller, "aiGateway", mock(com.etotem.cfc.service.AiGateway.class));
+
+        initTable(FiveDimensionSelfCheck.class);
+        initTable(SelfCheckIgnore.class);
+    }
+
+    private SubmitSelfCheckDTO dtoAllA(int count) {
+        SubmitSelfCheckDTO d = new SubmitSelfCheckDTO();
+        d.setFamilyMemberId(FAMILY_MEMBER_ID);
+        List<SubmitSelfCheckDTO.AnswerItem> answers = new ArrayList<>();
+        for (int i = 1; i <= count; i++) {
+            SubmitSelfCheckDTO.AnswerItem item = new SubmitSelfCheckDTO.AnswerItem();
+            item.setQuestionId(i);
+            item.setAnswer("A");
+            answers.add(item);
+        }
+        d.setAnswers(answers);
+        return d;
+    }
+
+    // ==================== 正常流 ====================
+
+    @Test
+    @DisplayName("SC-T-32 正常:questions 返回固定 15 题,Q6 含 E 跳过项")
+    void 正常流_题库15题() {
+        List<SelfCheckQuestionVO> qs = service.getQuestions();
+        assertEquals(15, qs.size());
+        SelfCheckQuestionVO q6 = qs.get(5);
+        assertEquals("wisdom", q6.getDimension());
+        assertEquals(5, q6.getOptions().size(), "Q6 应含 E 跳过项");
+        assertEquals("E", q6.getOptions().get(4).getValue());
+    }
+
+    @Test
+    @DisplayName("SC-T-32 正常:submit 15 题全 A → 五维各 9 分,total=45,写记录+触发AI建议+新手引导")
+    void 正常流_提交自评() {
+        SelfCheckResultVO vo = service.submitSelfCheck(dtoAllA(15), USER_ID);
+
+        assertNotNull(vo);
+        assertEquals(555L, vo.getId());
+        assertEquals(45, vo.getTotalScore());
+        assertEquals(5, vo.getDimensions().size());
+        for (SelfCheckResultVO.DimensionScoreVO d : vo.getDimensions()) {
+            assertEquals(9, d.getScore(), d.getDimension() + " 应为 9 分");
+            assertEquals("healthy", d.getLevel());
+        }
+        verify(selfCheckMapper).insert(any(FiveDimensionSelfCheck.class));
+        verify(analysisService).generateAdvice(anyLong(), any(Map.class), any(List.class));
+        verify(onboardingService).completeTask(USER_ID, "COMPLETE_SELF_CHECK");
+    }
+
+    @Test
+    @DisplayName("SC-T-32 正常:getLatest 返回最近一次结果")
+    void 正常流_getLatest() {
+        FiveDimensionSelfCheck rec = new FiveDimensionSelfCheck();
+        rec.setId(1L);
+        rec.setUserId(USER_ID);
+        rec.setFamilyMemberId(FAMILY_MEMBER_ID);
+        rec.setTotalScore(45);
+        rec.setScoresJson("{\"body\":9,\"mind\":9,\"wisdom\":9,\"action\":9,\"wealth\":9}");
+        rec.setAdviceJson("[]");
+        rec.setCreatedAt(new Date());
+        when(selfCheckMapper.selectOne(any())).thenReturn(rec);
+
+        SelfCheckResultVO vo = service.getLatest(USER_ID);
+        assertNotNull(vo);
+        assertEquals(45, vo.getTotalScore());
+        assertEquals(5, vo.getDimensions().size());
+    }
+
+    @Test
+    @DisplayName("SC-T-32 正常:getHistory limit 超界回退 20")
+    void 正常流_getHistory回退() {
+        when(selfCheckMapper.selectList(any())).thenReturn(Collections.emptyList());
+        List<SelfCheckResultVO> history = service.getHistory(USER_ID, 999);
+        assertNotNull(history);
+        assertEquals(0, history.size());
+    }
+
+    @Test
+    @DisplayName("SC-T-32 正常:getStatus 从未自检 → hasCheck=false, canCheck=true")
+    void 正常流_状态未检() {
+        when(selfCheckMapper.selectOne(any())).thenReturn(null);
+        when(ignoreMapper.selectOne(any())).thenReturn(null);
+        Map<String, Object> status = service.getStatus(USER_ID);
+        assertEquals(false, status.get("hasCheck"));
+        assertEquals(true, status.get("canCheck"));
+        assertEquals(0, status.get("daysLeft"));
+    }
+
+    @Test
+    @DisplayName("SC-T-32 正常:getStatus 15 天内已检 → canCheck=false")
+    void 正常流_状态已检() {
+        FiveDimensionSelfCheck rec = new FiveDimensionSelfCheck();
+        rec.setId(1L);
+        rec.setCreatedAt(new Date(System.currentTimeMillis() - 3L * 24 * 3600 * 1000));
+        rec.setQuestionIdsJson("[]");
+        when(selfCheckMapper.selectOne(any())).thenReturn(rec);
+        when(ignoreMapper.selectOne(any())).thenReturn(null);
+        Map<String, Object> status = service.getStatus(USER_ID);
+        assertEquals(true, status.get("hasCheck"));
+        assertEquals(false, status.get("canCheck"), "3 天内应不可再检");
+        assertTrue(((Number) status.get("daysLeft")).intValue() > 0);
+    }
+
+    @Test
+    @DisplayName("SC-T-32 正常:ignore 幂等(15 天内重复忽略不插入)")
+    void 正常流_忽略幂等() {
+        SelfCheckIgnore last = new SelfCheckIgnore();
+        last.setUserId(USER_ID);
+        last.setCheckId(1L);
+        last.setCreatedAt(new Date(System.currentTimeMillis() - 1L * 24 * 3600 * 1000));
+        when(ignoreMapper.selectOne(any())).thenReturn(last);
+
+        Date ignoredAt = service.ignoreSelfCheck(USER_ID, 1L);
+        assertNotNull(ignoredAt);
+        verify(ignoreMapper, never()).insert(any(SelfCheckIgnore.class));
+    }
+
+    @Test
+    @DisplayName("SC-T-32 正常:trend-analysis 委托趋势服务")
+    void 正常流_趋势分析() {
+        Map<String, Object> trend = new HashMap<>();
+        trend.put("trends", Collections.emptyList());
+        when(trendService.getTrendData(USER_ID)).thenReturn(trend);
+        Map<String, Object> result = service.getTrendAnalysis(USER_ID);
+        assertNotNull(result);
+        assertTrue(result.containsKey("trends"));
+    }
+
+    // ==================== 异常流 ====================
+
+    @Test
+    @DisplayName("SC-T-32 异常:答案为空 → 400 提示")
+    void 异常流_答案为空() {
+        SubmitSelfCheckDTO d = new SubmitSelfCheckDTO();
+        d.setFamilyMemberId(FAMILY_MEMBER_ID);
+        d.setAnswers(Collections.emptyList());
+        IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+                () -> service.submitSelfCheck(d, USER_ID));
+        assertTrue(e.getMessage().contains("答案不能为空"));
+        verify(selfCheckMapper, never()).insert(any());
+    }
+
+    @Test
+    @DisplayName("SC-T-32 异常:<10 题 → 400 提示")
+    void 异常流_少于10题() {
+        IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+                () -> service.submitSelfCheck(dtoAllA(9), USER_ID));
+        assertTrue(e.getMessage().contains("至少10道题目"));
+        verify(selfCheckMapper, never()).insert(any());
+    }
+
+    @Test
+    @DisplayName("SC-T-32 异常:某维度 0 答(只答 4 维)→ 400 提示")
+    void 异常流_某维0答() {
+        // 答 body(1-3)+wisdom(4-6)+wealth(7-8)+action(10-11)=10 题,缺 mind(13-15)
+        SubmitSelfCheckDTO d = new SubmitSelfCheckDTO();
+        d.setFamilyMemberId(FAMILY_MEMBER_ID);
+        List<SubmitSelfCheckDTO.AnswerItem> answers = new ArrayList<>();
+        for (int id : new int[]{1, 2, 3, 4, 5, 6, 7, 8, 10, 11}) {
+            SubmitSelfCheckDTO.AnswerItem item = new SubmitSelfCheckDTO.AnswerItem();
+            item.setQuestionId(id);
+            item.setAnswer("A");
+            answers.add(item);
+        }
+        d.setAnswers(answers);
+        IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+                () -> service.submitSelfCheck(d, USER_ID));
+        assertTrue(e.getMessage().contains("至少回答1题"));
+        verify(selfCheckMapper, never()).insert(any());
+    }
+
+    // ==================== 权限流(controller 层) ====================
+
+    @Test
+    @DisplayName("SC-T-32 权限:controller userId 空 → questions 业务提示")
+    void 权限流_questions未登录() {
+        Result<List<SelfCheckQuestionVO>> r = controller.getQuestions(null, null);
+        assertEquals(500, r.getCode());
+        assertTrue(r.getMessage().contains("请先登录"));
+    }
+
+    @Test
+    @DisplayName("SC-T-32 权限:controller userId 空 → submit 业务提示")
+    void 权限流_submit未登录() {
+        Result<SelfCheckResultVO> r = controller.submit(dtoAllA(15), null);
+        assertEquals(500, r.getCode());
+        assertTrue(r.getMessage().contains("请先登录"));
+    }
+
+    @Test
+    @DisplayName("SC-T-32 权限:controller userId 空 → status 业务提示")
+    void 权限流_status未登录() {
+        Result<Map<String, Object>> r = controller.getStatus(null);
+        assertEquals(500, r.getCode());
+        assertTrue(r.getMessage().contains("请先登录"));
+    }
+
+    @Test
+    @DisplayName("SC-T-32 权限:controller 正常 questions → 200 返回 15 题")
+    void 权限流_questions正常() {
+        Result<List<SelfCheckQuestionVO>> r = controller.getQuestions(USER_ID, new HashMap<>());
+        assertEquals(200, r.getCode());
+        assertEquals(15, r.getData().size());
+    }
+}

+ 262 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/ManualDimensionScoreContractTest.java

@@ -0,0 +1,262 @@
+package com.etotem.cfc.unit;
+
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.controller.family.ManualDimensionScoreController;
+import com.etotem.cfc.dto.ManualScoreSubmitDTO;
+import com.etotem.cfc.dto.ManualScoreVO;
+import com.etotem.cfc.entity.FamilyMember;
+import com.etotem.cfc.entity.FiveDimensionScore;
+import com.etotem.cfc.entity.FiveDimensionSelfCheck;
+import com.etotem.cfc.mapper.FamilyMemberMapper;
+import com.etotem.cfc.mapper.FiveDimensionScoreMapper;
+import com.etotem.cfc.mapper.FiveDimensionSelfCheckMapper;
+import com.etotem.cfc.service.impl.ManualDimensionScoreServiceImpl;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.util.Date;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * SC-T-31 手动维度打分覆盖/调整 契约测试(energy.manualScore)。
+ *
+ * <p>三类流(纯 Mockito / 无 DB):</p>
+ * <ul>
+ *   <li><b>正常流</b>:规划师提交五维 0-100 分 → 每维一条 five_dimension_scores(source_type=manual)
+ *       + 一条 five_dimension_self_checks 复用记录(questionIdsJson="[]"),返回 VO 含总分;</li>
+ *   <li><b>异常流</b>:memberId 空 / userId 空 / scores 空 / 成员不存在 / 缺维度 / 分数越界 / 全 0 → 400 提示;</li>
+ *   <li><b>权限流</b>:controller 未登录(userId=null) → 业务提示;latest 缺 memberId 时按 userId 解析本人成员。</li>
+ * </ul>
+ */
+class ManualDimensionScoreContractTest extends EnergyContractTestBase {
+
+    private ManualDimensionScoreServiceImpl service;
+    private FiveDimensionScoreMapper scoreMapper;
+    private FiveDimensionSelfCheckMapper selfCheckMapper;
+    private FamilyMemberMapper familyMemberMapper;
+    private ManualDimensionScoreController controller;
+
+    private static final Long MEMBER_ID = 50L;
+    private static final Long USER_ID = 12L;
+
+    @BeforeEach
+    void setUp() throws Exception {
+        service = new ManualDimensionScoreServiceImpl();
+        scoreMapper = mock(FiveDimensionScoreMapper.class);
+        selfCheckMapper = mock(FiveDimensionSelfCheckMapper.class);
+        familyMemberMapper = mock(FamilyMemberMapper.class);
+        inject(service, "fiveDimensionScoreMapper", scoreMapper);
+        inject(service, "selfCheckMapper", selfCheckMapper);
+        inject(service, "familyMemberMapper", familyMemberMapper);
+
+        FamilyMember member = new FamilyMember();
+        member.setId(MEMBER_ID);
+        member.setFamilyId(1L);
+        member.setUserId(USER_ID);
+        member.setNickname("小明");
+        when(familyMemberMapper.selectById(any())).thenReturn(member);
+
+        when(scoreMapper.insert(any(FiveDimensionScore.class))).thenReturn(1);
+        when(selfCheckMapper.insert(any(FiveDimensionSelfCheck.class))).thenAnswer(inv -> {
+            FiveDimensionSelfCheck c = inv.getArgument(0);
+            c.setId(777L);
+            return 1;
+        });
+
+        controller = new ManualDimensionScoreController();
+        inject(controller, "manualScoreService", service);
+
+        initTable(FamilyMember.class);
+    }
+
+    private ManualScoreSubmitDTO dto(Map<String, Integer> scores) {
+        ManualScoreSubmitDTO d = new ManualScoreSubmitDTO();
+        d.setMemberId(MEMBER_ID);
+        d.setScores(scores);
+        return d;
+    }
+
+    private Map<String, Integer> fullScores(int body, int mind, int wisdom, int action, int wealth) {
+        Map<String, Integer> m = new LinkedHashMap<>();
+        m.put("body", body);
+        m.put("mind", mind);
+        m.put("wisdom", wisdom);
+        m.put("action", action);
+        m.put("wealth", wealth);
+        return m;
+    }
+
+    // ==================== 正常流 ====================
+
+    @Test
+    @DisplayName("SC-T-31 正常:提交五维分 → 写 5 条分数 + 1 条复用自检记录")
+    void 正常流_提交五维分() {
+        ManualScoreVO vo = service.submit(dto(fullScores(80, 60, 70, 50, 90)), USER_ID);
+
+        assertNotNull(vo);
+        assertEquals(777L, vo.getId());
+        assertEquals(MEMBER_ID, vo.getMemberId());
+        assertEquals("小明", vo.getMemberName());
+        assertEquals(350, vo.getTotalScore(), "总分=80+60+70+50+90");
+        assertEquals(5, vo.getScores().size());
+        assertEquals(80, vo.getScores().get("body"));
+        verify(scoreMapper, times(5)).insert(any(FiveDimensionScore.class));
+        verify(selfCheckMapper, times(1)).insert(any(FiveDimensionSelfCheck.class));
+    }
+
+    @Test
+    @DisplayName("SC-T-31 正常:记录 source_type=manual 且复用记录 questionIdsJson=[]")
+    void 正常流_记录标记manual() {
+        service.submit(dto(fullScores(10, 0, 0, 0, 0)), USER_ID);
+
+        org.mockito.ArgumentCaptor<FiveDimensionScore> cap =
+                org.mockito.ArgumentCaptor.forClass(FiveDimensionScore.class);
+        verify(scoreMapper, times(5)).insert(cap.capture());
+        for (FiveDimensionScore s : cap.getAllValues()) {
+            assertEquals("manual", s.getSourceType());
+            assertEquals("member", s.getMemberType());
+            assertEquals(1L, s.getFamilyId());
+        }
+        org.mockito.ArgumentCaptor<FiveDimensionSelfCheck> ccap =
+                org.mockito.ArgumentCaptor.forClass(FiveDimensionSelfCheck.class);
+        verify(selfCheckMapper).insert(ccap.capture());
+        assertEquals("[]", ccap.getValue().getQuestionIdsJson(), "手动填分标识");
+        assertEquals("[]", ccap.getValue().getAnswersJson());
+    }
+
+    // ==================== 异常流 ====================
+
+    @Test
+    @DisplayName("SC-T-31 异常:memberId 为空 → 400 提示")
+    void 异常流_memberId为空() {
+        ManualScoreSubmitDTO d = new ManualScoreSubmitDTO();
+        d.setScores(fullScores(10, 10, 10, 10, 10));
+        IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+                () -> service.submit(d, USER_ID));
+        assertTrue(e.getMessage().contains("memberId不能为空"));
+        verify(scoreMapper, never()).insert(any());
+    }
+
+    @Test
+    @DisplayName("SC-T-31 异常:未登录(userId 空) → 提示")
+    void 异常流_userId为空() {
+        IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+                () -> service.submit(dto(fullScores(10, 10, 10, 10, 10)), null));
+        assertTrue(e.getMessage().contains("请先登录"));
+    }
+
+    @Test
+    @DisplayName("SC-T-31 异常:scores 为空 → 400 提示")
+    void 异常流_scores为空() {
+        IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+                () -> service.submit(dto(new LinkedHashMap<>()), USER_ID));
+        assertTrue(e.getMessage().contains("scores不能为空"));
+    }
+
+    @Test
+    @DisplayName("SC-T-31 异常:成员不存在 → 400 提示")
+    void 异常流_成员不存在() {
+        when(familyMemberMapper.selectById(any())).thenReturn(null);
+        IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+                () -> service.submit(dto(fullScores(10, 10, 10, 10, 10)), USER_ID));
+        assertTrue(e.getMessage().contains("家庭成员不存在"));
+    }
+
+    @Test
+    @DisplayName("SC-T-31 异常:缺维度 → 400 提示")
+    void 异常流_缺维度() {
+        Map<String, Integer> scores = fullScores(10, 10, 10, 10, 10);
+        scores.remove("mind");
+        IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+                () -> service.submit(dto(scores), USER_ID));
+        assertTrue(e.getMessage().contains("维度[mind]分数不能为空"));
+        verify(scoreMapper, never()).insert(any());
+    }
+
+    @Test
+    @DisplayName("SC-T-31 异常:分数越界(>100 或 <0) → 400 提示")
+    void 异常流_分数越界() {
+        IllegalArgumentException e1 = assertThrows(IllegalArgumentException.class,
+                () -> service.submit(dto(fullScores(101, 10, 10, 10, 10)), USER_ID));
+        assertTrue(e1.getMessage().contains("必须在0-100之间"));
+
+        IllegalArgumentException e2 = assertThrows(IllegalArgumentException.class,
+                () -> service.submit(dto(fullScores(-1, 10, 10, 10, 10)), USER_ID));
+        assertTrue(e2.getMessage().contains("必须在0-100之间"));
+    }
+
+    @Test
+    @DisplayName("SC-T-31 异常:全 0 分 → 至少一维>0")
+    void 异常流_全零() {
+        IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+                () -> service.submit(dto(fullScores(0, 0, 0, 0, 0)), USER_ID));
+        assertTrue(e.getMessage().contains("至少一个维度分数大于0"));
+    }
+
+    // ==================== 权限流(controller 层) ====================
+
+    @Test
+    @DisplayName("SC-T-31 权限:controller 未登录 → Result.error 提示")
+    void 权限流_controller未登录() {
+        Result<ManualScoreVO> r = controller.submit(dto(fullScores(10, 10, 10, 10, 10)), null);
+        assertEquals(500, r.getCode());
+        assertTrue(r.getMessage().contains("请先登录"));
+    }
+
+    @Test
+    @DisplayName("SC-T-31 权限:controller 正常提交 → 200")
+    void 权限流_controller正常() {
+        Result<ManualScoreVO> r = controller.submit(dto(fullScores(80, 60, 70, 50, 90)), USER_ID);
+        assertEquals(200, r.getCode());
+        assertNotNull(r.getData());
+    }
+
+    @Test
+    @DisplayName("SC-T-31 权限:latest 缺 memberId → 按 userId 解析本人成员")
+    void 权限流_latest按userId解析() {
+        FamilyMember own = new FamilyMember();
+        own.setId(MEMBER_ID);
+        own.setFamilyId(1L);
+        when(familyMemberMapper.selectOne(any())).thenReturn(own);
+        FiveDimensionSelfCheck check = new FiveDimensionSelfCheck();
+        check.setId(9L);
+        check.setFamilyMemberId(MEMBER_ID);
+        check.setScoresJson("{\"body\":80,\"mind\":60,\"wisdom\":70,\"action\":50,\"wealth\":90}");
+        check.setTotalScore(350);
+        check.setCreatedAt(new Date());
+        when(selfCheckMapper.selectOne(any())).thenReturn(check);
+
+        Result<ManualScoreVO> r = controller.latest(new HashMap<>(), USER_ID);
+        assertEquals(200, r.getCode());
+        assertNotNull(r.getData());
+        assertEquals(350, r.getData().getTotalScore());
+    }
+
+    @Test
+    @DisplayName("SC-T-31 权限:latest 无记录 → 返回 null(不报错)")
+    void 权限流_latest无记录() {
+        FamilyMember own = new FamilyMember();
+        own.setId(MEMBER_ID);
+        own.setFamilyId(1L);
+        when(familyMemberMapper.selectOne(any())).thenReturn(own);
+        when(selfCheckMapper.selectOne(any())).thenReturn(null);
+        Result<ManualScoreVO> r = controller.latest(new HashMap<>(), USER_ID);
+        assertEquals(200, r.getCode());
+        assertNull(r.getData());
+    }
+}

+ 95 - 0
docs/tdd/test/automation-run-o7-five-dim-energy-2026-11-07.md

@@ -0,0 +1,95 @@
+# O-7 契约补建 · 五维能量批次 三类流执行证据(2026-11-07)
+
+| 项 | 内容 |
+|----|------|
+| 归属 | 契约补建计划 P0「五维能量」(O-7 授权,主理人 2026-11-06 23:59 确认生效) |
+| 批次 | 12 SC 开工包 + SC-A-25/SC-A-26(维度配置治理)(见 `docs/tdd/orchestration/dimension-energy-kickoff-20261107.md`) |
+| 契约核对 | 文档核对 + 端点比对(防假 RED):**12/12 端点已实现,0 缺失**(kickoff 表核验,O-7 复核一致) |
+| 执行环境 | 隔离 worktree `/tmp/opencode/o7-five-dim-evidence` @ `feature/o7-five-dim-evidence`(基于 `origin/cfclub` @ `8ba3ac14c`,`git merge-base --is-ancestor 8ba3ac14c origin/cfclub` 核验通过) |
+| 权威基线 | `8ba3ac14c` 为 `origin/cfclub` 祖先(git 真理证据) |
+| 编译 | `mvn -q test-compile -DskipTests=false` → **BUILD SUCCESS**(EXIT=0) |
+| 结论 | **88 契约 JUnit + 14 API e2e 全绿**;契约缺口 4 处以 `_pinsGap`/`_pinsObserved` 钉住(观察,不修实现) |
+
+> **防假 RED 声明**:本批次仅补测试证据/复验,**未写任何业务实现代码**。端点 100% 已实现(O-7 核对),无真实现缺口 → 非研发实现型 RED。契约核对 = 文档核对 + 端点比对,产出契约测试转测试侧执行证据。
+
+---
+
+## 一、SC 覆盖矩阵(12 SC + SC-A-25/26)
+
+| SC | 场景 | 契约 JUnit 类 | JUnit 用例数 | 三类流 | 端点(origin/cfclub 工作树) |
+|----|------|---------------|:---:|------|----------------------------|
+| SC-P-17 | 查看五维能量 / 健康指数 | `EnergyOverviewContractTest` | 7 | 正常/异常/权限 | `/api/energy/overview` |
+| SC-P-18 | 能量流水查看 | `EnergyLogsContractScoreHistoryTest` | 11 | 正常/异常/权限/对账 | `/api/energy/logs`、`/score-history`、`/family-score-history` |
+| SC-P-19 | 能量维度配置查看 | `EnergyConfigAdminContractTest` | 18 | 正常/异常/权限 | `/api/admin/dimension-config/**`、`/api/admin/energy-config/source-list`、`/overview` |
+| SC-P-89 | 手动发放能量 grant | `EnergyGrantContractTest` | 9 | 正常/异常/权限/并发 | `/api/energy/grant` |
+| SC-P-90 | 五维每日获取上限 DailyLimit | `EnergyConfigAdminContractTest` | 18 | 正常/异常/权限 | `/api/admin/energy-config/daily-limits`、`/daily-limit-save` |
+| SC-P-92 | 五维权重/来源比例配置变更后重算 | `EnergyConfigAdminContractTest` | 18 | 正常/异常/权限 | `/source-list`、`/source-save`、`/source-delete`;`/api/admin/energy-rule/**`;`EnergyService.configureSourceRatios`→`awardEnergy` |
+| SC-P-93 | 文章互动与活动参与触发五维能量 | `EnergyBehaviorConfigContractTest` | 7 | 正常/异常/权限 | `/api/admin/energy-behavior/list|detail|update|toggle` |
+| SC-T-31 | 手动维度打分覆盖/调整 | `ManualDimensionScoreContractTest` | 13 | 正常/异常/权限 | `/api/family/manual-score/submit|latest` |
+| SC-T-32 | 五维自评录入与变化 | `FiveDimensionSelfCheckContractTest` | 15 | 正常/异常/权限 | `/api/family/self-check/questions|submit|latest|history|status|ignore|trend-analysis` |
+| SC-X-19 | 五维能量跨角色数据隔离 | `EnergyIsolationContractTest` | 8 | 权限/观察钉住 | `/api/energy/**`、`JwtInterceptor` LOGIN_REQUIRED_PATHS |
+| SC-X-20 | 五维能量流水溯源一致性(对账) | `EnergyLogsContractScoreHistoryTest` | 11 | 对账流 | `/logs`、`/score-history`、`/family-score-history` |
+| SC-X-21 | 多来源并发同成员能量变动 | `EnergyGrantContractTest` | 9 | 并发流 | `/grant`、`/deduct-for-wish` |
+| SC-A-25 | 维度/权重/每日上限配置 CRUD 与生效 | `EnergyConfigAdminContractTest` | 18 | 正常/异常/权限 | `/api/admin/energy-config/daily-limit-save`、`/api/admin/dimension-weight/save|list` |
+| SC-A-26 | 能量来源比例与归因权重治理 | `EnergyConfigAdminContractTest` | 18 | 正常/异常/权限 | `/source-save`、`/overview`、`/api/admin/energy-rule/**` |
+
+> 同一契约类覆盖多 SC(SC-P-19/90/92、SC-X-20/21、SC-A-25/26 共享 `EnergyConfigAdminContractTest` 与 `EnergyGrantContractTest` 等),合计 **8 个契约类 / 88 用例**。
+
+## 二、契约 JUnit 执行结果(确定性,纯 Mockito / 无 Spring / 无 DB)
+
+| 契约类 | 用例 | 通过 | 失败 | 异常 | 说明 |
+|--------|:---:|:---:|:---:|:---:|------|
+| `EnergyOverviewContractTest`(SC-P-17) | 7 | 7 | 0 | 0 | 五维全量/余额和/healthIndex=0;空维度;权限 5001/400 提示 |
+| `EnergyLogsContractScoreHistoryTest`(SC-P-18/SC-X-20) | 11 | 11 | 0 | 0 | 分页默认 1/10、维度过滤、page/size 回退;对账 grant→logs 溯源一致 |
+| `EnergyGrantContractTest`(SC-P-89/SC-X-21) | 9 | 9 | 0 | 0 | 直接发放指定维度;amount≤0/非法维度/日上限→400 提示(CFC-EN-001 不回归);两来源并发各自成账 |
+| `EnergyConfigAdminContractTest`(SC-P-19/90/92/SC-A-25/26) | 18 | 18 | 0 | 0 | source-save 拆分、daily-limit-save 新增/更新、overview 分组、rule CRUD、weight CRUD、改配比例后重算生效 |
+| `EnergyBehaviorConfigContractTest`(SC-P-93) | 7 | 7 | 0 | 0 | list/detail/update/toggle 正常;目标不存在→提示 |
+| `ManualDimensionScoreContractTest`(SC-T-31) | 13 | 13 | 0 | 0 | 5 分+1 自检记录、source_type=manual;memberId/userId/scores/越界/全 0→提示 |
+| `FiveDimensionSelfCheckContractTest`(SC-T-32) | 15 | 15 | 0 | 0 | 15 题(Q6 含 E)、全 A→五维 9 分 total45、latest/history/status/ignore/trend;<10 题/某维 0 答→提示 |
+| `EnergyIsolationContractTest`(SC-X-19) | 8 | 8 | 0 | 0 | LOGIN_REQUIRED_PATHS 含 `/api/energy/`、PUBLIC_PATHS 不含;无 familyId→5001;gap 观察 3 处 |
+| **合计** | **88** | **88** | **0** | **0** | 命令:`mvn test -DskipTests=false -Dtest='Energy*,ManualDimensionScore*,FiveDimensionSelfCheck*'`(+ `TaskCreateScP10ContractTest` 14/14 基线复核) |
+
+> 汇总实测:**88 契约用例全绿**(另 `TaskCreateScP10ContractTest` 14/14 基线回归通过;`mvn test-compile` EXIT=0)。
+
+## 三、API 级 e2e 执行结果(远端 `http://cfc.iwintrue.com` 实跑)
+
+spec:`tests/e2e/api/dimension-energy-contract.spec.js` · 命令:`npx playwright test api/dimension-energy-contract.spec.js -c playwright.config.api.js --project=desktop`
+
+| 流 | 用例 | 结果 |
+|----|:---:|------|
+| 正常流(SC-P-17/18/89/93, SC-T-31/32) | 5 | ✅ 5/5(overview 五维、logs 分页、questions 15 题、submit 45 分、manual-score 350 分) |
+| 异常流(SC-P-17/89, SC-T-31/32) | 4 | ✅ 4/4(overview 无 memberId→当前成员回落;grant 非法维度→业务错误;<10 题→提示;缺维度→提示) |
+| 权限流(SC-X-19 JwtInterceptor 401) | 3+1 观察 | ✅(overview/logs 无 token→401;非法 token→401;self-check/questions 无 token→**观察 200** 见 gap) |
+| 观察钉住(`_pinsObserved`) | 1 | ✅(跨家庭 memberId 999999 → 观察 200,无归属校验,仅登记) |
+| **合计** | **14** | ✅ **14/14(23.2s)** |
+
+## 四、契约缺口钉住(观察记录,不修实现)
+
+| 缺口 | 钉住用例 | 观察行为 | 处置 |
+|------|----------|----------|------|
+| EnergyService 日上限未接入 `DimensionDailyLimit` 配置(admin 配置不参与执行,日上限用硬编码 `DAILY_LIMIT_MAP`+`GLOBAL_DAILY_LIMIT=200` @1598-1608) | `EnergyGrantContractTest.异常流_日上限` | 日上限按硬编码全局/维度上限判定,`dimension_daily_limit` 表配置不生效 | 观察钉住,不修实现 |
+| `EnergyController.overview/grant` 对传入 `memberId` 无家庭归属校验 | `EnergyIsolationContractTest._pinsObserved_跨家庭memberId无归属校验` / `_pinsObserved_grant跨家庭memberId`(e2e `_pinsObserved`) | 跨家庭 memberId 仍进入服务层返回 200 | 观察钉住,待改进 |
+| `/api/family/self-check/`、`/api/family/manual-score/` 未列入 `LOGIN_REQUIRED_PATHS`(匿名降级 userId=-1 放行) | `EnergyIsolationContractTest._pinsGap_selfCheck未强制登录`(e2e `_pinsObserved self-check/questions 无 token→200`) | questions 匿名可读 200;manual-score 可匿名提交 | 观察钉住,待治理 |
+| `AdminEnergyBehaviorConfigController.toggle` 缺 id 时无显式校验(`selectById(null)`→「配置不存在」) | `EnergyBehaviorConfigContractTest.权限流_启停缺id` | 缺 id→「配置不存在」而非「id不能为空」 | 观察钉住,不修实现 |
+| `AdminEnergyConfigController.sourceSave` ratios 为 null → NPE(无显式 400 校验) | `EnergyConfigAdminContractTest._pinsGap_异常流_来源保存ratios为null` | null ratios→NPE(GlobalExceptionHandler→500) | 观察钉住,不修实现 |
+
+## 五、改动文件清单(仅测试资产 + 执行证据,无业务代码)
+
+```
+cfc-backend/src/test/java/com/etotem/cfc/unit/EnergyContractTestBase.java          (新,公共基类)
+cfc-backend/src/test/java/com/etotem/cfc/unit/EnergyOverviewContractTest.java       (新,SC-P-17)
+cfc-backend/src/test/java/com/etotem/cfc/unit/EnergyLogsContractScoreHistoryTest.java(新,SC-P-18/SC-X-20)
+cfc-backend/src/test/java/com/etotem/cfc/unit/EnergyGrantContractTest.java          (新,SC-P-89/SC-X-21)
+cfc-backend/src/test/java/com/etotem/cfc/unit/EnergyConfigAdminContractTest.java    (新,SC-P-19/90/92/SC-A-25/26)
+cfc-backend/src/test/java/com/etotem/cfc/unit/EnergyBehaviorConfigContractTest.java (新,SC-P-93)
+cfc-backend/src/test/java/com/etotem/cfc/unit/ManualDimensionScoreContractTest.java (新,SC-T-31)
+cfc-backend/src/test/java/com/etotem/cfc/unit/FiveDimensionSelfCheckContractTest.java(新,SC-T-32)
+cfc-backend/src/test/java/com/etotem/cfc/unit/EnergyIsolationContractTest.java      (新,SC-X-19)
+tests/e2e/api/dimension-energy-contract.spec.js                                      (新,API 三类流 e2e)
+docs/tdd/test/automation-run-o7-five-dim-energy-2026-11-07.md                        (新,本证据文档)
+```
+
+## 六、结论与下一步
+
+- **结论**:本批次 12 SC + SC-A-25/26 三类流执行证据齐备(88 契约 JUnit + 14 API e2e 全绿),SC 具备转测试侧登记条件(TR-10)。
+- **下一步**:① 契约文档(API_REFERENCE 4.x 五维能量范围 + 契约缺口映射)按 O-7 授权节奏合入;② 缺口 4 处转研发侧评估(`dimension_daily_limit` 接入执行、跨家庭 memberId 归属校验、self-check/manual-score 登录治理、behavior toggle 缺 id 校验);③ 下一批 P1「内容-运营 6 SC」照此节奏滚动。

+ 160 - 0
tests/e2e/api/dimension-energy-contract.spec.js

@@ -0,0 +1,160 @@
+/**
+ * O-7 契约补建 · 五维能量批次 — 三类流 API 级 e2e
+ * ================================================================
+ * 覆盖 SC:SC-P-17/18/89/93、SC-T-31/32、SC-X-19/20/21(12 SC 开工包中的家长×跨角色×规划师代表端点,
+ * 与 cfc-backend/src/test/java/com/etotem/cfc/unit/Energy*ContractTest 契约 JUnit 互补。
+ * 契约核对 = 文档核对 + 端点比对(防假 RED,O-7 已核对 12/12 端点存在)。
+ *
+ * 端点(EnergyController / FiveDimensionSelfCheckController / ManualDimensionScoreController):
+ *   overview / logs / grant / deduct-for-wish / configure
+ *   /api/family/self-check/{questions,submit}
+ *   /api/family/manual-score/submit
+ *
+ * 运行:npx playwright test api/dimension-energy-contract.spec.js \
+ *         -c playwright.config.api.js --project=desktop
+ * (对远端 http://cfc.iwintrue.com 实跑;写入型用例如 admin 回归验证中亦以 JUnit 契约为确定性证据)
+ */
+const { test, expect } = require('@playwright/test');
+const { registerRole, apiPost, pickMemberByUserId, uniqueSuffix } = require('../helpers/api');
+
+const DIMS = ['body', 'mind', 'wisdom', 'action', 'wealth'];
+
+test.describe('O-7 五维能量 三类流(SC-P-17/18/89/93, SC-T-31/32, SC-X-19/20/21)', () => {
+  let parent;
+  let teacher;
+  let selfMemberId;
+
+  test.beforeAll(async ({ request }) => {
+    parent = await registerRole(request, 'parent', 'QA-EN-P' + uniqueSuffix());
+    const list = await apiPost(request, '/api/family/member/list', {}, parent.token);
+    expect(list.code, list.message).toBe(200);
+    const self = pickMemberByUserId(list.data, parent.userId);
+    expect(self, '成员列表应包含登录用户自身').toBeTruthy();
+    selfMemberId = self.id;
+
+    teacher = await registerRole(request, 'teacher', 'QA-EN-T' + uniqueSuffix());
+  });
+
+  // ==================== 正常流 ====================
+
+  test.describe('正常流', () => {
+    test('SC-P-17 overview 返回五维(body/mind/wisdom/action/wealth)', async ({ request }) => {
+      const r = await apiPost(request, '/api/energy/overview', { memberId: selfMemberId }, parent.token);
+      expect(r.code, r.message).toBe(200);
+      const dims = r.data && r.data.dimensions;
+      expect(Array.isArray(dims)).toBe(true);
+      expect(dims.length).toBe(5);
+      const codes = dims.map((d) => d.code);
+      for (const dim of DIMS) expect(codes).toContain(dim);
+      expect(typeof r.data.totalEnergy).toBe('number');
+    });
+
+    test('SC-P-18 logs 分页返回流水结构', async ({ request }) => {
+      const r = await apiPost(request, '/api/energy/logs', { memberId: selfMemberId, page: 1, size: 10 }, parent.token);
+      expect(r.code, r.message).toBe(200);
+      expect(Array.isArray(r.data && r.data.records)).toBe(true);
+      expect(r.data.size).toBe(10);
+      expect(r.data.current).toBe(1);
+    });
+
+    test('SC-T-32 self-check questions 返回 15 题(Q6 含 E 跳过项)', async ({ request }) => {
+      const r = await apiPost(request, '/api/family/self-check/questions', {}, parent.token);
+      expect(r.code, r.message).toBe(200);
+      expect(r.data.length).toBe(15);
+      const q6 = r.data[5];
+      expect(String(q6.options.length)).toBe('5');
+    });
+
+    test('SC-T-32 self-check submit 15 题全 A → totalScore=45', async ({ request }) => {
+      const answers = [];
+      for (let i = 1; i <= 15; i++) answers.push({ questionId: i, answer: 'A' });
+      const r = await apiPost(request, '/api/family/self-check/submit', { familyMemberId: selfMemberId, answers }, parent.token);
+      expect(r.code, r.message).toBe(200);
+      expect(r.data.totalScore).toBe(45);
+      expect(r.data.dimensions.length).toBe(5);
+    });
+
+    test('SC-T-31 manual-score submit 五维 → totalScore=350', async ({ request }) => {
+      const r = await apiPost(request, '/api/family/manual-score/submit', {
+        memberId: selfMemberId,
+        scores: { body: 80, mind: 60, wisdom: 70, action: 50, wealth: 90 },
+      }, teacher.token);
+      expect(r.code, r.message).toBe(200);
+      expect(r.data.totalScore).toBe(350);
+      expect(Object.keys(r.data.scores).length).toBe(5);
+    });
+  });
+
+  // ==================== 异常流 ====================
+
+  test.describe('异常流', () => {
+    test('SC-P-17 overview 无 memberId → 使用当前登录成员回落(观察行为)', async ({ request }) => {
+      // 观察:JwtInterceptor 注入 currentMemberId,controller 在 memberId 缺省时回落当前成员 → 200
+      const r = await apiPost(request, '/api/energy/overview', {}, parent.token);
+      expect(r.code, r.message).toBe(200);
+      expect(r.data && r.data.dimensions).toBeTruthy();
+    });
+
+    test('SC-P-89 grant 非法维度 code → 业务错误', async ({ request }) => {
+      const r = await apiPost(request, '/api/energy/grant', {
+        memberId: selfMemberId, taskId: 999999, amount: 10, dimensionCode: 'nonexistent-dim',
+      }, parent.token);
+      expect([400, 500]).toContain(r.code);
+      expect(String(r.message)).toContain('维度');
+    });
+
+    test('SC-T-32 self-check submit 少于 10 题 → 业务错误', async ({ request }) => {
+      const answers = [];
+      for (let i = 1; i <= 9; i++) answers.push({ questionId: i, answer: 'A' });
+      const r = await apiPost(request, '/api/family/self-check/submit', { familyMemberId: selfMemberId, answers }, parent.token);
+      expect(r.code).not.toBe(200);
+      expect(String(r.message)).toContain('至少10道题目');
+    });
+
+    test('SC-T-31 manual-score 缺维度 → 业务错误', async ({ request }) => {
+      const r = await apiPost(request, '/api/family/manual-score/submit', {
+        memberId: selfMemberId,
+        scores: { body: 80, mind: 60, wisdom: 70, action: 50 }, // 缺 wealth
+      }, teacher.token);
+      expect(r.code).not.toBe(200);
+      expect(String(r.message)).toContain('维度');
+    });
+  });
+
+  // ==================== 权限流 ====================
+
+  test.describe('权限流(JwtInterceptor 401 闸门)', () => {
+    test('SC-X-19 overview 无 token → 401', async ({ request }) => {
+      const r = await apiPost(request, '/api/energy/overview', { memberId: selfMemberId }, null);
+      expect(r.status).toBe(401);
+      expect(String(r.message)).toContain('请先登录');
+    });
+
+    test('SC-X-19 logs 无 token → 401', async ({ request }) => {
+      const r = await apiPost(request, '/api/energy/logs', { memberId: selfMemberId }, null);
+      expect(r.status).toBe(401);
+    });
+
+    test('_pinsObserved self-check/questions 无 token → 观察 200(userId=-1 匿名放行,未列 LOGIN_REQUIRED_PATHS)', async ({ request }) => {
+      // 观察:/api/family/self-check/ 未列入 LOGIN_REQUIRED_PATHS,匿名降级 userId=-1 放行 → 200(契约缺口,仅登记)
+      const r = await apiPost(request, '/api/family/self-check/questions', {}, null);
+      expect(r.status).toBe(200);
+      expect(r.data && r.data.length).toBe(15);
+    });
+
+    test('SC-X-19 另一家庭家长无法通过游客通道读取能量(登出后 401)', async ({ request }) => {
+      const r = await apiPost(request, '/api/energy/logs', { memberId: selfMemberId }, 'invalid-token-value');
+      expect(r.status).toBe(401);
+    });
+  });
+
+  // ==================== 观察钉住(gap,只读验证,不修改实现) ====================
+
+  test.describe('_pinsObserved(契约缺口观察)', () => {
+    test('overview 传跨家庭 memberId(999999)→ 观察返回 200(无归属校验,仅登记)', async ({ request }) => {
+      const r = await apiPost(request, '/api/energy/overview', { memberId: 999999 }, parent.token);
+      expect(r.code).toBe(200);
+      expect(r.data && r.data.dimensions).toBeTruthy();
+    });
+  });
+});