# Validation Implementation Plan

进度标记于 2026-08-21。

1. [x] Add a read-only reference inspection utility or library helper that validates GeoJSON,
   converts GCJ-02 to WGS84, computes bounds/center, and associates the sample with OSM node
   `8005332807`. — `scripts/lib/gaode-junction-reference.js` + `scripts/inspect-junction-reference.js`
2. [x] Add focused tests for coordinate conversion, malformed input rejection, spatial association,
   and the no-reference fallback. — `npm run test:gaode-junction-reference`
3. [x] Add a diagnostic comparison between the reference footprint and native
   `intersection_surface.geojson`, including center offset, envelope overlap, and approach headings.
   — 复杂路口的面写在 `road_surface.geojson`（`complex_part`）而非 `intersection_surface`，
   原实现匹配不到、恒返回 `nativeIntersection: null`。已扩展为可回落到复杂路口簇
   （新增 `--native-road-surface` / `--cluster-id`，schema 升至 v2）。
4. [x] Add a reference-backed, parameterized junction template and dispatch it only for
   explicitly enabled samples. — 实际实现为 `complex-junction-v1`，非原计划的 cross 模板，
   范围变更见 prd.md「Scope Drift」。
5. [x] Preserve connector, movement, signal, and stop-line generation; validate containment against
   the new surface. — A/B 实测通过，数据见 prd.md「Verification Log」。
6. [x] Run native-road, preflight, preview-traffic, and package-contract tests, plus the sample
   comparison. Inspect the generated overlay/diagnostic manually.
   — 2026-08-21 全绿：`test:gaode-junction-reference`、`test:native-road`、`test:road-workbench`、
   `test:preflight`、`test:native-preview-traffic`、`test:package-contract`、`test:traffic-signals`，
   外加 `road:check` → `ok: true, errors: []`。人工视觉确认仍待用户。
7. [x] Stop at validation. Do not commit,
   and do not modify the source OSM or reference GeoJSON. — 未 commit；参考 GeoJSON 未改；
   源 OSM 有改动但来自人工 JOSM 编辑，非管线写入。

## 本次会话追加的修复（2026-08-21）

- 车道中心线与车道标线越过斑马线：`compileLaneCenterlines` 现接收模板已产出的斑马线/停止线，
  新增 `trimLaneOutsideControls`（按到路口中心的半径定向后再裁剪，因为车道几何两种朝向都存在）。
  拓扑几何 `coordinates` 保持完整，仅裁剪发布几何与标线源几何。
  实测越线要素 20 → 0，分隔线越界 2 → 0，connector 356 / movement 370 前后一致。
- 新增诊断 `complex-junction-configured-radius-ignored`、`lane-centerline-fully-inside-control`。
- 删除死函数 `clusterApproachRing`。
- **复杂路口人行道转角**（`complex-junction.js`）：直条带被裁在簇边界后，相邻两臂的步行带
  各自留一个断头，中间整个楔形无覆盖。现沿圆角已定义的路缘补一条 2 m 宽转角带。
  - 复用同一函数作用域内已算好的 `curve` / `tangents` / `edges` / `apex`，不重新拟合曲线
  - 新增 `armCarriesSidewalk`（按臂的外向方向翻转道路自身的 `sidewalkLeft/Right`）、
    `edgeRunToRadius`、`offsetPolylineAwayFromCenter`、`ringSelfIntersects`
  - 经 `islands` 通道并入 `generatedComplexSidewalks`
  - 自交或几何无效时跳过并报 `complex-junction-sidewalk-corner-fallback`，不硬塞坏几何
  - 实测：人行道要素 7 → 8；生成角 1（平分线 286°，241°→331°，57 顶点）；无自交；
    与两侧条带均相接；面积采样 331 点中 0 点落在车行道内
  - **限制**：全区 139 条路仅 3 条带人行道，4 个角中只有 286° 两侧齐备，
    其余 3 个角当前不产出，缺少验证样本

## Rollback Points

- Delete/disable the optional reference configuration to restore the default native path.
- Remove only the reference diagnostic output; existing native-road outputs remain authoritative.
- Do not overwrite existing layers until the comparison is accepted.