AI-Secretary/docs/specs/04_定时提醒.md

04_定时提醒

1. 模块目标

定时提醒模块负责创建一次性或固定周期提醒，到点生成通知、发送飞书消息、按需接收反馈，并记录触发结果和失败原因。

2. 第一版做什么

1. 支持一次性提醒。
2. 支持每天、每周、每月固定周期提醒。
3. 支持提醒来自手动创建。
4. 支持提醒来自老板 AI 草稿 confirmed 后转换。
5. 支持提醒与事项关联。
6. 到点后通知接收人。
7. 通知成功或失败都要记录。
8. 支持查看自己相关提醒状态。
9. 创建人、发起人、管理员可以修改、暂停或取消提醒。
10. 提醒可以设置是否需要接收人反馈。

3. 第一版不做

1. 不做 cron 表达式。
2. 不做自定义复杂周期规则。
3. 不做日历系统。
4. 不做复杂自动化流程。
5. 不自动操作外部系统。
6. 不从 AI 工作台结果生成提醒。

4. 核心流程

创建提醒：

手动创建或草稿确认
-> 后端校验创建权限
-> AI 提醒草稿必须有明确 scheduled_at
-> 写入 reminders
-> 计算 next_trigger_at
-> 写 operation_logs

触发提醒：

scheduler 扫描 due reminders
-> 校验提醒状态
-> 用事务锁定当前批次
-> 生成幂等键
-> 创建 notifications
-> 调用飞书发送
-> 更新 last_triggered_at 和 next_trigger_at
-> 成功或失败都写记录

反馈：

接收人点击卡片反馈
-> 飞书回调验签
-> 校验接收人权限
-> 写 feedbacks
-> 保留 reminders 调度状态，反馈结果通过 feedbacks 展示

5. 数据对象

本模块主要使用：

1. ai_drafts
2. tasks
3. reminders
4. notifications
5. feedbacks
6. failure_records
7. operation_logs

字段以 docs/contracts/数据对象约定.md 为准。

6. 接口需求

主要接口：

1. GET /api/reminders
2. POST /api/reminders
3. GET /api/reminders/{id}
4. PATCH /api/reminders/{id}
5. POST /api/reminders/{id}/pause
6. POST /api/reminders/{id}/resume
7. POST /api/reminders/{id}/cancel
8. POST /api/reminders/{id}/notify
9. POST /api/reminders/{id}/feedback

接口格式以 docs/contracts/API接口约定.md 为准。

7. 权限规则

1. 所有人可以创建自己的提醒。
2. 老板和程经理可以给别人创建提醒。
3. 普通员工不能给同事创建提醒。
4. 创建人、发起人、管理员可以修改、暂停或取消提醒。
5. 接收人只能反馈自己相关提醒。

8. 状态流转

提醒状态以 docs/contracts/状态流转约定.md 为准。核心约束：

1. active 提醒才允许 scheduler 触发。
2. paused 不触发，但可以恢复。
3. cancelled 不触发、不可恢复。
4. trigger_failed 必须写失败记录。
5. 同一个提醒同一触发时间同一接收人同一渠道只能生成一条有效通知。
6. 一次性提醒成功触发后进入 triggered；周期提醒成功触发后保持 active 并计算下一次 next_trigger_at。
7. 提醒反馈不改变提醒调度状态，反馈结果通过 feedbacks 展示。
8. AI 提醒草稿缺少明确时间时不得创建 active 提醒，应由 01 模块追问或标记 missing_fields。

9. 失败和日志

必须记录：

1. 提醒创建、修改、暂停、恢复、取消。
2. scheduler 触发成功或失败。
3. 飞书通知发送成功或失败。
4. 幂等冲突或重复触发跳过。
5. 权限拒绝。
6. 有问题反馈原因。

10. 给 AI 的测试样例

1. 普通员工给同事创建提醒，应返回权限错误。
2. paused 提醒到点不应触发通知。
3. 同一提醒同一触发时间重复扫描，不应重复创建通知。
4. 每周提醒触发后，应计算下一次提醒时间。
5. 通知失败应写失败记录。
6. 自己提醒自己默认不需要反馈，老板或程经理给别人提醒默认需要反馈。

11. Review 重点

1. 是否防止重复触发。
2. 是否限制普通员工给别人创建提醒。
3. 是否不支持 cron 等第一版不做内容。
4. scheduler 是否走 service 层而不是直接改业务表。
5. 失败是否可复盘。
6. 是否使用事务锁和 notifications.idempotency_key 唯一约束防止重复触发。