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

test(RED): S-cfc-262 task.frequency.config 任务频率/周期配置 契约级单测 11例全红

Sisyphus Agent 5 дней назад
Родитель
Сommit
738aa8a1ae

+ 419 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/TaskFrequencyConfigContractTest.java

@@ -0,0 +1,419 @@
+package com.etotem.cfc.unit;
+
+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.core.conditions.Wrapper;
+import com.baomidou.mybatisplus.core.metadata.TableInfoHelper;
+import com.etotem.cfc.dto.CreateTaskDTO;
+import com.etotem.cfc.entity.FamilyMember;
+import com.etotem.cfc.entity.Task;
+import com.etotem.cfc.entity.User;
+import com.etotem.cfc.mapper.FamilyMemberMapper;
+import com.etotem.cfc.mapper.MiniGameMapper;
+import com.etotem.cfc.mapper.SurveyTemplateMapper;
+import com.etotem.cfc.mapper.TaskMapper;
+import com.etotem.cfc.service.TaskService;
+import com.etotem.cfc.service.UserService;
+import org.apache.ibatis.builder.MapperBuilderAssistant;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.springframework.web.bind.annotation.PostMapping;
+
+import java.io.InputStream;
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Date;
+import java.util.List;
+import java.util.Scanner;
+
+import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
+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;
+
+/**
+ * 契约级单测:任务频率/周期配置(能力键 {@code task.frequency.config},TDD-RED 阶段)。
+ *
+ * <p>契约来源(需求 SC-P-12 + 设计 API_REFERENCE §4.3):
+ * <blockquote>
+ *   SC-P-12 · 任务频率/周期配置 — 设<b>日/周/自定义周期</b>;流程:配频率 →
+ *   按周期自动生成实例;边界:<b>周期计算跨月/跨年正确</b>;<b>暂停/恢复</b>。模块:{@code TaskController}。
+ *   API_REFERENCE §4.3 — {@code POST /api/tasks/create} 以 {@code actionType}+{@code actionConfig}
+ *   声明任务配置;{@code POST /api/tasks/{id}/start} 为两阶段入口。
+ * </blockquote></p>
+ *
+ * <p><b>实现现状</b>(本分支 src/main 核实):
+ * <ul>
+ *   <li>{@code TaskService.VALID_FREQUENCIES} = {none, daily, weekly, monthly, every_other_day, hourly},
+ *       不含自定义周期(任意 N 天),{@code createTask} 会以「任务频率不合法」拒绝自定义周期请求;</li>
+ *   <li>{@code RepeatTaskGenerator} 仅按 fixed 日匹配生成 hourly/daily/every_other_day/weekly/monthly 实例,
+ *       无自定义周期(every N 天)生成分支,也无跨月/跨年的周期推进计算;</li>
+ *   <li>{@code Task} 实体无周期配置字段(周期单位/间隔/锚点),无暂停标记;</li>
+ *   <li>{@code TaskService} 无 pause/resume 方法;{@code TaskController} 无
+ *       pause/resume 端点;schema.sql {@code tasks} 表 {@code status} 枚举无 paused,无周期列。</li>
+ * </ul>
+ * 因此本测试以「反射结构契约 + 既有 createTask 行为探测」断言契约所需结构缺失(红),
+ * 失败断言原文清晰可贴;GREEN 阶段实现后自动转绿。</p>
+ *
+ * <p><b>GREEN 升级指引</b>:实现者(1)在任务创建侧支持自定义周期频率(如 frequency=custom +
+ * actionConfig 携带周期单位/间隔,或独立字段),(2) 在 {@code RepeatTaskGenerator} 增加自定义周期
+ * 生成分支并按周期锚点推进(跨月/跨年正确),(3) 为模板任务落地暂停标记与 {@code TaskService.pauseTask /
+ * resumeTask} 及 {@code TaskController} pause/resume 端点,(4) 同步 schema.sql 后本测试自动转绿。</p>
+ */
+class TaskFrequencyConfigContractTest {
+
+    /** 契约要求的最小自定义周期取值(SC-P-12「自定义周期」) */
+    private static final String CUSTOM_FREQUENCY = "custom";
+
+    /** Task 实体应承载的自定义周期配置字段候选(周期单位/间隔/锚点) */
+    private static final String[] PERIOD_FIELDS = {
+            "frequencyInterval", "frequencyUnit", "periodDays", "cycleDays", "cycleAnchor", "periodStartDate"
+    };
+
+    /** Task 实体应承载的暂停标记字段候选 */
+    private static final String[] PAUSE_FIELDS = {"isPaused", "paused", "pauseStatus"};
+
+    /** RepeatTaskGenerator 自定义周期生成入口的方法名片段(按周期 N 天推进) */
+    private static final String[] CUSTOM_GEN_METHOD_FRAGMENTS = {"custom", "interval", "period"};
+
+    /** RepeatTaskGenerator 跨月/跨年周期推进计算方法名片段 */
+    private static final String[] CYCLE_ADVANCE_FRAGMENTS = {"next", "cycle", "advance", "occurrence", "compute"};
+
+    /** RepeatTaskGenerator 当前已存在方法——探测时排除,防误报绿 */
+    private static final List<String> KNOWN_GENERATOR_METHODS = Arrays.asList(
+            "generateDailyTasks", "isEveryOtherDay", "hasTaskForDate",
+            "createTaskFromTemplate", "startOfDay");
+
+    private static final String REPEAT_GENERATOR = "com.etotem.cfc.task.RepeatTaskGenerator";
+    private static final String TASK_SERVICE = "com.etotem.cfc.service.TaskService";
+    private static final String TASK_CONTROLLER = "com.etotem.cfc.controller.task.TaskController";
+
+    // ------------------------------------------------------------------
+    // Mockito 行为探测基建(复用同批 TaskFrequencyScP12ContractTest 风格)
+    // ------------------------------------------------------------------
+
+    private TaskService service;
+    private UserService userService;
+    private FamilyMemberMapper familyMemberMapper;
+    private TaskMapper taskMapper;
+    private final List<Task> insertedTasks = new ArrayList<>();
+    private long idSeq = 9000L;
+
+    @BeforeAll
+    static void initMybatisPlusTableInfo() {
+        TableInfoHelper.initTableInfo(
+                new MapperBuilderAssistant(new MybatisConfiguration(), ""), FamilyMember.class);
+    }
+
+    @BeforeEach
+    void setUp() throws Exception {
+        service = new TaskService();
+        userService = mock(UserService.class);
+        familyMemberMapper = mock(FamilyMemberMapper.class);
+        taskMapper = mock(TaskMapper.class);
+        inject(service, "userService", userService);
+        inject(service, "familyMemberMapper", familyMemberMapper);
+        inject(service, "taskMapper", taskMapper);
+        inject(service, "miniGameMapper", mock(MiniGameMapper.class));
+        inject(service, "surveyTemplateMapper", mock(SurveyTemplateMapper.class));
+
+        User user = new User();
+        user.setId(1L);
+        user.setFamilyId(1L);
+        when(userService.getUserInfo(any())).thenReturn(user);
+        when(familyMemberMapper.selectCount(any(Wrapper.class))).thenReturn(1L);
+        when(taskMapper.insert(any(Task.class))).thenAnswer(inv -> {
+            Task t = inv.getArgument(0);
+            if (t.getId() == null) t.setId(++idSeq);
+            t.setCreatedAt(new Date());
+            insertedTasks.add(t);
+            return 1;
+        });
+        when(taskMapper.selectList(any(Wrapper.class))).thenReturn(new ArrayList<>());
+    }
+
+    private static void inject(Object target, String field, Object value) throws Exception {
+        Field f = target.getClass().getDeclaredField(field);
+        f.setAccessible(true);
+        f.set(target, value);
+    }
+
+    private CreateTaskDTO customPeriodDto() {
+        CreateTaskDTO dto = new CreateTaskDTO();
+        dto.setTitle("自定义周期任务");
+        dto.setPoints(5);
+        dto.setMemberId(100L);
+        dto.setFrequency(CUSTOM_FREQUENCY);
+        // §4.3:actionType + actionConfig 声明任务配置 —— 自定义周期频率,周期单位+间隔放 actionConfig
+        dto.setActionType("none");
+        dto.setActionConfig("{\"periodUnit\":\"DAY\",\"periodInterval\":3}");
+        dto.setExecutorType("child");
+        dto.setNeedReview(0);
+        return dto;
+    }
+
+    // ------------------------------------------------------------------
+    // 正常流:创建侧应支持「自定义周期」频率(SC-P-12 日/周/自定义周期)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-1:Task 实体应承载自定义周期配置字段(周期单位/间隔/锚点)")
+    void taskEntity_hasCustomPeriodConfigField() {
+        Class<?> clazz = loadClass("com.etotem.cfc.entity.Task");
+        assertNotNull(clazz, "[task.frequency.config] Task 实体不存在。");
+        List<String> fieldNames = new ArrayList<>();
+        for (Field f : clazz.getDeclaredFields()) {
+            fieldNames.add(f.getName());
+        }
+        boolean found = false;
+        for (String candidate : PERIOD_FIELDS) {
+            if (fieldNames.contains(candidate)) { found = true; break; }
+        }
+        assertTrue(found,
+                "[task.frequency.config] Task 实体应承载自定义周期配置字段(周期单位/间隔/锚点,"
+                        + "候选 " + Arrays.toString(PERIOD_FIELDS) + "),当前字段=" + fieldNames
+                        + ":SC-P-12 要求「设日/周/自定义周期→按周期自动生成实例」,自定义周期(任意 N 天)"
+                        + "必须持久化周期间隔与锚点。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("正常流-2:createTask 应接受自定义周期频率(不抛「任务频率不合法」)")
+    void createTask_acceptsCustomPeriodFrequency() {
+        assertDoesNotThrow(() -> service.createTask(1L, customPeriodDto()),
+                "[task.frequency.config] createTask 应按契约接受自定义周期频率 'custom'(§4.3 "
+                        + "actionConfig 声明周期配置),当前 VALID_FREQUENCIES 不含自定义周期,抛「任务频率不合法」"
+                        + "(src/main TaskService 核实)。SC-P-12 要求配频率即可创建。实现未落地。");
+        assertEquals(CUSTOM_FREQUENCY,
+                insertedTasks.isEmpty() ? null : insertedTasks.get(0).getFrequency(),
+                "[task.frequency.config] 自定义周期频率应落库。");
+    }
+
+    // ------------------------------------------------------------------
+    // 正常流:RepeatTaskGenerator 应有「按周期自动生成实例」的自定义周期分支
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-3:RepeatTaskGenerator 应有自定义周期生成入口(every N 天)")
+    void repeatGenerator_hasCustomPeriodEntry() {
+        Class<?> clazz = loadClass(REPEAT_GENERATOR);
+        assertNotNull(clazz, "[task.frequency.config] RepeatTaskGenerator 类不存在。");
+        StringBuilder methods = new StringBuilder();
+        boolean found = false;
+        for (Method m : declaredMethods(clazz)) {
+            methods.append(m.getName()).append(' ');
+            String name = m.getName().toLowerCase();
+            if (!KNOWN_GENERATOR_METHODS.contains(m.getName())
+                    && containsAny(name, CUSTOM_GEN_METHOD_FRAGMENTS)) {
+                found = true;
+            }
+        }
+        assertTrue(found,
+                "[task.frequency.config] RepeatTaskGenerator 缺少自定义周期(every N 天)生成入口,"
+                        + "现有方法=" + methods + ":SC-P-12「按周期自动生成实例」,自定义周期须有独立生成分支"
+                        + "(方法名片段候选 " + Arrays.toString(CUSTOM_GEN_METHOD_FRAGMENTS) + "),"
+                        + "当前仅 fixed 日匹配(daily/every_other_day/weekly/monthly/hourly)。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("正常流-4:RepeatTaskGenerator 应有跨月/跨年的周期推进计算")
+    void repeatGenerator_hasCycleAdvanceMath() {
+        Class<?> clazz = loadClass(REPEAT_GENERATOR);
+        assertNotNull(clazz, "[task.frequency.config] RepeatTaskGenerator 类不存在。");
+        StringBuilder methods = new StringBuilder();
+        boolean found = false;
+        for (Method m : declaredMethods(clazz)) {
+            methods.append(m.getName()).append(' ');
+            String name = m.getName().toLowerCase();
+            if (!KNOWN_GENERATOR_METHODS.contains(m.getName())
+                    && containsAny(name, CYCLE_ADVANCE_FRAGMENTS)) {
+                found = true;
+            }
+        }
+        assertTrue(found,
+                "[task.frequency.config] RepeatTaskGenerator 缺少跨月/跨年的周期推进计算方法"
+                        + "(方法名片段候选 " + Arrays.toString(CYCLE_ADVANCE_FRAGMENTS) + "),现有方法=" + methods
+                        + ":SC-P-12 边界「周期计算跨月/跨年正确」,自定义周期(如每 3 天)推进必须按周期锚点"
+                        + "逐周期计算(跨月/跨年不漂移),当前仅按当天固定匹配。实现未落地。");
+    }
+
+    // ------------------------------------------------------------------
+    // 边界流:暂停标记 + 周期配置落地(SC-P-12 暂停/恢复、跨月/跨年)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("边界流-1:Task 实体应有暂停标记(暂停后不生成实例)")
+    void taskEntity_hasPauseFlag() {
+        Class<?> clazz = loadClass("com.etotem.cfc.entity.Task");
+        assertNotNull(clazz, "[task.frequency.config] Task 实体不存在。");
+        List<String> fieldNames = new ArrayList<>();
+        for (Field f : clazz.getDeclaredFields()) {
+            fieldNames.add(f.getName());
+        }
+        boolean found = false;
+        for (String candidate : PAUSE_FIELDS) {
+            if (fieldNames.contains(candidate)) { found = true; break; }
+        }
+        assertTrue(found,
+                "[task.frequency.config] Task 实体缺少暂停标记字段(候选 " + Arrays.toString(PAUSE_FIELDS)
+                        + "),当前字段=" + fieldNames + ":SC-P-12 边界「暂停/恢复」要求暂停的重复任务模板"
+                        + "不再生成实例,需持久化暂停标记。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("边界流-2:schema.sql tasks 表应承载周期配置与暂停标记列(跨月/跨年、暂停/恢复)")
+    void schemaSql_carriesPeriodAndPauseColumns() {
+        String schema = readSchemaSql();
+        String tasksDdl = extractTableDdl(schema, "CREATE TABLE IF NOT EXISTS tasks");
+        boolean hasPeriodCol = containsAny(tasksDdl, "frequency_interval", "cycle_days", "cycle_anchor", "period_start");
+        boolean hasPauseCol = containsAny(tasksDdl, "is_paused", "pause_status");
+        assertTrue(hasPeriodCol || hasPauseCol,
+                "[task.frequency.config] schema.sql tasks 表缺少自定义周期列(frequency_interval/cycle_days/"
+                        + "cycle_anchor/period_start)或暂停标记列(is_paused/pause_status):SC-P-12 周期配置"
+                        + "(跨月/跨年)与暂停/恢复状态必须可落库。实现未落地。");
+    }
+
+    // ------------------------------------------------------------------
+    // 暂停/恢复:TaskService + TaskController(SC-P-12 暂停/恢复,模块 TaskController)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("暂停/恢复-1:TaskService 应提供 pauseTask 方法")
+    void taskService_hasPauseMethod() {
+        assertMethodExists(TASK_SERVICE, "pause",
+                "[task.frequency.config] TaskService 缺少 pauseTask 方法:SC-P-12「暂停/恢复」要求"
+                        + "暂停后可停止周期实例生成。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("暂停/恢复-2:TaskService 应提供 resumeTask 方法")
+    void taskService_hasResumeMethod() {
+        assertMethodExists(TASK_SERVICE, "resume",
+                "[task.frequency.config] TaskService 缺少 resumeTask 方法:SC-P-12「暂停/恢复」要求"
+                        + "恢复后按原周期继续生成实例。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("暂停/恢复-3:TaskController 应暴露 POST /api/tasks/{id}/pause 端点")
+    void taskController_exposesPauseEndpoint() {
+        assertEndpointExists(TASK_CONTROLLER, "pause",
+                "[task.frequency.config] TaskController 缺少 pause 端点(POST /api/tasks/{id}/pause):"
+                        + "SC-P-12 模块为 TaskController,暂停/恢复须经控制器暴露。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("暂停/恢复-4:TaskController 应暴露 POST /api/tasks/{id}/resume 端点")
+    void taskController_exposesResumeEndpoint() {
+        assertEndpointExists(TASK_CONTROLLER, "resume",
+                "[task.frequency.config] TaskController 缺少 resume 端点(POST /api/tasks/{id}/resume):"
+                        + "SC-P-12 模块为 TaskController,暂停/恢复须经控制器暴露。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("边界流-3:tasks.status 应可表达暂停态(枚举值或独立列)")
+    void schemaSql_statusCanExpressPaused() {
+        String schema = readSchemaSql();
+        String tasksDdl = extractTableDdl(schema, "CREATE TABLE IF NOT EXISTS tasks");
+        assertTrue(tasksDdl.contains("paused")
+                        || tasksDdl.contains("is_paused")
+                        || tasksDdl.contains("pause_status"),
+                "[task.frequency.config] schema.sql tasks 表状态(status ENUM 或独立列)无 paused 表达:"
+                        + "SC-P-12 「暂停/恢复」要求暂停态可持久化、可查询、可恢复。实现未落地。");
+    }
+
+    // ------------------------------------------------------------------
+    // 权限流(说明):暂停/恢复按 §4.3 为任务管理能力,走统一 JWT 登录态,
+    // 与同批其它契约一致以说明性用例标注,不产生独立断言失败。
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("权限流:暂停/恢复为后端任务管理能力,走统一 JWT 登录态(说明性)")
+    void permissionFlow_loggedInViaJwt() {
+        // 契约 AC 为「配频率→按周期生成实例」+「暂停/恢复」;暂停/恢复动作发生在已登录家庭上下文,
+        // 沿用 /api/** 统一 JwtInterceptor(8 个公开路径除外)。本能力无新增权限维度,说明性标注。
+        assertTrue(true, "权限流说明:task.frequency.config 复用统一 JWT 登录态,无新增权限维度。");
+    }
+
+    // ------------------------------------------------------------------
+    // 反射辅助
+    // ------------------------------------------------------------------
+
+    private void assertMethodExists(String fqcn, String fragment, String msg) {
+        Class<?> clazz = loadClass(fqcn);
+        assertNotNull(clazz, "[task.frequency.config] 类不存在: " + fqcn);
+        boolean found = false;
+        for (Method m : declaredMethods(clazz)) {
+            if (m.getName().toLowerCase().contains(fragment)) { found = true; break; }
+        }
+        assertTrue(found, msg);
+    }
+
+    private void assertEndpointExists(String fqcn, String fragment, String msg) {
+        Class<?> clazz = loadClass(fqcn);
+        assertNotNull(clazz, "[task.frequency.config] 类不存在: " + fqcn);
+        boolean found = false;
+        for (Method m : declaredMethods(clazz)) {
+            PostMapping ann = m.getAnnotation(PostMapping.class);
+            if (ann == null) continue;
+            String path = ann.value().length > 0 ? ann.value()[0] : "";
+            if (path.toLowerCase().contains(fragment)) { found = true; break; }
+        }
+        assertTrue(found, msg);
+    }
+
+    private static Method[] declaredMethods(Class<?> clazz) {
+        List<Method> list = new ArrayList<>();
+        Class<?> current = clazz;
+        while (current != null && current != Object.class) {
+            list.addAll(Arrays.asList(current.getDeclaredMethods()));
+            current = current.getSuperclass();
+        }
+        return list.toArray(new Method[0]);
+    }
+
+    private static boolean containsAny(String haystack, String... needles) {
+        if (haystack == null) return false;
+        String lower = haystack.toLowerCase();
+        for (String n : needles) {
+            if (lower.contains(n.toLowerCase())) return true;
+        }
+        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 "";
+        }
+    }
+
+    private String extractTableDdl(String schema, String tableMarker) {
+        int start = schema.indexOf(tableMarker);
+        if (start < 0) {
+            return "";
+        }
+        int end = schema.indexOf(") ENGINE", start);
+        return end < 0 ? schema.substring(start) : schema.substring(start, end);
+    }
+}