# 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. 失败是否可复盘。