文档：完善泽源后端协作基线

2026-06-22 16:27:57 +08:00
parent 53a5260cac
commit fcbd728457
19 changed files with 2806 additions and 0 deletions
@@ -1 +1,106 @@
+# AGENTS.md

+本文件是给 AI 和开发者看的后端协作导航。开发任何后端功能前，先按本文件判断要读哪些 spec、contract、plan 和 checklist。
+
+## 项目一句话
+
+第一版要做一个公司内部 AI 协作最小闭环：
+
+```text
+老板一句话
+-> AI 草稿
+-> 人工确认
+-> 创建事项或定时提醒
+-> 飞书通知
+-> 接收人反馈
+-> 页面看到结果和失败记录
+```
+
+这不是完整任务系统、完整 AI 工作台、完整看板，也不是全自动 Agent。
+
+## 当前技术栈
+
+| 层级    | 约定                                          |
+| ----- | ------------------------------------------- |
+| 后端    | Python Django + Django REST Framework       |
+| ORM   | Django ORM + Django Migrations              |
+| 数据库   | MySQL 8，使用平台自有应用库                           |
+| 定时任务  | Django management command + 独立 scheduler 进程 |
+| 后台管理  | Django Admin                                |
+| AI 接入 | 阿里百炼 API，后端封装薄 `ai_client`                  |
+| 飞书    | 飞书身份登录、机器人私聊、个人消息、交互卡片和回调                   |
+| 部署    | Docker Compose + Nginx + Gunicorn           |
+|       |                                             |
+## 渐进式阅读规则
+
+普通任务只读：
+
+1. `AGENTS.md`
+2. 当前相关 `docs/specs/*.md`
+3. 当前 active plan
+
+涉及接口时再读：
+
+1. `docs/contracts/API接口约定.md`
+
+涉及数据库或字段时再读：
+
+1. `docs/contracts/数据对象约定.md`
+
+涉及状态流转时再读：
+
+1. `docs/contracts/状态流转约定.md`
+
+涉及飞书时再读：
+
+1. `docs/specs/03_飞书通知与反馈.md`
+2. `docs/contracts/API接口约定.md`
+
+涉及 Review 或提交前检查时再读：
+
+1. `docs/checklists/AI生成代码检查清单.md`
+2. `docs/checklists/后端Review清单.md`
+
+不要每次全量读取所有 docs，避免上下文过大、重点变散。
+
+## 事实源优先级
+
+1. `docs/contracts/` 是字段、接口、状态、错误码和全局约定的唯一事实源。
+2. `docs/specs/` 说明业务边界和模块目标，不复制完整字段表。
+3. `docs/plans/active/` 是当前施工依据，不用于偷偷改变业务边界。
+4. `docs/checklists/` 和测试是 Review 闸门。
+
+如果 spec 和 contract 冲突，以 contract 为准，并提出文档修正建议。
+
+## 生成代码禁止事项
+
+1. 不允许 AI 未经人工确认直接创建事项、提醒或发送通知。
+2. 不允许普通员工给别人创建事项或提醒。
+3. 不允许绕过后端权限校验，只靠前端隐藏按钮。
+4. 不允许自动操作交易系统、公司历史数据库、后台管理系统或其他外部业务系统。
+5. 不允许把 API Key、App Secret、飞书 token、完整手机号、完整邮箱写进代码或普通日志。
+6. 不允许把老板解释中的游戏化表达写进事项标题、接收人、时间、反馈要求等结构化字段。
+7. 不允许把第一版明确不做的功能混入主线。
+
+## AI 写代码推荐流程
+
+```text
+人确定任务
+-> AI 读 AGENTS.md
+-> AI 读对应 spec
+-> AI 检查 docs/plans/active/ 是否已有当前 plan
+-> 没有 plan：读必要 contracts，生成 plan 给人确认
+-> 已有 plan：只按当前 plan 执行
+-> AI 读 checklists
+-> AI 按 plan 写代码
+-> AI 自测
+-> 泽源跑测试
+-> 乔大卫 / 田宇 Review 关键代码
+-> 王一多验收闭环
+```
+
+active plan 是当前施工依据。除非发现 plan 明确不符合 spec/contracts，否则不要重新生成新 plan。
+
+## 第一版不做
+
+AI 工作台、技能市场、文件上传、多模态处理、会议纪要、日报、文档摘要、复杂反馈看板、复杂 BI、成本驾驶舱、完整工作流、完整项目管理、多级子任务、甘特图、复杂审批流、复杂组织架构、cron 表达式、日历系统、自动操作交易系统、自动操作历史数据库、自动读取员工本地文件、手机端网页完整适配、把飞书机器人开放为程经理或普通员工通用派活入口。