talesofzes
140 lines
3.8 KiB
Markdown
140 lines
3.8 KiB
Markdown
# 04_定时提醒
|
|
|
|
## 1. 模块目标
|
|
|
|
定时提醒模块负责创建一次性或固定周期提醒，到点生成通知、发送飞书消息、按需接收反馈，并记录触发结果和失败原因。
|
|
|
|
## 2. 第一版做什么
|
|
|
|
1. 支持一次性提醒。
|
|
2. 支持每天、每周、每月固定周期提醒。
|
|
3. 支持提醒来自手动创建。
|
|
4. 支持提醒来自老板 AI 草稿确认。
|
|
5. 支持提醒与事项关联。
|
|
6. 到点后通知接收人。
|
|
7. 通知成功或失败都要记录。
|
|
8. 支持查看自己相关提醒状态。
|
|
9. 创建人、发起人、管理员可以修改、暂停或取消提醒。
|
|
10. 提醒可以设置是否需要接收人反馈。
|
|
|
|
## 3. 第一版不做
|
|
|
|
1. 不做 cron 表达式。
|
|
2. 不做自定义复杂周期规则。
|
|
3. 不做日历系统。
|
|
4. 不做复杂自动化流程。
|
|
5. 不自动操作外部系统。
|
|
6. 不从 AI 工作台结果生成提醒。
|
|
|
|
## 4. 核心流程
|
|
|
|
创建提醒：
|
|
|
|
```text
|
|
手动创建或草稿确认
|
|
-> 后端校验创建权限
|
|
-> 写入 reminders
|
|
-> 计算 next_trigger_at
|
|
-> 写 operation_logs
|
|
```
|
|
|
|
触发提醒：
|
|
|
|
```text
|
|
scheduler 扫描 due reminders
|
|
-> 校验提醒状态
|
|
-> 生成幂等键
|
|
-> 创建 notifications
|
|
-> 调用飞书发送
|
|
-> 更新 last_triggered_at 和 next_trigger_at
|
|
-> 成功或失败都写记录
|
|
```
|
|
|
|
反馈：
|
|
|
|
```text
|
|
接收人点击卡片反馈
|
|
-> 飞书回调验签
|
|
-> 校验接收人权限
|
|
-> 写 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` 展示。
|
|
|
|
## 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. 失败是否可复盘。
|