# Platform Master — 模块 PRD

> **module**: platform-master
> **doc_type**: PRD
> **status**: Active (v3 PR2-4 实施后)
> **owner**: FFOA Team
> **last_verified**: 2026-05-17

## 1. 目标

提供**跨模块复用**的主数据 / 字典 / 通用对象底座，按 [standard 16](../../standards/16-data-layering-and-metadata-policy.md) 分层架构的 L1 层落地。让所有业务模块（robot-manager / 未来 sales / service / finance）共用同一份 Customer / Supplier / 字典等基础数据，避免重复表 / 重复 schema。

## 2. 范围

| 子层 | 内容 | 状态 |
|---|---|---|
| **L1a 主数据** | Customer + Contact + Address / Supplier + Contact / Partner + Contact / Location（含层级 + customerId 回引）| ✅ v3 完成 |
| **L1b 字典 / 参考数据** | Currency / Country / GeoRegion / UnitOfMeasure / Dictionary（5 个 category：label_type / tariff_type / declaration_type / service_issue_type / industry）| ✅ PR1 完成 |
| **L1c 通用业务对象** | Attachment（多态 ownerType/ownerId）| ✅ v3 完成 |

## 3. 用户故事

- 作为 **robot-manager 模块**，我能 FK 引用 platform-master 的 Customer / Supplier / Location 来描述机器人当前归属，不用在 robot-manager 自己建一套客户/供应商表
- 作为 **多模块共用业务**，我能拿同一份 currency 字典做金额本地化（USD / CNY / EUR 等）
- 作为 **业务方**，我能在管理台维护 Customer / Supplier 主数据，所有依赖模块同步可见
  - **权限边界**（v3 临时方案）：当前 CRUD 端点复用 `robot-manager:manage:{customers|suppliers|partners|locations}` 权限点（历史原因），实际语义跟 platform-master 不匹配。followup PR（见 issue #428 / 05-ui-interaction-spec.md §3）改为 `platform-master:manage:reference-data` + 单独 seed 权限点 + 角色挂权限。当前实施期 RLE / SupplyChain 等 robot-manager 写角色顺带拿到 platform-master 主数据写权限

## 4. 设计决策

| 决策 | 理由 |
|---|---|
| **每个主数据类型独立表**（不归 EAV）| 类型安全 + Prisma 强类型 + 专属字段（Customer.creditLimit / Supplier.leadTimeDays 等）|
| **Currency / Country 独立**（不入 Dictionary）| 有专属字段（decimals / iso3）值得独立 |
| **5 个无专属字段的字典 → 统一 Dictionary 表** | label_type / tariff_type / declaration_type / service_issue_type / industry 都是纯 code+label 结构 |
| **Attachment 多态 ownerType/ownerId** | 替代 v2 RobotAttachment，可挂在任意业务实体（robot_unit / sales_order / delivery_fulfillment / payment_record / rental_agreement / ...）|
| **跨 schema FK 用 @skip-data-scope 注释**：子表 / Attachment.ownerId 等非"owner 同义词"场景豁免 | 保留 organizationId 索引 + createdById 审计就够 |
| **字典全局可见（organizationId nullable）** | DataScope 按 ALL 处理 |

## 5. 跨模块契约

依赖 platform-master 的模块在 Prisma 层**不写 @relation**（避免类型推导污染），改在 service 层显式 join。DB 层仍建 FK constraint 保证引用完整性。

详见 [standard 16 §1.5](../../standards/16-data-layering-and-metadata-policy.md)。

## 6. 关联文档

- [06-data-model.md](./06-data-model.md) — 完整 ERD + 字段
- [07-api.md](./07-api.md) — REST API 契约
- [robot-manager 06-data-model](../robot-manager/06-data-model.md) — 主消费者参考