aps-agent/docs/product/ruiyang-data-runbook.md

# 锐扬现场数据接入手册（MOM 主数据收集表 → APS 排产）

> 适用：湖南锐扬创科智能科技有限公司 · 项目「新工厂排产项目」。
> 配套实现：`server/aps_domain/importers.py`（round-55/57 模板识别 + 制造流程提取）与 `server/aps_domain/folder_pack.py`（round-61 非排产块跳过统计、round-63 结构化诊断与真实 Excel 行号）。

## 1. 工程目录

- 目录：由 `RUIYANG_DEMO_DIR` 指定
- 系统会自动扫描该目录下的 `.xlsx/.xlsm/.csv/.txt/.sql`（跳过 `~$` 临时文件）。
- 放好数据后，在工作台说「**给我模拟排产一下**」或「**带我排一版**」，系统先分析数据齐备度，再出 P2 确认卡（导入 + 试排，可回滚）。

## 2. 主数据收集表 sheet 映射（round-55/57/61/63）

| 文件 sheet | 内容 | 导入类型 | 说明 |
| --- | --- | --- | --- |
| 02-工艺模型 | 物料清单（BOM/物料） | 物料 + **工艺路线** | 每行 = 一个物料（ERP品号→编码、产品名称→名称）；**第 17 列「制造流程」= 工艺代码序列**（如 `ZP01组装 / LM01POP拉铆 / BZ01机柜包装`，次行 01..12 为工序序号）→ 自动提取为工艺路线 |
| 04-物料模型 | 物料主数据 | 物料 | 「物料主数据」块第 5 行起为真实表头；物料组名称(成品/半成品/原材料)→类型；规格型号→spec |
| 07-设备模型 | 设备台账 | 设备 | 财务编号/固定资产编号/厂内编号→设备编码（最后一个非空值优先，空别名不覆盖已有编码）、设备名称→名称；无「可执行工序」列时暂记 GENERAL（需后续确认） |
| 01/03/05/06/09/10 | 工厂/质检/仓储/人力/客户/供应商 | 不导入 | 非排产数据块，已跳过且不计问题行；原始行数单独计入 `skippedRows`，不影响其余有效行入库 |

**字段别名**（圆括号内为系统标准字段，表头自动匹配）：
- 编码：ERP品号 / 财务编号 / 固定资产编号 / 厂内编号 / 物料编码 / 物料代码 / 编码（code）
- 名称：物料名称 / 物料简称 / 产品名称 / 名称（name/name/productName）
- 数量：单套用量 / 数量 / 用量（quantity）
- 类型：物料组名称 / 物料类型 / 类型（type）
- 其他：单位、库存、规格型号(spec)、交期、订单号、客户、优先级、加急(isRush)

## 3. 订单表（样例已就绪）

现场表没有订单 sheet；排产必须有订单。请在该目录新增一个订单表（CSV 或 Excel 均可），列名按下表：

| 列名 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- |
| 订单号 | 是 | 唯一编号 | SO-RY-20260801 |
| 客户 | 是 | 客户/项目名称 | 比亚迪 |
| 产品编码 | 是 | 必须是 02/04 表里的成品编码（如 A0050101-00280） | A0050101-00280 |
| 数量 | 是 | 整数 | 1 |
| 交期 | 是 | YYYY-MM-DD（**不能留空**） | 2026-08-30 |
| 优先级 | 否 | 1-9，默认 5 | 5 |
| 加急 | 否 | 是/否 | 否 |

已放置样例：`订单-样例.csv`（改掉示例行即可；导入前系统会校验产品编码/数量/交期，错误行不入库）。

> 2026-08-02 round-63 全链路复核：订单样例入目录后，目录分析得到 **有效行 1404 / 问题行 1 / 跳过 974**。结构化诊断为 ignored 979（974 非排产块 + 5 内嵌表头/字典行）、warning 181（134 台设备暂按 GENERAL + 47 行重复编码列恢复）、blocking 1。唯一阻塞是 `07-设备模型` **Excel 第 130 行**“3.8吨锂电叉车”：财务编号、固定资产编号、厂内编号均为空；出厂编号仅保留审计，不冒充业务编码。

