KI-Website-Bau & CockpitOS: Integrationskonzept

Dieses Dokument beschreibt das Zielbild und die Umsetzungsphasen, damit eine KI-Session (z. B. Claude) Websites bauen und Inhalte in CockpitOS anlegen oder aktualisieren kann — ohne dass Nutzer:innen alles manuell im Dashboard nachpflegen müssen. Es gilt für Neuaufbau (Greenfield) und Bestand (Brownfield).

Leitplanken: Kein Datenverlust, keine destruktiven Schema-Schritte; neue Schnittstellen nur additiv und mit klarer Auth. Bestehende APIs bleiben stabil.

1. Problem & Zielbild

Heute	Ziel
KI erzeugt schnell UI (v0, Claude, …), Daten liegen getrennt	Eine Session: Bauen + „für wen" + welcher Content
Daten manuell in Cockpit nachziehen	KI prüft Cockpit (Center vorhanden? Daten da?) und schreibt fehlendes über gesicherte APIs
Website zeigt Demodaten	Öffentliche Site liest dieselben Daten wie Cockpit (Single Source of Truth)
Redaktion braucht IT für jede Änderung	Redaktion erstellt Entwürfe per Sprache — Freigabe im Cockpit-Workflow

Identität: centerId ist durchgängig die UUID ShoppingCenter.id in Cockpit (nicht Google Place ID). Slug → UUID über öffentliche API möglich (siehe Public API — Ablauf centerId).

2. Was im System bereits vorhanden ist

Diese Bausteine nicht neu erfinden — darauf aufsetzen:

Baustein	Zweck	Doku / Artefakt
AgencyOS Magic Link + API-Key	Vertrauensstellung, Org- oder nutzerweiter Scope	AgencyOS-Integration
Center lesen / anlegen / zuweisen	`GET`/`POST`/`PATCH` unter `/api/agencyos/v1/centers/…`	siehe AgencyOS-Doku
Kontext für KI	Bestand: Shops, Services, News, Events, Offers, Kategorien/Ketten (schlank), Push-IDs; optional `include=floors_summary` ohne `mapSvg`-Body	`GET …/centers/{id}/context`
Inhalte schreiben (Upsert)	Shops, Events, News, Offers, Services; Idempotenz über `metadata`	`POST …/content/push`
Vorschau ohne DB-Schreiben	Dry-run vor Live-Push	`POST …/content/push/preview`
Öffentliche Lese-API	Website/SSR: Daten aus Cockpit ohne Session	Public Center-Website API
MCP-Server (Stdio + Remote)	Claude Desktop / Remote: alle öffentlichen Reads + AgencyOS Context/Preview/Push; inkl. Centerplan (`cockpit_public_wayfinding_floors` → `GET /api/wayfinding/floors`, inkl. Hybrid-SVG mit `mapSvg` + optional `mapImage`/`shopViewBoxes`)	`packages/mcp-cockpit-os`, `packages/mcp-cockpit-remote`
Workflow & Freigaben (UI)	Entwürfe prüfen, genehmigen, ablehnen	Workflow & Freigaben
Maschinenlesbar	OpenAPI AgencyOS (inkl. Context mit `floors_summary`) und öffentlicher Wayfinding-Read	`/openapi/agencyos-integration.yaml`, `/openapi/public-wayfinding-read.yaml`

3. Zwei Nutzungspfade

3.1 Greenfield (neues Center / neue Site)

Nutzer:in nennt Organisation, Center-Name, Slug-Wunsch, benötigte Content-Typen.
KI prüft: Center existiert? (GET Centers / ggf. Slug-Auflösung über öffentliche API)
Falls nötig: Center anlegen oder zuordnen (nur mit passenden Rechten — AgencyOS-/Cockpit-Flows).
Content schrittweise per Push-Preview validieren, dann Push — oder direkt Push mit Monitoring.
Website-Template / v0: centerId oder Slug fest verdrahten; Datenbezug nur über öffentliche Endpunkte + getDashboardApiUrl() / Vertrag.

3.2 Brownfield (bestehendes Center)

Nutzer:in nennt Center (Slug oder UUID).
KI lädt Kontext (context?include=…), sieht vorhandene Entitäten und Push-IDs.
Änderungen: wieder Preview → Push; keine Dubletten dank Idempotenz-Regeln in der Push-Doku.
Website bleibt an gleicher centerId gekoppelt — nur Content-Version ändert sich.

