feat: add live V2X Cesium preview overlay

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

@@ -0,0 +1,81 @@
+# Integrate live V2X intersection data into Cesium preview
+
+## Goal
+
+Provide a Cesium-based operational view of the current complex intersection in
+this repository. It must show live data from the existing V2X platform while
+retaining the native road compiler's WGS84/ENU output as the geometry authority.
+
+## Confirmed Facts
+
+- The source dashboard's holographic-intersection view uses V2X REST resources for
+  road/link geometry, device bindings, poles, configuration, traffic metrics, and
+  a token-authenticated signal WebSocket.
+- The dashboard development proxy targets `172.16.1.159:50400` under `/api`,
+  `/websocket`, and `/vectortile`; the application sends the upstream token as the
+  `Authorization` header.
+- The source dashboard uses AMap and therefore its road/link data is GCJ-02. Its
+  road-network exporter converts that data from GCJ-02 to WGS84 before export.
+- This repository's native road, signal, and simulation artifacts are WGS84/ENU.
+- The target is the existing Cesium preview, not AMap. High德 data in this
+  repository is a calibration/reference GeoJSON only, not a target runtime map.
+- The requested page has a simple login gate; V2X data must remain real live
+  interface data, not copied mock data.
+
+## Requirements
+
+- R1: Add a Cesium-based complex-intersection operations view to this repository, protected by
+  a simple application login.
+- R2: Integrate the real V2X REST endpoints used by the source dashboard, including
+  current intersection/link geometry, devices, poles/configuration, traffic metrics,
+  and signal state where upstream authorization permits it.
+- R3: Keep the V2X platform credentials separate from the simple application login;
+  do not put a reusable upstream credential into browser source or committed files.
+- R4: Treat V2X map-facing coordinates as GCJ-02. Treat native compiler artifacts
+  as WGS84/ENU, and convert V2X GCJ-02 coordinates to WGS84 exactly once before
+  adding them to Cesium.
+- R5: Surface a clear unavailable/authentication state when live data cannot be
+  loaded while leaving the native complex-intersection view usable.
+- R6: Make endpoint origin, selected V2X intersection code, and authorization
+  mechanism deployment configuration rather than hard-coded source values.
+
+## Candidate Upstream Resources
+
+- `GET /network/api/link/network/queryCrossLinkInfo/{crossCode}`: intersection
+  link geometry and signal phase association.
+- `GET /network/api/pole/network/queryPoles/{crossCode}`: pole and light placement
+  configuration.
+- `GET /facilities/api/crossDevice/findDeviceByCrossCode/{crossCode}`: bound devices.
+- `GET /facilities/api/crossDeviceConfig/{crossCode}`: target-device configuration.
+- `GET /facilities/api/FlowTravelRatio/queryListWeek?code={crossCode}` and related
+  cross-monitor resources: operational metrics.
+- `WS /network/ws/network/signal?authorization={token}`: live signal lamps.
+
+## Acceptance Criteria
+
+- [ ] A user can pass the local login gate and open the current complex-intersection
+  Cesium view.
+- [ ] The page retrieves and renders live V2X data for a configurable intersection
+  code without source-dashboard runtime dependencies.
+- [ ] The page identifies the coordinate reference of each source and visually
+  aligns native WGS84 geometry with V2X data converted from GCJ-02.
+- [ ] A missing/expired upstream credential or unavailable service is visible and
+  does not make the native intersection view unusable.
+- [ ] Upstream URL, intersection code, and credentials/tokens are excluded from
+  tracked application source and documented for deployment.
+
+## Out Of Scope
+
+- Copying the source dashboard's Vue, AMap/Three, or proprietary UI component stack.
+- Building a full user/role management service.
+- Replacing native road geometry or traffic-signal contracts with V2X data.
+
+## Authentication Decision
+
+- The page signs in to the upstream V2X service with the user-entered account,
+  posting `userName` and MD5-hashed `password` to
+  `/facilities/api/sys/login` through the configured API prefix.
+- The returned token lives only in `sessionStorage`, is sent as the raw
+  `Authorization` header for REST requests, and is supplied as the
+  `authorization` WebSocket query parameter for the signal subscription.
+- No default credentials, reusable token, or API secret may be committed.