# v3 / v5 业务方迭代 — 内容汇总

> **created**: 2026-05-16
> **作者**: chentao + Claude
> **触发**: 业务方在 workspace 根目录放了 3 个 v3 / v5 文件，需要并入 business-analysis

---

## 这次迭代是什么

业务方基于本目录之前的 `需求流程图.html` + `需求分析.md`，做了第二轮精细化：
- 主数据本体升级 **v3 → v5**（117 → 172 行，81 → 82 列）
- 新增**字段-节点映射矩阵**（解决"哪些字段在哪个节点主写"的争论）
- 流程图加 Master 字段覆盖标注（每节点 N 字段徽章 + ★ 主写 / ○ 只读区分）

3 个文件本目录新增：

| 文件 | 用途 | 关键变化 |
|---|---|---|
| [Master_Metadata_v5.xlsx](Master_Metadata_v5.xlsx) | 主数据本体 | 117 → **172 行** / 81 → **82 列**（+ Placeholder SN orig） |
| [Master_to_Node_Mapping_v3.xlsx](Master_to_Node_Mapping_v3.xlsx) | **字段 ↔ 节点映射矩阵** | 新文件 · 5 sheet · 82 列字段精确归属节点 |
| [Requirement_Workflow_with_Master_mapping_v3.html](Requirement_Workflow_with_Master_mapping_v3.html) | 流程图 + 字段映射可视化 | 基于本目录 `需求流程图.html` 二次开发 |

---

## 关键设计：`Placeholder SN` — FF SN 主写时机定论

业务方解决了一个核心争论：**FF SN 应该在哪个节点首次写入 Master？**

### 三版演化

| 版本 | FF SN 主写节点 | 理由 | 状态 |
|---|---|---|---|
| v1（初版）| 01 PO_CREATED | 直观映射 | 弃 |
| v2（用户纠正 1）| 07 RECEIVED | "PO 时机器人个体不存在，Master 行尚未创建" | 弃 |
| **v3（用户纠正 2 · 当前）** | **01 PO_CREATED（一表到底）** | "Sherry 需要在 PO 阶段跟进每台进度" + "v4 数据现实：67 条在途已有 FF SN" | ✅ |

### v3 的具体方案：占位 SN（Placeholder SN）

**PO 阶段**（在 Master 创建 N 行占位行）：
```
FF SN (key)         = "PO-2026-Q1-03-LINE-001"   ← 占位 SN
Status (Build)      = Ordered
Lifecycle Status    = Ordered
Model, Variant, Usage Type, PO, Date, Partner, Price = 实际值
```

**07 RECEIVED 阶段**（操作员扫供应商物理标签激活）：
```
1. 生成正式 FF SN（如 FFF1226030000123）
2. 将 FF SN (key) 从占位换成正式 SN
3. 原占位 SN 写入新列 Placeholder SN (orig)
4. Supplier SN 由扫码填入
5. Status(Build) → Received
6. Notes / Comments 追加 "Activated 2026-MM-DD HH:MM"
```

### 命名标准

- **推荐格式**: `{PO#}-LINE-{NNN}`
- **示例**: `PO-2026-Q1-03-LINE-001`
- **历史数据**: v5 当前 172 行的 `Placeholder SN (orig)` 默认 NULL（无历史可追溯），仅适用未来按此标准命名的新 PO

---

## 关键设计：字段 ↔ 节点精确映射

`Master_to_Node_Mapping_v3.xlsx` 含 5 sheet：

| Sheet | 内容 |
|---|---|
| 1. Field → Node | 82 行字段视角：每字段标"主写节点 ★" + "只读引用节点 ○" + 中文标签 + 说明 |
| 2. Node → Fields | 每节点的字段清单 + 数量 |
| 3. Matrix view | 字段 × 节点的 ★/○ 矩阵（82 × 30 节点） |
| 4. 版本演进 | v1 / v2 / v3 演化 |

### 字段归类规则（v3 引入）

| 类型 | 标记 | 含义 |
|---|---|---|
| **主写节点** | ★ primary | 字段第一次被写入 Master 的地方 |
| **只读引用** | ○ read | 该节点会显示/用到这个字段，但不修改 |
| **跨节点** | multi | 字段在多个节点都会更新（如 Lifecycle Status / Location）|
| **系统全局** | GLOBAL | 由系统自动维护，不归属任何业务节点（Sources / Conflict Count / Record Status）|

### 节点字段数分布

