# 锐扬案例一键演示数据链路

## 1. 目标

基于 `RUIYANG_DEMO_DIR` 指向的真实目录，完成：

1. 解析案例文件夹并盘点 XLSX/DXF；
2. 使用正式 `mom_pack` 导入器生成 flex 主数据；
3. 使用正式同步函数生成 canonical 主数据；
4. 执行多层 BOM MRP 分解；
5. 输出严格闭环准入诊断；
6. 在显式、可审计的演示假设下生成生产订单和工单；
7. 将完整 world 和订单面板数据写入 `outputs/ruiyang-demo`，供后端/桌面端接入。

脚本不修改活动项目 world，不修改 `server/`、前端或桌面核心。

## 2. 真实文件盘点（2026-08-05）

- `湖南锐扬MOM主数据收集表.xlsx`：9 个工作表。
- DXF：3 个。
  - `5060102101-001-e(1).dxf`
  - `5060102101-002-e(1).dxf`
  - `5060102101-003-e(1).dxf`
- 3 个 DXF 文件名在 Excel 单元格中没有直接匹配，当前只做文件级盘点，不虚构图纸与物料关系。

## 3. 一键命令

### PowerShell（桌面演示推荐）

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\run-ruiyang-demo.ps1 `
  -SourceDir $env:RUIYANG_DEMO_DIR `
  -BusinessDate '2026-08-05' `
  -ScheduleStart '2026-08-06' `
  -DueDate '2026-09-04'
```

省略日期参数时，脚本以运行当天为业务日期，次日为排产起点，业务日期后 30 天为演示交期。

### Python

```powershell
python .\scripts\ruiyang_demo.py `
  --source-dir "$env:RUIYANG_DEMO_DIR" `
  --business-date 2026-08-05 `
  --schedule-start 2026-08-06 `
  --due-date 2026-09-04
```

## 4. 双投影硬门禁

脚本在 MRP 之前强制验证 flex/canonical 两套投影，任一失败立即退出：

- `boms >= 3`
- `bomItems >= 42`
- `routings >= 3`
- `routingSteps >= 15`
- `canonical.bomItems == flex.flexBom`
- `canonical.routingSteps == flex.flexRoutings`
- `canonical.materials == flex.flexMaterials`
- `canonical.salesOrders == flex.flexOrders`

完整原始 XLSX 当前实测为：

| 投影 | 数据量 |
|---|---:|
| flexMaterials | 253 |
| flexBom | 383 |
| flexEquipment | 135 |
| flexOrders | 1 |
| flexRoutings | 400 |
| materials | 253 |
| boms | 119 |
| bomItems | 383 |
| routings | 80 |
| routingSteps | 400 |
| salesOrders | 1 |

这可以直接识别“会话回复已分解，但项目 world 只有 flex 数据、canonical BOM/工艺为空”的问题。

## 5. MRP 与订单面板预期

当前真实文件的稳定结果：

- 销售订单：1 张（源文件无销售订单号，演示号为 `RY-DEMO-A0050101-00280`）。
- 自制建议：106 条。
- 采购建议：124 条。
- 委外建议：0 条。
- 演示排产后生产订单：1 张。
- 工单：5 张，对应 CUT、BEND、WELD、PAINT、ASM。

订单面板应读取 `07-order-panel.json` 或 `world-ruiyang-demo.json` 中：

- `salesOrders`
- `makeSuggestions`（输出面板键为 `make`）
- `purchaseOrders`
- `outsourceOrders`
- `productionOrders`
- `workOrders`

## 6. 为什么严格闭环仍会 BLOCKED

真实文件当前存在以下正式准入缺口：

- Excel 没有销售订单交期，必须由演示参数补充；
- 当前导入器对 02-工艺模型的真实制造流程码尚未逐列解析，而是生成五道模板工艺；
- 67 个自制需求为未确认模板工艺；
- 39 个半成品缺完整工艺路线；
- 124 条采购记录是 DRAFT 建议，不能作为可信供应；
- ASM 在设备台账中没有原生能力标签。

因此 `04-strict-readiness.json` 保留正式 `CLOSED_LOOP_V1` 的阻断结果，不能把“演示可排”误报为“生产可发布”。

## 7. 演示适配层

为了让桌面演示完整走到生产订单/工单，脚本显式执行以下适配并写入 `05-demo-adapter.json`：

- 使用参数补充交期；
- 将根产品绑定到正式同步生成的“柔性能力池”；
- 从真实设备中选择：
  - CUT：光纤激光切割机；
  - BEND：数控折弯机；
  - WELD：二保焊接机器人；
  - PAINT：喷粉线设备；
  - ASM：真实压铆机作为组装代理；
- 生成 08:00-17:00 演示白班；
- 默认按本次 MRP 净需求建立演示齐套快照。

不希望假设齐套时，使用：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\run-ruiyang-demo.ps1 -NoAssumeKitted
```

此时仍会生成排产草案，但会保留真实缺料冲突。

## 8. 输出文件

默认目录：`outputs/ruiyang-demo`

| 文件 | 用途 |
|---|---|
| `00-source-inventory.json` | XLSX/DXF 清单、大小、SHA-256、DXF 实体统计 |
| `01-field-mapping.json` | 源字段到 flex/canonical 字段映射 |
| `02-import-projection.json` | 导入结果、双投影计数和硬门禁 |
| `03-mrp.json` | 自制/采购/委外建议及完整摘要 |
| `04-strict-readiness.json` | 正式闭环准入阻断及原因 |
| `05-demo-adapter.json` | 演示假设、真实设备映射、齐套假设 |
| `06-schedule.json` | 排产版本、生产订单、工单、冲突 |
| `07-order-panel.json` | 订单面板可直接消费的数据集合 |
| `compact-ruiyang-demo.json` | 精简演示包：计数、样例、设备映射、1 张生产订单和 5 张工单 |
| `world-ruiyang-demo.json` | 完整隔离演示 world |
| `summary.json` | 一页式结果摘要 |
| `manifest.json` | 输出文件大小和 SHA-256 |

## 9. 验证

```powershell
python -m pytest tests/golden/test_ruiyang_demo_flow.py -q
```

PowerShell 一键脚本在生成后会自动执行 `scripts/verify_ruiyang_demo.py`，校验源目录、2026-08-05 业务日期、双投影、MRP、生产订单/工单和全部输出哈希。

Golden 测试使用真实 XLSX，并重复验证：文件盘点、双投影、MRP 数量、严格闭环阻断、真实设备映射、精简包、生产订单/工单以及输出哈希。

## 10. 桌面端接入边界

桌面端只需负责两件事：

1. 安装包中提供“一键准备锐扬案例”入口，执行 `scripts/run-ruiyang-demo.ps1` 或等价 Python 命令；
2. 后端加载 `outputs/ruiyang-demo/world-ruiyang-demo.json` 后刷新订单/主数据/排产视图。

本数据链路不直接修改当前活动 world，避免覆盖用户已有项目。