Skip to content

Contract: Spatial Production ↔ Platform ​

Abstimmung zwischen raumgrid (Platform) und raumgrid-generator. Kein gemeinsamer Git-Root. Kopie für das Generator-Repo: docs/PLATFORM.md (Spiegel: PLATFORM.md in diesem Repo). Generator-S3-Notiz: generator-s3-handoff.md. Testbetrieb-Topologie: ../ops/testbetrieb-gpu-workstation.md.

Entscheidungen ​

  • Generator-SPA wird in Filament „Spatial Production“ per iframe eingebettet (Dev: Vite, Prod/Cluster: Cloudflare Tunnel und/oder Tailscale).
  • Beim Job-Anlegen aus dem Embed gehen customerId + userId (optional stationId) mit.
  • Testbetrieb (aktuell): kein Object Storage. Input-Daten liegen nur auf der GPU-Workstation. Bei Ready: Webhook ohne s3Key; Platform pullt splat.ply per HTTP von der Generator-API und legt ein Authoring-Asset auf dem VPS an (ASSETS_DISK=assets_local).
  • Phase 2 (später): Shared Object Storage — Generator lädt PLY nach generator/jobs/…, Webhook mit s3Key; Platform-Assets optional ASSETS_DISK=assets_s3.

Testbetrieb (ohne S3) ​

text
Capture / Upload  →  nur GPU-Workstation (lokale Pfade, analysis/, jobs/)
Browser Embed     →  Tunnel oder Tailscale → Generator-SPA
Platform ↔ API    →  Tailscale (GENERATOR_API_URL = WS MagicDNS)
Ready             →  Webhook → VPS pullt GET …/splat.ply → Asset-Store auf VPS-Volume
  • Rohdaten / TB nicht auf den VPS.
  • Auf den VPS nur fertige Outputs (PLY + Nav-Pipeline), typisch GB, nicht Capture-Sätze.
  • Keine AWS_* nötig. Generator-Webhook ohne s3Key ist gültig.

Live-Endpoints (aktueller Testbetrieb) ​

SeiteWert
Platformhttps://app.raumgrid.de
Webhookhttps://app.raumgrid.de/api/generator/hooks/job-ready
Asset-StoreASSETS_DISK=assets_local (Volume auf dem VPS)

Generator .env (WS):

env
RAUMGRID_PLATFORM_WEBHOOK_URL=https://app.raumgrid.de/api/generator/hooks/job-ready
RAUMGRID_PLATFORM_WEBHOOK_SECRET=<gleich wie Platform GENERATOR_WEBHOOK_SECRET>
RAUMGRID_EMBED_ORIGINS=https://app.raumgrid.de
# keine AWS_*

Platform .env (VPS): GENERATOR_API_URL = Tailscale-URL der WS, GENERATOR_TOKEN, GENERATOR_WEBHOOK_SECRET, optional GENERATOR_PUBLIC_URL fürs iframe.

Object Storage (Phase 2, optional) ​

Ein privater Bucket (z. B. Hetzner). Beide Seiten dieselben Credentials.

PrefixEigentümerInhalt
customers/{slug}/…Platform (ASSETS_DISK=assets_s3)Library, Station-Splats — Web-Auslieferung
generator/jobs/{jobId}/splat.plyGenerator → kurzlebigHandoff

Env Object Storage (nur Phase 2) ​

VariableBedeutung
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEYS3 Keys
AWS_DEFAULT_REGIONz. B. fsn1
AWS_BUCKET / AWS_ENDPOINTBucket + Endpoint
AWS_USE_PATH_STYLE_ENDPOINTtrue (Hetzner)
ASSETS_DISKPlatform: assets_s3 wenn Assets im Bucket

Embed ​

Variable (Platform)Bedeutung
GENERATOR_PUBLIC_URLSPA-Origin (iframe; Tunnel-URL oder Tailscale)
GENERATOR_API_URLAPI für Server-Pull (Testbetrieb: Tailscale-URL der WS; Default = Public-URL)
GENERATOR_TOKENBearer für Platform → Generator-API
GENERATOR_WEBHOOK_SECRETHMAC-Secret für eingehende Webhooks
Variable (Generator)Bedeutung
RAUMGRID_EMBED_ORIGINSKomma-Liste erlaubter Eltern-Origins → CSP frame-ancestors
RAUMGRID_PLATFORM_WEBHOOK_URLz. B. https://app…/api/generator/hooks/job-ready
RAUMGRID_PLATFORM_WEBHOOK_SECRETdasselbe Secret wie Platform

