chore(task): archive 08-18-native-traffic-signal-parity
This commit is contained in:
@@ -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,55 @@
|
||||
# Design
|
||||
|
||||
## Source Of Truth And Migration
|
||||
|
||||
The native compiler owns a versioned area-local signal model and override
|
||||
artifact. It is generated from OSM controls and native geometry inputs, then
|
||||
edited by the Workbench without QGIS. The existing
|
||||
`traffic_signal_assemblies.geojson` is a migration adapter: it can be imported
|
||||
into the native model and exported for legacy QGIS/reimport workflows, but a
|
||||
native compile never requires it to exist.
|
||||
|
||||
The existing `buildTrafficSignalFeatures()` and validation functions remain the
|
||||
compatibility implementation for initial generation and import/export. Imported
|
||||
features retain their legacy `signal_uid` where valid; newly generated native
|
||||
features use the same deterministic identity rule so downstream runtime IDs do
|
||||
not fork.
|
||||
|
||||
## Workbench API And Editing
|
||||
|
||||
`GET /api/state` adds the normalized native signal model, source control
|
||||
metadata, migration provenance, and derived runtime signal records. A signal
|
||||
edit is represented as an atomic replacement of the validated native signal
|
||||
override artifact through a dedicated signal save endpoint. A separate import
|
||||
or export action handles the legacy QGIS collection; road overrides remain in
|
||||
their existing file and schema.
|
||||
|
||||
The browser uses stable `signal_uid` values. It supports:
|
||||
|
||||
- generate: choose an OSM traffic-signal control and arm, then create the
|
||||
deterministic assembly using the existing generator contract;
|
||||
- move: update the Point coordinates while retaining stop-line/source fields;
|
||||
- rotate: update `heading_deg` with normalized degrees;
|
||||
- delete: remove the assembly from the editable collection;
|
||||
- edit enabled state, display ID, mast reach, z offset, and phase group.
|
||||
|
||||
Every save validates uniqueness, identity, finite geometry, source references,
|
||||
and field ranges before an atomic write. Deleted features are absent from the
|
||||
runtime output; disabled features remain in the editable/QGIS layer but are
|
||||
omitted by `buildTrafficSignalsFromFeatures()`.
|
||||
|
||||
## Delivery Flow
|
||||
|
||||
The native road compile result includes signal assemblies and derived runtime
|
||||
metadata without adding them to road geometry layers. Native Blender/Cesium
|
||||
stages consume `traffic_signals.json` and dynamic GLB inputs generated directly
|
||||
from the native model. The legacy QGIS adapter may materialize the old GeoJSON,
|
||||
but it is not in the native build's critical path.
|
||||
|
||||
## Compatibility And Rollback
|
||||
|
||||
QGIS reimport continues to read/export the compatibility GeoJSON while the
|
||||
legacy path remains unchanged. If native signal editing fails validation, the
|
||||
previous atomic native override remains in place and the user receives a
|
||||
field-level error. Rollback is selecting the legacy provider or exporting the
|
||||
last native state to the QGIS adapter.
|
||||
@@ -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,31 @@
|
||||
# Implementation Plan
|
||||
|
||||
1. Define the native signal model/override artifact and migration adapter;
|
||||
reuse existing generation, validation, and deterministic signal UID rules.
|
||||
2. Add QGIS import/export commands that translate
|
||||
`traffic_signal_assemblies.geojson` to/from the native artifact without
|
||||
making native compile depend on QGIS.
|
||||
3. Extend native compile/workbench state to expose signal assemblies, OSM
|
||||
controls/arms, and derived runtime provenance.
|
||||
4. Add validated atomic signal save operations for generate, move, rotate,
|
||||
delete, and field edits; preserve legacy ID compatibility.
|
||||
5. Add Workbench map styling, selection, editing controls, dirty state, save,
|
||||
compile/reload, and clear error handling for signal assemblies.
|
||||
6. Ensure native Blender/Cesium/preview stages consume runtime signal data
|
||||
generated from the native model, while legacy stages remain compatible.
|
||||
7. Add focused traffic-signal, Workbench, migration, and cross-layer round-trip tests;
|
||||
run the existing legacy traffic-signal and preview suites.
|
||||
|
||||
## Validation
|
||||
|
||||
```bash
|
||||
npm run test:traffic-signals
|
||||
npm run test:preview-assets
|
||||
npm run test:road-workbench
|
||||
npm run road:compile -- --config config/areas/nantaizi-lake-innovation-valley.json
|
||||
npm run road:check -- --config config/areas/nantaizi-lake-innovation-valley.json
|
||||
```
|
||||
|
||||
Manual acceptance must cover native-only generate/move/rotate/delete -> save ->
|
||||
recompile -> runtime JSON and preview, plus QGIS import/export compatibility;
|
||||
disabled signals must be omitted from runtime output.
|
||||
@@ -0,0 +1,55 @@
|
||||
# Native traffic signal parity with QGIS
|
||||
|
||||
## Goal
|
||||
|
||||
Move traffic-signal ownership from the QGIS editing chain into the native road
|
||||
compiler and Workbench. Existing QGIS signal assemblies remain import/export
|
||||
compatibility data during migration, but native overrides become the long-term
|
||||
source for generation, editing, and Blender/Cesium/preview delivery.
|
||||
|
||||
## Confirmed Facts
|
||||
|
||||
- QGIS currently edits `traffic_signal_assemblies.geojson`; this is the
|
||||
migration input/output contract, not the desired long-term authority.
|
||||
- `scripts/reimport-gpkg.js` validates and reimports that legacy layer.
|
||||
- `scripts/build-area.js` currently derives runtime `traffic_signals.json` from
|
||||
the edited assemblies; the native path must replace this dependency.
|
||||
- Existing native road layers do not read traffic-signal artifacts. Historical
|
||||
native Cesium work intentionally omitted signal runtime assets.
|
||||
- Stable signal identity and editable fields already include `signal_uid`,
|
||||
enabled state, source/control/approach IDs, arm direction, pose, mast reach,
|
||||
and phase-group/runtime data.
|
||||
|
||||
## Requirements
|
||||
|
||||
- R1: Native compile/workbench must own a versioned area-local signal model and
|
||||
override artifact, with an explicit one-time/import compatibility path from
|
||||
existing QGIS assemblies.
|
||||
- R2: Workbench state must expose signal provenance and the existing editable
|
||||
signal fields using stable IDs, and support generating, moving, rotating,
|
||||
and deleting signal assemblies.
|
||||
- R3: Native compile and preview delivery must generate runtime signal data
|
||||
directly from the native model, preserving enabled/disabled state, arm
|
||||
direction/pose, and phase-group data without requiring QGIS.
|
||||
- R4: A compatibility adapter must import/export the existing QGIS assembly
|
||||
format during migration and preserve legacy signal IDs where possible.
|
||||
|
||||
## Scope Boundary
|
||||
|
||||
- Native signal model and overrides are the long-term source of truth.
|
||||
- QGIS GeoJSON/GeoPackage support is transitional compatibility only; do not
|
||||
make native compile depend on QGIS or regenerate native edits from QGIS.
|
||||
- Do not redesign signal geometry, timing logic, or vehicle behavior in this
|
||||
task.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] A native compile/reopen round trip preserves edited signal assemblies,
|
||||
stable IDs, enabled state, and provenance without QGIS running.
|
||||
- [ ] The Road Workbench can generate, inspect, move, rotate, and delete signal
|
||||
assemblies, then save durable edits without breaking QGIS reimport.
|
||||
- [ ] Native Blender/Cesium/preview consume runtime signal data generated from
|
||||
the native model, including disabled signals being omitted from runtime.
|
||||
- [ ] QGIS import/export compatibility and legacy build stages continue to
|
||||
pass while the migration adapter exists.
|
||||
- [ ] Nantaizi has documented native-only and QGIS-imported round trips.
|
||||
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"id": "native-traffic-signal-parity",
|
||||
"name": "native-traffic-signal-parity",
|
||||
"title": "Align native traffic signals with QGIS",
|
||||
"description": "",
|
||||
"status": "completed",
|
||||
"dev_type": null,
|
||||
"scope": null,
|
||||
"package": null,
|
||||
"priority": "P2",
|
||||
"creator": "dingkang",
|
||||
"assignee": "dingkang",
|
||||
"createdAt": "2026-08-18",
|
||||
"completedAt": "2026-08-18",
|
||||
"branch": null,
|
||||
"base_branch": "feature/native-road-compiler",
|
||||
"worktree_path": null,
|
||||
"commit": null,
|
||||
"pr_url": null,
|
||||
"subtasks": [],
|
||||
"children": [],
|
||||
"parent": "08-13-native-road-compiler",
|
||||
"relatedFiles": [],
|
||||
"notes": "",
|
||||
"meta": {}
|
||||
}
|
||||
Reference in New Issue
Block a user