aps-agent/docs/architecture/harness.md

# 门禁权力矩阵（Harness）

> 与 `server/agent_core/harness.py` 的 `_POWER_MAP` **一一对应**。  
> 改 `_POWER_MAP` 或新增需备案的 API → **同轮**改本表，并在 [`../CHANGELOG.md`](../CHANGELOG.md) 留痕。

等级语义：P0 只读 / P1 写沙盒或草稿（直通）/ P2 写主干或破坏性（单次确认卡）/ P3 外部副作用（二次确认；未登记动作默认 P3 拒绝）。

## 权力矩阵（与 _POWER_MAP 同步）

| action | 等级 | 为什么是这个等级 | 确认卡要点 | 加入 |
| --- | --- | --- | --- | --- |
| `schedule.run` | P1 | 试排只产草稿版本 | 无需确认 | M1 |
| `schedule.publish` | P2 | 发布写主干、推进订单状态 | 版本号/订单数/冲突数；发布前自动建档 | M1 |
| `scenario.compare` | P1 | 深拷贝沙盒，主干零接触 | 无需确认 | M2 |
| `scenario.sensitivity` | P1 | 参数扰动 Tornado，沙盒不写主干 | 无需确认 | SC-06 |
| `sop.compile` | P0 | SOP→约束编译预览 | 无需确认 | IND-02 |
| `sop.apply` | P2 | 应用 SOP 规则包 | 效果摘要；写前自动建档 | IND-02 |
| `checkpoint.create` | P1 | 只新增快照 | 无需确认 | M2 |
| `checkpoint.rollback` | P2 | 整体替换主干世界 | 目标检查点；回滚前再自动建档 | M2 |
| `data.reset` | P2 | 清空重播种子 | 明示重置；重置前自动建档 | M1 |
| `knowledge.query` | P0 | 只读知识；强制出处 | 无需确认 | M3 |
| `knowledge.import` | P2 | 导入 PDF/docx/md 切块入库 | 文件/切块数；确认后写资产 | RAG |
| `skill.list` | P0 | 外部算法 skill 清单 | 无需确认 | Skill |
| `skill.health` | P0 | skill 健康检查 | 无需确认 | Skill |
| `skill.register` | P2 | 登记/更新 skill 端点 | ID/端点/轨道 | Skill |
| `skill.enable` | P2 | 启停 skill | skillId + 目标状态 | Skill |
| `guidance.next` | P0 | 主动引导下一步建议（空态/冲突/知识未命中） | 无需确认 | AG-07 |
| `params.query` | P0 | 排产参数只读 | 无需确认 | OR-02 |
| `params.update` | P2 | 客户等级/目标权重/展望期 | 变更摘要；写前自动建档 | OR-02 |
| `param.optimize` | P1 | 参数优化触发（split→回放→候选 GRAY，不写主干参数） | 无需确认 | §9.8 |
| `param.experiment.promote` | P2 | 实验转正：验证集回放 finalize GRAY→FULL，退化自动回滚 | 实验摘要/候选参数/回放 KPI；写前自动建档 | §9.8 |
| `param.experiment.rollback` | P1 | 手动回滚实验（恢复基线参数） | 无需确认 | §9.8 |
| `param.observation.record` | P1 | 线上 KPI 观测回调（对比基线，连续劣化自动回滚） | 无需确认 | §9.8 |
| `constraint.profile.query` | P0 | 约束剖面只读 | 无需确认 | SC-04 |
| `constraint.profile.save` | P2 | 约束启停/硬软 | 变更摘要；写前自动建档 | SC-04 |
| `report.generate` | P1 | 产出文档并入知识库（不改排产世界） | 无需确认；对外承诺函未来升 P2 | M3 |
| `order.upsert` | P2 | 新增/编辑销售订单会改变后续排产输入 | 客户/产品/数量/交期；写入前自动建档 | M4 首切片 |
| `order.cancel` | P2 | 取消订单会从后续排产输入中排除 | 订单号/当前状态；写入前自动建档 | M4 首切片 |
| `order.complete` | P2 | 完成订单会从后续排产输入中排除 | 订单号/当前状态；写入前自动建档 | M4 首切片 |
| `order.delete` | P2 | 物理删除订单池记录 | 订单号；清草稿 MRP；写入前自动建档 | 录数 |
| `order.clear` | P2 | 一键清空全部订单与采购/委外建议 | 条数摘要；写入前自动建档 | 清理 |
| `order.submit` | P1 | 提交审核：DRAFT/REJECTED/CHANGED → SUBMITTED | 无需确认 | OR-03 |
| `order.approve` | P2 | 批准进排产池：SUBMITTED/CHANGED → APPROVED | 订单号列表；写入前自动建档 | OR-03 |
| `order.reject` | P2 | 驳回：SUBMITTED/CHANGED → REJECTED | 订单号/原因；写入前自动建档 | OR-03 |
| `rush.evaluate` | P1 | 插单影响快评：双沙盒对比，不改主干 | 无需确认 | OR-04 |
| `rush.apply` | P2 | 采用插单：LNS 局部修复（`apply_lns_local`，DRAFT+LNS_RUSH，窗口外订单冻结）或升级全量重排（`apply_rush`）；`execute_confirmed` 按 impact.lns 路由 LOCAL/ESCALATE | 影响摘要+lns 摘要；写入前自动建档；audit 记 mode+escalateReasons | OR-04 |
| `forecast.query` | P0 | 预测/长周期订单只读 | 无需确认 | OR-05 |
| `forecast.upsert` | P2 | 新建/编辑预测台账（默认不进正式排产） | 产品/数量/分桶/交期；写入前自动建档 | OR-05 |
| `forecast.delete` | P2 | 删除预测台账 | 预测号；写入前自动建档 | OR-05 |
| `forecast.convert` | P2 | 预测转正为 APPROVED 销售订单 | 预测号→销售单；写入前自动建档 | OR-05 |
| `plan.buckets` | P0 | 时间分桶计划：日/周/月/混合粗能力对照 | 无需确认 | PL-01 |
| `plan.rccp` | P0 | 有限/无限产能粗评估对照（RCCP） | 无需确认 | PL-02 |
| `plan.feasibility` | P0 | 交期可行性：累计粗能力能否按期 | 无需确认 | PL-03 |
| `plan.inventory` | P0 | 库存投影：物料随时间可用量曲线 | 无需确认 | PL-04 |
| `plan.leveling` | P0 | 产能平衡/削峰：超载桶挪空档建议 | 无需确认 | PL-05 |
| `plan.supply` | P0 | 产供方向：加班/扩线/外协结构化建议 | 无需确认 | PL-06 |
| `project.create` | P1 | 新建项目与默认会话 | 无需确认 | AG-08 |
| `project.delete` | P1 | 删项目元数据（不删世界） | 无需确认 | AG-08 |
| `session.create` | P1 | 新建会话 | 无需确认 | AG-08 |
| `message.append` | P1 | 追加会话消息 | 无需确认 | AG-08 |
| `message.replace` | P1 | 整包替换会话消息 | 无需确认 | AG-08 |
| `workspace.replace` | P1 | 整包同步工作区（迁移） | 无需确认 | AG-08 |
| `data.import` | P2 | 自然语言批量导入订单/物料 | 行数摘要；写入前自动建档 | 录数 |
| `master.line.upsert` | P2 | 产线编辑/停启用改后续新排产资源池 | 产线/产能/状态变更影响面；写入前自动建档 | M4 首切片 |
| `master.material.upsert` | P2 | 物料新建/全字段/停用改齐套与产品池 | 编码类型库存状态；写入前自动建档 | 工艺模型 |
| `master.maintenance.upsert` | P2 | 维保新增/取消改设备避让窗口 | 设备/窗口起止；写入前自动建档 | M4 首切片 |
| `master.bom.upsert` | P2 | BOM 头/明细增删改齐套与采购建议 | 增删改用量/关键料；写入前自动建档 | 工艺模型 |
| `master.routing.upsert` | P2 | 工艺路线/步骤增删改占槽与外协 | 步骤工时/外协；写入前自动建档 | 工艺模型 |
| `master.operation.upsert` | P2 | 工序库改路线可选步骤 | 编码/标准工时；写入前自动建档 | 工艺模型 |
| `master.lineProduct.upsert` | P2 | 产线-产品绑定改选线依据（排产前必需） | 产线×产品/优先级；写入前自动建档 | 工艺模型 |
| `master.changeover.upsert` | P2 | 换型矩阵写入（产品族切换分钟） | 从族/到族/分钟；写入前自动建档 | MD-06 |
| `changeover.query` | P0 | 换型矩阵只读 | 无需确认 | MD-06 |
| `campaign.preview` | P0 | 战役/批次合并预览 | 无需确认 | SC-08 |
| `master.clear` | P2 | 一键清理主数据板块（按范围清空） | scope=resource/process/calendar/flex/all；写入前自动建档 | 清理 |
| `import.commit` | P2 | Excel/CSV 校验通过行写入主干 | 文件名/种类/行数；写入前自动建档 | MD-04 |
| `order.decompose` | P1 | 订单分解只写 DRAFT 建议表（采购/委外），不碰主数据 | 无需确认（ALGO_RUN 审计留痕） | M4 首切片 |
| `mrp.release` | P2 | MRP 草稿采购/委外转正式 | 下达范围；写入前自动建档 | M4 |
| `plan.trace` | P0 | 计划追溯只读单据链 | 无需确认 | 追溯 |
| `flex.schedule` | P1 | 柔性排产（能力池+虚拟产线）只写 flex* 草稿表 | 无需确认（ALGO_RUN 审计留痕） | M5 首切片 |
| `flex.reschedule` | P2 | 分级重排 L2/L3/L4：窗外冻结 + 窗内重排，影响面大 | 等级/冻结工单/重排订单数；执行前自动建档 | DY-01 |
| `flex.swap` | P1 | L1 局部换机：池内备机接手，他单不动 | 无需确认 | DY-01 |
| `flex.capacity` | P0 | 瓶颈产能评估（能力池日产能） | 无需确认；联动视口产能池 | EX-10 |
| `flex.conflict.resolve` | P1 | EX-03 冲突安全修复（重排类另 stage P2） | 无需确认（重排走 flex.reschedule 卡） | EX-03 |
| `conflict.list` | P0 | 冲突中心只读 | 无需确认 | EX-03 |
| `flex.adjust.preview` | P0 | EX-04 甘特调程预览 | 无需确认 | EX-04 |
| `flex.adjust.commit` | P2 | EX-04 柔性甘特调程提交新草稿 | 工单/平移量/联动条数；执行前自动建档 | EX-04 |
| `schedule.adjust.preview` | P0 | EX-04 固定甘特调程预览 | 无需确认 | EX-04 |
| `schedule.adjust.commit` | P2 | EX-04 固定甘特调程提交新草稿 | 工单/平移量；执行前自动建档 | EX-04 |
| `sap.status` | P0 | MD-05 SAP 连接状态（Mock） | 无需确认 | MD-05 |
| `sap.sync.inbound` | P2 | MD-05 SAP→APS 拉单/库存 | 新单数/库存项；执行前自动建档 | MD-05 |
| `sap.sync.outbound` | P2 | MD-05 APS→SAP 开完工回写 | 条数/幂等；执行前自动建档 | MD-05 |
| `mes.status` | P0 | EX-05 MES 连接状态（Mock） | 无需确认 | EX-05 |
| `mes.dispatch` | P3 | EX-05 下发车间（外部副作用） | 版本/新下发条数；同一令牌二次确认；最终批准签发绑定审批参数摘要的一次性作用域执行凭据；执行前自动建档；最终审计绑定确认令牌、精确版本、真实前置快照和排产证据 | EX-05 |
| `mes.report` | P1 | EX-09 报工回流写工单进度 | 无需确认 | EX-09 |
| `readiness.query` | P0 | 数据齐备度检查（产品→路线→工时→资源→日历）只读 | 无需确认 | M-B |
| `flex.time.update` | P2 | 更新产品×工序单件工时并标记来源，改后续排产输入 | 产品/工序/分钟/来源；写入前自动建档 | M-B |
| `rag.query` | P0 | 外部 Skill 消费知识库（只读，manifest ragScopes 鉴权） | 无需确认 | M-E |
| `routing.template.apply` | P2 | 行业模板实例化为产品工艺路线（工时标「模板」） | 模板/产品/步数/知识出处；写入前自动建档 | M-E |
| `schedule.wizard` | P0 | 引导式排产向导（对话态本身只读，写入走各自 P2） | 无需确认 | M-F |
| `viewport.*` | P0 | 纯视图状态 | 无需确认 | M1 |
| `query.*` | P0 | 只读查询 | 无需确认 | M1 |

