feat(junction): establish stable complex junction structure

This commit is contained in:
que01 committed 2026-09-08 11:25:57 +08:00
1 parent bd8b55e58b
commit 0a5a229ce3
22 files changed
+1386 -125

No files matched your search

+57
View File
@@ -298,3 +298,60 @@ document byte-identical; warnings remain saveable. This prevents a client from
skipping preview and persisting a width, corner radius, crossing offset, or
stop-line value that the compiler rejects. Version conflicts are checked first
and continue to return HTTP 409 without invoking geometry validation writes.
## 16. Scoped complex junction identity
### Scope and signatures
Stage 1 establishes the read model consumed by later cluster editing. Use
`resolveComplexJunctionTopology(model, cluster, helpers)` in complex geometry,
then `structureFromTopology(topology, shape, center, features)`. Projection is
`projectJunctionStructure({ model, layers, trafficSignals, junctionRef })`.
### Contracts
- `junctionRef` is `{ type: 'node' | 'cluster', id }`. Explicit `null` means no
junction projection; unknown references return `null`, never the first core.
- `GET /api/state` returns `junctionStructures`, keyed by `node:<id>` and
`cluster:<id>`. The legacy singular field is null at this unscoped entry point.
- `GET /api/edit-state?junction=<node>` preserves the node selection contract;
`?cluster=<id>` selects a cluster. Preview uses the equivalent `selection`
object. Cluster handle manifests are empty until a future writable contract.
- Complex road-surface features carry `junction_key`, `object_key` and relevant
`arm_key`, `carriageway_key`, `corner_key`. Core (or the first remaining
approach when the core fails) carries `junction_structure` for persisted reads.
- Stable keys derive from cluster and sorted source node/segment/road IDs, with
corner keys derived from adjacent arms. Display indices and headings are not
object identities. `topologyFingerprint` detects source topology changes.
- Root provenance lists member nodes and external road/segment IDs. Arms point
to carriageways, corners to arms, facilities to feature IDs; normalizers must
preserve these fields and readonly capabilities across JSON round trips.
- Signal projection joins exact member `node_id` / `control_id`, retaining the
existing `signal_uid` as `geometryRef` and `provenance.featureIds`. It does not
rewrite the separately persisted signal document or guess from UID substrings.
### Validation matrix
| Input | Result |
| --- | --- |
| Multiple selection keys or repeated query keys | 400, no implicit priority |
| Empty/object-valued ID | 400 |
| Unknown node/cluster or missing compiled complex structure | null structure, empty diagnostics |
| Missing/ambiguous object source | readonly capability with reason |
| Explicit cluster selection | empty handles; never all-area or member-node handles |
### Cases and tests
Good: reorder member/road arrays and retain semantic IDs; delete a source and
change its identity/fingerprint. Base: legacy node editing still works. Bad:
opening cluster B while rendering cluster A's first core. Test the 3/4/offset/5+
arm matrix, two-cluster isolation, internal-link exclusion, grouped crossings,
scoped signals, JSON round trips, and persisted/preview projection equality.
```js
// Wrong: chooses an arbitrary junction and loses the selected scope.
projectJunctionStructure({ model, layers });
// Correct for a scoped editor:
projectJunctionStructure({ model, layers, trafficSignals,
junctionRef: { type: 'cluster', id: selectedClusterId } });
```
@@ -271,3 +271,28 @@ The same internal node layout can resolve to different external-arm topology.
If no summary exists, omit the shape row and retain normal cluster context; do
not show an inferred fallback. The compiler's safe fallback has no complex core
and therefore no summary.
## 16. Scoped structure and semantic map selection
Use `structureForJunction(state, ref)` to read `state.junctionStructures`; do not
reuse the unscoped singular structure when its ref differs. A missing structure
stays unavailable. Use `junctionEditSelection(ref)` for edit-state and preview
requests so a cluster never falls back to the last selected road or node.
Compiler structure provenance supplies cluster hotspots and external road IDs.
`localJunctionState` and `localJunctionPreview` recognize explicit `junction_key`
(and legacy `cluster_id`) before testing node/road references. This keeps core
and corner features that do not carry member node IDs and excludes neighboring
clusters even if a connecting road is shared.
Map/list selection goes through `junctionObjectKeyForFeature` and
`junctionObjectFeatures`: compiler keys identify arms/corners/crossing groups;
signal UIDs resolve through scoped facility provenance. Display labels and row
indices are never parsed into IDs. Highlighting is a read-only overlay, allocated
when selecting an object; it must not mutate baseline features or rebuild the
map. On scope changes clear object selection and ignore obsolete manifest loads.
Map capability reason codes into user-facing Chinese descriptions.
Required checks: opposite node/cluster scopes with equal raw IDs, unknown scope,
list-to-feature grouping and feature-to-list identity, foreign-cluster exclusion,
raw signal UID selection, map identity preservation, and reload stability.