Appearance
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(optionalstationId) mit. - Testbetrieb (aktuell): kein Object Storage. Input-Daten liegen nur auf der GPU-Workstation. Bei Ready: Webhook ohne
s3Key; Platform pulltsplat.plyper 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 mits3Key; Platform-Assets optionalASSETS_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 ohnes3Keyist gültig.
Live-Endpoints (aktueller Testbetrieb)
| Seite | Wert |
|---|---|
| Platform | https://app.raumgrid.de |
| Webhook | https://app.raumgrid.de/api/generator/hooks/job-ready |
| Asset-Store | ASSETS_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.
| Prefix | Eigentümer | Inhalt |
|---|---|---|
customers/{slug}/… | Platform (ASSETS_DISK=assets_s3) | Library, Station-Splats — Web-Auslieferung |
generator/jobs/{jobId}/splat.ply | Generator → kurzlebig | Handoff |
- Generator schreibt nicht unter
customers/. - Job-Workdirs bleiben lokal auf dem Generator-Host.
- Setup: ops/hetzner-object-storage.md.
Env Object Storage (nur Phase 2)
| Variable | Bedeutung |
|---|---|
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY | S3 Keys |
AWS_DEFAULT_REGION | z. B. fsn1 |
AWS_BUCKET / AWS_ENDPOINT | Bucket + Endpoint |
AWS_USE_PATH_STYLE_ENDPOINT | true (Hetzner) |
ASSETS_DISK | Platform: assets_s3 wenn Assets im Bucket |
Embed
| Variable (Platform) | Bedeutung |
|---|---|
GENERATOR_PUBLIC_URL | SPA-Origin (iframe; Tunnel-URL oder Tailscale) |
GENERATOR_API_URL | API für Server-Pull (Testbetrieb: Tailscale-URL der WS; Default = Public-URL) |
GENERATOR_TOKEN | Bearer für Platform → Generator-API |
GENERATOR_WEBHOOK_SECRET | HMAC-Secret für eingehende Webhooks |
| Variable (Generator) | Bedeutung |
|---|---|
RAUMGRID_EMBED_ORIGINS | Komma-Liste erlaubter Eltern-Origins → CSP frame-ancestors |
RAUMGRID_PLATFORM_WEBHOOK_URL | z. B. https://app…/api/generator/hooks/job-ready |
RAUMGRID_PLATFORM_WEBHOOK_SECRET | dasselbe 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
}
}sourcePathist ein Pfad auf der Workstation (Upload/Capture dort), nicht auf dem VPS.- Aus dem Platform-Embed:
customerId+userIdpflicht,stationIdoptional. - Generator persistiert
platformam Job und liefert es inGET /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:
- Phase 2: optional
PUTnachgenerator/jobs/{jobId}/splat.ply, dann Webhook mits3Key. - 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:
- Signatur prüfen; Idempotenz über
generator_job_id. - Bei
s3Key: Objekt aus Object Storage lesen. - Sonst (Testbetrieb):
GET {GENERATOR_API_URL}/api/jobs/{id}/splat.plymitAuthorization: Bearer {GENERATOR_TOKEN}. - Dateiname
{slugify(name)}.ply→ Authoring-Asset am Customer; Station falls gesetzt. - Nav-/Collision-Pipeline wie bei normalen Splat-Uploads.
Fallback: Platform-Command generator:reconcile-ready pollt GET /api/jobs und importiert fehlende.
Operator-API (Pull)
| Route | Nutzung |
|---|---|
GET /api/health | Erreichbarkeit |
GET /api/jobs | Liste; Filter status=completed / splatReady |
GET /api/jobs/{id} | DTO inkl. splatReady, platform, optional s3Key |
GET /api/jobs/{id}/splat.ply | Roh-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.