# Parameterize junction geometry with optional Gaode reference

## Goal

验证一种通用的、参数化的路口几何生成范式：借鉴高德路口 GeoJSON 的规整边界和标线组织方式，
但保持 OSM/native compiler 对道路身份、连接关系、车道可行驶性、信号和停止线的权威性。
当前阶段先做一个可回滚的生产几何验证，不提交代码或产物。

## Requirements

- R1: native 路口在没有参考数据时行为不变，现有 OSM/native 输出仍是默认路径。
- R2: 支持可选的路口参考输入，至少记录输入路径、坐标来源（GCJ-02）和目标 OSM 路口关联方式。
- R3: 参考输入先转换为 WGS84；禁止将 GCJ-02 坐标直接与 OSM/native 几何叠加。
- R4: 参考数据只允许影响路口面的规整化参数、边界形态和标线布局；不得改变 OSM 道路、车道、connector、
  signal_uid、停止线归属或车辆路线拓扑。
- R5: 不机械复制高德 feature 的 `type=1..5`；先建立可审计的几何类别映射或只使用其可验证的形态特征。
- R6: 以“珠山湖大道（枫树二路）”路口作为验证样本，输出参考前后对比、偏差诊断和可回滚结果。
- R6.1: 生成器按路口拓扑选择模板，至少区分 cross、T 和复杂/多臂路口；不能用一个固定几何参数机械覆盖所有路口。
- R6.2: 首个生产几何验证只启用 cross 模板，利用参考样本校准 cutback、圆角和进口过渡；T/复杂路口先保留现有 native 行为并记录诊断。
- R6.3: 模板生成的路口面必须由 OSM/native 道路宽度、方向和车道结构驱动；高德几何只用于校准参数或对比，不直接复制其 feature。
- R7: 参考文件缺失、坐标转换失败、无法关联 OSM 路口或几何越界时，构建必须回退默认 native 算法并给出诊断，
  不得静默覆盖生产几何。
- R8: 保持当前阶段 manifest、GLB/package 契约和无参考区域的 parity 行为不变。

## Acceptance Criteria

> 措辞修订说明见文末「Scope Drift」。勾选项均为 2026-08-21 实测，证据记录在「Verification Log」。

- [x] 不配置参考输入时，现有 native-road 测试和样本区域输出保持默认行为。
- [x] 配置枫树二路参考后，能稳定关联 OSM node `8005332807`，并生成 WGS84 参考诊断。
- [x] 参考几何与 native 路口的叠加结果可检查：路口中心、边界、进口方向有数值和 SVG 记录。
- [x] 参考模式不改变 OSM 衍生的 connector、车道连接、信号或停止线集合；模板只新增自有
      `complex-*` 命名空间要素。（原措辞「不会新增或删除…停止线」严于 R4 本意，已修订）
- [x] 参考模式失败时有明确 warning，并成功回退默认 native 几何。
- [x] 模板生成的路口面视觉上接近高德参考。connector / 信号 / 停止线集合一致性已实测通过；
      视觉接近度由用户 2026-08-21 在工作台确认（「基本 ok」），其间提出的人行道转角缺口已修复并复核通过。
- [x] 无参考路口继续走默认 native 几何，不被模板误套。
- [x] 验证产物写入区域输出目录，未执行 git commit。（源 OSM 有改动，但来自人工 JOSM 编辑，
      非管线写入；原措辞未区分这两者，已修订）

## Scope Drift（2026-08-21 记录）

R6.2 原定「首个生产几何验证只启用 cross 模板；T/复杂路口先保留现有 native 行为」。
实际实现走的是 `complex-junction-v1`，对枫树二路 4 节点簇做整体路口面、斑马线、停止线、
角部安全岛和圆角生成。范围已越过 R6.2，本文档据实修订，R6.2 视为被本次决策取代。
cross 模板（`cross-v1` / `cross-cluster-v1`）代码路径仍在，未被删除。

## Verification Log（2026-08-21）

参考模式 A/B 对照（同一 OSM 输入，`junctionTemplates.enabled` 开/关，独立 outputRoot）：

