# Live V2X Cesium Preview

The Cesium preview can overlay live V2X operational data on a compiled native
intersection. This is an optional verification feature; the package manifest,
native road geometry, traffic signals, and deterministic traffic simulation do
not depend on a V2X service being available.

## Configuration

Add a non-sensitive `v2xPreview` object to the area configuration:

```json
{
  "v2xPreview": {
    "enabled": true,
    "apiBaseUrl": "/api",
    "wsBaseUrl": "/websocket",
    "crossCode": "420100023333"
  }
}
```

`apiBaseUrl` and `wsBaseUrl` should normally be relative, same-origin paths.
The deployment server proxies them to the V2X REST and WebSocket services. Do
not commit a private upstream address, an account, a token, or an AMap key.

The browser sends `POST {apiBaseUrl}/facilities/api/sys/login` with `userName`
and an MD5-hashed password, matching the source V2X dashboard. It holds the
returned token in `sessionStorage` only, sends it as the raw `Authorization`
header for REST calls, and uses it as the `authorization` parameter for the
signal WebSocket. Closing the tab clears the session token.

## Data Sources

After sign-in the preview reads the selected intersection's links, pole
configuration, bound devices, device configuration, weekly traffic flow ratio,
and `/network/ws/network/signal` phase updates. Failures are shown in the V2X
panel and do not block the static Cesium scene.

## Coordinate Contract

| Data | Coordinate system | Preview handling |
| --- | --- | --- |
| Native package placement, routes, traffic signals | WGS84 and local ENU | Existing Cesium contract; unchanged. |
| V2X dashboard road/link/device data | GCJ-02 | Converted once to WGS84 immediately before Cesium entity creation. |
| High德 reference GeoJSON | GCJ-02 | Compiler calibration input only; never loaded by this preview. |

Do not convert native WGS84 data again, and do not pass V2X GCJ-02 coordinates
directly to Cesium. Either error produces a visible intersection offset.

## Proxy Requirements

Use an HTTPS reverse proxy which forwards the configured REST prefix and supports
WebSocket upgrade for the configured WS prefix. The generated preview is static,
so direct cross-origin calls are likely to fail CORS or expose an internal origin.
The V2X panel reports that condition while leaving native preview controls usable.

## Rollback

`v2xPreview.enabled` defaults to `false`; set it to `true` for a selected area.
Set it back to `false` and regenerate the preview. The generated
page omits the V2X panel; published package contents remain unchanged.