talesofzes
5.2 KiB
5.2 KiB
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。 - 涉及权限、安全、日志脱敏、飞书验签或幂等时已读
docs/contracts/安全权限日志约定.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/unknown/unsupported不创建事项、提醒或通知。- 实时问答第一版只做暂不支持提示，不做交易判断。
need_more_info最多 3 个问题、最多 3 轮追问。- PostgreSQL AI 对话记忆只辅助理解和草稿修订，不替代任务、提醒、通知等正式业务表。
- 结构化字段没有写入游戏化表达。
- 模型调用记录了背景摘要、老板风格和业务规则版本。
- AI 解析失败会写
model_call_logs和failure_records。
5. 状态
- 草稿、事项、提醒、通知、反馈、失败记录的状态枚举来自
状态流转约定.md。 - 非法状态跳转返回
state_conflict。 - 已取消对象不能继续转换、通知或反馈。
converted草稿不会重复转换。- 通知失败不会被标记为已通知。
- 有问题反馈必须填写原因。
6. 飞书
- 飞书回调必须验签。
- 飞书事件使用
event_id或idempotency_key幂等。 - 卡片重复点击不会重复创建事项、提醒或反馈。
- 旧卡片、失效卡片、已替代草稿和已过期通知只记录事件，不写业务对象。
- 飞书通知只发送摘要和链接。
- 非老板机器人访问不会调用 AI。
- 回调失败会写
feishu_events和failure_records。
7. 定时提醒
- scheduler 独立于 Gunicorn worker 运行。
- 同一环境同一应用库同时只有一个 scheduler 进程运行。
- 只有
active提醒会触发。 paused和cancelled不会触发。- 同一提醒、同一触发时间、同一接收人、同一渠道只生成一条有效通知。
- 触发失败会写失败记录。
8. 事务和幂等
- 创建事项或提醒、创建通知、写日志在事务边界内处理。
- 外部调用失败不会留下半截错误状态。
- 补发保留原失败记录和新发送结果。
- 重复请求不会重复执行业务动作。
9. 日志和敏感信息
- 关键动作写
operation_logs。 - 失败写
failure_records。 - 普通日志不包含 API Key、App Secret、飞书 token。
- 普通日志不包含完整手机号或完整邮箱。
- 原始错误摘要不包含密钥。
- OAuth code/state、回调验签密钥、一次性操作 token 明文不进入日志或业务表。
model_call_logs原始请求/响应和feishu_events.raw_payload访问范围受限。
10. 测试
- 权限测试覆盖普通员工不能给别人创建事项或提醒。
- 状态测试覆盖非法跳转。
- 飞书测试覆盖验签失败、幂等重复事件和非接收人反馈。
- 定时测试覆盖重复触发防护。
- 事务测试覆盖通知失败不留下半截数据。
- AI 测试覆盖解析失败、实时问答和人工确认边界。
- 每个 plan 完成前已说明新增或修改了哪些 tests、覆盖哪些 spec / contract 约定、如何运行。
11. 文档同步
- 改接口同步
docs/contracts/API接口约定.md。 - 改字段同步
docs/contracts/数据对象约定.md。 - 改状态同步
docs/contracts/状态流转约定.md。 - 改权限、安全、日志脱敏、飞书验签或幂等同步
docs/contracts/安全权限日志约定.md。 - 改飞书逻辑同步
docs/specs/03_飞书通知与反馈.md。 - 改 AI 规则同步
docs/specs/01_老板AI秘书与AI草稿.md。