## 认证握手端点（安全边界，不入 _POWER_MAP）

| 端点 | 用途 | 加入 |
| --- | --- | --- |
| `POST /api/auth/login·refresh·logout` · `GET /api/auth/me` | Web 用户会话 | Auth/Tenancy |
| `POST /api/auth/license/activate` | 桌面客户端授权码激活、设备绑定与期限校验 | Desktop License |

## 只读端点备案（P0，不入 _POWER_MAP）

| 端点 | 用途 | 加入 |
| --- | --- | --- |
| `GET /api/world/summary·gantt·load·due` | 世界视图投影 | M1 |
| `GET /api/timeline` | 时间线 | M2 |
| `GET /api/checkpoints/{pairId}` | 检查点世界侧投影（P0，summary+固定/柔性工单+产能池；缺失 404） | 矩阵 54 |
| `GET /api/checkpoints?pairIds=&branchIds=&sessionId=` | 分支锚定批量投影（P0，缺失项上报） | 矩阵 54 |
| `POST /api/wms/events` | WMS 缺料事件上报（P1：幂等消费→库存版本→影响评估→Explore 方案卡 P2 门禁） | 矩阵 74/77 |
| `GET /api/wms/replay` | WMS 事件重放（P0） | 矩阵 74 |
| `GET /api/wms/inventory` | 库存台账/版本投影（P0 只读） | 矩阵 74 |
| `GET /api/saga` · `GET /api/saga/{id}` | Saga 列表/详情（中间态可见，P0） | 矩阵 78/119 |
| `GET /api/params/experiments` | 参数实验列表/状态（P0） | 矩阵 87 |
| `POST /api/params/optimize` · `POST /api/params/observations` | 参数优化触发 / 线上观测回调（P1） | 矩阵 87 |
| `POST /api/params/experiments/{id}/promote` · `.../rollback` | 实验转正（P2 确认卡）/ 手动回滚（P1） | 矩阵 87 |
| `POST /api/multimodal/extract` | 多模态候选抽取（P0 只读：结构化候选+置信度；含 dxf_drawing 图纸提取器） | 矩阵 101 |
| `POST /api/multimodal/ingest` | 多模态摄取（低置信出 P2 确认卡，确认前不写世界；dxf_drawing 候选 fail closed 指引 /api/dxf/stage） | 矩阵 101 |
| `POST /api/dxf/parse` · `/parse-path` | 工程图纸 DXF 解析（P0 只读：标题栏/位置号/技术说明 + 物料/BOM/工艺路线候选，不写世界） | DXF-01 |
| `GET /api/dxf/{drawingId}/svg` · `GET /api/dxf/discover` | 图纸 SVG 预览（解析缓存复用）/ 工程目录 DXF 发现（P0 只读） | DXF-01 |
| `GET /api/features` | 功能开关（P0 只读）：文件化配置功能上线/隐藏；可用性开关非权限边界，缺失/损坏 fail-open 默认全开并显式 error | FF-01 |
| `GET /api/gov/archive/verify` | WORM 归档完整性验证（P0 只读：sha256/merkle 篡改检出） | 矩阵 104/116/112 |
| `POST /api/gov/archive/run` | 触发归档密封（P1：archive_old + worm manifest） | 矩阵 104/116/112 |
| `POST /api/saga/{id}/retry` | Saga 重试（P1，先按快照回滚步副作用） | 矩阵 78/119 |
| `POST /api/saga/{id}/compensate` | 手动触发补偿链（P1） | 矩阵 78/119 |
| `POST /api/saga/{id}/takeover` | 人工接管（P1，补偿失败安全降级） | 矩阵 78/119 |
| `POST /api/automation/tick` · `GET /api/automation/status` | 自动化定时驱动（手动 tick + lifespan 后台自动；P1 驱动/ P0 状态） | 矩阵 76 |
| `POST /api/rebuild/{module_id}` | 可重生流水线触发（候选构建+隔离黄金+安全扫描+灰度，P1） | 矩阵 91 |
| `GET /api/rebuild` · `POST /api/rebuild/{module_id}/promote|rollback` | 流水线状态/转正/回滚（P0/P1） | 矩阵 91 |
| `GET /api/gov/pending` | 待审批 | M2 |
| `GET /api/gov/approval-history` | 按租户/项目过滤的审批历史、停留时长和超时结果 | M2 |
| `GET /api/gov/audit` | 审计链 | M2 |
| `POST /api/gov/audit/events` | 桌面端/登录态审计事件上报（矩阵 103 收口：desktop 模式由 SidecarIdentityApp nonce 门禁即身份（updater 带 nonce 即可）；web 模式要求登录身份；可选 idempotencyKey 幂等去重；失败 4xx 明确；事件复用 write_audit 入链） | 矩阵 103 |
| `GET /api/gov/modules` | 模块注册表 | M2 |
| `GET /api/gov/policy` | 权力矩阵投影 | M2.5 |
| `GET /api/gov/tests` | 黄金测试看板（`run=true` 须线程池，防阻塞） | M2.5 |
| `GET /api/plans/{planId}` · `/{planId}/versions` | Plan 最新版与不可变版本历史（P0） | Plan §3.1 |
| `POST /api/plans` · `/{planId}/regenerate` | 追加 Plan 草稿/重生版本（P1，不写世界状态） | Plan §3.1 |
| `GET /api/settings/llm` | LLM 状态 | M2.5 |
| `GET /api/knowledge/assets` · `/{id}` | 知识资产 | M3 |
| `POST /api/knowledge/import` · `/upload` | 知识导入（P2 暂存确认卡） | RAG |
| `GET /api/skills` · `/health` | 外部算法 Skill 清单/健康 | Skill |
| `POST /api/skills/register` | 登记 Skill（P2 暂存） | Skill |
| `GET /api/reports/{type}` | 报告导出 daily / version-diff | M3 |
| `GET /api/orders` | 订单管理页投影（订单 + 成品选项） | M4 首切片 |
| `GET /api/master` | 主数据管理页投影（资源树/物料BOM/日历维保） | M4 首切片 |
| `GET /api/mrp` | MRP 建议单投影（采购/委外 DRAFT） | M4 首切片 |
| `POST /api/mrp/decompose` | 订单分解（P1 直通，经 `harness.guard`） | M4 首切片 |
| `GET /api/flex/world` | 柔性排产页投影（能力池/设备/模具/订单 + 虚拟产线） | M5 首切片 |
| `POST /api/flex/schedule` | 柔性排产（P1 直通，经 `harness.guard`） | M5 首切片 |
| `POST /api/flex/reschedule` | 分级重排暂存确认卡（P2，执行走 confirm） | DY-01 |
| `POST /api/flex/swap` | L1 局部换机（P1） | DY-01 |
| `GET /api/flex/conflicts` | 冲突中心（P0） | EX-03 |
| `POST /api/flex/conflicts/resolve` | 冲突修复（P1 / 或 stage P2） | EX-03 |
| `POST /api/flex/adjust/preview` | 甘特调程预览（P0） | EX-04 |
| `POST /api/flex/adjust/stage` | 甘特调程确认卡（P2） | EX-04 |
| `POST /api/schedule/adjust/preview` | 固定轨调程预览（P0） | EX-04 |
| `POST /api/schedule/adjust/stage` | 固定轨调程确认卡（P2） | EX-04 |
| `GET /api/sap/status` | SAP 连接状态（Mock，P0） | MD-05 |
| `GET /api/sap/inbound/preview` · `outbound/preview` | SAP 入/出站预览（P0） | MD-05 |
| `POST /api/sap/inbound/stage` · `outbound/stage` | SAP 同步确认卡（P2） | MD-05 |
| `GET /api/mes/status` · `execution` · `dispatch/preview` | MES 状态/进度/下发预览（P0） | EX-05/09 |
| `POST /api/mes/dispatch/stage` | MES 下发确认卡（P3，首次批准只留审计，二次批准才执行） | EX-05 |
| `POST /api/mes/report` | 报工回流（P1） | EX-09 |
| `GET /api/analytics/kpi` | KPI 仪表盘聚合（P0） | EX-08 |
| `GET /api/analytics/utilization` | 资源利用率：设备热力+班组（P0） | EX-06 |
| `GET /api/analytics/compare` | 方案对比表（P0 沙盒） | EX-07 |
| `POST /api/flex/simulate-due` | 交期承诺模拟（P0 只读沙盒，PL-08 雏形） | M5 首切片 |
| `GET /api/flex/capacity` | 瓶颈产能法分析（P0，各池日产能+限制性瓶颈，PL-07 / EX-10） | M5 首切片 |
| `POST /api/import/preview` | Excel/CSV 上传校验（P1，不写主干） | MD-04 |
| `POST /api/rush/evaluate` | 插单影响快评（P1 沙盒，经 `harness.guard`） | OR-04 |
| `POST /api/orders/submit` | 订单提交审核（P1 直通） | OR-03 |
| `GET /api/forecast` | 预测/长周期订单投影（P0） | OR-05 |
| `GET /api/plan/buckets` | 时间分桶计划投影（P0，含 capacityMode） | PL-01/02 |
| `GET /api/plan/rccp` | 有限/无限粗能力对照（P0） | PL-02 |
| `GET /api/plan/feasibility` | 交期可行性（P0，前置于排产） | PL-03 |
| `GET /api/plan/inventory` | 库存投影（P0） | PL-04 |
| `GET /api/plan/leveling` | 产能平衡/削峰建议（P0） | PL-05 |
| `GET /api/plan/supply` | 产供方向决策（P0） | PL-06 |
| `GET /api/workspace` | 项目/会话/消息工作区快照（P0） | AG-08 |
| `PUT /api/workspace` | 整包同步工作区（P1，迁移/防抖） | AG-08 |
| `GET/PUT/POST /api/sessions/{id}/messages` | 会话消息读写（P0/P1） | AG-08 |
| `GET /api/readiness` · `/api/times` | 齐备度报告 / 工时矩阵（P0） | M-B |
| `POST /api/times/update` | 工时更新确认卡（P2 暂存） | M-B |
| `GET /api/projects` · `/api/packs` | 项目清单 / 数据包清单（P0） | M-A |
| `GET /api/templates` · `/recommend` | 工艺模板库 / 按产品推荐（P0） | M-E |
| `POST /api/templates/apply` | 模板生成路线确认卡（P2 暂存） | M-E |
| `POST /api/rag/query` | Skill 消费 RAG（P0，apiKey + ragScopes 鉴权） | M-E |
| `GET /api/knowledge/index/status` · `POST …/rebuild` | 向量索引状态 / 重建（P0 / P1） | M-E |
| `POST /api/skills/{id}/enable` | 启停 skill 确认卡（P2 暂存） | M-D |
| `GET /api/skills/{id}/audit` · `/history` | skill 审计过滤 / 健康历史（P0） | M-D |
| `POST /api/skills/{id}/test` | 跑该 skill 黄金测试子集（P1，子进程） | M-D |
| `GET /api/skills/contracts` | SchedulingProblem/Solution 契约（P0） | M-D |
| `GET /api/mcp/plugins*` | MCP 插件清单/健康/权限/审计（P0） | M-D |
| `POST /api/mcp/plugins/register` · `/enable` · `/permissions` | MCP 注册/启停/权限（P2 审计） | M-D |
| `GET /api/jobs` · `POST /api/jobs` | 异步任务列表/提交（敏感性/蒙特卡洛重算） | M3 |
| `GET /api/jobs/{id}` · `/cancel` | 异步任务轮询/取消 | M3 |

