Hermes CI Fix
be71c2296e
全PASS: Bot建议→unapplied→人apply→目标生效+apply_detail before/after→低危kpi-result source_batch落库→audit L2留痕→清理回查=0
7.3 KiB
7.3 KiB
Bot 写操作分级 + 分层授权审计清单（2026-09-03）
任务: P0-② CMA Bot写操作分级 + 分层授权落地（低危直写留痕 / 高危建议待批） 依据: CMA交互架构规范_三区分工模型_v1.md 第5节 + 5.1 分层授权模型（任总 2026-09-03 拍板） 代码权威注释: backend/app/risk_levels.py 文件头「写操作语义分级」段 配套端点: backend/app/api/bot_suggestions.py（新增，Bot高危建议创建通道）
一、两套分级的正交关系（防误读）
| 维度 | 名称 | 作用 | 载体 |
|---|---|---|---|
| 技术风险分级 | L1 只读 / L2 业务写 / L3 批量写 / L4 危险不开放 | 约束操作面、批量、写前校验 | API_RISK_MAP + @risk_level 装饰器 |
| 业务写语义分级 | low（规则型数据写，Bot直写+留痕） / high（考核基准/资源承诺，Bot只能建议） | 约束"写的是不是考核基准"，落地为行为约束 | 本清单 + 代码注释 |
关系：low = 现有 L2/L3 直写端点行为不变；high = Bot API面不提供直写端点，只走建议通道端点（本身按 L2 标注）。本任务未替代、未改动 L1-L4 体系，只在其上补业务语义约束。
二、端点审计清单（Bot API面全量）
只读（L1，无写语义，不属于 low/high）
- GET /api/cma/bot/ping · overview · kpis · kpis/{kpi_id}/history · strategic-maps · alerts · budget/plans · cost/standard · cost/actual · actions · organization · data-sources · users · query · okr/list · nlp · iron-law · iron-law/bots · risk-levels
- GET /api/cma/bot-kpis
- GET /api/cma/bot-bridge/verify/{action_plan_id}/history
low = Bot 直写 + 留痕（规则型、写库即生效；audit_log.bot_audit_middleware 全量覆盖 /api/cma/bot* 路径）
| 端点 | L级 | 写什么 | 留痕机制 | 归类依据 |
|---|---|---|---|---|
| POST /api/cma/bot/kpi-value-with-check | L2 | KPI实际值（upsert）+联动预警 | audit_log + source_type=bot | 数据搬运，规则明确 |
| POST /api/cma/bot-bridge/kpi-result | L2 | KPI实际值（upsert） | audit_log + source_batch=source | 同上（PRD第七部分数据通道） |
| POST /api/cma/bot-kpis/{kpi_id}/value | L2 | KPI实际值（upsert） | audit_log | Bot KPI看板值更新 |
| POST /api/cma/bot/import | L3 | Excel批量导入KPI实际值 | audit_log + rows | 批量数据导入 |
| POST /api/cma/bot-bridge/mpm-result | L3 | MPM结果→KPI实际值 | audit_log + rows | 批量分析结果落库 |
| POST /api/cma/bot-bridge/verify/{action_plan_id} | L2 | 轻量验证记录（verify_log，无回填） | audit_log | 行动方案验证状态 |
| POST /api/cma/bot/okr/create | L2 | 创建OKR Objective | audit_log | 管理类业务写（目标创建，保留评审：列P1待办） |
| POST /api/cma/bot/kpis/create-with-links | L3 | 创建新KPI定义+因果链 | audit_log + rows | 建KPI标准动作（本任务收口见下） |
high = 建议通道（无直写端点，人审批后生效）
| 端点 | L级 | 语义 | 生效路径 |
|---|---|---|---|
| POST /api/cma/bot/ai/suggestions（本任务新增） | L2 | Bot创建 kpi_target/budget_adjust/action_plan 建议，status 恒 unapplied | UI AI建议中心（SuggestionCenter.vue）→ 人 apply → /api/cma/ai/suggestions/{id}/apply 写库 + apply_detail(before/after) + applied_by/applied_at |
三、直写 KPI 目标值/预算审批端点审计结论（grep 实证）
- KPI 目标值直写：grep
target_value|目标值全 backend/app —— bot_bridge.py / bot_bridge_v2.py / bot_kpis.py 中target_value仅出现在读响应（查询返回 kpi.target_value）与验证引擎（value>target 比较），无任何修改现有 KPI target_value 的 Bot 端点。存量 KPI 目标修改只经/api/cma/ai/suggestions/{id}/apply（require_auth 人token）。 - 收口项（发现并处理）：
POST /api/cma/bot/kpis/create-with-links原允许 payload 带target_value随新建 KPI 一并写入（Bot 间接直写初始目标值=考核基准）。2026-09-03 已收口：传入非零 target_value → 400 明确拒绝，指引省略（人工设定）或走建议通道；0/省略不受影响。 - 预算审批直写：Bot API面预算相关端点仅 GET /api/cma/bot/budget/plans（只读）；budget.py / budget_generate.py 均挂在人工 require_role 路由下。Bot 无任何预算写端点。
- 阈值类（红黄绿）：监测参数类（Bot建议+人批量确认）本轮未开放 Bot 直写也未开放批量确认 UI——列入 P1 待办（见六），不阻塞本单验收。
四、高危审批留痕闭环（M3 实证结论）
- kpi_target applier（ai_suggestions.py
_apply_kpi_target）已含 before→after 留痕：apply_detail=[{target_type,target_id,target_name,action,before,after}] 写入 ai_suggestions.apply_detail，同时写 OperationLog(detail 含 suggestion_id/before/after)；apply_suggestion 置 status=applied + applied_by/applied_user_id/applied_at。无需补代码（E2E 断言验证）。 - SuggestionCenter.vue：默认展示 unapplied（statusFilter 默认 'unapplied'）+ 新增 suggestion_type 过滤（全部/kpi_target/budget_adjust/action_plan），小改无重构。
五、留痕链路（低危直写）
- bot_audit_middleware（backend/app/api/audit_log.py）对路径前缀 /api/cma/bot* 全部请求写 JSON 行至 backend/logs/bot_audit.log，字段: timestamp/bot_name/endpoint/method/risk_level/entity_id/status（L3 额外 rows）。
- 覆盖: /api/cma/bot、/api/cma/bot-bridge、/api/cma/bot-kpis、/api/cma/bot/ai/suggestions（新增，自动覆盖）。
- /kpi-result 写入 KPIValue 带 source_batch=source（bot_bridge_v2.py:465 existing.source_batch = source）→ KPIValue.source_batch 落库可追溯。
六、P1 待办（不阻塞本单验收）
- 阈值类批量确认 UI：alert_rules 红黄绿阈值"Bot建议+人批量确认（一次5-10条）"——需阈值建议通道+批量 apply 端点+UI，改动面大，单列任务。
- OKR Objective 创建归口评审：okr/create 是否应降级为建议通道（OKR=战略承诺，边缘属考核基准类）；本轮保留 L2 直写并在 risk_levels.py 注释中列示待评审。
- suggestion 来源 UI 标注：source='bot'/'rule' 的来源标签补充（前端 sourceLabel 已加 bot: 'Bot建议'）。
- 审计清单文档同步巡检：新增 Bot 写端点时应同步本清单与 risk_levels.py 头部注释（当前为手工维护，防止漂移）。
七、验收记录（E2E/回归）
- 回归: backend/tests/test_bot_suggestion_channel.py（12条：鉴权/语义/多租户/幂等/审批闭环/审计/收口）；test_risk_levels.py 计数更新 L2=6。
- 生产E2E: backend/scripts/verify_bot_write_tiering_e2e.py（可复跑，标记+清理+回查）2026-09-03 全 PASS： A Bot创建kpi_target建议→unapplied → B 人apply→KPI目标100→888.88 + apply_detail(before/after) + applied_by=管理员/applied_at → C /kpi-result 直写 source_batch=e2e-bot-tier-20260903 落库 → D bot_audit.log 两条 L2 记录（财务BOT / bot-bridge）→ E 清理回查=0。
- pytest 全量: 726 passed / 4 failed(日历漂移预存：budget roll_forward + ai_suggestions budget_overrun + roadmap budget_headroom×2，非本次回归) / 1 xfailed。
- 后端重启: systemctl restart cma-backend（ActiveEnter 晚于 commit）; /health ok。