# Robot Manager — 业务分析与需求溯源

> **module**: robot-manager
> **doc_type**: BusinessAnalysis（非标准模块文档，业务上下文沉淀）
> **status**: Active
> **created**: 2026-05-15
> **upstream**: 业务方提供的 5 个源文件（在 `MyBrain/机器人管理/`，未入仓）

## 这是什么

这个目录沉淀了基于业务方提供的 5 个事实源文件（Master_Metadata_v3 / eai_lifecycle_unified / robot_lifecycle_unified_v2 / EAI WBS / ffai_roadmap_gantt_2），由 chentao + Claude 在 2026-05-15 做的**业务需求梳理 + 实现差距分析**。

跟 `01-prd.md` / `06-data-model.md` 等标准模块文档的关系：

- **标准文档**（同目录的 `01-*` 到 `99-*`）：当前 v3 已实现的契约（PRD / 数据模型 / API / 状态机 / UI 规格 / 测试方案）
- **本目录**（business-analysis）：**业务需求的完整事实源 + 现状差距分析**，是补齐模块未来迭代的素材库

## 文件索引

### 第一轮：需求梳理（2026-05-15）

| 文件 | 用途 | 何时读取 |
|---|---|---|
| [需求分析.md](需求分析.md) | **主分析文档**：五根支柱（数据完整性 / 流程完整性 / 权责清晰性 / 可观测性 / 状态一致性）梳理；13 数据表 / 10 阶段 / 6 控制门 / 6 仓库 / 21 stage 状态字典 / 8 业务报告 | 任何时候要追溯"业务需求原始定义"先看这个 |
| [需求流程图.html](需求流程图.html) | 端到端流程图可视化（25 节点 + 80+ 字段 + 处理人 + 数据表）| 给非技术人员看流程的时候 |
| [覆盖率报告.html](覆盖率报告.html) | **按源文件**覆盖率（5 个源文件逐一对比）| 评估"我们梳理的需求是否完整对齐源文件" |
| [覆盖率报告-按维度.html](覆盖率报告-按维度.html) | **按维度**覆盖率（节点 / 字段 / 责任人 / 控制门 / 枚举 / 仓库 / stage / 数据表 / 报告 9 维度）| 同上，换个切面看 |
| [合理性分析.html](合理性分析.html) | **批判性 review**：流程结构 / 字段建模 / 责任归属 三角度合理性评分（7.0/10）+ 15 个优化项按 P0-P3 排优先级 | 重大重构 / 设计 review 前看 |
| [实现差距报告.html](实现差距报告.html) | **当前 robot-manager v3 实现 vs 需求**的差距分析：状态机 10→21 / 字段 31→50 / Guard 4→10 等，估总工作量 6-8 周 | 排迭代任务、做 roadmap 时看 |

### 第二轮：业务方迭代（2026-05-16）— v3 / v5

| 文件 | 用途 | 何时读取 |
|---|---|---|
| [汇总-v3-v5-业务方迭代.md](汇总-v3-v5-业务方迭代.md) | **本轮迭代汇总** — 必读 | 看本轮变化和影响 |
| [Master_Metadata_v5.xlsx](Master_Metadata_v5.xlsx) | 主数据本体 v5（172 行 / 82 列） | 查具体记录 / 字段定义 / Enum 字典 |
| [Master_to_Node_Mapping_v3.xlsx](Master_to_Node_Mapping_v3.xlsx) | **字段 ↔ 节点映射矩阵 v3** | 字段 owner 设计 / 数据建模时的事实源 |
| [Requirement_Workflow_with_Master_mapping_v3.html](Requirement_Workflow_with_Master_mapping_v3.html) | 流程图 + 字段映射可视化 v3 | 看节点 N 字段徽章 / ★ 主写 / ○ 只读 / 占位 SN 激活机制 |

## 跟标准模块文档的关系

```
business-analysis/                  ← 本目录（业务上下文、需求事实源）
  ├── 需求分析.md                       (业务侧"应有"全景)
  ├── 需求流程图.html                  (可视化)
  ├── 覆盖率报告.html × 2              (源文件对齐度)
  ├── 合理性分析.html                  (产品/数据层批判)
  └── 实现差距报告.html                (跟当前实现的 gap)
        │
        │  ←──── 业务需求侧
        │
        ▼  ←──── 系统实现侧（gap 由此跨越）
        │
01-prd.md / 04-state-machine.md / 06-data-model.md / 07-api.md / ...   ← 当前实现的契约
```

## 当前实现状态（截至 2026-05-16）

| 维度 | 现状 | 目标（需求侧 v3/v5） | Gap |
|---|---|---|---|
| 状态机 | 10 个 RobotStatus | 21 个 stage | 11 个待加 |
| 动态字段 | 31 个 RobotFieldDef | ~50 个（v5 Master 82 列去重） | 20 个待加（**纯配置不改代码**） |
| Guard | 4 个 | 10 个（G1-G6 + 验证门） | 6 个待加 |
| **占位 SN 机制** | ❌ 没有 | `Placeholder SN (orig)` + PO 阶段占位 → 07 RECEIVED 扫码激活 | 🆕 v3 新增需求 |
| **字段 ★/○ owner** | ❌ 没有 | 82 字段精确到主写节点 + 只读引用节点 | 🆕 v3 mapping 提供事实源 |
| 业务实体表 | 5 张（Model/Sku/Supplier/Customer/Location） | 同 | ✅ |
| 子表 | RobotServiceRecord / Attachment / StatusChangeLog | + Payment / SalesOrder / DeliveryRequest | 3 个可选 |
| 报表 | 3 张（库存/销售/财务）| 8 张 | 5 张待加 |

详情见 [实现差距报告.html](实现差距报告.html) + [汇总-v3-v5-业务方迭代.md](汇总-v3-v5-业务方迭代.md)。

## 原始源文件位置

业务方提供的 5 个原始源文件未入仓（XLSX 二进制 + 较大），存放在开发机：

```
/home/chentao/Code/MyBrain/机器人管理/
  ├── Master_Metadata_v3.xlsx                                 ← 117 SN / 81 列主档 / 17 Enum / 4 上游源
  ├── eai_lifecycle_unified.html                              ← 端到端流程主图
  ├── robot_lifecycle_unified_v2.html                        ← 三泳道生命周期
  ├── EAI Robotics End to End Planning and Operation.xlsx    ← WBS 项目管理
  └── ffai_roadmap_gantt_2.html                                ← FFAI 开发路线图（不在本模块范围）
```

如需访问 / 更新，去 MyBrain 目录拉最新版本。

## 在线访问（开发机）

本目录的 HTML 同时在开发机 Caddy 域名下挂着，方便团队浏览：

- 流程图：https://slot-3.chentao.test.jiachentao.com/
- 覆盖率（按文件）：.../report.html
- 覆盖率（按维度）：.../report-by-dimension.html
- 合理性分析：.../review.html
- 实现差距：.../gap.html

（注：slot-3 域名是开发机临时挂载，正式环境需另起静态服务）