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

docs/checklists/AI生成代码检查清单.md

@@ -1 +1,95 @@
+# AI 生成代码检查清单
 
+AI 生成或修改后端代码前后都要检查本清单。checklists 是 Review 闸门，不是写完后随手看一眼。
+
+## 1. 文档读取
+
+- [ ] 已读 `AGENTS.md`。
+- [ ] 已读当前相关 `docs/specs/*.md`。
+- [ ] 已读当前 active plan。
+- [ ] 涉及接口时已读 `docs/contracts/API接口约定.md`。
+- [ ] 涉及字段或数据库时已读 `docs/contracts/数据对象约定.md`。
+- [ ] 涉及老板 AI 秘书、Agent、BotContext 或对话记忆时已读 `docs/specs/01_老板AI秘书与AI草稿.md`。
+- [ ] 涉及状态流转时已读 `docs/contracts/状态流转约定.md`。
+- [ ] 涉及飞书时已读 `docs/specs/03_飞书通知与反馈.md`。
+
+## 2. 范围控制
+
+- [ ] 只实现 active plan 要求的范围。
+- [ ] 没有混入第一版明确不做的功能。
+- [ ] 没有把 AI 工作台、技能市场、复杂看板、复杂 BI、cron、自定义日历等能力带入主线。
+- [ ] 没有为了方便临时绕过权限、状态或日志要求。
+
+## 3. 权限
+
+- [ ] 普通员工不能给别人创建事项。
+- [ ] 普通员工不能给别人创建提醒。
+- [ ] 接收人之外的人不能反馈事项或提醒。
+- [ ] 飞书机器人私聊入口第一版只允许老板使用。
+- [ ] 程经理复杂事项确认走平台，不通过机器人对话处理。
+- [ ] 权限在后端校验，不只靠前端隐藏按钮。
+
+## 4. AI 草稿
+
+- [ ] AI 只生成草稿，不直接创建事项、提醒或通知。
+- [ ] 老板消息统一走 `POST /api/secretary/handle-message`。
+- [ ] `source + message_id` 幂等，不重复调用模型、不重复创建草稿、不重复写 `secretary_messages`。
+- [ ] AI 输出 JSON 已做结构校验。
+- [ ] `qa/realtime_qa/note/need_more_info/unsupported` 不创建事项、提醒或通知。
+- [ ] 实时问答第一版只做暂不支持提示，不做交易判断。
+- [ ] `need_more_info` 最多 3 个问题、最多 3 轮追问。
+- [ ] PostgreSQL AI 对话记忆只辅助理解和草稿修订，不替代任务、提醒、通知等正式业务表。
+- [ ] 结构化字段没有写入游戏化表达。
+- [ ] 模型调用记录了背景摘要、老板风格和业务规则版本。
+- [ ] AI 解析失败会写 `model_call_logs` 和 `failure_records`。
+
+## 5. 状态
+
+- [ ] 草稿、事项、提醒、通知、反馈、失败记录的状态枚举来自 `状态流转约定.md`。
+- [ ] 非法状态跳转返回 `state_conflict`。
+- [ ] 已取消对象不能继续转换、通知或反馈。
+- [ ] `converted` 草稿不会重复转换。
+- [ ] 通知失败不会被标记为已通知。
+- [ ] 有问题反馈必须填写原因。
+
+## 6. 飞书
+
+- [ ] 飞书回调必须验签。
+- [ ] 飞书事件使用 `event_id` 幂等。
+- [ ] 卡片重复点击不会重复创建事项、提醒或反馈。
+- [ ] 飞书通知只发送摘要和链接。
+- [ ] 非老板机器人访问不会调用 AI。
+- [ ] 回调失败会写 `feishu_events` 和 `failure_records`。
+
+## 7. 定时提醒
+
+- [ ] scheduler 独立于 Gunicorn worker 运行。
+- [ ] 同一环境同一应用库同时只有一个 scheduler 进程运行。
+- [ ] 只有 `active` 提醒会触发。
+- [ ] `paused` 和 `cancelled` 不会触发。
+- [ ] 同一提醒、同一触发时间、同一接收人、同一渠道只生成一条有效通知。
+- [ ] 触发失败会写失败记录。
+
+## 8. 事务和幂等
+
+- [ ] 创建事项或提醒、创建通知、写日志在事务边界内处理。
+- [ ] 外部调用失败不会留下半截错误状态。
+- [ ] 补发保留原失败记录和新发送结果。
+- [ ] 重复请求不会重复执行业务动作。
+
+## 9. 日志和敏感信息
+
+- [ ] 关键动作写 `operation_logs`。
+- [ ] 失败写 `failure_records`。
+- [ ] 普通日志不包含 API Key、App Secret、飞书 token。
+- [ ] 普通日志不包含完整手机号或完整邮箱。
+- [ ] 原始错误摘要不包含密钥。
+
+## 10. 测试
+
+- [ ] 权限测试覆盖普通员工不能给别人创建事项或提醒。
+- [ ] 状态测试覆盖非法跳转。
+- [ ] 飞书测试覆盖验签失败、幂等重复事件和非接收人反馈。
+- [ ] 定时测试覆盖重复触发防护。
+- [ ] 事务测试覆盖通知失败不留下半截数据。
+- [ ] AI 测试覆盖解析失败、实时问答和人工确认边界。

