talesofzes
299 lines
7.2 KiB
Markdown
299 lines
7.2 KiB
Markdown
# 状态流转约定
|
|
|
|
本文件是状态枚举、允许流转、触发人和日志要求的唯一事实源。代码枚举、接口返回和测试用例应与本文件一致。
|
|
|
|
## 1. 通用原则
|
|
|
|
1. 状态统一使用英文枚举。
|
|
2. 状态变化必须通过 service 层完成。
|
|
3. 关键状态变化必须写 `operation_logs`。
|
|
4. 非法状态跳转必须返回 `state_conflict`。
|
|
5. 通知、回调、调度相关状态变化必须幂等。
|
|
|
|
## 2. AI 草稿状态
|
|
|
|
| 状态 | 含义 |
|
|
| --- | --- |
|
|
| `pending_confirmation` | 等待老板确认 |
|
|
| `awaiting_follow_up` | 等待老板补充/重说 |
|
|
| `pending_manager_confirm` | 等待程经理确认 |
|
|
| `confirmed` | 已人工确认 |
|
|
| `converted` | 已转换为事项或提醒 |
|
|
| `cancelled` | 已取消 |
|
|
| `parse_failed` | AI 输出解析失败 |
|
|
| `expired` | 补充/重说上下文过期 |
|
|
|
|
允许流转：
|
|
|
|
```text
|
|
pending_confirmation -> awaiting_follow_up
|
|
pending_confirmation -> pending_manager_confirm
|
|
pending_confirmation -> confirmed
|
|
pending_confirmation -> cancelled
|
|
pending_confirmation -> parse_failed
|
|
awaiting_follow_up -> pending_confirmation
|
|
awaiting_follow_up -> expired
|
|
pending_manager_confirm -> confirmed
|
|
pending_manager_confirm -> cancelled
|
|
confirmed -> converted
|
|
```
|
|
|
|
约束：
|
|
|
|
1. `parse_failed`、`cancelled`、`converted` 为终态。
|
|
2. 未进入 `confirmed` 的草稿不得转换。
|
|
3. 补充/重说生成的新草稿应写 `parent_draft_id`。
|
|
|
|
## 3. 事项状态
|
|
|
|
| 状态 | 含义 |
|
|
| --- | --- |
|
|
| `pending_manager_confirm` | 等待程经理确认 |
|
|
| `pending_notify` | 待通知 |
|
|
| `notified` | 已通知 |
|
|
| `notify_failed` | 通知失败 |
|
|
| `feedback_received` | 已收到反馈 |
|
|
| `completed` | 已完成 |
|
|
| `problem` | 有问题 |
|
|
| `cancelled` | 已取消 |
|
|
|
|
允许流转：
|
|
|
|
```text
|
|
pending_manager_confirm -> pending_notify
|
|
pending_manager_confirm -> cancelled
|
|
pending_notify -> notified
|
|
pending_notify -> notify_failed
|
|
notify_failed -> pending_notify
|
|
notified -> feedback_received
|
|
notified -> completed
|
|
notified -> problem
|
|
feedback_received -> completed
|
|
feedback_received -> problem
|
|
problem -> pending_notify
|
|
```
|
|
|
|
约束：
|
|
|
|
1. `cancelled` 为终态。
|
|
2. 未通知事项不得接收飞书反馈。
|
|
3. `problem` 必须有问题原因。
|
|
4. 通知失败不得标记为 `notified`。
|
|
|
|
## 4. 事项用户可见反馈状态
|
|
|
|
| 状态 | 含义 |
|
|
| --- | --- |
|
|
| `received` | 已收到 |
|
|
| `in_progress` | 处理中 |
|
|
| `completed` | 已完成 |
|
|
| `problem` | 有问题 |
|
|
|
|
约束：
|
|
|
|
1. `problem` 必须填写 `problem_reason`。
|
|
2. 反馈人必须是事项接收人。
|
|
3. `received` 和 `in_progress` 反馈写入 `feedbacks.status`，并将 `tasks.status` 置为 `feedback_received`、`tasks.visible_feedback_status` 置为对应值。
|
|
4. `completed` 反馈将 `tasks.status` 和 `tasks.visible_feedback_status` 都置为 `completed`。
|
|
5. `problem` 反馈将 `tasks.status` 和 `tasks.visible_feedback_status` 都置为 `problem`，并写入 `problem_reason`。
|
|
|
|
## 5. 提醒状态
|
|
|
|
| 状态 | 含义 |
|
|
| --- | --- |
|
|
| `active` | 生效中 |
|
|
| `paused` | 已暂停 |
|
|
| `triggered` | 一次性提醒已触发 |
|
|
| `trigger_failed` | 触发失败 |
|
|
| `cancelled` | 已取消 |
|
|
| `expired` | 已过期 |
|
|
|
|
允许流转：
|
|
|
|
```text
|
|
active -> paused
|
|
paused -> active
|
|
active -> triggered
|
|
active -> trigger_failed
|
|
trigger_failed -> active
|
|
active -> cancelled
|
|
paused -> cancelled
|
|
trigger_failed -> cancelled
|
|
triggered -> expired
|
|
```
|
|
|
|
约束：
|
|
|
|
1. 只有 `active` 可以被 scheduler 触发。
|
|
2. `cancelled` 为终态。
|
|
3. `paused` 不触发通知。
|
|
4. `trigger_failed` 必须写失败记录。
|
|
5. 一次性提醒成功触发后，状态从 `active` 变为 `triggered`，并可在后续清理或展示时变为 `expired`。
|
|
6. `daily`、`weekly`、`monthly` 周期提醒成功触发后状态保持 `active`，只更新 `last_triggered_at` 和下一次 `next_trigger_at`。
|
|
7. 提醒反馈不改变提醒调度状态；反馈结果保存在 `feedbacks`，提醒是否继续触发只由 `status`、`repeat_rule` 和 `next_trigger_at` 决定。
|
|
|
|
## 6. 重复规则
|
|
|
|
| 值 | 含义 |
|
|
| --- | --- |
|
|
| `none` | 一次性 |
|
|
| `daily` | 每天 |
|
|
| `weekly` | 每周 |
|
|
| `monthly` | 每月 |
|
|
|
|
第一版不支持 cron 表达式和自定义复杂周期。
|
|
|
|
## 7. 通知状态
|
|
|
|
| 状态 | 含义 |
|
|
| --- | --- |
|
|
| `pending` | 待发送 |
|
|
| `sent` | 已发送 |
|
|
| `failed` | 发送失败 |
|
|
| `retrying` | 补发中 |
|
|
| `cancelled` | 已取消 |
|
|
|
|
允许流转：
|
|
|
|
```text
|
|
pending -> sent
|
|
pending -> failed
|
|
failed -> retrying
|
|
retrying -> sent
|
|
retrying -> failed
|
|
pending -> cancelled
|
|
failed -> cancelled
|
|
```
|
|
|
|
约束：
|
|
|
|
1. `sent` 不得重复发送同一通知。
|
|
2. 补发必须保留原失败记录和新发送结果。
|
|
3. 飞书通知必须使用幂等键。
|
|
|
|
通知幂等键建议：
|
|
|
|
```text
|
|
target_type + target_id + receiver_id + channel + trigger_time
|
|
```
|
|
|
|
提醒触发幂等键建议：
|
|
|
|
```text
|
|
reminder_id + trigger_time + receiver_id + notification_channel
|
|
```
|
|
|
|
## 8. 反馈状态
|
|
|
|
| 状态 | 含义 |
|
|
| --- | --- |
|
|
| `received` | 已收到 |
|
|
| `in_progress` | 处理中 |
|
|
| `completed` | 已完成 |
|
|
| `problem` | 有问题 |
|
|
|
|
约束：
|
|
|
|
1. 反馈目标只能是 `task` 或 `reminder`。
|
|
2. 反馈人必须是接收人。
|
|
3. `problem` 必须填写一句原因。
|
|
4. 重复点击卡片不得重复创建相同反馈。
|
|
|
|
## 9. 失败记录状态
|
|
|
|
| 状态 | 含义 |
|
|
| --- | --- |
|
|
| `pending` | 待处理 |
|
|
| `processing` | 处理中 |
|
|
| `resolved` | 已处理 |
|
|
| `cancelled` | 已取消 |
|
|
|
|
允许流转：
|
|
|
|
```text
|
|
pending -> processing
|
|
pending -> resolved
|
|
pending -> cancelled
|
|
processing -> resolved
|
|
processing -> cancelled
|
|
```
|
|
|
|
约束：
|
|
|
|
1. `resolved` 必须填写处理结果。
|
|
2. 状态变化必须写操作日志。
|
|
|
|
## 10. 失败类型
|
|
|
|
| 类型 | 含义 |
|
|
| --- | --- |
|
|
| `ai_parse_failed` | AI 输出解析失败 |
|
|
| `person_mapping_missing` | 缺少人员映射 |
|
|
| `feishu_auth_failed` | 飞书登录失败 |
|
|
| `feishu_notify_failed` | 飞书通知失败 |
|
|
| `feishu_callback_failed` | 飞书回调处理失败 |
|
|
| `feishu_signature_invalid` | 飞书验签失败 |
|
|
| `scheduler_trigger_failed` | 定时提醒触发失败 |
|
|
| `unauthorized_bot_access` | 非老板使用机器人入口 |
|
|
| `bot_context_expired` | 补充/重说上下文过期 |
|
|
| `user_feedback_problem` | 用户反馈有问题 |
|
|
| `permission_denied` | 权限拒绝 |
|
|
| `other` | 其他 |
|
|
|
|
## 11. 飞书事件处理状态
|
|
|
|
| 状态 | 含义 |
|
|
| --- | --- |
|
|
| `pending` | 已接收待处理 |
|
|
| `processed` | 已处理 |
|
|
| `failed` | 处理失败 |
|
|
| `ignored` | 已忽略 |
|
|
|
|
约束：
|
|
|
|
1. 同一 `event_id` 只处理一次。
|
|
2. 验签失败不得执行业务动作。
|
|
3. 处理失败必须写失败记录。
|
|
|
|
## 12. 用户和配置状态
|
|
|
|
用户状态：
|
|
|
|
| 状态 | 含义 |
|
|
| --- | --- |
|
|
| `active` | 启用 |
|
|
| `disabled` | 停用 |
|
|
|
|
人员映射状态：
|
|
|
|
| 状态 | 含义 |
|
|
| --- | --- |
|
|
| `pending` | 待解析 |
|
|
| `resolved` | 已解析 |
|
|
| `failed` | 解析失败 |
|
|
|
|
Prompt 上下文状态：
|
|
|
|
| 状态 | 含义 |
|
|
| --- | --- |
|
|
| `draft` | 草稿 |
|
|
| `active` | 启用 |
|
|
| `archived` | 已归档 |
|
|
|
|
飞书登录会话状态：
|
|
|
|
| 状态 | 含义 |
|
|
| --- | --- |
|
|
| `pending` | 登录处理中 |
|
|
| `success` | 登录成功 |
|
|
| `failed` | 登录失败 |
|
|
|
|
机器人上下文状态：
|
|
|
|
| 状态 | 含义 |
|
|
| --- | --- |
|
|
| `idle` | 空闲 |
|
|
| `awaiting_follow_up` | 等待补充/重说 |
|
|
| `expired` | 已过期 |
|
|
| `closed` | 已关闭 |
|