# 核心业务旅程（已落地）

> 只描述**当前代码真实路径**。规划能力见 `features.md` 🔜 项与 `plan.md`。

---

## 旅程 A：试排一版并看图

```mermaid
sequenceDiagram
  participant U as 用户
  participant Web as apps/web
  participant GW as gateway
  participant Intent as intent
  participant WF as workflow
  participant Eng as RuleEngine
  participant Store as WorldStore

  U->>Web: 「试排一版交期优先」
  Web->>GW: POST /api/chat (SSE)
  GW->>Intent: 解析 → schedule.run + strategy
  Intent->>WF: 编排
  WF->>Eng: solve(world, params)  P1
  Eng->>Store: 写入 DRAFT 版本/PO/WO/冲突
  WF-->>Web: 文本 + 可选 UI 块
  Web->>GW: GET /api/world/gantt|load|due
  GW-->>Web: 右侧刷新
```

**业务语义（正确口径）**

1. 只处理未取消/未完成的销售订单及其未完成明细。  
2. 按策略模板排序后，为每个订单项选产线、按工艺路线拆工单、在班次窗内顺排占槽。  
3. 产出 **DRAFT** 排产版本；**不**自动发布。  
4. 冲突写入世界状态，甘特/交期视图可高亮；**不会**自动改主数据或采购计划。

**口令示例**：试排一版交期优先 / 按产能均衡排一下  

---

## 旅程 A2：维护订单后再试排

```mermaid
sequenceDiagram
  participant U as 用户
  participant Web as 订单面板
  participant GW as gateway
  participant Harness as harness
  participant WF as workflow
  participant Store as WorldStore

  U->>Web: 新增/编辑/取消/完成订单
  Web->>GW: POST /api/orders/stage
  GW->>Harness: stage_confirmation(order.*)
  Harness-->>Web: confirm-card
  U->>Web: 批准
  Web->>GW: POST /api/actions/confirm
  GW->>WF: execute_confirmed(order.*)
  WF->>Store: 写订单池 + 审计 + 自动 Checkpoint
  U->>Web: 再试排
```

**业务语义（正确口径）**

1. `GET /api/orders` 是 P0 只读投影；页面展示订单、成品下拉、状态枚举。  
2. `order.upsert` / `order.cancel` / `order.complete` 都是 P2，页面只生成确认卡，真正执行仍走 `/api/actions/confirm`。  
3. `CANCELLED` / `COMPLETED` 订单不会进入后续新排产版本；历史已生成版本不被回写。  
4. 当前首切片每张销售订单只维护一个明细行；批量明细、附件后置。订单池审核（OR-03）、预测台账（OR-05）已另切片落地。  

**验收口径**：取消一张订单并批准后再试排，版本 `orderCount` 从 7 变为 6，且没有对应生产订单。

---

## 旅程 A3：维护主数据后再试排（MD-01/02/03）

1. 侧栏「主数据」→ 三页签：**资源**（工厂→车间→产线→工位→设备树）/ **物料与BOM** / **日历与维保**  
2. `GET /api/master` 是 P0 只读投影；编辑动作只生成确认卡（`POST /api/master/stage`），执行仍走 `/api/actions/confirm`  
3. 三个 P2 写动作与影响面：

| 动作 | 改什么 | 对新排产的影响 |
| --- | --- | --- |
| `master.line.upsert` | 产线名称/日产能/效率/停启用 | 停用（INACTIVE）产线被引擎 ACTIVE 过滤排除，订单走替代产线 |
| `master.material.upsert` | 物料库存/在途/安全库存/前置期 | 齐套检查输入变化，缺料冲突随之增减 |
| `master.maintenance.upsert` | 维保窗口新增/取消 | 新窗口产生 `EQUIPMENT` 冲突或避让；取消后窗口失效 |

4. 所有写入执行前自动 Checkpoint、写审计链；**只影响后续新版本，历史版本不回写**。

**验收口径**：停用一条产线并批准后再试排，新版本没有任何工单落在该产线（`test_master_data.py`）。

**纠偏**：工位/设备编辑、周日历模板为后续切片；**Excel/CSV 导入（MD-04）已落地**（订单/主数据面板「导入」→ preview → P2 确认）；BOM 明细用量与工艺步骤（工时/外协）已可编辑；柔性资源见主数据「柔性资源」页签。

---

## 旅程 A4：订单分解（MRP，对标西门子订单驱动分解）

