# 机器人管理流程图 — backend 实现现状审计

**审计日期**：2026-05-17
**审计基线**：`docs/modules/robot-manager/business-analysis/robot-lifecycle.yaml`（28 节点 + 3 子流程）
**审计对象**：`backend/src/modules/robot-manager/**`（含 l3-business / services / controllers）

---

## 总体覆盖率：85% (24 / 28 节点完整 + 4 节点有缺口)

| 实现状态 | 数量 | 节点 |
|---|---|---|
| ✅ **完整实现** | 24 | 02 / 03 / 04 / 05 / 06 / 08 / 16 / 09 / 10 / 11 / 12 / P6.1 / 14 / DA / 15 / 17 / ST / RR / W6 / 18 / 19 / 21 + DELIVERED 分流 + W6 三向 fan-out |
| 🟡 **部分实现** | 3 | 01 / 07 / 13 |
| ❌ **未实现** | 1 | QA 保修外报价 |
| ➖ **可合并**（无独立 endpoint 但状态机已覆盖）| 2 | FT W3 功能测试 / DV 交付验证 |

---

## 完整实现 ✅（24 节点）

| Seq | 节点 | 主要 API / Service | 备注 |
|---|---|---|---|
| 02 | 工厂在制 | `POST :id/change-stage` + `PUT :id` | Status(Build)=WIP 通过 update |
| 03 | 工厂可发运 | `PUT robot-records/readiness` + `change-stage` | G1/G2 通过状态机校验 |
| 04 | 国际运输 | `POST logistics-legs` + `change-stage` | 6 字段（HTS / 关税 / 运单 / 到货日期） |
| 05 | 保税 | `change-stage` + `PUT compliance` | 合规备注 |
| 06 | 已清关 G3 | `PUT compliance` + `change-stage` | FCC Status |
| 08 | W1 改装前初检 | `change-stage`（含分流校验 W2_RLE / MODIFICATION）| 健康度 / 分流路径 |
| 16 | W2 外采库 | `change-stage` + `POST :id/move-location` | RLE 免改装直入 |
| 09 | 本地化改装 | `PUT quality-labels`（7 个标签字段） | 机身 / 遥控器 / 电池 / 检验单 / 出货箱 标 |
| 10 | 改装验收 | `change-stage` | Conversion Validation Gate |
| 11 | W4 可售库存 | `PUT readiness`（13 字段：Specialist + 10 配件 + 可交付天数） | |
| 12 | 已锁单 G4 | `POST sales-orders` | Customer / SO# / Mentor / Mentee / 销售价 / 协议链接 |
| P6.1 | 收款记录 | `POST payments` + `POST :id/mark-paid` | 4 字段：付款方式 / 金额 / 收款状态 / 转账单链接 |
| 14 | 准备交付 | `POST delivery-requests` | 交付方式 / 预计日期 / 交付单号 |
| DA | 交付审批 | `PUT delivery-requests/:id` | 签字表 / 验收表 / 审批人 |
| 15 | 已交付 G6 | `POST delivery-fulfillments` + `change-stage` | PGI 触发收入确认 + 发票 + 保修激活 |
| 17 | 租赁中 | `POST rentals` + `POST :id/terminate` | W5 租赁仓 + 租期跟踪 |
| ST | 售后工单 | `POST service-tickets` + `POST :id/activities` | 工单号 / 服务记录 / 客户反馈 |
| RR | 退回签收 | `change-stage` | 总部签收入库 |
| W6 | 售后库（三向处置）| `change-stage` 支持 3 路推进（UNDER_REPAIR / QUOTE_APPROVAL / CLOSED） | fan-out 状态机已就绪 |
| 18 | 维修中 | `change-stage` + service-ticket activities | 处置方式=In Repair |
| 19 | 已修复 | `change-stage` 支持回 DELIVERED / BRANDED_READY 两路 | |
| 21 | 终结 | `POST :id/terminate` | 资产注销 + 终结原因 |

**DELIVERED 分流**（两路：租赁 / 客户报修）→ `change-stage` 支持 ✅
**W6 三向处置**（保内维修 / 保修外报价 / 直接处置）→ `change-stage` 支持 ✅

---

## 部分实现 🟡（3 节点）

### 01 SUPPLY_PO_CREATED — 占位 SN 批量预留缺失

| 实现项 | 状态 |
|---|---|
| Prisma schema：`RobotUnit.placeholderSnOrig` + `PurchaseOrderLine.placeholderPattern` | ✅ 已 migrate |
| `POST purchase-orders`（创建 PO + line）| ✅ 已实现 |
| `RobotUnitService.create()` 接受 `placeholderSnOrig` 参数 | ✅ 单条手动可传 |
| **创建 PO 后按 placeholderPattern 自动批量 createMany 占位 RobotUnit** | ❌ **缺** |
| `generateFfsn()` 生成正式 `FF-yyyymm-NNNNNN` | ✅ 但格式不是 `{PO#}-LINE-{NNN}` 占位 |
| **支持占位/正式两种 SN 格式** | ❌ **缺** |

