# [LRN-20260416-001] RobotUnit metadata 架构迁移经验

## 概述
将 RobotUnit 从 19 个强类型业务列迁移到 metadata JSONB 架构（骨架 + FieldDef + metadata）。

## 关键发现

### 1. 删列后所有引用该列的代码都会静默报 500
Prisma 不会在编译时告诉你哪些 service 还在引用已删除的列。`robot-status.service.ts` 的 `executeSideEffects` 写 `deliveredDate` 和 `salesOrderId`（已删除列）导致状态推进 500 错误。

**教训**：删列前用 `grep -r "columnName" backend/src/` 全局扫描所有引用，不能只改 service 和 DTO。

### 2. E2E seed 文件也会引用已删除列
`robot-manager-e2e-seed.ts` 中的 `robotUnit.create({ data: { poNumber, salesPrice, ... } })` 在删列后会报 `Unknown argument` 错误。

**教训**：删列的 checklist 应包括：schema → DTO → service → controller → 报表 → Excel → 状态机 → **seed 文件** → 前端类型。

### 3. FieldDef 的 group 归属必须和测试一致
测试中 `paymentMethodCode` 放到 finance group 的 FieldDef seed 中，但真实种子定义它在 sales group。section update 的白名单从 FieldDef 动态生成，group 不匹配导致字段被静默丢弃，API 返回 200 但数据没变。

**教训**：测试 FieldDef 种子必须和真实种子的 group 归属保持一致。

### 4. 测试数据库 schema 重建后种子不会自动跑
`run-backend-integration.sh --force-reset` 重建 schema 但不跑种子（`seed.ts` 需要单独执行）。集成测试的 `seedV2Fixtures` 只创建测试需要的最小数据，不依赖全局种子。

### 5. validateMetadata 在 FieldDef 表不存在时会 500
测试数据库如果没有 `robot_field_defs` 表（旧 schema），`validateMetadata` 查询会抛 PrismaClientKnownRequestError。首次跑测试需要 `--force-reset` 重建 schema。

## 适用范围
任何模块从强类型列迁移到 JSONB 动态字段的场景。