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

docs/contracts/API接口约定.md

@@ -1 +1,212 @@
+# API 接口约定
 
+本文件是后端接口路径、请求响应格式、错误码和分页格式的唯一事实源。spec 只描述业务边界，不重复完整接口返回。
+
+## 1. 通用规则
+
+1. 所有业务接口使用 `/api` 前缀。
+2. 请求和响应使用 JSON。
+3. 时间字段使用 ISO 8601 字符串，并统一保存为服务器时区感知时间。
+4. 列表接口默认分页。
+5. 动作类接口使用 `POST /api/{resources}/{id}/{action}`。
+6. 飞书回调接口必须单独记录原始 payload。
+7. 后端必须做权限校验，不能只靠前端隐藏入口。
+
+## 2. 统一响应格式
+
+成功：
+
+```json
+{
+  "success": true,
+  "data": {},
+  "error": null,
+  "request_id": "req_20260622_xxx"
+}
+```
+
+失败：
+
+```json
+{
+  "success": false,
+  "data": null,
+  "error": {
+    "code": "permission_denied",
+    "message": "当前用户无权执行该操作",
+    "detail": {}
+  },
+  "request_id": "req_20260622_xxx"
+}
+```
+
+分页：
+
+```json
+{
+  "success": true,
+  "data": {
+    "items": [],
+    "page": 1,
+    "page_size": 20,
+    "total": 0
+  },
+  "error": null,
+  "request_id": "req_20260622_xxx"
+}
+```
+
+## 3. 通用错误码
+
+| code | HTTP | 含义 |
+| --- | --- | --- |
+| `validation_error` | 400 | 请求字段校验失败 |
+| `unauthenticated` | 401 | 未登录或登录态失效 |
+| `permission_denied` | 403 | 当前用户无权操作 |
+| `not_found` | 404 | 对象不存在或不可见 |
+| `state_conflict` | 409 | 当前状态不允许该操作 |
+| `idempotency_conflict` | 409 | 幂等键冲突或重复请求 |
+| `ai_parse_failed` | 422 | AI 输出无法解析或不符合结构 |
+| `ai_model_failed` | 502 | 百炼或模型网关失败，重试后仍不可用 |
+| `missing_person_mapping` | 422 | 缺少人员映射 |
+| `memory_store_failed` | 500 | AI 对话记忆、消息或 BotContext 保存/读取失败 |
+| `draft_convert_failed` | 500 | 草稿确认后转换任务或提醒失败 |
+| `feishu_signature_invalid` | 401 | 飞书回调验签失败 |
+| `feishu_api_failed` | 502 | 飞书接口调用失败 |
+| `reminder_trigger_failed` | 500 | 定时提醒触发失败 |
+| `internal_error` | 500 | 未分类服务端错误 |
+
+## 4. 用户与人员映射
+
+| 方法 | 路径 | 作用 | 权限 |
+| --- | --- | --- | --- |
+| GET | `/api/users/me` | 获取当前用户 | 已登录 |
+| GET | `/api/users` | 用户列表 | 管理员 / AI 团队 |
+| GET | `/api/auth/feishu/login` | 发起飞书扫码登录 / 身份登录 | 公开 |
+| GET | `/api/auth/feishu/callback` | 飞书登录回调 | 公开回调 |
+| POST | `/api/auth/logout` | 退出登录 | 已登录 |
+| GET | `/api/person-mappings` | 人员映射列表 | 管理员 / AI 团队 |
+| POST | `/api/person-mappings` | 新增人员映射 | 管理员 / AI 团队 |
+| PATCH | `/api/person-mappings/{id}` | 修改人员映射 | 管理员 / AI 团队 |
+| POST | `/api/person-mappings/{id}/resolve-feishu` | 根据手机号或邮箱解析飞书身份 | 管理员 / AI 团队 |
+
+## 5. Prompt 上下文
+
+| 方法 | 路径 | 作用 | 权限 |
+| --- | --- | --- | --- |
+| GET | `/api/prompt-contexts` | 查看提示词上下文配置 | 管理员 / AI 团队 |
+| PATCH | `/api/prompt-contexts/{id}` | 修改提示词上下文配置 | 管理员 / AI 团队 |
+| POST | `/api/prompt-contexts/{id}/activate` | 启用某个提示词上下文版本 | 管理员 / AI 团队 |
+
+## 6. AI 草稿
+
+| 方法 | 路径 | 作用 | 权限 |
+| --- | --- | --- | --- |
+| POST | `/api/secretary/handle-message` | 统一老板消息入口，返回草稿、追问、普通回复、上下文回顾或错误降级 | 老板；调试入口需管理员 token |
+| GET | `/api/ai-drafts` | 草稿列表 | 相关用户、程经理、管理员 |
+| GET | `/api/ai-drafts/{id}` | 草稿详情 | 相关用户、程经理、管理员 |
+| PATCH | `/api/ai-drafts/{id}` | 修改草稿字段 | 草稿发起人、待确认程经理 |
+| POST | `/api/ai-drafts/{id}/confirm` | 确认草稿 | 草稿发起人、待确认程经理 |
+| POST | `/api/ai-drafts/{id}/cancel` | 取消草稿 | 草稿发起人 |
+| POST | `/api/ai-drafts/{id}/convert` | 转换为事项或提醒 | 草稿发起人、待确认程经理 |
+| POST | `/api/ai-drafts/{id}/follow-up` | 根据补充/重说重新生成草稿 | 草稿发起人 |
+
+`POST /api/secretary/handle-message` 请求示例：
+
+```json
+{
+  "source": "feishu",
+  "message_id": "msg_xxx",
+  "sender": {
+    "open_id": "ou_xxx",
+    "name": "老板",
+    "role": "boss"
+  },
+  "text": "明天上午提醒东东给我订会议室",
+  "context": {}
+}
+```
+
+响应 `data` 建议包含：
+
+- `intent`
+- `reply_type`
+- `answer`
+- `draft`
+- `questions`
+- `context_summary`
+- `failure`
+
+`reply_type` 建议取值：
+
+- `draft_preview`
+- `follow_up_question`
+- `plain_answer`
+- `context_summary`
+- `unsupported`
+- `error`
+
+兼容接口 `/api/ai-drafts/parse`、`/api/demo/boss-message` 可以保留，但内部必须转发到 `/api/secretary/handle-message`。
+
+## 7. 事项
+
+| 方法 | 路径 | 作用 | 权限 |
+| --- | --- | --- | --- |
+| GET | `/api/tasks` | 事项列表 | 相关用户、程经理、管理员 |
+| POST | `/api/tasks` | 手动创建事项 | 老板、程经理 |
+| GET | `/api/tasks/{id}` | 事项详情 | 相关用户、程经理、管理员 |
+| PATCH | `/api/tasks/{id}` | 修改事项 | 发起人、程经理 |
+| POST | `/api/tasks/{id}/manager-confirm` | 程经理确认复杂事项 | 指定程经理 |
+| POST | `/api/tasks/{id}/cancel` | 取消事项 | 发起人、程经理 |
+| POST | `/api/tasks/{id}/notify` | 发送或补发通知 | 发起人、程经理、管理员 |
+| POST | `/api/tasks/{id}/feedback` | 平台内反馈 | 接收人 |
+
+## 8. 定时提醒
+
+| 方法 | 路径 | 作用 | 权限 |
+| --- | --- | --- | --- |
+| GET | `/api/reminders` | 提醒列表 | 相关用户、程经理、管理员 |
+| POST | `/api/reminders` | 创建提醒 | 已登录；给别人创建需老板或程经理 |
+| GET | `/api/reminders/{id}` | 提醒详情 | 相关用户、程经理、管理员 |
+| PATCH | `/api/reminders/{id}` | 修改提醒 | 创建人、发起人、管理员 |
+| POST | `/api/reminders/{id}/pause` | 暂停提醒 | 创建人、发起人、管理员 |
+| POST | `/api/reminders/{id}/resume` | 恢复提醒 | 创建人、发起人、管理员 |
+| POST | `/api/reminders/{id}/cancel` | 取消提醒 | 创建人、发起人、管理员 |
+| POST | `/api/reminders/{id}/notify` | 手动补发提醒通知 | 创建人、发起人、管理员 |
+| POST | `/api/reminders/{id}/feedback` | 平台内反馈 | 接收人 |
+
+## 9. 通知、反馈和失败
+
+| 方法 | 路径 | 作用 | 权限 |
+| --- | --- | --- | --- |
+| GET | `/api/notifications` | 通知记录列表 | 相关用户、程经理、管理员 |
+| GET | `/api/notifications/{id}` | 通知详情 | 相关用户、程经理、管理员 |
+| POST | `/api/notifications/{id}/retry` | 通知补发 | 发起人、程经理、管理员 |
+| GET | `/api/feedbacks` | 反馈列表 | 相关用户、程经理、管理员 |
+| GET | `/api/failure-records` | 失败记录列表 | 管理员 / AI 团队；必要时程经理 |
+| GET | `/api/failure-records/{id}` | 失败详情 | 管理员 / AI 团队；必要时程经理 |
+| PATCH | `/api/failure-records/{id}` | 更新处理状态 | 管理员 / AI 团队 |
+| POST | `/api/failure-records/{id}/resolve` | 填写处理结果并标记已处理 | 管理员 / AI 团队 |
+
+## 10. 飞书回调
+
+| 方法 | 路径 | 作用 | 权限 |
+| --- | --- | --- | --- |
+| POST | `/api/feishu/events` | 飞书事件回调，包含机器人消息事件 | 飞书验签 |
+| POST | `/api/feishu/bot/messages` | 可选：单独承接机器人私聊消息 | 飞书验签 |
+| POST | `/api/feishu/card-callback` | 飞书卡片回调 | 飞书验签 |
+
+飞书回调要求：
+
+1. 必须验签。
+2. 必须记录原始 payload 到 `feishu_events`。
+3. 必须使用 `event_id` 幂等。
+4. 验签失败不得执行业务动作。
+5. 回调处理失败必须写入 `failure_records`。
+
+## 11. 敏感信息返回边界
+
+1. API 不返回 API Key、App Secret、飞书 token。
+2. 手机号和邮箱默认脱敏返回，除非管理员维护页确有需要。
+3. 飞书通知只发送摘要和链接，不发送敏感全文。
+4. 模型调用日志对外接口默认不返回完整 prompt 和原始大段上下文。