## 确认暂存端点备案（不直接执行写入）

| 端点 | 用途 | 权力路径 | 加入 |
| --- | --- | --- | --- |
| `POST /api/orders/stage` | 订单新增/编辑/取消/完成/批准/驳回生成确认卡 | `order.*` P2 → `/api/actions/confirm` 执行 | M4 首切片 |
| `POST /api/rush/stage` | 采用紧急插单生成确认卡 | `rush.apply` P2 → `/api/actions/confirm` 执行 | OR-04 |
| `POST /api/forecast/stage` | 预测新建/删除/转正确认卡 | `forecast.*` P2 → `/api/actions/confirm` 执行 | OR-05 |
| `POST /api/projects` · `DELETE /api/projects/{id}` · `POST /api/sessions` | 项目/会话元数据（P1 直通） | `project.*` / `session.create` | AG-08 |
| `POST /api/master/stage` | 产线/物料/维保编辑生成确认卡 | `master.*` P2 → `/api/actions/confirm` 执行 | M4 首切片 |
| `POST /api/import/commit` | 导入批次生成确认卡 | `import.commit` P2 → `/api/actions/confirm` 执行 | MD-04 |
| `POST /api/dxf/stage` | DXF 图纸主数据候选（物料/BOM/工艺路线）生成确认卡 | `master.*` P2 → `/api/actions/confirm` 执行 | DXF-01 |

