# 自动匹配 Cesium 巡航车道中心：实施计划

## 实施顺序

- [x] 1. 新增 `scripts/lib/lane-geometry.js`，从 `turn-lane-arrows.js` 迁移并导出 Driving polygon 中轴提取与必要的纯几何 helper；补充共享几何测试，确认箭头行为不变。
- [x] 2. 扩展 `scripts/lib/vehicle-route.js` 输入校验和车道索引，按 OSM way、行驶方向、实际横向位置及 maneuver 选择目标 Driving lane。
- [x] 3. 实现同车道多 fragment 的方向校验、确定性拼接和 lane centerline 路线生成；删除固定偏移路径，加入稳定 reason-code diagnostics 与 `laneSegments` 溯源。
- [x] 4. 更新 `scripts/test-preview-assets.js` fixture，覆盖 `3.0 m` / `3.5 m`、双向单车道、同向多车道、oneway、正反方向、左/直/右选择、坏 polygon 和缺失匹配。
- [x] 5. 修改 `scripts/build-area.js`，在任何 preview 写入前校验 `lane_polygons.geojson`，传给路线生成器并记录到 stage manifest inputs。
- [x] 6. 修改 `scripts/lib/area-diagnostics.js` 的 preview expected inputs，并补充 manifest freshness 回归测试或等价断言。
- [x] 7. 更新 README 巡航说明，移除固定 `1.3 m` 描述，说明实际车道中轴、跳过语义和诊断字段。
- [x] 8. 重生成目标区域 preview 路线，检查所有 route 的 lane 溯源、空/拒绝诊断和直线路段 `<= 0.10 m` 中心误差。
- [x] 9. 将路线拓扑切换到 `network.json` internal road/intersection，并对 connector 执行 `intersection_surface` 越界拒绝；预览仅显示当前选中 route，等待用户做最终视觉复核。

## 当前验证状态

- 目标区域只读生成验证通过：`5` 条路线、`56` 个 lane segment、`116` 个中轴顶点最大误差 `0 m`，覆盖 left/right/through/u_turn，实际 center offset 范围 `1.415–1.588 m`。
- 第 8、9 步暂未完成：preview stage 在写产物前因既有 `traffic_signal_assemblies.geojson` 和 `traffic_signals.json` 缺失而失败。
- `check:area` 的 3 个 failure 均来自既有 intermediates/blender/preview manifest stale；修复需要重跑会重建 GeoPackage 的 intermediates，未获用户授权前不执行。

## 验证命令

```bash
node --check scripts/lib/lane-geometry.js
node --check scripts/lib/vehicle-route.js
node --check scripts/lib/turn-lane-arrows.js
node --check scripts/build-area.js
npm run test:turn-lane-arrows
npm run test:preview-assets
npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages preview
npm run diagnose:area -- --config config/areas/nantaizi-lake-innovation-valley.json
npm run check:area -- --config config/areas/nantaizi-lake-innovation-valley.json
```

若仓库已有覆盖 manifest freshness 的独立测试入口，一并运行；否则在现有最接近的 Node 测试中加入定向断言。

## 风险与检查点

- polygon fragment 拼接是最高风险点：完成第 3 步后先用目标区域做只读匹配统计，确认不会因 osm2streets 分段导致全部路线被拒绝，再继续 stage 集成。
- 多车道 lane order 不得只依赖 renderer `index`；必须用行驶方向下的实际横向位置验证顺序。
- 不把 OSM `width` 或默认宽度作为无声回退；任何覆盖率下降必须能从 diagnostics 定位。
- 不修改用户已有的 `config/areas/nantaizi-lake-innovation-valley.json` Linux 路径变更。
- 不需要 GLB parity；本任务不改变 Blender/GLB。但必须重跑 preview manifest 和区域质量门。