feat: add Gaussian simulation workspace

2026-08-26 02:09:44 +03:00
parent b111406cf8
commit d943ec853c
22 changed files with 3422 additions and 17 deletions
@@ -0,0 +1,99 @@
+# Simulation Worlds — product-surface brief
+
+Status: accepted for the first working vertical slice on 2026-08-26.
+
+## Job story
+
+When an operator has a computed XGRIDS export, they need to create a named simulation project from
+one LCC/LCC2 folder or one ZIP/RAR/7z archive, observe the real Worker 006 build state, and open the
+result as an interactive PlayCanvas scene. The scene is a future simulation runtime, not a terminal
+Gaussian viewer: vehicles, scripts, sensors, physics and debug layers must be able to join the same
+`pc.Application` later without replacing the product surface.
+
+## Placement decision
+
+The explicit product decision is `Тестировочный контур → Симуляции`, as a sibling of
+`Лабораторные контуры`.
+
+Alternatives considered:
+
+1. Extend `Лабораторные контуры`. Rejected because that surface owns reproducible experiment
+   evidence and selectors, while a simulation world has its own project, upload, build and deletion
+   lifecycle.
+2. Add a dedicated workspace under `Тестировочный контур`. Selected because it preserves the Lab
+   root while allowing table-first catalog and scene-first runtime compositions.
+3. Place the feature under `Система`. Rejected because Worker/provider health is a system concern,
+   but creating and operating worlds is an operator task.
+
+The workspace is a real `productModel` entry. It is not an internal route, iframe or generic
+capability placeholder.
+
+## Composition and component ownership
+
+The catalog is table-first: project identity, source kind, byte size, splat count when actually
+available, build status, updated time, edit and delete. A selected ready project switches to a
+scene-first composition with the PlayCanvas canvas and bounded runtime controls.
+
+Canonical Design Guideline entities are reused for buttons, icon buttons, status badges, fields,
+selects, segmented controls, confirmation, window, activity and glass surfaces. The semantic
+project table, upload-source target, progress row and PlayCanvas stage are feature-owned renderers;
+they are not introduced as parallel generic UI primitives.
+
+## State and ownership boundaries
+
+```text
+React workspace
+  ├─ project catalog and modal state
+  ├─ same-origin resumable upload
+  └─ selected immutable WorldManifest
+       └─ PlayCanvasRuntime
+            └─ pc.Application / realtime entity graph
+
+Mission Core backend
+  ├─ durable project metadata and source staging
+  ├─ provider orchestration and artifact import
+  └─ same-origin immutable artifact delivery
+
+DC Gaussian Pipeline
+  ├─ TUS bundle or archive admission
+  ├─ secure ZIP/RAR/7z normalization
+  └─ SplatTransform build on Worker 006
+```
+
+The browser never receives the Worker token. Mission Core does not embed archive-format behavior
+in its product domain. The portable pipeline normalizes archives into the same immutable LCC/LCC2
+bundle contract used by folder uploads.
+
+## Runtime decision
+
+Mission Core pins the direct `playcanvas` package. `PlayCanvasRuntime` owns one `pc.Application`,
+camera controls, GSplat asset lifecycle and later physical/debug entities. React owns no per-frame
+entity state. A new world is data and does not require a new frontend build.
+
+The first Worker 006 provider is CPU-only and therefore does not advertise collision outputs. The
+UI disables collision/combined modes and states this explicitly; it does not synthesize a proxy.
+The manifest already keeps visual and collision URLs and their independent world transforms so the
+GPU collision build can be admitted without changing the project surface.
+
+Primary implementation references:
+
+- [PlayCanvas Engine](https://github.com/playcanvas/engine)
+- [GSplatComponent API](https://api.playcanvas.com/engine/classes/GSplatComponent.html)
+- [Streamed SOG runtime](https://developer.playcanvas.com/user-manual/gaussian-splatting/building/lod-streaming/)
+- [SplatTransform](https://developer.playcanvas.com/user-manual/splat-transform/)
+- [SplatTransform Docker](https://developer.playcanvas.com/user-manual/splat-transform/docker/)
+- [SplatTransform collision](https://developer.playcanvas.com/user-manual/splat-transform/collision/)
+
+## First-slice acceptance
+
+- archive or folder selection does not depend on the parent folder name;
+- folder input contains exactly one `.lcc` or `.lcc2` descriptor;
+- ZIP, RAR and 7z are uploaded resumably and normalized only inside the pipeline container;
+- encrypted, linked, traversing, duplicate and over-limit archive entries fail closed;
+- project status is durable and reflects provider state without fabricated percentages;
+- ready artifacts are imported digest-bound and served from Mission Core same-origin URLs;
+- edit changes project metadata; delete removes both the Mission Core project and terminal provider
+  job;
+- a ready project mounts direct PlayCanvas Engine and loads Streamed SOG with preview fallback;
+- visual, collision and combined remain distinct runtime modes even when collision is not yet
+  available on the CPU provider.