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

feat(task): completeTask 时间窗守卫 — earliest_start/latest_end 窗口外拒绝提交

产品规则:设置时间窗的任务只能在窗内提交完成/提交审核,窗口外需
提示用户。未到 earliest_start → 「未到开始时间,HH:mm 后可提交」;
已过 latest_end → 「已过截止时间 HH:mm,无法提交」。窗口为闭区间,
边界时刻(等于 earliest/latest)可提交;deadline 逾期零奖励机制独立
不受影响。TDD:TaskTimeWindowGuardContractTest RED 3 失败 → GREEN 4/4,
Task* 回归 175 条仅存 flaky/存量 1 失败(基线对比确认)。
Xiaogang Liao 2 часов назад
Родитель
Сommit
e36e28089f

+ 11 - 0
cfc-backend/src/main/java/com/etotem/cfc/service/TaskService.java

@@ -825,6 +825,17 @@ public List<Task> getTodayTasks(Long memberId, String dimensionCode) {
             return null;
         }
 
+        // 时间窗守卫(earliest_start / latest_end 闭区间):窗口外既不能直接完成,也不能提交审核
+        // 未到 earliest_start → 提示「未到开始时间」;已过 latest_end → 提示「已过截止时间」。
+        // deadline(逾期零奖励)是另一套机制,二者独立。窗口边界时刻(等于 earliest/latest)视为可提交。
+        java.text.SimpleDateFormat twFmt = new java.text.SimpleDateFormat("HH:mm");
+        if (task.getEarliestStart() != null && now.before(task.getEarliestStart())) {
+            throw new IllegalArgumentException("未到开始时间," + twFmt.format(task.getEarliestStart()) + " 后可提交");
+        }
+        if (task.getLatestEnd() != null && now.after(task.getLatestEnd())) {
+            throw new IllegalArgumentException("已过截止时间 " + twFmt.format(task.getLatestEnd()) + ",无法提交");
+        }
+
         // 需审核的任务:提交后进入待审核,审核通过后再发放积分
         if (task.getNeedReview() != null && task.getNeedReview() == 1) {
             return submitTaskForReview(task, memberId, now, content, contentType);

+ 206 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/TaskTimeWindowGuardContractTest.java

@@ -0,0 +1,206 @@
+package com.etotem.cfc.unit;
+
+import com.etotem.cfc.entity.FamilyMember;
+import com.etotem.cfc.entity.PointsLog;
+import com.etotem.cfc.entity.Task;
+import com.etotem.cfc.entity.TaskExecution;
+import com.etotem.cfc.mapper.FamilyMemberMapper;
+import com.etotem.cfc.mapper.PointsLogMapper;
+import com.etotem.cfc.mapper.TaskExecutionMapper;
+import com.etotem.cfc.mapper.TaskMapper;
+import com.etotem.cfc.service.CfPathwayEarnService;
+import com.etotem.cfc.service.EnergyService;
+import com.etotem.cfc.service.NotificationDispatchService;
+import com.etotem.cfc.service.StreakService;
+import com.etotem.cfc.service.TaskReminderConfigService;
+import com.etotem.cfc.service.TaskService;
+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.text.SimpleDateFormat;
+import java.util.Date;
+import java.util.HashMap;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+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.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * 时间窗任务(earliest_start / latest_end)提交门禁契约测试。
+ *
+ * <p><b>契约锚点</b></p>
+ * <ul>
+ *   <li>产品规则:设置了执行时间窗的任务,只能在窗口内提交完成/提交审核;
+ *       未到 earliest_start 提示「未到开始时间」,已过 latest_end 提示「已过截止时间」。</li>
+ *   <li>接口:{@code POST /api/tasks/{id}/complete} → {@link TaskService#completeTask}</li>
+ * </ul>
+ *
+ * <p><b>RED 预期(TDD-RED)</b>:现状 {@code completeTask} 对 earliest_start/latest_end
+ * 没有任何校验,窗口外提交会照常完成/进入待审核并发奖;以下前 3 条用例断言失败(红),
+ * GREEN 阶段在 need_review 分支前补时间窗守卫后转绿。第 4 条为控制组(现状即绿),
+ * 用于防止修复后误伤窗口内正常完成。</p>
+ */
+class TaskTimeWindowGuardContractTest {
+
+    private TaskService service;
+    private TaskMapper taskMapper;
+    private FamilyMemberMapper familyMemberMapper;
+    private PointsLogMapper pointsLogMapper;
+    private TaskExecutionMapper taskExecutionMapper;
+    private StreakService streakService;
+
+    private static final long HOUR = 3_600_000L;
+
+    @BeforeEach
+    void setUp() throws Exception {
+        service = new TaskService();
+        taskMapper = mock(TaskMapper.class);
+        familyMemberMapper = mock(FamilyMemberMapper.class);
+        pointsLogMapper = mock(PointsLogMapper.class);
+        taskExecutionMapper = mock(TaskExecutionMapper.class);
+        streakService = mock(StreakService.class);
+
+        inject(service, "taskMapper", taskMapper);
+        inject(service, "familyMemberMapper", familyMemberMapper);
+        inject(service, "pointsLogMapper", pointsLogMapper);
+        inject(service, "taskExecutionMapper", taskExecutionMapper);
+        inject(service, "streakService", streakService);
+        inject(service, "energyService", mock(EnergyService.class));
+        inject(service, "cfPathwayEarnService", mock(CfPathwayEarnService.class));
+        TaskReminderConfigService taskReminderConfigService = mock(TaskReminderConfigService.class);
+        inject(service, "taskReminderConfigService", taskReminderConfigService);
+        inject(service, "notificationDispatchService", mock(NotificationDispatchService.class));
+
+        when(taskReminderConfigService.loadAllConfigs()).thenReturn(new HashMap<>());
+        when(streakService.checkAndAwardMilestone(anyLong(), anyInt())).thenReturn(0);
+    }
+
+    @Test
+    @DisplayName("时间窗-1:未到 earliest_start 提交 → 拒绝并提示未到开始时间(含 HH:mm)")
+    void 未到开始时间_拒绝提交() {
+        Date start = new Date(System.currentTimeMillis() + HOUR);
+        Date end = new Date(System.currentTimeMillis() + 5 * HOUR);
+        Task t = task(21L, 100L, "pending", 0);
+        t.setEarliestStart(start);
+        t.setLatestEnd(end);
+        when(taskMapper.selectById(21L)).thenReturn(t);
+        when(familyMemberMapper.selectById(100L)).thenReturn(member(100L, 20));
+
+        IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
+                () -> service.completeTask(21L, 100L, null, null, null));
+
+        assertTrue(ex.getMessage() != null && ex.getMessage().contains("未到开始时间"),
+                "应提示未到开始时间,实际: " + ex.getMessage());
+        String expectHm = new SimpleDateFormat("HH:mm").format(start);
+        assertTrue(ex.getMessage().contains(expectHm),
+                "提示应含具体开始时间 " + expectHm + ",实际: " + ex.getMessage());
+        assertEquals("pending", t.getStatus(), "被拒时任务状态不应改变");
+        verify(taskMapper, never()).updateById(any(Task.class));
+        verify(pointsLogMapper, never()).insert(any(PointsLog.class));
+    }
+
+    @Test
+    @DisplayName("时间窗-2:已过 latest_end 提交 → 拒绝并提示已过截止时间(含 HH:mm)")
+    void 已过截止时间_拒绝提交() {
+        Date start = new Date(System.currentTimeMillis() - 3 * HOUR);
+        Date end = new Date(System.currentTimeMillis() - HOUR);
+        Task t = task(22L, 100L, "pending", 0);
+        t.setEarliestStart(start);
+        t.setLatestEnd(end);
+        when(taskMapper.selectById(22L)).thenReturn(t);
+        when(familyMemberMapper.selectById(100L)).thenReturn(member(100L, 20));
+
+        IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
+                () -> service.completeTask(22L, 100L, null, null, null));
+
+        assertTrue(ex.getMessage() != null && ex.getMessage().contains("已过截止时间"),
+                "应提示已过截止时间,实际: " + ex.getMessage());
+        String expectHm = new SimpleDateFormat("HH:mm").format(end);
+        assertTrue(ex.getMessage().contains(expectHm),
+                "提示应含具体截止时间 " + expectHm + ",实际: " + ex.getMessage());
+        assertEquals("pending", t.getStatus(), "被拒时任务状态不应改变");
+        verify(pointsLogMapper, never()).insert(any(PointsLog.class));
+    }
+
+    @Test
+    @DisplayName("时间窗-3:需审核任务窗口外提交 → 同样被拒,不进入待审核")
+    void 需审核任务窗口外_拒绝提交() {
+        Date start = new Date(System.currentTimeMillis() + HOUR);
+        Date end = new Date(System.currentTimeMillis() + 5 * HOUR);
+        Task t = task(23L, 100L, "pending", 1);
+        t.setEarliestStart(start);
+        t.setLatestEnd(end);
+        when(taskMapper.selectById(23L)).thenReturn(t);
+        when(familyMemberMapper.selectById(100L)).thenReturn(member(100L, 20));
+
+        IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
+                () -> service.completeTask(23L, 100L, null, "内容", "text"));
+
+        assertTrue(ex.getMessage() != null && ex.getMessage().contains("未到开始时间"),
+                "需审核任务窗口外也应提示未到开始时间,实际: " + ex.getMessage());
+        assertEquals("pending", t.getStatus(), "被拒时不应流转到 pending_review");
+        verify(taskExecutionMapper, never()).insert(any(TaskExecution.class));
+    }
+
+    @Test
+    @DisplayName("时间窗-4(控制组):窗口内提交 → 正常完成并发奖")
+    void 窗口内_正常完成() {
+        Date start = new Date(System.currentTimeMillis() - HOUR);
+        Date end = new Date(System.currentTimeMillis() + HOUR);
+        Task t = task(24L, 100L, "pending", 0);
+        t.setEarliestStart(start);
+        t.setLatestEnd(end);
+        t.setDeadline(new Date(System.currentTimeMillis() + 2 * HOUR));
+        when(taskMapper.selectById(24L)).thenReturn(t);
+        when(familyMemberMapper.selectById(100L)).thenReturn(member(100L, 20));
+
+        Map<String, Object> result = service.completeTask(24L, 100L, null, null, null);
+
+        assertEquals("completed", t.getStatus(), "窗口内应正常完成");
+        assertEquals(11, result.get("pointsEarned"), "窗口内完成应正常发奖(10+提前1)");
+        assertEquals(Boolean.FALSE, result.get("needReview"));
+    }
+
+    // ==================== helpers ====================
+
+    private Task task(Long id, Long memberId, String status, Integer needReview) {
+        Task t = new Task();
+        t.setId(id);
+        t.setFamilyId(1L);
+        t.setFamilyMemberId(memberId);
+        t.setTitle("下午阅读半小时");
+        t.setPoints(10);
+        t.setStatus(status);
+        t.setNeedReview(needReview);
+        t.setReviewByCategory(0);
+        t.setCategory("阅读任务");
+        t.setCreatedAt(new Date());
+        return t;
+    }
+
+    private FamilyMember member(Long id, Integer totalPoints) {
+        FamilyMember m = new FamilyMember();
+        m.setId(id);
+        m.setUserId(1L);
+        m.setTotalPoints(totalPoints);
+        m.setPenaltyEnabled(0);
+        m.setStreakDays(0);
+        return m;
+    }
+
+    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);
+    }
+}