Files
road-compiler/.trellis/tasks/09-08-junction-reference-fidelity/research/geometry-refactor.md
T

48 lines
5.6 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.
# 复杂路口生成器结构整理
用户于 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` 依赖,已补入并重跑。客户端类型检查和变更文件格式检查通过。