6–8
人周（一人开发）
改动不大 · ROI 高
好消息：robot-manager 模块已经是 v3 现代化架构（骨架 + JSONB metadata + 动态字段定义 + 统一字典表 + 业务实体 FK），核心架构无需重做。
这意味着我们梳理的需求里 ~80% 的字段补齐可以纯配置完成（加 RobotFieldDef 行 + 默认数据），不用改代码。真正需要写代码的是：
- RobotStatus enum 从 10 个扩到 21+ 个状态
- 5 个新 Guard（G1-G6 业务校验）
- 2-3 个新子表（Payment / SalesOrder / DeliveryRequest，可选）
整体工作量：P0 (2-3 周) + P1 (3-4 周) 即可达到需求覆盖 95%+。
现状
已经实现的（不用改）
v3 架构 · 设计先进
workspace 仓库 robot-manager 模块当前已经覆盖了需求的大部分基础架构。这是个 v3 重构后的现代化设计。
| 现有能力 | 覆盖需求 | 说明 |
|---|
RobotUnit 一机一档（骨架+JSONB） |
✅ |
对应需求"机器人主档"，且解决了"81 列宽表"问题 |
| 5 张业务实体表（Model/Sku/Supplier/Customer/Location） |
✅ |
跟需求 §1 「业务实体表 5 张」对齐 |
RobotFieldDef 动态字段定义（31 个字段 / 6 group） |
✅ |
架构对了，字段数还不够，加配置即可 |
RobotOption 统一字典（10 category） |
✅ |
对应需求 §1 OptionDict |
RobotStatusChangeLog 状态变更日志 |
✅ |
支持完整审计 |
RobotAttachment 附件表（合同/发票/图片） |
✅ |
文档链接 6 字段、配件 BOM 都可走此表，不需要新建 |
RobotServiceRecord 服务记录 |
✅ |
对应需求 AfterSalesTicket（部分） |
| 审计字段齐全（createdAt / updatedAt / createdBy / updatedBy / deletedAt / version） |
✅ |
已有乐观锁 + 软删除 |
| RobotSystemConfig（FFSN 规则 / 状态-Location 映射） |
✅ |
对应需求 SystemConfig |
| 状态机 transition 表 + Guard（部分） |
部分 |
有 4 个 Guard，但 G1-G6 还没全做 |
| 权限：robot-manager:* 全局权限 |
部分 |
有全局权限，缺 Section 级细化 |
| Excel 导入导出 + 字段映射 |
✅ |
需要更新映射表加新字段 |
P0 必做
① 状态机扩展（10 → 21+ 状态）
M 3-5 天
现状 enum 缺 11 个状态，主要是供应链上半段（工厂在制 → 清关 → 收货 → 改装）+ 售后分支细化。
| 需求状态 | 现状 | 说明 |
|---|
| PO_CREATED | ✓ | 对应 ORDERED |
| IN_PRODUCTION | 缺 | 工厂在制 |
| READY_TO_SHIP | 缺 | 工厂可发运 |
| IN_TRANSIT | ✓ | |
| BONDED | ✓ | |
| CUSTOMS_CLEARED | 缺 | 清关完成（现合并在 BONDED→IN_STOCK 转换中） |
| RECEIVED / AT_W1_PDI | 合并 | 现合在 IN_STOCK，可考虑拆开 |
| UNDER_MODIFICATION | 缺 | 本地化改装中 |
| CONVERSION_VALIDATED | 缺 | 改装已验证 |
| BRANDED_READY | 缺 | W4 可售（现在用 IN_STOCK 表达） |
| RESERVED | ✓ | |
| PAYMENT_VALIDATED | 缺 | 对应 SOLD 但语义更明确（G5 后） |
| READY_FOR_DELIVERY | 缺 | 准备交付 |
| DELIVERED | ✓ | |
| AT_W2_RLE | 缺 | 外采库分支 |
| ON_RENTAL | 缺 | 租赁分支 |
| UNDER_REPAIR | ✓ | 对应 REPAIR |
| REPAIRED | ✓ | |
| RETURN_INITIATED / RECEIVED | 缺 | RMA 拆 2 步 |
| CLOSED (SCRAPPED / SWAPPED / CANCELLED) | 合并 | 现只有 CANCELLED，缺 SCRAPPED / SWAPPED 子类型 |
改动文件
backend/prisma/schema/robot_manager.prisma（RobotStatus enum）+
backend/src/modules/robot-manager/services/robot-status.service.ts（VALID_TRANSITIONS + 副作用）+
数据迁移脚本（现有 SOLD/IN_STOCK 拆分映射）
P0 必做
② 字段补齐（31 → ~50 个动态字段）
S 2-3 天 · 纯配置
现状 31 个 RobotFieldDef → 需要补 ~20 个。这是配置数据补齐，不需要改代码。在管理台界面加字段即可，或写一个 seed 脚本。
| Group | 现有 | 需补 | 缺什么 |
|---|
| identity（身份） |
5 |
+2 |
health（健康度横切）/ track（分流路径） |
| supply-chain |
6 |
+3 |
variant 型号变体 / paintingColor 喷漆 / factoryQcStatus 工厂 QC |
| sales |
10 |
+4 |
signedFormStatus / acceptanceFormStatus / deliveryNumber / mentor |
| finance |
3 |
+3 |
salesPriceHardware / salesPriceSoftware（如果不已存在）/ paymentStatus |
| compliance |
4 |
+2 |
htsCode / customsDoc |
| after-sales |
3 |
+3 |
returnStatus / disposition / repairType |
| 横切（备注类） |
0 |
+3 |
issue / generalNotes / complianceNotes（catch-all 系列） |
✨ 配置即字段
v3 架构的好处：加 20 个业务字段 = 在 RobotFieldDef 表插 20 行配置 + 给 select 类型的字段在 RobotOption 字典加 category。不需要改 Prisma schema，不需要改 controller/service 代码，不需要数据库迁移。可以由业务人员在管理台界面添加。
P0 必做
③ 控制门 Guard 补全（4 → 10 个 Guard）
M 2-3 天
现状 status service 已有 4 个 Guard，但 G1-G6 业务校验大部分还没实现。
| Gate | 转换 | 现状 | 需补 |
|---|
| G1 | → READY_TO_SHIP | 无 | 预测锁定校验 |
| G2 | READY_TO_SHIP → IN_TRANSIT | 无 | 出厂 QC 完成 |
| G3 | BONDED → CUSTOMS_CLEARED | 无 | 清关凭证 |
| G4 | IN_STOCK → RESERVED | customerId 必填 | contractStatus = 'Signed' |
| 🔴 G5 | RESERVED → PAYMENT_VALIDATED | salesPrice 必填 | payment.status = 'Paid' OR financingApproval = true（硬阻塞） |
| G6 | READY_FOR_DELIVERY → DELIVERED | 无 | acceptanceForm.status = 'Complete' |
| ◆ Conversion | UNDER_MODIFICATION → CONVERSION_VALIDATED | 无 | 验证证据上传 |
| ◆ Return Inspection | RETURN_RECEIVED → UNDER_REPAIR | 无 | 检查报告 + 处置判定 |
改动文件
backend/src/modules/robot-manager/services/robot-status.service.ts 的 validateGuardConditions() 增 6 个 Guard 检查。配套错误码在 errors/robot-manager.errors.ts 加。
P1 重要
④ 新建 3 个独立子表（Payment / SalesOrder / DeliveryRequest）
L 1-2 周
需求 §1 把这 3 个定义为独立业务表，现状全塞在 RobotUnit.metadata JSONB 里。短期能用，但限制了"一台机器人多次交付/多笔付款"的场景。
| 表 | 现状 | 建议 |
|---|
RobotPayment |
字段在 metadata（payment_method / payment_status / amount） |
独立表，1 robot : N payment（支持订金 + 尾款） |
RobotSalesOrder |
字段在 metadata（salesOrderId / contractStatus / mentor / mentee） |
独立表，1 robot : 1 active order（保留历史订单） |
RobotDeliveryRequest |
字段在 metadata（requestType / deliveryStatus / acceptanceForm） |
独立表，1 robot : N delivery（首次交付 + 售后再交付） |
是否真要做？
取决于业务规模 — 117 台机器人当前每台一笔订单/付款/交付，metadata 扁平方案短期足够。
但如果接下来要支持租赁回流、售后再售、多笔分期，必须拆。建议至少先建 RobotPayment（订金+尾款是普遍场景）。
P1 重要
⑤ 字段 Owner 制度（Section 级权限细化）
M 3-5 天
需求 §3 + 合理性分析里指出 82 个字段冲突的根因是"没有字段 owner"。现状 robot-manager 只有全局权限 robot-manager:*，缺 Section 级。
| 改动 | 说明 |
|---|
RobotFieldDef 加 ownerSection 列 |
Supply-Chain / Warehouse / Sales / Finance / After-Sales / Governance |
| 权限校验：update 时校验用户 section 与 field.ownerSection 匹配 |
在 RobotUnitService.update() 加 |
| VALID_TRANSITIONS 的 roles 字段升级为代码强制 |
当前是文档意图，未代码强制（04-state-machine.md 注释提到） |
stage / currentStatus 升级为"系统只读" |
只能通过状态机 transition API 改，不能通过 metadata edit API 直接覆盖 |
P1 重要
⑥ 业务报表补全（3 → 8 张）
M 1 周
现状 PRD V1 已实现 3 张（库存 / 销售 / 财务），需求 §4 共 8 张。
| 报表 | 现状 |
|---|
| R1 库存周转报告 | 已实现 |
| R2 在途与清关报告 | 缺 |
| R3 销售管道报告 | 已实现 |
| R4 交付进度报告 | 缺 |
| R5 收款状态报告 | 缺 |
| R6 收入确认与毛利 | 已实现 |
| R7 售后回流分析 | 缺 |
| R8 数据健康度报告 | 缺 |
P2 缓做
⑦ 其他小项
S 共 1-2 天
| 项 | 工作量 | 说明 |
|---|
| 仓库 W1-W6 seed 初始化 + status→location 映射 | S 1d | 配置层 |
| Excel 模板更新（新字段 + 新状态） | S 1d | 配套 ① + ② |
| Field 命名规范统一 | S 1d | 批量改 RobotFieldDef |
| "系统自动 vs 人为触发"在 status change 区分 | S 1d | 加标识字段 |
✨ 不在范围（业务自然消失）
- 多源数据治理（4 个上游源 + 82 字段冲突 + DataConflictLog）：一旦数据统一进 FFOA 单一系统，"多源"问题自然消失，不需要做 LSync。
- WBS 项目管理 / 客户管道 GTM：不在 robot-manager 模块职责内，是独立模块。
汇总
工作量与时间线
| 优先级 | 项 | 工作量 | 天数 |
|---|
| P0 | ① 状态机 10→21 | M | 3-5d |
| P0 | ② 字段补齐 31→50（配置） | S | 2-3d |
| P0 | ③ Guard 4→10 | M | 2-3d |
| P0 小计 | | ~2 周 |
| P1 | ④ 3 个新子表（Payment/SO/Delivery） | L | 1-2w |
| P1 | ⑤ 字段 Owner / Section 权限 | M | 3-5d |
| P1 | ⑥ 报表 3→8 | M | 1w |
| P1 小计 | | ~3-4 周 |
| P2 | ⑦ 其他小项 | S × 4 | 4-5d |
| 总计 | 一人开发，串行 | 6-8 周 |
📌 推荐节奏
第 1 阶段（2 周 · P0）：状态机扩展 + 字段配置补齐 + Guard 补全。这一阶段完成后，流程图就可以在系统里"跑起来"，每台机器人能完整走 21 个状态。
第 2 阶段（3-4 周 · P1）：拆子表 + 字段 Owner + 报表。这一阶段让系统具备"长期可维护性"和"业务可观测性"。
第 3 阶段（1 周 · P2）：配置层完善 + 体验优化。