aps-agent/docs/architecture/harness.md

228 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 门禁权力矩阵(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 |
| `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 | 采用插单:写急单+DRAFT 排产版本 | 影响摘要;写入前自动建档 | 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/gov/pending` | 待审批 | M2 |
| `GET /api/gov/audit` | 审计链 | M2 |
| `GET /api/gov/modules` | 模块注册表 | M2 |
| `GET /api/gov/policy` | 权力矩阵投影 | M2.5 |
| `GET /api/gov/tests` | 黄金测试看板(`run=true` 须线程池,防阻塞) | M2.5 |
| `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 |
## 确认暂存端点备案(不直接执行写入)
| 端点 | 用途 | 权力路径 | 加入 |
| --- | --- | --- | --- |
| `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 |
## 防线
1. P2 只能:`stage_confirmation` → 确认卡 → `/api/actions/confirm` → `take_confirmation`
2. 未登记动作 → P3 拒绝;`guard()` 禁止 P2/P3 直通
3. P2 写主干前自动 Checkpoint(publish / reset / rollback)
4. GATE / WORLD_WRITE 写审计哈希链,可 `verify_audit_chain`
## 变更记录
| 日期 | 变更 |
| --- | --- |
| 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 管理台端点与模板/索引端点 |