feat: add live V2X Cesium preview overlay

docs/v2x-cesium-preview.md

@@ -0,0 +1,62 @@
+# 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.