AI-Secretary/docs/checklists/后端Review清单.md

后端 Review 清单

后端 Review 优先找风险、权限漏洞、状态错误、事务问题、缺测试和敏感信息泄漏。

1. 权限

• DRF permission class 覆盖入口权限。
• service 层覆盖业务权限。
• 普通员工不能给别人创建事项或提醒。
• 反馈人必须是事项或提醒接收人。
• 飞书身份没有直接绕过平台角色权限。
• 非老板机器人私聊不会触发 AI。
• 失败记录仅管理员 / AI 团队和必要管理角色可见。
• 权限、安全、日志脱敏、验签和幂等符合 docs/contracts/安全权限日志约定.md。

2. 状态流转

• 状态枚举与 docs/contracts/状态流转约定.md 一致。
• 状态变化集中在 service 层。
• 非法状态跳转返回明确错误。
• 已取消、已转换、已完成等终态不会被重复处理。
• 有问题反馈必须留下原因。

3. 事务和一致性

• 创建事项 / 提醒 / 通知 / 日志的事务边界清晰。
• 外部 API 失败不会造成业务状态误判。
• 通知失败不会标记已通知。
• 补发不会覆盖历史失败记录。
• scheduler 不绕过 service 直接改业务表。

4. 飞书

• 回调已验签。
• event_id 或 idempotency_key 幂等。
• 卡片重复点击幂等。
• 旧卡片、失效卡片、已替代草稿和已过期通知不会继续写业务对象。
• 通知内容只包含摘要和链接。
• 飞书 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 / unknown / unsupported 不创建事项或提醒。
• 实时问答不做交易判断。
• PromptContext 版本被记录。
• PostgreSQL AI 对话记忆只辅助理解和草稿修订，不替代正式业务表。
• PostgreSQL AI 记忆读写失败会写 memory_store_failed，不继续依赖内存确认草稿。
• 游戏化表达没有进入结构化字段。

6. 定时提醒

• 只支持一次性、每天、每周、每月。
• 不支持 cron 和复杂日历。
• 同一环境同一应用库同时只有一个 scheduler 进程。
• paused、cancelled 不触发。
• 触发幂等键覆盖提醒、时间、接收人和渠道。
• 触发失败可复盘。

7. 日志和失败

• 关键动作写 operation_logs。
• 失败写 failure_records。
• 失败记录包含类型、关联对象、原因、处理状态。
• 失败处理必须有处理结果。
• 日志包含操作人和渠道。
• OAuth code/state、回调验签密钥、一次性操作 token、完整手机号和完整邮箱没有进入普通日志。
• 模型原始请求/响应和飞书原始 payload 的访问范围受限。

8. 测试

• 单元测试覆盖权限、状态、AI 输出校验、飞书回调、提醒幂等。
• 失败路径有测试。
• 测试没有依赖真实飞书或真实百炼网络调用。
• 测试 fixture 不包含真实手机号、邮箱、token 或密钥。
• 每个 plan 完成前说明了新增或修改的 tests、覆盖的 spec / contract 约定和运行方式。

9. 文档同步

• 改接口同步 docs/contracts/API接口约定.md。
• 改字段同步 docs/contracts/数据对象约定.md。
• 改状态同步 docs/contracts/状态流转约定.md。
• 改权限、安全、日志脱敏、飞书验签或幂等同步 docs/contracts/安全权限日志约定.md。
• 改飞书逻辑同步 docs/specs/03_飞书通知与反馈.md。
• 改 AI 规则同步 docs/specs/01_老板AI秘书与AI草稿.md。