56 lines
2.7 KiB
Markdown
56 lines
2.7 KiB
Markdown
# 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.
|