Просмотр исходного кода

test(plan.task.list): add RED contract test for SC-P-47 plan task list view (S-cfc-282)

TDD-RED: plan.task.list 能力键契约新增,实现未落地,写预期红契约单测。

契约溯源:
- 需求 SC-P-47(查看方案下任务列表:方案关联任务列表(状态/进度),任务增删与方案同步)
- 设计 API_REFERENCE.md 4.3 任务视图;模块 GrowthPlanController + TaskController

新增 GrowthPlanTaskListContractTest(反射结构契约,纯 Mockito/无 Spring/DB/外部服务):
- 正常流-1: GrowthPlanController 应暴露 POST /api/growth/plan/task/list
- 正常流-2: 任务 Item 应含 status/progress 字段(已存在,绿)
- 正常流-3: 任务应含 growthPlanId/planId 方案关联(任务增删与方案同步)
- 正常流-4: GrowthPlanService 应提供方案任务清单方法
- 异常流-1: 缺 planId/memberId 参数守卫
- 权限流-1: 家庭归属校验(IDOR 防护)

RED 结果: 6 tests, 5 failures(契约缺失点), 1 pass(既有字段)
Sisyphus 6 дней назад
Родитель
Сommit
51ab1a0d09

+ 305 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/GrowthPlanTaskListContractTest.java

