feat(junction): share complex topology build plan
This commit is contained in:
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.
|
||||
Reference in new issue
Block a user