| 指标 | ON | OFF | 判定 |
| --- | --- | --- | --- |
| connector 要素 | 356 | 356 | 集合逐一相同，无新增/缺失 |
| movement / published | 370 / 356 | 370 / 356 | 一致 |
| connection | 215 | 215 | 一致 |
| 信号 uid 集合 | 20 | 20 | 集合完全一致 |
| 普通斑马线 `native-road-crosswalk/v1` | 6 | 6 | 一致 |
| 模板新增 `complex-crosswalk` | 128 | 0 | 模板自有命名空间 |
| 模板新增 `complex-corner-crosswalk` | 24 | 0 | 同上 |
| 模板新增 `complex-stop-line` | 4 | 0 | 同上 |
| 预览车道 `cluster-approach-lane` | 24 | 0 | 同上 |

参考关联与叠加（`npm run reference:junction`）：

- 匹配方式 `node-id`，命中 `8005332807`，参考中心到节点 **8.98 m**
- 匹配到 `complex-cluster` = `zhushanhu-fengshu-complex`，13 个要素
- native core 半径 **24 m**（配置 `coreRadiusMeters: 28`），进口 4 / 车行道 8，
  进口朝向 `[-118.5, -28, 62.2, 151.9]`
- 已知口径差异：检查工具用参考文件**全部** feature 算 bounds（约 380×330 m，含长引道），
  而 `readReferenceCalibration` 只取 `type ∈ [1,2,3,4]` 的子集。两者不同量级，
  故 bbox IoU（0.070）当前**不是**可用的质量指标，仅中心偏差和朝向可比。

失败回退（`referenceFile` 指向不存在路径）：

- 编译成功不抛错；诊断由 `complex-junction-reference-calibrated` 降级为 `complex-junction-generated`
- connector 356 / movement 370 不变
- 该路径下 `lane-centerline-fully-inside-control` 触发 10 次：无参考时 coreRadius 仅 14.56 m，
  10 条车道整体落在控制带内，回退为未裁剪发布。非回归（改动前同样未裁剪），但属已知限制。

非簇路口未受模板影响（A/B `intersection_surface`）：

| | ON | OFF |
| --- | --- | --- |
| 普通路口面总数 | 41 | 45 |
| 簇成员节点出现次数 | 0（预期 0） | 4（模板关闭时预期 4） |
| 非簇节点（41 个） | — | 与 ON 逐点几何完全一致，无增无缺 |
| 模板 `complex_part` 要素 | 13，全部归属唯一簇 `zhushanhu-fengshu-complex` | 0 |

结论：模板严格限定在 `nodeIds` 列表内，无外溢。

## Known Gaps（2026-08-21）

1. `way/858770823:segment/2`（长 19.2 m，远端为 service 路口 `8613058676`）被 `native-road.js`
   的 cluster 丢弃判据误伤，整段无路面，该节点周边 25×25 m 内 25.8% 露底。
   判据应从「远端在 outerRadius 内」改为「远端也是 cluster 成员节点」，实测该判据分界干净。
   **用户 2026-08-21 明确暂缓，未修改。**
2. `coreRadiusMeters` 在有参考文件时不参与计算（被 calibration 覆盖并 clamp 到 24）。
   已加诊断 `complex-junction-configured-radius-ignored` 使其可见，行为未改。
3. `approachLengthMeters` 对 `complex-junction-v1` 无效（仅 `cross-v1` / `cross-cluster-v1` 使用）。
   死函数 `clusterApproachRing` 已删除。
4. 无参考路径下普通停止线为 0（`crossing-no-safe-stop-line` 告警 1 条），先于本任务存在。


## Constraints And Deferred Scope

- OSM WGS84 与 native 拓扑是交通语义的单一事实源。
- 高德参考暂不作为完整道路网络输入，也不直接替代 road surface 或 connector 几何。
- 暂不定义所有高德 `type` 值的业务语义；先验证几何范式和校准边界。
- 暂不提交代码、配置或生成产物；本阶段完成后由用户决定是否进入正式实现。