**业务影响**：当前 PO 创建后业务方需**手工逐台创建 robot 记录**。v3 设计意图是"一次性批量预留 N 台占位"，看 PO 一台一台手工挂在那等于绕过流程图。

### 07 WAREHOUSE_RECEIVED — 占位 → 正式 SN 激活缺失

| 实现项 | 状态 |
|---|---|
| `change-stage` 推进到 RECEIVED | ✅ 状态机可走 |
| **扫供应商物理标签生成正式 FFSN** | ❌ **缺** |
| **占位 SN 替换为正式 SN，原值保留至 `placeholderSnOrig`** | ❌ **缺**（schema 有列、无逻辑） |
| **Supplier SN 由扫码填入** | 🟡 字段在 DTO 里有，无扫码触发的专门 API |

**业务影响**：v3 的"PO 阶段占位 → 收货激活"两段流程**两端都没通**——占位没批量创建，激活也没实现。占位 SN 机制是 v3 流程图核心创新（解决"Sherry 跟踪每台进度但 PO 时机器人个体不存在"的矛盾），目前完全没生效。

### 13 SALES_PAYMENT_VALIDATED — G5 硬阻塞校验

| 实现项 | 状态 |
|---|---|
| `change-stage` 推进到 PAYMENT_VALIDATED | ✅ |
| `Payment & Contract (PreDel)` 字段 | ✅ Master DTO 字段在 |
| **G5 硬阻塞校验**：未核验 = 拒绝推进到 READY_FOR_DELIVERY | 🟡 **需 verify**（lifecycle service 内部是否有 guard） |
| **全款 / 金融审批分流** | 🟡 **需 verify** |

**Action**：需要看 `lifecycleService.changeStage()` 实现细节，G5 应该是 hard gate，没核验阻断推进。

---

## 未实现 ❌（1 节点）

### QA AFTERSALES_QUOTE_APPROVAL — 保修外报价 service

| 实现项 | 状态 |
|---|---|
| `change-stage` 推进到 QUOTE_APPROVAL | ✅ 状态机可走 |
| `change-stage` 从 QUOTE_APPROVAL 推进到 UNDER_REPAIR / CLOSED（客户同意 / 拒绝）| ✅ |
| **保修外报价金额录入** | ❌ Master DTO 无 quote_amount 字段 |
| **客户审批回执** | ❌ 无专门 service |
| **建议**：复用 service-ticket activity 记录报价金额 + 审批结果 | — |

**业务影响**：从售后维修分流到保修外的流程**状态机能走但数据落不到表**。需要 schema 加 `service_ticket.quote_amount` + `quote_approved_by` 字段，或者复用现有 activities payload。

---

## 可合并 ➖（2 节点）

### FT WAREHOUSE_MODIFICATION 之前的 W3 功能测试

v3 流程图独立 FT 节点（位置=W3、功能测试报告），但 frontend RobotLifecycleStage enum 把 FT 和 09 改装合并成 `WAREHOUSE_MODIFICATION` 单 stage。

**实现状态**：合并合理（v3 表 FT 节点 0 主写字段，功能测试报告是非结构化文本）。如果业务方要把 FT 拆独立 stage：
- 加 enum `WAREHOUSE_FUNCTION_TEST`
- 状态机加 RECEIVED → AT_W1_PDI → AT_W1_PDI → **FUNCTION_TEST** → MODIFICATION → ...

### DV DELIVERY_VALIDATION 交付验证

类似情况，v3 流程图独立 DV 节点（序列号 / 客户 / 就绪 三件套核验），但 frontend 合并到 DELIVERY_APPROVAL。

**当前**：DA 阶段调 `PUT delivery-requests/:id` 校验通过即推进 → DELIVERED。如果业务方要独立 DV stage：拆 enum + 状态机。

---

## 总结 + 建议优先级

### P0（v3 流程图核心机制 — 当前完全没实现）
1. **占位 SN 批量预留 + 收货激活**（01 PO_CREATED → 07 RECEIVED 链路）
   - 工作量：~1 天（PO service 改 + 新激活 API + 状态机扩展 + L1 测试）
   - 这是 v3 流程图最大的"画了但没做"

### P1（业务可走但数据落不全）
2. **QA 保修外报价 service**（schema 加字段或复用 activity）
3. **G5 硬阻塞 verify**（确认 lifecycleService 是否有 guard，没有则补）

### P2（合并节点拆分 — 看业务需要）
4. FT W3 功能测试独立 stage（如果 W3 数据有结构化需求）
5. DV 交付验证独立 stage（如果三件套核验要单独审计）

### P3（无 backend gap，体验改进）
6. my-work 工作台：占位 SN 批量后可在 SUPPLY_PO_CREATED 卡片显示"PO-2026-001 · 50 台 (待收 30 / 已收 20)" PO-level dashboard

---

## 数据视角

当前 db 数据：30 台机器人分布在 15 个 stage（详见 my-work 工作台）。**全部是手工创建（FF-yyyymm-XXXXXX 正式 SN 格式）**，无占位 SN 真实数据。

修复 P0 后：业务方实际跑 PO 创建 → 自动生成 N 行占位 → 跟踪进度 → 收货扫码激活 → 完整流程通。