فهرست منبع

test(S-cfc-265): RED 契约单测 energy.ledger.view(SC-P-18 能量流水查看展示口径)

契约锚点:SC-P-18 / API_REFERENCE §4.5 /api/energy/logs;与 energy.ledger.guard(S-cfc-225) 职责区分:view=查看流水、guard=账本守卫。

RED 断言展示口径未落地:
- sourceName 可读来源名(task→完成任务 / health_checkin→健康打卡 / assessment→测评 / 未映射回退原始码)
- dimensionCode 维度代码暴露(按 dimensionId)
- createdAt @JsonFormat(yyyy-MM-dd'T'HH:mm:ss) 时间格式统一

纯 Mockito/反射,无 Spring/DB;8 测试 = 6 红(契约缺口)+ 2 绿(既有 memberId/familyId 门禁回归)。仅新增测试文件,未改 src/main。
Sisyphus 3 روز پیش
والد
کامیت
494b64c820
1فایلهای تغییر یافته به همراه235 افزوده شده و 0 حذف شده
  1. 235 0
      cfc-backend/src/test/java/com/etotem/cfc/unit/EnergyLedgerViewContractTest.java

+ 235 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/EnergyLedgerViewContractTest.java

@@ -0,0 +1,235 @@
+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.mapper.EnergyDimensionMapper;
+import com.etotem.cfc.mapper.EnergyLogMapper;
+import com.etotem.cfc.service.EnergyService;
+import com.fasterxml.jackson.annotation.JsonFormat;
+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.HashMap;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+/**
+ * 契约测试:能力键 {@code energy.ledger.view}(SC-P-18 能量流水查看,业务域 C 五维能量与健康)。
+ *
+ * <p><b>契约锚点</b></p>
+ * <ul>
+ *   <li>需求:{@code tests/user-scenarios/应用场景总览.md} SC-P-18 —— 目标:追溯能量来源;流程:能量明细(任务/打卡/测评);边界:时间格式统一。模块:{@code EnergyController}。</li>
+ *   <li>设计:{@code docs/superpowers/api/API_REFERENCE.md} §4.5 —— {@code POST /api/energy/logs} 能量流水。</li>
+ *   <li>职责边界:本键 = 查看流水(view);{@code energy.ledger.guard}(S-cfc-225)= 账本一致性守卫。二者互补不重复:guard 校验 {@code balanceAfter==prev+amount},view 校验 <b>展示口径</b>(来源可读名 + 时间格式)。</li>
+ * </ul>
+ *
+ * <p><b>被校验的契约行为(展示口径,TDD-RED)</b></p>
+ * <ul>
+ *   <li><b>来源溯源可读</b>:每条流水必须暴露可读来源名 {@code sourceName}("task"→"完成任务"、"health_checkin"→"健康打卡"、"assessment"→"测评"等),而非仅原始 {@code sourceType} 码;未映射来源回退原始码,不得抛错。</li>
+ *   <li><b>维度代码</b>:每条流水需暴露 {@code dimensionCode}(如 "body"/"mind"),使前端无需再查维度表即可按维度着色/筛选。</li>
+ *   <li><b>时间格式统一</b>:{@code createdAt} 响应须以 {@code yyyy-MM-dd'T'HH:mm:ss}(ISO 8601)字符串暴露,而非裸 {@code java.util.Date}(Jackson 默认序列化为 epoch 毫秒)。与项目时间显示规范一致(后端统一 ISO 8601,前端按需格式化)。</li>
+ * </ul>
+ *
+ * <p><b>测试范围</b>:{@link EnergyController#getEnergyLogs} + {@link EnergyService#getLogs} 的展示口径。仅用 Mockito(无 Spring / 无 DB),不依赖真实外部服务。</p>
+ *
+ * <p><b>读取策略</b>:{@code sourceName}/{@code dimensionCode} 为待落地的展示字段,{@code EnergyLog} 实体当前没有,
+ * 故用反射 {@link #readField} 读取(字段缺失即抛异常 = 契约失败),使本测试可编译、失败发生在测试阶段(运行期红)而非编译期红,
+ * 与同批 RED 契约测试风格一致。{@code createdAt} 的 ISO 8601 契约用 {@code @JsonFormat} 注解存在性断言。</p>
+ *
+ * <p><b>RED 预期</b>:{@code EnergyLog} 实体当前只有 {@code sourceType}/{@code sourceId}/{@code dimensionId}/{@code Date createdAt},
+ * 无 {@code sourceName}/{@code dimensionCode} 展示字段,{@code createdAt} 亦无 {@code @JsonFormat} —— 本契约展示口径未落地,
+ * 三条用例在 GREEN 补齐前应失败(红)。</p>
+ */
+class EnergyLedgerViewContractTest extends EnergyContractTestBase {
+
+    private static final String MSG_NO_MEMBER = "memberId不能为空";
+
+    private EnergyService service;
+    private EnergyDimensionMapper dimensionMapper;
+    private EnergyLogMapper logMapper;
+    private EnergyController controller;
+
+    @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));
+
+        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(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;
+        });
+    }
+
+    /** 通过 controller 入口取回流水 Page(走 memberId/familyId 门禁 + service.getLogs) */
+    private Page<EnergyLog> invokeLogs() {
+        Map<String, Object> params = new HashMap<>();
+        params.put("memberId", 50L);
+        Result<Page<EnergyLog>> r = controller.getEnergyLogs(params, 1L, 50L);
+        assertEquals(200, r.getCode(), "入口应返回 200");
+        assertNotNull(r.getData());
+        return r.getData();
+    }
+
+    /** 反射读取实体字段(沿类层次向上查找);字段缺失即抛 IllegalStateException = 契约失败 */
+    private static Object readField(Object target, String fieldName) {
+        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 IllegalStateException(
+                    "EnergyLog 缺少契约展示字段 '" + fieldName + "'(SC-P-18 能量流水查看:展示口径未落地)");
+        }
+        f.setAccessible(true);
+        try {
+            return f.get(target);
+        } catch (IllegalAccessException e) {
+            throw new IllegalStateException("无法读取字段 " + fieldName, e);
+        }
+    }
+
+    // ==================== 契约 AC-1:来源溯源可读(task / health_checkin / assessment) ====================
+
+    @Test
+    @DisplayName("SC-P-18 契约:task 流水暴露可读来源名 sourceName=完成任务")
+    void 契约_任务流水_来源可读名() {
+        seedDims();
+        seedPage(energyLog(1L, 50L, 5L, 10, 30, "task", 100L));
+
+        Page<EnergyLog> page = invokeLogs();
+        EnergyLog log = page.getRecords().get(0);
+        assertEquals("task", log.getSourceType(), "原始来源码应为 task");
+        assertEquals("完成任务", readField(log, "sourceName"), "task 应映射为可读来源名「完成任务」");
+    }
+
+    @Test
+    @DisplayName("SC-P-18 契约:health_checkin 流水暴露可读来源名 sourceName=健康打卡")
+    void 契约_打卡流水_来源可读名() {
+        seedDims();
+        seedPage(energyLog(2L, 50L, 4L, 5, 25, "health_checkin", 200L));
+
+        Page<EnergyLog> page = invokeLogs();
+        EnergyLog log = page.getRecords().get(0);
+        assertEquals("health_checkin", log.getSourceType(), "原始来源码应为 health_checkin");
+        assertEquals("健康打卡", readField(log, "sourceName"), "health_checkin 应映射为「健康打卡」");
+    }
+
+    @Test
+    @DisplayName("SC-P-18 契约:assessment 流水暴露可读来源名 sourceName=测评")
+    void 契约_测评流水_来源可读名() {
+        seedDims();
+        seedPage(energyLog(3L, 50L, 1L, 8, 18, "assessment", 300L));
+
+        Page<EnergyLog> page = invokeLogs();
+        EnergyLog log = page.getRecords().get(0);
+        assertEquals("assessment", log.getSourceType(), "原始来源码应为 assessment");
+        assertEquals("测评", readField(log, "sourceName"), "assessment 应映射为「测评」");
+    }
+
+    @Test
+    @DisplayName("SC-P-18 契约:未映射来源码回退原始码,不抛错")
+    void 契约_未映射来源_回退原始码() {
+        seedDims();
+        seedPage(energyLog(4L, 50L, 3L, 6, 6, "unknown_source", 400L));
+
+        Page<EnergyLog> page = invokeLogs();
+        EnergyLog log = page.getRecords().get(0);
+        assertEquals("unknown_source", readField(log, "sourceName"), "未映射来源应回退原始码,且不抛错");
+    }
+
+    // ==================== 契约 AC-2:维度代码暴露 ====================
+
+    @Test
+    @DisplayName("SC-P-18 契约:流水暴露 dimensionCode(如 body)供前端维度着色/筛选")
+    void 契约_流水暴露维度代码() {
+        seedDims();
+        seedPage(energyLog(5L, 50L, 5L, 10, 10, "task", 500L));
+
+        Page<EnergyLog> page = invokeLogs();
+        EnergyLog log = page.getRecords().get(0);
+        assertEquals(5L, log.getDimensionId(), "前置:维度 ID=5 应为 body");
+        assertEquals("body", readField(log, "dimensionCode"), "应按 dimensionId 暴露 dimensionCode");
+    }
+
+    // ==================== 契约 AC-3:时间格式统一(yyyy-MM-dd'T'HH:mm:ss) ====================
+
+    @Test
+    @DisplayName("SC-P-18 契约:createdAt 以 ISO 8601 序列化(@JsonFormat yyyy-MM-dd'T'HH:mm:ss)")
+    void 契约_时间格式ISO8601() throws Exception {
+        seedDims();
+        seedPage(energyLog(6L, 50L, 5L, 10, 10, "task", 600L));
+
+        Page<EnergyLog> page = invokeLogs();
+        EnergyLog log = page.getRecords().get(0);
+        assertNotNull(log.getCreatedAt(), "前置:createdAt 非空");
+
+        Field createdAtField = EnergyLog.class.getDeclaredField("createdAt");
+        JsonFormat ann = createdAtField.getAnnotation(JsonFormat.class);
+        assertNotNull(ann,
+                "EnergyLog.createdAt 需 @JsonFormat(pattern=\"yyyy-MM-dd'T'HH:mm:ss\"),否则 Jackson 序列化为 epoch 毫秒,时间格式不统一");
+        assertEquals("yyyy-MM-dd'T'HH:mm:ss", ann.pattern(), "时间格式必须统一为 yyyy-MM-dd'T'HH:mm:ss");
+    }
+
+    // ==================== 既有门禁回归:view 与 guard 职责不互斥 ====================
+
+    @Test
+    @DisplayName("SC-P-18 回归:无 memberId 仍返回业务提示(view 不破坏既有门禁)")
+    void 回归_无memberId_业务提示() {
+        Map<String, Object> params = new HashMap<>();
+        params.put("dimensionCode", "body");
+        Result<Page<EnergyLog>> r = controller.getEnergyLogs(params, 1L, null);
+        assertEquals(500, r.getCode());
+        assertEquals(MSG_NO_MEMBER, r.getMessage());
+    }
+
+    @Test
+    @DisplayName("SC-P-18 回归:无 familyId 返回 5001(view 不破坏既有权限门禁)")
+    void 回归_无familyId_5001() {
+        Map<String, Object> params = new HashMap<>();
+        params.put("memberId", 50L);
+        Result<Page<EnergyLog>> r = controller.getEnergyLogs(params, null, 50L);
+        assertEquals(5001, r.getCode());
+    }
+}