## 审批角色策略

`APS_APPROVAL_ROLE_POLICIES` 可按精确 action 和 P2/P3 等级分别配置发起、批准、历史查看角色。每种能力独立解析，固定优先级为：**精确 action > power 等级 > 既有全局环境变量**。

```json
{
  "actions": {
    "mes.dispatch": {
      "initiate": ["dispatcher"],
      "approve": ["mes-approver"],
      "history": ["mes-auditor"]
    }
  },
  "powers": {
    "P2": {
      "approve": ["planner", "approver"]
    },
    "P3": {
      "approve": ["senior-approver"]
    }
  }
}
```

- action 必须是 `_POWER_MAP` 中精确登记且需要审批的 P2/P3 动作；不接受 `*`。
- 规则只允许 `initiate`、`approve`、`history`，值必须为角色字符串数组；空数组表示除合法 `system` 身份外不授权任何角色。
- 某能力未在 action 规则声明时回退同等级规则，再未声明时分别回退 `APS_APPROVAL_INITIATOR_ROLES`、`APS_APPROVAL_ROLES`、`APS_APPROVAL_VIEW_ROLES`，保持既有部署兼容。
- 未知字段/action/等级、重复 JSON 键、非数组或非法角色会使整份配置失效。失效期间包括 `system` 在内均不得发起、批准或查看审批；`GET /api/gov/policy` 保留原字段，并通过各条目的 `rolePolicy.valid=false/error` 暴露配置错误。
- 角色策略只决定谁可操作，不改变 P2 一次批准和 P3 两个不同用户批准的次数与职责分离约束。

