osmWorkflow/.trellis/tasks/archive/2026-08/08-24-v2x-amap-intersection-data/implement.md

Implementation Plan: Live V2X Cesium Intersection View

1. Read preview and pipeline specifications, then add a focused V2X preview configuration. Keep secrets and private origins out of defaults and tracked area configuration.
2. Add browser-safe GCJ-02-to-WGS84 conversion and focused tests for source coordinate labels and prevention of duplicate conversion. Preserve the current compiler reference conversion behavior.
3. Implement the V2X browser client: login, session token lifecycle, REST envelope handling, capability errors, and signal WebSocket lifecycle.
4. Extend the generated Cesium preview with V2X entities and operations controls for links, devices, poles/configuration, metrics, live signal state, and the OBU/target-vehicle streams. Do not load or generate simulated vehicle routes.
5. Add a local development/proxy configuration example and deployment documentation for V2X REST/WS proxying. Do not add an AMap key, SDK, or page.
6. Add focused tests for HTML generation, configuration escaping, login/request construction, coordinate conversion, source-layer diagnostics, and graceful unavailable/auth states. Run existing preview and native-road regressions.
7. Validate in a browser with a real V2X account and configured proxy: sign in, inspect aligned native/V2X features, verify REST panels and signal updates, then verify sign-out/token expiry behavior.

Validation Commands

node --check scripts/lib/area-preview.js
node --check scripts/lib/cesium-preview.js
npm run test:gaode-junction-reference
npm run test:preview-assets
npm run test:native-preview-traffic
npm run test:traffic-signals
npm run road:compile -- --config config/areas/fengshu-er-road.json
npm run build:area -- --config config/areas/fengshu-er-road.json --stages preview

Review Gates

• Confirm no token, account, or private host is committed.
• Verify V2X GCJ-02 coordinates convert once before Cesium use.
• Verify the existing native WGS84/ENU scene contract remains unchanged.
• Verify the current Cesium preview works without V2X configuration or sign-in.