# robot-manager 模块

机器人全生命周期管理系统（Robot Lifecycle Management, RLE），以"单机维度"为核心，
建立每台机器人从采购到交付的全生命周期管理能力。

## 当前状态

| 阶段 | 状态 | 日期 |
|------|------|------|
| 需求文档（v6） | ✅ 完成 | 2026-04-18 |
| 数据模型（v6 - 10 状态 + FieldDef scope） | ✅ 完成 | 2026-04-18 |
| 后端开发（v6 角色重命名 + manage:* 拆分） | ✅ 完成 | 2026-04-18 |
| 前端开发（14 页 + 动态字段 + 模板下载） | ✅ 完成 | 2026-04-18 |
| L1 集成测试（109 用例） | ✅ 完成 | 2026-04-18 |
| L2 E2E 规格（19 场景） | ✅ 规格就绪 | 2026-04-18 |
| L3 人工验收规格 | ✅ 就绪（05-ui-interaction-spec） | 2026-04-18 |
| 全流程执行（L0→L3） | ⏳ 待跑 | - |

## 文档索引

| 文档 | 说明 | 何时读取 |
|------|------|----------|
| [01-prd.md](01-prd.md) | 产品需求文档：功能 F1-F8 + 业务约束 + v2 字段级权限矩阵 | 始终 |
| [04-state-machine.md](04-state-machine.md) | 10 状态生命周期（含 SOLD/REPAIRED）+ 合法转换 + 副作用 + 配置化 location 联动 | 涉及状态流转时 |
| [05-ui-interaction-spec.md](05-ui-interaction-spec.md) | UI 交互规范：页面清单、Tab 权限、OptionsEditor、错误码提示 | 涉及前端实现或 L3 验收时 |
| [06-data-model.md](06-data-model.md) | v2 数据模型：10 张表 / 业务实体 FK / 统一字典 / 系统配置 | 涉及数据结构时 |
| [07-api.md](07-api.md) | API 参考：核心 + 状态变更 + Section 级 + Admin + 报表 + Excel + Attachment + Search | 涉及前后端契约时 |
| [08-error-codes.md](08-error-codes.md) | 错误码清单：19 条 ROBOT_* 码 × HTTP 状态 × 触发点 × 前端文案 | 排查业务错误或 i18n 时 |
| [09-test-scenarios.md](09-test-scenarios.md) | 测试场景矩阵：业务流 × 角色 × 盲区映射（L1 + L2 索引） | 设计测试或查覆盖时 |
| [10-e2e-test-spec.md](10-e2e-test-spec.md) | E2E 测试规格：14 个场景 (P0×5 + P1×7 + P2×2) | 跑 L2 测试时 |
| [11-user-guide.md](11-user-guide.md) | 用户指南：Setup / Lifecycle / Daily Ops 三部分 | L3 人工验收时 |
| [12-roadmap.md](12-roadmap.md) | 路线图：AI / 效率 / 集成 三阶段 | 评估优先级时 |
| [13-import-mapping-prd.md](13-import-mapping-prd.md) | v5 → v3 字段映射 PRD（历史迁移用，DEPRECATED）| 仅 v5 迁移参考 |
| [14-import-export-tool-prd.md](14-import-export-tool-prd.md) | v3 数据导入工具 PRD（M1 PO importer 已上线，M2/M3 扩展）| 触碰 import / wizard / batch 时 |
| [15-seed-operations.md](15-seed-operations.md) | Master 测试数据 seed 运行手册（本地 / UAT / 清理 / 回灌）| 要在某环境放 / 重置 master 测试数据时 |
| [specs/placeholder-sn-mechanism.md](specs/placeholder-sn-mechanism.md) | 占位 SN 机制 tech spec（PO 占位 + activate-sn 激活）| 触碰 SN / PO publish 路径时 |
| [99-changelog.md](99-changelog.md) | 模块开发记录（含 v2/v3/v4/v5/v6 演进） | 复盘时 |

## 历史文档（不再更新）

以下文档来自早期"订单维度"设计阶段，**与 v2 不兼容**，仅作参考保留：

| 文档 | 说明 |
|------|------|
| [database-schema.md](database-schema.md) | 早期数据模型（订单维度） |
| [implementation-guide.md](implementation-guide.md) | Power Apps 实施方案 |
| [us-compliance.md](us-compliance.md) | 美国合规要求（Phase 2 及以后） |

## 核心概念

- **Unit Level**：每一行数据 = 一台机器人，一机一档
- **FFSN**：FF 内部序列号，按 `RobotSystemConfig.ffsn_rule` 自动生成，组织内唯一
- **Supplier SN**：供应商序列号，手动输入
- **生命周期**：Ordered → In Transit → Bonded/In Stock → Reserved → Delivered → Repair → Cancelled
- **业务实体**：Model / Sku / Supplier / Customer / Location 都是独立 FK 表
- **统一字典**：`RobotOption` 一张表管 10 类分类标签（业务自助维护）
- **Section 权限**：identity / supply-chain / sales / finance / after-sales 5 个 section，每个角色只能写自己 section

## 角色

| 角色 | code | 说明 |
|---|---|---|
| 系统管理员 | `Administrator` | 绕过所有权限检查 |
| 机器人生命周期管理员 | `RLE` | 持有所有 robot-manager section 写权限 + 字典/配置管理 |
| 供应链 | `SupplyChain` | 写 identity + supply-chain section，可创建/导入/导出/状态变更 |
| 销售 | `Sales` | 写 sales section，可状态变更/导出 |
| 财务 | `Finance` | 写 finance section，可导出 |

## 前端页面清单

### 业务页面（5）
- `/robot-manager` 设备列表（搜索/筛选/批量状态变更/导出）
- `/robot-manager/create` 新建设备
- `/robot-manager/[id]` 详情：**多角色 Tab 视图**（全部 / 设备身份 / 供应链 / 销售 / 财务 / 售后）
- `/robot-manager/reports` 报表（库存/销售/财务）
- `/robot-manager/import-export` Excel 导入导出

### 管理页面（7，需 `robot-manager:admin` 权限）
- `/robot-manager/admin/models` 型号管理
- `/robot-manager/admin/skus` SKU 管理（FK Model）
- `/robot-manager/admin/suppliers` 供应商档案
- `/robot-manager/admin/customers` 客户档案
- `/robot-manager/admin/locations` 位置档案（仓库/客户站点/...）
- `/robot-manager/admin/dictionary` 统一字典管理（10 category tab）
- `/robot-manager/admin/settings` 系统配置（FFSN 规则 + 状态默认 location 映射 + 维修自动 ServiceType）

## 后端代码位置

| 位置 | 路径 |
|------|------|
| 模块 | `backend/src/modules/robot-manager/` |
| Schema | `backend/prisma/schema/robot_manager.prisma` |
| 种子（v2） | `backend/prisma/seeds/robot-manager-e2e-seed.ts` |
| 集成测试 | `testing/backend/integration/robot-manager/`（v2 后未更新） |

## 前端代码位置

| 位置 | 路径 |
|------|------|
| 页面根 | `frontend/src/app/(modules)/robot-manager/` |
| API client | `frontend/src/app/(modules)/robot-manager/_lib/api/index.ts` |
| Admin 共享组件 | `frontend/src/app/(modules)/robot-manager/admin/_lib/EntityAdminPage.tsx` |