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 写入事件分开记录，禁止把该历史漂移伪称为本轮未发生。