Files
road-compiler/.trellis/tasks/09-08-junction-reference-fidelity/implement.md
T

9.7 KiB
Raw Blame History

实施计划与阶段出口

当前为 in_progress;用户已批准实施。单一任务按串行里程碑交付;每阶段必须提交证据,不能以接口有返回代替效果验收。

0. 契约与最小反例

  • 审计 compiler/resolver 的归组、方向、沿线距离/半径、共享边与各图层裁切;核实 research/current-state.md 风险。
  • 写出 JunctionBuildPlan 字段、单位、引用完整性、歧义策略和兼容矩阵;确认现有 polygon 工具能力,必要时小型验证,不先扩展 UI。
  • 构造无需图片的反例:分隔双向进口、T 形闭合侧、偏置且不等宽交叉、曲线短进口;在旧实现上记录问题。
  • 出口:每个反例都有结构预期与几何不变量;任何样本 ID 专用分支均不接受。

1. 共享纯拓扑与接入计划

  • 统一重复归组;保存车行道和内部通路,不将不同通道按接近角度无条件合并。
  • 引入 EntrySection 契约、来源/推断信息和稳定键;BoundaryGraph 留待连续边界阶段实现。
  • 分离参考文件加载和纯 resolver;补输入重排、角度绕回、歧义、两路口隔离测试。
  • 出口 A1/A2 基础:3~6 臂和分隔组合均能产生可解释结构或明确不支持原因;已覆盖偏置、不等宽、规则与不规则角度分布、曲线短进口、输入重排、平移、旋转及跨 0° 绕回回归。

2. 连续边界与区域求解(最高风险)

  • 将复杂路口边界半径映射到来源折线的实际首次相交站点,并把同一车行道裁切传递给道路面、边线、中心线、人行道和车道发布线。
  • 为每条车行道生成带稳定边引用的内外断面,复杂进口面直接消费这些边;核心闭合边显式保留为待解,避免臆造跨分隔通行面。
  • 对每臂单一来源车行道,用入口内断面原始边闭合核心面并保持共享接缝;分隔/并行车行道无法确认中心通行关系时拒绝闭合并报告对象级诊断。
  • 实现接入断面到固定远端过渡;以共享边界构建中心/进口/角部,取消独立半径拼接作为权威。
  • 支持凹形与已知排除区域,检查环、自交、接缝、必要连接;设计边界可行域并由 solver/manifest 共用。
  • 审计 roadSurface、sidewalkSurface、edgeLines、lane/center markings 的每个裁切入口,确保消费同一计划。
  • 出口 A3:接缝≤1 cm,必要区域连通,无自交与排除区侵占;自动测试验证实际几何,不只是参数回显。
    • 已验证:3~6 臂核心环闭合、正面积、无自交、共享内边邻接;maxSharedSeamErrorMeters 已测量核心与入口内边端点的实际米制误差,尚不等同于全图层接缝测量;入口 ring 闭合/有限/正面积;短过渡、零长度边、零宽度和排除区相切均有失败回归。
    • 待完成:凹形/多区域/孔洞、全图层连通性和统一接缝误差测量。
  • 此阶段不通过,不开启新几何控件。

3. 通用局部校正闭环

  • 首个跨层契约:固定 cluster-carriageway-transition-length 的米制值、来源车行道 anchor、最小/最大可行域及旧文档兼容策略;在 solver 与编译器共享同一派生值后再开放客户端控件。

  • 贯通接入位置、方向、左右边界、过渡长度与归组覆盖的 validator/replay/solver/manifest/客户端。

  • 保留已有宽度/收口/圆角语义兼容,超出可行域明确重检,不发布 current 超出自身范围的正常可编辑手柄。

  • 输入和拖拽复用 EditSession;验证批量编辑已有约束、预览早于 Enter、请求乱序、切换路口、撤销重做、重置和 pending。

  • 出口 A4/A5/A7:两类结构在浏览器完成预览→保存→编译→刷新,并验证最终地图 source/几何与服务端一致。

4. 现有设施联动与缺失信息治理

  • 停止按夹角和道路宽度自动伪造角部导流岛与短斑马线;缺少岛体区域或步行连接来源时省略并报告原因。
  • 现有过街/停止线依附最终车行道;区分未知、已知存在、不支持。
  • 清理没有区域/连接依据的自动角部设施;对旧结果变化提供来源和诊断说明。
  • 验证已知排除区和独立通道未被核心铺装吞并,未知岛体不臆造。
  • 出口 A6;导流岛自由编辑与新右转通道创建留后续任务。

当前阶段收口

已完成并验证的通用底座:共享来源拓扑、3~6 臂结构矩阵、重排/平移/旋转稳定性、核心与入口边界不变量、排除区域保护、入口过渡状态诊断、设施来源证据、预览/保存/刷新基础回归及端到端工作台流程。

