aps-agent/docs/round-76-kangni-real-data-trial-work-plan.md

# 第 76 轮工作计划：康尼真实数据本地全流程试排

更新日期：2026-08-17（2026-08-18 收口）

## 1. 本轮目标

使用 `KANGNI_DATA_DIR` 指向的现有真实数据完成本地 APS 全流程试排准备：修复 10/10 订单导入，校验工艺、BOM、工时、设备与模具映射，生成 MPS 草案，比较五种柔性排产策略，采用一个本地草案版本并导出订单/设备结果，最后通过浏览器复跑完整操作路径。

本轮严格停止在真实 MES 下发前。允许排产结果出现业务延期，但必须提供约束、资源和数据证据；不得把共享设备、缺失能力或推断工时包装成现场确认结果。

## 2. 背景和当前状态

- 真实数据目录已有 `订单.xlsx`、`工艺路线.xlsx`、`工时.xlsx`、`BOM.xlsx`、`设备.xlsx`、`模具.xlsx`、`物料.xlsx` 及两份映射模板。
- 只读预检确认：10 个订单、72 条订单工序记录、26 个唯一工序代码、965 条 BOM；`工时.xlsx` 的 72 条工序均有分钟值。
- 当前 `parse_routing_sheet` / `parse_bom_sheet` 只按订单号匹配 sheet，后 8 个订单位于 `Sheet2`-`Sheet9`，现状只导入 2/10 个订单。
- 当前可读取 40 台真实设备、40 套真实模具，并增加 1 台共享设备占位；40 台真实设备均缺工序能力，40 套模具均缺工序/设备/寿命映射，仍需现场确认。
- MPS 已有 draft/persist/trace/gap，本地排产已有 `ASC`、`DESC`、`BOTTLENECK`、`KITTING_FIRST`、`SKILL_FIRST` 和订单/设备 XLSX 导出。
- Round 71-75 的大量成果仍在原工作区未提交状态。本轮保护这些改动，不清理、不重置、不盲目提交、不推送。

## 3. 已确认决策

- 采用方案 A：完成本地 10 订单全流程试排，停止在真实 MES 下发前。
- 康尼原始 Excel 全部只读；解析修复、映射结果和验收证据写入代码、测试或独立 artifact，不覆盖源文件。
- 10/10 订单可识别、每个订单工艺/BOM 来源可追溯是硬验收。
- 允许延期 KPI 非零，但硬约束违规必须为零或明确阻断采用；占位映射必须显式标记。
- 五种策略全部比较；输出订单视角、设备视角、MPS trace/gap、冲突/数据质量四类结果。
- 先 `--no-persist` 只读预检，再使用隔离 `APS_HOME` 试排，最后做 Web 实际操作验收。

## 4. 范围

In scope：

- `Sheet2`-`Sheet9` 按结构化订单字段解析，不依赖任意字符串猜测。
- 主订单与兄弟订单从 `工时.xlsx` 回填真实标准工时，并保留来源/推断标记。
- BOM、工艺、订单数量、工序数量、设备和模具数量的对账报告。
- MPS 草案/trace 与本地排产版本、采用/发布事实的可追溯关联；不触发 MES。
- 五策略比较、采用、订单/设备 XLSX 导出及确定性验证。
- 隔离数据目录下的真实数据试排、Web 操作验收和可复跑手册。

Out of scope：

- 真实 MES/WMS/SAP 地址、凭据、报文联调和任何外部下发。
- 擅自补造设备能力、模具适配、库存、在途、班次或换型参数。
- 修改康尼原始 Excel。
- commit、push、merge、部署或清理现有未提交改动；这些动作另行确认。

## 5. 工作阶段

### R76.0 基线与只读数据预检

- 记录源文件清单、大小、修改时间和 SHA-256。
- 对账订单号、sheet、工艺、BOM、工时、设备、模具及映射字段。
- 所有真实数据运行使用 `--no-persist` 或独立 `APS_HOME`。

### R76.1 10 订单导入修复

- 工艺解析优先精确订单名 sheet；generic routing sheet 通过 `工时.xlsx` 订单命名 sheet 的规范工序代码/排序序列匹配。多个候选只有在规范工艺内容完全相同时才允许确定性复用，否则失败关闭。
- BOM 独立扫描所有 sheets 并按结构化 `工单编号` 定位订单行，不假设 BOM 与工艺的同名 `SheetN` 属于同一订单。
- 工艺和 BOM 不得跨订单串行；重复、缺失或歧义必须失败关闭并给出中文诊断。
- 增加合成 fixture 和康尼只读数据门禁，覆盖 exact-sheet、generic-sheet、missing、ambiguous 四类情况。

### R76.2 MPS 与本地排产追溯

