Zum Hauptinhalt springen

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 TypenEin Boolean signageCompanionOnly pro Entität
News: showOnSignage = Stele-Opt-in (bleibt)Orthogonal: Opt-in Stele ≠ Opt-out Website
News/Events/Offers: toGoExclusive = NOW!-App exklusivEigener Kanal; nicht ersetzen
Jobs: keine Kanal-FlagsGleicher 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:

  • showOnSignage schließt News nicht von der Website aus — es filtert nur Stele-Feeds (forSignage=true).
  • toGoExclusive zielt auf die NOW!-Exklusiv-Schicht, nicht generell auf Signage/Kiosk.
  • Hot-Pick-channels kuratiert 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​

RolleAuswirkung
RedaktionNeuer Toggle im Reiter Veröffentlichung (News, Events, Angebote, Jobs)
Center-BetriebKeine Migration bestehender Inhalte nötig (Default false)
Besucher WebsiteSehen keine signageCompanionOnly-Items mehr in Aktuelles/Listen
Besucher Signage/CompanionSehen diese Items in Kiosk-, Stele- und Companion-Feeds
Entwickler / v0Website filtert Feld client- oder serverseitig; Signage/Companion inkludiert
Agenten (MCP/AgencyOS)Feld in Update-Tools und Public-Read-Beschreibungen

Wo​

BereichPfad (geplant)
Prismapackages/database/schema.prisma — Spalte signageCompanionOnly auf News, Event, Offer, Job
Migrationpackages/database/migrations/YYYYMMDD_add_signage_companion_only_SAFE.sql + *_SAFE.md
Public Readaktuelles-bundle, …/news, …/events, …/offers, …/jobs
Signage/CompanionGleiche Routen mit Kanal-Query; ggf. dedizierte Signage-Content-Aggregation
Dashboard UIedit-news-page.tsx, edit-event-page.tsx, Offer-/Job-Editoren — Reiter Veröffentlichung
AgencyOSapps/dashboard/src/app/api/agencyos/v1/{news,events,offers,jobs}/…
MCPregister-cockpit-tools.ts — cockpit_update_*, cockpit_public_*
MCP-Hintswebsite-config-mcp-schema.ts / Content-Push-Felder in process-center-entity-push.ts
Tool-Exportexports/cockpitos-tools.json
Nutzer-Doku (später)Content-Creator-Handbuch — Abschnitt Kanäle/Veröffentlichung
v0-Leitfadenv0-content-channels-signage-only.md

Empfohlenes Datenmodell​

Entscheidung: signageCompanionOnly (Boolean) — nicht channels-Objekt​

OptionBewertung
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​

FeldEbeneSemantikÄnderung durch diese Spec
showOnSignageNewsOpt-in für Stele (forSignage=true); News bleibt standardmäßig auf WebsiteUnverändert. Bei signageCompanionOnly=true ist News ohnehin auf Signage sichtbar; showOnSignage wird für Stele-Filter redundant, darf aber gesetzt bleiben (kein Fehler).
toGoExclusiveNews, Event, OfferNOW!-Exklusiv — aus Website-Bundle ausgeschlossen; in Companion mit forToGo=trueUnverändert. Orthogonal: NOW-Exklusiv ≠ Signage-only. Kombination möglich (selten); Website filtert beide aus.
HotPick.channelsHotPickJSON-Array z. B. website, digital-signage, app — Kuratierungs-LayerUnverändert. Hot Pick kann auf Content verweisen, der signageCompanionOnly ist; Kanal-Steuerung am Content bleibt maßgeblich für API-Filter.
featured, VeröffentlichungsfensteralleSortierung / ZeitfensterUnverändert — gelten innerhalb des jeweiligen Kanals

Empfohlene UI-Hinweise (Dashboard)​

KombinationVerhalten
signageCompanionOnly + toGoExclusiveWebsite: ausgeblendet; Companion: in NOW-Exklusiv- und Signage-Feeds (Redaktion per Tooltip warnen)
signageCompanionOnly + showOnSignageKein Konflikt; Toggle „Auf Stele anzeigen“ bei signageCompanionOnly=true ausgrauen oder Hinweis „bereits Signage-only“
Hot Pick verweist auf signage-only ContentHot 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;
SchrittAktion
1Migration + db_structure.md ergänzen
2API: Feld lesen/schreiben; Website-Filter ausschließen true
3Dashboard: Toggle im Reiter Veröffentlichung
4MCP/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“).