4. Architektur-Skizze (Ziel)

Schreiben / sensibler Kontext: über AgencyOS (oder später user-scoped Tokens — Roadmap).
Entwürfe zur Freigabe: über submitToWorkflow-Pfad → landen in Workflow & Freigaben, nicht direkt live.
Auslieferung an Besucher: über Public API (kein Secret im Browser).

5. Konkreter Use Case: „Angebot für alle Deichmann-Center"

Dieser Use Case wurde als End-to-End-Test des gesamten KI-Redaktions-Workflows analysiert. Er ist repräsentativ für alle Multi-Center-Kampagnen.

Gewünschter Ablauf:

Redakteur → Claude: "Erstell ein Angebot für Deichmann in allen Centern wo es Deichmann gibt"
         ↓
Claude findet alle Center mit Deichmann-Filiale
         ↓
Claude generiert Angebotstext
Redakteur gibt Bild-URL mit (oder lädt Bild vorher in Cockpit hoch)
         ↓
Claude legt Entwurf in Cockpit an — für jedes Center separat
         ↓
Entwürfe erscheinen in Workflow & Freigaben (alle auf einmal sichtbar)
         ↓
Freigeber genehmigt (Einzel oder Bulk) → sofort live auf allen Websites

Was davon heute funktioniert — und was nicht

Schritt	Status heute	Bemerkung
Alle Center abrufen	✅	`cockpit_agencyos_list_centers`
Deichmann-Center herausfiltern	⚠️ Möglich, aber N+1 Calls	Pro Center: `cockpit_agencyos_center_context?include=chains` — bei 50 Centern 51 API-Calls
Angebotstext generieren	✅	Claude nativ
Bild mitgeben	❌ Nur als URL	Datei-Upload nicht möglich; Bild muss vorher gehostet sein
Angebot als Entwurf anlegen	⚠️ Direkt in DB	`content/push` schreibt sofort, kein Workflow-Item
Entwurf in Workflow & Freigaben	❌ Nicht verknüpft	AgencyOS-Push erscheint nicht in der Workflow-Queue
Freigabe im Dashboard	⚠️ UI vorhanden, Backend teils Mock	Workflow-System noch nicht vollständig implementiert
Bulk-Freigabe mehrerer Center	❌ Geplant, nicht implementiert	Bulk-Actions in Workflow & Freigaben fehlen noch

Konsequenz: Der Workflow funktioniert heute mit manuellen Workarounds (Bild vorab hochladen, Drafts manuell in Content-Liste suchen), aber nicht als nahtloser, sicherer Redakteurs-Workflow für nicht-technische Nutzer.

6. Fehlende Bausteine (Development-Backlog)

Die folgenden Features blockieren oder beeinträchtigen den idiotensicheren KI-Redaktions-Workflow. Priorisiert nach Auswirkung.

B1 — `submitToWorkflow`-Modus im Content-Push (Priorität: Hoch / Blockierend)

Problem: POST /api/agencyos/v1/content/push schreibt direkt in die Datenbank. Inhalt geht sofort live (oder als Draft ohne Queue-Eintrag). Der Workflow & Freigaben-Bereich sieht diese Items nicht — Redakteure und Freigeber können sie dort nicht finden.

Gewünschtes Verhalten: Ein Flag "submitToWorkflow": true im Push-Body (oder ein eigener Endpunkt POST …/content/push/workflow-draft) soll statt eines DB-Upserts einen WorkflowItem-Datensatz anlegen:

source: "agencyos"
status: "pending"
Alle Content-Felder (title, description, image, dates, …) als JSON im WorkflowItem-Payload
centerId zugeordnet
Optional: campaignId oder campaignLabel (z. B. "Deichmann Mai-Kampagne") für gebündelte Ansicht
Bei Genehmigung: automatische Umwandlung in echten Content-Datensatz

Implementierung (Vorschlag):

Neuer optionaler Body-Parameter submitToWorkflow: boolean in POST …/content/push
Wenn true: keine Upsert-Logik, stattdessen WorkflowItem-Erstellung mit source: "agencyos", status: "pending"
Vorschau (/preview) weiterhin wie bisher (kein DB-Write, kein WorkflowItem)
MCP-Tool cockpit_agencyos_content_push um Flag ergänzen; alternativ neues Tool cockpit_agencyos_submit_for_approval

