# platform-master 模块

平台公共主数据层（L1） — 项目级 standard 16 数据分层架构的最底层：跨模块复用的主数据、字典、参考数据。

## 当前状态（v3 已上线）

| 阶段 | 状态 | 日期 |
|---|---|---|
| L1b 字典 / 参考数据 schema | ✅ 完成（PR1） | 2026-05-16 |
| L1b NestJS module + 10 GET API | ✅ 完成（PR1） | 2026-05-16 |
| L1b L1 集成测试 | ✅ 完成（PR1） | 2026-05-16 |
| L1a 主数据 schema + CRUD API + Restore | ✅ 完成（v3 PR2-4） | 2026-05-17 |
| L1c 多态 Attachment | ✅ 完成（v3 PR2-4） | 2026-05-17 |
| Frontend 6 page UI | ✅ 完成（v3 PR2-4） | 2026-05-18 |
| 完整模块文档（01-prd / 05-ui-spec / 06-data-model / 07-api） | ✅ 完成（v3 PR2-4） | 2026-05-18 |

## 范围

| 子层 | 内容 | 状态 |
|---|---|---|
| **L1a 主数据** | Customer / Supplier / Partner / Location（含 contacts / addresses 子表）| ✅ v3 |
| **L1b 字典 / 参考数据** | Currency / Country / GeoRegion / UnitOfMeasure / Dictionary（含 label_type / tariff_type / declaration_type / service_issue_type / industry 5 个 category）| ✅ v3（含 Currency 写端点） |
| **L1c 通用业务对象** | Attachment（多态附件，owner_type/id）| ✅ v3 |

## 路由文档

- [01-prd.md](01-prd.md) — PRD（v3 实施后定稿）
- [05-ui-interaction-spec.md](05-ui-interaction-spec.md) — 6 page UI 交互规范
- [06-data-model.md](06-data-model.md) — 数据模型 + 跨 schema FK 策略
- [07-api.md](07-api.md) — 完整 API 参考（v3）

## API（v3 完整）

详见 [07-api.md](07-api.md)。摘要：

| 类别 | endpoint | 方法 |
|---|---|---|
| **L1a CRUD** | `/customers` `/suppliers` `/partners` `/locations` | GET / POST / PUT / DELETE / `:id/restore` |
| **L1b 字典写** | `/currencies` | GET + POST / PUT / DELETE / enable（admin） |
| **L1b 参考只读** | `/countries` `/geo-regions` `/units-of-measure` `/dictionaries` | GET（含 query 过滤）|
| **L1c 附件** | `/attachments` | 多态 owner_type/owner_id |

## 关键设计决策（事实源在 standard 16 + robot-manager/business-analysis/）

- **跨 schema FK 策略**：DB 层建 FK constraint + Prisma 层不写 `@relation` + Service 层显式批量 join（避免 N+1）。详见 [standard 16](../../standards/16-data-layering-and-metadata-policy.md)。
- **字典 vs 独立表判据**（standard 16 §5.1）：有专属字段或被强类型 FK 频繁引用 → 独立表（Currency / Country / GeoRegion / UnitOfMeasure）；无专属字段、纯枚举、被 FK 引用次数少 → 入 `Dictionary(category, code, label)`（LabelType / TariffType / DeclarationType 等）。
- **标准字段**（standard 04）：所有字典表都含 `id / organizationId nullable / createdById nullable / createdAt / updatedAt`。organizationId nullable 表全局共享（DataScope 按 ALL 处理）。
- **命名冲突规避**：`GeoRegion`（避开 `corp_hr.Region`）/ `QualityLabelStatus`（避开 `mfg_inventory.LabelStatus`）/ `DeliveryFormStatus`（避开 `platform_form.FormStatus`）。

## 关联文档

- [standard 16 数据分层与元数据策略](../../standards/16-data-layering-and-metadata-policy.md)
- [robot-manager/business-analysis/数据分层方案.md](../robot-manager/business-analysis/数据分层方案.md) — 22 表分层归位
- [robot-manager/business-analysis/最终字段设计.md](../robot-manager/business-analysis/最终字段设计.md) — v5 82 字段精确归位 + enum 清单
- [robot-manager/business-analysis/重构方案.md](../robot-manager/business-analysis/重构方案.md) — PR1-PR5 落地方案

## 代码位置

| 位置 | 路径 |
|---|---|
| Module | `backend/src/modules/platform-master/` |
| Schema | `backend/prisma/schema/platform_master.prisma` |
| Seed | `backend/prisma/seeds/platform-master-seed.ts` |
| L1 测试 | `testing/backend/integration/platform-master/` |