|
|
@@ -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`
|