feat(junction): share complex topology build plan

This commit is contained in:
que01 committed 2026-09-08 17:47:35 +08:00
1 parent 855400fba2
commit a12e2ac823
20 files changed
+712 -147

No files matched your search

@@ -0,0 +1,20 @@
# 当前证据与通用问题
## 图像观察
三组图显示角部设施离散、形态趋同和内部空间组织不足。紫色连接线/节点等属于调试显示,不能据此断定铺装或实际标线错误。路口 2 的 T 形判断、图像与 OSM 对应关系均待核实;禁止将截图观察硬编码成拓扑真值。
## 代码入口(规划时)
- src/compile/complex-junction.js:17 resolveComplexJunctionTopology:以来源和方向归组;独立通道/分隔关系需要显式保留。
- src/compile/complex-junction.js:150 boundaryParts;约 325 行按夹角与过街框架生成岛体/小斑马线;约 550 行由进口端点排序生成核心;约 603 行生成独立进口矩形。彼此缺少统一边界所有权。
- src/compile/complex-junction.js:698 classifyJunctionShape:有形态分类,但主要生成规则仍共用包络。
- src/compile/junction-topology.js:29 structureFromTopology 和 junction-structure.js:已有来源、臂、角部、设施稳定键,但结构主要是输出读模型;不宜直接把展示 schema 当可求解计划。
- src/compile/direct-edit-solver.js:276 clusterArms 再次归组,可能与几何生成器方向采样/来源判断漂移;规划需统一纯拓扑解析。
- src/compile/native-road.js:3198 trimLineAtComplexCluster 及所有调用:最近修复只为道路面传 per-road 半径,其他裁切消费者仍可能使用默认半径,需跨图层审计。
- src/compile/direct-edit-solver.js:17 引入 complexJunctionMetrics,而其所在模块读取参考文件。后端规范要求 resolver 无 IO,应将预加载参数与纯计算分离。
- workbench/client/src/components/ParameterPanel.tsx 和 App.tsx:复用现有编辑通道;要验证预览先于 Enter 返回、批量修改已有约束、取消与旧响应等场景,避免只证明请求发生。
## 设计约束
遵守 .trellis/spec/backend/direct-edit-api.md、frontend/direct-edit-client.md;既有实现与规范不一致处需显式记录修正。数据中没有路缘/岛体精确形状时,只能推断或人工校正,不能宣称全自动真实还原。
@@ -0,0 +1,142 @@
# Phase 0 Audit: Current Complex-Junction Construction
Date: 2026-09-08
## Scope and evidence
This audit uses source-independent synthetic fixtures in
`test/junction-build-plan-counterexamples.js`. They deliberately do not contain
the reference image names, OSM object IDs, place names, or fixed real-world
coordinates. The file records the old behaviour as a baseline; phase 1 must
replace its absence assertions with positive `JunctionBuildPlan` assertions.
## Findings
### 1. Source identity survives, but grouping and geometry have separate rules
- `src/compile/native-road.js:2823-2841` groups ordinary junction approaches by
`segmentId`, sums both directions into one width, and selects the first road
for the approach line.
- `src/compile/complex-junction.js:17-89` creates one complex carriageway per
existing approach, then groups them into an arm when heading differs by less
than 20 degrees (`:60-71`). The direct-edit solver repeats that independently
in `src/compile/direct-edit-solver.js:210-297`, including its own line and
tangent sampling (`:254-258`, `:277-296`).
- Stable keys use source identity (`complex-junction.js:47-88` and
`junction-topology.js:3-9`), which is reusable. But an arm becomes the
operative geometry unit: the core uses one envelope per arm
(`complex-junction.js:551-566`), and arm crossings start from the
representative (`:244-247`). That does not provide a distinct EntrySection
or shared curb for each separated carriageway.
Result: directional/source identity is a good starting point, but no single
pure structure resolver is authoritative for compiler and solver. Do not make
the 20-degree threshold the `JunctionBuildPlan` grouping rule.
### 2. Distance semantics mix along-line and radial projection
- Ordinary cutback uses `pointAlongLine()` and a tangent at that cutback
(`native-road.js:2844-2859`, `:2900-2918`), which is the correct local basis
for a bent ordinary approach.
- Complex geometry takes the first-segment heading at the node
(`complex-junction.js:42-44`) and maps a radius to an along-line station by a
scalar projection (`:857-861`). For a curve, that is not the intersection of
the centre-radius boundary and the line. `armEnvelopeAtRadius()` and corner
calculations reuse it (`:862-878`, `:919-934`).
- External road surface has a late per-road radial correction
(`native-road.js:656-699`, `:3215-3236`), but the other consumers do not all
receive that same per-road radius.
Result: `EntrySection` must name a fixed far section and a station measured on
the source polyline. It may derive a boundary intersection from the actual
polyline, but may not equate that with a centre projection.
### 3. Existing surfaces have no shared-boundary authority
- Complex geometry independently emits a core polygon (`complex-junction.js:551-602`), one rectangular polygon per carriageway (`:603-631`), corner fills
(`:450-490`), pedestrian corner bands (`:492-549`), and automatic corner
islands/crossings (`:319-449`). Their overlap is intentional in places; it is
not a referenced seam contract.
- Ordinary boundaries merge parallel approaches into a single face
(`native-road.js:2861-2897`) and then independently round corners
(`:2900-2955`). This avoids one failure mode but loses separate-corridor
semantics.
- `roadRing()` and `sidewalkRing()` only offset independent centre lines
(`native-road.js:3364-3396`); neither receives a shared boundary reference.
- Validation is local: complex pedestrian corners check self-intersection
(`complex-junction.js:519-530`) and the core checks one ring (`:565-566`).
There is no validation of road/core seams, connected required pavement, holes,
or exclusion zones.
Result: phase 2 needs `BoundaryGraph` ownership before adding more controls.
Core, approach, corner, sidewalk, marking, and facility producers must consume
edge references rather than reconstructing offset rectangles.
### 4. Layer trimming is inconsistent
| Consumer | Complex-cluster trim path | Per-carriageway boundary radius |
| --- | --- | --- |
| Road surface | `native-road.js:688-699` | Yes, from `complexApproachBoundaryRadii()` |
| Edge lines | `native-road.js:1098-1120` | No |
| Centre/lane separators | `native-road.js:1171-1192` | No |
| Sidewalk strips | `native-road.js:1850-1855` | No |
| Lane centre lines | `native-road.js:2109-2140` | No |
| Complex carriageway, core, corners, facilities | `complex-junction.js:149-667` | Separate radial/core rules |
The shared helper falls back to `approachOuterRadius` when no radius is passed
(`native-road.js:3201-3212`). Thus the earlier road-surface continuity repair
does not establish a cross-layer contract. Every listed consumer must eventually
take its termination from the same `EntrySection`/BoundaryGraph plan.
### 5. Solver purity is currently violated indirectly
`direct-edit-solver.js:17` imports `complexJunctionMetrics()`. That function
calls `readReferenceCalibration()` (`complex-junction.js:740-757`), which uses
`fs.existsSync` and `fs.readFileSync` (`:723-737`). This conflicts with the
direct-edit resolver purity requirement in `.trellis/spec/backend/direct-edit-api.md`.
Preload reference-derived metrics in the compile/service boundary, then pass
plain values into a pure topology/plan resolver.
## Minimal counterexamples and required future invariants
| Fixture | Current baseline | Required plan invariant |
| --- | --- | --- |
| `divided` | Two 10 m-separated, same-heading carriageways become one 20-degree arm. | Two stable carriageways and EntrySections remain distinct; an arm may group them for presentation only. Their boundaries cannot collapse into a single solid approach unless an explicit traversable connection says so. |
| `tee` | Shape is `t-junction`; no closure or boundary object exists. | The blocked side is represented by explicit boundary edges, with no invented through pavement or facility. |
| `offset-unequal` | Label is `offset-cross`; widths remain approach metadata without boundary references. | Each section keeps its own position, tangent, left/right edge, and far anchor; generated rings have shared seams within 1 cm. |
| `curved-short` | Heading samples the first segment and core/radius code uses a projection-derived station; length is below the minimum core radius. | Resolve against actual polyline length and local tangent. Return an object-scoped unsupported diagnostic when a required transition cannot fit; never extend or silently disconnect geometry. |
## Recommended first implementation slice
Implement a pure `junction-build-plan` module before touching rendering or UI.
It should receive already-loaded model/config data and return either:
1. `JunctionBuildPlan` with version, source topology, stable carriageway keys,
`EntrySection`s (source polyline, far station, entry station, tangent,
left/right boundary endpoints), grouping provenance, and diagnostics; or
2. an object-scoped unsupported/ambiguous result with no geometry claim.
The module must be the sole source for both `resolveComplexJunctionTopology()`
and solver cluster handle anchors. First tests should make all four fixtures
positive: input order and rotation stable, separated carriageways retained,
curved stations bounded by actual length, and T closure explicit. Do not add a
new user control until phase 2 verifies shared seams and all layer consumers use
the plan.
## Compatibility matrix for the first slice
| Existing concept | First-slice treatment |
| --- | --- |
| Stable carriageway/arm/corner keys | Preserve source-derived keys; add plan-local keys without coordinate ordering. |
| `cluster-carriageway-width` and cutback | Read existing constraints through an adapter; retain values only when the resolved EntrySection has a feasible range, otherwise mark recheck/stale. |
| Corner radius | Preserve as a compatibility request, but do not derive a final curve until BoundaryGraph feasibility exists. |
| Crossing and stop-line offsets | Keep document readability; mark as dependent on an arm/section plan and do not create a facility from angle alone. |
| Ordinary junction output | No behavior change in the first slice. |
| Reference-file calibration | Move I/O outside the pure resolver and inject resolved metrics. |
## Checks run
`node test/junction-build-plan-counterexamples.js`
This is a planning-stage baseline and is intentionally not added to `npm test`
until phase 1 replaces its current-state assertions with the new plan contract.