Compare commits
247
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
0f1850f740 | ||
|
|
c03a90709e | ||
|
|
1842eb7d8c | ||
|
|
05614d1a69 | ||
|
|
7c04d086db | ||
|
|
512333375e | ||
|
|
818d91d8b5 | ||
|
|
e8ecfecbf4 | ||
|
|
c4c25dea80 | ||
|
|
b9c38b0b7b | ||
|
|
cfb3593a0b | ||
|
|
79590d3d0f | ||
|
|
55888e8d91 | ||
|
|
1679d1bfc1 | ||
|
|
e0eaa1c950 | ||
|
|
0c42eb46cd | ||
|
|
c3579074fd | ||
|
|
3ed503a986 | ||
|
|
95b8f068aa | ||
|
|
f122e8236a | ||
|
|
fda733ce72 | ||
|
|
a2bce9f465 | ||
|
|
7ca57a68e6 | ||
|
|
8882754b23 | ||
|
|
787faa7604 | ||
|
|
914adcc4e6 | ||
|
|
062f20f34c | ||
|
|
ad0f55e79d | ||
|
|
92c5977dd6 | ||
|
|
6b11c640e1 | ||
|
|
edadf98df1 | ||
|
|
0f9dcace3d | ||
|
|
36c5d5c4c8 | ||
|
|
3d5cc2de6b | ||
|
|
82846cdebc | ||
|
|
78c357e445 | ||
|
|
aeccae1187 | ||
|
|
d0a4cfa7ff | ||
|
|
6a8f026d12 | ||
|
|
695bf21a84 | ||
|
|
1b91e280bc | ||
|
|
7a7912f302 | ||
|
|
76f81d024a | ||
|
|
de97600fe8 | ||
|
|
f356e8e99c | ||
|
|
df39237829 | ||
|
|
14930c5dd6 | ||
|
|
eaafcd85da | ||
|
|
6cfcd5d4b2 | ||
|
|
376427d270 | ||
|
|
3575e372bd | ||
|
|
ff11dc2654 | ||
|
|
f40caaa264 | ||
|
|
2b79085042 | ||
|
|
3a8af43140 | ||
|
|
858db529ae | ||
|
|
067c0e370d | ||
|
|
a5089220b5 | ||
|
|
44fa82299b | ||
|
|
f1a5b284a7 | ||
|
|
f722cadf25 | ||
|
|
c77308c170 | ||
|
|
53b63ae333 | ||
|
|
e2ec728af3 | ||
|
|
7e4d77afbe | ||
|
|
655e7efaef | ||
|
|
936354fec8 | ||
|
|
38dc9d6f52 | ||
|
|
3e74732190 | ||
|
|
88b7e17f4d | ||
|
|
92894c7e4f | ||
|
|
5ec46c3b3e | ||
|
|
3cf6bebb10 | ||
|
|
efb7de6a83 | ||
|
|
bde28c8743 | ||
|
|
609935d209 | ||
|
|
c003edaf51 | ||
|
|
101bcb3792 | ||
|
|
79f2ee5d4e | ||
|
|
cd65dbe879 | ||
|
|
49212b3f34 | ||
|
|
79f83412e6 | ||
|
|
801d8be980 | ||
|
|
21c05800c0 | ||
|
|
413b3d9b89 | ||
|
|
95c49722d4 | ||
|
|
433499bbcb | ||
|
|
fe6a160741 | ||
|
|
febaeb4092 | ||
|
|
a4b1ad8510 | ||
|
|
134e0752ed | ||
|
|
011874dd33 | ||
|
|
a37c707188 | ||
|
|
a90826efed | ||
|
|
b3a2d5fcd5 | ||
|
|
2f627df232 | ||
|
|
f4cf42f1c6 | ||
|
|
d35b704e5e | ||
|
|
ff7f011826 | ||
|
|
1de7bc2bd0 | ||
|
|
173296e348 | ||
|
|
9df315ec16 | ||
|
|
103004b30a | ||
|
|
a090cb1e58 | ||
|
|
9af3afcbbd | ||
|
|
57530016f7 | ||
|
|
a6121aecfe | ||
|
|
a476faf171 | ||
|
|
af286c6149 | ||
|
|
88fcee94a0 | ||
|
|
a22319a149 | ||
|
|
9b6b5b5791 | ||
|
|
6c7d81df35 | ||
|
|
b1fd54f0f8 | ||
|
|
e5d805a369 | ||
|
|
c4902cd4c8 | ||
|
|
9ec99ed03e | ||
|
|
234dd46f59 | ||
|
|
f18dd0c0eb | ||
|
|
db904d3194 | ||
|
|
8929edcee4 | ||
|
|
0e162d1f43 | ||
|
|
cd3a9c9613 | ||
|
|
4e7274ec61 | ||
|
|
280b726c6f | ||
|
|
d353b48a0b | ||
|
|
a98d170757 | ||
|
|
48fd432266 | ||
|
|
d49cdab40a | ||
|
|
c14b8b09f2 | ||
|
|
3bf2edaf99 | ||
|
|
75bdfbe607 | ||
|
|
4b8f37a219 | ||
|
|
b6f4dfeb0c | ||
|
|
f56c0978b0 | ||
|
|
88d8b841e5 | ||
|
|
b4abfdb870 | ||
|
|
4de971ce68 | ||
|
|
a12e2ac823 | ||
|
|
855400fba2 | ||
|
|
53a2cb3450 | ||
|
|
36a8291c05 | ||
|
|
bf26a74a33 | ||
|
|
f515a1e934 | ||
|
|
880ca8da91 | ||
|
|
6896f8a554 | ||
|
|
a5f64a2349 | ||
|
|
89f4ce79b0 | ||
|
|
49a44fdf73 | ||
|
|
bb5dc01c07 | ||
|
|
80f122be46 | ||
|
|
d0e1f62f2b | ||
|
|
971be2314c | ||
|
|
c4bcbe8ff9 | ||
|
|
56647fcdaa | ||
|
|
3a151e97c3 | ||
|
|
0a5a229ce3 | ||
|
|
bd8b55e58b | ||
|
|
bba3ebe4b0 | ||
|
|
2b49a78b99 | ||
|
|
a0bdd25c9d | ||
|
|
3ba7e6f1e8 | ||
|
|
0065c3eaec | ||
|
|
61ae90352a | ||
|
|
fc962ce402 | ||
|
|
92ab2edd96 | ||
|
|
4519cad562 | ||
|
|
73ce56c290 | ||
|
|
63c6cefce7 | ||
|
|
cb55b3ad68 | ||
|
|
06a58c9dbf | ||
|
|
de6ef8e64b | ||
|
|
b89c5fd174 | ||
|
|
977858b283 | ||
|
|
fc7fe81eff | ||
|
|
0f804b71d1 | ||
|
|
d61c86ed2c | ||
|
|
39e338668b | ||
|
|
91e088b25a | ||
|
|
61cf276745 | ||
|
|
8d6f531377 | ||
|
|
cdcc606391 | ||
|
|
a359f88edc | ||
|
|
38ea779d9b | ||
|
|
57248f1aa4 | ||
|
|
1f439d98de | ||
|
|
f10a5da325 | ||
|
|
e6b822416d | ||
|
|
c9d9e45f48 | ||
|
|
39d7453ebc | ||
|
|
a78f5257fc | ||
|
|
3811790dc8 | ||
|
|
b7d9a1973e | ||
|
|
8c99bb7340 | ||
|
|
6a0736517f | ||
|
|
ecfa391eea | ||
|
|
1bd1fd712f | ||
|
|
60e28f6b7a | ||
|
|
f6f51fe90b | ||
|
|
4b38ce3c31 | ||
|
|
c59fb704ef | ||
|
|
2504e8342f | ||
|
|
96833d3a63 | ||
|
|
7d9b0f46d4 | ||
|
|
bd7b049930 | ||
|
|
6b75d273e7 | ||
|
|
15be3480ed | ||
|
|
58f59c8a45 | ||
|
|
fcb07b8396 | ||
|
|
2fb9db65e5 | ||
|
|
bb6c51c489 | ||
|
|
31552a5b6f | ||
|
|
834470cfa1 | ||
|
|
caa3cb843f | ||
|
|
9b7c3d59bd | ||
|
|
9c83392b97 | ||
|
|
cf5bc0602b | ||
|
|
00d5f7650f | ||
|
|
c804a373ca | ||
|
|
118dc8e9aa | ||
|
|
fe73d993a9 | ||
|
|
0318876e6a | ||
|
|
bb108267e3 | ||
|
|
6d80597642 | ||
|
|
9cb715a592 | ||
|
|
5457f960ff | ||
|
|
3d135761e7 | ||
|
|
2415733597 | ||
|
|
e48eb15827 | ||
|
|
8b84166e6f | ||
|
|
335c8ea68a | ||
|
|
15d41be444 | ||
|
|
f3924caa5c | ||
|
|
84c82f3f09 | ||
|
|
323ff9279f | ||
|
|
5c89d92041 | ||
|
|
59e3dc2320 | ||
|
|
479ffd00ed | ||
|
|
8a039f47ab | ||
|
|
4b70b0221d | ||
|
|
7b5bb753a7 | ||
|
|
2694cad619 | ||
|
|
623481fd2c | ||
|
|
086939be93 | ||
|
|
2ef24539f9 | ||
|
|
6663c289e7 | ||
|
|
1c27501534 |
No files matched your search
@@ -14,3 +14,4 @@ workbench-data/
|
||||
|
||||
# Claude 本机私有设置,不进入版本控制
|
||||
.claude/settings.local.json
|
||||
test-results/
|
||||
@@ -10,7 +10,7 @@ It is required because the feature crosses compiler, storage, and HTTP layers.
|
||||
|
||||
```js
|
||||
resolveDirectEditConstraints(model, editDocument, context)
|
||||
// -> { roadProfiles, junctionPlans, constraintStates, handles, diagnostics }
|
||||
// -> { roadProfiles, junctionPlans, clusterPlans, constraintStates, handles, diagnostics }
|
||||
|
||||
GET /api/edit-state
|
||||
POST /api/edit-preview
|
||||
@@ -40,6 +40,10 @@ POST /api/revisions/:id/rebase
|
||||
- `POST /api/revisions/:id/rebase` is read-only and returns status counts plus
|
||||
per-constraint details. `pending`, `conflicted`, and `stale` constraints do
|
||||
not enter geometry solving.
|
||||
- A resolved constraint whose saved numeric value no longer fits the current
|
||||
geometry range is returned as `stale` with reason `range-out-of-bounds`.
|
||||
A missing replay anchor uses reason `anchor-missing`; callers must not infer
|
||||
the stale cause from the status alone.
|
||||
|
||||
## 4. Validation & Error Matrix
|
||||
|
||||
@@ -53,6 +57,7 @@ POST /api/revisions/:id/rebase
|
||||
| Solver replay anchor cannot resolve | Mark `stale` or `conflicted` with diagnostic; never silently apply |
|
||||
| Compiler geometry version differs | Mark all replayable constraints `recheck` without changing values |
|
||||
| Invariant violation (lane width, crossing boundaries, self-intersection, connector bounds) | Return a blocking diagnostic; do not clamp or silently repair |
|
||||
| Constraint value outside the current handle range | Return a blocking diagnostic; do not clamp or silently repair |
|
||||
|
||||
## 5. Good / Base / Bad Cases
|
||||
|
||||
@@ -108,6 +113,21 @@ the pure resolver remains reusable by preview and formal compilation.
|
||||
The handle manifest reports `axisAzimuth = tangent + 90` for both sides, which is
|
||||
therefore *right*. Handle placement must offset the left handle by `tangent - 90`.
|
||||
|
||||
Complex carriageway edge handles use the same convention, but their position is
|
||||
the effective inner entry section rather than the legacy cutback point:
|
||||
|
||||
```text
|
||||
innerStation = outerStation - transitionLength + positionOffset
|
||||
edgeDistance = effectiveWidth / 2 + sideEdgeOffset
|
||||
```
|
||||
|
||||
Compute the tangent at `innerStation`, then apply `directionOffsetDegrees` before
|
||||
placing the left and right handles. This keeps the manifest aligned with
|
||||
`JunctionBoundaryGraph` after transition, position, direction, width, or edge
|
||||
edits. Tests must measure that the two handles are geographically opposite and
|
||||
their separation equals `effectiveWidth + leftOffset + rightOffset` within the
|
||||
geometry tolerance; checking only stored scalar values does not prove placement.
|
||||
|
||||
**Regression**: `makeRoadHandles()` once placed the left handle at `tangent + 90`,
|
||||
drawing it over the right kerb, so dragging the visually-left handle moved the
|
||||
right edge. Assert sides by geography (a north-heading road's left handle is west
|
||||
@@ -147,3 +167,352 @@ empty one produce identical output. Assert that a **non-empty** document changes
|
||||
the compiled output. Wiring gaps between two handlers need an HTTP-level test, and
|
||||
a regression test is only trustworthy once you have watched it fail without the
|
||||
fix.
|
||||
|
||||
---
|
||||
|
||||
## 11. One segment, two directional roads, two junctions
|
||||
|
||||
A segment's forward and backward roads can both reach the same junction while
|
||||
serving different objects. Anything that resolves "the thing at this approach" by
|
||||
taking the first match will therefore publish one road's answer on the other's
|
||||
handle.
|
||||
|
||||
Measured: 15 of 23 segments carried two `junction-crosswalk-inset` handles, and
|
||||
one segment carried two crosswalk groups.
|
||||
|
||||
The discriminator is the road whose **last source node** is this junction —
|
||||
`road.sourceNodeIds.at(-1)` — which is the rule `crossingJunctionInset()` already
|
||||
applies to find its junction plan:
|
||||
|
||||
```js
|
||||
// WRONG — whichever direction comes first in `items` wins
|
||||
const crossing = approach.items.map((i) => crossingByRoadId.get(i.road.id)).find(Boolean);
|
||||
|
||||
// RIGHT — the road that actually ends here
|
||||
const crossing = approach.items
|
||||
.filter((i) => String(i.road.sourceNodeIds?.at(-1)) === String(nodeId))
|
||||
.map((i) => crossingByRoadId.get(i.road.id))
|
||||
.find(Boolean);
|
||||
```
|
||||
|
||||
**Mistake made, twice in one session**: once on the client picking a handle for a
|
||||
selected element, once in the solver computing that handle's bound. Both produced
|
||||
plausible values on the wrong object, which no type check and no smoke test
|
||||
catches — only asserting against a segment that genuinely has two.
|
||||
|
||||
---
|
||||
|
||||
## 12. A handle's range is part of its contract
|
||||
|
||||
`value.min` / `value.max` say "drag here and something happens". Each kind
|
||||
currently derives them independently, and every one measured was wrong in a
|
||||
different direction:
|
||||
|
||||
| kind | declared | measured | failure |
|
||||
| --- | --- | --- | --- |
|
||||
| `road-edge-offset` | ±2.925 | rejected past ~±1 | blocking diagnostic mid-drag |
|
||||
| `junction-crosswalk-inset` | 0–8 | inert past 1.0–4.5 | **silent**, 44–88% dead |
|
||||
| `junction-stop-line-offset` | 0.5–126.28 | fully linear | no meaningful ceiling at all |
|
||||
|
||||
The silent case is the worst: a drag that does nothing is indistinguishable from
|
||||
a broken control, and it is what `flag.ts` blocks whole features for.
|
||||
|
||||
Rules:
|
||||
|
||||
- Derive the ceiling from the geometry that consumes the value, not from a
|
||||
constant. `effectiveCrosswalkInsetMax()` is the worked example: read where the
|
||||
consuming function saturates and solve for it.
|
||||
- Never publish a `max` below the current value — a manifest that contradicts
|
||||
itself. Equal is fine and honest: it says there is no headroom.
|
||||
- A range wide enough to produce nonsense (a stop line 126m from its junction) is
|
||||
as much a defect as one that is dead.
|
||||
|
||||
## 13. Complex junction shape summary
|
||||
|
||||
### 1. Scope / Trigger
|
||||
|
||||
Complex-junction compilation publishes a structural classification which the
|
||||
JunctionTools page displays. This crosses the compiler, the persisted GeoJSON
|
||||
layer, `/api/state`, and the typed browser state.
|
||||
|
||||
### 2. Signatures
|
||||
|
||||
```js
|
||||
GET /api/state?debug=1
|
||||
// debug.junctionShapes?: Array<{
|
||||
// clusterId: string, kind: string, label: string,
|
||||
// armCount: number, throughPairCount: number
|
||||
// }>
|
||||
```
|
||||
|
||||
### 3. Contracts
|
||||
|
||||
- `complex-core` is published in `layers/road_surface.geojson`, not
|
||||
`intersection_surface.geojson`.
|
||||
- Its `shape_kind`, `shape_label`, `arm_count`, and `through_pair_count`
|
||||
properties are the compiler authority. The service must project them without
|
||||
reclassifying from node count.
|
||||
- `debug.junctionShapes` is present only for debug state. An absent matching
|
||||
entry means the client shows its ordinary cluster context, not an invented
|
||||
shape.
|
||||
|
||||
### 4. Validation & Error Matrix
|
||||
|
||||
| Condition | Required behavior |
|
||||
| --- | --- |
|
||||
| No complex core for a configured cluster | Omit its summary; do not emit a false shape |
|
||||
| Shape is unsupported | Compiler emits a normal-junction fallback diagnostic and no `complex-core` |
|
||||
| GeoJSON properties are missing | Use `unsupported` and the readable fallback label only while projecting an existing core |
|
||||
|
||||
### 5. Good / Base / Bad Cases
|
||||
|
||||
- Good: a five-node cluster with five external arms returns `5 臂非规则路口`.
|
||||
- Base: debug is off, so no shape summaries are returned.
|
||||
- Bad: reading `intersection_surface.geojson` returns no complex cores and makes
|
||||
the UI falsely appear to lack classification.
|
||||
|
||||
### 6. Tests Required
|
||||
|
||||
- Compiler: assert `complex-core` has the expected shape kind and arm count for
|
||||
a real OSM cluster.
|
||||
- Service/UI: assert debug state reads the road-surface core and the workspace
|
||||
renders the received label without node-count inference.
|
||||
|
||||
### 7. Wrong vs Correct
|
||||
|
||||
```js
|
||||
// Wrong: complex cores are not stored in this layer.
|
||||
readLayer('layers/intersection_surface.geojson')
|
||||
|
||||
// Correct: project compiler-owned properties from their published layer.
|
||||
readLayer('layers/road_surface.geojson')
|
||||
```
|
||||
|
||||
## 14. Junction structure and standards profile
|
||||
|
||||
Stage-0 JunctionTools structure is compiler-owned and versioned independently
|
||||
of the direct-edit document. `buildJunctionStructure(input)` must return
|
||||
`junction-structure/v1` with unique stable object keys, readable labels, and
|
||||
explicit arm/corner/facility references; it must reject duplicate keys,
|
||||
unknown references, and an effective arm count that differs from the supplied
|
||||
arms. It must not infer missing arms from an internal `2x1`/`2x2` layout.
|
||||
|
||||
`CN_URBAN_DEFAULT_PROFILE` is the immutable `cn-urban-default` profile. Use
|
||||
`cloneProfile()` before applying project-specific changes and
|
||||
`validateStandardsProfile()` at the boundary. Rules distinguish recommended,
|
||||
warning, and blocking/invariant fields; a profile is metadata and rule
|
||||
configuration, not a client-side save decision. Keep the compiler as the sole
|
||||
producer of structure and diagnostics so the client cannot reclassify a
|
||||
junction from node counts.
|
||||
## 15. Save-time geometry validation
|
||||
|
||||
`saveEdits()` must run the same `resolveDirectEditConstraints()` used by
|
||||
`editPreview()` after validating the candidate document and before writing it.
|
||||
Any diagnostic with `severity: 'error'` returns HTTP 400 and leaves the active
|
||||
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. A selected editable cluster publishes its external carriageway,
|
||||
corner, and stop-line handles. It publishes `cluster-crossing-inset` only for
|
||||
an arm with a matching OSM crossing node.
|
||||
- A selected cluster that cannot project an authoritative `junctionStructure`
|
||||
returns an empty scoped handle list from both edit state and preview. The API
|
||||
must not advertise controls for an object the workbench cannot identify or
|
||||
render as an editable structure.
|
||||
- A cluster carriageway anchor contains `clusterId`, stable
|
||||
`carriagewayKey`, `sourceNodeIds`, and `sourceRoadIds`. Replay matches all
|
||||
source identity; a missing or changed source is stale with `anchor-missing`.
|
||||
The solver stores width and cutback values separately, and `compileGeometry()`
|
||||
applies them only to the matching complex-junction approach before geometry is
|
||||
generated.
|
||||
- A cluster corner anchor contains its stable adjacent-arm `cornerKey` and the
|
||||
two representative carriageway keys. It is replayed against the same
|
||||
source-sorted arm grouping used by `resolveComplexJunctionTopology()`. The
|
||||
complex generator reads a local radius by that `cornerKey`; no other corner is
|
||||
rewritten.
|
||||
- A cluster crossing anchor contains `clusterId`, stable
|
||||
`crossingKey` (`crossing:<armKey>`), and its source-backed carriageway keys.
|
||||
Crosswalk inset is in `0..8` m; stop-line offset is in `0.5..12` m. Replay
|
||||
resolves the same arm grouping and marks a missing arm `stale/anchor-missing`.
|
||||
Generated crosswalk stripes and stop lines publish that `crossing_key`; the
|
||||
generator applies the inset once per stripe group and positions each incoming
|
||||
stop line relative to its matching crossing. Never identify these facilities
|
||||
by `crossing_node_id`, because complex members can share a node.
|
||||
- A road envelope or inferred stop line is not crossing evidence. Without a
|
||||
matching source crossing node, compilation emits no complex crosswalk,
|
||||
publishes no crossing-inset handle, records facility evidence as
|
||||
`unknown-no-crossing-source`, and emits
|
||||
`complex-junction-crossing-source-missing`. A stop line may remain as an
|
||||
independent inferred facility; its position must not consume a nonexistent
|
||||
crossing inset.
|
||||
- Source matching uses the same inferred arm radius in handle publication and
|
||||
constraint solving. A published handle must remain applicable at every
|
||||
advertised value, including `value.max`.
|
||||
- Preview and save both evaluate the same candidate through the resolver and
|
||||
`compileGeometry()`. Save rejects every `severity: error` diagnostic before
|
||||
writing the edit document.
|
||||
- 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.
|
||||
- A supported complex core publishes measurable region evidence:
|
||||
`connected_entry_count`, `required_pavement_connected`, `core_ring_area`,
|
||||
`core_ring_self_intersects`, and the existing shared-seam metrics. A contained
|
||||
exclusion hole is valid only when it preserves every required entry seam.
|
||||
- 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 } });
|
||||
```
|
||||
|
||||
## Complex carriageway transition length
|
||||
|
||||
`cluster-carriageway-transition-length` uses the source-checked
|
||||
`cluster-carriageway` anchor and `value.transitionLengthMeters`. Replay verifies
|
||||
source road/node membership before solving. The resolved `clusterTransitions`
|
||||
map is separate from `clusterCutbacks`: the outer source seam is fixed, and the
|
||||
inner station is `outerStation - transitionLengthMeters` along the source
|
||||
polyline. Radial distance differences are not lengths on curved approaches.
|
||||
The maximum is the available outer station; the minimum is the smaller of the
|
||||
configured minimum and the existing source-derived transition (short existing
|
||||
approaches remain representable). Impossible surface geometry still requires
|
||||
compiler validation. A saved transition is never silently clamped.
|
||||
|
||||
Regression evidence: solver rejects out-of-range/source-mismatched values;
|
||||
API preview measures the requested length and preserves the outer seam;
|
||||
save/read/replay reproduces preview geometry; browser input sends the new kind.
|
||||
|
||||
## Complex carriageway direction and edge bounds
|
||||
|
||||
`cluster-carriageway-direction` remains persisted as
|
||||
`value.offsetDegrees`, including for numeric input and existing documents. Its
|
||||
manifest handle declares `interaction.kind = rotation`, an EPSG:4326 `center`
|
||||
at the effective inner entry section, and `radiusMeters`. Pointer projection is
|
||||
the signed shortest azimuth change around that center; pointer metres must never
|
||||
be interpreted as degrees. The direction ghost follows the declared circle and
|
||||
uses degree units.
|
||||
|
||||
Position and width handles use the same effective inner entry section as the
|
||||
BoundaryGraph. Direction edits rotate the width axis and both edge handles at
|
||||
that section.
|
||||
|
||||
The manifest and solver share the carriageway edge range. For one side, with
|
||||
effective width `W`, opposite offset `O`, and minimum lane total `M`, the range
|
||||
is `max(-W/2, M-W-O)..W/2`. Both endpoints are accepted; a value outside the
|
||||
range is rejected with a blocking geometry diagnostic. Independent side
|
||||
constraints and legacy constraints containing both offsets must be evaluated
|
||||
with both effective offsets present.
|
||||
|
||||
Boundary closure reports `sharedSeamErrors` per carriageway and
|
||||
`maxSharedSeamErrorMeters` against the authoritative BoundaryGraph inner
|
||||
section. For a simple closure the section is an exact ring edge. For overlapping
|
||||
multi-carriageway entries, the center is the union of center-to-entry cells;
|
||||
a complete inner seam may then lie inside that union. Such a seam is accepted
|
||||
only after splitting it at every polygon boundary intersection and checking
|
||||
all resulting intervals (0.1 mm numerical boundary tolerance), then measuring
|
||||
its endpoint mismatch against its authoritative graph edge. Missing or
|
||||
uncovered seams remain `Infinity`; valid overlap must not discard carriageways
|
||||
or falsify the connected-entry count. Explicit transition stations are clamped to the source polyline
|
||||
range for legacy/direct compiler inputs and marked
|
||||
`insufficient-source-length` when the requested length cannot fit. The solver
|
||||
rejects such values before they can be saved.
|
||||
|
||||
|
||||
## Shared complex approach consumers
|
||||
|
||||
`compileGeometry()` builds each complex approach BoundaryGraph once. External
|
||||
road surfaces, edges, sidewalks, center markings and published lane centerlines
|
||||
read its source-polyline `outer.stationMeters`; do not independently reconstruct
|
||||
`outerRadius - cutback` in a consumer. The complex surface generator receives the
|
||||
same graph instance. Transition lane endpoints interpolate the respective outer
|
||||
and inner section edges, preserving the fixed source width when the inner width
|
||||
changes. Unsupported, invalid or excluded transitions do not publish preview
|
||||
lanes or their derived markings. This contract does not yet replace the separate
|
||||
corner sidewalk overrun geometry or validate all short-road suppression paths.
|
||||
|
||||
|
||||
## Complex cluster vehicle paths
|
||||
|
||||
Cluster connectors trace enabled lane movements through internal roads to
|
||||
external lane ports. Use breadth-first traversal per incoming lane; avoid
|
||||
cycling through internal lanes. Preserve source movement IDs and existing lane
|
||||
restrictions. A published whole-cluster path references visible approach lanes
|
||||
and their travel-oriented endpoints (outbound preview polylines are stored in
|
||||
reverse travel order). Do not retain per-node connector fragments as if they
|
||||
were whole-cluster trajectories.
|
||||
|
||||
Curves preserve endpoint tangents and use adaptive sampling (2 cm chord error,
|
||||
2 m maximum segment length, 1 degree tangent/chord error). These are geometric
|
||||
sampling tolerances, not proof of curvature continuity or vehicle turning
|
||||
radius. Published cluster paths must be non-self-intersecting, fully inside the
|
||||
published pavement region and avoid island edges/interiors. Failed candidate
|
||||
paths remain diagnostic/deferred movements, never fake safe curves. Current
|
||||
implementation explores a bounded set of cubic control lengths; it is not a
|
||||
complete motion planner and does not prove vehicle swept-envelope clearance.
|
||||
|
||||
## Preview computation and bundled assets
|
||||
|
||||
When `resolveDirectEditConstraints()` receives `selection.type === 'cluster'`,
|
||||
it may omit road, node-junction, and lane-maneuver handles that the selector
|
||||
would discard. It must still solve the complete document before filtering the
|
||||
manifest: saved constraints outside the selected handle family can affect the
|
||||
compiled geometry. The scoped result must equal the unscoped resolution with
|
||||
only the published handle array filtered.
|
||||
|
||||
The bundled `assets/lane-icons/manifest.json` may be cached in-process using its
|
||||
file modification time and size as the invalidation key. Custom manifest paths
|
||||
remain uncached because they are valid live test/config inputs. Caching must not
|
||||
change compiled features or manifest validation errors.
|
||||
|
||||
Regression requirements: compare scoped and unscoped resolution plus compiled
|
||||
layers for an empty document and a document containing mixed constraint kinds;
|
||||
load the bundled manifest twice and verify the cached result; run the existing
|
||||
preview/API and geometry suites after changes.
|
||||
@@ -4,3 +4,6 @@
|
||||
|
||||
- [Road Revision Storage](./road-revision-storage.md) -- immutable workbench revision layout, validation, and recovery contract.
|
||||
- [Direct Edit Solver And API](./direct-edit-api.md) -- pure constraint solving, preview/save endpoints, version protection, and rebase behavior.
|
||||
|
||||
- [Junction Island Contact](./junction-island-contact.md) -- confirmed target contract for full crossing-edge contact, dynamic island legs and the six-point green region (implementation pending).
|
||||
- [Junction Layer Seams](./junction-layer-seams.md) -- metric seam audit, source identity mapping, and both-end corridor trims.
|
||||
@@ -0,0 +1,78 @@
|
||||
# Junction island contact
|
||||
|
||||
## Status and scope
|
||||
|
||||
Confirmed user requirement, 2026-09-11; implementation pending. Applies to the
|
||||
complex-junction composition with two adjacent arm crossings and one crossing
|
||||
beside the inward-curved hypotenuse. This is not a universal traffic-island
|
||||
definition. Simple junction behavior is unchanged.
|
||||
|
||||
## Geometry contract
|
||||
|
||||
- A contact is the complete short edge of a crossing rectangle, not an arbitrary
|
||||
white stripe, a point, or only the portion that happens to intersect the island.
|
||||
- Each of the three crossings contributes one contact segment and two endpoints.
|
||||
All three complete segments must be shared with the island outer boundary.
|
||||
- Contact positions are geometry-dependent. The two perpendicular leg lengths
|
||||
are solved from the contacts and available space; twice crossing depth is not
|
||||
a hard constraint.
|
||||
- Preserve six distinct contact endpoints in boundary order. Connecting them
|
||||
forms the green hexagon on the island. Its three contact edges coincide with
|
||||
the crossing contacts; its other three edges connect adjacent contacts.
|
||||
The green region and rounded island outer boundary are distinct geometries.
|
||||
- Rounded corners and inward curves occupy non-contact boundary portions.
|
||||
A straight contact edge must remain straight over its full length, including
|
||||
the hypotenuse-side landing. Rounding must not trim away contact endpoints.
|
||||
- Solve in local metric coordinates and reuse coordinates across consumers.
|
||||
Preserve consistent stripe dimensions and spacing, avoid positive-area
|
||||
crossing/island intersection, and maintain stop-line separation.
|
||||
- If the available space cannot satisfy the composition, report the object and
|
||||
failed constraint. Do not shorten a crossing, detach it, or report the partial
|
||||
composition as valid.
|
||||
|
||||
## Required validation
|
||||
|
||||
For each complete contact segment S and published island boundary B, measure
|
||||
the length of S covered by B, not polygon intersection area alone. Require
|
||||
uncovered length and endpoint-to-boundary distance <= 0.01 m; this tolerance
|
||||
is numerical, not a design gap. Also check interior samples to catch an arc
|
||||
touching only at the endpoints.
|
||||
|
||||
The six green vertices must equal the six contact endpoints within metric
|
||||
tolerance, with each used once; the ring must be simple, have positive area,
|
||||
lie inside the outer island, and retain all three full contact edges. An
|
||||
independently fitted polygon or a hull dropping vertices fails this contract.
|
||||
|
||||
Required cases: orthogonal base case; unequal contact offsets and crossing
|
||||
depths; translated/rotated equivalents; changed available space; roundovers
|
||||
that would cut into contacts; and an infeasible composition. On the current
|
||||
real OSM, verify all contacts and all six vertices for every published island,
|
||||
not just feature counts or a hand-picked corner. Retain image evidence showing
|
||||
the outer boundary, green hexagon, complete crossing rectangles and stop lines.
|
||||
|
||||
Wrong: move a stripe until it touches an arc at one point and declare success
|
||||
because overlap area is zero. Correct: share the complete crossing short-edge
|
||||
segment with the island boundary, then derive the green polygon from those
|
||||
same endpoints and verify non-contact curves separately.
|
||||
|
||||
## Generator stage ordering
|
||||
|
||||
`src/compile/complex-junction.js` keeps `buildComplexJunctionGeometry` as the
|
||||
orchestrator. Its private stages own approach selection/stop lines, arm crossing
|
||||
layout, corner composition, crossing displacement, pavement assembly and
|
||||
publication. Keep the existing local solvers in their geometry modules.
|
||||
|
||||
- `buildArmCrossings` writes the arm's `crosswalkFrame`, `crosswalkRadius` and
|
||||
evidence before `buildCornerCompositions` consumes them.
|
||||
- Corner contact solutions collect both endpoint offsets for each shared arm.
|
||||
Call `applyCrossingDisplacements` once after all corners, before pavement
|
||||
assembly. It updates stripes, stop lines and the full swept crossing regions;
|
||||
moving only the visible stripes leaves pavement gaps.
|
||||
- Preserve the current failure dependency during structural refactors: a failed
|
||||
corner contact solve also skips that corner's sidewalk. Changing this is a
|
||||
behavior change requiring a dedicated regression, not a helper extraction.
|
||||
- Core `approach_headings` uses `arm.representative.heading`, not `arm.heading`:
|
||||
the representative heading and grouped arm heading can differ.
|
||||
- Validate refactors against complete generator results, including feature
|
||||
order, metadata and diagnostics. Run `test/junction-island-offset.js` explicitly
|
||||
alongside `npm test`; it covers the shared-endpoint displacement path.
|
||||
@@ -0,0 +1,88 @@
|
||||
# Junction layer seams
|
||||
|
||||
## Scope and source contracts
|
||||
|
||||
Complex-junction seams use a **0.01 m** numerical tolerance in local metric
|
||||
coordinates. This is internal stitching precision, not OSM survey accuracy.
|
||||
`test/helpers/junction-seams.js` audits published features against source
|
||||
identities in `junction_structure`; it does not call the geometry builders to
|
||||
manufacture expected geometry.
|
||||
|
||||
- Exterior surfaces match the complete `directional_road_ids` set of a
|
||||
carriageway. Core and pavement match `cluster_id`; approaches match
|
||||
`carriageway_key`.
|
||||
- Native lanes use `road_id` and travel-direction `lane_index`. Preview lanes
|
||||
use a combined cross-section index running from `outer.right` to `outer.left`.
|
||||
Map outgoing lanes in reverse order, followed by incoming lanes in forward
|
||||
order. Do not equate these two index spaces or choose a nearest lane globally.
|
||||
- Edge lines match the source road and `side`. Separators match the lane pair;
|
||||
the boundary between opposite directions belongs to the road centre marking.
|
||||
Centre markings match the complete `directional_road_ids` set and a primary
|
||||
`road_id` belonging to that set; a partial source match is not sufficient.
|
||||
- Sidewalk corners match `corner_key` and strips from their two source arms.
|
||||
Absence is acceptable only for disabled source sidewalks or an explicit
|
||||
rejection identifying that exact corner. A cluster-wide fallback diagnostic
|
||||
must not excuse a missing corner elsewhere.
|
||||
|
||||
## Both ends of a corridor
|
||||
|
||||
`trimRoadAtComplexClusters(road, junctionPlans, clusters, boundaries)` in
|
||||
`native-road.js` calculates **both** endpoint cutbacks from the original source
|
||||
polyline and each cluster's `outer.stationMeters`, then calls `trimLineRange`
|
||||
once. Road surfaces, sidewalks, edges, centre lines and native lanes share it.
|
||||
|
||||
Wrong: select `startCluster || endCluster` as the only trim owner, or trim
|
||||
sequentially using the second station on the shortened line. Correct: resolve
|
||||
each endpoint independently and preserve intermediate source bends.
|
||||
|
||||
The first bug leaves the far approach covered by exterior pavement and its
|
||||
edge/lane endpoints tens of metres past the seam. Vertex-to-boundary checks can
|
||||
miss it because the long side edges still touch both seam endpoints.
|
||||
|
||||
## Measurements and failures
|
||||
|
||||
`auditJunctionSeams(model, geometry, structures)` returns each layer's `checked`,
|
||||
`failed`, `notApplicable` and identity-bearing `records`.
|
||||
|
||||
| Interface | Required measurement |
|
||||
| --- | --- |
|
||||
| Exterior surface / approach | Endpoint error and complete boundary segment coverage |
|
||||
| Approach / core and published pavement | Complete segment containment, respecting holes |
|
||||
| Native / preview lanes and solid edges | Corresponding endpoint or paint-cap midpoint |
|
||||
| Dashed edges, centre lines, separators | Support alignment and bounded terminal gap |
|
||||
| Corner / sidewalk strip | Both full end edges, with source-arm matching |
|
||||
|
||||
Missing expected objects fail; never iterate only detected objects and report an
|
||||
empty set as success. Segment coverage partitions at all boundary crossings, so
|
||||
interior notches cannot hide between fixed probes. Polygon holes remain holes.
|
||||
|
||||
The canonical complex-pavement region fills construction pockets before it
|
||||
subtracts explicit `model.exclusionRegions`. A core hole alone is not proof of
|
||||
the published pavement contract: crossing and corner inputs can otherwise fill
|
||||
it again. After subtraction, an empty or disconnected result, or any missing
|
||||
complete approach seam, rejects canonical pavement publication and carries the
|
||||
cluster plus exclusion identities in its diagnostic.
|
||||
|
||||
Dashes do not need white paint across every seam. An outward road starts its
|
||||
dash sequence at the seam, so its first cap must coincide; the other end can
|
||||
leave a residual dash cycle. Current edge/separator cycles are 2 m paint + 2 m
|
||||
gap. Centre markings publish `dash_length_m` and `dash_gap_m`. Report these gaps
|
||||
separately from the 1 cm transverse alignment tolerance. The audit does not
|
||||
certify every individual dash, every double-line component, or interior paint
|
||||
continuity through a complex core where centre markings are not published.
|
||||
|
||||
## Required regression
|
||||
|
||||
Run `node test/junction-layer-seams.js` (also in `npm test`). To inspect every
|
||||
identity and measurement, run:
|
||||
|
||||
```sh
|
||||
node test/junction-layer-seams.js --report /private/tmp/junction-layer-seams.json
|
||||
```
|
||||
|
||||
Keep nonempty per-layer counts for straight/curved, one-way/two-way, local width
|
||||
and island edits, two-ended corridors, reordered input, current real OSM and
|
||||
explicitly sidewalk-enabled real OSM. Required negative controls: exactly 2 cm
|
||||
displacement, missing single/whole counterparts, wrong source identities,
|
||||
swapped lane indices, absent first anchored dash, a 2 cm interior notch and a
|
||||
hole. Do not loosen the tolerance or refresh unrelated fixture snapshots.
|
||||
@@ -2,4 +2,8 @@
|
||||
|
||||
Use typed React function components. `App.tsx` owns session/editor composition, while reusable map and UI concerns live in named components. Prefer the shared `ui/button.tsx` primitive for commands. Do not create business UI with `querySelector` or `innerHTML`.
|
||||
|
||||
Forms use controlled inputs and submit handlers. Keep map canvas DOM owned by OpenLayers and surrounding controls owned by React.
|
||||
Components expose explicit props for values and callbacks. A form component may own presentation-local state such as a select value, but it must not import `api`, mutate `WorkbenchState` directly, or implement save/preview/undo behavior. The composition root passes commands such as `stage`, `updateSignal`, or `onAccept`.
|
||||
|
||||
The inspector is composed from independent sections. Section components must preserve existing write semantics: ordinary v1 forms stage overrides, `lane-maneuver` uses the v2 session, and signal forms update the signal draft command. Do not make a generic form abstraction that hides these boundaries.
|
||||
|
||||
Forms use controlled inputs and submit handlers. Keep map canvas DOM owned by OpenLayers and surrounding controls owned by React. Extracting a component must preserve labels, default values, event ordering, and the current accordion behavior unless a separate product task approves a change.
|
||||
@@ -125,6 +125,13 @@ a swapped object would leave the requester arbitrating for a session nobody read
|
||||
request layer only sends and cancels. The discard rule is worth unit-testing and
|
||||
must not depend on network timing.
|
||||
|
||||
Selection changes are a second freshness boundary. `PreviewRequester.invalidate()`
|
||||
must cancel the active request and advance its generation; `dispatch()` checks
|
||||
that captured generation before giving a response to `EditSession`. Abort alone
|
||||
is insufficient because a transport may resolve after receiving its abort signal.
|
||||
When changing junction/segment scope, clear scoped preview geometry before the
|
||||
new manifest arrives, so an A-scope result cannot render while B is selected.
|
||||
|
||||
Undo of a **saved** gesture appends an inverse operation; persisted history is
|
||||
never rewritten. Undo of an unsaved one just moves the cursor.
|
||||
|
||||
@@ -140,6 +147,23 @@ match `main` exactly. Guard once at construction, not per call site.
|
||||
while `compileGeometry()` ignores `profile.interval`. A control whose drag changes
|
||||
nothing is worse than no control.
|
||||
|
||||
### Lane maneuver is v2 direct edit only
|
||||
|
||||
`lane-maneuver` is a spatial direct-edit constraint. Its selector and draggable
|
||||
outline are available only in edit mode and must be routed through `EditSession` and
|
||||
the preview endpoint. It must never be added to the ordinary v1 staged override
|
||||
array, which is reserved for road, connector, and marking style overrides.
|
||||
|
||||
With edit mode off, selecting a turn-arrow part may still show read-only element
|
||||
information, but it must not create a manifest request, ghost, preview, handle, or
|
||||
staged lane-maneuver override.
|
||||
|
||||
Crosswalk inset and stop-line offset follow the same element ownership rule. New
|
||||
manifests use a `junction-crossing` anchor containing `crossingId` plus its road
|
||||
context; legacy `junction-approach` anchors remain readable for document replay.
|
||||
The crossing values must be kept separate from junction approach width/cutback
|
||||
plans so editing one crossing cannot move the road geometry or another crossing.
|
||||
|
||||
---
|
||||
|
||||
## 10. Saving is not the same as applying
|
||||
@@ -152,6 +176,84 @@ say so.
|
||||
|
||||
---
|
||||
|
||||
## 11. Two input channels, three shared exits
|
||||
|
||||
A value can come from a drag or from a number field. They differ only in how the
|
||||
scalar is produced and when the gesture closes; everything downstream is shared:
|
||||
|
||||
| Exit | Meaning |
|
||||
| --- | --- |
|
||||
| `draftValue(handle, value)` | preview, do not commit |
|
||||
| `settleValue(handle, value)` | one undoable command, or abandon if it drafts nothing |
|
||||
| `abandonGesture()` | release the id, clear live overrides, re-preview the settled state |
|
||||
|
||||
`EditSession` needs no change to accept a second channel: `gestureIdentity()` is
|
||||
minted lazily by the first draft and released by `commitGesture()`, so `focus` /
|
||||
`blur` land on the same boundary `pointerdown` / `pointerup` already used. That is
|
||||
what makes typing `1.53` one undo step instead of four.
|
||||
|
||||
**Forbidden**: a second preview path, debounce, or undo stack per input device.
|
||||
|
||||
---
|
||||
|
||||
## 12. Continuous input clamps; discrete input refuses
|
||||
|
||||
The invariant is shared — a constraint value never leaves `[min, max]` — but the
|
||||
two devices express it differently.
|
||||
|
||||
- A drag **clamps**. A pointer cannot state an intent it never reached, and the
|
||||
handle has to stay on a road shape that can exist (§3). The clamp is visible in
|
||||
the moment: the handle stops while the cursor keeps going.
|
||||
- A number field **refuses**: mark it invalid, send no preview, add no undo step,
|
||||
keep the last valid preview. Typed text *is* an intent, so rewriting it is a
|
||||
retroactive edit — and the failure modes are asymmetric. A clamped typo (24
|
||||
becoming 5.4) reads as a plausible value and can go unnoticed; a refusal cannot.
|
||||
|
||||
Offer the extremes as one click, but round them **inward**: a real max of `2.925`
|
||||
renders as `2.93` under nearest-rounding, which the range it came from rejects.
|
||||
`formatBoundInward()` exists for this.
|
||||
|
||||
**Mistake made**: the first draft of the panel displayed and filled
|
||||
`formatParameterValue(min)`, which produced a value its own range check refused.
|
||||
|
||||
---
|
||||
|
||||
## 13. A field being typed in owns its own text
|
||||
|
||||
Every settled preview replaces the manifest, so a controlled input bound to
|
||||
`handle.value.current` is rewritten mid-keystroke: typing `1.` fires a preview for
|
||||
`1`, and the response resets the field to `1`, dropping the decimal point.
|
||||
|
||||
The field therefore holds local text while focused and follows the manifest only
|
||||
when it is not:
|
||||
|
||||
```ts
|
||||
value={text ?? formatParameterValue(handle.value.current)}
|
||||
```
|
||||
|
||||
There is no second number to reconcile: `numericValue()` in the solver reads the
|
||||
constraint back out, so `value.current` is the request echoed, never a solved
|
||||
substitute. Seed the local text from what is on screen at focus, not from the
|
||||
manifest — after a drag the row can legitimately be ahead of the last settled
|
||||
preview.
|
||||
|
||||
---
|
||||
|
||||
## 14. Reset disables the constraint; it does not delete it
|
||||
|
||||
`validateEditDocument()` rejects an operation whose `constraintIds` name a
|
||||
constraint that is not in the document, so removing one would mean recording an
|
||||
operation about nothing. Setting `enabled: false` is what design.md already
|
||||
sanctions for undoing saved work, and `constraintFor()` skips disabled
|
||||
constraints, so the handle comes back without a `constraintId` and the row reports
|
||||
itself unmodified again.
|
||||
|
||||
This is the one edit a drag cannot express: a drag can set a value, never withdraw
|
||||
one. `handle.constraintId` — present only when a constraint exists — is also how
|
||||
"untouched" is told apart from "explicitly set to the baseline number".
|
||||
|
||||
---
|
||||
|
||||
## Checklist before committing edit-client changes
|
||||
|
||||
- [ ] No baseline source is written
|
||||
@@ -161,4 +263,88 @@ say so.
|
||||
- [ ] Constraints sent with their operations
|
||||
- [ ] No geometry or OL reads inside a `setState` updater
|
||||
- [ ] No per-`pointermove` React state updates
|
||||
- [ ] Flag off ⇒ no sources, no layers, no interactions, no requests
|
||||
- [ ] Flag off ⇒ no sources, layers, or interactions. A selected complex
|
||||
JunctionTools workspace may request its scoped manifest solely to discover
|
||||
server-published edit capability before the edit switch is enabled.
|
||||
- [ ] Every input channel meets at the shared exits, not a parallel path
|
||||
- [ ] Displayed bounds round inward, so an offered extreme is accepted
|
||||
- [ ] A focused field is not rewritten by an arriving preview
|
||||
|
||||
## 15. Complex shape display is server-owned
|
||||
|
||||
`WorkbenchState.debug.junctionShapes` is a debug-only read model keyed by
|
||||
`clusterId`. JunctionTools may display `label` and `armCount` for the currently
|
||||
opened cluster, but it must not derive T/十字/偏置 shapes from `nodeIds.length`.
|
||||
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.
|
||||
|
||||
## 17. Complex geometry editing
|
||||
|
||||
Complex JunctionTools consumes the same v2 `EditSession`, `PreviewRequester`,
|
||||
`ParameterPanel`, and map handle callbacks as ordinary junctions. Editable
|
||||
handles include `cluster-carriageway-width`, `cluster-carriageway-cutback`,
|
||||
`cluster-corner-radius`, `cluster-crossing-inset`, and
|
||||
`cluster-stop-line-offset`. The first two use a `cluster-carriageway` anchor; a
|
||||
corner anchor is resolved to its representative carriageway only to create the
|
||||
snapshot; crossing controls use `cluster-crossing` and its stable
|
||||
`crossingKey`. Before edit mode, a selected cluster loads its scoped manifest so
|
||||
`canEditJunction()` can use an editable server handle as the capability signal.
|
||||
Do not add a cluster-local draft, preview, undo, or save flow.
|
||||
|
||||
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.
|
||||
|
||||
### Junction workspace save and grouped ranges
|
||||
|
||||
Workspace actions must include `EditSession.dirty`, `canUndo`, and `canRedo`;
|
||||
`JunctionSession.dirty` alone misses settled grouped edits. Reuse the global
|
||||
commands and expose save status in the junction route, where the main header is
|
||||
hidden. The edit render revision is not a persisted document version: a save
|
||||
changes it, so comparing a captured render revision after saving can crash React.
|
||||
The API owns version conflict checks.
|
||||
|
||||
Cluster browse mode may prefetch its scoped manifest before an `EditSession`
|
||||
exists. Record a document key as loaded only after the session has actually
|
||||
loaded its constraints, operations, and `documentVersion`. When the cached key
|
||||
matches but the session version does not, reload the authoritative document;
|
||||
otherwise the first save can incorrectly send version 0 after a topology update.
|
||||
|
||||
A grouped scalar is available only if the individual ranges intersect. Otherwise
|
||||
show why a common value is unavailable and expand individual controls; never
|
||||
render a minimum larger than the maximum. Transition length uses the same input,
|
||||
preview, history, and persistence path as other geometry parameters.
|
||||
|
||||
### Rotational direction handles
|
||||
|
||||
`cluster-carriageway-direction` keeps `value.current` and persisted
|
||||
`offsetDegrees` in degrees. Its manifest declares
|
||||
`interaction: { kind: 'rotation', center, radiusMeters }`. Project pointer input
|
||||
as the shortest signed azimuth change around `center`, clamp it to the manifest
|
||||
range, and place the ghost on the declared circle. Never convert linear pointer
|
||||
metres directly into degrees. The ghost label uses `°`; numeric input continues
|
||||
through the shared scalar edit session and save path.
|
||||
@@ -1,5 +1,13 @@
|
||||
# Directory Structure
|
||||
|
||||
The Vite workbench lives in `workbench/client/`. Application code is under `src/`: `components/` for UI, `map/` for OpenLayers adapters, `lib/` for API clients, `types/` for API contracts, and `ui/` for shared primitives. The Node HTTP server remains `workbench/server.js`.
|
||||
The Vite workbench lives in `workbench/client/`. Application code is under `src/`:
|
||||
|
||||
Keep OpenLayers construction and source mutation outside page components; `src/components/MapCanvas.tsx` owns lifecycle and `src/map/layers.ts` owns the layer registry.
|
||||
- `components/` contains typed React view components and form sections. Components receive domain data and commands through props; they do not own cross-page persistence.
|
||||
- `hooks/` contains one stateful editing domain per hook (`useOverrideDraft`, `useDirectEditSession`, or `useTrafficSignalDraft`). Hooks may call the API boundary through injected commands, but must not share mutable module state.
|
||||
- `edit/` contains pure direct-edit models, projections, sessions, preview arbitration and geometry-unit helpers.
|
||||
- `map/` contains OpenLayers adapters. `MapCanvas.tsx` owns map lifecycle and `map/layers.ts` owns the layer registry and source updates.
|
||||
- `lib/` is the browser HTTP boundary; `types/` owns API and workbench contracts; `ui/` contains shared primitives.
|
||||
|
||||
`App.tsx` is the composition root: it loads server state, owns selection and page-level commands, and connects editing domains to the map and inspector. It must not contain substantial form implementations or a second copy of an editing protocol.
|
||||
|
||||
Keep OpenLayers construction and source mutation outside page components. The map is constructed once per mounted canvas; React re-renders and inspector extraction must not rebuild it or reset its view.
|
||||
@@ -1,3 +1,9 @@
|
||||
# Hook Guidelines
|
||||
|
||||
Use effects for imperative OpenLayers lifecycle only. `MapCanvas.tsx` constructs one map on mount, updates sources when server state changes, and updates visibility separately. Store callback-sensitive values such as selected road and scene mode in refs so stable OpenLayers style callbacks see current values.
|
||||
|
||||
Each custom hook owns one domain and exposes a typed command surface. The three existing edit domains are distinct: ordinary v1 staged overrides, v2 direct-edit session/preview, and traffic-signal drafts. A hook must not create a second undo stack or preview path for another domain.
|
||||
|
||||
Keep `EditSession`, `PreviewRequester`, signal history, and gesture refs stable across renders. Effects may synchronize external state, but a hook must not recreate a session or requester from ordinary state changes. Callback dependencies that are consumed by a stable OpenLayers listener belong in refs.
|
||||
|
||||
Hooks should return data and callbacks; they should not render JSX. API errors are converted to the existing status/reporting command at the composition boundary unless the hook owns a self-contained async view.
|
||||
@@ -15,12 +15,12 @@ This directory contains guidelines for frontend development. Fill in each file w
|
||||
| Guide | Description | Status |
|
||||
|-------|-------------|--------|
|
||||
| [Direct Edit Client](./direct-edit-client.md) | Handle/ghost/preview layer ownership, drag projection, session and save contracts | Filled |
|
||||
| [Directory Structure](./directory-structure.md) | Module organization and file layout | To fill |
|
||||
| [Component Guidelines](./component-guidelines.md) | Component patterns, props, composition | To fill |
|
||||
| [Hook Guidelines](./hook-guidelines.md) | Custom hooks, data fetching patterns | To fill |
|
||||
| [State Management](./state-management.md) | Local state, global state, server state | To fill |
|
||||
| [Quality Guidelines](./quality-guidelines.md) | Code standards, forbidden patterns | To fill |
|
||||
| [Type Safety](./type-safety.md) | Type patterns, validation | To fill |
|
||||
| [Directory Structure](./directory-structure.md) | Module organization and file layout | Filled |
|
||||
| [Component Guidelines](./component-guidelines.md) | Component patterns, props, composition | Filled |
|
||||
| [Hook Guidelines](./hook-guidelines.md) | Custom hooks, data fetching patterns | Filled |
|
||||
| [State Management](./state-management.md) | Local state, global state, server state | Filled |
|
||||
| [Quality Guidelines](./quality-guidelines.md) | Code standards, forbidden patterns | Filled |
|
||||
| [Type Safety](./type-safety.md) | Type patterns, validation | Filled |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -14,6 +14,8 @@ The workbench frontend uses Prettier as the source formatting authority. Code is
|
||||
|
||||
- Do not commit dense, manually minified, or single-line JSX/TypeScript.
|
||||
- Do not hand-format around Prettier output.
|
||||
- Do not leave a page component responsible for unrelated form implementations, API calls, and multiple edit histories after a named component or hook boundary exists.
|
||||
- Do not duplicate an edit protocol while extracting it. Move ownership and update call sites in one change so there is only one active path.
|
||||
|
||||
---
|
||||
|
||||
@@ -22,6 +24,8 @@ The workbench frontend uses Prettier as the source formatting authority. Code is
|
||||
- Run `npm run format` after editing frontend files.
|
||||
- Run `npm run format:check` in the validation gate.
|
||||
- Keep React components, hooks, types, and API clients in separately formatted modules once a component becomes non-trivial.
|
||||
- Keep `App.tsx` as a composition root. New domain behavior belongs in a hook or named component with typed props.
|
||||
- Refactors must preserve API call order, DOM-visible labels/defaults, and OpenLayers map identity unless the task explicitly changes them.
|
||||
|
||||
---
|
||||
|
||||
@@ -35,3 +39,4 @@ The workbench frontend uses Prettier as the source formatting authority. Code is
|
||||
|
||||
- Formatting check passes.
|
||||
- UI behavior changes do not rebuild the OpenLayers map unless the map lifecycle explicitly requires it.
|
||||
- Verify ordinary v1 staged, v2 direct-edit, and traffic-signal draft flows independently; passing one flow does not prove the others survived extraction.
|
||||
@@ -1,3 +1,12 @@
|
||||
# State Management
|
||||
|
||||
Use component `useState` for server state, selection, staged overrides, layer visibility and UI filters. `src/lib/api.ts` is the sole browser HTTP boundary. Keep staged overrides separate from persisted `WorkbenchState.overrides`; save them before compile.
|
||||
Use component `useState` for server state, selection, layer visibility and UI filters. Domain hooks own their draft state: ordinary v1 staged overrides remain separate from persisted `WorkbenchState.overrides`; v2 constraints remain inside `EditSession`; signal drafts remain separate until the signal save step.
|
||||
|
||||
`src/lib/api.ts` is the sole browser HTTP boundary. Presentational components never call it directly. `App` coordinates the fixed save order: ordinary v1 overrides, v2 document, signal draft, then compile and replace server state.
|
||||
|
||||
Whenever App accepts a fresh server `WorkbenchState` (initial load, import, compile,
|
||||
signal generation, or an accepted junction candidate), it must also refresh the
|
||||
signal draft's saved baseline. Otherwise discard can restore an older signal geometry
|
||||
after a later rotation or move.
|
||||
|
||||
Do not duplicate the whole `WorkbenchState` in multiple hooks. Hooks may use `setState` to update their owned slice and refs for non-serializable history, but there must be one current server state and one owner for each undo/redo stack. `lane-maneuver` belongs exclusively to v2 direct edit; it must not re-enter the v1 staged array.
|
||||
@@ -1,3 +1,5 @@
|
||||
# Type Safety
|
||||
|
||||
Define browser contracts in `src/types/state.ts` from actual workbench API payloads. Use `unknown` for extensible GeoJSON properties and comparison payloads, then narrow locally. Run `npm run test:client` after TypeScript changes; avoid `any` and broad assertions.
|
||||
|
||||
Component and hook boundaries must define named prop/return types for commands and domain data. Do not pass an untyped bag of callbacks or expose mutable refs as public props. Keep API payload narrowing in `lib/` or the owning domain adapter, not in each presentational component.
|
||||
@@ -1,21 +0,0 @@
|
||||
# 设计
|
||||
|
||||
技术合约不在本文重复定义。权威定义见父任务 `.trellis/tasks/08-26-direct-manipulation-road-editor/design.md` 的以下小节:
|
||||
|
||||
- 「约束模型」— `junction-approach-width`、`junction-cutback`、`junction-corner-radius` 三个 kind 与其锚点。
|
||||
- 「编辑所有权」— junction reserve 独占、`junction-approach-width` 优先于道路 profile、单 `JunctionRef` 会话。
|
||||
- 「Handle manifest」— 手柄字段与 `reserves`。
|
||||
- 「预览时序与延迟预算」— 防抖、`previewSeq` 仲裁、`degraded`。
|
||||
- 「上线与回滚形态」— `directEdit` 开关。
|
||||
|
||||
会话状态、四态语义与所有权边界的完整推导见父任务 `research/junction-tools.md`。
|
||||
|
||||
## 本子任务的局部决定
|
||||
|
||||
- 工作区是独立路由,不是主地图上的浮层面板:路口编辑是高密度局部操作,叠在主地图上会与道路手柄争夺命中区。
|
||||
- 复用 `direct-edit-map-editor` 的 `EditSession`、ghost/preview source 与命令栈,不新建第二套编辑基础设施。差异只在加载的上下文范围与可用 kind。
|
||||
- 草稿属于活动工作副本的 session,不是独立导出文件。因此「取消」只需丢弃 session,不涉及文件回滚。
|
||||
- 「应用到工作区」不写盘:合并后的约束是活动副本的未保存状态,交给主地图的普通 undo/redo 管理。这样保存路径只有一条。
|
||||
- 会话互斥用显式守卫实现:存在未处理草稿时切换 `JunctionRef` 直接拒绝并提示,不做自动应用或自动丢弃——两者都会让用户丢失意图。
|
||||
- 本期只实现 `JunctionRef.type === 'node'`。`cluster` 分支保留类型但入口置灰,避免把 cluster 降级成多个互相冲突的普通路口编辑。
|
||||
- 单个角部圆角:本期只允许编辑一个 corner,多角部批量编辑属后续任务。
|
||||
@@ -1,41 +0,0 @@
|
||||
# 实施计划
|
||||
|
||||
对应父任务 `implement.md` 的第 7 步。每步一个提交,门禁不过就停。
|
||||
|
||||
前置:`direct-edit-solver-api`(junction 三个 kind 的求解与预览端点)与 `direct-edit-map-editor`(`EditSession`、ghost/preview source、命令栈)均已交付。
|
||||
|
||||
## 1. 工作区路由与上下文加载
|
||||
|
||||
- 目标:能进能回,且不丢全局方位。
|
||||
- 范围:单 `JunctionRef` 路由(本期只走 `node`,`cluster` 入口置灰);从路口面或诊断进入;加载该路口的编辑上下文(路口面、进口、相邻道路短上下文、车道/connector、步行带、停止线、斑马线、诊断、当前约束);返回主地图并恢复位置。
|
||||
- 验证:`npm run test:client`、`npm run build`;手测——从路口面进入、从诊断进入、返回后主地图位置与选中态保持。
|
||||
- 门禁:`cluster` 入口置灰且有原因提示,不落到 node 分支。
|
||||
- 回滚点:纯新增路由,`directEdit` 开关关闭即隐藏入口。
|
||||
|
||||
## 2. 会话状态机与互斥守卫
|
||||
|
||||
- 目标:四态语义先于几何落地,避免后续用几何调试状态。
|
||||
- 范围:`draft` / `applied` / `saved` / `cancelled` 的纯逻辑;未处理草稿时切换 `JunctionRef` 的拒绝守卫;取消复原。复用 `EditSession`,不新建第二套命令栈。
|
||||
- 验证:`npm run test:client:unit` —— draft → 应用后成为主工作区未保存约束;取消后活动副本无残留;存在未处理草稿时切换被拒绝且草稿不丢;应用后的编辑可被主地图 undo/redo 撤销。
|
||||
- 门禁:切换拒绝路径有测试;不存在自动应用或自动丢弃草稿的分支。
|
||||
- 回滚点:纯逻辑模块,revert 后回到第 1 步的只读工作区。
|
||||
|
||||
## 3. 三项可拖能力与完整预览
|
||||
|
||||
- 目标:进口宽度、cutback、单角部圆角真正可编辑,预览覆盖全部受影响对象。
|
||||
- 范围:三类手柄的渲染与拖拽;首次拖拽即 ghost;防抖后服务端局部权威预览;预览覆盖道路面、路口面、步行带、车道中心线、connector/movement、停止线、斑马线、标线;拟合失败返回最后有效几何加结构化诊断。
|
||||
- 验证:`npm run test:client:unit`(手柄事件到三个 kind 的约束值投影)、`npm run test`(局部求解与全量编译对同一约束集结果一致)、`npm run test:client`、`npm run build`;手测——三项各自可拖;预览包含上述全部对象;制造拟合失败时不把非法图形显示成已应用。
|
||||
- 门禁:预览对象清单逐项核对通过;失败态显示最后有效几何而非空白或非法图形。
|
||||
- 回滚点:按 kind 分批提交,可单独回退某一类手柄。
|
||||
|
||||
## 4. 闭环验证
|
||||
|
||||
- 目标:与主工作区和持久化链路接通。
|
||||
- 范围:应用回主地图、保存、重新编译的完整往返;`expectedDocumentVersion` 复用主地图已实现的冲突处理。
|
||||
- 验证:`npm run format:check`、`npm run test`、`npm run test:client`、`npm run test:client:unit`、`npm run build`;手测——应用后返回主地图显示同一几何;保存后重新编译几何不变且约束状态 `exact`。
|
||||
- 门禁:`prd.md` 全部验收标准勾选。
|
||||
- 回滚点:revert 后回到第 3 步的预览-only 状态。
|
||||
|
||||
## 步骤依赖
|
||||
|
||||
1 → 2 → 3 → 4 硬顺序。第 2 步先于第 3 步是刻意的:会话四态若在几何可拖之后才做,取消与互斥的缺陷会被误当成求解问题。
|
||||
@@ -1,41 +0,0 @@
|
||||
# 最小 JunctionTools
|
||||
|
||||
父任务:`.trellis/tasks/08-26-direct-manipulation-road-editor`。需求来源与权威合约在父任务的 `prd.md` / `design.md`。
|
||||
|
||||
## 目标
|
||||
|
||||
用专用工作区承载路口编辑,验证单一普通路口的进口宽度、cutback 与单个角部圆角,闭合"预览 → 应用到工作区 → 保存 → 取消"四态。这是路口能力的最小可信切片,不是完整路口编辑器。
|
||||
|
||||
## 顺序依赖
|
||||
|
||||
前置:`direct-edit-solver-api`(junction 相关的三个 kind 求解与预览端点)与 `direct-edit-map-editor`(`EditSession`、ghost/preview 图层、命令栈)。
|
||||
后继:无。cluster 高级编辑、多路口联动为独立后续任务。
|
||||
|
||||
## 范围
|
||||
|
||||
- 单 `JunctionRef`(`{type:'node'|'cluster', id}`,本期只走 `node`)的工作区路由与返回主地图的上下文保持。
|
||||
- 加载该路口的编辑上下文:路口面、进口、相邻道路短上下文、车道/connector、步行带、停止线、斑马线、诊断与当前约束。
|
||||
- 三项可拖能力:进口宽度、cutback、单个角部圆角。
|
||||
- session draft:首次拖拽即 ghost,防抖后服务端权威局部预览。
|
||||
- 「应用到工作区」合并有效草稿为活动副本的未保存约束;「保存」持久化;「取消」丢弃草稿并复原。
|
||||
- 会话边界:切换相邻路口前必须应用或取消。
|
||||
|
||||
## 不做
|
||||
|
||||
- cluster 的高级编辑与复合路口模板编排。
|
||||
- 多个路口的联合会话或联动编辑。
|
||||
- 控制设施的逐个手工布置。
|
||||
- 主地图道路区间的编辑(属 `direct-edit-map-editor`)。
|
||||
- OSM 图拓扑的修改。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [ ] 从路口面或诊断可进入工作区,并能带位置返回主地图。
|
||||
- [ ] 三项能力各自可拖,首次拖拽即有 ghost,防抖后显示服务端权威几何。
|
||||
- [ ] 预览包含全部受影响派生对象:道路面、路口面、步行带、车道中心线、connector/movement、停止线、斑马线、标线。
|
||||
- [ ] 拟合失败时返回最后有效几何加结构化诊断,不把非法图形显示成已应用。
|
||||
- [ ] 「应用到工作区」后返回主地图仍显示同一几何,且该编辑处于未保存状态、可被主地图 undo/redo 管理。
|
||||
- [ ] 「取消」后回到进入工作区前的状态,活动副本无残留。
|
||||
- [ ] 未处理草稿时切换相邻路口被拒绝,并提示先应用或取消。
|
||||
- [ ] 「保存」后重新编译几何不变,约束状态 `exact`。
|
||||
- [ ] `npm run format:check`、`npm run test`、`npm run test:client`、`npm run test:client:unit`、`npm run build` 全绿。
|
||||
@@ -1,59 +0,0 @@
|
||||
# 斑马线元素级编辑器设计
|
||||
|
||||
## 架构边界
|
||||
|
||||
本实验扩展现有直接编辑链路,而非建立画布对象存储:
|
||||
|
||||
```text
|
||||
crosswalk feature 点击
|
||||
-> elementId
|
||||
-> element manifest (anchor + parameters + legal controls)
|
||||
-> native-road-edits/v2 constraint
|
||||
-> resolveDirectEditConstraints
|
||||
-> compileControlMarkings
|
||||
-> preview / save / recompile
|
||||
```
|
||||
|
||||
`elementId` 是选择和分组标识;持久化仍使用稳定语义 anchor 上的 constraint。它不能是 GeoJSON 数组下标、屏幕坐标或临时 UUID。
|
||||
|
||||
## 选择合同
|
||||
|
||||
斑马线的每一条 stripe feature 必须包含 `native_id`、`element_id` 与可回链的 crossing / approach 身份。选择适配层只读取 `element_id`,再向服务器取得选中元素的权威 manifest。客户端不会据条带数量、空间距离或渲染顺序自行聚类。
|
||||
|
||||
元素 manifest 至少包含:
|
||||
|
||||
```ts
|
||||
interface EditableElement {
|
||||
elementId: string
|
||||
kind: 'crosswalk'
|
||||
anchor: { type: 'junction-approach'; nodeId: string; segmentId: string }
|
||||
featureIds: string[]
|
||||
controls: Array<{
|
||||
kind: 'position' | 'length' | 'width'
|
||||
value: { current: number; min: number; max: number; unit: 'meter' }
|
||||
axisAzimuth?: number
|
||||
}>
|
||||
fields: Array<{ key: string; value: number; min: number; max: number; unit: 'meter' | 'count' }>
|
||||
}
|
||||
```
|
||||
|
||||
第一阶段只发布 `position` 及其现有 `junction-crosswalk-inset` 回写规则。第二阶段再加入尺寸和条带参数,避免在实验开始前规定尚未验证的通用元素协议。
|
||||
|
||||
## 编辑与预览
|
||||
|
||||
- 选择由 `MapCanvas` 的 feature 事件产生,但选择状态由 App/编辑会话持有,不能写入 baseline source。
|
||||
- 元素控件写入的是 manifest 指定的 constraint kind/value;表单复用同一写入器。
|
||||
- 选中框和控件只是 `editHandles` / `editGhost` 层的临时 UI;权威预览仍由服务端返回,baseline source 不被客户端改写。
|
||||
- 空白点击会清除元素选择;道路选择可继续决定道路级 handle manifest。斑马线元素选中与道路选择可并存,但两组控件不得重叠或竞争同一 pointer 手势。
|
||||
|
||||
## 数据演进
|
||||
|
||||
第一阶段不新增 persisted schema:位置继续使用已有 `junction-crosswalk-inset`。第二阶段如果确实需要尺寸参数,新增一个专属 kind 或扩展同一 kind 的严格 schema 校验;具体选择以第一阶段运行结果为准,不预先固化。
|
||||
|
||||
缺省参数必须字节级保持现有斑马线输出。参数越界、条带间互相重叠或越过可用进口范围均返回 blocking diagnostic,不在客户端静默钳制真实约束。
|
||||
|
||||
## 兼容与回滚
|
||||
|
||||
- 无新 constraint 时,编译输出与当前版本一致。
|
||||
- `directEdit` 关闭时不请求 element manifest、不安装元素选择交互、不产生额外图层。
|
||||
- 第一阶段每个步骤独立提交;回滚元素 UI 或 manifest 不影响既有道路级控制。
|
||||
@@ -1,49 +0,0 @@
|
||||
# 实施计划
|
||||
|
||||
## 0. 建立事实与测试夹具
|
||||
|
||||
- 追踪 `compileControlMarkings()` 的每条 stripe 属性、`native_id` 构成和从地图点击到 `onFeature` 的路径。
|
||||
- 添加失败优先的测试:同组 stripe 需要稳定共享 `elementId`,不同 crossing 不得共享;空编辑输出与基线一致。
|
||||
- 门禁:能证明一个具体 feature 无歧义回链到一个 junction approach 和 crossing。
|
||||
|
||||
## 1. 第一阶段:元素 manifest 与选择
|
||||
|
||||
- 在编译器为 crosswalk stripe 写稳定的元素标识和回链属性。
|
||||
- 在 direct-edit 服务响应中增量发布按 selection/element 获取的元素 manifest,不扩大现有道路 handle 的职责。
|
||||
- 客户端建立 `ElementSelection` 纯状态与 feature 点击适配;点击 stripe 选择整组、空白清除。
|
||||
- 验证:编译器单元测试、API 测试、客户端 selection 单元测试。
|
||||
|
||||
## 2. 第一阶段:位置编辑闭环
|
||||
|
||||
- 用 element manifest 的 position control 渲染元素级控件和选中外框;安装时不得影响道路 handle hit-test。
|
||||
- 从位置手势和表单走同一个 draft builder,写入 `junction-crosswalk-inset`。
|
||||
- 验证:拖拽与表单值生成同形约束;预览/保存/重载一致;`exact` 状态和撤销/重做覆盖。
|
||||
- 门禁:一次非空编辑可在正式重编译结果中观察到斑马线位置变化。失败即停止,不能只交付 UI。
|
||||
|
||||
## 3. 复盘门禁
|
||||
|
||||
- 手测选中、取消、道路级手柄共存、拖拽钳位、表单验证、保存重载。
|
||||
- 只有在第一阶段验收全部通过后,才能为尺寸/外观参数做持久化 schema 决策。
|
||||
|
||||
## 4. 第二阶段:尺寸与外观
|
||||
|
||||
- 依据第一阶段证据设计并验证长度、宽度、条带数、间距的约束 schema。
|
||||
- 编译器读取参数、返回 blocking diagnostics;元素 manifest 表达对应控件/字段。
|
||||
- 实现与表单字段完全一致的尺寸控件,补齐组合参数、持久化和 rebase 测试。
|
||||
|
||||
## 验证命令
|
||||
|
||||
```sh
|
||||
npm run format:check
|
||||
npm run test
|
||||
npm run test:client
|
||||
npm run test:client:unit
|
||||
npm run build
|
||||
```
|
||||
|
||||
## 风险文件
|
||||
|
||||
- `src/compile/native-road.js`:斑马线生成与默认输出兼容性。
|
||||
- `src/compile/direct-edit-solver.js` / `native-road-edits.js`:约束求解、schema 和 manifest 必须同步。
|
||||
- `workbench/server.js`:element manifest 查询与 preview 不得写入磁盘。
|
||||
- `workbench/client/src/components/MapCanvas.tsx`、`App.tsx`、`edit/`:选择、临时控件和表单不得污染 baseline layer。
|
||||
@@ -0,0 +1,2 @@
|
||||
{"file":".trellis/tasks/09-23-complex-junction-interior-line/prd.md","reason":"Acceptance criteria cover the white-line screenshot regression and ordinary-marking compatibility."}
|
||||
{"file":".trellis/tasks/09-23-complex-junction-interior-line/design.md","reason":"Provides the data-flow and compatibility checks for review."}
|
||||
@@ -0,0 +1,41 @@
|
||||
# Design
|
||||
|
||||
## Boundary
|
||||
|
||||
The compiler must publish complex-junction white road markings only on the
|
||||
approach side of the first generated crosswalk or stop line. The central
|
||||
junction pavement and zebra crossing remain free of those markings.
|
||||
|
||||
## Data Flow
|
||||
|
||||
1. Complex junction templates produce approach lane preview lines and control
|
||||
polygons (`crosswalks` and `stopLines`).
|
||||
2. `compileComplexLaneSeparators` derives white lane-separator geometry from
|
||||
preview lanes. This is the layer shown by the screenshot.
|
||||
3. `compileCenterLines` derives center-line marking geometry from the trimmed
|
||||
bidirectional approach line.
|
||||
4. Both paths use `trimLineBeforeFirstControl`; complex lines must first be
|
||||
oriented from the exterior toward the cluster center, then restored to their
|
||||
published direction.
|
||||
|
||||
## Implementation Shape
|
||||
|
||||
Reuse the existing center-aware `trimLaneOutsideControls` behavior (or extract
|
||||
its orientation step into a small shared helper) for complex preview and center
|
||||
lines. For complex lane separators, also trim against the stable published
|
||||
approach/core boundary so a control polygon that ends short of the core cannot
|
||||
leave an interior tail. Ordinary roads keep the existing behavior. All cutoffs
|
||||
remain driven by published geometry, with no cluster-specific coordinates.
|
||||
|
||||
## Compatibility
|
||||
|
||||
- Preserve feature identities, styles, source road IDs, and signal layers.
|
||||
- Do not change connector or lane-solving coordinates; only published marking
|
||||
geometry is clipped.
|
||||
- Ordinary-junction trimming remains unchanged.
|
||||
|
||||
## Risks
|
||||
|
||||
If the first control polygon is malformed or absent, the existing full-line
|
||||
fallback remains in place. Tests must cover both line orientations so a future
|
||||
OSM way direction cannot reintroduce the bug.
|
||||
@@ -0,0 +1,2 @@
|
||||
{"file":".trellis/tasks/09-23-complex-junction-interior-line/design.md","reason":"Defines the center-aware clipping contract for complex white markings."}
|
||||
{"file":".trellis/tasks/09-23-complex-junction-interior-line/implement.md","reason":"Lists the ordered implementation and validation work."}
|
||||
@@ -0,0 +1,27 @@
|
||||
# Implementation Plan
|
||||
|
||||
1. Add a focused geometry regression for the `8005332807` complex cluster that
|
||||
identifies white marking features and asserts their published geometry does
|
||||
not overlap generated crosswalk/stop-line controls or the interior side of
|
||||
the approach boundary.
|
||||
2. Update complex center-line and preview lane-separator trimming to orient by
|
||||
cluster center before applying the first-control cutoff.
|
||||
3. Add an opposite-direction synthetic/control assertion proving ordinary
|
||||
junction markings retain their current behavior.
|
||||
4. Run focused junction marking tests, then the full test suite and diff checks.
|
||||
|
||||
## Validation
|
||||
|
||||
- `node test/junction-corridor-markings.js`
|
||||
- `node test/junction-marking-containment.js`
|
||||
- `node test/junction-layer-seams.js`
|
||||
- `npm test`
|
||||
- `git diff --check`
|
||||
|
||||
## Risky Files
|
||||
|
||||
- `src/compile/native-road.js`
|
||||
- `test/junction-corridor-markings.js` or the closest existing geometry test
|
||||
|
||||
Do not update fixture baselines unless the final behavior change is reviewed
|
||||
and explicitly intended.
|
||||
@@ -0,0 +1,64 @@
|
||||
# Fix Complex Junction Interior Line for cluster-8005332807
|
||||
|
||||
## Goal
|
||||
|
||||
Prevent a white lane marking from crossing the zebra crossing and extending into
|
||||
the interior of a complex junction. The visible result must match the user's
|
||||
screenshot for `cluster-8005332807` and must not regress ordinary-junction
|
||||
markings.
|
||||
|
||||
## Confirmed Facts
|
||||
|
||||
- The reported line is white in the workbench screenshot, so it is a road
|
||||
marking layer rather than the dark/magenta signal or connector overlays.
|
||||
- The affected geometry is in the complex-junction cluster containing node
|
||||
`8005332807`; the screenshot shows the marking continuing inward past a
|
||||
zebra crossing toward the central pavement region.
|
||||
- Complex lane separators are generated separately from ordinary road
|
||||
separators in `src/compile/native-road.js` and are expected to stop at
|
||||
complex-junction controls and boundaries.
|
||||
- `trimLineBeforeFirstControl` assumes its input starts at the exterior and
|
||||
proceeds toward the junction. Complex preview/center lines can be supplied
|
||||
in the opposite direction, so the current code can preserve the interior
|
||||
segment instead of the approach segment.
|
||||
- The screenshot's white line is specifically published as
|
||||
`native-road-complex-lane-separator/v1` by `compileComplexLaneSeparators`,
|
||||
not as a signal or center-line overlay. That path clips against controls but
|
||||
does not independently enforce the complex core boundary.
|
||||
- Existing worktree changes are unrelated user work and must be preserved.
|
||||
|
||||
## Requirements
|
||||
|
||||
- R1. In a complex-junction view, the affected white lane marking must stop
|
||||
before it crosses the zebra crossing or enters the configured junction
|
||||
interior region.
|
||||
- R2. The fix must be derived from the actual complex-junction geometry,
|
||||
crossing controls, or their stable published boundary, not from a
|
||||
cluster-specific coordinate or screenshot-only special case.
|
||||
- R3. Lane markings outside the affected complex-junction segment, including
|
||||
ordinary-junction markings, must remain unchanged.
|
||||
- R4. Add a regression covering `cluster-8005332807` and a control case proving
|
||||
ordinary-junction marking generation remains unchanged.
|
||||
|
||||
## Technical Decision
|
||||
|
||||
Orient complex marking lines by distance from the cluster center before
|
||||
applying the existing first-control trim, then enforce the published complex
|
||||
approach/core boundary before restoring their original direction. This keeps
|
||||
the fix geometry-driven and leaves ordinary road trimming untouched.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] The reported white marking no longer crosses the zebra crossing or
|
||||
enters the complex-junction interior in the workbench image.
|
||||
- [ ] No affected white marking segment published for the complex cluster lies
|
||||
inside its configured crossing/interior boundary; geometry remains finite
|
||||
and stable.
|
||||
- [ ] Existing signal, marking, and complex-junction behavior remains intact,
|
||||
including the affected real OSM fixture.
|
||||
|
||||
## Scope Boundary
|
||||
|
||||
- In scope: complex-junction white lane-marking geometry and its regression.
|
||||
- Out of scope: traffic-signal phase logic, OSM source editing, free signal
|
||||
creation/deletion, vehicle simulation, and unrelated road or island geometry.
|
||||
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"id": "complex-junction-interior-line",
|
||||
"name": "complex-junction-interior-line",
|
||||
"title": "Fix complex junction interior line for cluster-8005332807",
|
||||
"description": "",
|
||||
"status": "in_progress",
|
||||
"dev_type": null,
|
||||
"scope": null,
|
||||
"package": null,
|
||||
"priority": "P2",
|
||||
"creator": "dingkang",
|
||||
"assignee": "dingkang",
|
||||
"createdAt": "2026-09-23",
|
||||
"completedAt": null,
|
||||
"branch": null,
|
||||
"base_branch": "main",
|
||||
"worktree_path": null,
|
||||
"commit": null,
|
||||
"pr_url": null,
|
||||
"subtasks": [],
|
||||
"children": [],
|
||||
"parent": null,
|
||||
"relatedFiles": [],
|
||||
"notes": "",
|
||||
"meta": {}
|
||||
}
|
||||
File renamed without changes.
@@ -0,0 +1,34 @@
|
||||
# 总体设计
|
||||
|
||||
## 边界
|
||||
|
||||
`JunctionTools` 是主地图之外的局部编辑器。主地图只负责显示派生热区和进入入口;编辑器负责一个 `JunctionRef` 的上下文、草稿、预览、应用、保存和取消。
|
||||
|
||||
## 数据流
|
||||
|
||||
`compiled model/junctionPlans` → `junction descriptors` → `hotspot layer` → `JunctionRef` → `junction session` → `semantic constraints` → `/api/edit-preview` → affected layers → apply/save → active document/revision。
|
||||
|
||||
热区是派生显示对象,不新增持久化 schema。node 使用 node id,cluster 使用 cluster id 加 arm/corner 锚点。所有长度使用米,位置锚定 station 或 OSM node。
|
||||
|
||||
## 编辑器分层
|
||||
|
||||
- `junction-detection`:纯逻辑识别 descriptor、状态和热区几何。
|
||||
- `junction-workspace`:路由、上下文加载、session 四态和主地图返回。
|
||||
- `junction-solver`:把 node/cluster 约束归一为 effective plan,供普通与复杂几何共同消费。
|
||||
- `junction-facilities`:设施联动、诊断汇总和发布前检查。
|
||||
- OpenLayers 仅作为显示/输入 adapter,不能直接写正式编译 source。
|
||||
|
||||
## 首期决策约束
|
||||
|
||||
- `JunctionRef` 首期只允许 `type: 'node'` 进入可编辑 session;`cluster` 和 `candidate` descriptor 可展示但不可写入。
|
||||
- 工作区与主地图共享 undo/redo 栈;一次“应用到工作区”是一个历史边界,拖拽过程只产生 draft/preview。
|
||||
- 工作区离开由显式守卫控制:有未处理草稿时必须应用、放弃或取消离开;不得静默处理草稿。
|
||||
- 保存请求必须携带打开时的文档/编译版本。版本不一致返回冲突,保留本地草稿,不做强制覆盖或隐式 rebase。
|
||||
- 阶段 B 的求解写入仅覆盖三种既有 junction constraint;车道、connector 和设施在此阶段只作为派生上下文与诊断输入。
|
||||
- 设施编辑只允许修改已有设施的语义 override,不新增或删除设施身份。
|
||||
- 诊断接口必须提供稳定 `code` 和 `severity`,几何非法为 `blocking`,非致命设施问题可为 `warning`。
|
||||
- JunctionTools 通过独立路由承载 `JunctionRef`,路由变化不得重建 `MapCanvas`,返回时恢复主地图视角和选择快照。
|
||||
|
||||
## 兼容与回滚
|
||||
|
||||
阶段 A/B 可挂在现有编辑开关下;未进入 JunctionTools 时主地图行为不变。cluster 几何统一前不得开放 cluster 写入。任何阶段失败都可回退到只读热区或现有普通路口编辑,不影响 v1 overrides、v2 文档和导出包。
|
||||
File renamed without changes.
@@ -0,0 +1,10 @@
|
||||
# 执行计划
|
||||
|
||||
1. 完成 RoadRunner 对标和本项目需求基线,冻结术语、范围、验收。
|
||||
2. 实现纯逻辑 junction descriptor 与热区显示;普通 node 可进入,candidate/cluster 状态明确。
|
||||
3. 建立独立 JunctionTools 路由与上下文快照,闭合 draft/apply/save/cancel 和返回主地图。
|
||||
4. 统一 node/cluster 的 effective junction plan,让宽度、cutback、圆角真正驱动同一套几何预览。
|
||||
5. 接入车道、connector、斑马线、停止线、信号灯的联动诊断和发布校验。
|
||||
6. 运行全量服务端、客户端、E2E、导出契约测试,完成用户复核后再提交。
|
||||
|
||||
每一步先写纯逻辑测试,再接 UI;不使用绝对像素作为核心契约,不自动提交。
|
||||
@@ -0,0 +1,110 @@
|
||||
# JunctionTools 路口编辑工作区
|
||||
|
||||
父任务:`.trellis/tasks/08-26-direct-manipulation-road-editor`。需求来源与权威合约在父任务的 `prd.md` / `design.md`。
|
||||
|
||||
## 目标
|
||||
|
||||
用地图上的可识别路口区域作为入口,进入一个独立的 JunctionTools 路口编辑页面。页面专注展示单个路口及其完整局部上下文,在同一可视化画布和同一编辑会话中同时承载路口几何、已有设施、参数双向联动、预览和诊断。主地图只负责发现、导航和返回,不承载完整路口编辑体验。
|
||||
|
||||
## 当前产品设想
|
||||
|
||||
- 主地图识别普通路口和已配置的复杂路口 cluster,并以可点击热区表达,而不是依赖点击某一条道路或控制柄。
|
||||
- 点击热区后进入独立 JunctionTools 编辑器,聚焦路口局部上下文;返回主地图时保留原地图视角、选中对象和未保存编辑。
|
||||
- 编辑器首版即作为一体化路口工作区:进口宽度、cutback、角部圆角、路口面、车道/connector、斑马线、停止线、信号灯和诊断在同一 session 中协调;内部可以分区,但用户不需要跨页面切换。
|
||||
- 所有编辑复用现有 direct-edit 文档、preview、revision、undo/redo 和导出契约,不建立第二套持久化几何。
|
||||
|
||||
## RoadRunner 对标拆解
|
||||
|
||||
RoadRunner 的路口能力不能简化成几个拖拽手柄。对本项目有价值的能力可拆成四层:
|
||||
|
||||
1. 路口识别与入口:从相交道路形成可识别的 junction 对象,并在场景中提供明确的选择目标。
|
||||
2. 局部工作区:聚焦一个路口,显示进口、边界、车道、连接关系、标线和诊断,编辑完成后回到整体场景。
|
||||
3. 几何与拓扑编辑:调整进口宽度、路口边界、转角圆角、车道连接和车道数,并让派生几何保持连续、合法。
|
||||
4. 设施与验证:在路口上下文中布置或调整停止线、斑马线、信号灯等设施,并对冲突、自交、车道宽度和连接状态给出反馈。
|
||||
|
||||
本项目的映射不是复制 RoadRunner 内部实现:OSM 中心线和拓扑是只读输入,GeoJSON 是派生输出;可持久化的对象必须是 node/cluster 锚定的语义约束。当前代码已经具备 cluster candidate 检测、complex-junction 几何生成、三类 junction 约束和 preview/save/revision 基础,但缺少“热区 → JunctionTools 工作区”的产品层闭环。
|
||||
|
||||
## 分阶段方向
|
||||
|
||||
- 阶段 A:派生路口热区和识别状态(普通 node、已确认 cluster、候选 cluster),点击后进入/返回工作区。
|
||||
- 阶段 B:独立单路口页面、局部上下文和现有三项几何参数编辑闭环。
|
||||
- 阶段 C:在同一页面接入车道/connector、斑马线、停止线、信号灯的联动编辑和冲突诊断;这是实现顺序,不是拆开的产品功能。
|
||||
- 阶段 D:cluster 多节点、多进口、多角部及更接近 RoadRunner 的拓扑创作能力。
|
||||
|
||||
阶段 A 不应把热区写成新的几何事实;它应由编译模型和 junction plan 派生,避免出现 UI 有路口而编译器不认的第二套数据。
|
||||
|
||||
## 本轮已决边界
|
||||
|
||||
- 首期只有普通 `node` 可编辑;已确认 `cluster` 只读,`candidate cluster` 只展示识别结果与诊断。
|
||||
- 阶段 B 只开放进口宽度、cutback、单角部圆角;车道/connector 先展示并诊断,不开放拓扑写入。
|
||||
- 设施首期允许移动或修改已有斑马线、停止线、信号灯,但不允许创建或删除设施。
|
||||
- “应用到工作区”形成一个 undo 步骤,并进入主地图共用历史栈;连续拖拽不逐帧进入 undo。
|
||||
- 离开工作区前必须选择应用并返回、放弃并返回或留在工作区,不自动应用或自动放弃。
|
||||
- 保存时若编译模型或文档版本变化,拒绝保存并保留草稿,要求重新加载后处理,不自动覆盖或自动 rebase。
|
||||
- candidate 不得在本轮被确认或转化为持久化 cluster。
|
||||
- 自交、越界、最小车道宽度等几何非法诊断为 `blocking`;可修复的设施缺失或间距问题可为 `warning`。
|
||||
- JunctionTools 使用独立 URL 路由,例如 `/junction/:type/:id`,支持刷新、浏览器返回和深链接。
|
||||
|
||||
## 总体约束
|
||||
|
||||
- OSM 节点、道路中心线和基础拓扑只读;编辑保存语义约束,不保存派生 GeoJSON。
|
||||
- 普通 node 与复杂 cluster 使用不同的 `JunctionRef` 锚点,不把 cluster 降级成多个普通 node。
|
||||
- 热区、路口边界和可编辑对象必须来自同一份编译状态;候选识别不能静默改变几何。
|
||||
- 路口编辑必须复用现有 preview、active document、revision、版本冲突保护和 undo/redo。
|
||||
- 无效几何不得替换最后有效预览;必须返回结构化诊断。
|
||||
- 路口 session 与主地图 session 互斥,切换对象前必须应用或取消草稿。
|
||||
- 导出包契约保持 `native-road-package/v1.1` 不变。
|
||||
|
||||
## 子任务地图
|
||||
|
||||
1. `09-02-junction-requirements-research`:RoadRunner 能力、用户流程、术语和需求验收基线。
|
||||
2. `09-02-junction-detection-hotspot`:node/cluster/candidate 识别、热区派生模型和点击入口。
|
||||
3. `09-02-junction-tools-workspace`:独立工作区路由、上下文加载、返回和 session 状态机。
|
||||
4. `09-02-junction-geometry-editor`:进口宽度、cutback、圆角、车道/connector 的统一求解与预览。
|
||||
5. `09-02-junction-facilities-validation`:斑马线、停止线、信号灯联动、诊断和最终发布验证。
|
||||
|
||||
依赖顺序为 1 → 2 → 3 → 4 → 5;每个子任务独立验收,父任务负责跨任务契约和最终集成。
|
||||
|
||||
## 顺序依赖
|
||||
|
||||
前置:`direct-edit-solver-api`(junction 相关的三个 kind 求解与预览端点)与 `direct-edit-map-editor`(`EditSession`、ghost/preview 图层、命令栈)。
|
||||
后继:无。cluster 高级编辑、多路口联动为独立后续任务。
|
||||
|
||||
## 范围
|
||||
|
||||
- 路口识别结果和热区入口的最小交互。
|
||||
- 单 `JunctionRef`(`{type:'node'|'cluster', id}`)的工作区路由与返回主地图的上下文保持;首期只有 `node` 进入可编辑 session,`cluster` 与 candidate 只读。
|
||||
- 加载该路口的编辑上下文:路口面、进口、相邻道路短上下文、车道/connector、步行带、停止线、斑马线、诊断与当前约束。
|
||||
- 三项可拖能力:进口宽度、cutback、单个角部圆角。
|
||||
- session draft:首次拖拽即 ghost,防抖后服务端权威局部预览。
|
||||
- 「应用到工作区」合并有效草稿为活动副本的未保存约束;「保存」持久化;「取消」丢弃草稿并复原。
|
||||
- 会话边界:切换相邻路口前必须应用或取消。
|
||||
|
||||
## 不做
|
||||
|
||||
- cluster 的高级编辑与复合路口模板编排。
|
||||
- 多个路口的联合会话或联动编辑。
|
||||
- 控制设施的新建、删除和身份创建;首期只允许修改已有设施的语义参数。
|
||||
- 主地图道路区间的编辑(属 `direct-edit-map-editor`)。
|
||||
- OSM 图拓扑的修改。
|
||||
- 一次性实现 RoadRunner 级别的完整路口建模、任意拓扑创作或多路口联合编辑。
|
||||
|
||||
## 验收标准
|
||||
|
||||
### 独立一体化页面方向(2026-09-03)
|
||||
|
||||
- [ ] `/junction/:type/:id` 是独立路口编辑页面,进入后自动聚焦单个路口;主地图只作为入口和返回目标。
|
||||
- [ ] 页面画布持续展示路口几何与已有斑马线、停止线、信号灯,参数面板不得遮挡主要路口视图。
|
||||
- [ ] 几何参数和已有设施调整在同一页面、同一 draft/preview/undo/apply/save/cancel 链路中完成。
|
||||
- [ ] 表单与地图操作双向同步:表单修改反映到画布,地图拖拽回写参数;失败预览保留最后有效几何并显示诊断。
|
||||
- [ ] 首版支持已有设施的移动或已有字段修改,不创建、删除或跨路口迁移设施;cluster 与 candidate 继续只读。
|
||||
|
||||
- [ ] 从路口面或诊断可进入工作区,并能带位置返回主地图。
|
||||
- [ ] 三项能力各自可拖,首次拖拽即有 ghost,防抖后显示服务端权威几何。
|
||||
- [ ] 预览包含全部受影响派生对象:道路面、路口面、步行带、车道中心线、connector/movement、停止线、斑马线、标线。
|
||||
- [ ] 拟合失败时返回最后有效几何加结构化诊断,不把非法图形显示成已应用。
|
||||
- [ ] 「应用到工作区」后返回主地图仍显示同一几何,且该编辑处于未保存状态、可被主地图 undo/redo 管理。
|
||||
- [ ] 「取消」后回到进入工作区前的状态,活动副本无残留。
|
||||
- [ ] 未处理草稿时切换相邻路口被拒绝,并提示先应用或取消。
|
||||
- [ ] 「保存」后重新编译几何不变,约束状态 `exact`。
|
||||
- [ ] `npm run format:check`、`npm run test`、`npm run test:client`、`npm run test:client:unit`、`npm run build` 全绿。
|
||||
+9
-3
@@ -3,7 +3,7 @@
|
||||
"name": "direct-edit-junction-tools",
|
||||
"title": "最小 JunctionTools",
|
||||
"description": "单一普通路口的进口宽度、cutback、单角部圆角与预览/应用/取消",
|
||||
"status": "planning",
|
||||
"status": "completed",
|
||||
"dev_type": null,
|
||||
"scope": null,
|
||||
"package": null,
|
||||
@@ -11,14 +11,20 @@
|
||||
"creator": "dingkang",
|
||||
"assignee": "dingkang",
|
||||
"createdAt": "2026-08-26",
|
||||
"completedAt": null,
|
||||
"completedAt": "2026-09-04",
|
||||
"branch": null,
|
||||
"base_branch": "main",
|
||||
"worktree_path": null,
|
||||
"commit": null,
|
||||
"pr_url": null,
|
||||
"subtasks": [],
|
||||
"children": [],
|
||||
"children": [
|
||||
"09-02-junction-requirements-research",
|
||||
"09-02-junction-detection-hotspot",
|
||||
"09-02-junction-tools-workspace",
|
||||
"09-02-junction-geometry-editor",
|
||||
"09-02-junction-facilities-validation"
|
||||
],
|
||||
"parent": "08-26-direct-manipulation-road-editor",
|
||||
"relatedFiles": [],
|
||||
"notes": "",
|
||||
@@ -0,0 +1,154 @@
|
||||
<!doctype html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>JunctionTools UI Prototype</title>
|
||||
<style>
|
||||
:root {
|
||||
color: #dfe9e5;
|
||||
background: #101a18;
|
||||
font-family: Inter, ui-sans-serif, system-ui, -apple-system, sans-serif;
|
||||
}
|
||||
* { box-sizing: border-box; }
|
||||
body { margin: 0; min-width: 1080px; }
|
||||
button, input { font: inherit; }
|
||||
button { cursor: pointer; }
|
||||
.app { min-height: 100vh; display: grid; grid-template-rows: 64px 1fr 38px; }
|
||||
.topbar { display: flex; align-items: center; gap: 22px; padding: 0 22px; background: #173b32; border-bottom: 1px solid #2d594d; }
|
||||
.brand { letter-spacing: .14em; font-size: 12px; color: #95b5aa; text-transform: uppercase; }
|
||||
.title { font-size: 18px; font-weight: 700; color: #f5fbf8; }
|
||||
.crumb { color: #9eb9ae; font-size: 13px; }
|
||||
.topbar-spacer { flex: 1; }
|
||||
.top-action { border: 1px solid #6d988a; color: #e9f4ef; background: transparent; padding: 8px 12px; border-radius: 4px; }
|
||||
.top-action.primary { background: #d3e9df; border-color: #d3e9df; color: #183a31; font-weight: 700; }
|
||||
.workspace { min-height: 0; display: grid; grid-template-columns: minmax(0, 1fr) 360px; }
|
||||
.canvas { position: relative; overflow: hidden; background: #d9dfda; }
|
||||
.canvas-head { position: absolute; z-index: 2; left: 20px; top: 18px; display: flex; gap: 8px; }
|
||||
.chip { border: 1px solid #b3c0ba; background: #eff4f0e8; color: #29483e; border-radius: 4px; padding: 7px 10px; font-size: 12px; box-shadow: 0 2px 8px #263b3222; }
|
||||
.chip.active { border-color: #2f755d; background: #e0f1e8; color: #205a45; }
|
||||
.map-svg { position: absolute; inset: 0; width: 100%; height: 100%; }
|
||||
.map-label { font-size: 13px; fill: #345448; font-weight: 700; }
|
||||
.map-note { position: absolute; left: 20px; bottom: 18px; padding: 9px 12px; color: #3c574d; background: #eef3efdf; border: 1px solid #b8c7bf; border-radius: 4px; font-size: 12px; }
|
||||
.inspector { overflow: auto; padding: 20px 18px; background: #f7faf8; color: #20352d; border-left: 1px solid #cad9d1; }
|
||||
.section { padding-bottom: 18px; margin-bottom: 18px; border-bottom: 1px solid #dbe6e0; }
|
||||
.section:last-child { border-bottom: 0; }
|
||||
.section-title { margin: 0 0 12px; font-size: 14px; color: #173b32; }
|
||||
.section-subtitle { margin: -5px 0 12px; color: #71847b; font-size: 12px; }
|
||||
.field { display: grid; grid-template-columns: 1fr 104px; gap: 10px; align-items: center; margin: 11px 0; }
|
||||
.field label { font-size: 13px; }
|
||||
.field small { display: block; color: #82938b; font-size: 11px; margin-top: 3px; }
|
||||
.field input { width: 100%; border: 1px solid #aabdb3; border-radius: 3px; padding: 7px 8px; color: #173b32; background: white; text-align: right; }
|
||||
.unit { position: relative; }
|
||||
.unit span { position: absolute; right: 8px; top: 8px; color: #7c9187; font-size: 12px; pointer-events: none; }
|
||||
.unit input { padding-right: 28px; }
|
||||
.range { height: 4px; margin: 6px 0 0; border-radius: 10px; background: #c9d9d1; }
|
||||
.range i { display: block; width: 57%; height: 100%; background: #3d8b6c; border-radius: 10px; }
|
||||
.facility { display: flex; justify-content: space-between; align-items: center; padding: 9px 0; border-top: 1px solid #e5ede8; font-size: 13px; }
|
||||
.facility:first-of-type { border-top: 0; }
|
||||
.facility strong { color: #245b47; }
|
||||
.status { display: flex; align-items: center; gap: 8px; color: #2e7558; font-size: 12px; }
|
||||
.dot { width: 8px; height: 8px; border-radius: 50%; background: #3d9a6c; }
|
||||
.diagnostic { padding: 9px 10px; background: #edf5f0; border-left: 3px solid #3d8b6c; color: #45665a; font-size: 12px; line-height: 1.5; }
|
||||
.actions { display: flex; gap: 8px; }
|
||||
.action { flex: 1; padding: 9px 8px; border: 1px solid #9bb2a7; border-radius: 3px; background: white; color: #245241; }
|
||||
.action.main { background: #286b52; color: white; border-color: #286b52; }
|
||||
.footer { display: flex; align-items: center; gap: 18px; padding: 0 20px; background: #18322b; color: #b7cdc3; font-size: 12px; }
|
||||
.footer strong { color: #e1f1ea; }
|
||||
.legend { margin-left: auto; display: flex; gap: 14px; }
|
||||
.legend span::before { content: ''; display: inline-block; width: 9px; height: 9px; margin-right: 5px; border-radius: 50%; background: currentColor; }
|
||||
.legend .geometry { color: #2f7e61; }
|
||||
.legend .facility-dot { color: #b1783c; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="app">
|
||||
<header class="topbar">
|
||||
<span class="brand">JunctionTools</span>
|
||||
<span class="title">路口节点 1140799919</span>
|
||||
<span class="crumb">独立编辑页面 / 普通路口</span>
|
||||
<span class="topbar-spacer"></span>
|
||||
<button class="top-action">撤销</button>
|
||||
<button class="top-action">重做</button>
|
||||
<button class="top-action">返回主地图</button>
|
||||
<button class="top-action primary">保存并重新生成</button>
|
||||
</header>
|
||||
|
||||
<main class="workspace">
|
||||
<section class="canvas" aria-label="路口可视化画布">
|
||||
<div class="canvas-head">
|
||||
<span class="chip active">路口几何</span>
|
||||
<span class="chip">斑马线</span>
|
||||
<span class="chip">停止线</span>
|
||||
<span class="chip">信号灯</span>
|
||||
</div>
|
||||
<svg class="map-svg" viewBox="0 0 900 700" role="img" aria-label="单个路口及其设施预览">
|
||||
<rect width="900" height="700" fill="#d9dfda" />
|
||||
<path d="M0 285 H900 V415 H0 Z" fill="#7e8987" />
|
||||
<path d="M385 0 H515 V700 H385 Z" fill="#7e8987" />
|
||||
<path d="M0 280 H900 M0 420 H900 M380 0 V700 M520 0 V700" stroke="#d5dcda" stroke-width="3" />
|
||||
<path d="M0 350 H900 M450 0 V700" stroke="#f4f5ed" stroke-width="2" stroke-dasharray="14 13" opacity=".7" />
|
||||
<path d="M320 285 H580 V415 H320 Z" fill="#697673" stroke="#286b52" stroke-width="4" stroke-dasharray="9 7" />
|
||||
<g fill="#f5f8ef">
|
||||
<path d="M346 265 h75 v12 h-75z M346 423 h75 v12 h-75z" />
|
||||
<path d="M479 265 h75 v12 h-75z M479 423 h75 v12 h-75z" />
|
||||
<path d="M305 305 h12 v90 h-12z M573 305 h12 v90 h-12z" />
|
||||
</g>
|
||||
<g stroke="#e8eee9" stroke-width="9" opacity=".95">
|
||||
<path d="M347 286 V330 M365 286 V330 M383 286 V330 M401 286 V330" />
|
||||
<path d="M499 370 V414 M517 370 V414 M535 370 V414 M553 370 V414" />
|
||||
</g>
|
||||
<g fill="none" stroke="#b1783c" stroke-width="6"><path d="M330 275 H430" /><path d="M470 425 H570" /></g>
|
||||
<g fill="#d4934b" stroke="#704c2b" stroke-width="2"><circle cx="300" cy="270" r="9" /><circle cx="600" cy="430" r="9" /><circle cx="565" cy="270" r="9" /></g>
|
||||
<g fill="#2f7e61" stroke="#f2fff8" stroke-width="3"><circle cx="450" cy="285" r="11" /><circle cx="385" cy="350" r="11" /><circle cx="515" cy="350" r="11" /><circle cx="450" cy="415" r="11" /></g>
|
||||
<g stroke="#2f7e61" stroke-width="2" fill="none"><path d="M450 285 L450 210" /><path d="M385 350 L300 350" /><path d="M515 350 L600 350" /><path d="M450 415 L450 490" /></g>
|
||||
<g class="map-label"><text x="30" y="80">北进口</text><text x="680" y="80">东进口</text><text x="30" y="635">南进口</text><text x="680" y="635">西进口</text></g>
|
||||
<g fill="#173b32"><text x="655" y="520" class="map-label">预览中 · 路口边界</text></g>
|
||||
</svg>
|
||||
<div class="map-note">拖动绿色控制点调整几何;橙色设施可单独移动或编辑</div>
|
||||
</section>
|
||||
|
||||
<aside class="inspector" aria-label="路口配置与诊断">
|
||||
<section class="section">
|
||||
<h2 class="section-title">路口几何</h2>
|
||||
<p class="section-subtitle">修改后立即在画布显示服务端预览</p>
|
||||
<div class="field"><label>北进口宽度<small>合法范围 3.6–12.0 m</small></label><div class="unit"><input value="7.20" /><span>m</span></div></div>
|
||||
<div class="range"><i></i></div>
|
||||
<div class="field"><label>东进口收口距离<small>合法范围 1.0–18.0 m</small></label><div class="unit"><input value="5.40" /><span>m</span></div></div>
|
||||
<div class="range"><i style="width: 32%"></i></div>
|
||||
<div class="field"><label>北→东角部圆角<small>合法范围 1.0–12.0 m</small></label><div class="unit"><input value="4.00" /><span>m</span></div></div>
|
||||
<div class="range"><i style="width: 40%"></i></div>
|
||||
</section>
|
||||
|
||||
<section class="section">
|
||||
<h2 class="section-title">已有设施</h2>
|
||||
<p class="section-subtitle">选择画布中的设施可编辑其语义参数</p>
|
||||
<div class="facility"><span>斑马线 · 北侧</span><strong>6 条带 · 退让 1.5 m</strong></div>
|
||||
<div class="facility"><span>停止线 · 北侧</span><strong>偏移 2.7 m</strong></div>
|
||||
<div class="facility"><span>信号灯组 · 3 组</span><strong>可移动 / 可旋转</strong></div>
|
||||
</section>
|
||||
|
||||
<section class="section">
|
||||
<h2 class="section-title">验证诊断</h2>
|
||||
<div class="diagnostic">当前几何合法,进口截面连续,路口面无自交。所有预览对象均落在所属道路范围内。</div>
|
||||
</section>
|
||||
|
||||
<section class="section">
|
||||
<div class="status"><span class="dot"></span><strong>预览已同步</strong><span>preview #18 · 142 ms</span></div>
|
||||
</section>
|
||||
|
||||
<div class="actions">
|
||||
<button class="action">放弃草稿</button>
|
||||
<button class="action main">应用到工作区</button>
|
||||
</div>
|
||||
</aside>
|
||||
</main>
|
||||
|
||||
<footer class="footer">
|
||||
<strong>草稿 · 3 项未应用</strong>
|
||||
<span>路口面、斑马线、停止线将随本次预览同步更新</span>
|
||||
<div class="legend"><span class="geometry">几何控制</span><span class="facility-dot">设施控制</span></div>
|
||||
</footer>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
File renamed without changes.
+10
-3
@@ -38,6 +38,7 @@ type RoadConstraintKind =
|
||||
| 'junction-cutback'
|
||||
| 'junction-corner-radius'
|
||||
| 'junction-crosswalk-inset'
|
||||
| 'junction-crosswalk-size'
|
||||
| 'junction-stop-line-offset'
|
||||
```
|
||||
|
||||
@@ -50,14 +51,21 @@ type RoadConstraintKind =
|
||||
| `junction-cutback` | `junction-approach` | `{ cutbackMeters }` | 米 | JunctionTools |
|
||||
| `junction-corner-radius` | `junction-corner` | `{ radiusMeters }` | 米 | JunctionTools |
|
||||
| `junction-crosswalk-inset` | `junction-approach` | `{ insetMeters }` | 米,斑马线距路口边界的退让 | 主地图 / JunctionTools |
|
||||
| `junction-crosswalk-size` | `junction-approach` | `{ depthMeters, stripeCount }` | 米 + 整数条带数 | 主地图 |
|
||||
| `junction-stop-line-offset` | `junction-approach` | `{ offsetMeters }` | 米,停止线沿进口后退的距离 | 主地图 / JunctionTools |
|
||||
|
||||
前 6 个 kind 对应 PRD 首期范围(外缘、步行带、车道分隔 + 进口、cutback、角部)。
|
||||
|
||||
后 2 个于 2026-08-28 追加,是「更多元素可直接操纵」方向的第一类扩展:控制标线的**位置**
|
||||
`junction-crosswalk-inset` 与 `junction-stop-line-offset` 于 2026-08-28 追加,是「更多元素可直接操纵」方向的第一类扩展:控制标线的**位置**
|
||||
成为可编辑参数。它们不改变路口形状,只移动标线,因此不触发路口边界重算。
|
||||
放置是否成立的判据(`STOP_LINE_MAX_APPROACH_DISTANCE_METERS` 等)不在此范围内。
|
||||
|
||||
`junction-crosswalk-size` 于 2026-08-31 追加,是第一个改变标线**自身尺寸**而非位置的 kind。
|
||||
横跨道路的跨度不是存储值,而是 `stripeCount × pitch` 派生;pitch 固定 0.9m 不可编辑,
|
||||
因为条带宽与间隙在现实中是标准化的,而它横跨的道路不是。加宽靠增加条带数,
|
||||
所以跨度是**量化**的。同批修掉了「跨度恒为 4.95m,与路宽无关」的缺陷:
|
||||
无约束时条带数由整段车行道宽度推导。
|
||||
|
||||
新增 kind 的前提:**几何阶段必须已经消费它**。本项目曾为 `profile.interval` 交付过
|
||||
一个拖动无效果的手柄(见 `08-26-direct-edit-map-editor/research/interval-not-applied.md`),
|
||||
所以扩展 kind 时先证明 `compileGeometry()` 读取该参数,再画任何手柄。
|
||||
@@ -213,7 +221,7 @@ workbench-data/import-<id>/
|
||||
|
||||
主地图 Road editor 只编辑两个 junction reserve 之间的道路内部 interval。reserve 内的 approach width、transition、cutback 和 corner 由 `JunctionTools` 独占。同一进口上 `junction-approach-width` 显式约束优先于道路 profile,求解器负责边界连续。
|
||||
|
||||
`JunctionTools` 是单 `JunctionRef` session(`{type:'node'|'cluster', id}`):拖拽立即 ghost,服务端返回完整局部派生图层;"应用到工作区"把有效草稿合并为活动副本的未保存约束,"保存"才持久化,"取消"回到进入前状态。切换相邻路口前必须应用或取消。首个交付仅支持普通 node junction 的进口宽度、cutback 与一个角部圆角。
|
||||
`JunctionTools` 是独立的单 `JunctionRef` 页面(`{type:'node'|'cluster', id}`):主地图只负责发现和导航,页面自身负责路口自动居中、完整可视化画布、几何与已有设施编辑。页面不得被参数面板遮挡;路口面、进口、车道/connector、斑马线、停止线和信号灯都必须保持可见,编辑控件覆盖在同一画布上。拖拽立即 ghost,服务端返回完整局部派生图层;"应用到工作区"把有效草稿合并为活动副本的未保存约束,"保存"才持久化,"取消"回到进入前状态。切换相邻路口前必须应用或取消。
|
||||
|
||||
## 不变量
|
||||
|
||||
@@ -262,4 +270,3 @@ workbench-data/import-<id>/
|
||||
|
||||
|
||||
|
||||
|
||||
File renamed without changes.
File renamed without changes.
+11
@@ -91,6 +91,17 @@
|
||||
|
||||
## 验收标准(交付阶段)
|
||||
|
||||
### 独立 JunctionTools 页面(重新确认,2026-09-03)
|
||||
|
||||
JunctionTools 必须是一个独立的路口编辑页面,而不是覆盖在主地图上的参数弹层。主地图只负责发现路口、显示入口和返回导航;进入 `/junction/:type/:id` 后,页面主要视觉对象是当前单个路口,不能被编辑面板遮挡。
|
||||
|
||||
- [ ] 页面自动聚焦并适配当前路口,持续显示路口面、进口道路、圆角、cutback、斑马线、停止线和信号灯。
|
||||
- [ ] 几何编辑与已有设施编辑在同一页面完成,使用同一份 draft、preview、undo/redo、apply、save、cancel 状态。
|
||||
- [ ] 参数输入和地图拖拽是同一参数的两个输入通道:任一通道变化都会在路口画布上显示权威预览,另一通道同步当前值。
|
||||
- [ ] 预览失败时保留最后一个有效几何并显示结构化诊断;非法值不得显示成已应用几何。
|
||||
- [ ] 首版支持已有斑马线、停止线、信号灯的可视化调整和已有字段编辑;设施创建、删除和跨路口迁移不在首版范围。
|
||||
- [ ] 主地图的道路级编辑能力不因进入独立页面而消失;离开页面前必须明确应用、保存、放弃或继续停留。
|
||||
|
||||
每条都必须可执行验证,不接受"看起来对了"。
|
||||
|
||||
- [ ] 拖动道路外缘 → 保存 → 重新编译,道路面、步行带、车道线、标线与 connector 一致更新,约束状态为 `exact`。
|
||||
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
+7
-3
@@ -3,7 +3,7 @@
|
||||
"name": "direct-manipulation-road-editor",
|
||||
"title": "直接操纵道路编辑工作台",
|
||||
"description": "探索类似 Drawtonomy 的直接操纵道路编辑,保持结构化 overrides、可审计性和可重编译性",
|
||||
"status": "planning",
|
||||
"status": "completed",
|
||||
"dev_type": "feature",
|
||||
"scope": "road-editor",
|
||||
"package": null,
|
||||
@@ -11,7 +11,7 @@
|
||||
"creator": "dingkang",
|
||||
"assignee": "dingkang",
|
||||
"createdAt": "2026-08-26",
|
||||
"completedAt": null,
|
||||
"completedAt": "2026-09-07",
|
||||
"branch": null,
|
||||
"base_branch": "main",
|
||||
"worktree_path": null,
|
||||
@@ -26,7 +26,11 @@
|
||||
"08-27-junction-dominated-roads",
|
||||
"08-28-edit-interaction-polish",
|
||||
"08-28-junction-control-offsets",
|
||||
"08-28-crosswalk-element-editor"
|
||||
"08-28-crosswalk-element-editor",
|
||||
"08-31-parameter-panel-binding",
|
||||
"08-31-constraint-range-validation",
|
||||
"08-31-lane-maneuver-override",
|
||||
"09-02-workbench-component-boundaries"
|
||||
],
|
||||
"parent": null,
|
||||
"relatedFiles": [
|
||||
File renamed without changes.
@@ -0,0 +1,148 @@
|
||||
# 斑马线元素级编辑器设计
|
||||
|
||||
## 架构边界
|
||||
|
||||
本实验扩展现有直接编辑链路,而非建立画布对象存储:
|
||||
|
||||
```text
|
||||
crosswalk feature 点击
|
||||
-> elementId
|
||||
-> element manifest (anchor + parameters + legal controls)
|
||||
-> native-road-edits/v2 constraint
|
||||
-> resolveDirectEditConstraints
|
||||
-> compileControlMarkings
|
||||
-> preview / save / recompile
|
||||
```
|
||||
|
||||
`elementId` 是选择和分组标识;持久化仍使用稳定语义 anchor 上的 constraint。它不能是 GeoJSON 数组下标、屏幕坐标或临时 UUID。
|
||||
|
||||
## 选择合同
|
||||
|
||||
斑马线的每一条 stripe feature 必须包含 `native_id`、`element_id` 与可回链的 crossing / approach 身份。选择适配层只读取 `element_id`,再向服务器取得选中元素的权威 manifest。客户端不会据条带数量、空间距离或渲染顺序自行聚类。
|
||||
|
||||
元素 manifest 至少包含:
|
||||
|
||||
```ts
|
||||
interface EditableElement {
|
||||
elementId: string
|
||||
kind: 'crosswalk'
|
||||
anchor: { type: 'junction-approach'; nodeId: string; segmentId: string }
|
||||
featureIds: string[]
|
||||
controls: Array<{
|
||||
kind: 'position' | 'length' | 'width'
|
||||
value: { current: number; min: number; max: number; unit: 'meter' }
|
||||
axisAzimuth?: number
|
||||
}>
|
||||
fields: Array<{ key: string; value: number; min: number; max: number; unit: 'meter' | 'count' }>
|
||||
}
|
||||
```
|
||||
|
||||
第一阶段发布 `position` 与 `length` / `width`:位置沿用现有 `junction-crosswalk-inset`,尺寸需要新的回写规则(见「尺寸的语义」)。`rotation` **不在本任务范围**,理由见文末。
|
||||
|
||||
## `elementId` 已经存在
|
||||
|
||||
实测:48 条条带按 `crossing_node_id` 分组恰好得到 8 组、每组 6 条,且没有任何
|
||||
crossing 对应多条道路。唯一性是结构性的——`compileControlMarkings()` 的循环是
|
||||
`for (const crossing of model.crossings)`,每次迭代由单个 `crosswalkCandidate`
|
||||
产出一组。
|
||||
|
||||
因此 **`crosswalk:node/<crossingId>` 就是稳定的组标识**,无需新增编译器字段。
|
||||
条带 `native_id` 形如 `crosswalk:node/-26452:1`,组前缀直接可用;
|
||||
`crossing_node_id` 也已在 feature 属性里。
|
||||
|
||||
客户端据此分组**不构成** PRD 禁止的「按经纬度近似聚类」——它读的是已发布的稳定
|
||||
标识,不是空间猜测。
|
||||
|
||||
> 早期分析曾断言组标识缺失,理由是「同一节点的多个进口共用它」。那是把
|
||||
> **crossing 节点**(`node/-26452`,人行横道)与 **junction 节点**
|
||||
> (`node/1140799725`,路口)混为一谈了。两者不是同一个 id。
|
||||
|
||||
## `affects` 缺失仍是真问题
|
||||
|
||||
上一节不影响这一节。`junctionAffects()`(`direct-edit-solver.js:628`)构造的是
|
||||
`junctionSurfaceId + roadAffects + connectors`,**从不加入 crosswalk 或 stop-line**。
|
||||
实测在有 48 条斑马线的区域,`junction-crosswalk-inset` 手柄的 `affects` 共 59 项,
|
||||
crosswalk 为 **0**。
|
||||
|
||||
成因是求解器手上没有「进口 → crossing」的映射:该关系在编译器的
|
||||
`compileControlMarkings()` 内部由 `arrivalEndpointIds` 与距离阈值算出,从未对外发布。
|
||||
|
||||
后果限于**拖拽高亮会亮错一片**(PRD 第 2 条要求高亮受影响对象)。
|
||||
它**不阻塞选中**,因为选中走的是上一节的组标识。两者是独立的两步。
|
||||
|
||||
## 编辑与预览
|
||||
|
||||
- 选择由 `MapCanvas` 的 feature 事件产生,但选择状态由 App/编辑会话持有,不能写入 baseline source。
|
||||
- 元素控件写入的是 manifest 指定的 constraint kind/value;表单复用同一写入器。
|
||||
- 选中框和控件只是 `editHandles` / `editGhost` 层的临时 UI;权威预览仍由服务端返回,baseline source 不被客户端改写。
|
||||
- 空白点击会清除元素选择;道路选择可继续决定道路级 handle manifest。斑马线元素选中与道路选择可并存,但两组控件不得重叠或竞争同一 pointer 手势。
|
||||
|
||||
## 尺寸的语义
|
||||
|
||||
斑马线的几何目前**全是字面量**(`native-road.js:1264`):
|
||||
|
||||
```js
|
||||
rectangleAt(controlCenter, axis, across, 3, 0.45, -2.25 + index * 0.9)
|
||||
// ↑长 ↑宽 ↑偏移,共 6 条
|
||||
```
|
||||
|
||||
`rectangleAt(center, axis, across, length, width, offset)` 中 `length` 沿 `axis`
|
||||
(行车方向),`width` 沿 `across`(横跨道路)。所以:
|
||||
|
||||
| 用户看到的 | 实际是什么 | 存储形态 |
|
||||
| --- | --- | --- |
|
||||
| 进深(沿行车方向) | 每条条带的 `length`,6 条共用 | 一个数,可直接参数化 |
|
||||
| 跨度(横跨道路) | **条带数 × 间距**,非存储值 | 派生量 |
|
||||
|
||||
跨度是派生量,所以拖四角改跨度必须决定改哪个因子。**已定:固定间距、改条带数。**
|
||||
|
||||
- 条带宽 0.45m 与间隙 0.45m(间距 0.9m)在现实中是标准化的,改间距会让宽路上的
|
||||
斑马线拉得很稀,不符合任何规范。
|
||||
- 代价是跨度手柄按 0.9m **量化跳动**,不是连续的。这是语义诚实的结果,
|
||||
不是手感缺陷;UI 上必须让它看起来是有意吸附的。
|
||||
|
||||
同时修掉一个既有缺陷:**跨度恒为 5.4m,与路宽无关**。20m 宽的路上斑马线也只有
|
||||
5.4m,横不过去。参数化后默认跨度应由路宽推导,而不是写死 6 条。
|
||||
|
||||
## 选中框与抓手
|
||||
|
||||
视觉采用常规 transform gizmo:矩形虚线选框 + 四角空心方块。
|
||||
|
||||
一条硬规矩:**画几个抓手,就得有几个是活的。** 画了拖不动的四角、或转了没反应的
|
||||
旋转柄,正是 `flag.ts` 为 `profile.interval` 立下的反面教材——
|
||||
「一个拖了没效果的控件比没有控件更糟」。长得像 Figma 但只有一半能用,
|
||||
比朴素的圆点更糟,用户会当成 bug 报。
|
||||
|
||||
所以抓手随能力分批出现,而不是先画全再逐个点亮:
|
||||
|
||||
| 抓手 | 语义 | 何时出现 |
|
||||
| --- | --- | --- |
|
||||
| 虚线选框 | 纯反馈,无语义 | 第一阶段 |
|
||||
| 移动 | `junction-crosswalk-inset` | 第一阶段(语义现成) |
|
||||
| 四角方块 | 进深 / 跨度 | 第一阶段(需编译器参数化) |
|
||||
| 旋转柄 | 相对进口轴的偏转角 | **不做** |
|
||||
|
||||
## 旋转为何押后
|
||||
|
||||
`axis` 派生自 `crosswalkCandidate.placement.axis`,即进口方向。要能旋转,
|
||||
需要新增一个「相对进口轴的偏转角」constraint kind。而 `design.md` 的规矩是
|
||||
**新增 kind 的前提是几何阶段必须已经消费它**——先证明 `compileGeometry()` 读取
|
||||
该参数,再画任何手柄。
|
||||
|
||||
偏转角本身是合理的(现实中斑马线确实会相对进口斜置),且用「相对派生轴的角度」
|
||||
表达是语义化的,不违反「不持久化 transform 矩阵」。但它是独立的一轮
|
||||
编译器 + kind + 客户端工作,已明确押后。
|
||||
|
||||
## 数据演进
|
||||
|
||||
位置继续使用已有 `junction-crosswalk-inset`。尺寸需要新的持久化形态,本阶段一并落地:进深与条带数各是一个参数,跨度由 `条带数 × 间距` 派生,间距本阶段不可编辑。具体是新增专属 kind 还是扩展同一 kind 的严格 schema,在第一个门禁(进口↔组映射)通过后定,不预先固化。
|
||||
|
||||
新增任何 kind 前必须先证明 `compileGeometry()` 读它——本项目已经为 `profile.interval` 交付过一个拖了无效果的手柄。
|
||||
|
||||
缺省参数必须字节级保持现有斑马线输出。参数越界、条带间互相重叠或越过可用进口范围均返回 blocking diagnostic,不在客户端静默钳制真实约束。
|
||||
|
||||
## 兼容与回滚
|
||||
|
||||
- 无新 constraint 时,编译输出与当前版本一致。
|
||||
- `directEdit` 关闭时不请求 element manifest、不安装元素选择交互、不产生额外图层。
|
||||
- 第一阶段每个步骤独立提交;回滚元素 UI 或 manifest 不影响既有道路级控制。
|
||||
+4
-2
@@ -1,4 +1,6 @@
|
||||
{"file":".trellis/spec/backend/direct-edit-api.md","reason":"元素 manifest、preview 和持久化必须继续满足直接编辑的服务端合同。"}
|
||||
{"file":".trellis/spec/frontend/direct-edit-client.md","reason":"元素选择、临时控件与表单必须保持 handle/ghost/preview 图层所有权。"}
|
||||
{"file":".trellis/spec/frontend/direct-edit-client.md","reason":"元素选择、临时控件与表单必须保持 handle/ghost/preview 图层所有权;§11-14 定义了输入通道汇合点、夹值/拒绝分工与聚焦期文本所有权。"}
|
||||
{"file":".trellis/spec/guides/cross-layer-thinking-guide.md","reason":"feature 属性、element manifest、constraint schema 与客户端选择状态跨越编译器、API 和 UI。"}
|
||||
{"file":".trellis/tasks/08-26-direct-manipulation-road-editor/design.md","reason":"继承 v2 语义约束、坐标分层、预览和 revision 的权威合同。"}
|
||||
{"file":".trellis/spec/guides/code-reuse-thinking-guide.md","reason":"元素控件必须接既有 draftValue/settleValue/abandonGesture,禁止新建第二条预览或 undo 链路。"}
|
||||
{"file":".trellis/tasks/08-26-direct-manipulation-road-editor/design.md","reason":"继承 v2 语义约束、坐标分层、预览和 revision 的权威合同,以及新增 kind 前必须先证明几何阶段消费它的规矩。"}
|
||||
{"file":".trellis/tasks/08-31-parameter-panel-binding/design.md","reason":"参数表单那一半的既有实现与三个通道无关出口的契约。"}
|
||||
@@ -0,0 +1,134 @@
|
||||
# 实施计划
|
||||
|
||||
顺序按**风险递减**排列:每一步都有可独立验证的门禁,失败即停,不进入下一步。
|
||||
|
||||
数据前提:`nantaizihu-9PTsZg`(由桌面 `南台子湖创新谷OSM.osm` 导入)含 10 个
|
||||
`highway=crossing` 节点、8 组 zebra,编译出 48 条斑马线与 8 条停止线。
|
||||
不带 crossing 的 OSM 无法验证本任务任何一步。
|
||||
|
||||
## 0. 建立事实与测试夹具
|
||||
|
||||
- 追踪 `compileControlMarkings()` 的每条 stripe 属性、`native_id` 构成,以及从地图点击到 `onFeature` 的路径。
|
||||
- 添加失败优先的测试:同组 stripe 需要稳定共享 `elementId`,不同 crossing 不得共享;空编辑输出与基线字节一致。
|
||||
- 门禁:能证明一个具体 feature 无歧义回链到一个 junction approach 和 crossing。
|
||||
|
||||
## 1. 元素选择(纯客户端)
|
||||
|
||||
`design.md` 已实测确认 `crosswalk:node/<crossingId>` 就是稳定组标识,
|
||||
条带属性里已有 `crossing_node_id`。**本步不需要改编译器。**
|
||||
|
||||
- 客户端建立 `ElementSelection` 纯状态:从 feature 属性推出组标识,不做空间聚类。
|
||||
- 点击任一条带选中整组、点空白清除;选择状态由 App / 编辑会话持有,不写 baseline source。
|
||||
- 元素选中与道路选择可并存,但两组控件不得竞争同一 pointer 手势。
|
||||
- 验证:客户端 selection 单元测试(同组共享、跨组不共享、重编译后稳定)。
|
||||
- **门禁**:一个具体 feature 无歧义回链到一个组,且组内条带数与编译输出一致。
|
||||
|
||||
## 2. 选中框与移动
|
||||
|
||||
- 渲染矩形虚线选框(框住整组 6 条)+ 移动抓手,接已有 `junction-crosswalk-inset`。
|
||||
- 控件走 `App.tsx` 既有的三个出口 `draftValue()` / `settleValue()` / `abandonGesture()`,**不新建第二条预览或 undo 链路**(见 `.trellis/spec/frontend/direct-edit-client.md` §11)。
|
||||
- 安装时不得影响道路 handle 的 hit-test。
|
||||
- **门禁**:一次非空元素编辑可在正式重编译结果中观察到斑马线位置变化。只交付 UI 不算通过。
|
||||
|
||||
## 3. 修正 `affects`(服务端)
|
||||
|
||||
独立于第 1 步——选中不依赖它,但拖拽高亮依赖。
|
||||
|
||||
- 求解器建立并消费「进口 → crossing」映射,使 `junctionAffects()` 不再遗漏 crosswalk。
|
||||
该关系目前只存在于 `compileControlMarkings()` 内部(`arrivalEndpointIds` + 距离阈值)。
|
||||
- 验证:API 测试。
|
||||
- **门禁**:`junction-crosswalk-inset` 手柄的 `affects` 必须包含它实际移动的那 6 条 crosswalk feature。当前实测为 0。
|
||||
|
||||
## 4. 编译器尺寸参数化
|
||||
|
||||
斑马线几何目前全是字面量(`native-road.js:1264`:长 3m、宽 0.45m、间距 0.9m、6 条)。
|
||||
|
||||
- 进深与条带数成为参数;间距本阶段固定 0.9m 不可编辑;跨度 = 条带数 × 间距,派生。
|
||||
- 默认跨度由路宽推导,修掉「跨度恒为 5.4m 与路宽无关」的既有缺陷。
|
||||
- 无约束时输出与当前版本**字节级一致**(除上述默认跨度修正外,该修正需单独记录并更新基线)。
|
||||
- 越界、条带重叠、超出可用进口范围返回 blocking diagnostic。
|
||||
- **门禁**:先证明 `compileGeometry()` 读取新参数,再画任何抓手。这条规矩来自
|
||||
`profile.interval` 那次教训——求解器写了、几何阶段没读、交付了一个拖动无效果的手柄。
|
||||
|
||||
## 5. 四角尺寸抓手
|
||||
|
||||
- 四角空心方块:一轴改进深(连续),一轴改跨度(按 0.9m 量化吸附)。
|
||||
- 量化必须看起来是有意吸附,不能像卡顿。
|
||||
- 表单与抓手写同一组元素参数,值、单位、范围、诊断一致。
|
||||
- **门禁**:画出来的每个抓手都必须是活的。宁可少画,不可画死的
|
||||
(`direct-edit-client.md` 的 `intervalEditingSupported` 先例)。
|
||||
|
||||
## 6. 复盘
|
||||
|
||||
- 手测:选中、取消、道路级手柄共存、移动钳位、尺寸吸附、表单校验、保存重载、撤销/重做。
|
||||
- 记录哪些结论可推广到停止线/箭头,哪些**不可**——斑马线只改位置与自身尺寸,
|
||||
不改路口形状;`approach-width` / `cutback` / `corner-radius` 是另一个几何类别,
|
||||
本实验不为它们背书(见 `prd.md` 的「试验对象的覆盖边界」)。
|
||||
|
||||
## 明确不做
|
||||
|
||||
- 旋转。需要新增「相对进口轴偏转角」constraint kind 且编译器先消费它,已决定押后。
|
||||
- 条带间距编辑。
|
||||
- 推广到停止线、箭头、信号灯。
|
||||
|
||||
## 验证命令
|
||||
|
||||
```sh
|
||||
npm run format:check
|
||||
npm run test
|
||||
npm run test:client
|
||||
npm run test:client:unit
|
||||
npm run build
|
||||
```
|
||||
|
||||
## 风险文件
|
||||
|
||||
- `src/compile/native-road.js`:斑马线生成与默认输出兼容性;尺寸参数化会动到基线快照。
|
||||
- `src/compile/direct-edit-solver.js`:`junctionAffects()` 是第 1 步的核心;element manifest 与 handle manifest 不得互相污染。
|
||||
- `src/compile/native-road-edits.js`:新增 kind 或扩展 schema 时校验必须同步。
|
||||
- `workbench/server.js`:element manifest 查询与 preview 不得写入磁盘。
|
||||
- `workbench/client/src/App.tsx`、`edit/`、`components/`:元素控件必须接既有三出口;选中框是临时 UI,不得写 baseline layer。
|
||||
- `test/fixtures.js`:默认跨度改由路宽推导会改动 fixture 基线,需显式更新而非静默接受。
|
||||
|
||||
---
|
||||
|
||||
## 交付进度(2026-08-31)
|
||||
|
||||
| 步骤 | 状态 |
|
||||
| --- | --- |
|
||||
| 0 建立事实与测试夹具 | ✅ |
|
||||
| 1 元素选择 | ✅ `edit/element.ts`,浏览器已确认;已推广到停止线 |
|
||||
| 2 选中框与移动 | ✅ 虚线框可直接拖拽 |
|
||||
| 3 修正 `affects` | ⏸ 暂缓——客户端从不读 `affects`,高亮未实现,单独修不可见。应与高亮作为一件事做 |
|
||||
| 4 编译器尺寸参数化 | ✅ `junction-crosswalk-size`,门禁已过,基线已更新 |
|
||||
| 5 四角尺寸抓手 | ⬜ 未开始,见下方设计难点 |
|
||||
| 6 复盘 | 部分:推广分析见 `research/generalising-to-other-markings.md` |
|
||||
|
||||
第 1–2 步之外另修了两处既有缺陷:`MapCanvas` 的陈旧闭包与空白点击不上报,
|
||||
以及 `junction-crosswalk-inset` 的上界(44%~88% 死区,见
|
||||
`08-31-parameter-panel-binding/research/manifest-range-vs-solver.md`)。
|
||||
|
||||
手测确认:选中、虚线框、拖拽均可用。**尚未手测**:框跟随修复后的表现、
|
||||
上界修复后的拖拽手感——两者都需重启工作台进程才能生效。
|
||||
|
||||
## 第 5 步的设计难点(未解决)
|
||||
|
||||
`junction-crosswalk-size` 的值是**一对数** `{ depthMeters, stripeCount }`,
|
||||
而拖拽链路是标量的:`projectHandleValue` 产出一个数,`constraintValueFor`
|
||||
把它包成一个 value。四角抓手需要两个自由度:
|
||||
|
||||
- 一轴改进深(连续,米)
|
||||
- 一轴改跨度(量化,写回 `stripeCount`)
|
||||
|
||||
拖其中一个必须**保留另一个的当前值**,否则每次拖拽都会把未触碰的那半重置为默认。
|
||||
可行方向(未定):
|
||||
|
||||
1. 发两个标量手柄,`draftFor` 在构造 value 时与已有约束合并
|
||||
2. 扩展 `EditHandle` 表达多分量,改动面更大
|
||||
3. 元素控件不走 `draftFor`,自己构造 value——**违反「两条通道汇合于同一出口」**,不推荐
|
||||
|
||||
方向 1 最小,但需要 `draftFor` 能读到该约束的当前值;目前它只从 handle 拿标量。
|
||||
动手前应先定这个,否则会长出第二条 draft 路径。
|
||||
|
||||
另:`junction-crosswalk-size` 已加入 `JUNCTION_KINDS` 但**不在** `CONTROL_KINDS`,
|
||||
所以参数面板不渲染它——它的值是一对数,而面板渲染标量。接入抓手时一并处理。
|
||||
+20
@@ -12,6 +12,7 @@
|
||||
- `compileControlMarkings()` 为一组斑马线生成多条 `crosswalk` GeoJSON feature;每条 feature 的属性目前不足以作为稳定的组级编辑目标。
|
||||
- 浏览器已有 `EditSession`、服务端权威 preview、保存、重编译与撤销链路。编辑数据必须保持语义约束,不得保存派生 GeoJSON 或屏幕坐标。
|
||||
- 当前普通道路级手柄仍服务于横断面参数,不应与元素级选择共用或互相覆盖。
|
||||
- `08-31-parameter-panel-binding` 已交付参数表单那一半:`ParameterPanel` 组件、`edit/parameter.ts` 的文本↔数值/范围判定/单位换算,以及 `App.tsx` 中通道无关的三个出口 `draftValue()`(预览)、`settleValue()`(提交一步 undo)、`abandonGesture()`(放弃)。元素级控件应接入同一组出口,**不要新建第二条预览或 undo 链路**。
|
||||
|
||||
## 范围
|
||||
|
||||
@@ -52,6 +53,25 @@
|
||||
- 选中框是交互反馈,不能成为第二个几何模型;所有位置、范围和尺寸的权威值由后端 element manifest 给出。
|
||||
- 当前地图 feature 的属性可能缺少足以识别 crossing 的稳定字段。需要先通过编译器补充,不可在客户端按经纬度近似聚类。
|
||||
|
||||
### 试验对象的覆盖边界(2026-08-31 决定)
|
||||
|
||||
本任务的上游动机是**为复杂路口做前置**:普通四岔口已有 20 个手柄分属 4 条 segment,
|
||||
主地图一次只显示当前选中 segment 的手柄,要看全一个路口需依次选中 4 条道路。
|
||||
每参数一个圆点的模型撑不到复杂路口,元素级选中是必需品而非优化。
|
||||
|
||||
已明确决定:**第一次试验只做斑马线,不并入形状类元素**,以控制风险。
|
||||
|
||||
代价必须记录在案——斑马线是**位置类**元素,`design.md` 明确「不改变路口形状,
|
||||
只移动标线,因此不触发路口边界重算」。而复杂路口真正难的是
|
||||
`junction-approach-width` / `junction-cutback` / `junction-corner-radius`:
|
||||
它们改变路口多边形本身,涉及边界连续、面自交、cutback 处截面衔接。
|
||||
|
||||
因此:
|
||||
|
||||
- 本试验通过 **只证明**「选中 + 位置编辑」这条链路可行。
|
||||
- 它 **不证明** 形状类元素的元素级编辑可行,那是另一个几何类别。
|
||||
- 推广到形状类元素前必须单独验证,不得以本试验的结论替代。
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] TBD
|
||||
+84
@@ -0,0 +1,84 @@
|
||||
# 元素模型能推广到哪些标线
|
||||
|
||||
日期:2026-08-31
|
||||
来源:`08-28-crosswalk-element-editor` 第 1–2 步交付后,对 `nantaizihu-9PTsZg` 的实测。
|
||||
|
||||
## 各元素的分组结构(实测)
|
||||
|
||||
| 图层 | provenance | 分组键 | feature | 组数 | 每组大小 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| `crosswalks` | `native-road-crosswalk/v1` | `crossing_node_id` | 48 | 8 | 恒 6 |
|
||||
| `vehicleStopLines` | `native-road-stop-line/v1` | `crossing_node_id` | 8 | 8 | 恒 1 |
|
||||
| `turnArrows` | `native-road-turn-arrow/v1` | `lane_id` + `maneuver` | 108 | 28 | 3 或 5 |
|
||||
| `directionArrows` | `native-road-direction-arrow/v1` | `lane_id` | 324 | 50 | 2~28 |
|
||||
| `laneSeparators` | `native-road-lane-separator/v1` | `road_id` + 车道对 | 731 | 9 | 26~230 |
|
||||
|
||||
## 关键陷阱:斑马线与停止线共用 `crossing_node_id`
|
||||
|
||||
交集 **8/8**——两者由同一个 `controlFeature()` 构造,`crossing_node_id` 完全重合。
|
||||
只按该字段分组会把一组斑马线和它的停止线并成一个"元素"。
|
||||
|
||||
**必须先按 `provenance` 判类型,再取分组键。** `element.ts` 已如此实现并有测试守着
|
||||
(`rejects a stop line, which shares the same feature builder`)。任何推广都不能绕过这一步。
|
||||
|
||||
## 可编辑性就绪度
|
||||
|
||||
| 元素 | 约束 kind | 编译器是否消费 | 实测响应 | 成本 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 斑马线 | `junction-crosswalk-inset` | ✅ | 已修正上界,全程有效 | **已完成** |
|
||||
| 停止线 | `junction-stop-line-offset` | ✅ | **全程线性,零死区** | **几乎免费** |
|
||||
| 转向箭头 | ❌ 无 | ❌ | — | 新 kind + 编译器 |
|
||||
| 方向箭头 | ❌ 无 | ❌ | — | 新 kind + 编译器 |
|
||||
| 车道分隔线 | v1 overrides,仅样式 | 仅样式 | 位置不可编辑 | 另一类问题 |
|
||||
|
||||
停止线实测:offset `0.5 → 126` 位移 `0 → 125.36m`,增量始终 1:1。
|
||||
**没有斑马线那种死区**,可以直接接入。
|
||||
|
||||
但它有反向的毛病:声明范围 `[0.5, 126.28]`(`approach.length * 0.45`),
|
||||
允许把停止线推到离路口 126 米——而 `native-road.js` 有
|
||||
`STOP_LINE_MAX_APPROACH_DISTANCE_METERS = 25`。范围过宽同样是缺陷,
|
||||
见 `.trellis/spec/backend/direct-edit-api.md` §12。
|
||||
|
||||
## 值得建立的抽象(仅此而已)
|
||||
|
||||
一个按 provenance 索引的小注册表:
|
||||
|
||||
```ts
|
||||
interface ElementSpec {
|
||||
provenance: string;
|
||||
kind: ElementKind;
|
||||
groupKey(properties: Record<string, unknown>): string | null;
|
||||
constraintKind: ConstraintKind;
|
||||
}
|
||||
```
|
||||
|
||||
`element.ts` 现有的 `crosswalkElementIdOf` / `groupMembers` / `elementSelectionFor`
|
||||
改为查表即可,选中、选框、拖拽三条链路无需改动。
|
||||
|
||||
**不要**据此建立"所有元素"的通用协议——PRD 明确禁止
|
||||
(「不提前建立『所有元素』的大而全抽象」)。理由在上表里:
|
||||
分组键的形态各不相同(单字段 / 双字段 / 派生),
|
||||
每组大小从 1 到 230,箭头类连约束 kind 都还不存在。
|
||||
现在能证明的只有「provenance + 分组键 → 组」这一条,注册表恰好只承诺这一条。
|
||||
|
||||
## 推荐顺序
|
||||
|
||||
1. **停止线**——注册表 + 一条 spec 条目。约束现成、编译器已消费、响应已验证。
|
||||
同时暴露注册表是否够用:它的每组只有 1 个 feature,而斑马线是 6 个,
|
||||
能验证分组逻辑不依赖"多 part"这个偶然属性。
|
||||
2. **修 `affects`**(原第 3 步)——目前 `junctionAffects()` 不含任何标线,
|
||||
拖拽高亮会亮错一片。停止线接入后这个问题会更明显。
|
||||
3. **转向箭头**——需要新 constraint kind,且必须先证明 `compileGeometry()` 读它。
|
||||
分组键 `lane_id + maneuver` 已验证(28 组,每组 3 或 5 个 part)。
|
||||
4. **方向箭头**——最贵。分组语义本身待定:按 `lane_id` 是 50 组(编辑间距/整体偏移),
|
||||
按 `lane_id + sequence` 是 324 组(逐个箭头独立摆放)。
|
||||
这是产品决策,不是实现细节,需先定。
|
||||
5. **车道分隔线**——不同类问题。已有 v1 样式 override,缺的是位置,
|
||||
而位置由 `road-lane-divider` 约束管,属道路横断面而非元素级。
|
||||
|
||||
## 与复杂路口的关系
|
||||
|
||||
停止线和转向箭头都是**位置类**元素,与斑马线同属一个几何类别:
|
||||
移动它们不改变路口多边形。所以第 1、3 步不会为形状类元素
|
||||
(`approach-width` / `cutback` / `corner-radius`)提供任何背书——
|
||||
那仍是独立的、未验证的一类,见 `prd.md`「试验对象的覆盖边界」。
|
||||
+2
-2
@@ -3,7 +3,7 @@
|
||||
"name": "crosswalk-element-editor",
|
||||
"title": "斑马线元素级编辑器实验",
|
||||
"description": "",
|
||||
"status": "planning",
|
||||
"status": "completed",
|
||||
"dev_type": null,
|
||||
"scope": null,
|
||||
"package": null,
|
||||
@@ -11,7 +11,7 @@
|
||||
"creator": "dingkang",
|
||||
"assignee": "dingkang",
|
||||
"createdAt": "2026-08-28",
|
||||
"completedAt": null,
|
||||
"completedAt": "2026-09-07",
|
||||
"branch": null,
|
||||
"base_branch": "main",
|
||||
"worktree_path": null,
|
||||
@@ -0,0 +1 @@
|
||||
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
|
||||
@@ -0,0 +1,57 @@
|
||||
# 设计:约束范围校验与重放失效
|
||||
|
||||
## 问题边界
|
||||
|
||||
`road-edge-offset` 的 manifest 以 `makeRoadHandles()` 中一个 segment 的双向总宽计算 `±width * 0.45`,而 `applyRoadConstraint()` 针对锚点指向的单条 direction road 执行最小车道宽与外缘边界判定。二者不共享数据和公式,导致已发布的拖拽终点能被求解器拒绝。
|
||||
|
||||
范围是锚点在**当前模型和当前已应用截面状态**下的可行域;它不是客户端提示。直接 API、正式编译重放和 manifest 必须对同一个值作同一判断。
|
||||
|
||||
## 单一范围所有者
|
||||
|
||||
在 `src/compile/direct-edit-solver.js` 增加内部 range resolver。它接收当前 model、constraint/handle anchor,以及已经应用的 road profile 或 junction plan,返回值字段的 `{ min, max }`;无法解析的锚点由现有锚点状态流程处理,而不是伪造范围。
|
||||
|
||||
每个已发布 kind 均通过该 resolver 取范围:
|
||||
|
||||
- `road-edge-offset`:以锚点所指单条 road 的宽度、车道数及另一侧当前 offset 推导。下限确保总宽不低于 `laneCount * MIN_LANE_WIDTH_METERS`;两侧上限受单侧半宽不变量约束。不能再以 segment 总宽发布范围。
|
||||
- `road-lane-divider`:按锚点 road 的单车道宽和最小车道宽推导对称范围。
|
||||
- `road-sidewalk-width`、corner radius、crosswalk size:将现有有限常量移进 resolver。
|
||||
- approach width、cutback、crosswalk inset、stop-line offset:由对应 approach 与当前 plan 推导;crosswalk inset 延用 `effectiveCrosswalkInsetMax()`,不再让 manifest / apply 分别持有上界。
|
||||
|
||||
Resolver 的上界不得低于已保存的 current 值:历史值会先在重放预检中判 stale,只有尚未失效的值才可发布给客户端。这避免“当前值超过 manifest max”的自相矛盾状态。
|
||||
|
||||
## 求解与重放
|
||||
|
||||
`solveConstraints()` 每次应用 constraint 前,将其与当前 profile/plan 交给 range resolver:
|
||||
|
||||
- 预览、保存后重新编译、直接调用 resolver:越界产生阻塞诊断,constraint state 为未应用 `invalid`;不夹值也不写回 document。
|
||||
- `reconcileConstraints()`:对 `exact` / `recheck` 的已解析锚点,在不改值的前提下按当前几何计算其范围。值越界时将 document 内存副本状态置为 `stale`,并携带不可变的 replay reason `range-out-of-bounds`;该约束随后不会进入 solver。
|
||||
- 锚点不存在仍是 `stale`,reason 为 `anchor-missing`。候选可重定位时仍沿用 `pending` / `conflicted`。
|
||||
|
||||
范围校验的阻塞诊断与重放 stale 是两条刻意不同的路径:前者说明本次草稿违法,后者说明曾经合法的历史编辑不再适合新的几何。
|
||||
|
||||
## API 契约
|
||||
|
||||
`constraintStates` 在原有 `status` / `applied` / `reason` 外,将 reason 标准化为可供 rebase 消费的枚举值:
|
||||
|
||||
- `range-out-of-bounds`
|
||||
- `anchor-missing`
|
||||
- 保留已有 `disabled`、`status-*`、`invalid`。
|
||||
|
||||
`POST /api/revisions/:id/rebase` 继续返回 status counts 和 constraints 明细;调用方通过每个 stale constraint 的 `reason` 区分范围失效和锚点失效。无 schema 版本变更,旧客户端可忽略新增/更精确的 reason。
|
||||
|
||||
## 数据流
|
||||
|
||||
```
|
||||
current model + applied profile/plan
|
||||
-> constraint range resolver
|
||||
-> manifest value.min/max
|
||||
-> preview/formal solver blocking validation
|
||||
-> reconciliation stale check during replay
|
||||
-> rebase constraintStates.reason
|
||||
```
|
||||
|
||||
## 兼容性与风险
|
||||
|
||||
- 不修改 persisted v2 schema,也不自动夹值、重写 value 或近似映射锚点。
|
||||
- 新 range 可能使旧文档中先前允许但几何上不可行的值显示为 stale;这是目标行为。上线前在真实 import 目录做 rebase 审计。
|
||||
- 多条相互影响的 road constraints 仍按文档顺序求解。范围 helper 使用当前已应用 profile,确保 manifest 和本次 solver 的单值判断一致;组合造成的后续不变量失败仍由现有事务式 solver 拒绝,不能把其他约束偷偷改掉。
|
||||
@@ -0,0 +1 @@
|
||||
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
|
||||
@@ -0,0 +1,29 @@
|
||||
# 实施计划:约束范围校验与重放失效
|
||||
|
||||
## 实施顺序
|
||||
|
||||
1. 在 `direct-edit-solver.js` 搜索所有 manifest 与 apply 分支中的范围常量,建立 anchor/context-aware range resolver,并为 road/junction kind 迁移已有边界。
|
||||
2. 让 `makeRoadHandles()` / `makeJunctionHandles()` 从该 resolver 填充 `value.min` / `value.max`;road edge 使用单向 road 和该 side 的 profile,移除 segment 总宽 `0.45` 公式。
|
||||
3. 在 `applyRoadConstraint()`、`applyJunctionConstraint()` 写入前调用相同 resolver,越界使用 kind 明确的 blocking diagnostic,保留现有 rollback snapshot 行为。
|
||||
4. 扩展 `reconcileConstraints()`:已解析、可重放的值若落在新几何范围外则变为 `stale`,并发出 `range-out-of-bounds`;锚点缺失变为 `anchor-missing`,不破坏 pending/conflicted 逻辑。
|
||||
5. 确认 `rebaseEdits()` 的现有 constraint 明细透传 reason;必要时为 response contract 补稳定字段和测试。
|
||||
6. 追加 unit tests:外缘 extrema、直接越界诊断、manifest/solver 同源、几何缩窄后的 stale、不参与求解、anchor stale reason、既有 exact 回归。
|
||||
7. 追加 API integration tests:`editPreview()` 越界诊断与 `rebaseEdits()` reason/counts。
|
||||
8. 按项目质量门槛运行 format、unit/integration/client/build;对真实 import 做只读 rebase 审计并记录受影响约束数。
|
||||
|
||||
## 验证命令
|
||||
|
||||
```sh
|
||||
npm run format:check
|
||||
npm run test
|
||||
npm run test:client
|
||||
npm run build
|
||||
```
|
||||
|
||||
测试重点不只比较 manifest 数字,还要把 manifest 的每个端点实际提交给 resolver,确认没有 blocking diagnostic。重放测试必须断言 stale constraint 未出现在 road profile / junction plan。
|
||||
|
||||
## 风险点与回退
|
||||
|
||||
- 风险文件:`src/compile/direct-edit-solver.js`。范围 helper 若错误共享 segment 与 direction 宽度,会再次出现 handle / solver 不一致;新增 fixture-style unit case 固化双向道路场景。
|
||||
- 兼容性:保留 v2 文档、constraint kind、status 集合与 API 主字段。reason 仅增加细分值。
|
||||
- 回退:本改动不迁移或覆写存储。若真实目录审计发现意外大量 stale,回退代码即可恢复旧行为,原始 edit documents 不受影响。
|
||||
@@ -0,0 +1,70 @@
|
||||
# 约束值范围的服务端校验与重放失效
|
||||
|
||||
## 目标
|
||||
|
||||
让 manifest 声明的取值范围与求解器实际接受的可行域一致,并让保存后因几何变化而越界的约束按既有 status 机制转 `stale`,而不是静默产出畸形几何。
|
||||
|
||||
缺口有**三种表现**,均已实测确认(证据见 `08-31-parameter-panel-binding/research/manifest-range-vs-solver.md`):
|
||||
|
||||
1. **过松且会被拒**——manifest 宣告的范围比求解器接受的宽。某 6.5m 道路的外缘偏移手柄声明 `±2.925`,超过约 `±1` 即返回 `direct-edit-outer-edges-cross`。宣告范围约为可行域的 3 倍。
|
||||
2. **过松且静默无效**——比上一种更糟,因为没有任何反馈。`junction-crosswalk-inset` 声明 `[0, 8]`,实测 `0 → 3.2` 线性响应,`3.2 → 8` **位移增量全为 0**。成因是 `crossingJunctionInset()` 中 `targetDistance = max(0, cutbackMeters - inset)` 在 inset 达到 `cutbackMeters` 后触底,外加 `CROSSWALK_MAX_JUNCTION_INSET_METERS = 4` 的封顶。声明范围里约 60% 是死区。
|
||||
3. **无校验**——求解器不检查 manifest 的 `min`/`max`,范围目前仅由客户端夹值实际约束。
|
||||
|
||||
> **第 2 种已于 2026-08-31 在 `08-28-crosswalk-element-editor` 中修复。**
|
||||
> `src/compile/crossing-approach.js` 的 `effectiveCrosswalkInsetMax()` 按
|
||||
> `cutback - max(0, junctionDistance - 4)` 发布真实上界,8 组实测全部吻合,
|
||||
> 且 fixture 证明几何字节不变。
|
||||
>
|
||||
> 本任务因此**只需覆盖其余 kind**——尤其是第 1 种(外缘偏移)。
|
||||
> 那次修复也给出了可复用的形态:**上界由几何推导,不是常量**;
|
||||
> 以及一个易犯的坑:一条 segment 的两条方向道路可能在同一路口服务不同对象,
|
||||
> 取第一个匹配会把 A 的上界发到 B 的手柄上。
|
||||
|
||||
第 1 种仍待处理:手柄在死区里拖动毫无反应或直接报错,与「控件坏了」难以区分,
|
||||
正是 `flag.ts` 为 `profile.interval` 立下的那条规矩要避免的情形
|
||||
(「一个拖了没效果的控件比没有控件更糟」),只是它发生在量程的一段而非整个控件。
|
||||
|
||||
## 已确认的事实
|
||||
|
||||
- `direct-edit-solver.js` 的 `applyConstraint` 分支(302、312、322 行附近)只校验 `Number.isFinite` 与非负,**未校验 manifest 声明的 `min` / `max`**。
|
||||
- 范围目前是纯客户端概念:manifest 下发它,`projection.ts:60` 的 `projectHandleValue` 夹它,仅此而已。今天没出事,只因拖拽是唯一写入通道且它必夹。
|
||||
- 部分范围是**动态的**:外缘偏移为 `±Math.max(0.1, width * 0.45)`,随道路宽度浮动;步行带固定 `0..8`;角部圆角固定 `0.5..30`。
|
||||
- 因此保存时合法的值,可能在道路几何变化后越界——重导入改变车道数、其它约束改变断面宽度均可触发。该类越界发生在保存之后的求解期,**客户端结构上无法拦截**。
|
||||
- 父 `design.md` 已为同类情形定义规则:"`boundaryIndex` ⋯ 重放时若车道数变化导致越界,该约束转 `stale`,不做近似映射。"数值范围越界属于同一类,只是未被写下。
|
||||
- `08-31-parameter-panel-binding` 引入第二条写入通道(数值输入)。该任务在客户端拦截越界输入,但那只覆盖输入当下,不覆盖本任务的场景。
|
||||
|
||||
## 范围
|
||||
|
||||
1. manifest 发布的 `min`/`max` 必须落在求解器实际接受的可行域内——宣告一个必被拒绝的极值等于骗用户。
|
||||
2. 求解器在应用约束时校验其值落在该 kind / 该锚点当前的合法范围内。
|
||||
3. 越界值产生**阻塞性诊断**,不静默夹值、不静默丢弃。
|
||||
4. 范围的计算与 manifest 中 `value.min` / `value.max` 的生成**共用同一处逻辑**,不得出现两份定义。
|
||||
5. 重放(重导入、几何版本变更)时,因范围变化而越界的约束转 `stale`,与 `boundaryIndex` 越界同等处理。
|
||||
6. rebase 响应的 status 计数与明细覆盖这一新的 `stale` 来源。
|
||||
|
||||
## 明确不做
|
||||
|
||||
- 不改变客户端拖拽的夹值行为(`projectHandleValue` 是渲染正确性的一部分)。
|
||||
- 不为越界约束做近似映射或自动修正——与父 `design.md` 的"不自动改值"一致。
|
||||
- 不新增约束 kind,不改动几何生成。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [ ] 复现 research 记录的场景:某 6.5m 道路的外缘偏移手柄,其发布的 `max` 不再是一个提交即被 `direct-edit-outer-edges-cross` 拒绝的值。
|
||||
- [ ] 对任一手柄,提交恰好等于 manifest `min` 或 `max` 的值不产生阻塞诊断(宣告即可用)。
|
||||
- [ ] 绕过客户端直接 POST 一个越界约束到 `/api/edit-preview`,返回阻塞性诊断而非畸形几何。
|
||||
- [ ] manifest 的 `min`/`max` 与求解器校验用的范围来自同一处代码,可由测试证明二者一致。
|
||||
- [ ] 构造一个"保存时合法、几何变化后越界"的场景(如缩窄道路使可行域下降),重放后该约束报 `stale`,且不参与求解。
|
||||
- [ ] `stale` 的原因在 rebase 响应中可区分于锚点丢失导致的 `stale`。
|
||||
- [ ] 既有的 `exact` 约束不因本改动被误判失效——回归现有 revision 编译结果不变。
|
||||
- [ ] `npm run format:check`、`npm run test`、`npm run test:client`、`npm run build` 全绿。
|
||||
|
||||
## 风险与门槛
|
||||
|
||||
- 范围收紧可能让**既有已保存约束**突然变 `stale`。上线前必须在真实 import 目录上跑一遍,确认影响面,并确保旧 revision 仍可打开并复现原结果(父 `design.md` 的可复现性要求)。
|
||||
- 范围的两份定义(manifest 生成处与校验处)若各写各的,会产生"手柄允许但求解器拒绝"的死区。第 3 条是硬要求。
|
||||
|
||||
## 关联
|
||||
|
||||
- 缺口由 `08-31-parameter-panel-binding` 的设计过程发现,详见该任务 `design.md` 的「已知缺口」。
|
||||
- 本任务不阻塞面板任务:面板的客户端校验独立成立。
|
||||
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"id": "constraint-range-validation",
|
||||
"name": "constraint-range-validation",
|
||||
"title": "约束值范围的服务端校验与重放失效",
|
||||
"description": "服务端补 manifest min/max 校验;保存后因几何变化导致的数值越界转 stale",
|
||||
"status": "completed",
|
||||
"dev_type": null,
|
||||
"scope": null,
|
||||
"package": null,
|
||||
"priority": "P3",
|
||||
"creator": "dingkang",
|
||||
"assignee": "dingkang",
|
||||
"createdAt": "2026-08-31",
|
||||
"completedAt": "2026-09-03",
|
||||
"branch": null,
|
||||
"base_branch": "main",
|
||||
"worktree_path": null,
|
||||
"commit": null,
|
||||
"pr_url": null,
|
||||
"subtasks": [],
|
||||
"children": [],
|
||||
"parent": "08-26-direct-manipulation-road-editor",
|
||||
"relatedFiles": [],
|
||||
"notes": "",
|
||||
"meta": {}
|
||||
}
|
||||
@@ -0,0 +1,2 @@
|
||||
{"file": ".trellis/spec/frontend/direct-edit-client.md", "reason": "Verify that new lane selection does not write baseline layers or join the drag-handle path."}
|
||||
{"file": ".trellis/spec/guides/cross-layer-thinking-guide.md", "reason": "Verify the staged override remains a compiler-valid lane-maneuver payload."}
|
||||
@@ -0,0 +1,48 @@
|
||||
# Lane Maneuver UI Design
|
||||
|
||||
## Boundary
|
||||
|
||||
This increment exposes the existing v1 `lane-maneuver` override in the workbench.
|
||||
It changes neither compiler validation nor the placement algorithms. In particular,
|
||||
`native-road-direction-arrow/v1` remains display-only because it represents repeated
|
||||
straight-ahead markings controlled by a separate interval policy.
|
||||
|
||||
## Selection Model
|
||||
|
||||
`edit/element.ts` remains the sole conversion point from clicked GeoJSON properties
|
||||
to a logical element. Its registry gains a turn-arrow entry whose group key is the
|
||||
ordered tuple `[lane_id, maneuver]`; the key is serialized with a dedicated, stable
|
||||
separator rather than inferred from `native_id`. This groups the 3/5 polygon parts
|
||||
of one visual arrow without merging arrows from different maneuvers on the same lane.
|
||||
|
||||
The current crosswalk/stop-line `ElementSelection` is junction-control-specific.
|
||||
Turn arrows instead produce a lane selection carrying `laneId`, `maneuver`, and the
|
||||
group feature ids. They deliberately do not call `handleForElement` or create an
|
||||
outline/drag target: changing a maneuver is a v1 discrete override rather than a
|
||||
v2 spatial constraint.
|
||||
|
||||
Lane centerlines already publish `native_id` equal to the compiler lane id. The
|
||||
click handler recognizes that id and creates the same lane selection, with the
|
||||
current maneuver resolved from the stored/staged override first, then from the
|
||||
clicked turn arrow if present, otherwise empty. That makes an unmarked lane editable.
|
||||
|
||||
## Inspector And Save Flow
|
||||
|
||||
The inspector owns the discrete selector. It receives the selected lane and the
|
||||
effective override list, offers the compiler's six exact canonical values plus
|
||||
empty-string removal, and stages one deterministic id per lane. The existing
|
||||
`stage` function replaces entries with equal ids, so a lane has exactly one pending
|
||||
override and save/recompile continues through the established API path.
|
||||
|
||||
This is intentionally not a direct-edit (`EditSession`) operation: no preview
|
||||
endpoint consumes lane-maneuver and a client-side visual preview would disagree with
|
||||
the authoritative compiler output. The existing save-then-recompile copy remains
|
||||
the user-visible boundary.
|
||||
|
||||
## Tests
|
||||
|
||||
Pure tests cover tuple grouping, part selection, lane-centerline selection and
|
||||
non-selection of direction arrows. A component-level test is unnecessary for the
|
||||
existing app test style; the inspector's emitted object is kept simple enough to
|
||||
exercise by extracting a pure override builder if needed. Typecheck and build cover
|
||||
the wiring.
|
||||
@@ -0,0 +1,2 @@
|
||||
{"file": ".trellis/spec/frontend/direct-edit-client.md", "reason": "Preserve direct-edit layer and handle ownership while adding a separate v1 discrete selection path."}
|
||||
{"file": ".trellis/spec/guides/cross-layer-thinking-guide.md", "reason": "Keep the UI's staged override shape aligned with the compiler and API contract."}
|
||||
@@ -0,0 +1,16 @@
|
||||
# Implementation Plan
|
||||
|
||||
1. Generalize the element registry's group-key reader and add a lane-maneuver
|
||||
selection type for turn arrows and lane centerlines.
|
||||
2. Wire map clicks to preserve the existing control-element path while selecting
|
||||
lane arrows or centerlines through the new path.
|
||||
3. Add an inspector selector that stages a lane-maneuver override with canonical
|
||||
values and an explicit removal value.
|
||||
4. Add focused element tests for multi-property grouping and unmarked-lane entry.
|
||||
5. Run formatting, server tests, client type/unit tests, and production build.
|
||||
|
||||
## Rollback
|
||||
|
||||
The UI is isolated to `workbench/client/src/edit/element.ts`, `App.tsx`, and its
|
||||
unit tests. Reverting those files restores the previous display-only arrow behavior;
|
||||
the compiler's already-shipped v1 override contract remains untouched.
|
||||
@@ -0,0 +1,125 @@
|
||||
# 车道转向箭头覆盖
|
||||
|
||||
## 目标
|
||||
|
||||
让用户能决定某条车道画什么导向箭头,而不必回去改 OSM。走 **v1 override**,
|
||||
新增 `lane-maneuver` kind。
|
||||
|
||||
## 为什么是 v1 而不是 v2
|
||||
|
||||
这一点决定了整个设计,先说清楚。
|
||||
|
||||
导向箭头的**内容**(左转/直行/右转)来自 OSM 标签
|
||||
`turn:lanes:<direction>`,是车道的一个**离散属性**;而 v2 直接编辑的锚点是
|
||||
`{roadId, station}` 这类**位置上的约束**。「这条车道显示什么箭头」没有位置,
|
||||
硬塞进 v2 会让锚点模型失去意义。
|
||||
|
||||
v1 override 里已有覆盖 OSM 派生值的先例:`road` kind 覆盖 `laneCount`、
|
||||
`widthMeters`、`sidewalkLeft/Right`。转向属于同一类。
|
||||
|
||||
**箭头的位置参数(间距、距路口距离)是另一回事**,属于 v2,且还有未定的
|
||||
分组决策,不在本任务内。
|
||||
|
||||
## 已确认的事实
|
||||
|
||||
- `turn:lanes:<direction>` 或 `turn:lanes` 以 `|` 分隔,每段对应一条车道;
|
||||
`compileLaneMarkings()`(`native-road.js:1520`)读它,`maneuvers[index]` 取到本车道那段。
|
||||
- 当前 `if (!explicitManeuver) continue`——OSM 没标的车道**不画箭头**,
|
||||
所以覆盖必须能给"本来没有"的车道加上箭头,不只是改已有的。
|
||||
- `normalizeManeuver()`(`turn-lane-arrows.js:114`)已导出,支持恰好 6 种取值:
|
||||
`through` / `left` / `right` / `through;left` / `through;right` / `through;left;right`。
|
||||
它对输入排序后查表,所以 `left;through` 与 `through;left` 等价。
|
||||
- `validateOverrides()` 已构造 `laneIds` 集合(`native-road.js:295`),
|
||||
形如 `lane:<roadId>:<index>`,`lane-connection` 是使用它的现成先例。
|
||||
- 实测当前区域有 28 条 `turn:lanes:*` 标签,编译出 108 个导向箭头,
|
||||
`maneuver` 取值 4 种、`placement_distance_meters` 恒为 6。
|
||||
|
||||
## 范围
|
||||
|
||||
1. 新增 v1 override kind `lane-maneuver`,字段 `{ laneId, maneuver }`。
|
||||
2. `maneuver` 取 6 种受支持值之一;**空字符串表示不画箭头**,用于移除 OSM 标了但不想要的箭头。
|
||||
3. 校验 `laneId` 属于已知车道;未知目标按既有 stale 机制处理,不新造一套。
|
||||
4. 覆盖优先于 OSM 标签;能给 OSM 未标注的车道**新增**箭头。
|
||||
5. 无覆盖时输出与当前版本**字节级一致**。
|
||||
|
||||
## 明确不做
|
||||
|
||||
- 箭头的位置参数(间距 32m、距路口 6m)——属 v2,且分组语义未定。
|
||||
- 直行箭头(`directionArrows`)——那是沿车道重复摆放的另一套逻辑。
|
||||
- 客户端 UI。本任务只做编译器与 override 合同;先证明覆盖生效,再谈怎么点选。
|
||||
- 不改 OSM 源文件,不改车道数或拓扑。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [x] 对一条 OSM 已标 `turn:lanes` 的车道施加覆盖,编译输出的 `maneuver` 变为覆盖值。
|
||||
- [x] 对一条 OSM **未标**的车道施加覆盖,输出**新增**该车道的箭头。
|
||||
- [x] `maneuver: ''` 使该车道不再输出箭头。
|
||||
- [x] 非法 `maneuver`(如 `'u-turn'`)被拒绝并报错,不静默降级。
|
||||
- [x] 未知 `laneId` 按既有 stale 机制处理,与 `lane-connection` 行为一致。
|
||||
- [x] 空覆盖集的编译输出与改动前字节一致(fixture 不变)。
|
||||
- [x] `npm run format:check`、`npm run test`、`npm run test:client`、`npm run test:client:unit`、`npm run build` 通过。
|
||||
|
||||
## 风险与门槛
|
||||
|
||||
- **门禁**:先证明覆盖真的改变正式编译输出,再谈 UI。本项目已有
|
||||
`profile.interval` 的教训——参数写了、几何阶段没读、交付了一个无效控件。
|
||||
- `laneId` 的稳定性与 `lane-connection` 同级:车道数变化会使高索引车道失效,
|
||||
由既有 stale 机制兜底,本任务不新增重定位逻辑。
|
||||
- `normalizeManeuver` 对未知取值会原样返回拼接串(`supported.get(...) || parts.join(';')`),
|
||||
所以校验必须在 override 层做,不能指望它兜底。
|
||||
|
||||
## 交付状态(2026-08-31)
|
||||
|
||||
编译器与 override 合同**已完成**,7 条验收标准全部通过,实测于
|
||||
`nantaizihu-9PTsZg`(108 个导向箭头 / 28 条车道有箭头)。
|
||||
|
||||
| 场景 | 结果 |
|
||||
| --- | --- |
|
||||
| 覆盖已标注车道 | `through;left;right` → `left` |
|
||||
| 给未标注车道新增 | 新增 3 个 part |
|
||||
| `maneuver: ''` 移除 | 0 个 |
|
||||
| 空覆盖集 | 与基线字节一致,fixture 未变 |
|
||||
|
||||
**客户端 UI 按 PRD 明确不做。** 现在只能通过 override 文件或 API 施加。
|
||||
接 UI 时需要的前置:导向箭头的分组键是 `lane_id + maneuver`(实测 108 个 → 28 组,
|
||||
每组 3 或 5 个 part),与斑马线的 `crossing_node_id` 不同形态,
|
||||
`element.ts` 的注册表需要扩展 `groupProperty` 为可组合的形式。
|
||||
|
||||
## UI 增量(规划中,2026-09-01)
|
||||
|
||||
### 已确认事实
|
||||
|
||||
- 工作台点击事件会传递所有命中的 feature,但只有开启 `?directEdit=1` 时才会请求
|
||||
`element.ts` 判断是否为可编辑元素;该注册表目前仅登记斑马线和停止线,故转向箭头
|
||||
会清空元素选择。
|
||||
- 路口转向箭头的 provenance 是 `native-road-turn-arrow/v1`,一个逻辑箭头由
|
||||
`lane_id + maneuver` 共同标识,并绘制为 3 或 5 个 part。
|
||||
- `lane-maneuver` 是 v1 离散 override,不是 v2 位置约束;它不能接入现有
|
||||
`ElementSelection -> handleForElement -> 拖拽手柄` 路径。
|
||||
- 沿车道重复的道路方向箭头 provenance 是 `native-road-direction-arrow/v1`,固定为
|
||||
`through`,由 32m 间距规则生成,当前没有对应的 override 合同。
|
||||
- 仅允许点击已生成的转向箭头无法满足“给 OSM 未标注车道新增箭头”:该车道没有 feature
|
||||
可点,故 UI 还必须允许从车道中心线或道路检查器选择目标车道。
|
||||
|
||||
### 拟议范围
|
||||
|
||||
1. 点击任一转向箭头 part 时,选中其完整 `lane_id + maneuver` 组,并在检查器展示
|
||||
六种合法转向及“无箭头”。
|
||||
2. 从车道中心线进入同一编辑器,使没有现存转向箭头的车道也能新增箭头。
|
||||
3. 选择值以单一、按 `laneId` upsert 的 `lane-maneuver` override 暂存;保存并重新生成后
|
||||
更新正式几何。空字符串仍表示移除。
|
||||
4. 扩展 element 注册表的分组键表达能力,但不把 v1 override 伪装成 v2 拖拽约束。
|
||||
|
||||
### 验收标准(UI)
|
||||
|
||||
- [x] 点击任一 `native-road-turn-arrow/v1` part 会选中同一
|
||||
`lane_id + maneuver` 的所有 part,且不会并入同车道的其他 maneuver。
|
||||
- [x] 点击车道中心线能选中该车道并展示相同的转向编辑器;即使该车道当前没有转向箭头,
|
||||
用户仍能选择一种转向并暂存。
|
||||
- [x] 转向编辑器只提供编译器接受的六种规范值和“无箭头”;选择会按 laneId upsert
|
||||
一个 `lane-maneuver` override,空字符串表示移除。
|
||||
- [x] “保存修改”后 override 被服务端接受;“保存并重新生成”后,编译结果反映所选
|
||||
maneuver 或移除,并可重新选择新的箭头。
|
||||
- [x] `native-road-direction-arrow/v1` 不显示转向编辑器,32m 间距及其生成数量不变。
|
||||
- [x] 既有斑马线、停止线选择及直接编辑手柄不回归;`npm run format:check`、
|
||||
`npm run test`、`npm run test:client`、`npm run test:client:unit`、`npm run build` 通过。
|
||||
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"id": "lane-maneuver-override",
|
||||
"name": "lane-maneuver-override",
|
||||
"title": "车道转向箭头覆盖",
|
||||
"description": "v1 override 新增 lane-maneuver:覆盖 OSM turn:lanes,决定某条车道画什么导向箭头",
|
||||
"status": "completed",
|
||||
"dev_type": null,
|
||||
"scope": null,
|
||||
"package": null,
|
||||
"priority": "P2",
|
||||
"creator": "dingkang",
|
||||
"assignee": "dingkang",
|
||||
"createdAt": "2026-08-31",
|
||||
"completedAt": "2026-09-01",
|
||||
"branch": null,
|
||||
"base_branch": "main",
|
||||
"worktree_path": null,
|
||||
"commit": null,
|
||||
"pr_url": null,
|
||||
"subtasks": [],
|
||||
"children": [],
|
||||
"parent": "08-26-direct-manipulation-road-editor",
|
||||
"relatedFiles": [],
|
||||
"notes": "",
|
||||
"meta": {}
|
||||
}
|
||||
@@ -0,0 +1,4 @@
|
||||
{"file":".trellis/spec/frontend/direct-edit-client.md","reason":"检查面板未写入 baseline source、控件值全部由 manifest 驱动、previewSeq 仲裁未被绕开。"}
|
||||
{"file":".trellis/spec/frontend/state-management.md","reason":"检查聚焦/失焦的值所有权切换无第二真相来源,且中间态不被预览响应改写。"}
|
||||
{"file":".trellis/spec/frontend/quality-guidelines.md","reason":"检查新增纯逻辑的单测覆盖与客户端质量门槛。"}
|
||||
{"file":".trellis/spec/guides/code-reuse-thinking-guide.md","reason":"核对拖拽与输入两条通道汇合于同一个 draftFor,未出现并行实现。"}
|
||||
@@ -0,0 +1,138 @@
|
||||
# 参数面板与数值双向绑定 · 设计
|
||||
|
||||
> 父任务 `08-26-direct-manipulation-road-editor/design.md` 仍是约束模型、求解边界与 API 合约的权威定义。本文只补充**第二条输入通道**引入的规则,不改变其中任何一条。
|
||||
|
||||
## 架构定位
|
||||
|
||||
本任务不触碰服务端。约束模型、求解器、handle manifest、revision 全部原样保留。改动完全落在客户端输入层:
|
||||
|
||||
```text
|
||||
┌─ 拖拽(连续)──→ projectHandleValue() ─┐
|
||||
选中道路 → manifest ─┤ ├→ draftFor(handle, value)
|
||||
└─ 输入框(离散)→ 解析 + 范围校验 ──────┘ ↓
|
||||
PreviewRequester
|
||||
(80ms 防抖 + previewSeq 仲裁)
|
||||
↓
|
||||
EditSession.commit()
|
||||
```
|
||||
|
||||
`draftFor(handle, value)`(`App.tsx:206`)本就是纯函数 `(手柄, 数字) → 草稿`。两条通道的唯一区别是**如何产生那个数字**以及**何时闭合 gesture**,汇合点之后完全一致。
|
||||
|
||||
## 不变量:取值范围
|
||||
|
||||
> **约束值永不超出 manifest 声明的 `[min, max]`。**
|
||||
>
|
||||
> - **连续输入**(拖拽、滑杆)在极限处**停止移动**。ghost 与手柄按夹后的值绘制,绝不跟随越界的光标。
|
||||
> - **离散输入**(数值框)**拒绝接受**越界值:标记非法、不发预览、不进 undo 栈、保留最后一个有效预览。范围提示可一键填入极值。
|
||||
|
||||
这是**一条规则的两种设备表达**,不是两套策略。
|
||||
|
||||
连续设备没有表达"拒绝"的手段——停止移动就是它的拒绝,而且是当场可见的:手柄停住、光标继续走。用户不会形成"我设成了 -24.1"这个信念。夹值理由见 `projection.ts:75` 的注释(ol-ext 探针把手柄拖到 -24.1m 而约束夹在 -5.4m,手柄指向一个不可能存在的路形)。
|
||||
|
||||
离散设备则相反:数字已经键入、Tab 已经按下,此时夹值是**事后篡改**。且失败模式不对称——
|
||||
|
||||
| 用户意图 | 夹值 | 拒绝 |
|
||||
| --- | --- | --- |
|
||||
| 打错(想输 2.4,输成 24) | 变成 5.4,看起来合理,可能永不被发现 | 立即可见 |
|
||||
| 想拉满 | 如愿 | 多一步(或点范围提示一键填入) |
|
||||
|
||||
拒绝错了只损失一次击键;夹值错了会把一个**看起来正常的错误值**送进下游编译与仿真。故取拒绝。
|
||||
|
||||
## 值的所有权
|
||||
|
||||
任一时刻,一个参数的显示值来源是**唯一**且由聚焦状态决定的:
|
||||
|
||||
| 状态 | 显示值 | 理由 |
|
||||
| --- | --- | --- |
|
||||
| 未聚焦 | `handle.value.current` | 服务端权威回显 |
|
||||
| 聚焦中 | 本地文本 draft | 保留 `1.`、`-`、空串等中间态 |
|
||||
|
||||
必须如此的原因:`App.tsx:197` 在每次预览结算时 `setManifest(response.handles)` 整体替换 manifest。受控输入若直接绑定 `value.current`,键入 `1.` 触发的防抖预览返回后会把输入框冲成 `1`,小数点消失。
|
||||
|
||||
失焦即清 draft。此时 `value.current` 必然等于刚提交的值——因为 `direct-edit-solver.js:136` 的 `numericValue()` 直接回显约束里的数字,服务端不改写。**故不存在"请求值 vs 求解值"的双显示需求。**
|
||||
|
||||
> 该结论依赖 solver 当前行为。若日后改为回写求解结果,本节规则失效,需同步重审。
|
||||
|
||||
## gesture 边界
|
||||
|
||||
`gestureIdentity()` 是懒创建的 operationId 单例,`commitGesture()` 释放它。它抽象的是"一段有始有终的操作",与指针无绑定关系,因此可原样承载键盘输入:
|
||||
|
||||
| 阶段 | 拖拽 | 输入框 | 动作 |
|
||||
| --- | --- | --- | --- |
|
||||
| 开始 | `pointerdown` | `focus` | 铸 operationId |
|
||||
| 进行 | `pointermove` | `onChange` | `requester.schedule()`,**不 commit** |
|
||||
| 结束 | `pointerup` | `blur` / `Enter` | `requester.flush()` + `commitGesture()` |
|
||||
| 放弃 | — | `Escape` | 回滚显示值 + `requester.cancel()` |
|
||||
|
||||
`EditSession` 与 `gestureIdentity()` 无需改动。输入 `1.53` 产生一步 undo,而非四步。
|
||||
|
||||
滑杆(若实现)的 pointerdown/up 天然落在此表内,不引入新分支。
|
||||
|
||||
**保存路径**:`saveDirectEdits()` 必须在入口强制结算未闭合的 gesture。DOM 中 blur 先于 click 触发,直接点"保存"能赶上,但该顺序过于脆弱,不作为正确性依赖。
|
||||
|
||||
## 区间的单位分层
|
||||
|
||||
父 `design.md` 的坐标分层表规定持久化层只有米与归一化 station。显示层不受该表约束。
|
||||
|
||||
| 层 | 单位 |
|
||||
| --- | --- |
|
||||
| 持久化 / 传输 | `station` (0..1) |
|
||||
| 面板显示与输入 | 米(`station × roadLengthMeters`) |
|
||||
|
||||
**只在用户实际编辑时换算**,不在每次渲染时做 米→station→米 的往返,否则四舍五入会让数字自行漂移。`roadLengthMeters` 取自 `IntervalRangeHandle`,与 range 手柄同源。
|
||||
|
||||
区间由整条道路共享(`rangeDraftFor` 重锚该路全部约束),故在面板中**每条路一行**,不随手柄重复。
|
||||
|
||||
## 面板可表达而拖拽不能表达的操作
|
||||
|
||||
`value.current` 在无约束时回落基线(外缘偏移基线为 0),因此"未修改"与"显式设为 0"数值完全相同。`handle.constraintId` 仅在约束存在时出现,客户端据此区分。
|
||||
|
||||
由此得到一个拖拽结构上无法提供的能力:**删除约束**。拖拽只能设值,不能移除。面板每行提供"重置",删除该约束并使该行回到未修改态。
|
||||
|
||||
这是参数面板的实质增量,而非拖拽的镜像显示。
|
||||
|
||||
## 渲染性能
|
||||
|
||||
`handleDragEvent` 每次 mousemove 触发,而 `App.tsx` 是单个 974 行组件。拖拽值回流面板必须经 rAF 节流,不得直接 `setState`。
|
||||
|
||||
节流有效性需在扩大面板规模前验证——手柄当前仅 5~6 个,问题不会自行显现。
|
||||
|
||||
## 边界
|
||||
|
||||
- 面板不得成为第二套几何算法或第二个值的真相来源。范围、位置、`affects`、可编辑性一律只来自服务端 manifest。
|
||||
- 面板只呈现主地图拥有的 kind。路口 shape 三 kind 仍属 `JunctionTools`;保留区内手柄呈禁用态并显示 `disabledReason`。
|
||||
- 不新增约束 kind,不改动求解器。
|
||||
|
||||
## 已知缺口
|
||||
|
||||
服务端 `applyConstraint` 只校验 `Number.isFinite` 与非负,**不校验 manifest 的 `min`/`max`**。今日范围仅由客户端 `projectHandleValue` 的夹值实际约束。
|
||||
|
||||
外缘偏移的范围随道路宽度浮动(`±Math.max(0.1, width * 0.45)`),因此保存时合法的值可能在后续几何变化后越界。此类越界发生在保存之后的求解期,**客户端结构上无法拦截**。
|
||||
|
||||
父 `design.md` 已为 `boundaryIndex` 定义同类规则——"重放时若车道数变化导致越界,该约束转 `stale`,不做近似映射"——数值范围越界应同等处理。
|
||||
|
||||
属重放正确性,不属本任务;独立成任务。本任务的客户端校验不因该缺口存在而降级:范围在哪定义就在哪拦,并避免一次注定被拒的求解。
|
||||
|
||||
## 右侧工作台信息架构(2026-09-01)
|
||||
|
||||
右栏是操作面板而非信息流。顶部固定呈现当前选择对象、其道路方向和修改状态;下方
|
||||
采用单主展开区的手风琴,避免所有表单在初始状态占满地图旁的空间。
|
||||
|
||||
| 分段 | 内容 | 展开规则 | 写入语义 |
|
||||
| --- | --- | --- | --- |
|
||||
| 道路 | 基础道路覆盖、直接编辑参数 | 选中道路时默认展开 | override 暂存;直接编辑 preview/session |
|
||||
| 元素 | 车道箭头、标线、信号灯 | 选择相应地图元素时自动展开 | 箭头/标线暂存;信号灯即时 API |
|
||||
| 连接 | 路口连接、行驶动作、手工候选 | 默认收起 | override 暂存 |
|
||||
| 高级 | 复杂路口候选、技术 JSON | 始终默认收起 | 候选沿用现有调用 |
|
||||
|
||||
每个分段使用受控 React 状态,而非依赖原生 `<details>` 的不可观察状态;这让地图选中
|
||||
事件可以可靠地展开相应段,且移动端与桌面端保持同一状态模型。分段标题显示摘要
|
||||
(如参数修改数、所选第几车道、连接数量),但不复制任何几何或约束值。
|
||||
|
||||
车道箭头在元素段显示 maneuver 选择、距路口端的米数读数和有限数值输入。数值输入与
|
||||
拖曳都写同一 `lane-maneuver.placementDistanceMeters`;客户端只限制为有限非负值,控制
|
||||
设施与端点安全位置仍由正式编译的 `nearestSafeTurnArrowPlacement()` 权威裁决。
|
||||
|
||||
为避免继续膨胀 `App.tsx`,右栏容器、对象摘要、手风琴、道路/连接/元素分段应迁入
|
||||
`workbench/client/src/components/`。现有 `ParameterPanel` 保持其 manifest 值所有权和
|
||||
DOM 直写性能策略,只作为“道路”分段的内容,不被重写为另一条输入链路。
|
||||
@@ -0,0 +1,6 @@
|
||||
{"file":".trellis/spec/frontend/direct-edit-client.md","reason":"面板是第二条输入通道,必须继续遵守 manifest 驱动、baseline 不被写入、预览时序与图层所有权。"}
|
||||
{"file":".trellis/spec/frontend/state-management.md","reason":"聚焦期本地 draft 与服务端 value.current 的所有权切换是本任务的核心状态规则,不得产生第二个值的真相来源。"}
|
||||
{"file":".trellis/spec/frontend/component-guidelines.md","reason":"新增参数面板组件需符合既有组件结构与职责边界。"}
|
||||
{"file":".trellis/spec/frontend/hook-guidelines.md","reason":"拖拽回流的 rAF 节流以 hook 承载,需符合既有 hook 约定。"}
|
||||
{"file":".trellis/spec/guides/code-reuse-thinking-guide.md","reason":"输入通道必须复用 draftFor / PreviewRequester / EditSession,禁止复制出第二套预览与 undo 链路。"}
|
||||
{"file":".trellis/tasks/08-26-direct-manipulation-road-editor/design.md","reason":"继承 v2 约束模型、坐标分层、预览时序与 handle manifest 的权威合同。"}
|
||||
@@ -0,0 +1,97 @@
|
||||
# 实施计划
|
||||
|
||||
顺序按**风险递减**排列:每一步都有可独立验证的门禁,失败即停,不进入下一步。
|
||||
|
||||
## 0. 纯逻辑与测试夹具
|
||||
|
||||
- 在 `workbench/client/src/edit/` 新增参数值的纯逻辑:数值格式化/解析(保留 `1.`、`-`、空串中间态)、范围校验、`station ↔ 米` 换算。
|
||||
- 与现有 `meters.ts` / `projection.ts` / `selection.ts` 同侧,**不得 import OpenLayers**。
|
||||
- 失败优先的 vitest:越界判定的边界值、中间态解析不丢字符、米↔station 往返不漂移。
|
||||
- 门禁:新增模块的单测在 node 下跑通,且 `grep -r "from 'ol" ` 对新文件无命中。
|
||||
|
||||
## 1. 面板只读渲染
|
||||
|
||||
- 新增面板组件,遍历 `editHandles` 渲染:中文名、`value.current`、单位、`[min, max]`。**此步不可编辑。**
|
||||
- 多个 `road-lane-divider` 按 `boundaryIndex` 分行;不可编辑手柄呈禁用态并显示 `disabledReason`。
|
||||
- 依 `handle.constraintId` 是否存在标记"已修改"。
|
||||
- 区间每条路一行,以米显示。
|
||||
- 验证:选中不同道路、选中含保留区的道路、选中多车道道路,面板结构正确。
|
||||
- 门禁:`directEdit` 开关关闭时面板不渲染、不请求 manifest,网络轨迹与 main 一致。
|
||||
|
||||
## 2. 拖拽 → 面板回流
|
||||
|
||||
- 拖拽值**直接写 DOM 节点**(ref + `textContent` / `value`),不经 React 渲染。
|
||||
`direct-edit-client.md` §7:rAF 合并是**最低要求**,"写到源头"才是生产规则;ghost 直接写 OL source,面板的等价物是直接写 DOM。
|
||||
- **禁止**在 `handleDragEvent` 中 `setState`;gesture 结束时才做一次 state 对账。
|
||||
- 禁止在 `setState` updater 内计算或读 OL 状态(§6)。
|
||||
- 验证:拖拽过程中面板数值实时跟随;用 render 计数确认**面板未新增任何渲染**。
|
||||
注意门禁不是"拖拽期间渲染 0 次"——`onSettled` 的 `setManifest` 本就会在拖拽中随防抖预览触发渲染,那是服务端权威预览的固有代价,改动前就存在。要证明的是 `pointermove` 自身不再产生渲染。
|
||||
- 拖拽中落地的预览会把 manifest 换成滞后一个防抖周期的值,需保证数字不在两者间闪烁。
|
||||
- 门禁:节流有效性必须在此步证明。手柄当前仅 5~6 个,问题不会自行显现;跳过则后续无从归因。
|
||||
|
||||
## 3. 输入通道:预览、gesture 边界、commit
|
||||
|
||||
- 输入框接入 `draftFor` → `PreviewRequester.schedule()`,复用 80ms 防抖与 `previewSeq` 仲裁。
|
||||
- gesture 边界按 `design.md` 表实现:`focus` 铸 operationId,`onChange` 只预览,`blur` / `Enter` 走 `flush()` + `commitGesture()`,`Escape` 回滚 + `cancel()`。
|
||||
- 聚焦期间显示本地文本 draft,失焦后跟随 `value.current`。
|
||||
- **`EditSession` 与 `gestureIdentity()` 不得修改**;若发现需要改,说明边界映射错了,退回重审。
|
||||
- 验证:输入框改值与拖到同一数值产出同形约束;输入 `1.53` 后一次 Ctrl+Z 回到修改前;键入 `1.` 期间到达的预览响应不改写输入框。
|
||||
- 门禁:一次非空表单编辑可在正式重编译结果中观察到几何变化。只交付 UI 不算通过。
|
||||
|
||||
## 4. 范围拒绝与极值填入
|
||||
|
||||
- 越界输入:标红、**不发预览请求**、不进 undo 栈、保留最后一个有效预览。
|
||||
- 拖拽与滑杆的夹值行为保持不变(`projectHandleValue` 不改)。
|
||||
- 范围提示中的极值可点击填入。
|
||||
- 验证:越界时网络面板无新请求;blur 后无新 undo 步骤;点击极值可正常提交;拖拽越界时手柄仍停在极限。
|
||||
- 门禁:夹值与拒绝的差异必须体现为 `design.md` 中的同一条不变量,不得实现成两条并列策略。
|
||||
|
||||
## 5. 重置与区间换算
|
||||
|
||||
- 每行"重置"删除该约束,使该行回到未修改态(`constraintId` 消失、值回落基线)。
|
||||
- 区间的米↔station 换算实现并单测;**区间行受 `intervalEditingSupported` 门控,当前为 `false` 故不渲染**。
|
||||
理由与 range 手柄一致(`flag.ts:46`):`compileGeometry()` 不读 `profile.interval`,一个改了没效果的输入框比没有更糟。
|
||||
换算只在用户实际编辑时进行,渲染路径不做米→station→米 往返。
|
||||
- 验证:重置后保存重编译,该参数回到基线;换算函数往返无累积漂移;开关为 `false` 时面板不出现区间行。
|
||||
|
||||
## 6. 加固与手测
|
||||
|
||||
- `saveDirectEdits()` 入口强制结算未闭合 gesture,不依赖 blur/click 顺序。
|
||||
- 手测清单:
|
||||
- 输入未失焦直接点"保存",修改被正确持久化。
|
||||
- 拖拽与输入交替操作,undo/redo 序列正确。
|
||||
- 快速连续输入,乱序预览响应不覆盖较新结果。
|
||||
- 切换选中道路时未闭合的输入被正确结算或放弃。
|
||||
- OpenLayers `Map` 未被重建,仅受影响 source 被替换。
|
||||
- 门禁:交付前 `directEdit` 开关行为与改动前一致。
|
||||
|
||||
## 验证命令
|
||||
|
||||
```sh
|
||||
npm run format:check
|
||||
npm run test
|
||||
npm run test:client
|
||||
npm run test:client:unit
|
||||
npm run build
|
||||
```
|
||||
|
||||
## 风险文件
|
||||
|
||||
- `workbench/client/src/App.tsx`:974 行单组件。面板 state 与拖拽回流都落在此处,是重渲染风险的集中点;必要时先抽出编辑状态再加面板。
|
||||
- `workbench/client/src/edit/session.ts`:**不应修改**。若实现中需要改动,说明 gesture 边界映射有误。
|
||||
- `workbench/client/src/edit/projection.ts`:`projectHandleValue` 的夹值是拖拽正确性的一部分(见其 75 行注释),不得为"统一行为"而移除。
|
||||
- `workbench/client/src/edit/preview-request.ts`:防抖与 `previewSeq` 仲裁由两条通道共用,任何改动同时影响拖拽。
|
||||
- `src/compile/direct-edit-solver.js`:**本任务不改**。若发现必须改,先确认不是把服务端校验缺口混进了本任务范围。
|
||||
|
||||
## 右侧工作台扩展(2026-09-01)
|
||||
|
||||
1. 抽出受控手风琴和选择对象摘要组件,建立“道路 / 元素 / 连接 / 高级”四段及其
|
||||
自动展开规则;先用静态现有内容验证不改变写入行为。
|
||||
2. 将现有 `Inspector` 的道路覆盖、连接、候选和技术详情迁入对应分段;将标线、箭头、
|
||||
信号迁入元素分段。保留 `ParameterPanel` 的 API 和直接编辑数据流。
|
||||
3. 补充箭头位置的米数读数和精确输入,与拖曳使用同一 staged override;输入非法值不暂存。
|
||||
4. 用组件/纯逻辑单测覆盖自动展开、分段摘要、箭头位置写入和不同写入语义;手测桌面及
|
||||
窄屏的空间、焦点和滚动。
|
||||
5. 执行 `npm run format:check`、`npm run test`、`npm run test:client`、
|
||||
`npm run test:client:unit`、`npm run build`,并验证选箭头、标线、信号、道路与连接的
|
||||
现有保存流程未回归。
|
||||
@@ -0,0 +1,118 @@
|
||||
# 参数面板与数值双向绑定
|
||||
|
||||
## 目标
|
||||
|
||||
给直接编辑加一个参数面板:选中道路后,每个可编辑参数以数值形式呈现,既能读到地图拖拽的实时结果,也能直接输入数值驱动几何。两条输入通道写同一份结构化约束,共用同一条预览、保存、撤销链路。
|
||||
|
||||
地图直接操纵**保留**,不被替换。面板是第二个平等的输入通道,不是拖拽的只读显示器。
|
||||
|
||||
## 已确认的事实
|
||||
|
||||
以下均为读代码核实,不是推断:
|
||||
|
||||
- `App.tsx:206` 的 `draftFor(handle, value)` 已经是纯函数 `(手柄, 数字) → 草稿`。拖拽只是产生这个数字的一种方式;输入框可以复用同一个入口。
|
||||
- `EditHandle.value` 是 `{ current, min, max, unit: 'meter' }`——**取值范围服务端早已下发**,客户端不需要新增来源。
|
||||
- `direct-edit-solver.js:136` 的 `numericValue(constraint, key, fallback)` 直接从约束读值,无约束时回落基线。**服务端从不改写用户输入的数字**;值非法时发阻塞诊断(`direct-edit-invalid-value`)拒绝,不做静默替换。因此不存在"请求值 vs 求解值"两个数字。
|
||||
- `App.tsx:197` 每次预览结算都 `setManifest(response.handles)` 整体替换 manifest,`value.current` 随之刷新。受控输入若直接绑定它,输入中间态(`1.`、`-`、空串)会被冲掉。
|
||||
- `projection.ts:60` 的 `projectHandleValue` 把拖拽值夹到 `[min, max]`,`ghost.show()` 与 `handlePositionFor()` 都按夹后的值绘制。拖拽越界时手柄停在极限、光标继续移动。
|
||||
- 服务端 `applyConstraint`(`direct-edit-solver.js:302/312/322` 附近)只校验 `Number.isFinite` 与非负,**未校验 manifest 的 `min`/`max`**。范围目前是纯客户端概念。
|
||||
- 外缘偏移的范围随道路宽度浮动(`±Math.max(0.1, width * 0.45)`);步行带固定 `0..8`;角部圆角固定 `0.5..30`。
|
||||
- `gestureIdentity()` 懒创建 operationId,`commitGesture()` 释放它。一次 gesture = `EditSession.commit()` 一次 = 一步 undo。该机制与指针无绑定关系。
|
||||
- `handle.constraintId` 仅在约束存在时出现,因此客户端能区分"未修改(基线回落)"与"显式设为该值"。
|
||||
- 区间由整条道路共享:`rangeDraftFor` 会把该路上所有约束一起重锚。`IntervalRangeHandle` 同时携带 `station` 与 `roadLengthMeters`。
|
||||
- 同一条路可有多个 `road-lane-divider` 手柄,靠 `boundaryIndex` 区分。
|
||||
- `direct-edit-solver.js` 写 `profile.interval`(290、472 行),但 `compileGeometry()` 不读它——`native-road.js` 中 `interval` 的唯一命中是方向箭头间距,与此无关。**每次直接编辑实际作用于整条道路。** 因此 `flag.ts:46` 的 `intervalEditingSupported` 为 `false`,range 手柄被隐藏。
|
||||
- 当前**没有任何参数面板**。与手柄相关的 UI 仅 `App.tsx:404` 状态栏一句 `手柄 ${n} 个`。
|
||||
- `handleDragEvent` 每次 mousemove 触发;`App.tsx` 是单个 974 行组件。
|
||||
|
||||
## 范围
|
||||
|
||||
### 1. 面板与读取
|
||||
|
||||
1. 选中道路后,面板按手柄列出可编辑参数:中文名、当前值、单位、合法范围。
|
||||
2. 多个 `road-lane-divider` 分别成行,用 `boundaryIndex` 标识,不按 kind 去重。
|
||||
3. 影响区间**每条路一行**(不是每个手柄一行),以米显示,`station` 仍是唯一存储真相。
|
||||
**受 `intervalEditingSupported` 门控**:该开关当前为 `false`,故本任务不渲染区间行。
|
||||
换算与显示逻辑仍按第 5 节实现并单测,随开关翻转一并生效。
|
||||
4. 每行标记该参数是否已被显式修改(依据 `handle.constraintId` 是否存在)。
|
||||
5. 不可编辑手柄(落在路口保留区)在面板中呈禁用态并显示 `disabledReason`。
|
||||
|
||||
### 2. 拖拽 → 数字
|
||||
|
||||
6. 拖拽过程中面板数值实时跟随,与地图 ghost 同步。
|
||||
7. 高频更新经 rAF 节流,不得每次 mousemove 触发整个 App 重渲染。
|
||||
|
||||
### 3. 数字 → 图形
|
||||
|
||||
8. 输入框修改值时走与拖拽相同的 `draftFor` → `PreviewRequester` 链路,含 80ms 防抖与 `previewSeq` 仲裁。
|
||||
9. gesture 边界:`focus` 对应 `pointerdown`(铸 operationId),`blur` / `Enter` 对应 `pointerup`(`commitGesture`)。输入 `1.53` 只产生**一步** undo。
|
||||
10. `Escape` 回滚到上一个有效值并 `cancel()` 在途请求。
|
||||
11. 聚焦期间输入框显示本地文本,失焦后跟随 `value.current`。中间态不被预览响应冲掉。
|
||||
12. `saveDirectEdits()` 入口先强制结算未闭合的 gesture,不依赖 blur 与 click 的触发顺序。
|
||||
|
||||
### 4. 范围处理
|
||||
|
||||
13. 拖拽与滑杆维持夹值(`projectHandleValue` 不变)。
|
||||
14. 数值输入**不夹值**:越界时标记非法、不发预览、不进 undo 栈,保留最后一个有效预览。
|
||||
15. 范围提示中的极值可一键填入。
|
||||
|
||||
### 5. 重置
|
||||
|
||||
16. 每行提供"重置",删除该约束回到基线。这是拖拽无法表达的操作——拖拽只能设值,不能移除约束。
|
||||
|
||||
## 明确不做
|
||||
|
||||
- 不移除、不削弱地图上的拖拽手柄。
|
||||
- 不新增约束 kind,不改动求解器几何逻辑。
|
||||
- 不补服务端 `min`/`max` 校验(见「已知缺口」,另立任务)。
|
||||
- 不做参数的批量编辑、复制粘贴、跨道路应用。
|
||||
- 不动 `JunctionTools` 的所有权边界;面板只呈现主地图拥有的 kind。
|
||||
- 不同步遗留 `workbench/client/app.js`。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [ ] 选中道路后面板列出全部可编辑参数;多条车道分隔各自成行且可独立修改。
|
||||
- [ ] 拖拽手柄时面板数值实时跟随;拖拽期间 React 重渲染次数经 rAF 收敛(非每 mousemove 一次)。
|
||||
- [ ] 输入框改值后地图预览更新,与拖到同一数值的结果一致。
|
||||
- [ ] 输入 `1.53` 后按 Ctrl+Z **一次**即回到修改前状态。
|
||||
- [ ] 输入过程中(如已键入 `1.`)到达的预览响应不会改写输入框内容。
|
||||
- [ ] 输入越界值:字段标红、不发预览请求(可由网络面板证明)、保留上一个有效预览、blur 后不产生 undo 步骤。
|
||||
- [ ] 点击范围提示中的极值可一键填入并正常提交。
|
||||
- [ ] 拖拽越界时手柄停在极限位置,行为与改动前一致。
|
||||
- [ ] 未修改参数与显式设为基线值的参数在面板上可区分;"重置"能删除约束并使该行回到未修改态。
|
||||
- [ ] 影响区间的米↔station 换算函数经单测覆盖,往返无累积漂移。(区间行本身受 `intervalEditingSupported` 门控,当前不渲染。)
|
||||
- [ ] 输入未失焦时直接点"保存",该次修改被正确持久化。
|
||||
- [ ] 路口保留区内的手柄在面板中禁用并显示原因。
|
||||
- [ ] `npm run format:check`、`npm run test`、`npm run test:client`、`npm run test:client:unit`、`npm run build` 全绿。
|
||||
|
||||
## 风险与门槛
|
||||
|
||||
- 面板不得成为第二套几何或第二个值的真相来源。所有范围、位置、影响对象仍只来自服务端 manifest。
|
||||
- `value.current` 是**请求值的回显**而非求解值。若后续 solver 改成回写求解结果,第 11 条的显示规则失效,必须同步重审。
|
||||
- 外缘偏移的 `min`/`max` 随道路宽度浮动,因此"当前合法"不等于"永远合法"。客户端校验只能覆盖输入当下。
|
||||
- 拖拽回流若实现为直接 `setState`,会逐帧重渲染 974 行的 `App`。必须先确认节流有效再扩大面板规模。
|
||||
|
||||
## 已知缺口(不在本任务内)
|
||||
|
||||
服务端只校验 finite/非负,不校验 manifest 的 `min`/`max`;而外缘偏移范围随道路宽度浮动,意味着保存时合法的值可能在几何变化后越界。这类越界**客户端结构上无法拦截**——它发生在保存之后的求解期。
|
||||
|
||||
`design.md` 已为 `boundaryIndex` 定义了同类规则("重放时若车道数变化导致越界,该约束转 `stale`"),数值范围越界应当同等处理。属重放正确性,独立成任务。
|
||||
|
||||
## 右侧工作台扩展(2026-09-01)
|
||||
|
||||
当前右侧栏将道路基础覆盖、直接编辑参数、路口连接、车道转向箭头、标线样式、
|
||||
原生信号灯、复杂路口候选和技术 JSON 直接按顺序堆叠,缺少所选对象摘要、明确的
|
||||
编辑上下文和一致的表单层级。用户确认本轮应覆盖全部既有编辑器,而非只处理道路
|
||||
参数或车道箭头。
|
||||
|
||||
拟纳入范围:
|
||||
|
||||
- 统一右侧栏的对象摘要、未保存/即时保存状态和表单布局。
|
||||
- 重新组织道路、元素、连接、调试/技术详情中的全部既有表单与信息展示。
|
||||
- 为车道转向箭头补足距路口位置的可读数与精确输入,继续复用
|
||||
`placementDistanceMeters` 覆盖和既有拖曳行为。
|
||||
- 保持各写入语义:普通 override 继续暂存并经保存/重新生成生效;信号灯继续走
|
||||
现有即时 API;直接编辑继续走 manifest/preview/session 链路。
|
||||
|
||||
已决 UX:右栏使用手风琴式可折叠分段,以控制地图工作台中的垂直空间占用。
|
||||
所选地图元素的关联编辑段自动展开;调试与技术详情默认收起。
|
||||
+108
@@ -0,0 +1,108 @@
|
||||
# manifest 范围与求解器可行域不一致
|
||||
|
||||
日期:2026-08-31
|
||||
来源:`08-31-parameter-panel-binding` 实施期间对运行中工作台(`osm-KZZP9U`)的实测。
|
||||
|
||||
## 现象
|
||||
|
||||
手柄 `handle:road-edge-offset:segment:way/-3246/0:left`,manifest 声明
|
||||
`value.min = -2.925`、`value.max = 2.925`(即 `±width * 0.45`,道路宽 6.5m)。
|
||||
|
||||
逐值探测 `POST /api/edit-preview`:
|
||||
|
||||
| offsetMeters | 阻塞诊断 |
|
||||
| --- | --- |
|
||||
| -2.90 | `direct-edit-outer-edges-cross` |
|
||||
| -2.00 | `direct-edit-outer-edges-cross` |
|
||||
| -1.00 | `direct-edit-outer-edges-cross` |
|
||||
| **-0.50** | **(无)** |
|
||||
| **0.00** | **(无)** |
|
||||
| **0.50** | **(无)** |
|
||||
| **1.00** | **(无)** |
|
||||
| 2.00 | `direct-edit-outer-edges-cross` |
|
||||
| 2.90 | `direct-edit-outer-edges-cross` |
|
||||
| 500 | `direct-edit-outer-edges-cross` |
|
||||
|
||||
探针构造已排除误报:小幅值干净,说明请求本身合法。
|
||||
|
||||
## 结论
|
||||
|
||||
**manifest 宣告的范围比求解器实际接受的可行域宽约 3 倍,且双向都是。**
|
||||
真实边界落在 `(-1.0, -0.5]` 与 `[1.0, 2.0)` 之间,未进一步二分。
|
||||
|
||||
失败原因未查明。`direct-edit-outer-edges-cross` 对应 design.md 的
|
||||
「同一站点左右外缘不得交叉」不变量,但仅移动**单侧**外缘 1m
|
||||
(6.5m 宽的路)为何会触发交叉,需要读 `compileGeometry()` 才能确定——
|
||||
可能经由车道最小宽度 2.4m 派生,也可能诊断名不完全对应其实际判据。
|
||||
|
||||
## 与既有行为的关系
|
||||
|
||||
这不是本任务引入的。拖拽一直夹到 `±2.925`,所以用户一直能拖进被拒区间——
|
||||
拖过约 1m 后几何冻结、诊断出现,而手柄继续走到 2.925。
|
||||
按 design.md「无效草稿不替换最后一个有效预览」,这是既定行为。
|
||||
|
||||
参数面板没有改变它,但**把它变可见了**:范围以文字打印,且极值可一键填入。
|
||||
点击极值会得到一个必被服务端拒绝的值。
|
||||
|
||||
## 处理
|
||||
|
||||
未在本任务修改。理由:
|
||||
|
||||
- 客户端范围校验必须用 manifest 的 `min`/`max`,用别的就是发明第二个真相来源
|
||||
(`direct-edit-client.md` §2)。
|
||||
- 收窄范围需要求解器解析地算出外缘交叉的可行区间,属求解器工作,
|
||||
本任务明确排除。
|
||||
- 点击极值的结果是一个诚实的服务端拒绝:诊断可见、最后一个有效预览保留、可撤销。
|
||||
不是静默破坏。
|
||||
|
||||
已并入 `08-31-constraint-range-validation` 的需求。
|
||||
|
||||
---
|
||||
|
||||
# 追加:`junction-crosswalk-inset` 的静默死区
|
||||
|
||||
日期:2026-08-31,区域 `nantaizihu-9PTsZg`。
|
||||
|
||||
手柄 `handle:junction-crosswalk-inset:node/1140799725:segment:way/-3246/0`
|
||||
声明 `value.min = 0`、`value.max = 8`。逐值提交预览并测量该组 6 条斑马线的中心位移:
|
||||
|
||||
| inset | 相对 inset=0 的位移 | 增量 |
|
||||
| --- | --- | --- |
|
||||
| 0 | 0.00 | — |
|
||||
| 0.5 | 0.50 | +0.50 |
|
||||
| 1.0 | 1.00 | +0.50 |
|
||||
| 2.0 | 2.00 | +0.50 |
|
||||
| 3.0 | 3.00 | +0.50 |
|
||||
| 4.0 | 3.20 | +0.20 |
|
||||
| 5.0 | 3.20 | **+0.00** |
|
||||
| 6.0 | 3.20 | **+0.00** |
|
||||
| 8.0 | 3.20 | **+0.00** |
|
||||
|
||||
`0 → 3.2` 是干净的 1:1 线性响应;`3.2 → 8` **完全无响应,且无任何诊断**。
|
||||
|
||||
## 成因
|
||||
|
||||
`crossingJunctionInset()`(`native-road.js:1325`):
|
||||
|
||||
```js
|
||||
const targetDistance = Math.max(0, plan.cutbackMeters - inset);
|
||||
return Math.min(CROSSWALK_MAX_JUNCTION_INSET_METERS,
|
||||
Math.max(0, candidate.junctionDistanceMeters - targetDistance));
|
||||
```
|
||||
|
||||
inset 增至 `plan.cutbackMeters` 后 `targetDistance` 触底为 0,再增无效;
|
||||
外层 `CROSSWALK_MAX_JUNCTION_INSET_METERS = 4` 另有封顶。
|
||||
因此有效上界是 `min(cutbackMeters, …)` 的某个函数,**逐进口不同**,
|
||||
而 manifest 对所有进口一律发布固定的 `max: 8`。
|
||||
|
||||
## 为何比外缘偏移那例更严重
|
||||
|
||||
外缘偏移越界会返回阻塞诊断——用户看得到"不行"。
|
||||
本例越界**什么都不发生**:拖动手柄,几何纹丝不动,没有诊断、没有提示。
|
||||
与「控件坏了」无法区分。
|
||||
|
||||
这正是 `flag.ts` 为 `profile.interval` 立下的规矩所要避免的
|
||||
(「一个拖了没效果的控件比没有控件更糟」),区别只在于它发生在量程的上半段,
|
||||
而不是整个控件。
|
||||
|
||||
若用户在已处于死区的进口上首次尝试拖拽,得到的印象就是"直接编辑不工作"。
|
||||
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"id": "parameter-panel-binding",
|
||||
"name": "parameter-panel-binding",
|
||||
"title": "参数面板与数值双向绑定",
|
||||
"description": "为直接编辑加参数面板:数值输入与地图拖拽双向绑定,共用同一条约束/预览/undo 链路",
|
||||
"status": "completed",
|
||||
"dev_type": null,
|
||||
"scope": null,
|
||||
"package": null,
|
||||
"priority": "P2",
|
||||
"creator": "dingkang",
|
||||
"assignee": "dingkang",
|
||||
"createdAt": "2026-08-31",
|
||||
"completedAt": "2026-09-03",
|
||||
"branch": null,
|
||||
"base_branch": "main",
|
||||
"worktree_path": null,
|
||||
"commit": null,
|
||||
"pr_url": null,
|
||||
"subtasks": [],
|
||||
"children": [],
|
||||
"parent": "08-26-direct-manipulation-road-editor",
|
||||
"relatedFiles": [],
|
||||
"notes": "",
|
||||
"meta": {}
|
||||
}
|
||||
@@ -0,0 +1,2 @@
|
||||
{"file": ".trellis/spec/frontend/direct-edit-client.md", "reason": "Check no baseline writes, per-pointermove React churn, or accidental rotation path."}
|
||||
{"file": ".trellis/spec/guides/cross-layer-thinking-guide.md", "reason": "Check position serialization, validation, and recompile behavior across layers."}
|
||||
@@ -0,0 +1,28 @@
|
||||
# Design: Lane Maneuver Position Drag
|
||||
|
||||
## Selection And Gesture
|
||||
|
||||
The selected arrow group remains one logical target: `lane_id + maneuver`. A new
|
||||
display-only selection layer will become the drag hit target, while its members are
|
||||
never moved independently. Pointer coordinates are projected onto the lane centerline
|
||||
and converted to a distance from the lane's junction end, matching the compiler's
|
||||
`placement_distance_meters` convention.
|
||||
|
||||
## Contract
|
||||
|
||||
The existing `lane-maneuver` override gains optional finite, non-negative
|
||||
`placementDistanceMeters`, measured from the lane's junction end. The compiler uses
|
||||
it when present, otherwise keeps its current candidate-placement algorithm
|
||||
byte-for-byte. Maneuver and position are updated together by lane id so an old
|
||||
maneuver override cannot shadow a newer position entry.
|
||||
|
||||
## Validation And Preview
|
||||
|
||||
The server remains authoritative for collision checks and final geometry. The client
|
||||
may project and clamp the ghost for responsive feedback, but it must submit the
|
||||
position through the existing save/recompile boundary and never mutate baseline
|
||||
GeoJSON. The candidate position must clear control features and leave the compiler's
|
||||
endpoint safety buffer.
|
||||
|
||||
Rotation is intentionally absent from the contract; adding it later must not require
|
||||
reinterpretation of the position field.
|
||||
@@ -0,0 +1,2 @@
|
||||
{"file": ".trellis/spec/frontend/direct-edit-client.md", "reason": "Reuse the existing projection, ghost, baseline ownership, and save-boundary rules for a new lane-arrow gesture."}
|
||||
{"file": ".trellis/spec/guides/cross-layer-thinking-guide.md", "reason": "Trace the new position field from UI through override validation and compiler placement."}
|
||||
@@ -0,0 +1,14 @@
|
||||
# Implementation Plan
|
||||
|
||||
1. Resolve invalid-position behavior and freeze the wire field name/units in the PRD.
|
||||
2. Add compiler validation and placement override handling with empty-override parity tests.
|
||||
3. Add a lane-arrow drag interaction that projects along the lane and moves the complete part group.
|
||||
4. Add authoritative save/recompile wiring and focused client/server regression tests.
|
||||
5. Run format, server tests, client type/unit tests, and production build; manually verify
|
||||
an existing and a newly-added arrow in the workbench.
|
||||
|
||||
## Explicit Non-Goals
|
||||
|
||||
- Arrow rotation or arbitrary lateral movement.
|
||||
- Position editing for `native-road-direction-arrow/v1`.
|
||||
- Per-part dragging or a second undo/preview protocol.
|
||||
@@ -0,0 +1,59 @@
|
||||
# 车道转向箭头位置拖曳
|
||||
|
||||
## Goal
|
||||
|
||||
TBD.
|
||||
|
||||
## Requirements
|
||||
|
||||
- TBD
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] TBD
|
||||
|
||||
## Notes
|
||||
|
||||
- Keep `prd.md` focused on requirements, constraints, and acceptance criteria.
|
||||
- Lightweight tasks can remain PRD-only.
|
||||
- For complex tasks, add `design.md` for technical design and `implement.md` for execution planning before `task.py start`.
|
||||
# 车道转向箭头位置拖曳
|
||||
|
||||
## 目标
|
||||
|
||||
让用户可以把一个完整的路口转向箭头沿所属车道拖到新的位置。箭头的 polygon
|
||||
part 必须整体平移,内部形状、part 顺序和 `maneuver` 不变;旋转和箭头内容修改
|
||||
不属于本任务。
|
||||
|
||||
## 已确认事实
|
||||
|
||||
- 一个视觉箭头由同一 `lane_id + maneuver` 下的 3 或 5 个 polygon part 组成,点击
|
||||
任一 part 已能选中整组。
|
||||
- 编译器目前以 `placement_distance_meters` 记录箭头距路口端的距离,并在 6/10/14/18/22m
|
||||
候选位置中避开斑马线和停止线。该字段目前是输出值,还没有 override 合同。
|
||||
- 车道中心线已作为无箭头车道的选择入口;位置拖曳必须同时适用于已有箭头和刚新增的箭头。
|
||||
- 现有 v2 拖曳链路按车道轴投影、以服务端预览为准;箭头位置属于新的离散/连续混合
|
||||
override,不能伪装成道路宽度或路口偏移 constraint。
|
||||
|
||||
## 范围
|
||||
|
||||
1. 拖曳完整 `lane_id + maneuver` 箭头组,保持 part 相对几何不变。
|
||||
2. 将拖曳位置保存为 `lane-maneuver.placementDistanceMeters`(从车道驶入路口端量起的米数),
|
||||
并在保存/重新生成后由编译器读取。
|
||||
3. 位置必须沿车道中心线投影,不能改变横向位置;不能越过车道有效端点或与斑马线、停止线重叠。
|
||||
4. 已有的 maneuver 下拉框继续有效;旋转手柄、角度字段和沿路 `directionArrows` 不在范围内。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [ ] 拖曳任一箭头 part 会整体移动同组所有 part,不拆散、不改变形状和旋转。
|
||||
- [ ] 拖曳释放时位置按车道轴投影并受有效范围约束;服务端正式编译输出的
|
||||
`placement_distance_meters` 反映新位置。
|
||||
- [ ] 新增箭头后也能拖曳其位置;刷新或重新编译不会回到旧位置。
|
||||
- [ ] 箭头不能落在斑马线/停止线范围内,也不能超出车道安全端点。
|
||||
- [ ] 未设置位置覆盖时,输出与现有编译结果字节一致。
|
||||
- [ ] 旋转、沿路重复方向箭头和既有 v2 控件行为不回归。
|
||||
|
||||
## 关键决策
|
||||
|
||||
当用户把箭头拖向无效区域(控制设施或安全端点)时,连续夹紧到最近合法位置,
|
||||
并在拖动过程中让完整箭头组停在该位置。这个行为与现有 v2 数值拖曳一致。
|
||||
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"id": "lane-maneuver-position-drag",
|
||||
"name": "lane-maneuver-position-drag",
|
||||
"title": "车道转向箭头位置拖曳",
|
||||
"description": "",
|
||||
"status": "completed",
|
||||
"dev_type": null,
|
||||
"scope": null,
|
||||
"package": null,
|
||||
"priority": "P2",
|
||||
"creator": "dingkang",
|
||||
"assignee": "dingkang",
|
||||
"createdAt": "2026-09-01",
|
||||
"completedAt": "2026-09-03",
|
||||
"branch": null,
|
||||
"base_branch": "main",
|
||||
"worktree_path": null,
|
||||
"commit": null,
|
||||
"pr_url": null,
|
||||
"subtasks": [],
|
||||
"children": [],
|
||||
"parent": null,
|
||||
"relatedFiles": [],
|
||||
"notes": "",
|
||||
"meta": {}
|
||||
}
|
||||
@@ -0,0 +1 @@
|
||||
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
|
||||
@@ -0,0 +1,3 @@
|
||||
# Design
|
||||
|
||||
新增纯逻辑 descriptor/状态模型和独立热点图层 adapter;输入只读编译状态,输出 `JunctionRef`,不写 active document。
|
||||
@@ -0,0 +1 @@
|
||||
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
|
||||
@@ -0,0 +1,21 @@
|
||||
# Implementation
|
||||
|
||||
先为 node/cluster/candidate 派生逻辑加单测,再接 MapCanvas 热区渲染和点击路由;验证与现有道路/设施命中隔离。
|
||||
# Implementation
|
||||
|
||||
1. Add a pure descriptor model deriving editable node, readonly configured cluster,
|
||||
and candidate cluster hotspots from the compiled state.
|
||||
2. Add a dedicated OpenLayers hotspot layer with visibility control and isolated
|
||||
click handling that returns a stable `JunctionRef`.
|
||||
3. Add unit coverage for descriptor stability and node/cluster/candidate status.
|
||||
|
||||
## Progress
|
||||
|
||||
- [x] Pure descriptor model and stable `JunctionRef`
|
||||
- [x] Dedicated hotspot layer and map click adapter
|
||||
- [x] Client type-check, unit tests, format check, and production build
|
||||
|
||||
## Deferred
|
||||
|
||||
- Independent JunctionTools route and session lifecycle belong to the workspace
|
||||
child task and are intentionally not implemented here.
|
||||
@@ -0,0 +1,20 @@
|
||||
# 路口识别与热区模型
|
||||
|
||||
## Goal
|
||||
|
||||
从编译模型派生普通 node、已确认 cluster 和 candidate cluster 的路口描述与可点击热区。
|
||||
|
||||
## Requirements
|
||||
|
||||
- 热区不新增持久化几何事实;来源必须是 junction plan、cluster 配置和诊断。
|
||||
- 普通 node 可进入编辑;已确认 cluster 显示 cluster 级热区;candidate 明确显示待确认状态。
|
||||
- 热区点击必须返回稳定 `JunctionRef` 和地图位置,不与道路/设施选择竞争。
|
||||
- 热区范围覆盖路口核心及必要的进口上下文,并可解释其来源。
|
||||
- 普通 node 热区可进入编辑;已确认 cluster 热区只读;candidate cluster 热区只展示状态、组成道路和诊断。
|
||||
- 本任务不得提供 candidate 确认或 cluster 持久化创建动作。
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] 同一编译状态下热区与 junction descriptor 一致且稳定。
|
||||
- [ ] node、cluster、candidate 的状态和点击行为有纯逻辑测试。
|
||||
- [ ] 热区图层开关、选中态和空白点击行为不破坏现有地图。
|
||||
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"id": "junction-detection-hotspot",
|
||||
"name": "junction-detection-hotspot",
|
||||
"title": "路口识别与热区模型",
|
||||
"description": "",
|
||||
"status": "completed",
|
||||
"dev_type": null,
|
||||
"scope": null,
|
||||
"package": null,
|
||||
"priority": "P2",
|
||||
"creator": "dingkang",
|
||||
"assignee": "dingkang",
|
||||
"createdAt": "2026-09-02",
|
||||
"completedAt": "2026-09-03",
|
||||
"branch": null,
|
||||
"base_branch": "main",
|
||||
"worktree_path": null,
|
||||
"commit": null,
|
||||
"pr_url": null,
|
||||
"subtasks": [],
|
||||
"children": [],
|
||||
"parent": "08-26-direct-edit-junction-tools",
|
||||
"relatedFiles": [],
|
||||
"notes": "",
|
||||
"meta": {}
|
||||
}
|
||||
@@ -0,0 +1 @@
|
||||
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
|
||||
@@ -0,0 +1,3 @@
|
||||
# Design
|
||||
|
||||
设施层只保存现有语义文档;JunctionTools 汇总设施约束、受影响图层和阻塞诊断,发布前复用导出契约校验。
|
||||
@@ -0,0 +1 @@
|
||||
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
|
||||
@@ -0,0 +1,14 @@
|
||||
# Implementation
|
||||
|
||||
接入斑马线/停止线/信号灯联动与诊断,再补保存、取消、撤销/重做、导出回归;所有产品改动等待用户复核后提交。
|
||||
|
||||
## Progress
|
||||
|
||||
- [x] 工作区展示已有斑马线、停止线、信号灯数量
|
||||
- [x] 汇总路口关联诊断并区分阻塞/提示
|
||||
- [x] 客户端类型检查、单元测试、格式检查和生产构建
|
||||
- [x] 全量服务端与工作台集成测试
|
||||
|
||||
## Deferred
|
||||
|
||||
- 设施的创建、删除和独立位置编辑仍按已决边界留给后续任务;本阶段只做已有设施的上下文展示与验证摘要。
|
||||
@@ -0,0 +1,20 @@
|
||||
# 路口设施与验证闭环
|
||||
|
||||
## Goal
|
||||
|
||||
在 JunctionTools 中协调斑马线、停止线、信号灯及发布前诊断,形成可复核的路口交付闭环。
|
||||
|
||||
## Requirements
|
||||
|
||||
- 设施编辑复用现有元素语义和交通信号文档,不复制 GeoJSON。
|
||||
- 设施必须受所属进口/路口几何约束,越界时给出结构化诊断。
|
||||
- 发布前展示受影响对象、阻塞问题、文档版本和导出契约状态。
|
||||
- 保存、取消、撤销/重做和导出行为与主地图保持一致。
|
||||
- 首期只允许修改已有斑马线、停止线和信号灯的语义位置或参数,不允许创建或删除设施。
|
||||
- 自交、越界和几何不可解为 `blocking`;设施缺失或间距不足等非致命问题可为 `warning`,UI 依赖稳定诊断 code/severity。
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] 设施联动 preview 包含斑马线、停止线和信号灯派生对象。
|
||||
- [ ] 非法设施位置不会替换最后有效预览。
|
||||
- [ ] 保存后导出包契约不变,完整回归测试通过。
|
||||
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"id": "junction-facilities-validation",
|
||||
"name": "junction-facilities-validation",
|
||||
"title": "路口设施与验证闭环",
|
||||
"description": "",
|
||||
"status": "completed",
|
||||
"dev_type": null,
|
||||
"scope": null,
|
||||
"package": null,
|
||||
"priority": "P2",
|
||||
"creator": "dingkang",
|
||||
"assignee": "dingkang",
|
||||
"createdAt": "2026-09-02",
|
||||
"completedAt": "2026-09-03",
|
||||
"branch": null,
|
||||
"base_branch": "main",
|
||||
"worktree_path": null,
|
||||
"commit": null,
|
||||
"pr_url": null,
|
||||
"subtasks": [],
|
||||
"children": [],
|
||||
"parent": "08-26-direct-edit-junction-tools",
|
||||
"relatedFiles": [],
|
||||
"notes": "",
|
||||
"meta": {}
|
||||
}
|
||||
@@ -0,0 +1 @@
|
||||
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
|
||||
@@ -0,0 +1,3 @@
|
||||
# Design
|
||||
|
||||
建立 node/cluster 共用的 effective junction plan;solver 是唯一语义来源,`complex-junction.js` 只消费求解结果并生成派生图层。
|
||||
@@ -0,0 +1 @@
|
||||
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
|
||||
@@ -0,0 +1,13 @@
|
||||
# Implementation
|
||||
|
||||
先统一锚点和计划,再逐项接宽度、cutback、圆角,最后验证完整 preview、失败保留和正式编译一致性。
|
||||
|
||||
## Progress
|
||||
|
||||
- [x] 统一输出 `effectiveJunctionPlans`
|
||||
- [x] 普通 node 输出可写计划,cluster 输出聚合只读计划
|
||||
- [x] 编译入口透传 junction template,上层 solver 单测覆盖
|
||||
- [x] 工作区三项几何控件接入 ParameterPanel,共享 preview/apply/save 回调(普通 node)
|
||||
- [x] 失败拟合、乱序预览和正式编译一致性 E2E
|
||||
|
||||
预览请求层已有失败保留、乱序丢弃的单元回归;本轮补充服务端工作流回归,验证真实路口进口宽度从预览到保存再到正式编译发布的几何一致性。
|
||||
@@ -0,0 +1,20 @@
|
||||
# 路口几何与拓扑编辑
|
||||
|
||||
## Goal
|
||||
|
||||
让 node/cluster 的路口编辑约束由同一套 effective plan 驱动,避免参数和复杂路口几何脱节。
|
||||
|
||||
## Requirements
|
||||
|
||||
- 统一进口宽度、cutback、角部圆角的 node/cluster 锚点和求解输入。
|
||||
- 预览覆盖道路面、路口面、步行带、车道中心线、connector/movement 和控制设施。
|
||||
- 最小车道宽度、边界连续、自交和 connector 越界必须阻塞并保留最后有效预览。
|
||||
- cluster 不得被静默拆成多个 node 编辑。
|
||||
- 阶段 B 仅允许普通 node 写入三项既有约束;cluster 仅验证只读 effective plan,不开放写入。
|
||||
- 车道和 connector 在本阶段作为预览、诊断和影响对象展示,不提供拓扑创建、删除或重连。
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] 三类约束在 node 和已确认 cluster 上均有可验证的 effective plan。
|
||||
- [ ] 乱序 preview、失败拟合和保存重编译有测试。
|
||||
- [ ] 同一约束集的 preview 与正式编译结果一致。
|
||||
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"id": "junction-geometry-editor",
|
||||
"name": "junction-geometry-editor",
|
||||
"title": "路口几何与拓扑编辑",
|
||||
"description": "",
|
||||
"status": "completed",
|
||||
"dev_type": null,
|
||||
"scope": null,
|
||||
"package": null,
|
||||
"priority": "P2",
|
||||
"creator": "dingkang",
|
||||
"assignee": "dingkang",
|
||||
"createdAt": "2026-09-02",
|
||||
"completedAt": "2026-09-03",
|
||||
"branch": null,
|
||||
"base_branch": "main",
|
||||
"worktree_path": null,
|
||||
"commit": null,
|
||||
"pr_url": null,
|
||||
"subtasks": [],
|
||||
"children": [],
|
||||
"parent": "08-26-direct-edit-junction-tools",
|
||||
"relatedFiles": [],
|
||||
"notes": "",
|
||||
"meta": {}
|
||||
}
|
||||
@@ -0,0 +1 @@
|
||||
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
|
||||
@@ -0,0 +1,3 @@
|
||||
# Design
|
||||
|
||||
以现有编译模型、RoadRunner 可观察工作流和父任务约束为证据源,产出术语表、能力矩阵、阶段边界和验收映射;不引入代码依赖。
|
||||
@@ -0,0 +1 @@
|
||||
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
|
||||
@@ -0,0 +1,3 @@
|
||||
# Implementation
|
||||
|
||||
整理官方/公开资料与仓库证据,记录事实、推断和未知;评审通过后再冻结父任务 PRD,不启动产品代码。
|
||||
@@ -0,0 +1,23 @@
|
||||
# 路口需求与RoadRunner能力调研
|
||||
|
||||
## Goal
|
||||
|
||||
建立 RoadRunner Junction 对标与本项目需求基线,明确用户流程、术语、约束和阶段边界。
|
||||
|
||||
## Requirements
|
||||
|
||||
- 区分 RoadRunner 可观察能力、不可验证的内部实现和本项目必须自研的部分。
|
||||
- 定义 node、cluster、candidate、hotspot、JunctionRef、session 的统一术语。
|
||||
- 输出阶段 A-D 的范围、风险和验收标准。
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] 需求文档包含用户流程、约束、不做项和可观察验收。
|
||||
- [ ] 所有 RoadRunner 对标结论标注证据或推断来源。
|
||||
- [ ] 父任务和后续子任务可直接引用该基线。
|
||||
|
||||
## Notes
|
||||
|
||||
- Keep `prd.md` focused on requirements, constraints, and acceptance criteria.
|
||||
- Lightweight tasks can remain PRD-only.
|
||||
- For complex tasks, add `design.md` for technical design and `implement.md` for execution planning before `task.py start`.
|
||||
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"id": "junction-requirements-research",
|
||||
"name": "junction-requirements-research",
|
||||
"title": "路口需求与RoadRunner能力调研",
|
||||
"description": "",
|
||||
"status": "completed",
|
||||
"dev_type": null,
|
||||
"scope": null,
|
||||
"package": null,
|
||||
"priority": "P2",
|
||||
"creator": "dingkang",
|
||||
"assignee": "dingkang",
|
||||
"createdAt": "2026-09-02",
|
||||
"completedAt": "2026-09-03",
|
||||
"branch": null,
|
||||
"base_branch": "main",
|
||||
"worktree_path": null,
|
||||
"commit": null,
|
||||
"pr_url": null,
|
||||
"subtasks": [],
|
||||
"children": [],
|
||||
"parent": "08-26-direct-edit-junction-tools",
|
||||
"relatedFiles": [],
|
||||
"notes": "",
|
||||
"meta": {}
|
||||
}
|
||||
Loaded 100 of 372 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user