文档：完善后端协作与AI秘书基线

docs/contracts/状态流转约定.md

@@ -1 +1,299 @@
+# 状态流转约定
 
+本文件是状态枚举、允许流转、触发人和日志要求的唯一事实源。代码枚举、接口返回和测试用例应与本文件一致。
+
+## 1. 通用原则
+
+1. 状态统一使用英文枚举。
+2. 状态变化必须通过 service 层完成。
+3. 关键状态变化必须写 `operation_logs`。
+4. 非法状态跳转必须返回 `state_conflict`。
+5. 通知、回调、调度相关状态变化必须幂等。
+
+## 2. AI 草稿状态
+
+| 状态 | 含义 |
+| --- | --- |
+| `PENDING_CONFIRM` | 草稿已整理完成，等待老板确认、修改、取消或转经理 |
+| `NEED_MANAGER_CONFIRM` | 老板已确认，但复杂任务需要程经理确认 |
+| `CONFIRMED` | 已人工确认，等待转换任务或提醒 |
+| `CONVERTED` | 已转换为事项或提醒 |
+| `CANCELLED` | 已取消 |
+| `FAILED` | AI 解析或草稿处理失败，仅用于调试追踪 |
+
+允许流转：
+
+```text
+PENDING_CONFIRM -> CONFIRMED
+PENDING_CONFIRM -> NEED_MANAGER_CONFIRM
+PENDING_CONFIRM -> CANCELLED
+PENDING_CONFIRM -> FAILED
+NEED_MANAGER_CONFIRM -> CONFIRMED
+CONFIRMED -> CONVERTED
+CONFIRMED -> FAILED
+```
+
+约束：
+
+1. `FAILED`、`CANCELLED`、`CONVERTED` 为终态。
+2. 未进入 `CONFIRMED` 的草稿不得转换。
+3. `need_more_info`、`answered`、`context_summary` 是非草稿处理结果，不落 `ai_drafts.status`。
+4. 多次补充/重说优先合并到同一个 `pending_draft`，直到老板确认、取消、过期或明确新建，不要求每次补充都新建草稿。
+
+## 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 输出解析失败 |
+| `ai_model_failed` | 百炼或模型网关超时、网络失败、服务异常，重试后仍失败 |
+| `bot_message_failed` | 入口消息结构缺失、无法解析文本或 sender 信息 |
+| `missing_person_mapping` | 缺少人员映射 |
+| `memory_store_failed` | PostgreSQL AI 记忆表、上下文或快照保存/读取失败 |
+| `draft_convert_failed` | 老板或程经理确认后，转换任务/提醒失败 |
+| `feishu_auth_failed` | 飞书登录失败 |
+| `feishu_send_failed` | 飞书通知失败 |
+| `feishu_callback_failed` | 飞书回调处理失败 |
+| `feishu_signature_invalid` | 飞书验签失败 |
+| `reminder_trigger_failed` | 定时提醒触发失败 |
+| `bot_unauthorized` | 非老板使用机器人入口 |
+| `follow_up_expired` | 补充/重说上下文过期 |
+| `user_feedback_problem` | 用户反馈有问题 |
+| `permission_error` | 权限拒绝 |
+| `system_error` | 未归类系统异常 |
+
+## 11. 飞书事件处理状态
+
+| 状态 | 含义 |
+| --- | --- |
+| `pending` | 已接收待处理 |
+| `processed` | 已处理 |
+| `failed` | 处理失败 |
+| `ignored` | 已忽略 |
+
+约束：
+
+1. 同一 `event_id` 只处理一次。
+2. 验签失败不得执行业务动作。
+3. 处理失败必须写失败记录。
+
+## 12. 用户和配置状态
+
+用户状态：
+
+| 状态 | 含义 |
+| --- | --- |
+| `active` | 启用 |
+| `disabled` | 停用 |
+
+人员映射状态：
+
+| 状态 | 含义 |
+| --- | --- |
+| `pending` | 待解析 |
+| `resolved` | 已解析 |
+| `failed` | 解析失败 |
+
+Prompt 上下文状态：
+
+| 状态 | 含义 |
+| --- | --- |
+| `draft` | 草稿 |
+| `active` | 启用 |
+| `archived` | 已归档 |
+
+飞书登录会话状态：
+
+| 状态 | 含义 |
+| --- | --- |
+| `pending` | 登录处理中 |
+| `success` | 登录成功 |
+| `failed` | 登录失败 |
+
+机器人上下文状态：
+
+| 状态 | 含义 |
+| --- | --- |
+| `empty` | 当前没有可补充或可确认的草稿 |
+| `awaiting_more_info` | AI 已追问，等待老板补充 |
+| `awaiting_confirm` | 草稿已整理完成，等待老板确认、修改、取消或转经理 |
+| `expired` | 已过期 |
+| `cleared` | 草稿已确认、取消或转换完成，上下文已清空 |