# 老板一句话闭环 Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** 建立第一版后端最小闭环：老板一句话生成 AI 草稿，人工确认后创建事项或提醒，通过飞书通知接收人并记录反馈和失败。 **Architecture:** 使用 Django 模块化单体。DRF view 负责请求入口，serializer 负责入参出参校验，service 负责权限、状态流转、事务和幂等，client 负责阿里百炼和飞书外部调用，audit 负责操作日志和失败记录。 **Tech Stack:** 部署 Python 3.12.13、本地开发 Python 3.11/3.12、Django 5.2 LTS、Django REST Framework、Django ORM、MySQL 8、Django management command scheduler、阿里百炼 API、飞书开放平台。 --- ## 施工前必须阅读 1. `AGENTS.md` 2. `ARCHITECTURE.md` 3. `docs/specs/01_老板AI秘书与AI草稿.md` 4. `docs/specs/02_事项任务.md` 5. `docs/specs/03_飞书通知与反馈.md` 6. `docs/specs/04_定时提醒.md` 7. `docs/specs/05_权限日志失败记录.md` 8. `docs/contracts/API接口约定.md` 9. `docs/contracts/数据对象约定.md` 10. `docs/contracts/状态流转约定.md` 11. `docs/checklists/AI生成代码检查清单.md` 12. `docs/checklists/后端Review清单.md` ## 范围边界 本计划只做第一版最小闭环： ```text 老板一句话 -> AI 草稿 -> 人工确认 -> 创建事项或定时提醒 -> 飞书通知 -> 接收人反馈 -> 页面/API/Admin 可看到结果和失败记录 ``` 本计划不做 AI 工作台、技能市场、文件上传、多模态处理、会议纪要、日报、文档摘要、复杂反馈看板、复杂 BI、成本驾驶舱、完整工作流、完整项目管理、多级子任务、甘特图、复杂审批流、复杂组织架构、cron 表达式、日历系统、自动操作交易系统、自动操作历史数据库、自动读取员工本地文件、手机端网页完整适配，也不把飞书机器人开放为程经理或普通员工通用派活入口。 ## 可执行性门禁 1. 本计划先跑通 mock-first 后端闭环；单元测试和最小闭环测试不得访问真实百炼、真实飞书或公网回调。 2. 真实联调前必须确认飞书正式应用、HTTPS 回调地址、个人消息权限、交互卡片权限、老板 / 程经理 / 第一批试用人员映射，以及百炼 API Key 环境变量。 3. Docker / 部署环境固定 Python 3.12.13；本地开发允许 Python 3.11 或 3.12，但提交前必须在 Python 3.12.13 环境跑完整测试。 4. scheduler 必须作为独立进程运行，同一环境同一应用库同时只能启动一个 scheduler 进程。 ## 文件结构 第一轮代码施工建议创建这些目录和文件： ```text requirements.txt manage.py config/ __init__.py settings.py urls.py wsgi.py apps/ accounts/ people/ prompts/ audit/ drafts/ tasks/ reminders/ notifications/ feedbacks/ feishu/ tests/ ``` 每个 Django app 采用统一结构： ```text apps// __init__.py admin.py apps.py models.py serializers.py services.py urls.py views.py tests/ ``` 外部 API 封装放在： ```text apps/drafts/ai_client.py apps/feishu/client.py apps/feishu/signature.py ``` --- ### Task 1: Django 项目骨架和依赖基线 **Files:** - Create: `requirements.txt` - Create: `manage.py` - Create: `config/__init__.py` - Create: `config/settings.py` - Create: `config/urls.py` - Create: `config/wsgi.py` - Create: `apps/__init__.py` - Create: `apps/accounts/__init__.py` - Create: `apps/accounts/apps.py` - Create: `apps/people/__init__.py` - Create: `apps/people/apps.py` - Create: `apps/prompts/__init__.py` - Create: `apps/prompts/apps.py` - Create: `apps/audit/__init__.py` - Create: `apps/audit/apps.py` - Create: `apps/drafts/__init__.py` - Create: `apps/drafts/apps.py` - Create: `apps/tasks/__init__.py` - Create: `apps/tasks/apps.py` - Create: `apps/reminders/__init__.py` - Create: `apps/reminders/apps.py` - Create: `apps/notifications/__init__.py` - Create: `apps/notifications/apps.py` - Create: `apps/feedbacks/__init__.py` - Create: `apps/feedbacks/apps.py` - Create: `apps/feishu/__init__.py` - Create: `apps/feishu/apps.py` - [ ] **Step 1: 写依赖文件** `requirements.txt` 第一版固定包含： ```txt Django==5.2.15 djangorestframework==3.17.1 mysqlclient==2.2.8 asgiref==3.11.1 sqlparse==0.5.5 tzdata==2026.2 python-dotenv==1.2.2 requests==2.34.2 httpx==0.28.1 APScheduler==3.11.2 django-apscheduler==0.7.0 dashscope==1.25.23 alibabacloud-bailian20231229==2.13.1 lark-oapi==1.6.8 PyJWT==2.13.0 cryptography==49.0.0 gunicorn==26.0.0 ``` - [ ] **Step 2: 创建 Django 项目骨架和 app 空壳** 使用 `config` 作为项目配置包，`apps` 作为业务 app 根目录。Task 1 必须先创建所有业务 app 的 `__init__.py` 和 `apps.py`，保证后续加入 `INSTALLED_APPS` 时可导入。 - [ ] **Step 3: 配置 settings** `config/settings.py` 必须包含： 1. `INSTALLED_APPS` 加入 Django contrib app、DRF，以及已创建且可导入的业务 app 空壳。 2. Task 1 暂不设置 `AUTH_USER_MODEL`；Task 2 实现 `apps.accounts.models.User` 后、首次 `makemigrations` / `migrate` 前再设置 `AUTH_USER_MODEL = "accounts.User"`。 3. 数据库配置读取环境变量。 4. 飞书和百炼密钥只读取环境变量。 5. 日志配置避免输出密钥。 - [ ] **Step 4: 运行 Django 检查** Run: ```bash python manage.py check ``` Expected: `System check identified no issues`。 --- ### Task 2: 账号、人员映射、Prompt 和审计基础模型 **Files:** - Modify: `config/settings.py` - Create: `apps/accounts/models.py` - Create: `apps/people/models.py` - Create: `apps/prompts/models.py` - Create: `apps/audit/models.py` - Create: `apps/accounts/admin.py` - Create: `apps/people/admin.py` - Create: `apps/prompts/admin.py` - Create: `apps/audit/admin.py` - Test: `apps/accounts/tests/test_permissions.py` - Test: `apps/audit/tests/test_sensitive_logging.py` - [ ] **Step 1: 实现自定义 User** 字段必须覆盖 `docs/contracts/数据对象约定.md` 中的 `users`。实现后立刻在 `config/settings.py` 设置 `AUTH_USER_MODEL = "accounts.User"`，且必须发生在第一次迁移之前。 - [ ] **Step 2: 实现 PersonMapping** 字段必须覆盖 `person_mappings`，并支持别名 JSON。 - [ ] **Step 3: 实现 PromptContext** 支持 `company_background`、`boss_style`、`business_rules` 三类上下文，只允许同类一个 `active` 版本。 - [ ] **Step 4: 实现 FailureRecord、OperationLog、ModelCallLog** 失败类型和状态必须来自 `docs/contracts/状态流转约定.md`。 - [ ] **Step 5: 写权限和脱敏测试** 测试必须覆盖： 1. 普通员工不能访问失败记录列表。 2. 普通日志工具不会输出完整手机号。 3. 普通日志工具不会输出完整邮箱。 4. 日志元数据不会保存 API Key、App Secret 或飞书 token。 - [ ] **Step 6: 生成并运行迁移** Run: ```bash python manage.py makemigrations python manage.py migrate python manage.py test apps.accounts apps.audit ``` Expected: migrations 成功，测试通过。 --- ### Task 3: AI 草稿模型、AI 输出校验和解析服务 **Files:** - Create: `apps/drafts/models.py` - Create: `apps/drafts/serializers.py` - Create: `apps/drafts/ai_client.py` - Create: `apps/drafts/services.py` - Create: `apps/drafts/views.py` - Create: `apps/drafts/urls.py` - Test: `apps/drafts/tests/test_ai_output_validator.py` - Test: `apps/drafts/tests/test_parse_service.py` - [ ] **Step 1: 实现 AiDraft 模型** 字段必须覆盖 `ai_drafts`，状态必须来自 `状态流转约定.md`。 - [ ] **Step 2: 实现 AI 输出 validator** validator 必须校验： 1. JSON 可解析。 2. `draft_type` 在允许范围内。 3. `task` / `reminder` 才允许 `should_create_draft = true`。 4. `qa` / `realtime_qa` 必须有 `answer`，且不得创建事项、提醒或通知。 5. `follow_up_questions` 最多 3 个。 6. `route_type` 在允许范围内。 7. 结构化字段不得包含明显游戏化表达。 - [ ] **Step 3: 实现可 mock 的 ai_client** `ai_client` 只封装阿里百炼调用，不修改业务表。测试中必须使用 mock，不访问真实网络。 - [ ] **Step 4: 实现 parse service** service 流程： ```text 加载 active prompt_contexts -> 调用 ai_client -> 写 model_call_logs -> 校验 JSON -> 成功创建 ai_drafts -> 失败创建 parse_failed 草稿和 failure_records ``` - [ ] **Step 5: 实现 API** 实现： 1. `POST /api/ai-drafts/parse` 2. `GET /api/ai-drafts` 3. `GET /api/ai-drafts/{id}` 4. `PATCH /api/ai-drafts/{id}` 5. `POST /api/ai-drafts/{id}/cancel` 6. `POST /api/ai-drafts/{id}/follow-up` - [ ] **Step 6: 跑测试** Run: ```bash python manage.py test apps.drafts ``` Expected: AI 输出校验、解析失败、实时问答、补充/重说测试全部通过。 --- ### Task 4: 事项、提醒、通知和反馈模型与服务 **Files:** - Create: `apps/tasks/models.py` - Create: `apps/tasks/services.py` - Create: `apps/tasks/views.py` - Create: `apps/reminders/models.py` - Create: `apps/reminders/services.py` - Create: `apps/reminders/views.py` - Create: `apps/notifications/models.py` - Create: `apps/notifications/services.py` - Create: `apps/feedbacks/models.py` - Create: `apps/feedbacks/services.py` - Test: `apps/tasks/tests/test_task_permissions.py` - Test: `apps/reminders/tests/test_reminder_permissions.py` - Test: `apps/feedbacks/tests/test_feedback_rules.py` - [ ] **Step 1: 实现模型** 字段必须覆盖 `tasks`、`reminders`、`notifications`、`feedbacks`。 - [ ] **Step 2: 实现事项 service** 必须支持： 1. 老板和程经理创建事项。 2. 普通员工不能给别人创建事项。 3. 程经理确认复杂事项。 4. 通知失败保留失败状态。 5. 有问题反馈必须填写原因。 - [ ] **Step 3: 实现提醒 service** 必须支持： 1. 所有人创建自己的提醒。 2. 老板和程经理给别人创建提醒。 3. 普通员工不能给别人创建提醒。 4. 一次性、每天、每周、每月重复规则。 5. 暂停、恢复、取消。 - [ ] **Step 4: 实现通知和反馈 service** 必须支持： 1. 生成飞书通知记录。 2. 使用幂等键避免重复通知。 3. 接收人反馈。 4. 非接收人反馈返回 `permission_denied`。 - [ ] **Step 5: 实现 API** 按 `docs/contracts/API接口约定.md` 实现 tasks、reminders、notifications、feedbacks 相关接口。 - [ ] **Step 6: 跑测试** Run: ```bash python manage.py test apps.tasks apps.reminders apps.notifications apps.feedbacks ``` Expected: 权限、状态、反馈原因和通知失败测试通过。 --- ### Task 5: 飞书登录、机器人事件和卡片回调 **Files:** - Create: `apps/feishu/models.py` - Create: `apps/feishu/client.py` - Create: `apps/feishu/signature.py` - Create: `apps/feishu/services.py` - Create: `apps/feishu/views.py` - Create: `apps/feishu/urls.py` - Test: `apps/feishu/tests/test_signature.py` - Test: `apps/feishu/tests/test_event_idempotency.py` - Test: `apps/feishu/tests/test_bot_access.py` - Test: `apps/feishu/tests/test_card_callback.py` - [ ] **Step 1: 实现 FeishuEvent 和 FeishuAuthSession** 字段必须覆盖 `feishu_events` 和 `feishu_auth_sessions`。 本任务所有测试必须 mock 飞书 SDK / HTTP client，不依赖真实飞书应用、公网回调或个人消息权限。 - [ ] **Step 2: 实现验签** 验签失败返回 `feishu_signature_invalid`，不得执行业务动作。 - [ ] **Step 3: 实现事件幂等** 同一 `event_id` 重放时只返回已有处理结果，不重复创建草稿、事项、提醒或反馈。 - [ ] **Step 4: 实现老板机器人入口** 非老板私聊机器人时： ```text 不调用 AI 不生成草稿 回复当前入口仅对老板开放 写 unauthorized_bot_access 失败记录 ``` - [ ] **Step 5: 实现卡片回调** 支持： 1. 老板确认草稿。 2. 老板补充/重说。 3. 老板取消草稿。 4. 接收人反馈事项或提醒。 5. 程经理待确认提醒只跳转平台。 - [ ] **Step 6: 跑测试** Run: ```bash python manage.py test apps.feishu ``` Expected: 验签、幂等、非老板访问、卡片反馈测试通过。 --- ### Task 6: 草稿转换、事项通知和提醒调度闭环 **Files:** - Modify: `apps/drafts/services.py` - Modify: `apps/tasks/services.py` - Modify: `apps/reminders/services.py` - Modify: `apps/notifications/services.py` - Create: `apps/reminders/management/commands/run_reminder_scheduler.py` - Test: `apps/drafts/tests/test_convert_draft.py` - Test: `apps/reminders/tests/test_scheduler.py` - Test: `apps/notifications/tests/test_notification_retry.py` - [ ] **Step 1: 实现草稿确认和转换** `confirmed -> converted` 只允许执行一次。`task` 草稿转换为事项，`reminder` 草稿转换为提醒。 - [ ] **Step 2: 实现复杂事项转程经理确认** `route_type = manager_confirm` 时创建程经理待确认记录，并生成给程经理的飞书提醒。 - [ ] **Step 3: 实现 scheduler command** 命令名： ```bash python manage.py run_reminder_scheduler ``` scheduler 只扫描 `active` 且 `next_trigger_at <= now` 的提醒。一次性提醒成功触发后走 `active -> triggered`；每天、每周、每月提醒成功触发后保持 `active`，只更新 `last_triggered_at` 和下一次 `next_trigger_at`。 同一环境同一应用库只允许一个 scheduler 进程运行；测试中要用幂等键验证重复扫描不会重复创建通知。 - [ ] **Step 4: 实现提醒触发幂等** 幂等键： ```text reminder_id + trigger_time + receiver_id + notification_channel ``` - [ ] **Step 5: 实现通知补发** 补发必须保留原失败记录，并写新的通知发送结果。 - [ ] **Step 6: 跑测试** Run: ```bash python manage.py test apps.drafts apps.reminders apps.notifications ``` Expected: 草稿不重复转换、提醒不重复触发、通知补发测试通过。 --- ### Task 7: Admin、路由汇总、最小验收脚本 **Files:** - Modify: `config/urls.py` - Modify: `apps/*/admin.py` - Create: `tests/test_minimal_closure.py` - Modify: `README.md` - [ ] **Step 1: 汇总 API 路由** `config/urls.py` 挂载： 1. `/api/ai-drafts/` 2. `/api/tasks/` 3. `/api/reminders/` 4. `/api/notifications/` 5. `/api/feedbacks/` 6. `/api/failure-records/` 7. `/api/feishu/` 8. `/api/auth/feishu/` - [ ] **Step 2: 注册 Admin** Admin 至少可查看和维护： 1. 用户。 2. 人员映射。 3. Prompt 上下文。 4. AI 草稿。 5. 事项。 6. 提醒。 7. 通知。 8. 反馈。 9. 失败记录。 10. 操作日志。 11. 模型调用日志。 12. 飞书事件。 - [ ] **Step 3: 写最小闭环测试** 测试覆盖： ```text boss 用户提交一句话 -> mock AI 返回 task 草稿 -> boss 确认 -> 创建事项 -> mock 飞书通知成功 -> 接收人反馈 completed -> 事项状态 completed -> 有操作日志和通知记录 ``` - [ ] **Step 4: 更新 README 本地启动** 补充： 1. 安装依赖。 2. 环境变量。 3. 迁移。 4. 创建测试用户。 5. 启动 Web。 6. 启动 scheduler。 7. 运行测试。 - [ ] **Step 5: 跑完整测试** Run: ```bash python manage.py test python manage.py check ``` Expected: 全部测试通过，Django check 无错误。 --- ## 完成标准 1. 所有模型字段与 `docs/contracts/数据对象约定.md` 一致。 2. 所有状态与 `docs/contracts/状态流转约定.md` 一致。 3. 所有接口路径与 `docs/contracts/API接口约定.md` 一致。 4. AI 只生成草稿，人工确认后才创建事项或提醒。 5. 普通员工不能给别人创建事项或提醒。 6. 飞书回调验签和幂等有测试。 7. 定时提醒重复触发防护有测试。 8. 通知失败、AI 解析失败、回调失败有失败记录。 9. 普通日志不包含密钥、token、完整手机号或完整邮箱。 10. `python manage.py test` 和 `python manage.py check` 通过。 ## 执行备注 如果执行中发现本计划与 spec 或 contracts 冲突，以 contracts 为准，并先提出计划变更建议；不要偷偷修改业务边界。