@@ -0,0 +1,305 @@
+package com.etotem.cfc.unit;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.lang.reflect.Method;
+import java.lang.reflect.ParameterizedType;
+import java.lang.reflect.Type;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assertions.fail;
+
+/**
+ * 契约级单测:成长方案任务清单视图(能力键 {@code plan.task.list})。
+ *
+ * <p>契约来源(TDD-RED 阶段契约新增能力,SC-P-47 方案任务列表,业务域 D):
+ * <blockquote>
+ *   SC-P-47 · 查看方案下任务列表 — 目标:跟踪执行。流程:方案 → 关联任务列表(状态/进度)。
+ *   边界:任务增删与方案同步。模块:{@code GrowthPlanController} + {@code TaskController}。
+ * </blockquote></p>
+ *
+ * <p><b>与 task.* 能力的区分</b>:{@code task.parent.createTask} / {@code task.parent.review}
+ * (S-cfc-12/13)面向通用任务的创建与审批;本键 {@code plan.task.list} 面向
+ * <b>方案维度的任务清单视图</b>(读侧聚合:列表 + 状态/进度 + 增删同步)。</p>
+ *
+ * <p><b>实现现状(src/main 核实)</b>:
+ * <ul>
+ *   <li>{@code GrowthPlanController}(/{@code api/growth/plan})现有端点:create / child/{memberId} /
+ *       child/{memberId}/active / {id} / update / {id}/review / list(管理端分页);
+ *       <b>无方案任务列表视图端点</b>。</li>
+ *   <li>{@code GrowthPlanService} 无 {@code planTaskList}/{@code getPlanTasks}/{@code planTasks}
+ *       等任务清单方法;{@code GrowthPlan} 实体无任务关联字段、无进度聚合。</li>
+ *   <li>任务实体 {@code Task} 尚无成长方案关联维度(无 growthPlanId/planId),
+ *       「任务增删与方案同步」无落点。</li>
+ * </ul>
+ * 因此本测试以「反射结构契约」探测实现缺失:
+ * <b>能编译通过、能运行、断言失败(红)</b>,且失败断言原文清晰可贴。</p>
+ *
+ * <p><b>GREEN 升级指引</b>:实现者在 {@code GrowthPlanController} 暴露方案任务列表视图
+ * (契约路由 {@code POST /api/growth/plan/task/list},body {planId} 或 {memberId}),
+ * 由 {@code GrowthPlanService} 提供任务清单(返回含 status/progress 的任务项),
+ * 并打通任务增删与方案的同步后,本测试自动转绿;
+ * 届时可把结构探测升级为行为级 Mockito 验证。</p>
+ *
+ * <p><b>三流覆盖</b>:
+ * <ul>
+ *   <li>正常流:视图端点存在 + 任务清单方法存在 + 状态/进度字段 + 方案关联字段;</li>
+ *   <li>异常流:缺 planId/memberId 参数守卫;</li>
+ *   <li>权限流:非本家庭不可见(IDOR 防护,familyId 归属校验)。</li>
+ * </ul></p>
+ *
+ * <p><b>测试范围</b>:仅反射探测结构契约(无 Spring / 无 DB / 无外部服务),断言不依赖真实数据。</p>
+ */
+class GrowthPlanTaskListContractTest {
+
+    /** 契约要求的方案任务列表视图端点所在控制器(growth 子包) */
+    private static final String GROWTH_PLAN_CONTROLLER = "com.etotem.cfc.controller.growth.GrowthPlanController";
+
+    /** 契约要求的方案任务清单服务 */
+    private static final String GROWTH_PLAN_SERVICE = "com.etotem.cfc.service.GrowthPlanService";
+
+    /** 任务实体(现有,用于进度/关联字段探测) */
+    private static final String TASK_ENTITY = "com.etotem.cfc.entity.Task";
+
+    /** 契约路由:POST /api/growth/plan/task/list(方案任务列表视图,SC-P-47) */
+    private static final String CONTRACT_ROUTE = "/api/growth/plan/task/list";
+
+    /** 契约 GATE 接口方法名候选(任务清单视图入口 / 任务清单服务方法) */
+    private static final String[] PLAN_TASK_METHODS = {"planTaskList", "getPlanTasks", "planTasks"};
+
+    // ------------------------------------------------------------------
+    // 正常流-1:GrowthPlanController 应暴露方案任务列表视图端点
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-1:GrowthPlanController 应暴露 /api/growth/plan/task/list 方案任务列表端点")
+    void growthPlanController_exposesPlanTaskListRoute() {
+        Class<?> clazz = loadClass(GROWTH_PLAN_CONTROLLER);
+        assertNotNull(clazz, "[plan.task.list] GrowthPlanController 类不存在(" + GROWTH_PLAN_CONTROLLER + ")。");
+        assertTrue(hasRoutePrefix(clazz, "/api/growth/plan"),
+                "[plan.task.list] GrowthPlanController 应映射 /api/growth/plan 前缀。");
+        assertTrue(hasRoute(clazz, CONTRACT_ROUTE),
+                "[plan.task.list] " + simpleName(GROWTH_PLAN_CONTROLLER)
+                        + " 未暴露 POST " + CONTRACT_ROUTE
+                        + " 方案任务列表视图端点(SC-P-47:方案 → 关联任务列表(状态/进度))。实现未落地。");
+    }
+
+    // ------------------------------------------------------------------
+    // 正常流-2:任务清单应含「状态/进度」两个契约字段
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-2:任务清单 Item 应含 status/progress 字段(状态/进度)")
+    void planTaskListItem_carriesStatusAndProgress() {
+        Class<?> taskClazz = loadClass(TASK_ENTITY);
+        assertNotNull(taskClazz, "[plan.task.list] Task 实体不存在(" + TASK_ENTITY + ")。");
+        boolean hasStatus = hasField(taskClazz, "status");
+        boolean hasProgress = hasField(taskClazz, "progress") || hasField(taskClazz, "todayDone");
+        assertTrue(hasStatus && hasProgress,
+                "[plan.task.list] 任务 Item 应含 status(状态)与 progress/todayDone(进度)字段"
+                        + "(当前 status=" + hasStatus + ", progress=" + hasProgress + ")。");
+    }
+
+    // ------------------------------------------------------------------
+    // 正常流-3:任务增删与方案同步(方案维度关联)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-3:任务应支持方案维度关联(任务增删与方案同步)")
+    void task_supportsPlanAssociation() {
+        Class<?> taskClazz = loadClass(TASK_ENTITY);
+        assertNotNull(taskClazz, "[plan.task.list] Task 实体不存在(" + TASK_ENTITY + ")。");
+        boolean hasPlanAssoc = hasField(taskClazz, "growthPlanId")
+                || hasField(taskClazz, "planId");
+        assertTrue(hasPlanAssoc,
+                "[plan.task.list] 任务应含 growthPlanId/planId 方案关联字段,"
+                        + "保证「任务增删与方案同步」(SC-P-47 边界)。当前缺失。");
+    }
+
+    // ------------------------------------------------------------------
+    // 正常流-4:GrowthPlanService 应提供方案任务清单方法
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-4:GrowthPlanService 应提供方案任务清单方法")
+    void growthPlanService_hasPlanTaskListMethod() {
+        Class<?> clazz = loadClass(GROWTH_PLAN_SERVICE);
+        assertNotNull(clazz, "[plan.task.list] GrowthPlanService 类不存在(" + GROWTH_PLAN_SERVICE + ")。");
+        StringBuilder found = new StringBuilder();
+        for (String m : PLAN_TASK_METHODS) {
+            for (Method method : clazz.getDeclaredMethods()) {
+                if (method.getName().equals(m)) {
+                    found.append(m).append("(").append(method.getParameterCount()).append(") ");
+                    break;
+                }
+            }
+            if (found.length() > 0) {
+                break;
+            }
+        }
+        assertTrue(found.length() > 0,
+                "[plan.task.list] GrowthPlanService 应提供 " + String.join("/", PLAN_TASK_METHODS)
+                        + " 方案任务清单方法(返回任务列表,含状态/进度)。实现未落地。");
+    }
+
+    // ------------------------------------------------------------------
+    // 异常流-1:缺 planId/memberId 参数守卫
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("异常流-1:方案任务列表入参应含 planId/memberId(缺参守卫)")
+    void planTaskList_requiresPlanIdOrMemberId() {
+        Class<?> clazz = loadClass(GROWTH_PLAN_SERVICE);
+        if (clazz == null) {
+            fail("[plan.task.list] GrowthPlanService 不存在,无法校验入参守卫(异常流)。");
+        }
+        boolean methodFound = false;
+        for (Method method : clazz.getDeclaredMethods()) {
+            if (!isPlanTaskMethod(method)) {
+                continue;
+            }
+            methodFound = true;
+            boolean hasPlanParam = false;
+            for (Type t : method.getGenericParameterTypes()) {
+                String typeName = typeSimpleName(t);
+                if (typeName.equals("Long") || typeName.equals("Map")) {
+                    hasPlanParam = true;
+                }
+            }
+            assertTrue(hasPlanParam,
+                    "[plan.task.list] " + method.getName() + " 应接收 planId/memberId 参数(缺参守卫要求)。");
+        }
+        if (!methodFound) {
+            fail("[plan.task.list] 异常流:方案任务清单方法未落地,无法验证缺参守卫。实现未落地。");
+        }
+    }
+
+    // ------------------------------------------------------------------
+    // 权限流-1:非本家庭不可见(IDOR 防护)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("权限流-1:方案任务列表视图应校验家庭归属(IDOR 防护)")
+    void planTaskList_guardsFamilyScope() {
+        Class<?> clazz = loadClass(GROWTH_PLAN_CONTROLLER);
+        if (clazz == null) {
+            fail("[plan.task.list] GrowthPlanController 不存在,无法校验家庭归属守卫(权限流)。");
+        }
+        boolean methodFound = false;
+        for (Method method : clazz.getDeclaredMethods()) {
+            if (!method.getName().equals("planTaskList") && !method.getName().equals("planTasks")) {
+                continue;
+            }
+            methodFound = true;
+            boolean hasFamilyParam = false;
+            for (Type t : method.getGenericParameterTypes()) {
+                if (typeSimpleName(t).equals("Long")) {
+                    hasFamilyParam = true;
+                }
+            }
+            assertTrue(hasFamilyParam,
+                    "[plan.task.list] 方案任务列表视图端点应携带 familyId 校验家庭归属"
+                            + "(非本家庭不可见,IDOR 防护)。实现未落地。");
+        }
+        if (!methodFound) {
+            fail("[plan.task.list] 权限流:方案任务列表视图端点未落地,无法验证家庭归属守卫。实现未落地。");
+        }
+    }
+
+    // ------------------------------------------------------------------
+    // 反射辅助
+    // ------------------------------------------------------------------
+
+    private Class<?> loadClass(String name) {
+        try {
+            return Class.forName(name, false, Thread.currentThread().getContextClassLoader());
+        } catch (ClassNotFoundException e) {
+            return null;
+        }
+    }
+
+    private boolean isPlanTaskMethod(Method method) {
+        for (String m : PLAN_TASK_METHODS) {
+            if (method.getName().equals(m)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private boolean hasField(Class<?> clazz, String fieldName) {
+        try {
+            clazz.getDeclaredField(fieldName);
+            return true;
+        } catch (NoSuchFieldException e) {
+            return false;
+        }
+    }
+
+    /**
+     * 探测契约路由 {@code /api/growth/plan/task/list} 是否已暴露。
+     * <p>严格按「路径段」匹配,避免把管理端的 {@code /list}({@code /api/growth/plan/list})
+     * 误判为契约的 {@code /task/list}:方法级相对路径必须完整等于 {@code task/list}
+     * (或以 {@code /task/list} 形式声明)。</p>
+     */
+    private boolean hasRoute(Class<?> clazz, String route) {
+        // 类级 @RequestMapping 直接拼完整路由(无子包前缀时)
+        org.springframework.web.bind.annotation.RequestMapping rm =
+                clazz.getAnnotation(org.springframework.web.bind.annotation.RequestMapping.class);
+        if (rm != null) {
+            for (String v : rm.value()) {
+                if (route.equals(v)) {
+                    return true;
+                }
+            }
+        }
+        // 方法级:契约相对路径段 = "task/list"
+        final String contractRelative = "task/list";
+        for (Method m : clazz.getDeclaredMethods()) {
+            org.springframework.web.bind.annotation.PostMapping pm =
+                    m.getAnnotation(org.springframework.web.bind.annotation.PostMapping.class);
+            if (pm == null) {
+                continue;
+            }
+            for (String v : pm.value()) {
+                String normalized = v.startsWith("/") ? v.substring(1) : v;
+                if (normalized.equals(contractRelative)) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+
+    private boolean hasRoutePrefix(Class<?> clazz, String prefix) {
+        org.springframework.web.bind.annotation.RequestMapping rm =
+                clazz.getAnnotation(org.springframework.web.bind.annotation.RequestMapping.class);
+        if (rm == null) {
+            return false;
+        }
+        for (String v : rm.value()) {
+            if (prefix.equals(v)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private String typeSimpleName(Type t) {
+        if (t instanceof Class) {
+            return ((Class<?>) t).getSimpleName();
+        }
+        if (t instanceof ParameterizedType) {
+            return typeSimpleName(((ParameterizedType) t).getRawType());
+        }
+        return String.valueOf(t);
+    }
+
+    private String simpleName(String fqcn) {
+        int idx = fqcn.lastIndexOf('.');
+        return idx >= 0 ? fqcn.substring(idx + 1) : fqcn;
+    }
+}