refactor: split complex junction stages

This commit is contained in:
que01 committed 2026-09-16 17:45:57 +08:00
1 parent 1679d1bfc1
commit 55888e8d91
8 files changed
+1644 -1121

No files matched your search

@@ -54,3 +54,25 @@ Wrong: move a stripe until it touches an arc at one point and declare success
because overlap area is zero. Correct: share the complete crossing short-edge
segment with the island boundary, then derive the green polygon from those
same endpoints and verify non-contact curves separately.
## Generator stage ordering
`src/compile/complex-junction.js` keeps `buildComplexJunctionGeometry` as the
orchestrator. Its private stages own approach selection/stop lines, arm crossing
layout, corner composition, crossing displacement, pavement assembly and
publication. Keep the existing local solvers in their geometry modules.
- `buildArmCrossings` writes the arm's `crosswalkFrame`, `crosswalkRadius` and
evidence before `buildCornerCompositions` consumes them.
- Corner contact solutions collect both endpoint offsets for each shared arm.
Call `applyCrossingDisplacements` once after all corners, before pavement
assembly. It updates stripes, stop lines and the full swept crossing regions;
moving only the visible stripes leaves pavement gaps.
- Preserve the current failure dependency during structural refactors: a failed
corner contact solve also skips that corner's sidewalk. Changing this is a
behavior change requiring a dedicated regression, not a helper extraction.
- Core `approach_headings` uses `arm.representative.heading`, not `arm.heading`:
the representative heading and grouped arm heading can differ.
- Validate refactors against complete generator results, including feature
order, metadata and diagnostics. Run `test/junction-island-offset.js` explicitly
alongside `npm test`; it covers the shared-endpoint displacement path.
@@ -1,5 +1,13 @@
# 实施计划与阶段出口
## 2026-09-16 生成器结构重构
用户确认梳理 `buildComplexJunctionGeometry`,已将千行入口缩为约 159 行阶段编排,按进口、过街、角部、位移、铺装和发布拆出私有函数。45 次完整新旧返回值深比较一致;几何/编辑/API/导入回归、191 项客户端单测、类型检查和 12 项 E2E 通过。`npm test` 最后仍有重构前已复现的 fixture 快照差异;全仓格式检查仍有未修改文件的既有问题,本次源文件格式通过。独立复核未发现行为变化。详细边界、可重跑差分脚本及证据见 `research/geometry-refactor.md`。未提交,父任务其余验收保持原状态。
后续评估已先迁出无状态局部几何工具至 `complex-junction-geometry.js`;`complex-junction.js` 从 1685 行降至 1472 行。设施阶段应以整体迁移的方式进入单独模块,避免将共享 arm frame 和角部失败依赖拆散。完整评估与本轮针对性验证见同一 research 文档。
该模块拆分已完成:`complex-junction-surfaces.js` 承担核心/进口/铺装,`complex-junction-facilities.js` 承担进口停止线、过街、角部和位移;入口文件现为 367 行。保持公开导出与构建顺序,差分和针对性回归通过;仍需按任务既有质量门在提交前重跑全量检查。
当前为 in_progress;任务已收敛为分阶段推进。第一个新阶段是“复杂路口区域模型”:先统一中心通行区、角部可行域和安全岛边界,再恢复设施与视觉验收。实验性固定安全岛修改已保存至 `/private/tmp/junction-island-experiment.patch`,不作为正式方案。
## 0. 契约与最小反例
@@ -0,0 +1,47 @@
'use strict';
// Run from the repo root with node --require <this file> test/<suite>.js.
// This one-off comparison retains the pre-refactor generator as its oracle.
const assert = require('node:assert/strict');
const path = require('node:path');
const Module = require('node:module');
const { execFileSync } = require('node:child_process');
const root = path.resolve(__dirname, '../../../..');
const filename = path.join(root, 'src/compile/complex-junction.js');
const baseline = new Module(filename, module);
baseline.filename = filename;
baseline.paths = Module._nodeModulePaths(path.dirname(filename));
baseline._compile(
execFileSync('git', ['show', '1679d1b:src/compile/complex-junction.js'], { cwd: root, encoding: 'utf8' }),
filename,
);
const current = require(filename);
const build = current.buildComplexJunctionGeometry;
let comparisons = 0;
const shapes = new Set();
const diagnostics = new Set();
let shifted = 0;
let crossingEdits = 0;
current.buildComplexJunctionGeometry = function (model, cluster, helpers) {
const values = {};
const functions = {};
for (const [key, value] of Object.entries(helpers)) {
(typeof value === 'function' ? functions : values)[key] = value;
}
const copied = structuredClone({ model, cluster, values });
const expected = baseline.exports.buildComplexJunctionGeometry(copied.model, copied.cluster, {
...copied.values,
...functions,
});
const actual = build(model, cluster, helpers);
assert.deepStrictEqual(actual, expected, `generator output changed for ${cluster.id}`);
comparisons++;
shapes.add(actual.shape?.kind || 'early-return');
for (const item of actual.diagnostics) diagnostics.add(item.rule);
if (helpers.clusterIslandOffsetMeters) shifted++;
if (helpers.clusterCrossingControls?.size) crossingEdits++;
return actual;
};
process.on('exit', () => {
console.log('Generator parity:', { comparisons, shapes: [...shapes], shifted, crossingEdits, diagnostics: [...diagnostics] });
});
@@ -0,0 +1,47 @@
# 复杂路口生成器结构整理
用户于 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` 依赖,已补入并重跑。客户端类型检查和变更文件格式检查通过。