Abhängigkeit: Erfordert B3 (Workflow-System vollständig implementiert).

Betroffene Dateien (Referenz):

apps/dashboard/src/app/api/agencyos/v1/content/push/route.ts
apps/dashboard/src/lib/integration/process-center-entity-push.ts
packages/mcp-cockpit-os/src/register-cockpit-tools.ts

B2 — Center nach Kette filtern (Priorität: Mittel / Performance)

Problem: Es gibt keinen Endpunkt, um alle Center zu finden, in denen eine bestimmte Marke/Kette vorhanden ist. Claude muss heute:

Alle Center laden (GET /api/agencyos/v1/centers)
Pro Center den Kontext mit include=chains laden
Manuell filtern

Das sind bei N Centern N+1 API-Calls. Bei 50 Centern: 51 Requests, erhöhte Latenz, mehr Token-Verbrauch, höheres Fehlerrisiko.

Gewünschtes Verhalten:

GET /api/agencyos/v1/centers?chainSlug=deichmann
GET /api/agencyos/v1/centers?chainName=Deichmann

Oder als dedizierter Ketten-Endpunkt:

GET /api/agencyos/v1/chains?name=Deichmann
→ { id, name, slug, centers: [{ centerId, centerName, centerSlug }] }

Implementierung (Vorschlag):

Optionaler chainSlug- oder chainName-Filter in GET /api/agencyos/v1/centers
Intern: Join ShoppingCenter ↔ Shop/ShopLocation ↔ ShopChain nach Name/Slug
Gleiche Zugriffsprüfung wie bestehende Center-Liste (Org-Key vs. User-Key)
MCP-Tool cockpit_agencyos_list_centers um optionale chainSlug/chainName-Parameter erweitern

Betroffene Dateien (Referenz):

apps/dashboard/src/app/api/agencyos/v1/centers/route.ts
packages/mcp-cockpit-os/src/register-cockpit-tools.ts

B3 — Workflow & Freigaben: Backend vollständig implementieren (Priorität: Hoch / Blockierend)

Problem: Laut aktuellem Stand der Dokumentation sind mehrere Kernfunktionen des Workflow-Systems noch nicht produktionsbereit:

Funktion	Status
Change Requests & Approval Requests	Mock-Implementierung, keine echte DB-Integration
User-Session (wer hat genehmigt)	Platzhalter
Notifications / Audit-Trail	Nur geloggt, nicht persistent
Foto-Upload im Workflow	In Arbeit
Bulk-Aktionen (mehrere Items genehmigen)	Geplant

Was benötigt wird:

WorkflowItem-Tabelle mit echten Datenbankschreibvorgängen
Felder: id, centerId, source (agencyos/ki-assistent/cms/manager-app), type (offer/news/event/job), status (pending/in_review/approved/rejected), payload (JSON, alle Content-Felder), campaignLabel (optional), submittedBy, approvedBy, approvedAt, rejectedReason, createdAt, updatedAt
Status-Übergänge: pending → in_review → approved / rejected
Bei approved: automatische Erstellung des echten Content-Datensatzes (Offer, News, Event, …) inklusive Bild-URL aus Payload
approvedBy mit echter User-ID aus NextAuth-Session
Bulk-Approve: mehrere Items mit einem Klick genehmigen — zentral für Multi-Center-Kampagnen
Filter nach campaignLabel — damit Freigeber alle Items einer Kampagne auf einmal sehen
E-Mail-Benachrichtigung an Freigeber (oder zumindest Dashboard-Notification bei neuen Items)

Besonders wichtig für Multi-Center-Kampagnen: Wenn Claude 8 Angebote für 8 Deichmann-Center anlegt, müssen diese im Workflow gebündelt sichtbar und gemeinsam genehmigbar sein.

Betroffene Dateien (Referenz):

apps/dashboard/src/app/api/... (Workflow-Route)
apps/dashboard/src/app/dashboard/workflow/... (UI)
Prisma-Schema: neue WorkflowItem-Tabelle (additiv, kein DROP)

B4 — Bild-Upload über API / MCP (Priorität: Mittel)

Problem: Das image-Feld in offers, news, events erwartet eine URL als String. Nicht-technische Redakteure können Claude kein Bild "mitgeben" — sie müssten das Bild manuell irgendwo hochladen und die URL herauskopieren.

