Signage/Companion-only — Technische Spezifikation
Status: P0 geliefert (0.1.634) — Migration, Public-Read-Filter, Dashboard-Toggle, MCP-Update-Tools. P1/P2 (Companion-Home, Bulk-Edit) folgen.
Verwandt: Public Center-Website API — Vertrag · v0: Content-Kanäle Signage-only · Cockpit steuert Frontends
Was
Ein einheitlicher Redaktions-Schalter auf News, Events, Angebote und Jobs:
Nur Signage & Companion — Inhalt erscheint auf Digital Signage (Kiosk/Stele), in der Companion-/NOW-App und in zugehörigen v0-Feeds, nicht auf der öffentlichen Center-Website (
aktuelles-bundle, Einzelrouten mit Website-Filter).
| Heute (Ist) | Ziel |
|---|---|
| Kein gemeinsames „Website opt-out“ für alle vier Typen | Ein Boolean signageCompanionOnly pro Entität |
News: showOnSignage = Stele-Opt-in (bleibt) | Orthogonal: Opt-in Stele ≠ Opt-out Website |
News/Events/Offers: toGoExclusive = NOW!-App exklusiv | Eigener Kanal; nicht ersetzen |
| Jobs: keine Kanal-Flags | Gleicher Schalter wie bei Aktuelles |
Hot Picks: channels JSON (Kuratierung) | Unverändert; separate Schicht |
Warum
Redaktion will Stelen- und Companion-Inhalte (z. B. Kinowerbung, Kiosk-Teaser, App-only-Jobs) ohne Website-Doppelung pflegen. Heute fehlt dafür ein klares, typübergreifendes Feld:
showOnSignageschließt News nicht von der Website aus — es filtert nur Stele-Feeds (forSignage=true).toGoExclusivezielt auf die NOW!-Exklusiv-Schicht, nicht generell auf Signage/Kiosk.- Hot-Pick-
channelskuratiert Referenzen, steuert aber nicht die Sichtbarkeit des zugrunde liegenden Contents auf Website vs. Signage.
Ein explizites signageCompanionOnly macht Kanal-Intent für Redaktion, API und v0 eindeutig und konsistent.
Wer ist betroffen
| Rolle | Auswirkung |
|---|---|
| Redaktion | Neuer Toggle im Reiter Veröffentlichung (News, Events, Angebote, Jobs) |
| Center-Betrieb | Keine Migration bestehender Inhalte nötig (Default false) |
| Besucher Website | Sehen keine signageCompanionOnly-Items mehr in Aktuelles/Listen |
| Besucher Signage/Companion | Sehen diese Items in Kiosk-, Stele- und Companion-Feeds |
| Entwickler / v0 | Website filtert Feld client- oder serverseitig; Signage/Companion inkludiert |
| Agenten (MCP/AgencyOS) | Feld in Update-Tools und Public-Read-Beschreibungen |
Wo
| Bereich | Pfad (geplant) |
|---|---|
| Prisma | packages/database/schema.prisma — Spalte signageCompanionOnly auf News, Event, Offer, Job |
| Migration | packages/database/migrations/YYYYMMDD_add_signage_companion_only_SAFE.sql + *_SAFE.md |
| Public Read | aktuelles-bundle, …/news, …/events, …/offers, …/jobs |
| Signage/Companion | Gleiche Routen mit Kanal-Query; ggf. dedizierte Signage-Content-Aggregation |
| Dashboard UI | edit-news-page.tsx, edit-event-page.tsx, Offer-/Job-Editoren — Reiter Veröffentlichung |
| AgencyOS | apps/dashboard/src/app/api/agencyos/v1/{news,events,offers,jobs}/… |
| MCP | register-cockpit-tools.ts — cockpit_update_*, cockpit_public_* |
| MCP-Hints | website-config-mcp-schema.ts / Content-Push-Felder in process-center-entity-push.ts |
| Tool-Export | exports/cockpitos-tools.json |
| Nutzer-Doku (später) | Content-Creator-Handbuch — Abschnitt Kanäle/Veröffentlichung |
| v0-Leitfaden | v0-content-channels-signage-only.md |
Empfohlenes Datenmodell
Entscheidung: signageCompanionOnly (Boolean) — nicht channels-Objekt
| Option | Bewertung |
|---|---|
signageCompanionOnly: boolean (Default false) | Empfohlen — passt zu toGoExclusive, showOnSignage; einfache SQL-Filter; klare Redaktions-UI |
channels: { website, signage, companion, … } | Flexibler, aber Overhead für vier Tabellen, Migration, UI-Matrix und MCP; Hot Picks haben bereits channels JSON für Kuratierung |
Semantik:
signageCompanionOnly = false → wie heute: Website-Sichtbarkeit nach bestehenden Regeln
signageCompanionOnly = true → NICHT auf Website; SICHTBAR auf Signage/Kiosk/Stele + Companion
Default false: Alle bestehenden veröffentlichten Inhalte bleiben auf der Website sichtbar — kein Datenverlust, kein Backfill-Zwang.
Verhältnis zu bestehenden Feldern
| Feld | Ebene | Semantik | Änderung durch diese Spec |
|---|---|---|---|
showOnSignage | News | Opt-in für Stele (forSignage=true); News bleibt standardmäßig auf Website | Unverändert. Bei signageCompanionOnly=true ist News ohnehin auf Signage sichtbar; showOnSignage wird für Stele-Filter redundant, darf aber gesetzt bleiben (kein Fehler). |
toGoExclusive | News, Event, Offer | NOW!-Exklusiv — aus Website-Bundle ausgeschlossen; in Companion mit forToGo=true | Unverändert. Orthogonal: NOW-Exklusiv ≠ Signage-only. Kombination möglich (selten); Website filtert beide aus. |
HotPick.channels | HotPick | JSON-Array z. B. website, digital-signage, app — Kuratierungs-Layer | Unverändert. Hot Pick kann auf Content verweisen, der signageCompanionOnly ist; Kanal-Steuerung am Content bleibt maßgeblich für API-Filter. |
featured, Veröffentlichungsfenster | alle | Sortierung / Zeitfenster | Unverändert — gelten innerhalb des jeweiligen Kanals |
Empfohlene UI-Hinweise (Dashboard)
| Kombination | Verhalten |
|---|---|
signageCompanionOnly + toGoExclusive | Website: ausgeblendet; Companion: in NOW-Exklusiv- und Signage-Feeds (Redaktion per Tooltip warnen) |
signageCompanionOnly + showOnSignage | Kein Konflikt; Toggle „Auf Stele anzeigen“ bei signageCompanionOnly=true ausgrauen oder Hinweis „bereits Signage-only“ |
| Hot Pick verweist auf signage-only Content | Hot Pick erscheint nur in passenden Kanälen laut HotPick.channels; Website-Frontend sollte referenzierten Content ohnehin nicht listen, wenn signageCompanionOnly=true |
DB-Migration (Outline, expand-contract)
Prinzip: Additiv, nullable mit Default — siehe database-safety.mdc.
-- Pro Tabelle (News, Event, Offer, Job):
ALTER TABLE "News"
ADD COLUMN IF NOT EXISTS "signageCompanionOnly" BOOLEAN NOT NULL DEFAULT false;
ALTER TABLE "Event"
ADD COLUMN IF NOT EXISTS "signageCompanionOnly" BOOLEAN NOT NULL DEFAULT false;
ALTER TABLE "Offer"
ADD COLUMN IF NOT EXISTS "signageCompanionOnly" BOOLEAN NOT NULL DEFAULT false;
ALTER TABLE "Job"
ADD COLUMN IF NOT EXISTS "signageCompanionOnly" BOOLEAN NOT NULL DEFAULT false;
| Schritt | Aktion |
|---|---|
| 1 | Migration + db_structure.md ergänzen |
| 2 | API: Feld lesen/schreiben; Website-Filter ausschließen true |
| 3 | Dashboard: Toggle im Reiter Veröffentlichung |
| 4 | MCP/AgencyOS-Parität |
| 5 | (Optional P2) Backfill aus Legacy-Heuristik nur auf expliziten Center-Wunsch — nicht automatisch |
Kein DROP, kein UPDATE bestehender Zeilen auf true ohne Redaktionsentscheid.
Dashboard UI
Ort: Reiter Veröffentlichung je Content-Typ (analog „NOW! exklusiv“ / „Auf Stele anzeigen“).
| Typ | Label (DE) | Hilfetext |
|---|---|---|
| News, Event, Offer, Job | Nur Signage & Companion | „Erscheint auf Kiosk, Stele und in der Companion-App — nicht auf der Center-Website.“ |
Komponenten: Switch + Label aus @mall-os/ui; Alert variant="warning" bei gleichzeitig toGoExclusive (Hinweis, kein Blocker).
Speicherung: Direkt auf Entität (signageCompanionOnly); Workflow-Freigabe und content_push übernehmen Feld wie bei toGoExclusive.
Public API — Filterlogik (Zielbild)
Website / Aktuelles (EXCLUDE)
Betroffene Routen (alle mit bestehendem Website-/Publish-Filter):
GET /api/centers/{centerId}/aktuelles-bundleGET /api/centers/{centerId}/news?published=trueGET /api/centers/{centerId}/events(Website-Modus)GET /api/centers/{centerId}/offersGET /api/centers/{centerId}/jobs
Zusätzliche WHERE-Klausel (Pseudocode):
AND signageCompanionOnly = false
Gilt zusätzlich zu bestehendem toGoExclusive: false (außer forToGo=true).
Signage / Companion (INCLUDE)
| Kontext | Verhalten |
|---|---|
| Signage-Kiosk / Stele | Items mit signageCompanionOnly=true einschließen |
| Companion-App | Items mit signageCompanionOnly=true einschließen (neben NOW-Exklusiv-Logik) |
| News Stele-Filter | forSignage=true liefert (showOnSignage=true OR signageCompanionOnly=true) — damit Signage-only-News nicht extra showOnSignage brauchen |
Neuer optionaler Query-Parameter (P1):
| Parameter | Werte | Bedeutung |
|---|---|---|
forSignageCompanion | true | Nur Items mit signageCompanionOnly=true (Teaser-Feeds) |
includeSignageCompanionOnly | true | Signage/Companion-Aggregation: normale plus signage-only Items (Default für Signage-Consumer) |
Website-Routen ignorieren diese Parameter oder liefern 400 — nur Signage/Companion-Clients.
Response-Feld
Jeder betroffene Listeneintrag enthält:
{
"signageCompanionOnly": false
}
Ab P0 in Write- und Read-APIs; v0 kann clientseitig nachrollen (siehe v0-Doku).
MCP- & AgencyOS-Parität
| Tool / Route | Feld |
|---|---|
cockpit_update_news | signageCompanionOnly?: boolean |
cockpit_update_event | signageCompanionOnly?: boolean |
cockpit_update_offer | signageCompanionOnly?: boolean |
cockpit_update_job (neu/ergänzen) | signageCompanionOnly?: boolean |
cockpit_public_news/events/offers/jobs | Beschreibung: Website-Routen schließen true aus; Signage-Query inkludiert |
AgencyOS PUT …/news/{id} etc. | Boolean im Body |
content_push / Preview | Feld in previewPlan.planned |
Beschreibungstext (MCP):
„Nur Signage & Companion — nicht auf der öffentlichen Center-Website. Default false. Orthogonal zu
toGoExclusive(NOW!) undshowOnSignage(Stele-Opt-in).“
Rollout P0 / P1 / P2
| Phase | Inhalt | Akzeptanz |
|---|---|---|
| P0 | Migration + Prisma; Public Read Filter Website; Feld in JSON-Responses; Dashboard-Toggle; VERSION-Bump | Website-Bundle ohne signage-only; Toggle speicherbar; bestehende Items unverändert sichtbar |
| P1 | MCP/AgencyOS/content_push; forSignage=true-Erweiterung; Companion-Feed-Doku; Nutzer-Handbuch | Agenten können Feld setzen; Stele zeigt signage-only-News |
| P2 | Optionale Center-Analytics (Kanal-Split); Redaktions-Bulk-Edit; Legacy-Import-Heuristik nur manuell | Betrieb metriken; kein Auto-Backfill |
So testen (nach Implementierung)
- Regression: News/Event/Offer/Job mit Default — weiterhin in
aktuelles-bundlesichtbar. - Signage-only: Item mit Toggle anlegen → nicht in
aktuelles-bundle; sichtbar in Signage/Companion-Feed (bzw.includeSignageCompanionOnly=true). - News Stele:
signageCompanionOnly=true,showOnSignage=false→ erscheint bei Signage-News-Aggregation. - NOW! + Signage-only: Beide Toggles → weder Website noch normales Bundle; Companion-Feeds korrekt.
- Jobs: Erstes Kanal-Flag — Stellenanzeige signage-only erscheint nicht unter
/jobsauf Website. - MCP:
cockpit_update_newssetzt Feld; Public Read liefert korrekten Boolean. - Freigabe-Workflow: Entwurf mit Feld → nach Freigabe persistiert.
Betrieb
| Thema | Hinweis |
|---|---|
| Env | Keine neuen Secrets |
| Cron | Keine |
| Deploy | Render Dashboard (mallos-dashboard) — Migration vor Traffic |
| Rollback | Spalte bleibt (additiv); API kann Filter temporär deaktivieren; Default false = sicher |
Kein Datenverlust
- Additiv: Neue Spalte
NOT NULL DEFAULT false— bestehende Zeilen unverändert. - Kein automatisches Umsetzen von
showOnSignageoder Kategorie-Slugs aufsignageCompanionOnly=true. - Kein Entfernen von
showOnSignage,toGoExclusiveoder Hot-Pick-channels. - Expand-contract: Erst lesen/schreiben + filtern; optional später UI-Vereinfachung — nie Big-Bang-Umschreibung.
- Multi-Center-Veröffentlichung: Feld liegt auf der Entität (wie
toGoExclusive); Center-Sichtbarkeit weiter über*Center-Joins.
Offene Punkte (vor P0-Implementierung klären)
- Soll
GET /api/center-overview(Companion-Home) signage-only-Items intoday.*explizit mischen oder eigene Sektion? - Einzel-Detail-URLs auf Website: 404 vs. Redirect wenn
signageCompanionOnly=trueper Deep-Link — Empfehlung: 404 oder leere Antwort (kein Leak). - Jobs in
aktuelles-bundle: Template-abhängig; Filter gilt unabhängig vom Template.
Nutzungsstatistik: Seitenaufrufe werden anonymisiert erfasst. Im Umami-Dashboard nach diesem Pfad filtern: /developer-guide/content-channel-signage-only-spec