Files
laraundfelix/docs/architektur/medienzugriff-fuer-komponenten.md
T
LarsandCursor 7b325f0d66
CI Feature / test (push) Successful in 53s
Deploy Test / test (push) Successful in 48s
Deploy Test / deploy (push) Successful in 22s
Lasse Präsentationsmedien ohne Inhaltsfassung zu.
Bilder, Filme und Hörstücke lassen sich zuordnen und für die Website freigeben, ohne eine fachliche Fassung anzulegen. Unterrichtsfilme behalten die Teaserfassung an ihrer bereitgestellten Fassung.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-19 08:20:35 +01:00

141 lines
12 KiB
Markdown

# Medienzugriff für CMS-Komponenten
**Stand:** 18.11.2026. Beschreibt den vorhandenen Weg. Keine neue Freigabe, kein zweites Rechtesystem.
Eine CMS-Komponente, die im Medienmanager liegt, ist ein Inhaltselement (`ContentElement`). Sie entscheidet den Zugriff nicht selbst. Sie ruft eine der drei vorhandenen Stellen auf, je nachdem, was sie tut.
## Drei getrennte Stellen
| Was die Komponente tut | Stelle | Was sie nicht tut |
|---|---|---|
| Anzeigedaten auf der Website lesen | `PublicMaterialReader` | keine Datei, keine Ausgabeadresse |
| Datei an ein Mitglied ausliefern | `DecideAccess`, erneut bei jedem Abruf | keine eigene Erlaubnis, keine Vereinigung von Berechtigungen |
| Ein öffentliches Bild zeigen, das kein Bestandsmedium ist | `PublicMedia` | keinen Pfad aus `originals/` oder `derived/` |
Die Pflege im Medienmanager ist eine vierte, nur redaktionelle Tür: Ansehen dürfen Redaktion und Katalogverwaltung, Ändern nur die Redaktion (`ContentElementResource`). Diese Tür gibt nichts auf der Website und nichts im Mitgliederbereich frei.
## Anzeige auf der Website
`PublicMaterialReader` ist die einzige Lesesicht für ein Medium auf einer öffentlichen Seite. Die Medienkarte nutzt sie bereits.
Öffentlich genannt wird ein Medium nur, wenn alle Punkte zutreffen:
- es ist nicht archiviert und hat mindestens eine nicht gesperrte Fassung,
- es hat eine bereitgestellte Fassung,
- die Inhaltsart ist nicht `traineranleitung`,
- es gehört zur gezeigten Fassung eines öffentlich gezeigten Programms.
Solange öffentliche Profile (ADR-29) fehlen, ist das die Übergangsregel. Ein Medium hat keine eigene öffentliche Seite. Die Karte verweist dann auf die Programmseite.
Gelesen werden Anzeigename (sonst Arbeitstitel), Kurzbeschreibung, Inhaltsart und Ausgabeart. Nicht gelesen und nicht ausgegeben werden Beschreibung, Einsatzhinweis, Lizenzvermerk, Lehrtext und jede Datei.
Das Vorschaubild der Bibliothek erscheint nur in der Redaktionsvorschau, über die Route `editorial.card`, und nur für angemeldete Redaktion. Auf einer öffentlichen Seite hat dieses Bild keine Adresse.
## Auslieferung an Mitglieder
`DecideAccess` ist die einzige Entscheidung über eine Datei. Sie prüft an genau einer Berechtigung: aktives Konto, passender Artikel-Stand, Fassung im fixierten Inhalt dieses Stands, Fassung nicht gesperrt, Aktion im Rechte-Schnappschuss für die Ausgabeart. Zwei Berechtigungen werden nicht zu einer zusammengefügt.
Die Bibliothek ruft dieselbe Prüfung beim Aufbau der Seite und erneut beim Abruf auf (`LibraryController::media`, signierte Adresse, Leser gebunden). Eine Signatur, eine Karte oder eine gespeicherte Komponente ersetzen diesen zweiten Aufruf nicht.
Komponenten liefern Dateien nicht selbst aus. Sie bauen keine Adresse auf `content.file`, `content.preview`, `content.rendition` oder `/bereich/`.
## Öffentliche Bilder außerhalb des Bestands
Heute liegen Bilder, die nur zur Website gehören, unter dem Präfix `cms/` und laufen über `PublicMedia` und die Route `media.public`. Der Controller liefert nur Pfade, die mit `cms/` beginnen, von den Platten `media_public` und `cms_incoming`.
Dieser Pfad ist kein Zugang zum Medienmanager. Ein Inhaltselement wird darüber nicht ausgeliefert. Umgekehrt wird eine geschützte Bestandsdatei nicht in `cms/` gelegt, um sie öffentlich zu machen.
## Website-Medien für Hero, Teaser und Slideshow
Hero-Grafiken, Teaserfilme und Slideshows liegen im Medienmanager. Sie werden nicht verkauft. Lizenzartikel, Angebot, Grant und `DecideAccess` bleiben dafür unbenutzt.
Die Website-Freigabe ist eine eigene Entscheidung am Inhaltselement. Sie hängt nicht daran, dass eine Fassung bereit ist, und nicht daran, dass das Medium in einem öffentlichen Programm liegt. `PublicMaterialReader` bleibt die Lesesicht der Programmkarte. Widgets für Hero, Bild und Slideshow lesen `WebsiteMedia`.
| Aufruf | Klasse | Ergebnis |
|---|---|---|
| Ein Medium | `WebsiteMedia::present($elementOderId)` | `WebsitePresentation` oder `null` |
| Slideshow, Reihenfolge bleibt | `WebsiteMedia::presentMany([$id, ...])` | nur freigegebene Einträge |
`WebsitePresentation` enthält `elementId`, `title`, `alt`, `credit`, `kind` (`bild` oder `film`) und `url`. `url` ist die einzige Dateiadresse, Route `website.media`. `credit` ist die öffentliche Quellenzeile. `license_note` steht dort nicht.
Ein Widget speichert die Kennung des Inhaltselements (`refs.element` oder bei einer Slideshow `refs.elements`), nicht einen kopierten Dateipfad. Ist `present` leer, gibt das Widget nichts aus. Vorhandene Bilder unter `cms/` bleiben gültig, bis das jeweilige Widget umgestellt ist.
### Neues Bild aus dem CMS
`WebsiteIntake::acceptImage($pfad, $titel, $quellenzeile, $alternativtext, $redakteur)` legt das Medium an und gibt seine Kennung sofort zurück. `$pfad` ist die bereits hochgeladene Datei auf `cms_incoming` und beginnt mit `cms/` oder `vorschau/`. Titel, Quellenzeile und Alternativtext werden am Medium gespeichert. Eine Inhaltsfassung entsteht dabei nicht.
Die Warteschlange liest die Datei, schreibt das JPEG nach `vorschau/element-{id}.jpg` und gibt danach genau diese Ableitung frei. `present` bleibt leer, bis das abgeschlossen ist. Eine unlesbare Datei bleibt im Eingang, das Medium trägt `thumbnail_error` und wird nicht freigegeben. Fehlt die Datei, liegt sie außerhalb des Eingangs oder fehlt der Titel, entsteht kein Medium.
Das CMS ruft dafür nicht `DeriveThumbnail` und nicht `WebsiteRelease` auf.
Freigeben und Zurücknehmen eines schon abgelegten Mediums stehen in der Medienansicht, Bereich Beschreibung (`WebsiteRelease`). Die Warteschlange kopiert die Ableitung nach `media_public` unter `website/{id}/datei.{endung}` und setzt `website_released_at`. Der Web-Prozess schreibt diese Datei nicht. Zurücknehmen löscht nur diese Kopie.
Was freigegeben werden kann:
- Bild: Vorschaubild unter `vorschau/` auf `media_derived`, Endung jpg, jpeg, png, webp oder gif. Eine Inhaltsfassung ist dafür nicht nötig.
- Film oder Hörstück ohne Inhaltsfassung: `preview_path` am Medium, unter `teaser/`, Film mp4 oder webm, Hörstück mp3, m4a oder ogg.
- Film mit Inhaltsfassung: an der höchsten bereitgestellten Fassung eine Ausgabe mit Rolle `preview` und Pfad unter `teaser/`, Endung mp4 oder webm. Das gilt, wenn am Medium kein `preview_path` liegt.
Originaldatei, Master-Fassung und Traineranleitungen werden abgelehnt. Eine Quellenzeile (`website_credit`) und ein Alternativtext (`website_alt`) gehören zu den Anzeigedaten und erzeugen keine neue Fassung. Die Quellenzeile erscheint nur, solange die Freigabe besteht. Der interne Vermerk bleibt intern.
Ein neues Website-Bild nimmt `WebsiteIntake` auf und gibt es nach der Ableitung frei. Ein eigenständiges Präsentationsmedium legt `PresentationFile` ohne Inhaltsfassung an und gibt es nicht von selbst frei. Öffentliche Profile nach ADR-29 sind damit nicht umgesetzt.
## Was eine Komponente einhält
1. Identität und Anzeigedaten bleiben am Inhaltselement. Die Komponente speichert die Kennung, nicht eine Kopie von Titel, Text oder Datei.
2. Eine Programmkarte liest das Fachobjekt über `PublicMaterialReader` und ein Bild über `WebsiteImage`. Hero, Bild und Text sowie Karten lesen `WebsiteMedia`. Ist das Medium nicht freigegeben, wird es nicht ausgeliefert. Texte und übrige Inhalte des Widgets bleiben. Ein Widget ohne verbleibenden Inhalt entfällt.
3. Öffentliche Seiten enthalten keine Adresse unter `/redaktion/` oder `/bereich/` und kein Bibliotheksbild.
4. Die Mitgliedsdatei entsteht nur über den Mitgliederabruf, der `DecideAccess` erneut aufruft. Die Website-Ableitung läuft ausschließlich über `website.media`.
5. Der Web-Prozess schreibt nicht nach `originals/` und nicht nach `derived/` oder `public/`.
Eine Karte oder eine Komponente begründet keine Berechtigung.
## Umsetzung im CMS (19.11.2026, ADR-40)
Alle Bildstellen des CMS lesen den zentralen Medienbestand: Einstieg (Hero), Bild und Text, redaktionelle Karten,
Premium-Karten (Kartenbild) und Abschnittshintergrund. Das CMS hat keine eigene Medienverwaltung mehr.
- **Gespeichert** wird die Kennung des Inhaltselements im jeweiligen Bildschlüssel: `refs.image` (Einstieg, Bild und
Text, Premium-Karten), `data.items[].image` (redaktionelle Karten), `style.image` (Abschnittshintergrund).
**Abweichung von `refs.element`:** Die Medienkarte verwendet `refs.element` bereits für ihr Fachobjekt; ein
gemeinsamer Bildschlüssel `image` hält alle Widgets gleich und ändert die gespeicherte Struktur nicht.
- **Lesen:** `App\Domain\Cms\Widgets\Support\WebsiteImage` ruft `WebsiteMedia::present` auf. Öffentlich erscheint
ein Bild nur über `website.media`. In der Redaktionsvorschau erscheint ein nicht freigegebenes Bild als
Vorschaubild über `editorial.card` mit Hinweis; öffentlich nie.
- **Nicht freigegeben:** Das Medium wird nicht öffentlich ausgeliefert. Überschrift, Text und Schaltflächen bleiben.
Ein Widget, das danach keinen Inhalt mehr hat, entfällt. Die Redaktionsvorschau zeigt ein nicht freigegebenes Bild
weiter mit Hinweis. Entschieden am 19.11.2026, siehe ADR-40.
- **Neu hochladen im Widget-Dialog:** Die Datei geht über `WebsiteIntake::acceptImage` sofort in den Medienmanager
und wird ausgewählt. Titel aus dem Dateinamen, ohne Quellenzeile; beides ist im Medienmanager änderbar. Die
Warteschlange leitet ab und gibt frei (wie dokumentiert).
- **Auswahl:** alle Bilder (`output_class = bild`, nicht archiviert, keine Traineranleitung) mit Vorschaubild, Titel
und Website-Status; das gewählte Medium mit Status und Verweis auf den Medienmanager. Die Bildauswahl des
Modul-/Programmeditors ist an dessen Livewire-Seite gebunden und lässt sich nicht als Formularfeld einhängen; das
Bedienmuster (Suche, Vorschaubild, Auswahl) ist übernommen.
- **Alternativtext:** aus dem Medium (`website_alt`, sonst Titel). Das Feld im Widget ist eine optionale Abweichung.
- **Website-Ableitung:** Bilder werden bis 2400 px breit abgeleitet (vorher 640 px), nie vergrößert.
- **Medienmanager:** Die Medienansicht nennt die Website-Seiten, auf denen ein Bild verwendet wird
(`WebsiteImageUsage`), damit vor dem Zurücknehmen sichtbar ist, welche Seiten das Bild verlieren.
### Übernahme der früheren CMS-Bilder
- Der Job `ImportCmsImages` (angestoßen von einer Migration, ausgeführt von der Warteschlange) nimmt jede Bilddatei
unter `media_public/cms/` über `WebsiteIntake` auf. Bytegleiche Dateien werden ein Medium (SHA-256). Der Titel
kommt aus dem Dateinamen ohne Zufallskennung. Nichts wird gelöscht; der Job ist wiederholbar.
- `website_media_aliases` ordnet jeden früheren Pfad seinem Medium zu. **Wirksam** wird die Zuordnung erst, wenn das
Medium einmal für die Website freigegeben war; bis dahin (oder wenn die Ableitung scheitert) gilt der frühere Pfad
weiter, damit keine Seite ihr Bild verliert.
- Danach entscheidet die Website-Freigabe des Mediums allein, auch über die frühere Adresse `/medien/cms/…`
(404, wenn zurückgenommen).
- Gespeicherte Revisionen bleiben unverändert; frühere Pfade werden beim Darstellen zugeordnet und beim nächsten
Speichern durch die Kennung ersetzt. Frühere Pfade ohne Zuordnung bleiben über `PublicMedia` gültig.
- Eine Slideshow gibt es im CMS nicht; `WebsiteMedia::presentMany` ist für sie vorbereitet und noch unbenutzt.
## Präsentationszuordnungen (19.11.2026, ADR-41)
Ein Titelbild, Trailer oder Galerieelement an einem Film, Modul, Programm oder Lizenzartikel ist eine Referenz (`presentation_assignments`) auf die Medienidentität. Eine Inhaltsfassung ist dafür nicht erforderlich. `source_version_id` hält nur eine ausdrücklich hinterlegte Fassung fest. Die Rolle ist keine Verwendung im Aufbau, keine Inhaltsart und keine Website-Freigabe. Die Zuordnung macht das Medium nicht lizenzierbar.
Öffentliche Seiten lesen ein Bild nur über `WebsiteImage` und damit über `WebsiteMedia`. Ein freigegebener Film oder ein Hörstück wird über `website.media` ausgeliefert. Geschützte Originaldateien und Vorschaubilder der Bibliothek bleiben auf diesem Weg geschlossen. Wird die Freigabe zurückgenommen, endet die öffentliche Ausgabe; Überschriften und Texte bleiben. Ein Widget ohne verbleibenden Inhalt entfällt.
Die ausführliche Beschreibung, Einsatzhinweise, Lizenzvermerke und Lehrtexte bleiben außerhalb der öffentlichen Karte. `PublicMaterialReader` und `PublicCatalogReader` lesen dafür die Klasse-A-Angaben (`EditorialProfileReader`) und keine Datei.