Initialize Trellis project guidelines

.trellis/spec/config/index.md

@@ -0,0 +1,187 @@
+# Config：区域配置
+
+> 覆盖 `config/areas/*.json`、`config/examples/template.json`、`config/default.json`。
+> 无运行时——这是**管线三层共同消费的契约**，改一个字段会同时影响 Node、Blender、
+> 预览页。
+
+---
+
+## 两层配置
+
+用户只写第一层，第二层是机器生成的中间产物：
+
+```
+config/areas/<id>.json                          ← 你写的
+        │  build-area.js: normalizeAreaConfig()   补默认值 + 推导 14 个输出路径
+        ▼
+<areaDir>/_pipeline/osm2streets-qgis.config.json  ← 生成的，不要手改
+        │
+        ▼  build-osm2streets-qgis.js / reimport-gpkg.js
+```
+
+派生配置落在 `_pipeline/` 而不是临时目录——**构建失败时它还在**，可以直接拿去复现。
+
+`config/default.json` 和 `config/hanyang-block.json` 是**低层脚本**
+（`npm run build:qgis`）用的旧格式配置，与 `config/areas/` 不是一回事。
+新工作一律用 `config/areas/`。
+
+---
+
+## 新增一个区域
+
+```bash
+cp config/examples/template.json config/areas/my-area.json
+```
+
+改 `id` 和 `input` 就能跑。其余全有默认值。
+
+---
+
+## 字段全表
+
+### 顶层
+
+| 字段 | 必填 | 默认 | 说明 |
+|---|---|---|---|
+| `id` | ✅ | — | 区域标识。**同时是默认输出目录名和全部产物的文件名 stem** |
+| `input` | ✅ | — | OSM XML 的**绝对路径**。不存在直接抛错 |
+| `outputRoot` | | `<repo>/outputs` | 输出根目录 |
+| `qgisApp` | | `/Applications/QGIS.app` | 也可用环境变量 `QGIS_APP` |
+| `blenderApp` | | `/Applications/Blender.app` | |
+| `stages` | | 见下 | 各阶段默认开关 |
+| `qgis` | | 见下 | QGIS/osm2streets 旋钮 |
+| `osm2streets` | | 见下 | 透传给 osm2streets 的选项 |
+| `blender` | | 见下 | Blender 侧选项 |
+| `outputs` | | 从 `id` 推导 | 输出路径覆盖，逃生舱 |
+
+**路径一律绝对**。`normalizeAreaConfig` 对每一项都做 `path.resolve`，相对路径会
+相对于**进程 cwd** 解析，不是相对于配置文件——所以别用。
+
+### `stages`
+
+| 字段 | 默认 | 说明 |
+|---|---|---|
+| `intermediates` | `true` | 旧名 `qgis` 仍被接受 |
+| `blender` | `true` | |
+| `cesium` | `true` | |
+
+`reimport` 和 `preview` **在这里配也没用**——`normalizeAreaConfig:117-118` 把它们
+硬编码为 `false`，只能靠 `--stages` 显式请求。
+
+> 恢复动作（reimport）和补丁动作（preview）不该被一份配置文件变成默认行为。
+
+`--stages` 会整体覆盖这里的默认值。
+
+### `qgis`
+
+| 字段 | 默认 | 说明 |
+|---|---|---|
+| `arrowScale` | `0.8` | 导出前对 osm2streets 车道箭头多边形的缩放 |
+| `arrowMergeTriangles` | `true` | 把箭头的三角网合并成一个合法多边形。**保留原箭头形状和转向**，同时消掉共享三角边处的渲染缝隙 |
+| `arrowOutlineSimplifyMeters` | `0.05` | 去掉合并后箭头外轮廓上的亚分米级折角。默认值刚好去掉两个畸形尾顶点而**不动箭头头部**，剩下的尾边与杆身垂直 |
+| `intersectionCornerSourceMaxDimensionMeters` | `2.6` | 只保留小尺寸的 `sidewalk corner` 多边形。**大的路口标记多边形不当人行道处理**，因为它们会盖住可行驶的路口 |
+| `clipPad` | `0.002` | 送进 osm2streets 的裁剪框外扩（度） |
+| `canvasPad` | `0.001` | QGIS 画布范围外扩（度） |
+| `previewPad` | `0.0007` | 预览图范围外扩（度） |
+| `canvasExtent` | `null` | 显式画布范围，覆盖 `canvasPad` |
+| `previewExtent` | `null` | 显式预览范围，覆盖 `previewPad` |
+| `layerPrefix` | `"osm2streets"` | QGIS 图层名前缀 |
+
+三个 pad 单位是**度不是米**，且必须 `>= 0`（`build-osm2streets-qgis.js:49-53` 校验）。
+`arrowScale` 必须 `> 0`。
+
+> 这四个 arrow/corner 旋钮的默认值都是调出来的，**改之前先看 README 里记的理由**。
+> 尤其 `arrowOutlineSimplifyMeters`——调大会开始削箭头头部。
+
+### `osm2streets`
+
+原样透传给 `JsStreetNetwork` 构造函数（`build-osm2streets-qgis.js:77`）。默认：
+
+```json
+{
+  "debug_each_step": false,
+  "dual_carriageway_experiment": false,
+  "sidepath_zipping_experiment": false,
+  "inferred_sidewalks": true,
+  "osm2lanes": true
+}
+```
+
+⚠️ **给了就整体替换，不做逐字段合并**（`build-area.js:132`：`raw.osm2streets || {...}`）。
+只想改一个开关也必须把五个字段全写上，否则其余四个会退到 osm2streets 自己的默认值。
+
+### `blender`
+
+| 字段 | 默认 | 说明 |
+|---|---|---|
+| `treeStyle` | `"natural"` | 合法值见 `generate_scene.py:144` 的 `TREE_STYLES`（`natural`、`procedural`，加上 `tree.py` 注册的模型 style） |
+| `officeOverrides` | `""` | 旧名 `office_overrides` 仍被接受 |
+
+### `outputs`（逃生舱）
+
+默认全部从 `id` 推导为 `<outputRoot>/<id>/<fileStem>.<ext>`。需要定制时逐项覆盖：
+
+```json
+{
+  "outputs": {
+    "areaDir": "/absolute/path/to/custom-area",
+    "blend":   "/absolute/path/to/custom.blend",
+    "glb":     "/absolute/path/to/custom.glb",
+    "cesiumPreview": "/absolute/path/to/custom-preview.html"
+  }
+}
+```
+
+可覆盖的键（`build-area.js:87-102`）：`areaDir`、`fileStem`、`geojsonDir`、`gpkg`、
+`qgisProject`、`qgisPreview`、`blend`、`render`、`glb`、`metadata`、`cesiumPreview`、
+`vehicleRoute`、`vehicleModel`、`pipelineDir`。
+
+**优先改 `fileStem` 或 `areaDir`**——它们能一次性影响全部派生路径。逐个覆盖容易漏。
+
+---
+
+## 加一个配置字段
+
+1. `normalizeAreaConfig`（`build-area.js:74`）里加进对应的分组，**用 `??` 不用 `||`**
+   （`false` / `0` 可能是合法值）
+2. 只写两级 fallback：`raw.<group>?.<key> ?? 默认值`。
+   **不要**制造新的顶层平铺别名——那三级写法是历史兼容，不是模式
+3. 若要传给低层脚本，加进 `writeDerivedConfig`（`:189`）的 `derivedConfig` 对象
+4. 若是数值，在消费侧加 `Number.isFinite` + 范围校验，**在任何副作用之前**
+5. 更新 `config/examples/template.json`
+6. 更新本文档的字段表
+
+若新字段产出新文件，同时在 `outputs` 里加一行路径推导。
+
+---
+
+## 已沉淀的区域
+
+- `config/areas/nantaizi-lake-innovation-valley.json`（默认构建目标）
+- `config/areas/hanyang-block.json`
+
+两者都是 parity 校验的样本区域（`parity.js:26` 的 `DEFAULT_AREAS`）——
+**改动它们会影响基线比对**。
+
+---
+
+## 反模式
+
+| 反模式 | 后果 |
+|---|---|
+| 用相对路径 | 相对 cwd 解析，换个目录跑就错 |
+| 手改 `_pipeline/*.config.json` | 下次构建被覆盖 |
+| 只写 `osm2streets` 的一个字段 | 其余四个静默退到 osm2streets 默认值 |
+| 布尔字段用 `\|\|` 兜底 | `false` 被翻转 |
+| 给新字段造顶层平铺别名 | 扩大历史包袱 |
+| 逐个覆盖 `outputs` 而不用 `fileStem` | 漏掉某个产物路径 |
+| 在 `stages` 里配 `reimport` / `preview` | 无效，被硬编码为 false |
+| 加数值字段不做范围校验 | 错配置在中途才崩，输出已被破坏 |
+
+---
+
+## 相关
+
+- [CLI 与阶段](../pipeline/cli-and-stages.md)：配置怎么被读取和派生
+- [外部工具调用](../pipeline/external-tools.md)：`qgisApp` / `blenderApp` 怎么用
+- README「区域配置」节：面向使用者的说明