refactor: split complex junction stages
This commit is contained in:
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. 契约与最小反例
|
||||
|
||||
+47
@@ -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` 依赖,已补入并重跑。客户端类型检查和变更文件格式检查通过。
|
||||
Reference in new issue
Block a user