feat: add cesium traffic signal countdowns

.trellis/spec/pipeline/cli-and-stages.md

@@ -343,6 +343,84 @@ out.vehicleStopLines = crosswalkData.stopLines;
 // 原生 lane_markings 停止线不得复制到输出。
 ```
 
+## 信号锚点的跨阶段消费
+
+### 1. Scope / Trigger
+
+路口信号设施需要同时被 Blender 主 GLB 和 Cesium 预览消费时，使用
+`<geojsonDir>/traffic_signals.json`。它是附属 intermediates 产物，而不是第十个
+osm2streets/QGIS 图层。
+
+### 2. Signatures
+
+```bash
+npm run build:area -- --config config/areas/<area>.json --stages intermediates,blender,cesium,preview
+```
+
+`normalizeAreaConfig()` 将默认路径归一化为：
+
+```js
+area.outputs.trafficSignals
+// <areaDir>/osm2streets_web_out/traffic_signals.json
+```
+
+### 3. Contracts
+
+- `build-area.js:writeTrafficSignals()` 是锚点 JSON 的生产者，调用
+  `traffic-signals.js:readTrafficSignals()`，输入为 `vehicle_stop_lines.geojson` 和
+  `intersection_surface.geojson`。
+- `intermediates` 与 `reimport` 都必须在其 GeoJSON 产物稳定后重写锚点，确保 QGIS
+  人工修补反导入后，Blender 和 preview 仍使用同一事实。
+- `blender` 和 `preview` 在启动前必须检查该文件存在；前者把静态设施写进 `05_Props`，
+  后者只叠加动态灯珠、倒计时和车辆相位。
+- `traffic_signals.json` 不得加入 `SCENE_LAYERS`、GeoPackage 或 QGIS 工程；这些层只能
+  继续包含九个道路场景图层。
+- `layout.countdownLateralMeters` 等几何字段是 Blender/preview 的共同事实源；横向正值统一
+  表示相对来车方向的右侧。不得在任一消费方用独立的负号约定替代它。
+- `layout.mastHeightMeters` 与 `layout.headCenterHeightMeters` 必须相等，表示横杆与灯壳的
+  中心对齐；`lensVerticalOffsetsMeters` 以灯壳中心为基准，正值向上、负值向下。当前倒计时牌
+  垂直偏移为 `0`，必须贴在横杆上而非悬挂。
+
+### 4. Validation & Error Matrix
+
+| 条件 | 结果 |
+|---|---|
+| `intermediates` 或 `reimport` 有合法停止线和路口面 | 写出 `version` 与 `signals` 数组，即使数组为空 |
+| 直接运行 `blender` / `preview` 但锚点不存在 | 在启动外部工具前报 `Traffic signal anchors not found` |
+| 单个停止线无法可靠关联路口 | 锚点生成器跳过该项，其他进口照常输出 |
+| 用户仅修改 QGIS 后运行 `reimport` | 重新生成锚点，不沿用旧坐标 |
+
+### 5. Good/Base/Bad Cases
+
+- Good：完整构建后，GLB 的静态灯杆/灯壳和 Cesium 动态灯珠使用同一份 anchor。
+- Base：没有可用进口时写出空 `signals`，Blender 继续生成其余场景。
+- Bad：在 Cesium 中再次推导灯杆位置，或把 anchors 导入 GeoPackage；两者都会产生位置
+  漂移或污染人工 QGIS 工作流。
+
+### 6. Tests Required
+
+- `npm run test:budgets`：断言默认锚点路径位于 `osm2streets_web_out/`。
+- `npm run test:preview-assets`：断言预览配置仍传递相对锚点 URL。
+- 目标区域完整构建：确认 `traffic_signals.json` 与 Blender/preview stage manifest 均存在。
+- Blender 可运行环境：检查 `SCENE_DONE.traffic_signals`、主 GLB 的 `05_Props` 设施，
+  以及 Cesium 动态叠层与静态灯壳对齐。
+
+### 7. Wrong vs Correct
+
+错误：
+
+```js
+// preview 运行时再次从两份 GeoJSON 推导另一组锚点。
+const signals = buildTrafficSignals(stopLines, intersections);
+```
+
+正确：
+
+```js
+// Blender 与 preview 都消费 intermediates 写出的同一份文件。
+ensureFile(area.outputs.trafficSignals, "Traffic signal anchors");
+```
+
 ## 区域诊断命令
 
 ### 1. Scope / Trigger