## 4. 排产必备清单（当前状态 2026-08-02）

| 必备项 | 状态 | 说明 |
| --- | --- | --- |
| 物料 | ✅ 823 行 | 02 工艺模型 415 + 04 物料模型 408 |
| 工艺路线 | ✅ 446 行 | 02 制造流程列提取（如 ZP01组装→ZP01/组装） |
| 设备 | ⚠️ 134 行可导入 / 1 行阻塞 | 134 台缺工序能力时暂按 GENERAL；Excel 第 130 行设备业务编码全空，修复后即可消除唯一问题行 |
| 订单 | ✅ 样例就绪 | `订单-样例.csv` 已入目录，目录分析显示「可开排」；**替换为真实订单后即可开排** |

## 5. 注意事项

- **工时**：现场表无工时列，工艺路线默认按 1 分钟/件兜底；需要准确排产请补「工时」列（表头：产品编码/序号/工序编码/工时[分钟]）或单独工时表。
- **问题行、诊断与跳过行**：**非排产数据块已跳过且不计问题行**；`totalErrors` 只统计 blocking；结构行记 ignored、可恢复别名和 GENERAL 兜底记 warning，均不膨胀问题行。非排产块原始行数仍单独计入 `skippedRows`。每条诊断保留真实 `sheet + excelRow + rawSummary`，现场可直接回到 Excel 修复。
- **确认卡**：P2 需人工确认（批准后写入柔性主数据并试排一版，可回滚）；JMS 登录用户默认 planner 角色可发起/批准（round-56）。
- 端到端路径：放文件 → 「带我排一版」→ 目录分析 → P2 确认 → 试排一版 → 甘特/负荷/交期看板。

## Round 65 闭环验收（2026-08-03）

1. 复制现场 world 到内存/临时目录，不对 `server/data/**` 执行 P1/P2/P3 写入测试。
2. 按 2026-08-02 历史验收日与 2026-08-03 当前日分别重算，数量均为 106 MAKE / 124 BUY / 0 SUBCONTRACT。
3. 当前主数据必须阻断：39 缺工艺、67 模板/缺资源能力、124 供应短缺/草稿供应不可信；新版本 0 VL/WO。
4. 只有工厂补齐正式工艺、ASM 能力、班组/模具、可信到货日期后才可重跑并进入 P2。
5. 证据文件：`docs/round-65-aps-end-to-end-runtime-final.json`；当前源 world 在隔离运行前后 SHA-256 一致。历史基线 hash 与 2026-08-03 10:10:24 的旧订单 GET 写入事件分开记录，禁止把该历史漂移伪称为本轮未发生。
-												feat: APS 智能排产智能体全量实现（M-POC~M6 + 跨阶段治理 + round-1~66）

- 智能体核心：Harness 门禁/_POWER_MAP、P2/P3 确认卡、证据链、Plan 运行时 L0-L3、统一工具运行时、自动化 G0-G4
- 领域层：Rule/CP-SAT/GA/NSGA-II/LNS 引擎、13 类约束目录、IIS 冲突归因、敏感性/蒙特卡洛、插单重排、MRP 分解
- 状态层：世界/对话成对快照、分支树、检查点、Saga 补偿、审批文件/DB 双后端
- 集成层：MCP 插件总线、MES/WMS 适配器（stub+HTTP）、异步任务
- 前端：左说右动工作台（聊天+甘特/负荷/交期）、主数据、订单、治理台、分支树、时间线、审计统计
- 桌面端：Electron 壳 + Python Sidecar + NSIS 打包 + 许可证
- 文档：plan.md 蓝图、完成矩阵（50 Done/10 Partial/0 Missing）、CHANGELOG 全量账本、各轮次计划/状态
- 验证基线：黄金测试 1000+ 项、Node 60 项、Web build 通过（详见 docs/CHANGELOG.md）

											
										
										
											2026-08-20 11:39:21 +08:00
