# 车辆连续路线

## 1. Scope / Trigger

适用于 `scripts/lib/vehicle-route.js` 生成的路线 JSON，以及
`scripts/lib/cesium-preview.js` 对车辆巡航路线的读取与展示。

触发：修改路线生成、OSM 转向标签解析、车辆选择菜单或路线 JSON 字段时。
路线仅用于 Cesium 验证预览，不构成交通仿真或法规级导航。

## 2. Signatures

```js
buildVehicleRoute(osmPath, lanePolygonsPath, networkPath, intersectionSurfacePath) => {
  source, laneSource, networkSource, intersectionSource, bounds, generatedAt, speedMetersPerSecond, loop,
  routes, segments, diagnostics
}

allowedTurns(tags, direction) => Set<"left" | "through" | "right">
classifyConnection(incomingEdge, outgoingEdge) =>
  "left" | "through" | "right" | "u_turn"
```

浏览器运行时调用 `addVehicleCruises(viewer, routeData, vehicleModelName)`；它首先读取
`routeData.routes`，仅在其不存在时回退到 `routeData.segments`。

## 3. Contracts

- `routes` 是当前主字段；`segments` 必须是同一数组的兼容别名，供旧预览使用。
- 每个路线至少包含 `id`、`coordinates`、`centerlineCoordinates`、`lengthMeters`、
  `maneuvers`、`edgeIds`、`laneSegments` 与 `connectors`。道路区间来自匹配的 Driving lane polygon 中轴。
- 路线拓扑以 `network.json` 的 internal road 和 intersection 为准；禁止把整个 OSM way 直接当作一条不可分割 edge。
- connector 必须绑定同一个 internal intersection，并位于对应 `intersection_surface.geojson` 内或允许的边界容差内；越界时拒绝候选路线。
- legacy osm2streets preview 必须将 `lane_polygons.geojson`、`network.json` 和 `intersection_surface.geojson` 作为强制输入；native preview 不读取这些文件，路线缺失时保留可用预览并省略车辆巡航。
- route 经纬度由 Cesium 按 WGS84 直接放置；最终道路 GLB 必须由 WGS84 ECEF→ENU
  `Projector` 生成。禁止以固定米/度近似投影道路，否则即使 route 与 lane polygon
  完全一致，最终画面仍会随离锚点距离产生横向偏移。
- 单条路线无法可靠匹配时跳过并写结构化 `diagnostics`，不得回退固定或默认车道宽度。
- 有 `oneway=yes`（及等价真值）的 way 只能按 OSM 原始方向生成 edge，绝不能生成反向
  `:backward` edge；`oneway=-1` 仅允许反向 edge。
- 去程在路口按入边方向读取 `turn:lanes:forward` 或 `turn:lanes:backward`，只有标签中的
  `left`、`through`、`right` 才是候选出口；无标签时允许这三类非 U-turn 动作。
- 返程是展示路线的原路回返，不以反向 `turn:lanes` 再次否决，但依旧不可逆行单行道。
- 路网没有闭环时，在去程和返程端点插入平滑调头曲线；不得在 way 端点或路口瞬移。
- 选择菜单使用 `#编号 · 长度 m · 左 N / 右 N / 直 N`，因为一条路线可跨越多个道路名称。
- 预览只显示当前下拉框选中车辆的 route polyline，避免多条闭环轨迹在路口重叠造成错误的偏移判断。

## 4. Validation & Error Matrix

| 条件 | 结果 |
|---|---|
| 缺少或无法读取 route JSON | 预览继续加载，只取消巡航控件 |
| `routes` 存在但为空 | 不回退到旧 `segments`；没有可播放车辆 |
| 可行驶 way 少于两个节点或不在区域范围 | 不生成 edge |
| 只存在反向单行可达路径 | 不生成违反单行限制的路线 |
| 路口夹角接近掉头 | 分类为 `u_turn`，不作为去程出口 |
| 候选路线不足五条 | 输出实际可用数量，预览按已有路线加载 |

## 5. Good/Base/Bad Cases

- 正常：树状道路网产生多条跨 way 往返路线，车辆经过左、右、直三种连接并在端点平滑掉头。
- 基础：旧 JSON 只有 `segments` 时，预览仍能创建车辆与 Follow 控制。
- 错误：对返程再次套用反向 `turn:lanes`，使原路返回在树状网络中被错误过滤。

## 6. Tests Required

- `node scripts/test-preview-assets.js`：断言路线闭合、端点调头、`turn:lanes` 拆分、左/右/直
  分类、单行道不逆行，以及 `segments === routes`。
- `node --check scripts/lib/vehicle-route.js` 与
  `node --check scripts/lib/cesium-preview.js`：保证 Node 与浏览器直载脚本语法可用。
- 对目标区域运行 `npm run build:area -- --config config/areas/<area>.json --stages preview`，确认
  `routes` 中存在左、右、直动作，且 Cesium 下拉标签显示编号、长度与动作统计。
- 修改地理投影时必须运行 `blender,cesium,preview`，不能只重跑 preview；最终检查青色路线
  到黄色中心线及道路边缘的横截面距离，确认两侧路线分别位于各自车道中心。

## 7. Wrong vs Correct

错误：优先使用旧字段，导致新路线元数据无法被消费。

```js
const segments = routeData.segments || routeData.routes || [];
```

正确：新字段优先，旧字段仅作兼容回退。

```js
const routes = routeData.routes || routeData.segments || [];
```

错误：为使路线闭合而生成单行道路的反向 edge。

```js
edges.push(makeEdge(way, refs.reverse(), coords.reverse(), "backward"));
```

正确：单行仅保留其允许的方向，树状网络用端点调头闭合预览路线。

```js
if (oneway !== "-1") edges.push(makeEdge(way, refs, coords, "forward"));
if (!isOneWay(oneway)) edges.push(makeEdge(way, [...refs].reverse(), [...coords].reverse(), "backward"));
```

## 信号动态 GLB 契约

`traffic_signals.json` 的 `pose.*` 是 Blender 静态设施、动态灯珠和倒计时共享的锚点。Blender
把发光灯珠导出为独立的 `*-traffic-signals-dynamic.glb`，preview 必须使用与主 GLB 相同的
`scenePlacement(metadata).modelMatrix` 加载它；Cesium 仅按命名灯珠节点切换 `show`。倒计时
例外：它由 Cesium Entity 从 `pose.countdown` 的 ENU 坐标与面向直接绘制，避免 glTF 轴变换
反转七段字形。

动态表面不能与静态镜片或倒计时外壳共面：镜片和数码管必须沿本地 `face` 轴前移
`(static_depth + dynamic_depth) / 2 + epsilon`。这是模型局部几何关系，不是经纬度修正；
否则静态网格会通过深度测试遮住发光状态，表现为灯不切换或数字不可见。

错误：在 Cesium 用 `fromDegrees`/Entity 重新计算动态设施，或将动态网格中心与静态表面中心
重合。

正确：Blender 生成命名节点 `TrafficSignalDynamic_<signal-id>_<state>`；浏览器在同一 model
matrix 下加载该 GLB，并只切换这些灯珠节点。倒计时 Entity 使用 `pose.countdown` 的经纬度、
高度、`faceHeadingDegrees` 生成与牌面相同的 ENU 坐标轴。