Initialize Trellis project guidelines
This commit is contained in:
217
.trellis/spec/guides/cross-layer-thinking-guide.md
Normal file
217
.trellis/spec/guides/cross-layer-thinking-guide.md
Normal file
@@ -0,0 +1,217 @@
|
||||
# 跨层思考指南
|
||||
|
||||
> **目的**：动手前把数据流走一遍，把"没想到"变成"想过了"。
|
||||
>
|
||||
> 本项目的层是**跨语言、跨进程、跨运行时**的，边界比普通应用多得多。
|
||||
|
||||
---
|
||||
|
||||
## 本项目的层与边界
|
||||
|
||||
```
|
||||
config/areas/*.json JSON 数据
|
||||
↓ ①
|
||||
build-area.js Node（宿主机）
|
||||
↓ ② 派生配置 JSON
|
||||
build-osm2streets-qgis.js Node + osm2streets WASM
|
||||
↓ ③ 子进程 + 环境变量
|
||||
ogr2ogr / ogrinfo / QGIS Python GDAL/QGIS 运行时
|
||||
↓ ④ GeoJSON / GeoPackage 文件
|
||||
generate_scene.py Blender 内嵌 Python
|
||||
↓ ⑤ .blend 文件 + 材质名字符串
|
||||
export_cesium.py Blender 内嵌 Python
|
||||
↓ ⑥ GLB + JSON
|
||||
cesium-preview.js 浏览器
|
||||
```
|
||||
|
||||
| # | 边界 | 常见问题 |
|
||||
|---|---|---|
|
||||
| ① | 用户配置 → 归一化 | `??` vs `\|\|`、相对路径、字段整体替换 |
|
||||
| ② | 两层配置 | 低层脚本读错配置源 |
|
||||
| ③ | Node → 外部进程 | 环境变量缺失、退出码与信号、0 字节产物 |
|
||||
| ④ | 文件交换 | 图层集合/顺序漂移、精度丢失 |
|
||||
| ⑤ | Python → Python | **材质名字符串**，无校验 |
|
||||
| ⑥ | Blender → 浏览器 | 坐标系约定、材质在两种光照下的差异 |
|
||||
|
||||
---
|
||||
|
||||
## 什么时候该读这篇
|
||||
|
||||
- [ ] 改动同时出现在 `scripts/` 和 `blender/` 里
|
||||
- [ ] 你在改九个 osm2streets 图层中的任何一个
|
||||
- [ ] 你在改材质名、材质顺序
|
||||
- [ ] 你在往配置里加字段
|
||||
- [ ] 你在改任何被 `execFileSync` / `spawnSync` 调起的东西
|
||||
- [ ] 你在改 stage 的 stdout 打印
|
||||
- [ ] 你要新增一种在 Blender 里生成、要在 Cesium 里看的资产
|
||||
|
||||
---
|
||||
|
||||
## Step 1：画数据流
|
||||
|
||||
对每一个箭头问三件事：
|
||||
|
||||
- **格式是什么**——JSON？GeoJSON FeatureCollection？GeoPackage 图层？字符串键？
|
||||
- **可能出什么错**——文件不存在？0 字节？字段名对不上？
|
||||
- **谁负责校验**——上游写的时候，还是下游读的时候？
|
||||
|
||||
本项目的答案通常是：**上游写完就走，下游读的时候校验**。因为上游经常是外部工具
|
||||
（ogr2ogr、Blender），改不动。
|
||||
|
||||
## Step 2：找出"约定型"边界
|
||||
|
||||
最危险的不是有 schema 的边界，是**靠约定连接**的边界：
|
||||
|
||||
| 边界 | 靠什么连接 | 有没有校验 |
|
||||
|---|---|---|
|
||||
| `scene-layers.js` ↔ `catalog.py` | 图层 `id` 的集合与顺序 | ✅ `check_layers()`（warn） |
|
||||
| `generate_scene.py` ↔ `export_cesium.py` | **材质名字符串** | ❌ **无** |
|
||||
| GeoJSON 文件名 ↔ 图层 id | `layerFile()` 拼 `<id>.geojson` | 部分（reimport 会检查 gpkg 图层是否齐全） |
|
||||
| stage stdout ↔ `parity.js` | `SCENE_DONE` / `CESIUM_EXPORT_DONE` 字面量 | ❌ 无 |
|
||||
| GLB 材质索引 ↔ `MATERIALS` 顺序 | 隐式的创建顺序 | ❌ 无（靠 parity 事后发现） |
|
||||
|
||||
**没有校验的那几行就是本项目最容易静默出错的地方。**
|
||||
|
||||
## Step 3：定契约
|
||||
|
||||
对每个边界写清楚：输入格式、输出格式、能出什么错。
|
||||
本项目已定的契约见[产物一致性指南](./artifact-parity-guide.md#真正的契约)。
|
||||
|
||||
---
|
||||
|
||||
## 本项目真实踩过的坑
|
||||
|
||||
### 坑 1：同一份事实存了四份
|
||||
|
||||
九个图层的顺序曾同时存在于 z_index 表、样式 JSON、QGIS 工程、README。
|
||||
改一处漏三处，**不报错**，只是下游场景悄悄错栈。
|
||||
|
||||
**修法**：`scripts/lib/scene-layers.js` 单一事实源 + 四个派生函数。
|
||||
跨语言那一份（`catalog.py`）无法消除，改用运行时对账。
|
||||
|
||||
→ [图层表](../pipeline/layer-registry.md)
|
||||
|
||||
### 坑 2：外部工具失败但留下了文件
|
||||
|
||||
`ogr2ogr` 遇到不存在的图层退出码非零，**但已经创建了一个 0 字节文件**。
|
||||
直接覆盖目标目录就会用空文件冲掉好数据，而且看起来像成功。
|
||||
|
||||
**修法**：staging 目录 → 全部校验 → 才落盘。
|
||||
|
||||
→ [外部工具调用](../pipeline/external-tools.md#2-导出失败会留下-0-字节文件)
|
||||
|
||||
### 坑 3：为了"输出干净"加了个参数
|
||||
|
||||
给 `ogr2ogr` 显式设 `COORDINATE_PRECISION`，触发了 GDAL 的精度裁剪，
|
||||
7 个箭头多边形丢了 28 个顶点。默认行为本来就能完整往返双精度。
|
||||
|
||||
**教训**：跨边界时，**显式设置一个"看起来更安全"的参数，可能触发上游的另一条代码路径**。
|
||||
|
||||
### 坑 4：新资产在 Blender 里对、在 Cesium 里发黑
|
||||
|
||||
场景里每一个材质都被手工提亮过（草往亮绿混 72%、建筑自发光 0.18），
|
||||
因为 Cesium 默认光照偏白。新资产没调过，是唯一如实渲染的东西，
|
||||
放在旁边就显得发黑。
|
||||
|
||||
**教训**：**同一份数据在两个运行时里的"正确"可能不一样**。
|
||||
第二个运行时如果有一整套补偿，新东西必须也进那套补偿。
|
||||
|
||||
→ [资产生成](../blender/asset-generation.md#为什么新资产总是发黑)
|
||||
|
||||
### 坑 5：两个 Python 脚本靠字符串对接
|
||||
|
||||
`export_cesium.py` 不 import `catalog`，靠材质名字符串匹配四张覆盖表。
|
||||
改个材质名，Cesium 侧的调色**静默失效**。`catalog.CESIUM_EXPORT` 想解决这个问题，
|
||||
但迁移没做完，它现在是死代码。
|
||||
|
||||
**教训**：**字符串键的跨模块耦合必须配一个对账机制**，否则重命名就是定时炸弹。
|
||||
|
||||
---
|
||||
|
||||
## 加东西时的检查清单
|
||||
|
||||
### 加一个图层
|
||||
|
||||
- [ ] `scene-layers.js:SCENE_LAYERS` 末尾追加
|
||||
- [ ] `catalog.py:ROAD_LAYERS` 末尾追加，**顺序一致**
|
||||
- [ ] 确认 osm2streets 拆分结果里有对应的 `splitKey`
|
||||
- [ ] 跑一次构建，确认日志里没有 `Layer catalog warning:`
|
||||
- [ ] 跑 parity，确认只多了预期的对象
|
||||
|
||||
### 加一个材质
|
||||
|
||||
- [ ] `catalog.MATERIALS` **末尾**追加（中间插入会平移 GLB 材质索引）
|
||||
- [ ] 若在 Cesium 里需要调色，去 `export_cesium.py` 的四张表加
|
||||
- [ ] 跑 parity
|
||||
|
||||
### 加一个配置字段
|
||||
|
||||
- [ ] `normalizeAreaConfig` 里用 `??` 不用 `||`
|
||||
- [ ] 需要传给低层脚本？加进 `writeDerivedConfig`
|
||||
- [ ] 数值？在消费侧加 `Number.isFinite` + 范围校验，**在任何副作用之前**
|
||||
- [ ] 更新 `config/examples/template.json`
|
||||
- [ ] 更新 [config spec](../config/index.md) 的字段表
|
||||
|
||||
### 加一个 stage
|
||||
|
||||
- [ ] `normalizeAreaConfig` 的 `stages` + `resolveStages` 的 `aliases`
|
||||
- [ ] 想清楚进不进 `all`（恢复类/补丁类不进）
|
||||
- [ ] 与已有 stage 有覆盖关系？加互斥检查
|
||||
- [ ] 产出新文件？加进 `outputs` 路径推导
|
||||
- [ ] 阶段函数开头 `ensureFile` 校验依赖产物
|
||||
|
||||
### 加一种 OSM 要素
|
||||
|
||||
- [ ] 新模块放 `osmassets/`，`assemble(...)` 签名照抄现有三个
|
||||
- [ ] 只 import 需要的，**纯几何逻辑放 `geom.py` 并补测试**
|
||||
- [ ] 材质加进 `catalog.MATERIALS` 末尾
|
||||
- [ ] `generate_scene.py` 分发处加一行
|
||||
- [ ] 需要"随机"外观？用 index 的纯函数或显式 seed，**不要用 `random`**
|
||||
- [ ] 跑 parity
|
||||
|
||||
---
|
||||
|
||||
## 通用的四个错误
|
||||
|
||||
### 隐式格式假设
|
||||
|
||||
跨边界时假设"上游肯定给的是 X 格式"。本项目的做法是**读的时候验**：
|
||||
`reimport-gpkg.js:175` 明确检查 `type === "FeatureCollection" && Array.isArray(features)`。
|
||||
|
||||
### 校验散在各处
|
||||
|
||||
同一个约束在三个地方各写一遍，改的时候漏一个。
|
||||
本项目把参数校验集中在脚本开头（`build-osm2streets-qgis.js:41-70`），
|
||||
**在任何副作用之前一次验完**。
|
||||
|
||||
### 抽象泄漏
|
||||
|
||||
低层脚本如果直接读 `config/areas/*.json`，两层配置的边界就白设了。
|
||||
它们只该读派生配置。
|
||||
|
||||
### 每个消费方各自解析同一份数据
|
||||
|
||||
看到两处代码用各自的方式从同一份 payload 里挖同一个字段，
|
||||
就该有一个共享的解析函数了。`mergeScene(getCollection)` 用回调而不是数组，
|
||||
就是为了让 build 和 reimport 共用一套合并逻辑。
|
||||
|
||||
---
|
||||
|
||||
## 一条铁律
|
||||
|
||||
> **改任何值之前，先全仓 grep 一遍。**
|
||||
|
||||
```bash
|
||||
grep -rn "要改的值" scripts blender config
|
||||
```
|
||||
|
||||
本项目跨两种语言，IDE 的"查找引用"帮不上忙。这一个习惯能挡掉大部分
|
||||
"忘了同步 X" 的 bug。
|
||||
|
||||
---
|
||||
|
||||
## 相关
|
||||
|
||||
- [代码复用思考指南](./code-reuse-thinking-guide.md)
|
||||
- [产物一致性指南](./artifact-parity-guide.md)
|
||||
- [图层表](../pipeline/layer-registry.md)
|
||||
Reference in New Issue
Block a user