Files

5.6 KiB

复杂路口生成器结构整理

用户于 2026-09-16 确认实施代码审阅提出的结构重构。

边界与设计

现有 buildComplexJunctionGeometry 超过千行,阶段之间依赖 arm 上的可变字段和共享集合。本轮将入口整理为可读的阶段编排,抽取进口、过街布局、角部组合、位移联动和结果装配;角部组合继续拆出有明确职责的局部函数。阶段输入输出显式传递,避免通用可变 context。

实现范围为 src/compile/complex-junction.js 及必要的同目录内部模块。保留公开导出、运算顺序、坐标、Feature 顺序、ID、诊断和失败路径。清理本轮相关的无用变量、导入和过时注释;诊断内容不在此次改变。复用既有几何求解模块,不引入框架或新的配置机制,不改 UI 或几何算法。

验证计划

  1. 保存重构前生成器,对实际测试输入逐次深比较完整返回值。
  2. 运行现有几何、编辑及完整 npm test 回归;既有失败需与基线区分,禁止刷新快照隐藏差异。
  3. 运行格式、客户端类型及 git diff --check;审阅阶段依赖和失败路径。
  4. 记录重构结果与验证证据,不关闭父任务的其他未完成验收。

实现与差分结果

生产修改仅位于 src/compile/complex-junction.js。主函数从 1021 行缩为约 159 行;同文件私有函数分别承担阶段编排及单个设施构建,最大新函数约 115 行。没有新增公开导出或依赖。删除两个无用导入和两项无用坐标计算;保留历史诊断并注明其兼容性原因。

差分工具最初位于 /private/tmp/complex-junction-refactor-parity.cjs,现保留在同目录 geometry-refactor-parity.cjs。用 Node Module 加载基线提交 1679d1b 的生成器,将每次实际调用的输入复制后交给旧函数,再对完整返回值执行 assert.deepStrictEqual。45 次比较全部一致:主测试流 41 次,单独 island-offset 测试 4 次(其中 3 次非零外移)。覆盖正交、偏置十字、T 形、多臂和节点不足返回,以及无效断面、短过渡、排除区、岛体求解失败、核心闭合失败、过街编辑等诊断路径。

检查结果:

  • npm test 的代码、几何、编辑、API、工作台导入检查通过,最后 test/fixtures.js 失败。该快照差异在重构前已单独复现,重构后输出哈希相同;未刷新基线。
  • node --require /private/tmp/complex-junction-refactor-parity.cjs test/junction-island-offset.js 通过。
  • 客户端类型检查、191 项客户端单测通过。
  • 本次源文件格式和 git diff --check 通过。全仓 format:check 在未修改的 junction-facility-composition.js 失败;对 HEAD 原文运行 Prettier 同样失败。
  • npm run test:e2e 通过:生产构建及 12 项浏览器回归,包含三臂复杂路口控制编辑、保存和刷新。保留既有 bundle 大小提示。
  • 独立代码复核通过,无新增修复:核对角部失败依赖、Feature/诊断顺序、共享过街位移和停止线联动。

本轮未提交,父任务保持进行中。历史“角部设施已省略”诊断与实际默认生成行为的矛盾保留为单独行为修正事项。

后续模块边界评估(2026-09-16)

阶段编排已经从入口函数中抽出,但 complex-junction.js 仍保留了局部米制计算、道路臂包络、圆角相交、人行道接缝和环验证等无状态几何代码,导致文件仍有 1685 行。它们不依赖构建阶段、Feature 发布或诊断顺序,已迁入 complex-junction-geometry.js,入口文件降为 1472 行。

下一条清晰边界是 complex-junction-facilities.js:进口/停止线、道路臂过街、角部组合和位移联动共用可变的 arm frame,必须作为一个整体迁移;把它们逐个拆成更多小模块会掩盖阶段依赖。核心/入口面/统一铺装可作为之后的 complex-junction-surfaces.js。建议在当前功能任务结束并提交现有工作后,以完整输出差分为保护再实施这两次迁移,避免在仍频繁调整的设施算法中扩大冲突面。

本次几何模块提取保持输出:两组设施测试与 island-offset 测试通过,差分脚本对 5 次复杂路口完整返回值比较一致;铺装、落面和拓扑反例测试通过,变更文件 Prettier 与 git diff --check 通过。

随后迁出 complex-junction-surfaces.js:核心面、进口面与统一铺装区域现在作为一组独立的 surface 阶段。入口文件从 1473 行降至 1301 行。铺装、落面、拓扑反例与 island-offset 回归通过;差分脚本对 9 次复杂路口完整返回值比较一致,包含无效入口、T 形、圆角降级及非零岛体外移。

最后迁出 complex-junction-facilities.js:进口与停止线、道路臂过街、角部组合及共享位移共同拥有 arm frame 的写入、消费和最终应用,因此保持为单个模块。入口文件从 1301 行降至 367 行,只保留拓扑/指标/边界图、阶段编排和发布。迁移中补回形态分类所需的 normalizeHeading 与 positiveHeadingDelta 纯几何导入。设施组合、岛体外移、铺装、落面和拓扑反例通过;差分脚本对 5 次完整返回值比较一致,包含非零岛体外移。

完整 npm test 通过全部代码、几何、编辑 API 和工作台导入检查,最后仍在已有 test/fixtures.js 快照差异退出;该差异与重构前记录一致,未更新基线。首次完整回归暴露 facilities 模块遗漏 ringsOverlap 依赖,已补入并重跑。客户端类型检查和变更文件格式检查通过。