feat: add live V2X Cesium preview overlay

.trellis/tasks/08-24-v2x-amap-intersection-data/design.md

@@ -0,0 +1,80 @@
+# Design: Live V2X Cesium Intersection View
+
+## Architecture
+
+The native pipeline remains the source of static scene geometry and package
+placement. The existing Cesium preview gains an operations overlay and a compact
+V2X sign-in gate. The implementation stays in the current generated static
+preview architecture and does not import the source dashboard's Vue, AMap, or
+Three dependencies.
+
+The generated preview runtime is divided into four browser concerns:
+
+1. `auth`: presents the V2X sign-in form, MD5-hashes the password to match the
+   source contract, stores a successful token in `sessionStorage`, and clears it
+   on sign-out or authorization failure.
+2. `v2x-client`: owns configured REST/WS origins, adds the raw `Authorization`
+   request header, normalizes the source API envelope, and reports a capability
+   status rather than blanking the preview if an optional resource fails.
+3. `coordinates`: labels external values as GCJ-02 and native values as WGS84 or
+   ENU. It converts V2X GCJ-02 positions to WGS84 exactly once before Cesium
+   entity creation; the existing native package placement contract is unchanged.
+4. `cesium-v2x-overlay`: adds V2X links, devices, pole/configuration evidence,
+   metrics, and real signal phase updates to the existing Cesium viewer, with
+   independent visibility controls and diagnostics.
+
+## Data Flow
+
+```text
+V2X sign-in -> session token
+     |                  |
+     |                  +--> Authorization header / WS query parameter
+     v
+configured V2X REST + WS endpoints -> GCJ-02 V2X geometry, devices, metrics, lamps
+                                                   |
+                                                   v
+                                      GCJ-02-to-WGS84 adapter
+                                                   |
+native package + route/signal descriptors -> WGS84/ENU -> existing Cesium viewer
+                                                   ^
+                                                   |
+                                   Cesium V2X operations overlay
+```
+
+## Endpoint Contract
+
+The first delivery consumes `queryCrossLinkInfo`, `queryPoles`, bound-device,
+cross-device-config, and weekly flow-ratio APIs. It subscribes to
+`/network/ws/network/signal` only after link data establishes usable phases.
+Endpoint host/prefixes and selected `crossCode` are deployment configuration. A
+development proxy forwards REST and WebSocket traffic so the browser never needs
+a hard-coded private origin.
+
+## Coordinate Contract
+
+| Producer | Source CRS | Consumer rule |
+| --- | --- | --- |
+| Native compiler package, traffic signals, route descriptor | WGS84 / local ENU | Preserve the existing Cesium package placement and WGS84 entity contracts. |
+| V2X dashboard link, road, device, and pole data | GCJ-02 | Convert to WGS84 once before creating Cesium entities. |
+| High德 reference GeoJSON | GCJ-02 | Calibration-only compiler input; no runtime map or SDK dependency. |
+
+The existing `gaode-junction-reference` inverse conversion is an appropriate
+source for the V2X adapter. It will be factored or safely reused only when doing
+so preserves its compiler behavior and test coverage.
+
+## Compatibility And Failure Handling
+
+- Existing Cesium preview and its static-only workflow remain usable.
+- The V2X overlay is optional and starts only after successful sign-in.
+- An expired token returns the user to sign-in and removes live entities rather
+  than presenting stale data as current.
+- A REST/WS capability failure is shown in diagnostics; native scene, signals,
+  and traffic simulation remain usable.
+- Removing the optional overlay/support files restores current preview behavior
+  without changing static package contracts.
+
+## Security
+
+`sessionStorage` limits the upstream token to the current tab session. Credentials
+are never persisted. Configuration examples use placeholders, and deployment
+documentation requires an HTTPS same-origin reverse proxy for V2X API/WS traffic.