docs/checklists/后端Review清单.md

@@ -1 +1,83 @@
+# 后端 Review 清单
 
+后端 Review 优先找风险、权限漏洞、状态错误、事务问题、缺测试和敏感信息泄漏。
+
+## 1. 权限
+
+- [ ] DRF permission class 覆盖入口权限。
+- [ ] service 层覆盖业务权限。
+- [ ] 普通员工不能给别人创建事项或提醒。
+- [ ] 反馈人必须是事项或提醒接收人。
+- [ ] 飞书身份没有直接绕过平台角色权限。
+- [ ] 非老板机器人私聊不会触发 AI。
+- [ ] 失败记录仅管理员 / AI 团队和必要管理角色可见。
+
+## 2. 状态流转
+
+- [ ] 状态枚举与 `docs/contracts/状态流转约定.md` 一致。
+- [ ] 状态变化集中在 service 层。
+- [ ] 非法状态跳转返回明确错误。
+- [ ] 已取消、已转换、已完成等终态不会被重复处理。
+- [ ] 有问题反馈必须留下原因。
+
+## 3. 事务和一致性
+
+- [ ] 创建事项 / 提醒 / 通知 / 日志的事务边界清晰。
+- [ ] 外部 API 失败不会造成业务状态误判。
+- [ ] 通知失败不会标记已通知。
+- [ ] 补发不会覆盖历史失败记录。
+- [ ] scheduler 不绕过 service 直接改业务表。
+
+## 4. 飞书
+
+- [ ] 回调已验签。
+- [ ] `event_id` 幂等。
+- [ ] 卡片重复点击幂等。
+- [ ] 通知内容只包含摘要和链接。
+- [ ] 飞书 token、App Secret 不进入日志。
+- [ ] 找不到通知、草稿、事项、提醒时有失败记录。
+
+## 5. AI
+
+- [ ] AI 输出只进入草稿。
+- [ ] 老板消息统一走 `POST /api/secretary/handle-message`。
+- [ ] `source + message_id` 幂等覆盖模型调用、草稿创建和 `secretary_messages`。
+- [ ] 模型 JSON 有 validator。
+- [ ] `qa` / `realtime_qa` / `note` / `need_more_info` / `unsupported` 不创建事项或提醒。
+- [ ] 实时问答不做交易判断。
+- [ ] PromptContext 版本被记录。
+- [ ] PostgreSQL AI 对话记忆只辅助理解和草稿修订，不替代正式业务表。
+- [ ] PostgreSQL AI 记忆读写失败会写 `memory_store_failed`，不继续依赖内存确认草稿。
+- [ ] 游戏化表达没有进入结构化字段。
+
+## 6. 定时提醒
+
+- [ ] 只支持一次性、每天、每周、每月。
+- [ ] 不支持 cron 和复杂日历。
+- [ ] 同一环境同一应用库同时只有一个 scheduler 进程。
+- [ ] `paused`、`cancelled` 不触发。
+- [ ] 触发幂等键覆盖提醒、时间、接收人和渠道。
+- [ ] 触发失败可复盘。
+
+## 7. 日志和失败
+
+- [ ] 关键动作写 `operation_logs`。
+- [ ] 失败写 `failure_records`。
+- [ ] 失败记录包含类型、关联对象、原因、处理状态。
+- [ ] 失败处理必须有处理结果。
+- [ ] 日志包含操作人和渠道。
+
+## 8. 测试
+
+- [ ] 单元测试覆盖权限、状态、AI 输出校验、飞书回调、提醒幂等。
+- [ ] 失败路径有测试。
+- [ ] 测试没有依赖真实飞书或真实百炼网络调用。
+- [ ] 测试 fixture 不包含真实手机号、邮箱、token 或密钥。
+
+## 9. 文档同步
+
+- [ ] 改接口同步 `docs/contracts/API接口约定.md`。
+- [ ] 改字段同步 `docs/contracts/数据对象约定.md`。
+- [ ] 改状态同步 `docs/contracts/状态流转约定.md`。
+- [ ] 改飞书逻辑同步 `docs/specs/03_飞书通知与反馈.md`。
+- [ ] 改 AI 规则同步 `docs/specs/01_老板AI秘书与AI草稿.md`。

