diff --git a/docs/GLM5_SIGNAL_PLANNER_IMPLEMENTATION_PLAN_V4.md b/docs/GLM5_SIGNAL_PLANNER_IMPLEMENTATION_PLAN_V4.md new file mode 100644 index 00000000..51f3d9d5 --- /dev/null +++ b/docs/GLM5_SIGNAL_PLANNER_IMPLEMENTATION_PLAN_V4.md @@ -0,0 +1,231 @@ +# GLM-5 Signal Planner + 增量任务包管理实施清单(可打勾执行版) + +> 使用规则:严格按步骤推进;每个步骤完成后再勾选;未完成禁止进入下一步。 + +## 0. 全局硬约束(执行前必须确认) +- [ ] 所有业务写操作必须通过 service/repository 入口调用。 +- [ ] 严禁在调用链路散落裸 ORM `insert/update/commit`。 +- [ ] 数据库结构改动仅通过 Alembic migration。 +- [ ] API 统一包络:`{code, message, data}`。 +- [ ] 后端契约变更必须同步前端 TS 类型与文档。 +- [ ] 删除任何代码前必须执行 `FIND_USAGE` 并留证据。 +- [ ] 发现违例立即停止并输出 `[VIOLATION: 裸写位置]`。 +- [ ] 模型选择必须接口化配置,禁止在业务代码写死 `provider/model/api_env`。 + +## 1. 执行总览(里程碑) +- [ ] Step 0:基线文档与自动增量机制 +- [ ] Step 1:Signal Planner 数据层改造 +- [ ] Step 2:写入服务收口(StrategicAnalysis + Outbox) +- [ ] Step 3:SignalPlannerService 接入 +- [ ] Step 4:主链路触发与路由配置 +- [ ] Step 5:模型灵活配置(接口化,禁止写死) +- [ ] Step 6:前端展示与侧边栏新增功能 +- [ ] Step 7:脏代码/无用代码删减 +- [ ] Step 8:验收与交付 + +--- + +## Step 0:基线文档与自动增量机制 +### 入口条件 +- [ ] 项目当前主分支可读,文档目录可写。 + +### 执行项 +- [ ] 新建 `docs/architecture/MASTER_CONTRACT.md` +- [ ] 新建 `docs/architecture/API_CONTRACTS.md` +- [ ] 新建 `docs/architecture/DATAFLOW.md` +- [ ] 新建 `docs/architecture/TASK_BRIEF_TEMPLATE.md` +- [ ] 新建 `scripts/gen_task_brief.sh`(自动生成增量任务包) +- [ ] 新建 `scripts/check_contract_sync.sh`(契约同步检查) +- [ ] CI 增加 contract-check job + +### 完成标志 +- [ ] 本地可自动生成一份有效增量任务包 +- [ ] CI 可检测契约文档未同步并正确失败 + +--- + +## Step 1:Signal Planner 数据层改造 +### 入口条件 +- [ ] Step 0 完成 + +### 执行项 +- [ ] 新增 migration:`signals.planner_status VARCHAR(20) DEFAULT 'pending'` +- [ ] 新增 migration:`signals.planner_analyzed_at TIMESTAMP` +- [ ] 新增 migration:`signals.planner_assignee_user_id INTEGER` +- [ ] 为 `planner_status` 增加索引 +- [ ] 同步更新 `backend/app/models/signal.py` + +### 完成标志 +- [ ] `alembic upgrade` 后表结构正确 +- [ ] ORM 模型可读写三字段 + +--- + +## Step 2:写入服务收口 +### 入口条件 +- [ ] Step 1 完成 + +### 执行项 +- [ ] 新建 `backend/app/services/signal_strategic_analysis_service.py` +- [ ] 实现 `merge_and_save(db, signal_id, planner_result, tenant_id)` +- [ ] 实现 `mark_failed(db, signal_id, tenant_id, reason)` +- [ ] 新建 `backend/app/services/feishu_outbox_service.py` +- [ ] 实现 `enqueue(db, chat_id, text, source_message_id, dedupe_seed)` +- [ ] 幂等策略复用 `reply_hash`,不新增 outbox 冗余字段 + +### 完成标志 +- [ ] 新增 service 覆盖 Planner 写回与补发入队 +- [ ] 新增 service 文件中无业务外层裸写调用 + +--- + +## Step 3:SignalPlannerService 接入 +### 入口条件 +- [ ] Step 2 完成 + +### 执行项 +- [ ] 新建 `backend/app/services/signal_planner_service.py` +- [ ] `analyze(...)` 内部使用独立 `AsyncSessionLocal` +- [ ] 上下文查询使用现网字段:`signals.matched_project_id` +- [ ] 成员查询通过 `user_projects -> users -> user_workloads -> user_skill_bindings -> skill_tags` +- [ ] 调用 `llm_service.generate_structured_object(function_name="signal_planner_analyze")` +- [ ] 成功路径调用 `SignalStrategicAnalysisService.merge_and_save` +- [ ] 失败路径调用 `SignalStrategicAnalysisService.mark_failed` +- [ ] 补发路径调用 `FeishuOutboxService.enqueue` + +### 完成标志 +- [ ] Planner 失败不阻断主链路 +- [ ] Planner 成功后 `strategic_analysis.ai_planner` 写回成功 + +--- + +## Step 4:主链路触发与路由配置 +### 入口条件 +- [ ] Step 3 完成 + +### 执行项 +- [ ] 修改 `backend/app/services/ai_pmo_kernel_service.py` +- [ ] `signal.create` 成功提交后 `create_task(SignalPlannerService.analyze(...))` +- [ ] 在 `backend/app/config/ai_prompts.py` 增加 `PROMPT_SIGNAL_PLANNER` +- [ ] 在 LLM 结构化 schema 注册 `signal_planner_analyze` +- [ ] 更新 `/.openclaw/pmflow-routing-rules.json` 添加 high tier 路由 + +### 完成标志 +- [ ] 触发点仅在 commit 后 +- [ ] 路由命中 `signal_planner_analyze` + +--- + +## Step 5:模型灵活配置(接口化,禁止写死) +### 入口条件 +- [ ] Step 4 完成 + +### 执行项 +- [ ] 新建后端配置接口:`backend/app/api/model_routing.py` +- [ ] 新建后端服务:`backend/app/services/model_routing_service.py` +- [ ] 提供查询接口:按 `function_name` 读取当前生效模型路由 +- [ ] 提供更新接口:按 `function_name` 更新 `provider/model/api_env/tier` +- [ ] 配置持久化到统一配置源(数据库 Integration 或统一配置表) +- [ ] `SignalPlannerService` 改为运行时读取 `signal_planner_analyze` 路由配置,不在代码中写死模型 +- [ ] 保留默认兜底:当配置缺失时走安全默认路由,但记录告警日志 +- [ ] 增加权限控制:仅管理员可修改模型路由配置 +- [ ] 增加审计:每次配置变更写 `operation_log` + +### 完成标志 +- [ ] 通过接口切换模型后,Planner 无需改代码即可生效 +- [ ] 业务代码中不存在写死的 `signal_planner_analyze -> MiniMax-M2.5` 绑定 + +--- + +## Step 6:前端展示与侧边栏新增功能 +### 入口条件 +- [ ] Step 5 完成 + +### 执行项(Signal 展示) +- [ ] 修改 `backend/app/api/sstc.py` 返回 planner 字段与 `strategic_analysis` +- [ ] 修改 `frontend/src/api/sstc.ts` 扩展 `SSTCSignal` 类型 +- [ ] 修改 `frontend/src/components/sstc/SignalContentHoverCard.tsx` +- [ ] `planner_status=pending` 显示“AI 分析中...” +- [ ] `planner_status=completed` 显示分析区块 +- [ ] `planner_status=failed` 不显示分析区块 + +### 执行项(侧边栏任务包管理) +- [ ] 修改 `frontend/src/components/layout/Sidebar.tsx` 增加入口:`增量任务包中心` +- [ ] 修改 `frontend/src/components/layout/Sidebar.tsx` 增加入口:`任务包模板管理` +- [ ] 修改 `frontend/src/components/layout/Sidebar.tsx` 增加入口:`任务包生成记录` +- [ ] 修改 `frontend/src/components/layout/Sidebar.tsx` 增加入口:`契约同步看板` +- [ ] 新建页面 `frontend/src/pages/TaskBriefCenterPage.tsx` +- [ ] 新建页面 `frontend/src/pages/TaskBriefTemplatePage.tsx` +- [ ] 新建页面 `frontend/src/pages/TaskBriefRunsPage.tsx` +- [ ] 新建页面 `frontend/src/pages/ContractSyncBoardPage.tsx` +- [ ] 修改 `frontend/src/router/index.tsx` 注册新路由 +- [ ] 新建 `frontend/src/api/taskBriefs.ts` +- [ ] 新建后端 `backend/app/api/task_briefs.py` +- [ ] 新建后端 `backend/app/services/task_brief_service.py` +- [ ] 新增模型路由管理入口:`模型路由配置` +- [ ] 新建页面 `frontend/src/pages/ModelRoutingConfigPage.tsx` +- [ ] 新建前端 API `frontend/src/api/modelRouting.ts` +- [ ] 页面通过接口读取/更新 `signal_planner_analyze` 模型映射 + +### 完成标志 +- [ ] 侧边栏 4 个新入口均可访问 +- [ ] 任务包管理基础流程可跑通 +- [ ] 模型路由可在前端页面配置并即时生效 + +--- + +## Step 7:脏代码/无用代码删减(强制) +### 入口条件 +- [ ] Step 6 完成 + +### 执行项 +- [ ] 清理未使用 imports/variables/functions/components/routes +- [ ] 清理重复工具函数与废弃 fallback 分支 +- [ ] 删除无效 feature flag 与历史临时代码 +- [ ] 清理无引用 API 封装与页面入口 +- [ ] 每一处删除前后均有 `FIND_USAGE` 结果留档 + +### 门禁 +- [ ] PR 附“删除清单 + 引用扫描结果” +- [ ] 删除后构建与回归通过,否则回退该删除批次 + +### 完成标志 +- [ ] 无死代码残留在本次改动链路 +- [ ] 无跨域误删 + +--- + +## Step 8:验收与交付 +### 入口条件 +- [ ] Step 7 完成 + +### 功能验收 +- [ ] 飞书触发后信号主链路正常入库 +- [ ] 30 秒内 `planner_status=completed` +- [ ] `strategic_analysis.ai_planner` 非空 +- [ ] 相同消息补发不重复入队 +- [ ] 通过模型路由接口切换模型后,Planner 走新模型且结果正常 + +### 数据库只读验收 +- [ ] 执行: + - `SELECT planner_status, planner_analyzed_at, strategic_analysis->'ai_planner' FROM signals ORDER BY created_at DESC LIMIT 1;` +- [ ] 三项均符合预期 + +### 构建验收 +- [ ] `python -m py_compile` 通过 +- [ ] `npm run build` 通过 +- [ ] `tsc --noEmit` 零错误 + +### 文档验收 +- [ ] `MASTER_CONTRACT.md` 同步 +- [ ] `API_CONTRACTS.md` 同步 +- [ ] `DATAFLOW.md` 同步 +- [ ] `CLAUDE.md` 同步 + +### 交付物 +- [ ] 变更文件清单 +- [ ] 飞书补发记录截图 +- [ ] 数据库查询截图 +- [ ] 侧边栏新增功能截图 +- [ ] 模型路由接口调用与生效截图 +- [ ] 脏代码删减清单与 `FIND_USAGE` 证据