AI-Secretary/docs/contracts/状态流转约定.md

状态流转约定

本文件是状态枚举、允许流转、触发人和日志要求的唯一事实源。代码枚举、接口返回和测试用例应与本文件一致。

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	补充/重说上下文过期

允许流转：

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	已取消

允许流转：

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	已过期

允许流转：

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	已取消

允许流转：

pending -> sent
pending -> failed
failed -> retrying
retrying -> sent
retrying -> failed
pending -> cancelled
failed -> cancelled

约束：

1. sent 不得重复发送同一通知。
2. 补发必须保留原失败记录和新发送结果。
3. 飞书通知必须使用幂等键。

通知幂等键建议：

target_type + target_id + receiver_id + channel + trigger_time

提醒触发幂等键建议：

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	已取消

允许流转：

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	已关闭