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

181 lines
23 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 实施计划与阶段出口
当前为 in_progress;任务已收敛为分阶段推进。第一个新阶段是“复杂路口区域模型”:先统一中心通行区、角部可行域和安全岛边界,再恢复设施与视觉验收。实验性固定安全岛修改已保存至 `/private/tmp/junction-island-experiment.patch`,不作为正式方案。
## 0. 契约与最小反例
- [x] 审计 compiler/resolver 的归组、方向、沿线距离/半径、共享边与各图层裁切;核实 research/current-state.md 风险。
- [x] 写出 JunctionBuildPlan 字段、单位、引用完整性、歧义策略和兼容矩阵;确认现有 polygon 工具能力,必要时小型验证,不先扩展 UI。
- [x] 构造无需图片的反例:分隔双向进口、T 形闭合侧、偏置且不等宽交叉、曲线短进口;在旧实现上记录问题。
- [x] 出口:每个反例都有结构预期与几何不变量;任何样本 ID 专用分支均不接受。
## 1. 共享纯拓扑与接入计划
- [x] 统一重复归组;保存车行道和内部通路,不将不同通道按接近角度无条件合并。
- [x] 引入 EntrySection 契约、来源/推断信息和稳定键;BoundaryGraph 留待连续边界阶段实现。
- [x] 分离参考文件加载和纯 resolver;补输入重排、角度绕回、歧义、两路口隔离测试。
- [x] 出口 A1/A2 基础:3~6 臂和分隔组合均能产生可解释结构或明确不支持原因;已覆盖偏置、不等宽、规则与不规则角度分布、曲线短进口、输入重排、平移、旋转及跨 0° 绕回回归。
## 2. 连续边界与区域求解(最高风险)
- [x] 将复杂路口边界半径映射到来源折线的实际首次相交站点,并把同一车行道裁切传递给道路面、边线、中心线、人行道和车道发布线。
- [x] 为每条车行道生成带稳定边引用的内外断面,复杂进口面直接消费这些边;核心闭合边显式保留为待解,避免臆造跨分隔通行面。
- [x] 对每臂单一来源车行道,用入口内断面原始边闭合核心面并保持共享接缝;分隔/并行车行道无法确认中心通行关系时拒绝闭合并报告对象级诊断。
- [x] 实现接入断面到固定远端过渡;以共享边界构建中心/进口/角部,取消独立半径拼接作为权威。
- [x] 支持凹形与已知排除区域,检查环、自交、接缝、必要连接;设计边界可行域并由 solver/manifest 共用。
- [x] 审计 roadSurface、sidewalkSurface、edgeLines、lane/center markings 的每个裁切入口,确保消费同一计划。
- [x] 出口 A3:接缝≤1 cm,必要区域连通,无自交与排除区侵占;自动测试验证实际几何,不只是参数回显。
- 已验证:3~6 臂核心环闭合、正面积、无自交、共享内边邻接;maxSharedSeamErrorMeters 已测量核心与入口内边端点的实际米制误差,尚不等同于全图层接缝测量;入口 ring 闭合/有限/正面积;短过渡、零长度边、零宽度和排除区相切均有失败回归。
- 连通性现作为构建产物显式发布:`connectedEntryCount`、`requiredPavementConnected`、`ringArea` 和 `ringSelfIntersects`;安全孔洞回归验证孔洞保留时全部入口仍与核心相连。
- 限定:当前支持安全孔洞与已知排除区;无法确认多个机动车通行区域时对象级拒绝闭合。全图层共享接入断面已验证,暂无任意曲线、多区域自动重求解承诺。
- [ ] 此阶段不通过,不开启新几何控件。
## 3. 通用局部校正闭环
- [ ] 首个跨层契约:固定 `cluster-carriageway-transition-length` 的米制值、来源车行道 anchor、最小/最大可行域及旧文档兼容策略;在 solver 与编译器共享同一派生值后再开放客户端控件。
- [x] 贯通接入位置、方向、左右边界、过渡长度的 validator/replay/solver/manifest/客户端;归组覆盖沿用稳定来源节点集合并触发版本保护。
- [x] 保留已有宽度/收口/圆角语义兼容,超出可行域明确重检,不发布 current 超出自身范围的正常可编辑手柄。
- [ ] 输入和拖拽复用 EditSession;验证批量编辑已有约束、预览早于 Enter、请求乱序、切换路口、撤销重做、重置和 pending。
- [ ] 出口 A4/A5/A7:两类结构在浏览器完成预览→保存→编译→刷新,并验证最终地图 source/几何与服务端一致。
## 4. 现有设施联动与缺失信息治理
- [x] 停止按夹角和道路宽度自动伪造角部导流岛与短斑马线;缺少岛体区域或步行连接来源时省略并报告原因。
- [x] 现有过街/停止线依附最终车行道;区分未知、已知存在、不支持。缺少匹配 OSM crossing 节点时不生成复杂斑马线或退让手柄,停止线独立保留并标记 `unknown-no-crossing-source`。
- [x] 清理没有区域/连接依据的自动角部设施;对旧结果变化提供来源和诊断说明。
- [x] 验证已知排除区和独立通道未被核心铺装吞并,未知岛体不臆造。
- [ ] 出口 A6;导流岛自由编辑与新右转通道创建留后续任务。
## 当前阶段收口
已完成并验证的通用底座:共享来源拓扑、3~6 臂结构矩阵、重排/平移/旋转稳定性、核心与入口边界不变量、排除区域保护、入口过渡状态诊断、设施来源证据、预览/保存/刷新基础回归及端到端工作台流程。
明确遗留:接入位置/方向/左右边界的完整编辑闭环(过渡长度本次补齐),凹形与多区域连通性,全图层接缝测量,真实 OSM 视觉验收。导流岛自由编辑和独立右转通道继续留在后续任务。
## 5. 通用性验收与发布
- [x] 测试矩阵:3/4/5/6 臂,正交/斜交/偏置,不等宽,单/双向和分隔,曲线/短进口,邻接多个路口,缺失/矛盾数据;至少覆盖组合交互,不只各单变量。
- [x] 变形测试:重排、平移、旋转(含跨 0°),允许范围内微调;对象身份稳定,几何无跳变。
- [x] 保留未参与调参的真实 OSM 用作外部验证;若仓库不具备则记录数据需求,不冒称真实泛化通过。
- [x] 生成纯效果/调试效果、几何指标、支持/拒绝情况、耗时及兼容报告;三组截图仅复核暴露的问题是否被通用机制处理。
- [ ] 用户视觉验收合理初稿与局部校正结果;技术指标通过不能替代该验收。
- [ ] 更新 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、缺少撤销重做入口、保存回调误用渲染计数导致白屏,以及长短进口没有共同范围时仍显示统一输入的问题。浏览器回归覆盖单独过渡长度输入、撤销、重做、保存重编译与刷新;后端覆盖拒绝的收口约束不影响有效过渡范围。保持父任务进行中,不将本次编辑闭环等同于全部几何验收完成。
## 接入边界手柄几何交付记录
复杂车行道左右边界手柄现统一发布向右法线,由客户端仅对左侧反转一次,修复左边界向外拖反而收窄。手柄位置使用与 BoundaryGraph 相同的有效内断面站点 `outer - transition + position`,并消费当前方向、有效宽度及各侧边界偏移;左右手柄不再重叠,曲线进口和过渡长度变化后仍落在实际编辑断面。
回归按米制测量左右手柄间距、地理侧别、过渡断面对齐以及位置/方向响应;客户端覆盖两侧向外展宽、向内收窄、约束值、ghost 位置和边界钳制。npm test、190 项客户端单测、类型检查、生产构建、11 项 E2E、format:check 与 git diff --check 通过,构建仅保留既有 bundle 大小提示。
方向控件仍以沿切线的线性拖动米数映射角度,且位置/方向自身手柄仍显示旧收口点。完整旋转交互需要单独明确手柄契约,本轮不据此关闭 A4/A5。
后续已补齐该缺口:方向手柄发布有效内断面中心和旋转半径,客户端按最短方位角变化生成 `offsetDegrees`,ghost 沿圆周移动并显示角度;位置、方向和宽度手柄统一使用有效内断面。左右边界范围由有效宽度、另一侧偏移和最小车道总宽共同推导,manifest 与 solver 共用端点且越界阻塞。兼容数值输入及既有 `offsetDegrees` 文档。
浏览器回归现逐项编辑接入位置、方向和左右边界,验证请求被应用且目标道路面实际变化,并逐项撤销;随后继续验证过渡长度保存、正式重编译和刷新重放。该证据覆盖当前真实工作台 fixture,第二类结构的浏览器闭环仍需在最终 A4 矩阵中补齐。
第二类浏览器证据现使用 E2E 专用的独立三臂短节点簇:候选检测、接受、3 臂结构投影、位置/方向/左右边界/过渡长度预览、实际道路面变化、逐项撤销、保存重编译和刷新回放均通过。测试同时允许当前页面已同步版本时直接保存,或 API 外部接受候选造成 409 后显式重试;两种顺序最终产物一致。完整 E2E 为 12/12 通过。
第二真实候选审计发现一个两内部节点 cluster 会产生 solver 手柄但无法投影 `junctionStructure`。工作台状态与预览现统一隐藏此类无权威结构的手柄,并有 API 回归;该候选不再被错误计作第二类浏览器验收。A4 的第二类证据将使用具有完整结构投影的独立 3/4 臂 fixture。
本轮同时修复成功闭合且接缝合格的核心仍被误报为 `complex-junction-core-closure-unsupported` 的条件分支。npm test、191 项客户端单测、类型检查、生产构建、11 项 E2E、format:check 与 git diff --check 通过。区域邻接和排除区共同决定的更大向外边界仍留给区域级求解,不用固定范围冒充完整可行域。
本轮质量门: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:外侧偏移曲线的顶点切向统一、凹形/多区域/孔洞连通性仍需处理。当前回归证明了现有 fixture 的接缝,不冒称任意曲线与相邻多路口已全部满足 A3。父任务保持进行中。
## 附属图层与已知排除区域发布约束
`79f2ee5` 已将角部人行道端点接到实际发布的外部人行道完整接缝,并覆盖带人行道的非空 fixture;短道路的道路边线、中心线、车道标线和人行道遵循道路面的发布集合。
本轮进一步补齐两个遗漏:角部道路补面、人行道转角复用 BoundaryGraph 的区域相交判定,侵入已知排除区域时省略并给出角部对象级诊断;复杂过街仅在所属道路臂全部车行道过渡面有效时发布,避免短道路已经无效却继续输出斑马线。短道路回归现在包含 crosswalks、vehicleStopLines 以及缺接缝诊断的对象和来源 ID。排除区回归覆盖实际生成的道路圆角和人行道转角。
用户复核指出探出分支不应自动出现斑马线。本轮收紧设施证据:道路包络和推断停止线不再充当过街存在证据;只有与道路和位置匹配的 OSM crossing 节点才生成复杂斑马线并发布 `cluster-crossing-inset`。无来源进口输出 `complex-junction-crossing-source-missing`,停止线保留但不消费不存在的退让值。单元与工作台 API 同时覆盖无来源省略和有来源编辑,且 solver 与 manifest 共用来源搜索半径,保证已发布手柄的最大值可实际应用。当前真实 fixture 的验证指标由 5 个过街手柄降为 0,纯效果图确认探出分支无斑马线。
此处采用明确省略冲突对象,尚未实现绕排除区域重新求解、孔洞或多区域连通;不能据此关闭 A3/A6。下一步需建立区域级共享边界与连通性验证,再推进剩余接入位姿/左右边界编辑,最后做真实数据视觉验收。
本轮验证:npm test、客户端类型检查、188 项客户端单元测试、11 项 E2E(含生产构建)、format:check 与 git diff --check 全部通过。构建保留既有 bundle 大小提示。
## 斑马线短边构造修正(未提交)
用户手绘明确:两条相邻斑马线向各自路口外侧退一个完整矩形短边长度;安全岛两条直角边来自斑马线短边延长线,不来自道路圆角切线。短边延长一倍,连接端点并向直角顶点弯曲,第三组条纹平行于连接弦。
已修复此前无效退让:旧代码移动 frame.center 后又用原 endpoints 覆盖,实际条带未移动。现在先移动中心再生成端点;手柄同步。岛体使用最近端点处的两条短边延长线交点及两倍 groupDepth;岛体弧线纯函数覆盖手绘象限、边界相接无面积重叠、旋转平移回归。
当前用户 OSM 编译实测:4 个岛体,跨组斑马线重叠面积 0 m²,岛体与条带总交集约 0.00004524 m²。纯几何图为 references/crossing-short-edge-composition.png(编译坐标直接绘制,仅含目标复杂路口道路面/岛体/斑马线)。中央铺装仍存在空洞,整体任务未完成。此次未提交,不能将上述局部通过记作 A3/A8 全部通过。
## 用户暂存后的白条规格与正交框架调整
本轮保留用户 index 暂存内容,新变更只在工作区。所有复杂斑马线白条长度 3.4m、宽度 0.42m、净间隔 0.4m;端部余量居中分配,不再通过缩放间隔填满跨度。四臂且每臂与拟合正交方向偏差不超过 15°时,斑马线方向共用正交框架;其他结构保留来源方向。岛体继续引用斑马线短边,手柄使用同一退让方向。
当前用户 OSM 实测:4 岛,142 白条;跨组过街重叠面积 0m²,岛体与过街交集面积 0m²。references/orthogonal-crossing-composition.png 是编译几何简图,不是浏览器整图验收。中心铺装空洞仍未解决。
## 弧边贴合、三个圆角、停止线避让
第三组第一条白条按其实际宽度范围内的岛体曲线支撑位置放置,去掉首条居中余量,避免以弦代替弧造成间隙。岛体三个顶点使用曲线过渡,保留直边和中部内弯弧。停止线与手柄加入斑马线已发生的完整退让量。
当前 OSM 测量:停止线/斑马线面积交集 0;跨组斑马线面积交集 0;岛/斑马线约 1e-13 m²(浮点误差)。新增圆角、有限条宽弧边支撑、停止线与对应斑马线无交集回归。references/rounded-corner-detail.png 为局部编译几何图,黄色仅用于标示停止线;正式渲染颜色未改变。未提交、未改用户暂存内容。
### 本轮局部复核补充
复核修正一处遗漏:过街手柄虽然已计算四臂拟合方向,实际固定退让仍用了原道路臂方向;现使用同一 fitted heading。纯设施测试、direct-edit-solver、format:check、客户端类型检查通过。
停止线默认值 3m 在当前图上无交集,但不能据此宣称完整可编辑范围无重叠:将当前真实路口各 stopLineOffsetMeters 设为已允许的 0.5m,实际编译产生 47 对停止线/对应白条交集。需统一停止线退距的边界语义/可行域与手柄,再增加下界回归;复核未擅自更改文档参数语义。
上述下界问题已由主会话同步修正为距过街外缘的净退距,并包含停止线半厚度;复核重跑同一真实 OSM、相同 0.5m 参数,交集对数从 47 降为 0。此为当前真实样本验证,非任意斜交结构全范围保证。
停止线补充:按拟合斑马线方向放置,从退让后的斑马线外缘计净距,并计入停止线半厚 0.24m;编辑手柄同步。新增 0.5m 下界与对应过街无交集回归。当前真实 OSM 全部停止线/过街交集为 0。旧五臂 fixture 在最小退距时与非对应过街仍有少量交集,跨臂极端编辑避让尚未完成,不能外推为任意拓扑无冲突。
预览 API 单独重跑通过;之前 degraded 断言失败源于其 300ms 时间预算,不能将其解释为几何功能失败。全量 fixture 基线仍与用户更新后的 OSM 不一致,未刷新基线。此次未暂存、未提交。
## 2026-09-11 基线提交与新增完整接触规则
用户要求先提交当前视觉基线,已执行。随后补充的五条规则已写入 PRD、design 与 backend/junction-island-contact.md。此次补充为待实现契约,不声称已有代码满足完整短边接触或绿色六边形。下一实现单元:三段完整接触的共享求解 + 六点绿色区域 + 动态腿长,一起验证后交付;不得拆成独立挪动第三条斑马线、独立画绿色六边形的中间态。
## 完整接触求解实现(工作区,待提交)
新增 `solveIslandContacts`,复杂路口现在消费同一结果生成动态直角边、圆滑外轮廓和六点 `greenRing`;第三组斑马线中心也由该结果定位。前端以 `kind=island-green` 显示绿色六边形。真实 OSM 输出 4 个岛且每个都有 6 个接触点,相关重叠检查为 0。新增纯几何回归覆盖端点数量和动态腿长。尚未提交。
## 2026-09-14 四角协调与实际工作台配置复现(未提交)
实际最新导入工作区 import-fE8XI7 使用四节点、coreRadius=21;此前验证脚本硬编码五节点、24,漏掉真实失败。已复现两个 contact-crosses-corner 导致两岛省略。四臂过街现在在发布前共同检查相邻接触短边;必要时对称缩短所有过街跨度,以完整白条节距进行裁减,保留白条长度/宽度/间隔。找不到满足最小过街跨度的方案时不应用试探裁减,保留不可行诊断。未改保存配置或用户编辑。
实际配置现在发布四岛、四绿色六边形,各六个唯一点,面积约 19.49–28.70m²。新增真实 OSM 四节点 21m 回归检查四角对象、六点及岛体引用。references/four-islands-coordinated.png 为编译几何整图(黄色停止线用于辨识),非浏览器截图。接触交集约 4.2e-5m²、中心铺装缺口仍待解决;不能声称严格共享边界或整体验收完成。前序“六点数量通过即完整接触完成”的说法不成立。
## 2026-09-14 中心铺装与集群车辆轨迹(未提交)
按 research/core-and-trajectories-audit.md 实施。中心闭合改为每条有效车行道保留完整断面,按断面而非散点排序;多车行道内断面交叠产生自交时,对中心与边界形成的局部铺装单元做区域并集,不使用凸包,也不删除某条车行道。内接缝可成为并集内部线段,需逐边界交点拆分验证整段覆盖,随后与权威 BoundaryGraph 断面测量位置误差。原“必须缺失 core”断言改为连续区域验收;已有 T/五/六臂和排除区域反例仍通过。实际四节点、21m 配置生成中心面,8/8 入口接通,接缝误差0,四岛和绿色区域保持。
车辆轨迹先统一为端点切向 cubic 与自适应采样,随后实际叠加图证明原节点 connector 仍是局部碎片。因此继续增加集群级拼接:在原有允许的 lane movement 图上逐入口 BFS,追溯内部车道到外部出口,保留来源 movement IDs,遵守车道方向和默认目标车道对应关系。端口引用实际可见 approach lane(出口预览线按行驶方向反转)。用有限控制柄候选求曲线;检查整条发布折线的自交、与安全岛边相交、是否逐段落在真实铺装区域内。替代原四节点碎片;不可行候选明确诊断 deferred-region-conflict,不伪造可行轨迹。尚未提供车辆扫掠包络或曲率连续性保证。
实测与测试:中心8个入口全连通;集群28条发布完整路径,8条区域冲突暂缓。28条全部匹配可见车道端点,0条因端点缺失而跳过;最大端点切向误差0.9898度。合成T/四臂最大误差0.9807度。新 test/connector-trajectories.js 纳入 npm test。references/core-and-trajectories.png/svg 为实际配置编译几何叠加图(蓝线轨迹,黄色停止线),非浏览器截图。
npm test 中代码、投影、边界反例、设施、编辑与工作台导入检查通过;最后 test/fixtures.js 快照仍失败(当前 OSM 与旧基线不同,且本次轨迹几何也会改变输出),未刷新基线,因此不得写为全量测试通过。格式与diff检查通过。8条暂缓路径、车辆尺度转弯半径/扫掠、全图层接缝及已有岛/斑马线约4.2e-5m²微小面积交集尚未关闭。未提交、未归档。