81 lines
3.5 KiB
Markdown
81 lines
3.5 KiB
Markdown
# 思考指南索引
|
||
|
||
> 目的：在改代码前补一遍"跨层会不会断、重复事实会不会漂、产物是否仍一致"。
|
||
> 本目录不替代包级 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` 的旧材质名回退表
|
||
- [ ] 改 `build-area.js:74` 的 `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 定位
|