## 防线

1. P2 只能：`stage_confirmation` → 持久审批队列 → 确认卡/门禁管理台 → `/api/actions/confirm` → `take_confirmation`，批准一次后令牌失效
2. P3 使用同一令牌由两个不同用户连续批准：首次只写 GATE 审计并保留令牌，同一用户再次批准被职责分离门禁拒绝；第二名用户批准后签发绑定规范化审批参数摘要的一次性内部执行凭据，才允许外部副作用；审批记录冻结发起人的有效 `worldKey`，第二审批人的当前个人空间不能改变执行目标；`mes.dispatch` 必须以原始 `track/versionId/evidenceRefs` 消费该凭据，并校验真实存在的 `beforeSnapshot`
3. 未登记动作 → P3 拒绝；`guard()` 禁止 P2/P3 直通
4. P2/P3 写入前自动 Checkpoint（publish / reset / rollback / 外部下发）
5. GATE / WORLD_WRITE 写审计哈希链，可 `verify_audit_chain`
6. 审批队列、审批历史和一次性执行凭据经统一 backend 原子持久化；文件后端使用原子替换，数据库后端使用请求 `revision` CAS 和短事务。最终批准、P3 grant 签发和审批事件同事务提交；数据库只保存 grant token 的 SHA-256。审批和凭据 TTL 分别由 `APS_APPROVAL_TTL_SECONDS`、`APS_EXECUTION_GRANT_TTL_SECONDS` 控制，重启后继续生效且过期结果进入审批历史
7. 发起/批准/历史权限按 `APS_APPROVAL_ROLE_POLICIES` 的精确 action > power > 全局环境变量确定；配置非法时全部失败关闭。全部审计 actor 只从认证身份派生，不信任客户端 `sessionId`；损坏或字段非法的审批文件会被隔离为 `.corrupt-*` 并告警，拒绝继续使用其中令牌

