54 lines
2.6 KiB
Markdown
54 lines
2.6 KiB
Markdown
# Phase 1 Technical Design
|
|
|
|
## Boundary
|
|
|
|
`packages/road-compiler/` becomes the single implementation owner for native
|
|
road compilation. It is a CommonJS workspace package with explicit public
|
|
entrypoints for compiler APIs, traffic-signal schema, turn-lane helpers, OSM
|
|
parsing, reference conversion, and CLIs. It never imports `area-config`, reads
|
|
`config/areas`, or derives host paths.
|
|
|
|
The host owns `scripts/lib/area-config.js` and maps normalized configuration to
|
|
the v1 `RoadCompilerInput` shape using `toRoadCompilerInput(area)`. During P1,
|
|
`build-area.js` calls the package in-process; P2 is the only phase that changes
|
|
that call to a child process.
|
|
|
|
## Source Ownership and Compatibility
|
|
|
|
The following current `scripts/lib` implementations move into package `src`:
|
|
`native-road`, `complex-junction`, `turn-lane-arrows`, `lane-geometry`,
|
|
`gaode-junction-reference`, `native-traffic-signals`, and `osm`.
|
|
|
|
Some moved modules also serve legacy host paths: QGIS uses turn-lane arrows,
|
|
vehicle preview and reimport use OSM parsing, and preview tests use lane
|
|
geometry. Those consumers import the package entrypoints after the move. This
|
|
preserves one implementation while allowing host -> package dependency.
|
|
|
|
Traffic signal ownership follows the matrix in
|
|
`research/traffic-signals-split-matrix.md`: schema, geometry, validation, and
|
|
runtime construction move to the package. The host retains only two file-I/O
|
|
adapters, `readTrafficSignalFeatures()` and `readTrafficSignals()`, both
|
|
delegating to package exports. No duplicated schema code remains.
|
|
|
|
## Input and Path Handling
|
|
|
|
The package compiler API accepts only `RoadCompilerInput` from
|
|
`docs/native-road-package-v1.md`. Package CLI commands accept an explicit JSON
|
|
input file (`--input`) and never load area configuration. The compatibility
|
|
host CLI still accepts `--config`, but immediately maps it through
|
|
`toRoadCompilerInput()` before entering the package.
|
|
|
|
`junctionTemplates.*.referenceFile` changes to a path relative to its area
|
|
configuration. `readAreaConfig()` resolves it while normalizing configuration;
|
|
the package receives an absolute path and does no path resolution.
|
|
|
|
## Tests and Rollout
|
|
|
|
The package receives the required Fengshu OSM fixture plus migrated unit tests.
|
|
Its `npm test` must run from the package directory without reading host inputs
|
|
or outputs. After each source batch, run the two Phase 0 parity baselines. The
|
|
existing host command names remain compatibility wrappers through P1.
|
|
|
|
Rollback is a normal Git revert of the latest batch commit. No module has a
|
|
parallel host copy after its batch lands, preventing divergence.
|