# 思考指南索引

> 目的：在改代码前补一遍"跨层会不会断、重复事实会不会漂、产物是否仍一致"。
> 本目录不替代包级 spec；它用于那些单看一个文件容易误判的改动。

---

## 可用指南

| 指南 | 关注点 | 什么时候读 |
|---|---|---|
| [跨层思考指南](./cross-layer-thinking-guide.md) | JS、GDAL/QGIS、Blender Python、浏览器之间的数据契约 | 改图层、材质名、配置字段、stage 输出、外部工具调用 |
| [代码复用思考指南](./code-reuse-thinking-guide.md) | 单一事实源、重复解析、可接受重复与应抽取重复的边界 | 改 `parseArgs`、图层表、配置归一化、几何工具 |
| [产物一致性指南](./artifact-parity-guide.md) | `.blend` / `.glb` / metadata 的结构摘要校验 | 任何声称"纯重构、产物不变"的改动 |

---

## 本项目触发点

### 读跨层思考指南

- [ ] 改 `scripts/lib/scene-layers.js:15` 的 `SCENE_LAYERS`
- [ ] 改 `blender/osmassets/catalog.py:28` 的 `ROAD_LAYERS` 或 `catalog.py:56` 的 `MATERIALS`
- [ ] 改 `catalog.MATERIALS[*]["cesium"]`、`material["cesium_export"]` 或
  `export_cesium.py` 的旧材质名回退表
- [ ] 改 `scripts/lib/area-config.js` 的 `normalizeAreaConfig()` 或 `config/examples/template.json`
- [ ] 改任何 `execFileSync` / `spawnSync` 调起的脚本或参数
- [ ] 改 `SCENE_DONE` / `CESIUM_EXPORT_DONE` 的 stdout 标记

### 读代码复用思考指南

- [ ] 准备新增第二份或第三份图层、材质、配置字段枚举
- [ ] 修改多份重复的 `parseArgs` 之一：
  `build-area.js:54`、`build-osm2streets-qgis.js:153`、`reimport-gpkg.js:93`、
  `compress-glb.js:16`、`diagnose-area.js:17`
- [ ] 多个要素模块都要做同一件几何预处理，比如
  `water.py:9`、`grass.py:9`、`scrub.py:8` 都先 `clip_polygon`
- [ ] 低层脚本想直接读取 `config/areas/*.json`，绕开派生配置
- [ ] 新增 helper 前没有先 `grep -rn` 找现有函数

### 读产物一致性指南

- [ ] 挪函数、拆模块、改导入，且声称产物不变
- [ ] 重排 `ROAD_LAYERS` / `MATERIALS`
- [ ] 改材质名或导出调色逻辑
- [ ] 改几何、采样、实例化、UV、材质构建
- [ ] 改 `scripts/parity.js`、`scripts/glb-digest.js`、`blender/tools/scene_digest.py`

---

## 改值前的固定动作

```bash
grep -rn "要改的值" scripts blender config
```

本仓库跨 JS、Blender Python、浏览器 JS 和 JSON，很多连接靠字符串或文件名约定。
例如 `scene-layers.js` 与 `catalog.py` 只靠 `id` 集合和顺序对账；
`generate_scene.py` 与 `export_cesium.py` 的新材质导出契约靠 `.blend` 里的
`material["cesium_export"]` 自定义属性，旧 `.blend` 仍靠 `export_cesium.py`
的材质名回退表。

---

## 审查 AI 结果时

- 先看它有没有读到对应包的 index 和本目录指南
- 对任何"行为没变"的结论，要求说明是否需要 parity；需要却没跑就是风险
- 对任何"可以合并重复"的建议，先判断重复是不是刻意边界：
  多份 `parseArgs` 目前是可接受技术债，JS/Python 图层颜色则是刻意不同步
- 对任何"加精度、加默认值、直接覆盖文件"的建议，回到真实代码注释验证；
  `reimport-gpkg.js:152-156` 和 `reimport-gpkg.js:11-13` 都是反直觉约束

---

## 维护规则

- 发现新的跨层坑，优先补到相关指南，再补包级 spec
- 指南只写本项目已发生或代码已体现的约束，不写通用工程格言
- 每条新约束至少带两个真实路径或函数名，方便后续 grep 定位