默认 `APS_APPROVAL_BACKEND=file`：使用进程内可重入锁、同机跨进程文件锁和原子文件替换，可防止多个本机 Gateway worker 重复签发。显式设置 `APS_APPROVAL_BACKEND=database` 后复用 `APS_DATABASE_URL` 的 MySQL；批准/驳回竞态、最终 grant 签发和 grant 消费均使用 CAS 保证跨连接只有一个赢家。database 模式缺少 URL、配置 `APS_APPROVAL_PATH`、连接失败或使用非 MySQL 方言时失败关闭，不回退 file；`APS_APPROVAL_DATABASE_ALLOW_SQLITE=1` 只允许测试。

共享切换必须先执行 Alembic `20260731_03` 并整体切换所有节点，禁止 file/database 混跑。当前仅完成 SQLite 本地合同/CAS 测试，尚未宣称 MySQL 实机或多主机故障注入验收通过。

## 证据链 v1（§3.4）

- 出卡冻结：`stage_confirmation` 记录 `evidenceRefs`（显式或按 `versionId` 派生 `schedule-version:<id>`）、`beforeSnapshot`（写前 checkpoint pairId）与 `beforeFingerprint`（输入快照指纹，世界已加载时）。
- 执行强校验（fail closed）：`execute_confirmed` 在最终批准后、写世界前调用 `verify_pending_evidence`：
  - 版本证据绑定：params 含 `versionId` 时必须携带 `schedule-version:<versionId>` 证据，否则拒绝；
  - 前置快照存在：`beforeSnapshot` 指向的 checkpoint 必须存在，否则拒绝；
  - 版本一致性：世界带版本表时 `versionId` 必须仍可解析，否则拒绝（对象域校验，避免全局指纹假阳性）。
- 审计统一：全部 P2/P3 写审计事件携带 `beforeSnapshot` 与 `evidenceRefs`；拒绝路径写 `DENIED` 审计且不改变世界。
- 输入快照指纹：`world_fingerprint` 对业务主数据投影做 SHA256（排除 append-only 日志/审计/同步流水），用于出卡与执行间的漂移检测证据。
- mes.dispatch 原有强绑定（确认令牌 + 版本证据 + 写前快照）保持不变，作为统一协议的参考实现。
- 审批意见：`take_confirmation(confirm_id, approve, note=...)` 携带可选意见，随批准/驳回记录进 `approvals` 与审批历史事件（文件与共享 database 后端一致）；网关 `ConfirmRequest.note` 透传，管理台审批历史展示。
- 审批委托：`stage_confirmation(..., delegate_user_id=...)` 出卡时可指定被委托人；P2 单重审批作用域允许 owner 或被委托人操作，P3 双人职责分离不变（委托不视为身份合并）。
- 审批转派：`transfer_confirmation(confirm_id, to_user_id)` 把待确认项转派给指定用户（P2；转派后 owner=目标用户、原 owner/delegate 不可再审批；P3 拒绝转派保双人分离）；历史事件 `TRANSFERRED` 记录 from/to；网关 `POST /api/actions/transfer`。
- 统一 EvidenceItem：`server/agent_core/evidence.py` 提供结构化证据记录（kind/ref/version/runId/engine/seed/inputsHash/knowledgeVersion/confirmId/note）与 `trace_chain()`（规范化 JSON + 链哈希，可复算可追溯）；证据引用语法 `<kind>:<id>` 与 `schedule-version:<id>` 协议兼容。
- schedule.run 接入：`server/aps_domain/workflow.py` 的 `_run_schedule` 求解后经 `_build_run_trace` 构造 EvidenceItem 链（schedule-version/run/algorithm），ALGO_RUN `schedule.run` 审计 rationale 携带 `traceChainHash`/`traceCount`/`traceSummary`（可复算可追溯；失败返回空链摘要，不影响求解）。链哈希只含确定性信息（版本/run/引擎/策略/求解状态/gap/输入包指纹），墙钟 `solveTimeSec` 保留在审计顶层字段不进入链哈希，RULE/CP/HYBRID/GA 四引擎同输入同种子可复算；审计 `evidence` 合并 `schedule-version:<id>` 引用（`_run_audit_evidence`）。
- EXTERNAL 引擎接入：`_run_flex` 的 `flex.schedule.external` 分支经 `_build_external_trace` 构造同构链（schedule-version/run/EXTERNAL/algorithm），审计携带 traceChainHash；`algo_skill_stub.runId` 改为输入派生确定性哈希保证可复算；前端 GovConsole 审计链新增「可追溯链」列展示链哈希与摘要。
- 审计独立介质锚定：`server/agent_core/audit_ledger.py` 提供 `audit_root(events)`（对链哈希做双哈希聚合根）与 `AnchorLedger`（按租户/项目隔离的 append-only JSONL 账本）；`/api/gov/audit` 返回 `anchor` 状态，`POST /api/gov/audit/anchor` 显式锚定；改事件/删账本行可被检测（与链式校验互补）。
- 审计事件镜像：`server/agent_core/audit_mirror.py` 提供 `AuditMirror`（按租户/项目隔离 append-only JSONL）；`APS_AUDIT_MIRROR=1` 时 `write_audit` 同步镜像每条事件（尽力而为，失败只记日志），`/api/gov/audit` 有镜像时以镜像为事件源（业务进程改 world 无法抹掉独立介质证据）。
- 审计合规导出：`server/agent_core/audit_export.py` 提供 `sanitize_event`（token/password/secret/key/authorization/credential 键值递归掩码）与 `export_events`（json/csv）；`/api/gov/audit/export` 导出当前作用域事件（脱敏）+ 链/锚定摘要。
- 审计完整性告警：`server/agent_core/audit_alerts.py` 聚合链断裂（critical）、锚定不匹配/账本损坏、未锚定、镜像未启用等告警；`/api/gov/audit` 返回 `alerts`，管理台 AuditView 按 severity 展示。

