Sfoglia il codice sorgente

docs(tdd): 任务日提醒(早晚两次)设计契约 v1.0——独立开关可叠加/默认07:30+21:00/仅今日到期晚总结/固定cron逐用户判断

Agnes Agent 5 giorni fa
parent
commit
c56ea68ab

+ 121 - 0
docs/tdd/orchestration/task-daily-reminder-design-2026-11-14.md

@@ -0,0 +1,121 @@
+# 任务日提醒(早晚两次)设计契约
+
+> 版本:v1.0(2026-11-14,主理人定稿,4 项设计点已拍板)
+> 状态:已裁决待开发
+> 关联能力键:`task.reminder.daily`(新增,本次实现)
+> 关联 SC:`tests/user-scenarios/应用场景总览.md` SC-P-65(消息通知/提醒设置)、SC-P-79(推送/通知开关设置);业务域 H(设置与通知)
+
+---
+
+## 一、需求背景
+
+现有任务提醒规则有两种(`task_reminder_config.timing_mode` 二选一):
+1. `before_deadline`:任务截止前 offset 分钟提醒
+2. `after_timeout`:任务超时后 offset 分钟提醒
+
+本次新增**第三种提醒类型:日提醒**,与现有两档**独立开关、可叠加**:
+- **早上提醒**(默认 07:30,可配):提醒用户全天关注内容——今日到期 + 已逾期仍未打卡的任务清单
+- **晚上总结**(默认 21:00,可配):对今日到期任务做全天总结——已完成(用户已点完成)/ 未完成分组,催未点完成的用户补打卡
+
+## 二、设计决策(已拍板)
+
+| # | 决策点 | 结论 |
+|---|--------|------|
+| 1 | 形态 | **独立开关可叠加**:`daily_enabled` 独立于 `enabled`,与 before/after 互不影响,可同时开启 |
+| 2 | 时间 | **用户可配**早晚时间(`morning_time`/`evening_time`,HH:mm),**默认 07:30 / 21:00** |
+| 3 | 早提醒范围 | 今日到期(pending 未打卡)+ 已逾期未打卡(宽限内,复用 OVERDUE_GRACE_DAYS=3 口径)→ 全天关注 |
+| 4 | 晚总结范围 | **仅今日到期**任务:今日已完成(completedAt 今日)列「已完成」;今日到期未打卡列「未完成」并催补打卡。历史逾期不进晚总结(由超期提醒兜底) |
+| 5 | 收件人 | 沿用现有口径:`executorType=parent` 执行型任务的执行人(家庭主账号) |
+| 6 | 调度实现 | **固定 cron 逐用户判断**:morning/evening 两个 @Scheduled 方法(默认 07:30/21:00),按用户配置时间判断当日是否已触发,靠 `user_notifications` 判重保证每日一次 |
+
+## 三、实现改动
+
+### 3.1 数据库迁移(DatabaseInitializer + schema.sql 同步)
+
+`task_reminder_config` 表新增 3 列(迁移编号取当前最新 +1;用 `ensureColumn` 幂等):
+
+| 列 | 类型 | 默认值 | 说明 |
+|----|------|--------|------|
+| `daily_enabled` | TINYINT | 0 | 日提醒开关 1=启用 0=停用(独立于 enabled) |
+| `morning_time` | VARCHAR(5) | '07:30' | 早提醒时间 HH:mm(用户可配) |
+| `evening_time` | VARCHAR(5) | '21:00' | 晚总结时间 HH:mm(用户可配) |
+
+- schema.sql 的 `CREATE TABLE task_reminder_config` 同步补 3 列
+- DatabaseInitializer 的 CREATE TABLE 也同步(如该表由迁移 353 在代码里创建,需核对并保持两处一致)
+
+### 3.2 实体/DTO(`TaskReminderConfig` / `TaskReminderConfigDTO`)
+
+新增字段:
+- `Integer dailyEnabled`
+- `String morningTime`
+- `String eveningTime`
+
+### 3.3 配置服务(`TaskReminderConfigService`)
+
+- `getConfig`:未配置时默认 `dailyEnabled=0, morningTime="07:30", eveningTime="21:00"`;已配置按实体读取
+- `saveConfig` 新增校验:
+  - `dailyEnabled` ∈ {0, 1}(null 视为 0)
+  - `morningTime`/`eveningTime` 必须匹配 `HH:mm` 正则 `^([01]\d|2[0-3]):[0-5]\d$`,否则 `IllegalArgumentException("提醒时间格式不合法")`
+- 不改变现有 `timing_mode` 二选一逻辑(日提醒是独立维度)
+
+### 3.4 调度器(新增方法到 `TaskCheckinWebhookReminderTask` 或新建 `TaskDailyReminderScheduledTask`,推荐后者保持职责单一)
+
+**统一口径**(复用现有查询骨架):
+- 扫描:`is_template=0 AND executor_type='parent' AND status='pending' AND deadline ∈ [今日0点, 明日0点)` (晚总结另查 completed)
+- 判重:`user_notifications` 当日唯一(type=daily_morning / daily_evening,ref_type=task,当日 createdAt)
+- 渠道:`in_app` 恒兜底 + config.channels(复用 `dispatch()`)
+- 上限:单次 MAX_PROCESS_PER_RUN=200 兜底
+
+**早提醒方法** `@Scheduled(cron = "0 30 7 * * ?")`(07:30):
+- 对启用 daily_enabled 的用户配置(或默认启用?——**默认关闭**,用户到设置页手动开启,避免上线扰民)
+- 查询今日到期 + 逾期宽限内未打卡任务(今日到期主编 + OVERDUE_GRACE_DAYS=3 宽限)
+- 内容:「早上好,今日关注 N 项任务:标题1(截止HH:mm)、标题2(已逾期X天)…」
+- 若今日无任务 → 不发(避免空打扰)
+
+**晚总结方法** `@Scheduled(cron = "0 0 21 * * ?")`(21:00):
+- 今日到期任务分组:
+  - 已完成:`status=completed AND completedAt ∈ 今日`
+  - 未完成:`status=pending/pending_review AND deadline ∈ 今日`
+- 内容:「今日总结:完成 X/N。✅ 已完成:…;【未完成】⚠ 标题1(已截止HH:mm)… 别忘了打卡哦~」
+- 若今日无到期任务 → 不发
+
+> **注**:配置的 `morning_time`/`evening_time` 与固定 cron 的关系:cron 07:30 触发后,仅当「当前时间 ≥ 用户配置 morning_time」且当日未发才发送;即支持用户在 07:30 之前的任何早提醒时间(如 06:00),晚总结支持 21:00 之前任何时间。**边界**:用户配置晚于 cron 时刻(如 morning_time=08:00)时,本轮 cron 不会提前发送——需在前端限制可选范围或文档注明次日生效(实现时建议:若配置时间 < cron 时刻则按配置时间语义在次日 cron 前补发一次,或直接限定前端可选项 ≤ 07:30 / ≤ 21:00,二选一,实现者按注释执行)。
+
+### 3.5 前端(`cfc-frontend/pages/reminder-config/index.vue`)
+
+新增「日提醒」卡片(置于「提醒时机」下方):
+- 日提醒开关(dailyEnabled 0/1,样式复用 `cfg-switch`)
+- 早晚时间选择器(uni `picker` mode=time,默认 07:30 / 21:00)
+- 说明文案:「开启后,每天早上提醒今日待办,晚上总结今日完成情况并提醒补打卡」
+- 保存时携带 `dailyEnabled/morningTime/eveningTime`
+
+### 3.6 API_REFERENCE 文档同步
+
+`docs/superpowers/api/API_REFERENCE.md` §4.63.8 提醒设置行补充日提醒字段说明:
+`POST /api/task/reminder-config/get|save`(开关/渠道/时机/偏移/**日提醒开关+早晚时间**,SC-P-65/79)
+
+## 四、验收契约(RED 测试要点)
+
+1. ConfigService:`saveConfig` 拒绝非法 HH:mm(如 "25:00"、"7:30"、"07:3x")、接受合法值、dailyEnabled 边界
+2. 调度(早):启用日提醒用户今日到期任务 → 生成早提醒通知(当日唯一);未启用 → 不发;无任务 → 不发
+3. 调度(晚):今日到期任务按完成/未完成分组;未完成含催打卡文案;当日唯一判重
+4. 幂等:同一用户同一日早晚各一次(user_notifications 判重)
+5. 前端:开关持久化 + 时间选择回显
+
+## 五、风险与边界
+
+- **定时任务执行窗口**:固定 cron 与用户配置时间的语义差异(见 3.4 注),需实现者明确一个策略并在代码注释说明
+- **通知模板**:复用 `sendByTemplate`(type=task_daily_morning / task_daily_evening)或直接构造 NotificationMessage,按现有 dispatch 逻辑走
+- **不触碰**:现有 before_deadline/after_timeout 逻辑、timing_mode 二选一、completion_praise 完成表扬,全部保持原样
+- **收件人口径不变**:仅 parent 执行型任务执行人;child/其他执行类型不纳入(后续若需扩展另行评审)
+
+## 六、文档与代码位置
+
+- 设计契约:`docs/tdd/orchestration/task-daily-reminder-design-2026-11-14.md`(本文档,已推 origin/cfclub)
+- 实现文件:
+  - `cfc-backend/src/main/java/com/etotem/cfc/entity/TaskReminderConfig.java`
+  - `cfc-backend/src/main/java/com/etotem/cfc/dto/TaskReminderConfigDTO.java`
+  - `cfc-backend/src/main/java/com/etotem/cfc/service/TaskReminderConfigService.java`
+  - `cfc-backend/src/main/java/com/etotem/cfc/config/DatabaseInitializer.java`(迁移)+ `cfc-backend/src/main/resources/schema.sql`
+  - `cfc-backend/src/main/java/com/etotem/cfc/task/TaskDailyReminderScheduledTask.java`(新增)
+  - `cfc-frontend/pages/reminder-config/index.vue`