# 实施计划与阶段出口 当前为 in_progress;用户已批准实施。单一任务按串行里程碑交付;每阶段必须提交证据,不能以接口有返回代替效果验收。 ## 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] 对每臂单一来源车行道,用入口内断面原始边闭合核心面并保持共享接缝;分隔/并行车行道无法确认中心通行关系时拒绝闭合并报告对象级诊断。 - [ ] 实现接入断面到固定远端过渡;以共享边界构建中心/进口/角部,取消独立半径拼接作为权威。 - [ ] 支持凹形与已知排除区域,检查环、自交、接缝、必要连接;设计边界可行域并由 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. 现有设施联动与缺失信息治理 - [x] 停止按夹角和道路宽度自动伪造角部导流岛与短斑马线;缺少岛体区域或步行连接来源时省略并报告原因。 - [ ] 现有过街/停止线依附最终车行道;区分未知、已知存在、不支持。 - [ ] 清理没有区域/连接依据的自动角部设施;对旧结果变化提供来源和诊断说明。 - [ ] 验证已知排除区和独立通道未被核心铺装吞并,未知岛体不臆造。 - [ ] 出口 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、缺少撤销重做入口、保存回调误用渲染计数导致白屏,以及长短进口没有共同范围时仍显示统一输入的问题。浏览器回归覆盖单独过渡长度输入、撤销、重做、保存重编译与刷新;后端覆盖拒绝的收口约束不影响有效过渡范围。保持父任务进行中,不将本次编辑闭环等同于全部几何验收完成。 ## 接入边界手柄几何交付记录 复杂车行道左右边界手柄现统一发布向右法线,由客户端仅对左侧反转一次,修复左边界向外拖反而收窄。手柄位置使用与 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 矩阵中补齐。 本轮同时修复成功闭合且接缝合格的核心仍被误报为 `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。排除区回归覆盖实际生成的道路圆角和人行道转角。 此处采用明确省略冲突对象,尚未实现绕排除区域重新求解、孔洞或多区域连通;不能据此关闭 A3/A6。下一步需建立区域级共享边界与连通性验证,再推进剩余接入位姿/左右边界编辑,最后做真实数据视觉验收。 本轮验证:npm test、客户端类型检查、188 项客户端单元测试、11 项 E2E(含生产构建)、format:check 与 git diff --check 全部通过。构建保留既有 bundle 大小提示。