osmWorkflow/.trellis/tasks/archive/2026-08/08-19-gaode-junction-reference/prd.md

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」。

• 不配置参考输入时，现有 native-road 测试和样本区域输出保持默认行为。
• 配置枫树二路参考后，能稳定关联 OSM node 8005332807，并生成 WGS84 参考诊断。
• 参考几何与 native 路口的叠加结果可检查：路口中心、边界、进口方向有数值和 SVG 记录。
• 参考模式不改变 OSM 衍生的 connector、车道连接、信号或停止线集合；模板只新增自有 complex-* 命名空间要素。（原措辞「不会新增或删除…停止线」严于 R4 本意，已修订）
• 参考模式失败时有明确 warning，并成功回退默认 native 几何。
• 模板生成的路口面视觉上接近高德参考。connector / 信号 / 停止线集合一致性已实测通过； 视觉接近度由用户 2026-08-21 在工作台确认（「基本 ok」），其间提出的人行道转角缺口已修复并复核通过。
• 无参考路口继续走默认 native 几何，不被模板误套。
• 验证产物写入区域输出目录，未执行 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 值的业务语义；先验证几何范式和校准边界。
• 暂不提交代码、配置或生成产物；本阶段完成后由用户决定是否进入正式实现。