docs/contracts/数据对象约定.md

@@ -1 +1,333 @@
+# 数据对象约定
 
+本文件是核心表、字段、外键关系和状态字段的唯一事实源。Django model、serializer、接口返回和测试用例中的字段应与本文件一致。
+
+## 1. 通用字段
+
+多数业务表使用：
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 主键，建议 bigint 或 uuid |
+| `created_at` | 创建时间 |
+| `updated_at` | 更新时间 |
+| `created_by` | 创建人，可为空时必须说明来源 |
+| `updated_by` | 最后修改人 |
+| `deleted_at` | 软删除时间，可选 |
+| `remark` | 备注，可选 |
+
+第一版建议使用软删除，避免误删过程记录。
+
+## 2. users
+
+平台登录、角色判断和数据范围控制。Django 项目初始化时建议使用自定义用户模型。
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 用户 ID |
+| `username` | 登录名或内部唯一标识 |
+| `name` | 显示姓名 |
+| `role` | `boss`、`manager`、`employee`、`admin` |
+| `phone` | 手机号，可选，普通日志需脱敏 |
+| `email` | 邮箱，可选，普通日志需脱敏 |
+| `feishu_open_id` | 飞书 open_id，可选 |
+| `feishu_user_id` | 飞书 user_id，可选 |
+| `feishu_union_id` | 飞书 union_id，可选 |
+| `auth_provider` | `local`、`feishu` |
+| `last_login_channel` | `platform`、`feishu_scan`、`feishu_in_app` |
+| `status` | `active`、`disabled` |
+| `last_login_at` | 最后登录时间 |
+
+## 3. person_mappings
+
+把老板输入中的姓名、称呼、部门或角色映射到平台用户和飞书身份。
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 映射 ID |
+| `user_id` | 关联平台用户，可选 |
+| `display_name` | 标准姓名 |
+| `aliases` | JSON 数组，例如 `["东东", "CJN"]` |
+| `department` | 部门 |
+| `business_role` | 业务角色，例如行政、程经理、下单员 |
+| `phone` | 手机号，可选 |
+| `email` | 邮箱，可选 |
+| `feishu_open_id` | 飞书 open_id |
+| `feishu_user_id` | 飞书 user_id，可选 |
+| `feishu_union_id` | 飞书 union_id，可选 |
+| `mapping_status` | `pending`、`resolved`、`failed` |
+| `is_trial_user` | 是否第一批试用人员 |
+| `note` | 备注 |
+
+## 4. feishu_auth_sessions
+
+记录飞书登录过程和平台用户绑定结果。
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 会话 ID |
+| `state` | OAuth state 或登录状态标识 |
+| `feishu_open_id` | 飞书 open_id |
+| `feishu_user_id` | 飞书 user_id |
+| `feishu_union_id` | 飞书 union_id，可选 |
+| `matched_user_id` | 匹配到的平台用户 |
+| `login_channel` | `feishu_scan`、`feishu_in_app` |
+| `status` | `pending`、`success`、`failed` |
+| `failure_reason` | 失败原因 |
+| `completed_at` | 完成时间 |
+
+## 5. secretary_conversations
+
+老板 AI 秘书会话。第一阶段只有一个老板秘书入口，可先固定 `conversation_id=boss_secretary_default`，但表结构要能支持后续多会话。
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 会话 ID |
+| `conversation_id` | 业务会话唯一标识 |
+| `boss_id` | 关联老板用户 |
+| `source` | `feishu`、`web`、`debug` |
+| `status` | `active`、`closed` |
+| `last_message_at` | 最近消息时间 |
+
+## 6. secretary_messages
+
+老板输入、AI 回复、AI 追问、普通记录和上下文回顾的统一消息记录。该表只追加，不修改，用于对话回放、上下文回顾和问题复盘。
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 消息 ID |
+| `conversation_id` | 关联 `secretary_conversations.conversation_id` |
+| `boss_id` | 关联老板用户 |
+| `source` | `feishu`、`web`、`debug` |
+| `message_id` | 外部消息 ID 或内部生成 ID，和 `source` 组成幂等键 |
+| `role` | `boss`、`assistant`、`system` |
+| `text` | 原始输入或 AI 回复 |
+| `answer` | AI 给老板的回复，可为空 |
+| `intent_type` | `task`、`reminder`、`qa`、`realtime_qa`、`note`、`need_more_info`、`unsupported`、`context_summary` |
+| `draft_id` | 关联 AI 草稿，可为空 |
+| `raw_payload` | 原始请求摘要，避免保存密钥 |
+| `bot_context_snapshot` | JSONB，消息发生时的上下文快照 |
+| `created_at` | 消息时间 |
+
+## 7. bot_contexts
+
+记录老板机器人私聊中的补充/重说上下文。
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 上下文 ID |
+| `conversation_id` | 当前老板秘书会话 ID |
+| `boss_id` | PostgreSQL 中的老板用户 ID |
+| `status` | `empty`、`awaiting_more_info`、`awaiting_confirm`、`expired`、`cleared` |
+| `pending_draft_id` | 当前待补充或待确认的草稿 ID |
+| `pending_draft_type` | `task`、`reminder`、`none` |
+| `last_intent` | 上一条有效意图 |
+| `expires_at` | 上下文有效期，进入待补充或待确认时重置为 30 分钟后 |
+| `follow_up_count` | 当前草稿累计追问轮次 |
+| `last_message_id` | 最近一次参与上下文判断的消息 ID |
+| `extracted_facts` | JSONB，从多轮对话提取的候选事实，只用于草稿修订 |
+| `updated_at` | 上下文最近更新时间 |
+
+## 8. prompt_contexts
+
+维护 AI 秘书调用模型时加载的上下文版本。
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 上下文 ID |
+| `context_type` | `company_background_summary`、`boss_communication_style`、`ai_secretary_rules`、`role_and_alias_rules` |
+| `version` | 版本号 |
+| `title` | 标题 |
+| `content` | 实际使用的摘要或规则文本 |
+| `status` | `draft`、`active`、`archived` |
+| `activated_at` | 启用时间 |
+| `created_by` | 创建人 |
+
+模型调用日志只保存本次使用的摘要、版本号和必要规则，避免反复保存完整背景库全文。
+
+## 9. ai_drafts
+
+保存 AI 从一句话整理出的可确认草稿。
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 草稿 ID |
+| `source` | `platform`、`feishu_bot` |
+| `created_by` | 发起人 |
+| `raw_input` | 原始输入 |
+| `intent` | `task`、`reminder` |
+| `draft_type` | `task`、`reminder` |
+| `should_create_draft` | 固定为 true；`qa/realtime_qa/note/need_more_info/unsupported` 不落 ai_drafts |
+| `status` | 见状态流转约定 |
+| `title` | 草稿标题 |
+| `content` | 事项或提醒内容 |
+| `receiver_candidates` | JSON，接收人候选和置信度 |
+| `receiver_text` | 未映射成功时保留老板原始称呼 |
+| `scheduled_at` | 提醒时间，可为空；任务可使用 `schedule_text` 表达期望时间 |
+| `schedule_text` | 老板原始时间表达 |
+| `recurrence_type` | `none`、`daily`、`weekly`、`monthly` |
+| `requires_feedback` | 是否需要反馈 |
+| `route_type` | `direct_after_boss_confirm`、`manager_confirm_required` |
+| `need_manager_confirm` | 是否需要程经理确认 |
+| `missing_fields` | JSON 数组 |
+| `questions` | JSON 数组，最多 3 个；确认草稿一般为空 |
+| `answer` | 给老板看的回复摘要；不得写“已通知、已创建、已发送”等执行语义 |
+| `model_call_log_id` | 关联模型调用日志 |
+
+## 10. model_call_logs
+
+记录模型输入输出、模型名、耗时和结果。
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 日志 ID |
+| `provider` | `bailian` |
+| `model_name` | 模型名 |
+| `prompt_context_snapshot` | 本次使用的上下文版本和摘要 |
+| `request_payload` | 请求摘要，避免保存密钥 |
+| `raw_response` | 模型原始响应 |
+| `parsed_json` | 解析后的 `AiSecretaryResponse` JSON |
+| `status` | `success`、`failed` |
+| `failure_reason` | 失败原因 |
+| `latency_ms` | 耗时 |
+| `created_by` | 调用发起人 |
+
+## 11. tasks
+
+需要接收人处理并反馈的事情。
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 事项 ID |
+| `source_draft_id` | 来源草稿，可选 |
+| `title` | 标题 |
+| `content` | 事项内容 |
+| `initiator_id` | 发起人 |
+| `receiver_id` | 接收人 |
+| `manager_id` | 复杂事项确认人，可选 |
+| `status` | 见状态流转约定 |
+| `visible_feedback_status` | `received`、`in_progress`、`completed`、`problem` |
+| `requires_feedback` | 是否需要反馈 |
+| `due_at` | 截止或期望反馈时间，可选 |
+| `confirmed_at` | 确认时间 |
+| `notified_at` | 通知时间 |
+| `completed_at` | 完成时间 |
+| `problem_reason` | 有问题原因，可选 |
+
+## 12. reminders
+
+未来某个时间触发的提醒。
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 提醒 ID |
+| `source_draft_id` | 来源草稿，可选 |
+| `related_task_id` | 关联事项，可选 |
+| `title` | 标题 |
+| `content` | 提醒内容 |
+| `initiator_id` | 发起人 |
+| `receiver_id` | 接收人 |
+| `status` | 见状态流转约定 |
+| `scheduled_at` | 首次提醒时间 |
+| `next_trigger_at` | 下一次触发时间 |
+| `recurrence_type` | `none`、`daily`、`weekly`、`monthly` |
+| `requires_feedback` | 是否需要反馈 |
+| `last_triggered_at` | 最近触发时间 |
+| `cancelled_at` | 取消时间 |
+
+## 13. notifications
+
+飞书或平台内通知发送记录。
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 通知 ID |
+| `target_type` | `ai_draft`、`task`、`reminder`、`failure_record` |
+| `target_id` | 关联对象 ID |
+| `receiver_id` | 接收人 |
+| `channel` | `feishu`、`platform` |
+| `message_type` | `text`、`card` |
+| `summary` | 通知摘要 |
+| `link_url` | 平台详情链接 |
+| `status` | `pending`、`sent`、`failed`、`retrying`、`cancelled` |
+| `idempotency_key` | 幂等键 |
+| `feishu_message_id` | 飞书消息 ID |
+| `sent_at` | 发送时间 |
+| `failure_reason` | 失败原因 |
+
+## 14. feedbacks
+
+接收人的反馈状态和问题原因。
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 反馈 ID |
+| `target_type` | `task`、`reminder` |
+| `target_id` | 关联对象 ID |
+| `feedback_by` | 反馈人 |
+| `status` | `received`、`in_progress`、`completed`、`problem` |
+| `problem_reason` | 有问题原因，`problem` 时必填 |
+| `source` | `feishu_card`、`platform` |
+| `notification_id` | 关联通知 |
+| `created_at` | 反馈时间 |
+
+## 15. failure_records
+
+AI、通知、回调、调度等失败原因。
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 失败记录 ID |
+| `failure_type` | 见状态流转约定中的失败类型 |
+| `target_type` | 关联对象类型 |
+| `target_id` | 关联对象 ID |
+| `status` | `pending`、`processing`、`resolved`、`cancelled` |
+| `reason` | 失败原因 |
+| `raw_error` | 原始错误摘要，不含密钥 |
+| `need_manager_sync` | 是否需要同步程经理 |
+| `handled_by` | 处理人 |
+| `handled_at` | 处理时间 |
+| `handle_result` | 处理结果 |
+
+## 16. operation_logs
+
+人工确认、修改、取消、补发等过程留痕。
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 日志 ID |
+| `actor_id` | 操作人 |
+| `action` | 动作 |
+| `target_type` | 对象类型 |
+| `target_id` | 对象 ID |
+| `channel` | `platform`、`feishu_bot`、`feishu_card`、`scheduler`、`admin` |
+| `result` | `success`、`failed` |
+| `summary` | 操作摘要 |
+| `metadata` | JSON，避免敏感明文 |
+| `created_at` | 操作时间 |
+
+## 17. feishu_events
+
+飞书回调原始事件和处理结果。
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 事件 ID |
+| `event_id` | 飞书事件 ID |
+| `event_type` | 事件类型 |
+| `operator_open_id` | 操作人 open_id |
+| `action_value` | 按钮值 |
+| `target_type` | `ai_draft`、`task`、`reminder`、`auth`、`bot` |
+| `target_id` | 关联业务对象 |
+| `notification_id` | 关联通知 |
+| `raw_payload` | 原始事件 |
+| `process_status` | `pending`、`processed`、`failed`、`ignored` |
+| `process_result` | 处理结果 |
+| `created_at` | 接收时间 |
+
+## 18. 敏感字段规则
+
+1. `phone`、`email` 可入库，但普通日志和普通列表接口默认脱敏。
+2. API Key、App Secret、飞书 token 不得入库到业务表或普通日志。
+3. `raw_error`、`metadata`、`request_payload` 必须避免密钥和完整个人联系方式。
+4. 飞书通知内容只保存和发送摘要，不展开敏感全文。

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` | 草稿已确认、取消或转换完成，上下文已清空 |