## 变更记录

| 日期 | 变更 |
| --- | --- |
| 2026-08-01 | trace_chain 接入 schedule.run：ALGO_RUN 审计携带 traceChainHash/traceCount/traceSummary；schedule.run 首接入矩阵 114 行 |
| 2026-08-01 | trace_chain 跨引擎可复算：墙钟移出链哈希；evidence 并入 schedule-version 引用；RULE/CP/HYBRID/GA 四引擎可复算（round-16 补充） |
| 2026-08-01 | EXTERNAL 引擎接入 trace_chain（flex.schedule.external 审计携带 traceChainHash）+ 前端审计链「可追溯链」列（round-16b） |
| 2026-08-01 | 对话状态与世界状态成对快照：CheckpointStore 支持 conversationSide，_create_checkpoint 统一建档、_restore_conversation_side 回滚成对恢复（round-17） |
| 2026-08-01 | 审计完整性告警通知渠道：audit_notify（console/jsonl/webhook + 防抖），/api/gov/audit 联动（round-18） |
| 2026-08-01 | 审计完整 Merkle 树：audit_merkle（merkle_root/merkle_proof/verify_proof），JSON 导出携带 merkleRoot（round-19） |
| 2026-08-01 | 审计 append-only 守护：audit_filelock 跨进程锁 + audit_ledger.archive_old 保留窗口归档（round-20） |
| 2026-08-01 | 偏好学习升级：项目隔离（record/preferred_strategy 带 project_id）、explain 解释、reset 重置、冷启动/不确定度（round-21） |
| 2026-08-01 | Explore 与 Runtime 数据边界：explore_boundary（readonly_view + run_explore），scenario.compare 接入统一通道（round-22） |
| 2026-08-01 | L0-L3 Plan 重放：plan_runtime.node_at/replay_verify + plan_api 重放端点（round-23） |
| 2026-08-01 | 统一工具运行时：LLM 提议意图唯一执行入口（登记校验 + TOOL 审计），gateway 聊天接入（round-24） |
| 2026-08-01 | 分支树：BranchStore（fork/rename/switch/discard/merge + 状态机 + 审计），gateway branches API，快照纳入分支（round-25） |
| 2026-08-01 | 主数据工艺路线树产品升级：成品→半成品→工序层级树，build_process_tree 补展示字段（round-26） |
| 2026-08-01 | 分支切换自动恢复锚定检查点：_create_checkpoint 锚定分支、switch 端点成对恢复（round-27） |
| 2026-08-01 | 偏好解释 UI（设置·个人偏好 + /api/settings/preferences）+ stub runId 可复算修复（round-28） |
| 2026-08-01 | 主数据工艺树 → 树形表格：sourcing 去重/半成品推导/工序名补齐 + 类型来源标签（round-29） |
| 2026-08-01 | L0-L3 Plan 批准/驳回审计：transition_status + approve/reject 端点（round-30） |
| 2026-08-01 | Agent 自动编排：P2 出卡建 L0/L1/L2 链、批准/驳回流转、_load regen 校验修复（round-31） |
| 2026-08-01 | 偏好时间衰减加权模型：来源权重×时间衰减（半衰期14天），偏好漂移（round-32） |
| 2026-08-01 | Explore 通道扩展：run_sensitivity/run_monte_carlo 接入 run_explore 统一边界（round-33） |
| 2026-08-01 | 多智能体并行：session_ref/context_policy（A）、automation G0-G4（B）、分支树UI+时间线微观层（C）——round-34 |
| 2026-08-02 | 多智能体并行·第二批：CP-SAT工序级（D）、algolib+param_opt（E）、MCP总线+async_jobs（F）——round-35 |
| 2026-07-31 | 跨主机审批首切片：显式 MySQL backend、规范化 request/grant/event 表、CAS 终态和一次性消费、token 摘要落库；文件后端保持默认 |
| 2026-07-31 | 审批角色策略：支持 exact action / P2/P3 分级覆盖，按能力确定性回退全局角色；非法配置失败关闭，治理投影追加配置来源与校验状态 |
| 2026-07-31 | 审批治理持久化：队列/历史/执行凭据跨重启恢复，支持 TTL、P3 双人职责分离、停留时长和治理历史 API/UI |
| 2026-07-31 | 二次审计整改：执行凭据绑定审批参数摘要；MES 展示上限不再截断执行，整版完成标记取决于全部工单幂等链接 |
| 2026-07-31 | Plan §3.1：备案 `/api/plans` P0/P1 端点；创建/重生只追加治理版本，不穿透世界状态 |
| 2026-07-31 | 审计整改：P3 最终批准签发一次性作用域执行凭据；MES 精确锁定审批版本并校验真实快照/证据；跨租户不泄漏令牌状态 |
| 2026-07-31 | P3 二次确认：首次批准仅审计并保留令牌，第二次批准才执行 `mes.dispatch` 外部副作用；最终审计绑定确认令牌、前置快照和排产证据 |
| 2026-07-16 | 初版 8 条 + M2.5 只读端点 |
| 2026-07-23 | RAG：`knowledge.import` P2；Skill：`skill.*`；端点 `/api/knowledge/import*` `/api/skills*` |
| 2026-07-16 | 迁入 `architecture/harness.md`；注明 tests 线程池 |
| 2026-07-16 | OR-01：新增 `order.upsert/cancel/complete` P2 与订单暂存端点 |
| 2026-07-16 | MD-01/02/03：新增 `master.line/material/maintenance.upsert` P2 与 `/api/master`、`/api/master/stage` |
| 2026-07-16 | MRP：新增 `master.bom/routing.upsert` P2、`order.decompose` P1 与 `/api/mrp*` |
| 2026-07-22 | DY-01：`flex.reschedule` 升 P2；新增 `flex.swap` P1 与 `/api/flex/swap` |
| 2026-07-22 | EX-03：`conflict.list` P0、`flex.conflict.resolve` P1 与冲突 API |
| 2026-07-22 | EX-04：`flex.adjust.preview` P0 / `flex.adjust.commit` P2 |
| 2026-07-22 | EX-04：`schedule.adjust.preview/commit` 固定轨对称 |
| 2026-07-22 | MD-05：`sap.status` P0 / `sap.sync.inbound|outbound` P2（Mock 桩） |
| 2026-07-22 | EX-05/09：`mes.dispatch` P3 / `mes.report` P1（Mock MES） |
| 2026-07-22 | EX-07/08：`/api/analytics/compare|kpi` 视口对比表与 KPI 仪表盘 |
| 2026-07-22 | EX-06：`/api/analytics/utilization` 设备热力+班组并发；SC-11 文档对齐 |
| 2026-07-22 | AG-07：`guidance.next` P0 + `/api/guidance` 主动引导 |
| 2026-07-22 | OR-02：`params.query` P0 / `params.update` P2 + `/api/params*` |
| 2026-07-22 | SC-04：`constraint.profile.*` + `/api/constraints*`；硬约束拦发布 |
| 2026-07-23 | OR-05：`forecast.query` P0 / `forecast.upsert|delete|convert` P2 + `/api/forecast*` |
| 2026-07-23 | PL-01：`plan.buckets` P0 + `/api/plan/buckets` 分桶视口 |
| 2026-07-23 | PL-02：`capacityMode` + `plan.rccp` P0 + `/api/plan/rccp` |
| 2026-07-23 | PL-03：`plan.feasibility` P0 + `/api/plan/feasibility` |
| 2026-07-23 | PL-04：`plan.inventory` P0 + `/api/plan/inventory` |
| 2026-07-23 | PL-05：`plan.leveling` P0 + `/api/plan/leveling` |
| 2026-07-23 | PL-06：`plan.supply` P0 + `/api/plan/supply` |
| 2026-07-23 | MD-06：`changeover.query` / `master.changeover.upsert` + RuleEngine C10 |
| 2026-07-23 | SC-07：策略 `CHANGEOVER_MIN` + 方案对比换型卡 |
| 2026-07-23 | SC-08：策略 `CAMPAIGN` + `campaign.preview` |
| 2026-07-23 | SC-06：`scenario.sensitivity` P1 + `/api/scenario/sensitivity` Tornado |
| 2026-07-23 | SC-03：`get_engine(CP)` → CpSatEngine（OR-Tools）；GA/HYBRID 仍 RULE 代跑 |
| 2026-07-23 | SC-03：`get_engine(HYBRID)` → HybridEngine（RULE hint → CP） |
| 2026-07-23 | IND-02：`sop.compile` P0 / `sop.apply` P2 + `/api/sop*`；C13_sop |
| 2026-07-23 | 通用平台 M-A/B：`readiness.query` P0 / `flex.time.update` P2 + `/api/readiness` `/api/times*` `/api/projects` `/api/packs` |
| 2026-07-23 | 通用平台 M-D/E/F：`rag.query` P0 / `routing.template.apply` P2 / `schedule.wizard` P0 + skill 管理台端点与模板/索引端点 |

