# ERR-20260520-004: Prisma 反向关系字段缺失，只在 `db push` / `generate` 才暴露，`tsc build` 全过

## 症状

议程 v1.0 PR 内 `backend npm run build` ✅ 0 error，39 个 L1 集成测试全过 ✅。
但在 slot-1 跑 `npx prisma db push` 时炸：

```
error: Error validating field `organization` in model `MeetingAttachment`:
The relation field `organization` on model `MeetingAttachment` is missing an
opposite relation field on the model `Organization`.
```

5 个新 model（MeetingAgendaSection / MeetingAgendaItem / MeetingAgendaItemUploadTask /
MeetingAgendaItemAttachment / MeetingAttachment）都给 Organization 加了 FK，
但 corp_hr.prisma 的 Organization model 一个反向字段都没补。

## 根因

`backend npm run build` 走的是 `nest build` / `tsc`，**只编译 TypeScript**：
- 用的是已经 `prisma generate` 出来的 client（PrismaClient 类型）
- 不会重新校验 schema 关系完整性

而 L1 集成测试用的是 **slot 之外的 test 数据库 + 之前生成的 client**，
也碰不到 schema 校验：
- 测试启动跑 `db push --force-reset --skip-generate` 时，可能用了**别人提前 generate
  好的 schema**（worktree 共享 client 文件夹）
- 实际跑的 test 用例只摸到 5 张新表，没用到 Organization → 议程的反向关联

→ schema 关系完整性的校验**只在 `prisma format` / `prisma generate` / `prisma db push` /
  `prisma migrate dev` 跑**，build + test 都漏。

## 修法

在 corp_hr.prisma `Organization` model 加 5 个反向字段：

```prisma
model Organization {
  // ... existing fields ...
  meetingAgendaSections        MeetingAgendaSection[]        @relation("AgendaSectionOrg")
  meetingAgendaItems           MeetingAgendaItem[]           @relation("AgendaItemOrg")
  meetingAgendaItemUploadTasks MeetingAgendaItemUploadTask[] @relation("UploadTaskOrg")
  meetingAgendaItemAttachments MeetingAgendaItemAttachment[] @relation("AgendaItemAttachmentOrg")
  meetingAttachments           MeetingAttachment[]           @relation("MeetingAttachmentOrg")
}
```

## 防御

写 prisma schema 新关系时：

1. **加 `@relation("XxxYyy", ...)` 时立刻在被引用 model 里补反向字段** —— 别等 db push
   报错才知道。
2. **commit / push 前跑一次 `npx prisma format` 或 `npx prisma generate`**：
   ```bash
   cd backend && npx prisma format && npx prisma generate
   ```
   `prisma format` 会原地补齐反向字段（虽然命名不一定理想，但至少 schema 合法）。
3. 跨模块加 FK 的 PR **强制 reviewer / pre-commit 跑 `prisma generate`** —— 这是
   schema 关系完整性的唯一可靠 gate。

**为什么测试也漏**：L1 集成测试用的是 **shared test DB + 共享 prisma client 文件夹**
（多 worktree 抢同一份 generate 产物），导致 schema 缺反向字段时**client 类型仍正常**
（因为是别人 generate 出来的）。所以 build + test 双绿不代表 schema 合法。

## 关联

- 工单：议程 v1.0 / 本次 PR（待开）
- 类似坑：无（之前所有 FK 都在同 schema 文件内，反向字段一起写）
- 修复 commit：跟本 learning 同 commit