明确遗留:接入位置/方向/左右边界的完整编辑闭环(过渡长度本次补齐),凹形与多区域连通性,全图层接缝测量,真实 OSM 视觉验收。导流岛自由编辑和独立右转通道继续留在后续任务。

5. 通用性验收与发布

  • 测试矩阵:3/4/5/6 臂,正交/斜交/偏置,不等宽,单/双向和分隔,曲线/短进口,邻接多个路口,缺失/矛盾数据;至少覆盖组合交互,不只各单变量。
  • 变形测试:重排、平移、旋转(含跨 0°),允许范围内微调;对象身份稳定,几何无跳变。
  • 保留未参与调参的真实 OSM 用作外部验证;若仓库不具备则记录数据需求,不冒称真实泛化通过。
  • 生成纯效果/调试效果、几何指标、支持/拒绝情况、耗时及兼容报告;三组截图仅复核暴露的问题是否被通用机制处理。
  • 用户视觉验收合理初稿与局部校正结果;技术指标通过不能替代该验收。
  • 更新 spec,记录迁移和剩余能力;按当前用户提交授权执行提交,不假定授权发布或合并。

验证命令

按阶段运行针对性测试:node test/direct-edit-solver.js;node test/junction-structure.js;node test/junction-projection.js;node test/workbench-edit-api.js;新增纯拓扑/区域不变量测试纳入 npm test。

最终质量门:npm test、npm run test:client、npm run test:client:unit、npm run test:e2e、npm run format:check、git diff --check。需要本地端口的测试串行执行,避免 8899 冲突。命令失败时后续未执行的子测试不得报告通过。

关键文件与回滚点

complex-junction.js / native-road.js:构建与全部消费者;direct-edit-solver.js / native-road-edits.js:纯求解与兼容;junction-structure.js / junction-topology.js / junction-projection.js:身份及投影;server.js:预览保存一致性;App.tsx / ParameterPanel.tsx / MapCanvas.tsx / edit/*:输入和状态。

每个阶段独立可回滚。几何更换前保存原始文档和输出比较,禁止先更新 fixture baseline 掩盖差异。任何大幅缩减支持范围或迁移语义变更先更新规划供用户审阅。

过渡长度编辑交付记录

已接通过渡长度的文档回放、独立 solver 结果、沿来源折线的内部断面定位、客户端输入映射与手柄。外部接缝保持固定,独立于收口距离。API 验证实际长度、保存再读取重放;浏览器验证参数输入请求被应用。曲线进口有沿线长度回归。此交付不代表接入位置/方向/左右边界、全图层几何及真实数据视觉验收完成。

本次进一步修复路口面板保存按钮漏读 EditSession.dirty、缺少撤销重做入口、保存回调误用渲染计数导致白屏,以及长短进口没有共同范围时仍显示统一输入的问题。浏览器回归覆盖单独过渡长度输入、撤销、重做、保存重编译与刷新;后端覆盖拒绝的收口约束不影响有效过渡范围。保持父任务进行中,不将本次编辑闭环等同于全部几何验收完成。

本轮质量门:npm test 通过;npm run test:client 通过;npm run test:client:unit 15 文件/188 测试通过;npm run test:e2e(包含 production build)11 测试通过,包含保存后重置与放弃恢复;npm run format:check 与 git diff --check 通过。构建仍有既有 bundle 大小提示。遵循用户“整体任务完成再提交”,本轮未提交、未归档父任务。

下一阶段已实现共享内边的实际米制端点误差:sharedSeamErrors 逐车行道报告,缺失/非邻接为 Infinity;回归通过人为 2 米偏移验证指标变化。显式过渡站点统一限制在来源折线范围,超长请求标记来源长度不足并由 solver 拒绝。全图层接缝、凹形多区域和真实 OSM 视觉验收仍未完成。

共享入口断面消费交付记录

编译器现在只生成一次复杂入口 BoundaryGraph,外部道路面、边线、中心线、人行道、车道发布线的裁切直接读取其 outer.stationMeters;复杂过渡面复用同一图实例。过渡车道线按内外断面分别插值,局部展宽保持外侧车道端点固定,内部端点响应宽度与过渡长度。无效、来源长度不足或侵入已知排除区的过渡不发布预览车道线及其派生标线。

回归证据:真实 OSM fixture 的可配对外部道路面接缝实际误差 ≤1 cm;过渡车道起点与外断面一致;局部展宽保持外部道路面、边线、人行道、中心线和车道发布线不变;不可构建过渡不发布悬空预览车道线。npm test、客户端类型检查、188 项客户端单测、11 项浏览器测试、格式检查通过。

仍未关闭阶段 2:外侧偏移曲线的顶点切向统一、短道路被整体吞入路口时所有附属图层的发布一致性、角部步行带独立半径与 overrun 拼接、凹形/多区域/孔洞连通性仍需处理。当前回归证明了现有 fixture 的接缝,不冒称任意曲线与相邻多路口已全部满足 A3。父任务保持进行中。