Kurzfristiger Workaround (Option A):

Redakteur lädt Bild in die Cockpit-Mediathek oder ein verknüpftes CDN hoch
Kopiert die öffentliche URL
Nennt die URL Claude als Text: „Bild: https://cdn.cockpit-os.de/…"
Claude setzt die URL in den Push-Body

Diese Option sollte bis Option B vollständig als Schritt-0-Prozess dokumentiert und im Redakteurs-Workflow als Pflichtschritt verankert werden.

Langfristige Lösung (Option B):

Neuer Endpunkt:

POST /api/agencyos/v1/media/upload
Content-Type: multipart/form-data
Authorization: Bearer <apiKey>

→ { "success": true, "data": { "url": "https://cdn.cockpit-os.de/media/…" } }

MCP-Tool cockpit_agencyos_upload_media im Package registrieren
Claude kann diesen Endpunkt aufrufen, wenn der Redakteur ein Bild in den Chat lädt (Base64 oder Dateireferenz via Filesystem-MCP)

Betroffene Dateien (Referenz):

Neuer Endpunkt: apps/dashboard/src/app/api/agencyos/v1/media/upload/route.ts
packages/mcp-cockpit-os/src/register-cockpit-tools.ts

B5 — Batch-Kontext über mehrere Center (Priorität: Niedrig / Komfort)