| 节点 | 主写字段数 | 关键字段 |
|---|---|---|
| 01 PO_CREATED | **10** | FF SN (key), FF SN, **Placeholder SN (orig)** 🆕, Model, Variant, Usage Type, PO, Purchase Date, Purchase Price, Partner |
| 02 IN_PRODUCTION | **0** | 我方不主写任何字段（工厂在制，跟踪人是 Sherry 但不在 Master 录入新字段）|
| 03 READY_TO_SHIP | 2 | Date ready, sticker |
| 04 IN_TRANSIT | 6 | Arrival Date, Logistics Status, Tariff Type, Import Declaration Type 等 |
| 05 BONDED | 1 | Compliance Notes |
| 06 CUSTOMS_CLEARED | 1 | FCC Status |
| 07 RECEIVED | 1 | **Supplier SN**（扫码激活）|
| 08 AT_W1_PDI | 2 | Issue, Issue Tag |
| 09 UNDER_MODIFICATION | 7 | 7 个 Label 字段（body-FCC / body Made in CN / SN Body / SN remote / Battery SN / Inspection Sheet / Shipping box） |
| 11 BRANDED_READY | **13** | Physical Product Status, Specialist + **10 个配件**（Robot/Battery/Remote/...）+ Days Ready for Delivery |
| 12 RESERVED | 10 | Customer, Sales Order ID, Contract Status, Mentor, Mentee, Sales Price ... |
| 13 PAYMENT_VALIDATED | 1 | Payment & Contract (PreDel) |
| P6.1 Payment_Collected | 4 | Payment Method, Payment, Deposit Transfer Form Link, Deposit Transfer Contract Link |
| 14 READY_FOR_DELIVERY | 3 | Delivery Request Type, Delivery Number, Expected Delivery Date |
| DA Delivery_Approval | 5 | Delivery Signed Form, Acceptance Form, Acceptance Form Status 等 |
| 15 DELIVERED | 6 | Delivery Date, Cost, Gross Margin, Revenue Recognition, Invoice Status, Warranty Status |
| ST Support_Ticket | 2 | Service Records, Customer Feedback |
| **multi** 跨节点 | 5 | Status (Build), Lifecycle Status, Location, Delivery Status, Notes / Comments |
| **GLOBAL** 系统 | 3 | Sources, Conflict Count, Record Status |

合计 82 列字段全部归位。

---

## v5 主数据本体的变化

vs v3（117 行 / 81 列）：

| 维度 | v3 | v5 | 变化 |
|---|---|---|---|
| 总记录 | 117 | **172** | +65 新增 / 83 修改 / 24 不变 / 1 删除 / 9 v3 幻影丢弃 |
| Master 列数 | 81 | **82** | +1（Placeholder SN (orig)）|
| 数据来源 | 4 个 Excel | 同 | Robot_Unit_Lifecycle_Tracker / Robotics_Inventory_Readiness / Pre-Delivery_Report / Robotics_Sales_Confirmation |
| Enum 字典 | 17 | 17 | +29 个新枚举值 |
| 非标 SN 标记 | — | 17 个 | 新质量信号 |

---

## 跟本目录之前文件的关系

| 之前的文件 | v3/v5 影响 |
|---|---|
| 需求分析.md（v1 业务分析）| 仍是事实源；本次 v3/v5 给"FF SN 主写时机"+"字段-节点映射"细化 |
| 需求流程图.html（v1 流程图）| v3 HTML 是它的二次开发版（加 Master 字段覆盖徽章 + ★/○ 映射）|
| 合理性分析.html | 仍有效；v3 的"占位 SN"方案补强了我提的"字段命名不规范"问题 |
| 覆盖率报告.html × 2 | v3 mapping 提升了字段覆盖率统计的精度（从粗对齐到字段级精确）|
| 实现差距报告.html | 需要更新：现实现 vs v3/v5 的差距比 vs v1 更大（多了 1 字段 + 多了占位 SN 激活机制）|

---

## 给系统实现的影响

新出现的需要建模的概念：

### 1. Placeholder SN 字段

`RobotUnit` 需要加新字段：
```prisma
placeholderSnOrig  String?  @map("placeholder_sn_orig")
```
配合 service 层"PO 创建 N 行占位 → RECEIVED 扫码激活"的状态机副作用。

### 2. 字段级 owner（★ vs ○）

`RobotFieldDef` 需要加：
```prisma
primaryWriteNode   String   @map("primary_write_node")
readOnlyNodes      String[] @map("read_only_nodes")
// 或者 cross-node 标识
crossNodeWritable  Boolean  @default(false)
```

这是字段 owner 制度的事实源（在 v5 mapping 里业务方已经定好了）。

### 3. 全局字段（GLOBAL）

3 个系统字段：Sources / Conflict Count / Record Status — 不归属任何业务节点，由系统自动维护。一旦数据统一进 FFOA，这 3 个的概念会演化为 audit/数据治理服务。

### 4. 节点字段数高度不均

- 11 BRANDED_READY 13 字段（配件 10 + 标记字段 3）— **要么拆 RobotAccessory 子表，要么用 metadata JSONB 平摊**
- 09 UNDER_MODIFICATION 7 字段全是 Label — **拆 RobotLabelRecord 子表更合理**
- 02 IN_PRODUCTION 0 字段 — 工厂在制阶段我方不录入，只是状态推进

---

## 下一步要讨论的事

1. **Placeholder SN 命名标准的执行边界** — 现有 172 行不动，新建的 PO 是否强制走 `{PO#}-LINE-{NNN}`？
2. **字段 ★/○ 的代码强制程度** — 仅业务约定 vs Service 层守卫 vs 数据库 trigger
3. **配件 / Label 子表 vs JSONB** 的最终选择
4. **业务报表 R1-R8 在 v3 mapping 后的查询路径**