iframe-URL mit Kontext:

text
{GENERATOR_PUBLIC_URL}/?platformCustomer={id}&platformUser={id}&platformStation={id|omit}&platformOrigin={url-encoded Platform-Origin}

SPA speichert den Kontext und sendet ihn bei POST /api/jobs.

Generator: CSP frame-ancestors aus Embed-Origins; kein X-Frame-Options: DENY. Vite Dev: gleiche Header.

Job-Anlage mit Platform-Referenz ​

POST /api/jobs — optionales Objekt:

json
{
  "name": "Halltonne",
  "sourceKind": "stills",
  "sourcePath": "/data/…",
  "profile": "still-aliked",
  "platform": {
    "customerId": 12,
    "userId": 34,
    "stationId": 56
  }
}
  • sourcePath ist ein Pfad auf der Workstation (Upload/Capture dort), nicht auf dem VPS.
  • Aus dem Platform-Embed: customerId + userId pflicht, stationId optional.
  • Generator persistiert platform am Job und liefert es in GET /api/jobs/{id} zurück.
  • Jobs ohne platform = lokale Workstation-Jobs, kein Auto-Ingest.

Ready-Webhook (Generator → Platform) ​

Bei completed + vorhandener output/splat.ply + gesetztem platform:

  1. Phase 2: optional PUT nach generator/jobs/{jobId}/splat.ply, dann Webhook mit s3Key.
  2. Testbetrieb: kein Upload; Webhook ohne s3Key.

POST {RAUMGRID_PLATFORM_WEBHOOK_URL}

json
{
  "event": "job.ready",
  "jobId": "<uuid>",
  "name": "Halltonne",
  "splatReady": true,
  "platform": { "customerId": 12, "userId": 34, "stationId": 56 }
}

Phase 2 zusätzlich: "s3Key": "generator/jobs/<uuid>/splat.ply".

Header: X-Raumgrid-Signature: sha256=<hmac_sha256_hex(raw_body, secret)>.

Platform:

  1. Signatur prüfen; Idempotenz über generator_job_id.
  2. Bei s3Key: Objekt aus Object Storage lesen.
  3. Sonst (Testbetrieb): GET {GENERATOR_API_URL}/api/jobs/{id}/splat.ply mit Authorization: Bearer {GENERATOR_TOKEN}.
  4. Dateiname {slugify(name)}.ply → Authoring-Asset am Customer; Station falls gesetzt.
  5. Nav-/Collision-Pipeline wie bei normalen Splat-Uploads.

Fallback: Platform-Command generator:reconcile-ready pollt GET /api/jobs und importiert fehlende.

Operator-API (Pull) ​

RouteNutzung
GET /api/healthErreichbarkeit
GET /api/jobsListe; Filter status=completed / splatReady
GET /api/jobs/{id}DTO inkl. splatReady, platform, optional s3Key
GET /api/jobs/{id}/splat.plyRoh-PLY-Stream (Testbetrieb-Handoff)

Slug-Regel für Dateinamen (wie Generator slugify_name): Kleinbuchstaben, Umlaute aufgelöst (ä→ae), Nicht-Alphanumerisches → _.

Optional postMessage ​

SPA darf an parent senden (nur an Origins aus RAUMGRID_EMBED_ORIGINS):

json
{ "type": "raumgrid.jobFocus", "jobId": "<uuid>", "splatReady": true }

Netzwerk ​

  • Testbetrieb: Tailscale für Platform↔Generator-API; Cloudflare Tunnel optional nur fürs SPA-Embed.
  • Phase 2: PLY-Handoff zusätzlich über Object Storage.
  • Docker-VPN nicht empfohlen.

Grenzen ​

  • Generator schreibt nicht in den Asset-Store (customers/).
  • Platform mountet keine Job-/Results-Pfade und keine Capture-Bäume.
  • Capture Assets und Generator-sourcePath/analysis/ bleiben getrennt.
  • Kein SSO Filament ↔ Generator-Person; Bindung über platform.* am Job.