docs/checklists/联调验收清单.md

@@ -1 +1,73 @@
+# 联调验收清单
 
+联调验收看闭环是否真实可用，不看页面数量。
+
+## 1. 身份和入口
+
+- [ ] 用户可以通过飞书扫码登录 / 身份登录进入平台。
+- [ ] 飞书登录可以匹配到平台用户和角色。
+- [ ] 未匹配用户或停用用户不能进入平台，并有失败记录。
+- [ ] 老板可以通过飞书机器人私聊提交一句话。
+- [ ] 老板消息统一进入 `POST /api/secretary/handle-message`。
+- [ ] 非老板私聊机器人不会触发 AI，并有未授权访问记录。
+
+## 2. AI 草稿
+
+- [ ] AI 可以把老板一句话解析为结构化草稿。
+- [ ] AI 草稿可以展示原始输入、类型、内容、接收人候选、时间、反馈要求和缺失字段。
+- [ ] 草稿必须人工确认后才创建事项或提醒。
+- [ ] 普通聊天、普通记录、实时问答兜底不会创建草稿、事项或提醒。
+- [ ] 老板可以确认、补充/重说、取消草稿。
+- [ ] 补充/重说 30 分钟上下文可以生效并过期。
+- [ ] PostgreSQL 中可以查看 `secretary_messages` 和当前 `BotContext`。
+- [ ] 实时问答不会创建事项、提醒或通知。
+
+## 3. 事项闭环
+
+- [ ] 简单事项可以从草稿生成。
+- [ ] 复杂事项可以转程经理确认。
+- [ ] 程经理收到飞书提醒后进入平台确认。
+- [ ] 事项可以飞书通知接收人。
+- [ ] 接收人可以反馈已收到、处理中、已完成、有问题。
+- [ ] 有问题反馈必须留下原因。
+- [ ] 发起人或程经理可以看到事项结果。
+
+## 4. 定时提醒闭环
+
+- [ ] 手动创建一次性提醒。
+- [ ] 从草稿创建提醒。
+- [ ] 支持每天、每周、每月固定周期提醒。
+- [ ] 到点触发飞书通知。
+- [ ] 自己提醒自己默认不需要反馈。
+- [ ] 老板 / 程经理给别人设置的提醒默认需要反馈。
+- [ ] 暂停、恢复、取消按状态约定生效。
+- [ ] 同一提醒不会重复触发同一通知。
+- [ ] 演示 / 联调环境同一应用库只启动一个 scheduler 进程。
+
+## 5. 飞书通知和回调
+
+- [ ] 飞书个人消息可以发送。
+- [ ] 飞书交互卡片可以发送。
+- [ ] 卡片按钮回调可以被平台接收。
+- [ ] 回调验签失败不会执行业务动作。
+- [ ] 重复点击卡片不会重复创建反馈或转换草稿。
+- [ ] 通知成功和失败都有记录。
+
+## 6. 失败复盘
+
+- [ ] AI 解析失败有记录。
+- [ ] PostgreSQL AI 记忆读写失败有记录。
+- [ ] 人员映射缺失有记录。
+- [ ] 飞书登录失败有记录。
+- [ ] 飞书通知失败有记录。
+- [ ] 回调失败有记录。
+- [ ] 定时提醒触发失败有记录。
+- [ ] 管理员 / AI 团队可以处理失败并留下处理结果。
+
+## 7. 安全边界
+
+- [ ] 飞书通知只发摘要和链接。
+- [ ] 普通日志不含 API Key、App Secret、飞书 token。
+- [ ] 普通日志不含完整手机号和完整邮箱。
+- [ ] 不自动操作交易系统、历史数据库、后台管理系统或其他外部业务系统。
+- [ ] 第一版明确不做的功能没有混入主线。