# Live V2X Cesium Preview

The Cesium preview displays live V2X operational data on a compiled native
intersection. The package manifest, native road geometry, and traffic signals
remain independent of the service. Vehicle entities and their trace lines are
created only from authenticated V2X streams; generated routes and traffic
simulation are never rendered as a substitute.

## 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.
`crossCode` is deployment configuration for the selected intersection. It is
never shown or editable in the browser login panel.

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. It also subscribes to
`/network/ws/network/obuPosition` and `/network/ws/network/targetPosition` for
the only vehicle and vehicle-line sources. Failures are shown in the V2X panel;
the static Cesium scene stays available and the vehicle layer stays empty.

## Coordinate Contract

| Data | Coordinate system | Preview handling |
| --- | --- | --- |
| Native package placement and 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.