Problem: Für Multi-Center-Kampagnen (z. B. „alle Deichmann-Angebote prüfen") muss Claude heute pro Center einen separaten cockpit_agencyos_center_context-Aufruf machen. Das belastet das Kontext-Fenster und die Latenz.

Gewünschtes Verhalten:

POST /api/agencyos/v1/centers/batch-context
Body: { "centerIds": ["uuid-1", "uuid-2"], "include": "offers,chains" }
→ { "success": true, "data": { "uuid-1": { ... }, "uuid-2": { ... } } }

Oder als MCP-Tool:

cockpit_agencyos_multi_center_context({ centerIds: [...], include: "offers,chains" })

Betroffene Dateien (Referenz):

Neuer Endpunkt: apps/dashboard/src/app/api/agencyos/v1/centers/batch-context/route.ts
packages/mcp-cockpit-os/src/register-cockpit-tools.ts

7. Phasen-Roadmap (aktualisiert)

Phase	Inhalt	Blockiert durch	Risiko
0 — abgeschlossen	Konzept + Capabilities-JSON + MCP Phase 1 (öffentliche Reads + AgencyOS Context/Preview/Push)	—	Nur Doku
1 — nächster Schritt	Workflow-Backend fertigstellen (B3): WorkflowItem-Tabelle, Status-Übergänge, User-Session, Bulk-Approve, campaignLabel-Filter	—	DB-Migration additiv; kein Schema-Drop
2	`submitToWorkflow`-Flag im Content-Push (B1) + MCP-Tool-Erweiterung	B3 (Phase 1)	Keine Breaking Changes; neuer optionaler Parameter
3	Chain-Filter-Endpunkt (B2) + MCP-Update	—	Nur READ; kein Schreib-Risiko
4	Bild-Upload Option A: Cockpit-Mediathek-URL-Workflow dokumentieren (B4)	—	Nur Doku + UI-Check
5	Bild-Upload Option B: `POST …/media/upload` + MCP-Tool (B4)	—	Neuer Endpunkt; additiv
6	Batch-Context-Endpunkt + MCP (B5)	—	Nur READ; Komfort
7	Personal Access Tokens (User-Scope) parallel zu Org-Keys	Design + Migration soft

Verboten in allen Phasen: DROP-Statements, destruktive Migrationen, Änderung bestehender Push-Semantik ohne Versionierung.

8. Ziel-Workflow nach Abschluss der Backlog-Items

Wenn Phase 1–4 abgeschlossen sind, sieht der sichere Redakteurs-Workflow so aus:

1. [Redakteur — optional, Schritt 0]
   Bild in Cockpit-Mediathek hochladen → URL kopieren

2. [Claude Chat]
   "Erstell ein Angebot für Deichmann, 20% auf Schuhe,
    gültig 1.–14. Mai, Bild: https://cdn.cockpit-os.de/…
    Bitte in alle Center, wo es Deichmann gibt."

3. [Claude — automatisch]
   cockpit_agencyos_list_centers → alle Center laden
   Filter: Centers mit chainSlug=deichmann  (Phase 3 / B2)
   Angebotstext generieren
   cockpit_agencyos_content_push mit submitToWorkflow: true
     + campaignLabel: "Deichmann Mai-Kampagne"
     für jedes Center separat — Idempotenz über agencyosPushId

4. [Cockpit Dashboard — Freigeber]
   Workflow & Freigaben → Filter "Deichmann Mai-Kampagne"
   Alle 8 Entwürfe auf einmal sehen, Bilder-Vorschau
   Bulk-Genehmigen mit einem Klick
   → Sofort live auf allen Center-Websites

Sicherheits-Eigenschaften dieses Workflows:

Kein Content geht ohne menschliche Freigabe live
Audit-Trail: wer hat wann was eingereicht, wer hat genehmigt
Idempotenz: doppelter Push überschreibt, erstellt kein Duplikat
Rollback: abgelehnte Items bleiben als rejected erhalten, kein Datenverlust
Kein force-Modus; kein direkter DB-Zugriff für Redakteure
COCKPIT_ALLOW_CONTENT_PUSH bleibt als Sicherheitsschalter für direkten Push (ohne Workflow) erhalten

9. Checkliste für Implementierer:innen

centerId = UUID aus Cockpit; Slug über GET /api/centers/by-slug/{slug} auflösen.
Schreiben: immer Preview (/push/preview) vor direktem Push; bei Redakteurs-Workflow submitToWorkflow: true.
Idempotenz: agencyosPushId / externalId / Cockpit-UUID laut AgencyOS-Doku nutzen.
Website: nur öffentliche URLs aus Public API; keine Dashboard-Session im Client.
WorkflowItem bei Genehmigung: echter Content-Datensatz mit source: "agencyos" anlegen, WorkflowItem auf approved setzen.
Bulk-Approve: alle Items einer Kampagne (gleiches campaignLabel) gemeinsam genehmigbar.
Nach API-Erweiterung: cockpit-api-capabilities.json und ggf. OpenAPI mitziehen.

1. Problem & Zielbild​

2. Was im System bereits vorhanden ist​

3. Zwei Nutzungspfade​

3.1 Greenfield (neues Center / neue Site)​

3.2 Brownfield (bestehendes Center)​

4. Architektur-Skizze (Ziel)​

5. Konkreter Use Case: „Angebot für alle Deichmann-Center"​

Was davon heute funktioniert — und was nicht​

6. Fehlende Bausteine (Development-Backlog)​

B1 — submitToWorkflow-Modus im Content-Push (Priorität: Hoch / Blockierend)​

B2 — Center nach Kette filtern (Priorität: Mittel / Performance)​

B3 — Workflow & Freigaben: Backend vollständig implementieren (Priorität: Hoch / Blockierend)​

B4 — Bild-Upload über API / MCP (Priorität: Mittel)​

B5 — Batch-Kontext über mehrere Center (Priorität: Niedrig / Komfort)​

7. Phasen-Roadmap (aktualisiert)​

8. Ziel-Workflow nach Abschluss der Backlog-Items​

9. Checkliste für Implementierer:innen​

Verwandte Dokumentation​

1. Problem & Zielbild

2. Was im System bereits vorhanden ist

3. Zwei Nutzungspfade

3.1 Greenfield (neues Center / neue Site)

3.2 Brownfield (bestehendes Center)

4. Architektur-Skizze (Ziel)

5. Konkreter Use Case: „Angebot für alle Deichmann-Center"

Was davon heute funktioniert — und was nicht

6. Fehlende Bausteine (Development-Backlog)

B1 — `submitToWorkflow`-Modus im Content-Push (Priorität: Hoch / Blockierend)

B2 — Center nach Kette filtern (Priorität: Mittel / Performance)

B3 — Workflow & Freigaben: Backend vollständig implementieren (Priorität: Hoch / Blockierend)

B4 — Bild-Upload über API / MCP (Priorität: Mittel)

B5 — Batch-Kontext über mehrere Center (Priorität: Niedrig / Komfort)

7. Phasen-Roadmap (aktualisiert)

8. Ziel-Workflow nach Abschluss der Backlog-Items

9. Checkliste für Implementierer:innen

Verwandte Dokumentation