+								# 锐扬现场数据接入手册（MOM 主数据收集表 → APS 排产）
 								> 适用：湖南锐扬创科智能科技有限公司 · 项目「新工厂排产项目」。
 								> 配套实现：`server/aps_domain/importers.py`（round-55/57 模板识别 + 制造流程提取）与 `server/aps_domain/folder_pack.py`（round-61 非排产块跳过统计、round-63 结构化诊断与真实 Excel 行号）。
 								## 1. 工程目录
-												feat: complete Pi Agent integration and remove environment hardcoding

											
										
										
											2026-09-08 00:07:26 +08:00
+								- 目录：由 `RUIYANG_DEMO_DIR` 指定
-												feat: APS 智能排产智能体全量实现（M-POC~M6 + 跨阶段治理 + round-1~66）

- 智能体核心：Harness 门禁/_POWER_MAP、P2/P3 确认卡、证据链、Plan 运行时 L0-L3、统一工具运行时、自动化 G0-G4
- 领域层：Rule/CP-SAT/GA/NSGA-II/LNS 引擎、13 类约束目录、IIS 冲突归因、敏感性/蒙特卡洛、插单重排、MRP 分解
- 状态层：世界/对话成对快照、分支树、检查点、Saga 补偿、审批文件/DB 双后端
- 集成层：MCP 插件总线、MES/WMS 适配器（stub+HTTP）、异步任务
- 前端：左说右动工作台（聊天+甘特/负荷/交期）、主数据、订单、治理台、分支树、时间线、审计统计
- 桌面端：Electron 壳 + Python Sidecar + NSIS 打包 + 许可证
- 文档：plan.md 蓝图、完成矩阵（50 Done/10 Partial/0 Missing）、CHANGELOG 全量账本、各轮次计划/状态
- 验证基线：黄金测试 1000+ 项、Node 60 项、Web build 通过（详见 docs/CHANGELOG.md）

											
										
										
											2026-08-20 11:39:21 +08:00
