osmWorkflow/.trellis/tasks/archive/2026-08/08-19-gaode-junction-reference/design.md

Technical Design

Boundary

The native compiler remains authoritative for OSM road identity, directed lanes, connections, traffic signals, stop lines, and preview routes. A reference layer is an optional geometry-calibration input consumed before junction surface publication.

Proposed Flow

optional reference GeoJSON (GCJ-02)
  -> validate schema and coordinate bounds
  -> GCJ-02 to WGS84 conversion
  -> associate reference footprint with an OSM junction node
  -> classify geometry by observable shape, not opaque vendor type alone
  -> derive bounded junction-shape parameters
  -> native compiler creates surface/connectors as usual
  -> diagnostics compare generated geometry with reference

The first production validation keeps the reference overlay/diagnostic, then enables a bounded cross junction template for explicitly configured references. Connector endpoints and movement enumeration still come from the native model. T and complex junctions remain on the existing algorithm until their templates are separately validated.

Input Contract

Use an optional area-level reference configuration rather than a hard-coded filename. The sample points to inputs/osm/珠山湖大道（枫树二路）口.geojson, declares GCJ-02, and identifies the target through OSM node 8005332807 or a stable spatial/name match. The file is not assumed to contain a CRS member; the configured source CRS is required.

Geometry Safety

• Convert all reference coordinates to WGS84 before distance/overlap tests.
• Reject malformed or non-finite coordinates and references outside the OSM bounds plus a bounded tolerance.
• Never let a reference polygon create a movement, lane, signal, or stop-line record.
• Keep a fallback path to the current compileGeometry() junction algorithm.

Compatibility And Rollback

No-reference configs and existing output schemas remain unchanged. The experiment can be disabled by omitting the reference section or setting it disabled. Generated diagnostics must record source file hash, conversion mode, matched OSM node, and whether fallback was used. No source reference file is rewritten.

Open Technical Work

1. Select the smallest reusable geometry parameter set from the sample (approach cutback, corner radius/rounding, island/marking envelopes, and tolerances).
2. Implement and test GCJ-02 conversion independently from compiler logic.
3. Compare the sample against all native junctions near the converted footprint before any production surface override is enabled.
4. Add topology classification and template dispatch; only cross is enabled in this validation.
5. Preserve native connectors and controls while replacing only the bounded junction surface geometry.