# 产物一致性（Parity）指南

> **触发条件**：任何声称"纯重构、产物不变"的改动。
>
> 这条管线的产物是 `.blend` / `.glb` / `.png`——**二进制、无法 code review、
> 肉眼看不出 5% 的几何漂移**。parity 校验是这一层唯一的回归防线。

---

## 为什么不能直接比字节

三类文件全都**不是位级可复现**的，同一份代码跑两次就会不一样：

| 产物 | 为什么不稳定 |
|---|---|
| `.blend` | 内嵌绝对路径；图片按哈希表顺序打包 |
| `.png` | EEVEE 渲染非位级可复现 |
| `.glb` | glTF 导出器会去重相同的 accessor，而 `smart_project` 的 UV 带浮点噪声——实测两次跑出 399 vs 398 个 accessor、差 720 字节，而 node/mesh/primitive/material/image **完全一致** |

所以比对的是**结构摘要**，不是字节。

---

## 三件套

| 工具 | 位置 | 作用 |
|---|---|---|
| 场景摘要 | `blender/tools/scene_digest.py` | 在 Blender 内打开 `.blend`，输出稳定 JSON：对象名/顶点数/面数/材质槽/自定义属性、材质参数、场景属性 |
| GLB 摘要 | `scripts/glb-digest.js` | 纯 Node 读 GLB 的 JSON chunk，输出 node/mesh/material 清单与 PBR 参数，附 buffer 字节长度 |
| 驱动 | `scripts/parity.js` | 跑构建 → 采集摘要 → 快照 / 比对 |

```bash
node scripts/parity.js capture <label> [--areas a,b] [--stages blender,cesium]
node scripts/parity.js compare <labelA> <labelB>
```

基线落在 `outputs/_refactor-baseline/<label>/`，在 `.gitignore` 里——
**本地草稿，不是产物，不入库**（`parity.js:16-17`）。

默认样本区域两个（`parity.js:26`）：`nantaizi-lake-innovation-valley`（主，
OSM + osm2streets GeoJSON 齐全）、`hanyang-block`（次）。

---

## 必须先做 control 实验

**这是最容易被跳过、跳过之后整个校验就是假的一步。**

用**未改动**的代码连跑两次，diff 两份摘要。这一步确定哪些字段天然不确定，
把它们列入忽略名单。

```bash
node scripts/parity.js capture control-1
node scripts/parity.js capture control-2
node scripts/parity.js compare control-1 control-2   # 必须全绿
```

没做这步就开始改代码，你会分不清一个差异是"重构引入的 bug"还是"本来就每次都不一样"。

已完成的 control 结论（`docs/refactor-plan.md`）：

- `.blend` **结构摘要两次完全一致** ← 这是主校验信号，可信
- `.blend` 文件 sha256 不一致
- 渲染 PNG sha256 不一致
- GLB 结构（node / mesh / primitive / material / image）两次完全一致，
  但 accessor 数 399 vs 398、buffer 差 720 字节

---

## 忽略名单：必须附理由

`parity.js:25-54` 的 `IGNORED_PATHS`，每一条上面都写着为什么被忽略：

```
files.blend.sha256 / files.glb.{sha256,bytes} / files.render.{sha256,bytes}
glbDigest.fileBytes / glbDigest.buffers / glbDigest.counts.accessors
capturedAt / durationMs / label
```

这些字段**仍然被记录**——人读快照时想看到它们——只是不参与比对
（`parity.js:25-27`）。

> **往忽略名单里加东西是有代价的动作。**
> 加之前先确认这个字段是**真的**每次都变（用 control 实验证明），
> 而不是你的改动让它变了。注释里必须写清楚证据。

---

## 真正的契约

忽略名单之外剩下的就是契约，**改动它们 = 改动产物**：

| 契约项 | 谁产生 |
|---|---|
| `SCENE_DONE` stdout 标记及其 JSON 内容 | `generate_scene.py` |
| `CESIUM_EXPORT_DONE` stdout 标记及其 JSON 内容 | `export_cesium.py` |
| `.blend` 全量结构摘要（对象、网格、材质、自定义属性） | `scene_digest.py` |
| GLB 的 node / mesh / material / image 结构 | `glb-digest.js` |
| `<area>.json` 放置元数据 | `export_cesium.py` |

**改动 stage 的打印格式会静默破坏 parity 契约**——`parity.js:118-121` 解析这两个标记。

---

## 摘要工具本身的两条约定

改 `scene_digest.py` / `glb-digest.js` 时：

1. **浮点数四舍五入到 6 位**（`scene_digest.py:17-18`）。Blender 会把浮点数
   round-trip 过单精度，repr 的最后几位不是有意义的信号
