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

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.
• R7: Vehicle lines and moving vehicles must come only from the authenticated V2X vehicle streams. Do not render or fall back to generated route/simulation data when the service is unavailable.

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.
• Generated vehicle-route or traffic-simulation fallback in the operations preview.

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.