TypLabel (DE)Hilfetext
News, Event, Offer, JobNur 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-bundle
  • GET /api/centers/{centerId}/news?published=true
  • GET /api/centers/{centerId}/events (Website-Modus)
  • GET /api/centers/{centerId}/offers
  • GET /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)​

KontextVerhalten
Signage-Kiosk / SteleItems mit signageCompanionOnly=true einschließen
Companion-AppItems mit signageCompanionOnly=true einschließen (neben NOW-Exklusiv-Logik)
News Stele-FilterforSignage=true liefert (showOnSignage=true OR signageCompanionOnly=true) — damit Signage-only-News nicht extra showOnSignage brauchen

Neuer optionaler Query-Parameter (P1):

ParameterWerteBedeutung
forSignageCompaniontrueNur Items mit signageCompanionOnly=true (Teaser-Feeds)
includeSignageCompanionOnlytrueSignage/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 / RouteFeld
cockpit_update_newssignageCompanionOnly?: boolean
cockpit_update_eventsignageCompanionOnly?: boolean
cockpit_update_offersignageCompanionOnly?: boolean
cockpit_update_job (neu/ergänzen)signageCompanionOnly?: boolean
cockpit_public_news/events/offers/jobsBeschreibung: Website-Routen schließen true aus; Signage-Query inkludiert
AgencyOS PUT …/news/{id} etc.Boolean im Body
content_push / PreviewFeld in previewPlan.planned

Beschreibungstext (MCP):

„Nur Signage & Companion — nicht auf der öffentlichen Center-Website. Default false. Orthogonal zu toGoExclusive (NOW!) und showOnSignage (Stele-Opt-in).“


Rollout P0 / P1 / P2​

PhaseInhaltAkzeptanz
P0Migration + Prisma; Public Read Filter Website; Feld in JSON-Responses; Dashboard-Toggle; VERSION-BumpWebsite-Bundle ohne signage-only; Toggle speicherbar; bestehende Items unverändert sichtbar
P1MCP/AgencyOS/content_push; forSignage=true-Erweiterung; Companion-Feed-Doku; Nutzer-HandbuchAgenten können Feld setzen; Stele zeigt signage-only-News
P2Optionale Center-Analytics (Kanal-Split); Redaktions-Bulk-Edit; Legacy-Import-Heuristik nur manuellBetrieb metriken; kein Auto-Backfill

So testen (nach Implementierung)​

  1. Regression: News/Event/Offer/Job mit Default — weiterhin in aktuelles-bundle sichtbar.
  2. Signage-only: Item mit Toggle anlegen → nicht in aktuelles-bundle; sichtbar in Signage/Companion-Feed (bzw. includeSignageCompanionOnly=true).
  3. News Stele: signageCompanionOnly=true, showOnSignage=false → erscheint bei Signage-News-Aggregation.
  4. NOW! + Signage-only: Beide Toggles → weder Website noch normales Bundle; Companion-Feeds korrekt.
  5. Jobs: Erstes Kanal-Flag — Stellenanzeige signage-only erscheint nicht unter /jobs auf Website.
  6. MCP: cockpit_update_news setzt Feld; Public Read liefert korrekten Boolean.
  7. Freigabe-Workflow: Entwurf mit Feld → nach Freigabe persistiert.

Betrieb​

ThemaHinweis
EnvKeine neuen Secrets
CronKeine
DeployRender Dashboard (mallos-dashboard) — Migration vor Traffic
RollbackSpalte bleibt (additiv); API kann Filter temporär deaktivieren; Default false = sicher

Kein Datenverlust​

  1. Additiv: Neue Spalte NOT NULL DEFAULT false — bestehende Zeilen unverändert.
  2. Kein automatisches Umsetzen von showOnSignage oder Kategorie-Slugs auf signageCompanionOnly=true.
  3. Kein Entfernen von showOnSignage, toGoExclusive oder Hot-Pick-channels.
  4. Expand-contract: Erst lesen/schreiben + filtern; optional später UI-Vereinfachung — nie Big-Bang-Umschreibung.
  5. 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 in today.* explizit mischen oder eigene Sektion?
  • Einzel-Detail-URLs auf Website: 404 vs. Redirect wenn signageCompanionOnly=true per 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