2. **不稳定字段属于 `UNSTABLE_*` / `IGNORED_*` 名单，不属于摘要**
   （`scene_digest.py:11-13`）。Blender 自己加的对象自定义属性
   （`_RNA_UI`、`cycles`）就是这么排除的（`scene_digest.py:24-25`）

> 否则校验就是噪音，然后就会被忽略。一个天天报红的检查等于没有检查。

---

## 什么时候必须跑

| 改动 | 要不要跑 |
|---|---|
| 挪函数、拆模块、改导入 | **必须**——纯重构的定义就是产物不变 |
| 调整 `ROAD_LAYERS` / `MATERIALS` 的**顺序** | **必须**——会平移 GLB 材质索引 |
| 改材质名 | **必须**——可能静默断开 Cesium 侧的四张覆盖表 |
| 改几何构建、采样、实例化逻辑 | **必须** |
| 改 stage 的 stdout 打印 | **必须**——标记本身是契约 |
| 改 `.trellis/` 下的文档 | 不用 |
| 改 README / changelog | 不用 |
| **有意**改变产物（新功能、修渲染 bug） | 跑，但目的是**看清差异范围**，不是要全绿 |

最后一行很重要：parity 不只是"证明没变"的工具，也是"确认只变了预期的那部分"的工具。
加一种新植被，应该只看到新增对象，不该看到道路网格的顶点数也动了。

---

## 有意改变产物时怎么做

1. 先 capture 一份改动前的基线
2. 改
3. capture 改动后
4. compare，**逐条读差异**
5. 差异要么是预期的，要么就是 bug——**没有第三种**
6. 把结论写进 `docs/changelog.md`

---

## 风险高的改动要分次提交

`docs/refactor-plan.md` 对风险最高的一期写着：

> 逐要素分次提交，每次单独跑 parity。

一次改十个要素然后发现摘要有差异，你不知道是哪个引起的。**一次一个，每次跑校验。**

---

## 当前重构进度（`docs/refactor-plan.md`）

那份计划是**临时工作文档**，P3 收尾后会并入 changelog 并删除。当前状态：

| 期 | 内容 | 状态 |
|---|---|---|
| P0 | 抽纯函数到 `osmassets/{osm,geom}.py` | ✅ 已完成 |
| P1 | `catalog.py` 单一定义源 + `check_layers` | ✅ 已完成 |
| P2 | 要素注册表 | ⚠️ **部分**——`water/grass/scrub/tree.py` 已拆出，但**没有 `features/` 注册表**，`building` / `fountain` / `roads` 仍在 `generate_scene.py` 里 |
| P3 | 材质契约化（自定义属性传递 spec） | ❌ **未做**——`export_cesium.py` 仍不 import `catalog`，靠四张材质名表；`catalog.CESIUM_EXPORT` 是死代码 |

### 已知缺陷（记录在案，本轮不修）

| # | 位置 | 现象 |
|---|---|---|
| D1 | `export_cesium.py:74,82,91,100` | `"Office White Metal Facade"` 四张表里都有，但 `catalog` 里已无此材质——死条目 |
| D2 | `scene-layers.js` vs `catalog.py` | 同一批图层的颜色两侧各自手调，无一致性保证（**这是刻意的**，见[图层表](../pipeline/layer-registry.md#为什么颜色刻意不同步)） |
| D3 | `generate_scene.py` `tuft_density_wave` | 注释仍在跟已删除的 hedge banding 作对比 |

**碰到它们不要顺手修**——修复会改变产物或扩大 diff，属于独立决定。

---

## 反模式

| 反模式 | 后果 |
|---|---|
| 跳过 control 实验直接开始改 | 分不清真回归和天然噪声 |
| 因为"老是报红"往忽略名单里加字段 | 把真回归一起忽略掉 |
| 忽略名单不写理由 | 下一个人无法判断该不该移出来 |
| 直接 diff 文件字节 | 永远红，然后所有人都不看了 |
| 一次改十个地方再跑校验 | 差异定位不到具体改动 |
| 改 stage 打印格式 | 静默破坏契约 |
| 摘要里保留不稳定字段 | 检查变噪音，最终被忽略 |
| 顺手修 D1–D3 | 改变产物或扩大 diff |

---

## 相关

- [模块结构](../blender/module-structure.md)：bpy 层为什么没有单元测试
- [测试](../blender/testing.md)：纯 Python 层的防线
- [资产生成](../blender/asset-generation.md)：为什么构建必须确定性
- [图层表](../pipeline/layer-registry.md)：顺序为什么是承重的