## Round 65 P2/P3 排产发布与 MES 分离

- `POST /api/schedule/publish/stage` 只暂存 `schedule.publish` P2 确认卡，绑定 `track + versionId + schedule-evidence`；执行仍唯一经 `/api/actions/confirm`。
- 柔性发布出卡和执行时都重算 `publishReady`；证据漂移或版本替换一律拒绝。
- `mes.dispatch` 保持 P3 双人职责分离；不在 MES 路径中暗中把 DRAFT 改为 PUBLISHED。

### Round 65 审计补强：P2/P3 证据闭包

- `schedule.publish` 与 `mes.dispatch` 共享的 evidence 包含 `problemDigest`、`solutionDigest`、`solutionActivityDigest`、`validationDigest`、`currentValidationDigest` 和当前多资源快照摘要。
- 工单必须绑定 `activityId`、`activityIdentity`、`closedLoopRequirementId`；TEAM/TOOLING 分配与工单 `teamCode/moldCode` 不一致时失败关闭。
- 发布/下发时重建 FACTORY/WORKSHOP/LINE/WORKSTATION/EQUIPMENT/TEAM/TOOLING 当前约束并重新运行 V2 Validator。
- WMS Saga 在确认执行前后比较版本集合，只接受唯一新版本，并核验 `flex.reschedule.approve` 审计的 confirmId、versionId 与 WMS event evidence。