```mermaid
flowchart LR
  SO["销售订单"] --> DEC["order.decompose P1<br/>按 BOM/工艺展开"]
  DEC --> MAKE["自制：成品<br/>→ 试排生成 PO/WO"]
  DEC --> BUY["采购建议 DRAFT<br/>净需求+前置期倒排"]
  DEC --> OUT["委外建议 DRAFT<br/>外协工艺步骤"]
  MAKE --> SCHED["schedule.run 排产"]
  BUY -.-> REL["确认下达（后续 P2/P3）"]
  OUT -.-> REL
```

1. 入口：订单面板「分解建议」「分解此单」，或对话「分解订单 SOxxx」「生成采购建议」「MRP」  
2. 分解逻辑（全部来自主数据，改主数据即改分解结果）：

| 分支 | 依据 | 产出 |
| --- | --- | --- |
| 自制 | 订单明细成品 | 由排产引擎（试排）生成生产订单与工单 |
| 采购 | BOM 净需求 = 毛需求 − 库存 − 在途 > 0 | `purchaseOrders` DRAFT：数量、建议下单日（交期−前置期−1 天） |
| 委外 | 工艺步骤 `isExternal` 标记 | `outsourceOrders` DRAFT：产品、工序、数量、需求日 |

3. `order.decompose` 是 **P1**：只写建议表草稿，不改订单与主数据；重复分解幂等替换  
4. 建议单确认下达（转正式采购/委外，联动 ERP）为后续 P2/P3 能力  

**验收口径**：把某原料库存调零 → 分解 → 采购建议出现且下单日按前置期倒排；在工艺步骤勾「外协」→ 重分解 → 委外建议出现（`test_mrp.py`）。

---

## 旅程 B：多策略对比后采用

1. 「对比几种策略」→ `scenario.compare`（P1）  
2. 深拷贝沙盒内并行多策略试排 → 返回 `scenario-cards`（KPI/差异）  
3. **主干世界此时不变**  
4. 用户点「采用此方案」→ 正式 `schedule.run`（或 apply 通道）把选中策略落到主干草稿  
5. 右侧视图刷新  

**纠偏**：对比 ≠ 发布；采用 ≠ 下发 MES。

---

## 旅程 C：发布版本（写主干）

1. 「发布这个版本」→ `schedule.publish`（P2）  
2. 后端只 **暂存确认卡**，不执行  
3. 用户点批准 → `/api/actions/confirm` + 一次性令牌  
4. 执行前自动建 Checkpoint → 版本变 PUBLISHED、相关订单状态推进 → 审计链记账  

**纠偏**：任何绕过确认卡的「直接 publish API」都不应存在（唯一执行通道）。

---

## 旅程 D：存档与回滚

| 步骤 | 动作 | 权力 |
| --- | --- | --- |
| 存档 | 「存个档」→ `checkpoint.create` | P1 |
| 回滚 | 点时间线或「回滚」→ `checkpoint.rollback` | P2 确认卡 |
| 安全网 | 回滚执行前再自动建档 | — |

检查点是**对话上下文 + 世界状态**成对快照（见 `state/checkpoints.py`）。

---

## 旅程 E：知识问答与报告

| 用户说 | 意图 | 要点 |
| --- | --- | --- |
| 换线有什么规定 | `knowledge.query` P0 | 命中必须带出处；未命中诚实说没有 |
| @知识:某标题 | 同上，直达资产 | — |
| 生成日报 / 版本对比 | `report.generate` P1 | 数字来自冻结快照模板，LLM 不得改数 |

---

## 旅程 F：重置演示数据

「清空数据重新初始化」→ `data.reset`（P2）→ 确认后重播种子。  
种子是**电子装配演示工厂**，不是客户生产库。

---

## 前端项目树 vs 后端世界（易混点）

| 概念 | 存在哪里 | 含义 |
| --- | --- | --- |
| 项目 / 任务 / 聊天记录 | 浏览器 localStorage | 工作区组织，**尚未**与多租户后端世界 1:1 |
| 排产世界（订单/工单/版本） | 后端 `WorldStore` | 当前进程一份演示世界 |
| 排产版本文件登记 | 前端项目「文件」区 | UI 登记，便于找回 |

**纠偏**：删前端「项目」≠ 清空后端排产世界；后端 reset 才清世界。

---

## 失败与降级（产品应知）

| 情况 | 行为 |
| --- | --- |
| LLM 超时/非法 JSON | 降级正则意图 |
| 未登记动作 | 按 P3 拒绝 |
| 知识未命中 | 明确告知，不编造 SOP |
| 治理测跑阻塞 | 测试在线程池跑，不拖死世界视图 API |