# 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 列 / 18 enum sheet） | 查具体记录 / 字段定义 / Enum 字典 |
| [Master_to_Node_Mapping_v3.xlsx](Master_to_Node_Mapping_v3.xlsx) | **字段 ↔ 节点映射矩阵 v3**（5 sheet） | 字段 owner 设计 / 数据建模时的事实源 |
| [Requirement_Workflow_with_Master_mapping_v3.html](Requirement_Workflow_with_Master_mapping_v3.html) | 流程图 + 字段映射可视化 v3 | 看节点 N 字段徽章 / ★ 主写 / ○ 只读 / 占位 SN 激活机制 |

### 第三轮：数据分层 + 字段设计 + 重构方案（2026-05-16）

基于 standard 16 三层架构的完整模块设计：

| 文件 | 用途 | 何时读取 |
|---|---|---|
| [数据分层方案.md](数据分层方案.md) | **22 表分层归位** — L1 平台公共 / L2 模块主数据 / L3 业务表；含 SAP/D365 集成 anchor / 跨 schema FK 策略 / 不立 L4 + 不 SaaS 化承诺 | 任何模块表设计前先看 |
| [数据分层方案.html](数据分层方案.html) | 同上 HTML 可视化（fetch md 单一来源） | 浏览器看 |
| [最终字段设计.md](最终字段设计.md) | **v5 82 字段精确归位** + 29 stage（含部门前缀）+ 13 Guard + STAGE_TRANSITIONS + 事件投影表 + 完整 enum 清单 | prisma schema 实施前的事实源 |
| [最终字段设计.html](最终字段设计.html) | 同上 HTML | 浏览器看 |
| [重构方案.md](重构方案.md) | **PR1-PR5 详尽落地方案**（含 prisma migration SQL / Service / 前端 / 测试 / 风险与回退 / 验收点 / multi-agent review 修订记录） | 开 PR 实施时 |
| [重构方案.html](重构方案.html) | 同上 HTML | 浏览器看 |

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

```
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)。

## 原始源文件位置

**已入仓**（仓库内可直接查看 / `.gitignore` 例外允许 business-analysis 下 xlsx）：
- [`Master_Metadata_v5.xlsx`](Master_Metadata_v5.xlsx) — v5 主档（172 SN / 82 列 / 18 enum sheet）**核心事实源**
- [`Master_to_Node_Mapping_v3.xlsx`](Master_to_Node_Mapping_v3.xlsx) — 字段-节点映射 v3（5 sheet）
- [`Requirement_Workflow_with_Master_mapping_v3.html`](Requirement_Workflow_with_Master_mapping_v3.html) — 流程图 v3

**仍在开发机 MyBrain**（历史溯源用，已被 v5 取代）：
```
/home/chentao/Code/MyBrain/机器人管理/
  ├── Master_Metadata_v3.xlsx                                 ← v3 老主档（117 SN）已被 v5 取代
  ├── eai_lifecycle_unified.html                              ← v1 端到端流程主图（已被 v3 mapping html 取代）
  ├── robot_lifecycle_unified_v2.html                         ← v1 三泳道生命周期
  ├── EAI Robotics End to End Planning and Operation.xlsx     ← WBS 项目管理（不影响 schema）
  └── ffai_roadmap_gantt_2.html                                ← FFAI 开发路线图（不在本模块范围）
```

历史文件如需访问，去 MyBrain 目录拉。本目录已入仓的 3 个文件即可覆盖**核心设计需求**。

## 在线浏览

本目录所有 markdown 和 HTML 文件可直接通过 Gitea repo browser 查看。开发机 / slot 内可用 Caddy 反代 `python3 -m http.server` 临时挂载浏览（不入仓，参考 `.agents/skills` 内 slot 操作约定）。

## 外部依赖

本目录文档（特别是 `数据分层方案.md` / `最终字段设计.md` / `重构方案.md`）引用 [`docs/standards/16-data-layering-and-metadata-policy.md`](../../../standards/16-data-layering-and-metadata-policy.md)（PR #398 已合 develop，链接生效）。