docs(map): define Cesium integration plan
This commit is contained in:
DCCONSTRUCTIONS
@@ -0,0 +1,350 @@
|
|||||||
|
# Mission Core Map Page + Cesium integration plan
|
||||||
|
|
||||||
|
Status: proposed for product-owner acceptance, 2026-07-29
|
||||||
|
|
||||||
|
## Objective
|
||||||
|
|
||||||
|
Replace the schematic `Control → Map` placeholder with one production map-first
|
||||||
|
workspace that reuses the canonical NODE.DC Map Page contract, the shared
|
||||||
|
Platform Map Gateway and its NAS TileCache.
|
||||||
|
|
||||||
|
The first delivery proves an operational base map in online, degraded and
|
||||||
|
cache-only conditions. It does not introduce a new product root, copy Engine
|
||||||
|
workflow UI, ship fake subjects or grant command authority.
|
||||||
|
|
||||||
|
## Sources of truth
|
||||||
|
|
||||||
|
- NODE.DC Design Guideline `Map Page 0.1.0`;
|
||||||
|
- `@nodedc/page-patterns` and canonical UI package exports;
|
||||||
|
- `docs/MAP_TEMPLATE.md`;
|
||||||
|
- `docs/FOUNDRY_MAP_CESIUM_CANON.md`;
|
||||||
|
- the read-only Foundry Page Library and inspected editable Map application
|
||||||
|
manifests;
|
||||||
|
- Mission Core product UI, component architecture and surface-extension
|
||||||
|
canons.
|
||||||
|
|
||||||
|
Foundry application source is not a dependency. A reusable runtime component
|
||||||
|
must be published through a reviewed package boundary before Mission Core
|
||||||
|
consumes it.
|
||||||
|
|
||||||
|
## Product-surface decision
|
||||||
|
|
||||||
|
### Operator and job
|
||||||
|
|
||||||
|
A field operator opens `Control → Map` before or during a mission to understand
|
||||||
|
the scanner, mission geometry and selected operational subjects relative to
|
||||||
|
real geography, terrain and buildings. The same workspace must remain useful
|
||||||
|
when provider egress is unavailable but the shared NAS cache is reachable.
|
||||||
|
|
||||||
|
### Primary entity and lifecycle
|
||||||
|
|
||||||
|
The primary entity is a versioned Map view:
|
||||||
|
|
||||||
|
- provider-neutral camera and visual settings;
|
||||||
|
- base-layer visibility and provider readiness;
|
||||||
|
- cache intent;
|
||||||
|
- real geodetic subjects and selection;
|
||||||
|
- persisted Inspector state.
|
||||||
|
|
||||||
|
Cesium viewer instances, provider URLs, credentials and cache files are
|
||||||
|
runtime implementation details and are not product identities.
|
||||||
|
|
||||||
|
### Selected placement
|
||||||
|
|
||||||
|
Keep the existing `world-map` workspace under the current Control/Observation
|
||||||
|
root. Replace only its fake composition with a full map-first stage.
|
||||||
|
|
||||||
|
Rejected alternatives:
|
||||||
|
|
||||||
|
- a new product root: the operator job already belongs to Control and has one
|
||||||
|
admitted workspace;
|
||||||
|
- a modal or floating map: the map is the primary task, not auxiliary content;
|
||||||
|
- a Foundry iframe: it duplicates shell/navigation, breaks same-origin product
|
||||||
|
ownership and couples Mission Core to Foundry session state;
|
||||||
|
- reuse of the current generic `MapWorkspace` branch for both `world-map` and
|
||||||
|
`Missions → Routes`: the two workspaces have different lifecycle and
|
||||||
|
authority, so the mission-route editor remains separate.
|
||||||
|
|
||||||
|
This is novelty class A for the existing workspace composition, plus a shared
|
||||||
|
runtime-package admission gate for the generic Cesium adapter.
|
||||||
|
|
||||||
|
## Resulting composition
|
||||||
|
|
||||||
|
The default `Control → Map` surface is the map. Remove from this workspace:
|
||||||
|
|
||||||
|
- the schematic SVG route and contour drawing;
|
||||||
|
- the static right-side `Рабочая композиция` card;
|
||||||
|
- the product-facing feature inventory and `Картографический модуль` roadmap
|
||||||
|
copy;
|
||||||
|
- all fake routes, targets, geozones, heights and readiness statuses.
|
||||||
|
|
||||||
|
Retain canonical Map Page interactions:
|
||||||
|
|
||||||
|
- draggable Map Inspector;
|
||||||
|
- compact Layers overlay;
|
||||||
|
- central Map Toolbar;
|
||||||
|
- map expand/restore behavior owned by the existing workspace shell;
|
||||||
|
- provider-neutral selection and elevated target presentation when real data
|
||||||
|
exists.
|
||||||
|
|
||||||
|
The Layers overlay contains only imagery, terrain, 3D buildings, grid and
|
||||||
|
TileCache health in the first slice. Engine/Data Product layer menus are not
|
||||||
|
copied. Future Mission Core layers appear only after a real typed binding
|
||||||
|
exists.
|
||||||
|
|
||||||
|
## Settings retained from Foundry
|
||||||
|
|
||||||
|
The Inspector keeps:
|
||||||
|
|
||||||
|
1. Underlay and terrain.
|
||||||
|
2. Atmosphere and lighting.
|
||||||
|
3. 3D buildings.
|
||||||
|
4. Mission Core target presentation.
|
||||||
|
5. Grid and LOD.
|
||||||
|
6. Camera animation.
|
||||||
|
7. TileCache intent and safe health.
|
||||||
|
8. Selected entity details when a real selection exists.
|
||||||
|
|
||||||
|
Do not copy:
|
||||||
|
|
||||||
|
- `Классы состояния`;
|
||||||
|
- `HGeoZone`;
|
||||||
|
- `Метро`;
|
||||||
|
- `Вокзалы`;
|
||||||
|
- `Станции РЖД`;
|
||||||
|
- Foundry fleet bindings, provider-specific subjects or Engine execution
|
||||||
|
controls.
|
||||||
|
|
||||||
|
Canonical controls are `Inspector`, `ControlRow`, `InspectorSelectField`,
|
||||||
|
`Checker`, `RangeControl`, `ColorField`, `IconButton`, `Icon`,
|
||||||
|
`MapGlassSurface`, `Toolbar` and `WorkspaceWindow`. Mission Core does not
|
||||||
|
reimplement their geometry or interaction states.
|
||||||
|
|
||||||
|
## Runtime and dependency boundaries
|
||||||
|
|
||||||
|
```text
|
||||||
|
Mission Core browser on :8000
|
||||||
|
│ same-origin /api/v1/map/*
|
||||||
|
▼
|
||||||
|
Mission Core Map BFF
|
||||||
|
│ server-configured internal Gateway route
|
||||||
|
│ trusted server-side subject, no provider credential
|
||||||
|
▼
|
||||||
|
Shared Platform Map Gateway
|
||||||
|
├─ warm hit → shared NAS live TileCache
|
||||||
|
└─ cold miss / explicit refresh → approved platform egress → provider
|
||||||
|
```
|
||||||
|
|
||||||
|
The browser never connects directly to Cesium, Map Gateway, AMD Proxy or a NAS
|
||||||
|
address. The Gateway address is server configuration and is never hard-coded in
|
||||||
|
the frontend, map layout or router settings.
|
||||||
|
|
||||||
|
Mission Core reuses the existing shared cache. It must not create a local
|
||||||
|
browser cache, per-application TileCache, Docker volume or a second Gateway.
|
||||||
|
|
||||||
|
### Shared renderer gate
|
||||||
|
|
||||||
|
`@nodedc/page-patterns` already publishes the runtime-neutral Map Page
|
||||||
|
definition, but the Cesium adapter is not a published package. Production reuse
|
||||||
|
requires a shared reviewed package for:
|
||||||
|
|
||||||
|
- provider startup and independent imagery/terrain/buildings readiness;
|
||||||
|
- Gateway-proxied Cesium resource creation;
|
||||||
|
- render-loop recovery;
|
||||||
|
- provider-neutral scene/selection adapters;
|
||||||
|
- elevated target and label presentation;
|
||||||
|
- camera and cache-intent application.
|
||||||
|
|
||||||
|
Foundry and Mission Core must consume the same package revision. Copying the
|
||||||
|
Foundry application renderer into Mission Core is rejected. Cesium remains a
|
||||||
|
lazy chunk loaded only when the map workspace opens.
|
||||||
|
|
||||||
|
## Credential and control-plane decision
|
||||||
|
|
||||||
|
Mission Core does not need to receive a Cesium token to render the map. The
|
||||||
|
existing platform token remains owned by Platform Map Gateway, and Mission Core
|
||||||
|
uses it only after Gateway reports a configured/verified state. The current
|
||||||
|
network check did not independently verify that state.
|
||||||
|
|
||||||
|
The proposed `API и ключи` settings section is a write-only Platform
|
||||||
|
control-plane client:
|
||||||
|
|
||||||
|
1. The input is a password field, exists only in transient form state and is
|
||||||
|
cleared immediately after submit or cancel.
|
||||||
|
2. Browser submits the candidate through a same-origin authenticated request.
|
||||||
|
3. Mission Core revalidates an explicit admin authority.
|
||||||
|
4. The backend forwards the candidate through the canonical signed Gateway
|
||||||
|
admin route.
|
||||||
|
5. Gateway verifies assets `1`, `2` and `96188` before atomic replacement.
|
||||||
|
6. The response contains only `configured`, verification state, update time and
|
||||||
|
actor; the token is never returned.
|
||||||
|
7. A failed candidate preserves the previous working token.
|
||||||
|
|
||||||
|
The token is not stored in Mission Core environment settings, `.env`, browser
|
||||||
|
storage, logs, Git or Ops. The authoritative private file remains owned by
|
||||||
|
Platform Map Gateway.
|
||||||
|
|
||||||
|
Mission Core currently has no Launcher/Authentik role boundary. Therefore the
|
||||||
|
token-entry mutation is blocked until an authenticated admin control plane is
|
||||||
|
present. A hidden local button or loopback-only server is not sufficient
|
||||||
|
production authorization. Data-plane map work can proceed independently once
|
||||||
|
the existing Gateway is reachable and reports a configured state.
|
||||||
|
|
||||||
|
## Map state contract
|
||||||
|
|
||||||
|
Add a versioned Mission Core map document outside operator environment media,
|
||||||
|
for example `missioncore.map-view/v1`, with optimistic revision:
|
||||||
|
|
||||||
|
- camera: longitude, latitude, height, heading, pitch and roll;
|
||||||
|
- provider-neutral visual settings compatible with Map Page;
|
||||||
|
- map height;
|
||||||
|
- `inspectorOpenSections`;
|
||||||
|
- cache intent (`enabled`, `noOverwrite`), never server-level cache mode;
|
||||||
|
- selected stable subject id, or `null`;
|
||||||
|
- layer visibility;
|
||||||
|
- no credentials, upstream URLs, cache objects or transient Cesium ids.
|
||||||
|
|
||||||
|
Resolution order:
|
||||||
|
|
||||||
|
```text
|
||||||
|
canonical Map Page defaults
|
||||||
|
→ Mission Core persisted map view
|
||||||
|
→ transient operator changes
|
||||||
|
→ bounded runtime-only recovery overrides
|
||||||
|
```
|
||||||
|
|
||||||
|
Provider root failures are independent. Imagery failure must not blank terrain;
|
||||||
|
buildings failure must not stop the rest of the scene.
|
||||||
|
|
||||||
|
## Target and selection contract
|
||||||
|
|
||||||
|
The renderer supports canonical `elevated-spike` targets and
|
||||||
|
`map.moving_object` / `map.place_target` semantics from the start, but the
|
||||||
|
product renders no target without real geodetic evidence.
|
||||||
|
|
||||||
|
The current K1 acquisition contract exposes local `map_enu` trajectory and
|
||||||
|
`gnss_mode=none`; it does not expose a proved longitude/latitude/altitude
|
||||||
|
anchor. Local scan coordinates must not be plotted as world coordinates.
|
||||||
|
|
||||||
|
A real Mission Core map subject requires:
|
||||||
|
|
||||||
|
- stable `sourceId`;
|
||||||
|
- semantic type;
|
||||||
|
- longitude and latitude;
|
||||||
|
- optional altitude with an explicit height datum;
|
||||||
|
- observed/received timestamps;
|
||||||
|
- availability and motion states derived from real contracts;
|
||||||
|
- optional heading and trace;
|
||||||
|
- provenance linking the position to a session/device/mission.
|
||||||
|
|
||||||
|
Until that contract exists, the basemap remains valid with an honest empty
|
||||||
|
subject state and the selected-entity section remains absent.
|
||||||
|
|
||||||
|
## State grammar
|
||||||
|
|
||||||
|
The UI must distinguish:
|
||||||
|
|
||||||
|
- `loading`: runtime config and providers are being prepared;
|
||||||
|
- `ready`: selected providers are available;
|
||||||
|
- `degraded`: one or more providers failed while the scene remains useful;
|
||||||
|
- `empty`: basemap works but no real Mission Core subjects are bound;
|
||||||
|
- `offline-cache`: Gateway is reachable and the requested objects are served
|
||||||
|
without egress;
|
||||||
|
- `cache-miss`: requested offline object is absent;
|
||||||
|
- `gateway-unavailable`: Mission Core cannot reach the shared Gateway;
|
||||||
|
- `render-error`: browser/GPU/Cesium failure after one bounded recovery;
|
||||||
|
- `stale-health`: last-known-good cache statistics retained after a failed
|
||||||
|
poll.
|
||||||
|
|
||||||
|
Safe error codes remain visible to diagnostics. The UI must not collapse all
|
||||||
|
layers into a generic `502`, erase last-known-good cache state or perform
|
||||||
|
unbounded reconnect loops.
|
||||||
|
|
||||||
|
## Implementation slices
|
||||||
|
|
||||||
|
### M0 — shared contract and reachability gate
|
||||||
|
|
||||||
|
- approve the shared Cesium adapter package boundary;
|
||||||
|
- pin `Map Page 0.1.0`, Cesium `1.143.0` and Gateway route contracts;
|
||||||
|
- configure the Mission Core backend Gateway endpoint without hard-coded LAN
|
||||||
|
addresses;
|
||||||
|
- define a reviewed server-owned subject policy for the loopback-only
|
||||||
|
single-operator contour; require Launcher/Authentik identity before any
|
||||||
|
non-loopback or multi-user deployment;
|
||||||
|
- prove safe runtime-config and health reads from the intended field LAN;
|
||||||
|
- add credential-leak and route-allowlist tests.
|
||||||
|
|
||||||
|
### M1 — Mission Core Map BFF
|
||||||
|
|
||||||
|
- add bounded streaming GET/HEAD proxy routes for runtime config, asset
|
||||||
|
endpoints, cache resources and safe health;
|
||||||
|
- preserve Range, ETag, conditional headers, content type, abort and body
|
||||||
|
progress semantics;
|
||||||
|
- reject arbitrary target URLs and browser-supplied trusted identity;
|
||||||
|
- implement independent timeouts and safe error mapping;
|
||||||
|
- do not implement token rotation yet.
|
||||||
|
|
||||||
|
### M2 — real map-first workspace
|
||||||
|
|
||||||
|
- add isolated `core/map`, `components/map`, `workspaces/map` and
|
||||||
|
`styles/map.css` modules;
|
||||||
|
- consume `@nodedc/page-patterns`;
|
||||||
|
- lazy-load the shared Cesium adapter;
|
||||||
|
- replace the fake `world-map` branch only;
|
||||||
|
- remove the old map placeholder CSS from generic `workspaces.css`;
|
||||||
|
- keep `Missions → Routes` outside this change.
|
||||||
|
|
||||||
|
### M3 — Inspector, Layers and persisted view
|
||||||
|
|
||||||
|
- connect canonical Inspector controls to the versioned map view;
|
||||||
|
- add base provider visibility/readiness and cache health to Layers;
|
||||||
|
- persist camera, settings, cache intent and Inspector sections;
|
||||||
|
- implement bounded renderer recreation for explicit viewport refresh;
|
||||||
|
- keep provider credits available for any non-sandbox release.
|
||||||
|
|
||||||
|
### M4 — secure API/key control plane
|
||||||
|
|
||||||
|
- add authenticated Mission Core admin authority;
|
||||||
|
- add `API и ключи` to the existing `FeatureSettingsWindow`;
|
||||||
|
- implement write-only candidate rotation through the canonical Gateway admin
|
||||||
|
route;
|
||||||
|
- prove no secret appears in API responses, bundle, storage, logs or tests.
|
||||||
|
|
||||||
|
### M5 — real Mission Core targets
|
||||||
|
|
||||||
|
- admit a geodetic position/mission-target contract;
|
||||||
|
- adapt real subjects to the shared target presentation;
|
||||||
|
- implement selection and selected-entity details;
|
||||||
|
- add traces/routes only when their coordinate frame and authority are proved.
|
||||||
|
|
||||||
|
### M6 — operational acceptance
|
||||||
|
|
||||||
|
- cold online viewport streams while the Gateway commits objects;
|
||||||
|
- repeated viewport increases cache hits without repeating egress for the same
|
||||||
|
keys;
|
||||||
|
- provider egress/VPN loss does not break a warm viewport;
|
||||||
|
- uncached offline area produces a precise cache-miss state;
|
||||||
|
- explicit refresh failure preserves the previous cached object;
|
||||||
|
- reload restores camera, layers and Inspector state;
|
||||||
|
- each provider can fail independently;
|
||||||
|
- no fake entities survive scene changes;
|
||||||
|
- keyboard, Escape, normal/expanded map and responsive behavior pass browser
|
||||||
|
QA;
|
||||||
|
- all heavy validation remains sequential on the 18 GB Mac and the canonical
|
||||||
|
service stays on port `8000`.
|
||||||
|
|
||||||
|
## Current blockers and evidence
|
||||||
|
|
||||||
|
1. The Cesium adapter is not currently available through a published shared
|
||||||
|
package; exact code reuse is blocked until that boundary exists.
|
||||||
|
2. Mission Core lacks authenticated admin authority, so platform token rotation
|
||||||
|
cannot be exposed safely yet.
|
||||||
|
3. K1 currently has no admitted geodetic anchor, so live scanner targets are a
|
||||||
|
later data-contract slice.
|
||||||
|
4. From the current Mac network, direct safe probes to the expected private
|
||||||
|
Synology Map Gateway/Platform/AMD health endpoints timed out. End-to-end
|
||||||
|
acceptance requires the intended LAN route; no address will be hard-coded to
|
||||||
|
hide this condition.
|
||||||
|
|
||||||
|
None of these blockers requires a new product window, Engine embedding,
|
||||||
|
Ontology mutation, fake target or duplicate TileCache.
|
||||||
Reference in New Issue
Block a user