+								- 系统会自动扫描该目录下的 `.xlsx/.xlsm/.csv/.txt/.sql`（跳过 `~$` 临时文件）。
 								- 放好数据后，在工作台说「**给我模拟排产一下**」或「**带我排一版**」，系统先分析数据齐备度，再出 P2 确认卡（导入 + 试排，可回滚）。
 								## 2. 主数据收集表 sheet 映射（round-55/57/61/63）
 								| 文件 sheet | 内容 | 导入类型 | 说明 |
 								| --- | --- | --- | --- |
 								| 02-工艺模型 | 物料清单（BOM/物料） | 物料 + **工艺路线** | 每行 = 一个物料（ERP品号→编码、产品名称→名称）；**第 17 列「制造流程」= 工艺代码序列**（如 `ZP01组装 / LM01POP拉铆 / BZ01机柜包装`，次行 01..12 为工序序号）→ 自动提取为工艺路线 |
 								| 04-物料模型 | 物料主数据 | 物料 | 「物料主数据」块第 5 行起为真实表头；物料组名称(成品/半成品/原材料)→类型；规格型号→spec |
 								| 07-设备模型 | 设备台账 | 设备 | 财务编号/固定资产编号/厂内编号→设备编码（最后一个非空值优先，空别名不覆盖已有编码）、设备名称→名称；无「可执行工序」列时暂记 GENERAL（需后续确认） |
 								| 01/03/05/06/09/10 | 工厂/质检/仓储/人力/客户/供应商 | 不导入 | 非排产数据块，已跳过且不计问题行；原始行数单独计入 `skippedRows`，不影响其余有效行入库 |
 								**字段别名**（圆括号内为系统标准字段，表头自动匹配）：
 								- 编码：ERP品号 / 财务编号 / 固定资产编号 / 厂内编号 / 物料编码 / 物料代码 / 编码（code）
 								- 名称：物料名称 / 物料简称 / 产品名称 / 名称（name/name/productName）
 								- 数量：单套用量 / 数量 / 用量（quantity）
 								- 类型：物料组名称 / 物料类型 / 类型（type）
 								- 其他：单位、库存、规格型号(spec)、交期、订单号、客户、优先级、加急(isRush)
 								## 3. 订单表（样例已就绪）
 								现场表没有订单 sheet；排产必须有订单。请在该目录新增一个订单表（CSV 或 Excel 均可），列名按下表：
 								| 列名 | 必填 | 说明 | 示例 |
 								| --- | --- | --- | --- |
 								| 订单号 | 是 | 唯一编号 | SO-RY-20260801 |
 								| 客户 | 是 | 客户/项目名称 | 比亚迪 |
 								| 产品编码 | 是 | 必须是 02/04 表里的成品编码（如 A0050101-00280） | A0050101-00280 |
 								| 数量 | 是 | 整数 | 1 |
 								| 交期 | 是 | YYYY-MM-DD（**不能留空**） | 2026-08-30 |
 								| 优先级 | 否 | 1-9，默认 5 | 5 |
 								| 加急 | 否 | 是/否 | 否 |
 								已放置样例：`订单-样例.csv`（改掉示例行即可；导入前系统会校验产品编码/数量/交期，错误行不入库）。
 								> 2026-08-02 round-63 全链路复核：订单样例入目录后，目录分析得到 **有效行 1404 / 问题行 1 / 跳过 974**。结构化诊断为 ignored 979（974 非排产块 + 5 内嵌表头/字典行）、warning 181（134 台设备暂按 GENERAL + 47 行重复编码列恢复）、blocking 1。唯一阻塞是 `07-设备模型` **Excel 第 130 行**“3.8吨锂电叉车”：财务编号、固定资产编号、厂内编号均为空；出厂编号仅保留审计，不冒充业务编码。
 								## 4. 排产必备清单（当前状态 2026-08-02）
 								| 必备项 | 状态 | 说明 |
 								| --- | --- | --- |
 								| 物料 | ✅ 823 行 | 02 工艺模型 415 + 04 物料模型 408 |
 								| 工艺路线 | ✅ 446 行 | 02 制造流程列提取（如 ZP01组装→ZP01/组装） |
 								| 设备 | ⚠️ 134 行可导入 / 1 行阻塞 | 134 台缺工序能力时暂按 GENERAL；Excel 第 130 行设备业务编码全空，修复后即可消除唯一问题行 |
 								| 订单 | ✅ 样例就绪 | `订单-样例.csv` 已入目录，目录分析显示「可开排」；**替换为真实订单后即可开排** |
 								## 5. 注意事项
 								- **工时**：现场表无工时列，工艺路线默认按 1 分钟/件兜底；需要准确排产请补「工时」列（表头：产品编码/序号/工序编码/工时[分钟]）或单独工时表。
 								- **问题行、诊断与跳过行**：**非排产数据块已跳过且不计问题行**；`totalErrors` 只统计 blocking；结构行记 ignored、可恢复别名和 GENERAL 兜底记 warning，均不膨胀问题行。非排产块原始行数仍单独计入 `skippedRows`。每条诊断保留真实 `sheet + excelRow + rawSummary`，现场可直接回到 Excel 修复。
 								- **确认卡**：P2 需人工确认（批准后写入柔性主数据并试排一版，可回滚）；JMS 登录用户默认 planner 角色可发起/批准（round-56）。
 								- 端到端路径：放文件 → 「带我排一版」→ 目录分析 → P2 确认 → 试排一版 → 甘特/负荷/交期看板。
 								## Round 65 闭环验收（2026-08-03）
 . 复制现场 world 到内存/临时目录，不对 `server/data/**` 执行 P1/P2/P3 写入测试。
 . 按 2026-08-02 历史验收日与 2026-08-03 当前日分别重算，数量均为 106 MAKE / 124 BUY / 0 SUBCONTRACT。
 . 当前主数据必须阻断：39 缺工艺、67 模板/缺资源能力、124 供应短缺/草稿供应不可信；新版本 0 VL/WO。
 . 只有工厂补齐正式工艺、ASM 能力、班组/模具、可信到货日期后才可重跑并进入 P2。
 . 证据文件：`docs/round-65-aps-end-to-end-runtime-final.json`；当前源 world 在隔离运行前后 SHA-256 一致。历史基线 hash 与 2026-08-03 10:10:24 的旧订单 GET 写入事件分开记录，禁止把该历史漂移伪称为本轮未发生。