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 } });
|
||||
```
|
||||
Reference in new issue
Block a user