- 保持租户/项目/世界隔离和现有 draftHash/worldFingerprint 绑定。
- 将 trace 与本地 schedule version、采用/发布事实关联；错误轨道、版本漂移和跨项目引用失败关闭。
- 只记录本地 APS 事实，不产生 MES dispatch。

### R76.3 五策略与导出核验

- 五策略返回稳定、可解释的策略标识和 KPI。
- 订单/设备 XLSX 覆盖 10 订单试排结果，表头、排序和内容确定性可复跑。
- 齐套/技能数据不足时明确降级或冲突，不静默宣称策略有效。

### R76.4 集成、真实数据试排与浏览器验收

- 先运行 focused tests，再运行康尼真实数据 `--no-persist`。
- 在独立 `APS_HOME` 完成导入、MPS、五策略、采用和导出。
- 在 Web 完成上传/选择数据、分析、试排、比较、采用、查看冲突、导出全过程。
- 保存脱敏的操作步骤、断言、结果摘要和残余现场数据缺口。

## 6. 成功标准

- 导入结果为 10/10 订单，所有订单均有非空工艺，BOM 缺失必须逐单解释而不是静默跳过。
- 工时来源统计可复核，真实值、推断值、缺失值分开计数。
- 设备/模具映射的现场确认状态如实展示；共享设备占位不计为真实能力完成。
- MPS trace 能关联本地排产版本和采用/发布事实，gap 可复算，跨作用域访问被拒绝。
- 五策略比较完成，采用动作不触发 MES；订单/设备 XLSX 可打开且内容与版本一致。
- focused、相邻回归、Web build、真实数据只读试排和浏览器流程全部通过。
- 原始 Excel 的 SHA-256 在试排前后完全一致，默认业务世界不被预检污染。

## 7. 验证方式

- `.\.venv\Scripts\python.exe -X utf8 -m pytest tests/golden/test_kangni_intake.py tests/golden/test_kangni_mapping_validation.py -q`
- `.\.venv\Scripts\python.exe -X utf8 -m pytest tests/golden/test_mps_planning.py tests/golden/test_kangni_flex.py tests/golden/test_schedule_exports.py -q`
- `.\.venv\Scripts\python.exe -X utf8 scripts/load_kangni.py --with-siblings --no-persist`
- `npm run build:web`
- 最终运行 `pytest tests/golden -q`，并做独立 Web 浏览器验收。

## 8. 风险与控制

| 风险 | 影响 | 控制方式 |
|---|---|---|
| generic sheet 无订单字段或字段歧义 | 错单或漏单 | 结构化定位；歧义失败关闭；逐订单证据 |
| 设备/模具能力仍未确认 | 结果不可用于现场承诺 | 占位显式标记；生产可用性判定保持 Partial |
| 真实数据污染默认世界 | 影响现有演示/用户数据 | `--no-persist` + 独立 `APS_HOME` + 前后哈希 |
| 多智能体共享脏工作区 | 覆盖用户改动 | 文件所有权互斥；禁止 reset/cleanup/commit/push；主 agent 集成 |
| MPS 接线误触发外部副作用 | 真实系统风险 | 本轮禁用 MES dispatch；相关路径测试断言无外部调用 |

## 9. 停止条件

- 需要修改康尼原始 Excel 才能继续。
- 无法通过结构化字段唯一关联订单与 generic sheet。
- 必须伪造设备/模具能力才能得到“可行”结果。
- 任一智能体需要越过分配文件范围，或发现其他智能体/用户正在修改同一文件。
- 真实数据预检导致默认业务世界、外部系统或原始文件发生变化。

## 10. 完成定义

- 三个实施工作片均完成自检并由主 agent 集成。
- 真实数据门禁在集成前执行，浏览器验收在集成后执行。
- 独立审计无 P0/P1 阻断；发现问题完成修复和复验。
- 输出主要结论、关键洞察和特别注意事项；未经用户确认不 commit/push/merge/部署。

PLAN AUDIT: PASS

Blocking issues: none。当前脏工作区为显式受保护基线，实施采用互斥写入范围与主 agent 集成，不执行提交和分支清理。

## 11. 完成情况

- 10/10 订单、72 条工序、26 个唯一工序、965/823 两种 BOM 口径已完成。
- Web 9 文件上传、冻结 P2、10 VL / 72 WO trial、五策略、MPS trace/adopt/gap、订单/设备导出已完成。
- focused **136 passed / 2 warnings**；full golden **1352 passed / 2 warnings**；Node **60 passed**；Web build 通过。
- 浏览器最终新标签 title 正确、console warning/error=0；两个版本化下载均实际触发。
- 残余边界：`productionReady=false`，设备/模具现场映射、库存/在途和 MES/WMS/SAP 外部联调未完成。
- 未执行 commit、push、merge、publish 或 MES dispatch。
- 独立审计经过三轮 blocking 修复后最终 `AUDIT PASS`；详见同轮 audit 与 fix log。