feat(junction): establish stable complex junction structure
This commit is contained in:
1 parent
bd8b55e58b
commit
0a5a229ce3
22 files changed
+1386
-125
No files matched your search
@@ -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.
|
||||
Reference in new issue
Block a user