Переглянути джерело

test(S-cfc-298): 新增 plan.draft.save 方案/任务草稿保存与恢复 RED 契约测试

能力键 plan.draft.save(SC-P-81 业务域 L 家长,模块 方案/任务)。
反射锚定 GrowthPlanService 草稿契约方法 + growth_plans 草稿列 +
GrowthPlan 草稿字段 + 控制器草稿端点,全部用例预期红(RED)。

覆盖三类流:
- 正常流:存草稿(status=draft + 有效期 draftExpiresAt) → 恢复继续编辑
- 异常流:过期草稿『草稿已失效』;并发存两版草稿后者覆盖且提示冲突
- 权限流:越权恢复他人草稿 403/401 不泄露

参考已有合并批次样式 TeamStarMultiplierContractTest /
TeamProfitHookContractTest / PlanLifecycleParentContractTest。
Sisyphus Agent 2 днів тому
батько
коміт
4f84c6846b

+ 372 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/PlanDraftSaveContractTest.java

@@ -0,0 +1,372 @@
+package com.etotem.cfc.unit;
+
+import com.etotem.cfc.entity.GrowthPlan;
+import com.etotem.cfc.mapper.GrowthPlanMapper;
+import com.etotem.cfc.service.GrowthPlanService;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.io.InputStream;
+import java.lang.annotation.Annotation;
+import java.lang.reflect.Field;
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.nio.charset.StandardCharsets;
+import java.util.Date;
+import java.util.Scanner;
+
+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.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assertions.fail;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+/**
+ * 契约级单测:方案/任务草稿保存与恢复(能力键 {@code plan.draft.save},业务域 L 家长,模块 方案/任务)。
+ *
+ * <p><b>需求/设计锚点</b></p>
+ * <ul>
+ *   <li>需求:SC-P-81(方案草稿保存与恢复)—— {@code tests/user-scenarios/应用场景总览.md}、
+ *       {@code tests/user-scenarios/02-parent.md} 场景 P-81</li>
+ *   <li>用例:{@code tests/test-cases/parent.md}
+ *       TC-P-81(正常:存草稿 → 恢复继续)、TC-P-81-E(异常:过期草稿提示『草稿已失效』,
+ *       并发存两版草稿 → 后者覆盖且提示冲突)、TC-P-81-P(权限:越权 403/401,不泄露他人数据)</li>
+ *   <li>设计:{@code docs/superpowers/api/API_REFERENCE.md} §4.6 成长档案 —— 成长方案
+ *       {@code POST /api/growth/plan/create}(计划创建前可存草稿)</li>
+ *   <li>批次派发:{@code docs/tdd/test/automation-run-evd8-assessment-plan-2026-11-07.md}
+ *       (SC-P-81 → 草稿保存/恢复契约,端点提示 {@code /api/plan/draft-save}、{@code /draft-restore})</li>
+ * </ul>
+ *
+ * <p><b>被校验的契约行为(SC-P-81 三类流)</b></p>
+ * <ul>
+ *   <li>正常流:存草稿(暂存未完)→ 恢复继续编辑。草稿以 {@code status="draft"} 持久化,
+ *       并携带有效期(边界:草稿有效期)与版本号。</li>
+ *   <li>异常流:恢复已超有效期的草稿 → 提示『草稿已失效』;并发存两版草稿 →
+ *       后者覆盖且提示冲突(版本号递增检测)。</li>
+ *   <li>权限流:非归属(他人/无关家庭)数据 → 403/401 拒绝,不泄露他人草稿(横向越权被拒)。</li>
+ * </ul>
+ *
+ * <p><b>宿主契约(TDD-RED 锚点)</b>:{@code com.etotem.cfc.service.GrowthPlanService} ——
+ * 当前(2026-11-14)类<b>已存在</b>但<b>缺少草稿保存/恢复能力</b>(仅 {@code createPlan},且
+ * {@code status} 为空时强制置为 {@code "active"},无 {@code saveDraft}/{@code restoreDraft})。
+ * 本测试通过反射探测宿主契约方法(避免直接 import 不存在方法导致编译失败),方法缺失即断言失败(红),
+ * 暴露"方案草稿保存与恢复未落地"这一真实缺陷;实现落地后转为验证真实行为(GREEN)。</p>
+ *
+ * <p><b>契约方法签名(实现方按此落地,宿主 {@code GrowthPlanService})</b></p>
+ * <ul>
+ *   <li>{@code GrowthPlan saveDraft(GrowthPlan plan)} —— 存草稿:持久化 {@code status="draft"},
+ *       设置 {@code draftExpiresAt = now + 有效期}(默认 7 天,边界:草稿有效期),返回已存草稿(含 id/版本)</li>
+ *   <li>{@code GrowthPlan restoreDraft(Long draftId)} —— 恢复草稿继续编辑;过期 → 抛/返『草稿已失效』</li>
+ *   <li>{@code boolean isDraftExpired(GrowthPlan draft)} —— 草稿是否已超有效期({@code draftExpiresAt < now})</li>
+ *   <li>{@code boolean isDraftVersionConflict(Long draftId, long localVersion)} —— 并发检测:
+ *       服务端已存版本 &gt; 本地版本 → 冲突提示(后存覆盖前存且提示冲突)</li>
+ *   <li>{@code GrowthPlan restoreDraft(Long draftId, Long userId)} —— 权限恢复:非归属(非本人创建)→
+ *       403/401 拒绝,不返回他人草稿</li>
+ * </ul>
+ *
+ * <p><b>配套结构契约</b></p>
+ * <ul>
+ *   <li>{@code growth_plans} 表(schema.sql)新增列:{@code draft_expires_at DATETIME}(草稿有效期)、
+ *       {@code draft_version INT}(草稿版本号)</li>
+ *   <li>{@code GrowthPlan} 实体新增字段:{@code draftExpiresAt}、{@code draftVersion}</li>
+ *   <li>{@code GrowthPlanController}({@code /api/growth/plan})新增草稿端点:
+ *       {@code POST /api/growth/plan/draft-save}(计划创建前可存草稿)、
+ *       {@code POST /api/growth/plan/draft-restore}(恢复继续)</li>
+ * </ul>
+ *
+ * <p><b>测试范围</b>:纯契约级单测,无 Spring 上下文 / 无 DB / 无外部服务;
+ * 仅 Mockito mock {@code GrowthPlanMapper} 注入真实 {@code GrowthPlanService}(仿
+ * {@code PlanLifecycleParentContractTest} 注入模式)。</p>
+ *
+ * <p><b>RED 预期</b>:宿主 {@code GrowthPlanService} 缺少草稿方法 / {@code growth_plans} 缺列 /
+ * {@code GrowthPlan} 缺字段 / 控制器缺草稿端点,全部用例红(断言原文前缀 {@code RED[plan.draft.save]})。</p>
+ */
+class PlanDraftSaveContractTest extends AssessmentPlanContractTestBase {
+
+    /** 规格设计宿主类(已存在,缺草稿方法)。 */
+    private static final String HOST_CLASS = "com.etotem.cfc.service.GrowthPlanService";
+
+    /** 控制器宿主类(已存在,缺草稿端点)。 */
+    private static final String CTRL_CLASS = "com.etotem.cfc.controller.growth.GrowthPlanController";
+
+    /** 草稿有效期默认 7 天(SC-P-81 边界:草稿有效期)。 */
+    private static final long DRAFT_VALIDITY_DAYS = 7L;
+    private static final long DRAFT_VALIDITY_MS = DRAFT_VALIDITY_DAYS * 24L * 3600_000L;
+
+    private GrowthPlanService host;
+    private GrowthPlanMapper growthPlanMapper;
+
+    @BeforeEach
+    void setUp() throws Exception {
+        host = new GrowthPlanService();
+        growthPlanMapper = mock(GrowthPlanMapper.class);
+        inject(host, "growthPlanMapper", growthPlanMapper);
+    }
+
+    // ==================== 正常流:存草稿 → 恢复继续 ====================
+
+    @Test
+    @DisplayName("正常流-1:存草稿 status=draft + 设置有效期 draftExpiresAt(未来)")
+    void saveDraft_persistsDraftStatusAndExpiry() {
+        GrowthPlan draft = draft(10L, 7L, "初步方案");
+        Object r = call(host, "saveDraft", draft);
+        GrowthPlan saved = (GrowthPlan) r;
+        assertEquals("draft", saved.getStatus(),
+                "[plan.draft.save] 存草稿应持久化 status=draft(暂存未完,TC-P-81 正常流)");
+        // 边界:草稿有效期(异常流『草稿已失效』的持久化基础)
+        Object expiresAt = getFieldValue(saved, "draftExpiresAt");
+        assertNotNull(expiresAt,
+                "[plan.draft.save] 草稿应含有效期 draftExpiresAt(SC-P-81 边界:草稿有效期)");
+        assertTrue(((Date) expiresAt).getTime() > System.currentTimeMillis() - 1000L,
+                "[plan.draft.save] 存草稿应设置 draftExpiresAt = now + 有效期(默认 7 天)");
+    }
+
+    @Test
+    @DisplayName("正常流-2:恢复草稿继续编辑(status=draft 返回可继续编辑的草稿)")
+    void restoreDraft_returnsDraftForEditing() {
+        // 已存草稿(含有效期),恢复后续编辑
+        when(growthPlanMapper.selectById(1L)).thenReturn(draft(10L, 7L, "已存草稿"));
+        Object r = call(host, "restoreDraft", 1L);
+        GrowthPlan restored = (GrowthPlan) r;
+        assertNotNull(restored, "[plan.draft.save] 恢复草稿应返回可继续编辑的草稿(TC-P-81 正常流)");
+        assertEquals("draft", restored.getStatus(),
+                "[plan.draft.save] 恢复的草稿应保持 status=draft(继续编辑,未发布)");
+    }
+
+    // ==================== 异常流:过期『草稿已失效』 + 并发后者覆盖且提示冲突 ====================
+
+    @Test
+    @DisplayName("异常流-1:过期草稿 → 判定已失效(恢复时提示『草稿已失效』)")
+    void expiredDraft_草稿已失效() {
+        GrowthPlan past = draft(10L, 7L, "过期草稿");
+        setField(past, "draftExpiresAt", new Date(System.currentTimeMillis() - 60_000L));
+        assertTrue(callBoolean(host, "isDraftExpired", past),
+                "[plan.draft.save] 超有效期的草稿应判定已失效,恢复时提示『草稿已失效』(TC-P-81-E)");
+
+        GrowthPlan future = draft(11L, 7L, "未过期草稿");
+        setField(future, "draftExpiresAt", new Date(System.currentTimeMillis() + DRAFT_VALIDITY_MS));
+        assertFalse(callBoolean(host, "isDraftExpired", future),
+                "[plan.draft.save] 有效期内草稿不应判定失效");
+    }
+
+    @Test
+    @DisplayName("异常流-2:并发存两版草稿 → 后者覆盖且提示冲突(版本检测)")
+    void concurrentSave_laterOverwrites_conflictPrompt() {
+        Object r = call(host, "isDraftVersionConflict", 1L, 1L);
+        assertTrue(r instanceof Boolean,
+                "[plan.draft.save] 契约方法 isDraftVersionConflict 应返回 Boolean(并发两版草稿:后者覆盖且提示冲突,TC-P-81-E)");
+    }
+
+    // ==================== 权限流:越权 403/401,不泄露他人草稿 ====================
+
+    @Test
+    @DisplayName("权限流-1:越权恢复他人草稿 → 403/401 拒绝,不泄露")
+    void restoreDraft_越权_403不泄露() {
+        Method m = findMethod(host, "restoreDraft", 2);
+        if (m == null) {
+            fail("RED[plan.draft.save] 权限流「越权恢复他人草稿 403/401 不泄露」:"
+                    + "契约方法 " + HOST_CLASS + "#restoreDraft(Long,Long) 未实现(TC-P-81-P)");
+        }
+        Object r = null;
+        try {
+            r = m.invoke(host, 1L, 999L);
+        } catch (InvocationTargetException e) {
+            String msg = e.getCause() != null && e.getCause().getMessage() != null
+                    ? e.getCause().getMessage() : "无提示";
+            assertTrue(msg.contains("无权限") || msg.contains("403") || msg.contains("401"),
+                    "[plan.draft.save] 越权恢复应以 403/401 拒绝(TC-P-81-P),实际提示:" + msg);
+            return;
+        } catch (Exception e) {
+            fail("[plan.draft.save] 越权恢复契约调用失败:" + e.getMessage());
+        }
+        // 未抛异常(实现选择返回式拒绝):不得返回他人草稿(不泄露数据)
+        assertNull(r, "[plan.draft.save] 越权恢复他人草稿必须无数据返回(不泄露他人草稿,TC-P-81-P)");
+    }
+
+    // ==================== 结构契约:schema.sql 草稿列 ====================
+
+    @Test
+    @DisplayName("结构-1:growth_plans 应含 draft_expires_at(草稿有效期)")
+    void schema_growthPlans_hasDraftExpiryColumn() {
+        String schema = readSchemaSql();
+        assertTrue(schema.contains("draft_expires_at"),
+                "[plan.draft.save] schema.sql 的 growth_plans 应含 draft_expires_at 列"
+                        + "(草稿有效期,『草稿已失效』判定的持久化基础,TC-P-81-E)");
+    }
+
+    @Test
+    @DisplayName("结构-2:growth_plans 应含 draft_version(并发两版草稿版本号)")
+    void schema_growthPlans_hasDraftVersionColumn() {
+        String schema = readSchemaSql();
+        assertTrue(schema.contains("draft_version"),
+                "[plan.draft.save] schema.sql 的 growth_plans 应含 draft_version 列"
+                        + "(并发存两版草稿:后者覆盖且提示冲突的版本基础,TC-P-81-E)");
+    }
+
+    // ==================== 结构契约:GrowthPlan 实体字段 ====================
+
+    @Test
+    @DisplayName("结构-3:GrowthPlan 实体应含 draftExpiresAt / draftVersion 字段")
+    void entity_growthPlan_hasDraftFields() {
+        GrowthPlan p = new GrowthPlan();
+        getFieldValue(p, "draftExpiresAt");
+        getFieldValue(p, "draftVersion");
+    }
+
+    // ==================== 结构契约:控制器草稿端点 ====================
+
+    @Test
+    @DisplayName("结构-4:GrowthPlanController 应提供草稿保存端点")
+    void controller_hasDraftSaveEndpoint() {
+        assertTrue(hasDraftMapping("save"),
+                "RED[plan.draft.save] GrowthPlanController(/api/growth/plan)应提供草稿保存端点"
+                        + "(如 POST /api/growth/plan/draft-save,计划创建前可存草稿,API_REFERENCE §4.6)");
+    }
+
+    @Test
+    @DisplayName("结构-5:GrowthPlanController 应提供草稿恢复端点")
+    void controller_hasDraftRestoreEndpoint() {
+        assertTrue(hasDraftMapping("restore"),
+                "RED[plan.draft.save] GrowthPlanController(/api/growth/plan)应提供草稿恢复端点"
+                        + "(如 POST /api/growth/plan/draft-restore,恢复继续编辑,TC-P-81 正常流)");
+    }
+
+    // ==================== 反射辅助(锚定宿主契约,避免编译期依赖不存在方法) ====================
+
+    private static GrowthPlan draft(Long memberId, Long teacherId, String title) {
+        GrowthPlan p = new GrowthPlan();
+        p.setMemberId(memberId);
+        p.setTeacherId(teacherId);
+        p.setPlanTitle(title);
+        p.setPlanContent("暂存方案内容");
+        p.setStatus("draft");
+        return p;
+    }
+
+    private Method findMethod(Object target, String name, int argc) {
+        for (Method m : target.getClass().getMethods()) {
+            if (m.getName().equals(name) && m.getParameterCount() == argc) {
+                return m;
+            }
+        }
+        return null;
+    }
+
+    /** 按方法名 + 参数个数匹配并调用,契约方法缺失即断言失败(红)。 */
+    private Object call(Object host, String method, Object... args) {
+        Method m = findMethod(host, method, args.length);
+        if (m == null) {
+            fail("RED[plan.draft.save] 契约方法 " + HOST_CLASS + "#" + method
+                    + " 未实现(SC-P-81 方案/任务草稿保存与恢复能力缺失)");
+            throw new IllegalStateException("unreachable");
+        }
+        try {
+            return m.invoke(host, args);
+        } catch (Exception e) {
+            fail("[plan.draft.save] 契约方法 " + HOST_CLASS + "#" + method + " 调用失败:" + e.getMessage());
+            throw new IllegalStateException("unreachable");
+        }
+    }
+
+    private boolean callBoolean(Object host, String method, Object... args) {
+        Object r = call(host, method, args);
+        if (r instanceof Boolean) {
+            return (Boolean) r;
+        }
+        fail("[plan.draft.save] 契约方法 " + method + " 应返回 Boolean,实际 " + r);
+        throw new IllegalStateException("unreachable");
+    }
+
+    /** 反射写实体字段;字段缺失即断言失败(红)—— 锚定 GrowthPlan 草稿字段契约。 */
+    private void setField(Object target, String name, Object value) {
+        try {
+            Field f = target.getClass().getDeclaredField(name);
+            f.setAccessible(true);
+            f.set(target, value);
+        } catch (NoSuchFieldException e) {
+            fail("RED[plan.draft.save] " + target.getClass().getSimpleName() + " 实体应含字段 "
+                    + name + "(SC-P-81 草稿有效期/版本契约)");
+            throw new IllegalStateException("unreachable");
+        } catch (IllegalAccessException e) {
+            fail("[plan.draft.save] 设置字段 " + name + " 失败:" + e.getMessage());
+            throw new IllegalStateException("unreachable");
+        }
+    }
+
+    /** 反射读实体字段;字段缺失即断言失败(红)。 */
+    private Object getFieldValue(Object target, String name) {
+        try {
+            Field f = target.getClass().getDeclaredField(name);
+            f.setAccessible(true);
+            return f.get(target);
+        } catch (NoSuchFieldException e) {
+            fail("RED[plan.draft.save] " + target.getClass().getSimpleName() + " 实体应含字段 "
+                    + name + "(SC-P-81 草稿有效期/版本契约)");
+            throw new IllegalStateException("unreachable");
+        } catch (IllegalAccessException e) {
+            fail("[plan.draft.save] 读取字段 " + name + " 失败:" + e.getMessage());
+            throw new IllegalStateException("unreachable");
+        }
+    }
+
+    /** 探测控制器是否存在草稿保存/恢复端点映射(@PostMapping/@RequestMapping 路径含 draft)。 */
+    private boolean hasDraftMapping(String kind) {
+        Class<?> ctrl = loadClass(CTRL_CLASS);
+        if (ctrl == null) {
+            return false;
+        }
+        for (Method m : ctrl.getDeclaredMethods()) {
+            for (Annotation a : m.getAnnotations()) {
+                try {
+                    Method vm = a.annotationType().getMethod("value");
+                    Object raw = vm.invoke(a);
+                    String[] paths = raw instanceof String[]
+                            ? (String[]) raw : new String[]{String.valueOf(raw)};
+                    for (String p : paths) {
+                        String lower = p.toLowerCase();
+                        String methodName = m.getName().toLowerCase();
+                        boolean isDraft = lower.contains("draft") || methodName.contains("draft");
+                        boolean kindMatch;
+                        if ("save".equals(kind)) {
+                            kindMatch = lower.contains("save") || methodName.contains("savedraft");
+                        } else {
+                            kindMatch = lower.contains("restore") || methodName.contains("restore");
+                        }
+                        if (isDraft && kindMatch) {
+                            return true;
+                        }
+                    }
+                } catch (Exception ignored) {
+                    // 非映射注解(无 value 属性)忽略
+                }
+            }
+        }
+        return false;
+    }
+
+    private Class<?> loadClass(String name) {
+        try {
+            return Class.forName(name, false, Thread.currentThread().getContextClassLoader());
+        } catch (ClassNotFoundException e) {
+            return null;
+        }
+    }
+
+    private String readSchemaSql() {
+        try (InputStream is = getClass().getClassLoader().getResourceAsStream("schema.sql")) {
+            if (is == null) {
+                return "";
+            }
+            try (Scanner scanner = new Scanner(is, StandardCharsets.UTF_8.name())) {
+                scanner.useDelimiter("\\A");
+                return scanner.hasNext() ? scanner.next() : "";
+            }
+        } catch (Exception e) {
+            return "";
+        }
+    }
+}