2.7 KiB
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_degwith 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.