# 数据模型文档审查经验

> **日期**: 2026-04-12
> **场景**: robot-business 模块需求文档设计与多轮审查
> **价值**: 高（可复用于任何新模块的数据模型设计）

## 经验 1: 软删除 + 唯一约束需要 partial unique index

Prisma `@@unique([organizationId, ffsn])` 包含已软删除记录，导致软删除后无法复用同名标识。

**解法**: 通过 migration SQL 创建 partial unique index：
```sql
CREATE UNIQUE INDEX robot_units_org_ffsn_unique
ON robot_units (organization_id, ffsn) WHERE deleted_at IS NULL;
```

## 经验 2: 动态业务数据不应用 Prisma Enum

供应商、型号等会频繁新增的数据如果用 Prisma enum，每次新增都需要 schema 迁移 + 重部署。

**解法**: 用 String 类型，前端下拉选项由配置维护。只有业务语义固定的状态（如 CurrentStatus、PaymentStatus）才用 enum。

## 经验 3: 存储型计算字段有同步风险

`grossMargin = salesPrice - cost` 如果存在表中，任何一方变更时必须触发重算，遗漏就数据不一致。

**解法**: V1 数据量小时优先查询时计算（服务层或 SQL view），避免同步问题。

## 经验 4: Guard Condition 与副作用严格区分

状态机设计时容易把"变更后执行的动作"（副作用）错写成"变更前必须满足的条件"（Guard Condition）。

**判断标准**: Guard = 变更前已经为真的条件；副作用 = 变更后系统自动执行的动作。

## 经验 5: PDF 提取工具链

本环境无 poppler-utils 且无 sudo 权限：
- 文本提取: `npx pdf2json -f <file> -o <dir> -c` → 生成 `.content.txt`
- 图片提取: `npx pdf-to-img -s 2 -o <dir> <file>` → 每页一张 PNG（注意输出到 CWD 而非指定目录）

## 经验 6: 多轮审查维度清单

有效的审查需要切换视角，每轮只聚焦一个维度：
1. 文档结构与完整性
2. Schema 七维审查（数据类型/约束/索引/关系/多租户/迁移安全/范式）
3. 跨文档一致性（同一概念在多处的定义是否一致）
4. 实现者视角（拿着文档能否无歧义写代码）
5. 端到端场景走查（模拟完整业务流程）
6. 数据完整性与并发（极端情况下数据会不会坏）
7. Guard 一致性与边界路径（转换表 vs Guard vs 副作用 三者是否自洽）