# 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.