119 lines
7.2 KiB
Markdown
119 lines
7.2 KiB
Markdown
# Perspektivwerk Terminbuchung – lokales Entwicklungssystem
|
||
|
||
Dieser Ordner enthält eine lokale Contao-4.13.58-Entwicklungsumgebung mit Apache, MariaDB und Bootstrap 5. Die Buchungskomponente verwendet browsernative DOM-APIs und keine jQuery-Abhängigkeit.
|
||
|
||
## Contao-Version und Sicherheitsstatus
|
||
|
||
Die Abhängigkeiten sind auf `contao/manager-bundle` und `contao/core-bundle` in Version `4.13.58` festgelegt. `composer.lock` ist Teil des Repositorys und muss bei Änderungen mit eingecheckt werden.
|
||
|
||
Contao 4.13.58 ist ausschließlich als lokale Kompatibilitätsumgebung vorgesehen. In `composer.json` ist die Advisory `PKSA-f8tt-pn3h-s2tw` gezielt dokumentiert und für Composer freigegeben, weil keine neuere 4.13-Version verfügbar ist. Ein `composer audit` meldet darüber hinaus historische Abhängigkeitswarnungen; diese Umgebung darf deshalb nicht unverändert produktiv eingesetzt werden.
|
||
|
||
## Start
|
||
|
||
Voraussetzungen: Docker Desktop (Compose v2) und optional Node.js 20+ zum Ausführen der JavaScript-Regressionstests.
|
||
|
||
```powershell
|
||
docker compose up --build
|
||
```
|
||
|
||
Beim ersten Start eines frischen Clones erzeugt Contao die benötigten Laufzeitverzeichnisse und Asset-Symlinks. Danach einmalig ausführen:
|
||
|
||
```powershell
|
||
docker compose exec app vendor/bin/contao-setup --no-interaction --env=dev
|
||
docker compose exec app chown -R www-data:www-data var public system files
|
||
docker compose exec app vendor/bin/contao-console contao:migrate --no-interaction
|
||
|
||
Neuen Admin-Account anlegen:
|
||
|
||
```powershell
|
||
docker compose exec app vendor/bin/contao-console contao:user:create --admin
|
||
```
|
||
|
||
Danach den versionierten Seitenzustand importieren:
|
||
|
||
```powershell
|
||
.\scripts\Import-ContaoBaseline.ps1
|
||
```
|
||
|
||
- Website/CMS: <http://localhost:8080>
|
||
- Contao-Login: <http://localhost:8080/contao/login>
|
||
- Datenbankinspektor: <http://localhost:8081> (Server `db`, Benutzer `perspektivwerk`, Passwort `perspektivwerk`, Datenbank `perspektivwerk`)
|
||
|
||
Für die Frontend-Regressionstests:
|
||
|
||
```powershell
|
||
npm install
|
||
npm test
|
||
```
|
||
|
||
**Seite öffnen:**
|
||
|
||
Frontend: http://localhost:8080/default
|
||
Backend: http://localhost:8080/contao
|
||
|
||
|
||
## HTML Nachbau der Perpektivwerkseite
|
||
|
||
http://localhost:8080/perspektivwerk/
|
||
|
||
Die genaue Contao-, PHP- und Template-Version der öffentlichen Seite ist nicht verlässlich aus dem ausgelieferten HTML ableitbar. Das Setup bildet daher die wahrscheinlichste Komponentenfamilie nach; es ist kein Dump der Produktivinstallation. IONOS/Hosting, Matomo-Konfiguration, Inhalte, Templates und Erweiterungen müssen bei Bedarf separat ergänzt werden.
|
||
|
||
Die Terminlogik liegt in `public/booking/booking.js` als browsernatives ES-Modul. Für die statische Perspektivwerk-Vorschau liegen identische Kopien unter `public/perspektivwerk/js/`.
|
||
|
||
## Zwei Einbindungswege
|
||
|
||
Die Terminbuchungskomponente hat eine Vorschau auf einem Webseiten-Nachbau der Orginalseite:
|
||
|
||
**Apache-Vorschau:** auf der statischen Perspektivwerk-Seite unter <http://localhost:8080/perspektivwerk/>. Die Seite liegt in `public/perspektivwerk/`; ihre Referenzen auf die Komponente verwenden die relativen Pfade `js/booking.css` und `js/booking.js`.
|
||
2. **Contao:** als eigenständiges Inhaltselement vom Typ **HTML** auf einer Contao-Seite. Es enthält das kombinierte Snippet mit CSS, Komponentenplatzhalter und JavaScript.
|
||
|
||
`public/` ist der Apache-Webroot der lokalen Entwicklungsumgebung. Daher ist kein Kopieren der Komponentenassets nach `files/terminbuchung/` erforderlich.
|
||
|
||
## Statische Buchungsvorschau in Contao einbinden
|
||
|
||
Die erste Komponente ist absichtlich datenbankfrei. Sie zeigt Test-Slots, rendert einen Monatskalender und unterscheidet freie von belegten Terminen. Eine Buchung wird noch nicht gespeichert.
|
||
|
||
Die Komponente benötigt keinen TypeScript-Compiler und keinen Build-Schritt. Regressionstests ausführen:
|
||
|
||
```powershell
|
||
npm run test
|
||
```
|
||
### Einbinden in Contao
|
||
|
||
Ein **neues** Inhaltselement vom Typ **HTML** anlegen. Im Feld **HTML-Code** den vollständigen Inhalt aus [integration/contao-html-element.html](integration/contao-html-element.html) einfügen und speichern. Nicht das Inhaltselement **Text** und keinen TinyMCE-Editor verwenden: Diese können `link`- und `script`-Tags als Text maskieren. Für die Produktionsschule wird `data-project="produktionsschule"` gesetzt.
|
||
|
||
In der Seitenvorschau muss der HTML-Quelltext die Tags als `<link ...>` und `<script ...>` enthalten. Erscheinen stattdessen `<link` oder `<script`, wurde nicht das unmaskierte Feld **HTML-Code** verwendet und die Komponente kann nicht starten.
|
||
|
||
### Erforderliche Contao-Sicherheitseinstellung
|
||
|
||
Contao maskiert nicht freigegebene HTML-Tags auch im Inhaltselement **HTML**. Vor dem Einfügen der Komponente unter **System → Einstellungen → Sicherheit** die folgenden Einträge ergänzen:
|
||
|
||
- **Erlaubte HTML-Tags:** `script`, `link`
|
||
- **Erlaubte HTML-Attribute:** für `script` die Attribute `src`, `type`; für `link` die Attribute `href`, `rel`; für den Komponentenplatzhalter auf `div` entweder `data-*` oder mindestens `data-sufw-booking`, `data-project`.
|
||
|
||
Danach den Contao-Cache über **Systemwartung** leeren und das Inhaltselement erneut speichern. Keine globale Freigabe mit `*` verwenden. Wer ein HTML-Inhaltselement bearbeiten darf, kann mit dem freigegebenen `script`-Tag JavaScript auf der Website ausführen; diese Bearbeitungsrechte müssen daher auf vertrauenswürdige Backend-Nutzer beschränkt bleiben.
|
||
|
||
Die Beispieltermine stehen in `public/booking/booking.js`; `public/perspektivwerk/js/booking.js` ist die für den statischen Upload bestimmte Kopie. Ein Test stellt sicher, dass beide Dateien gleich bleiben. Der spätere serverseitige Endpunkt muss sie ersetzen; Datenbankzugänge oder SQL gehören niemals in das HTML oder das Browser-JavaScript.
|
||
|
||
## Statische Perspektivwerk-Seite übertragen
|
||
|
||
Das Skript [scripts/Deploy-Perspektivwerk.ps1](scripts/Deploy-Perspektivwerk.ps1) überträgt ausschließlich den Inhalt von `public/perspektivwerk/` per SCP und korrigiert anschließend die Lesbarkeit auf dem Server per SSH. Dieser Ordner enthält auch `js/booking.js` und `js/booking.css`. Es lädt weder Contao noch die Datenbank oder andere Projektdateien hoch.
|
||
|
||
```powershell
|
||
.\scripts\Deploy-Perspektivwerk.ps1
|
||
```
|
||
|
||
Der Hostname `boogie` wird aus der lokalen SSH-Konfiguration verwendet. Der vollständige Inhalt wird per SCP-Aufruf nach `/home/boogie/html/perspektivwerk/` übertragen. Anschließend führt ein separater SSH-Aufruf `chmod -R a+rX /home/boogie/html/perspektivwerk` aus. Die Passphrase des SSH-Schlüssels wird daher in der Regel zweimal abgefragt.
|
||
|
||
Vor dem Upload gibt das Skript den vollständigen Zielpfad aus. Damit lässt sich direkt prüfen, ob `booking.js` unter `/home/boogie/html/perspektivwerk/js/booking.js` landet. Das große `X` in `a+rX` setzt das Ausführungsrecht nur auf Verzeichnissen und auf bereits ausführbaren Dateien; normale HTML-, CSS- und JavaScript-Dateien erhalten kein unnötiges Ausführungsbit.
|
||
|
||
## Versionierter Contao-Seitenzustand
|
||
|
||
Die Contao-Seiten, Artikel und Layouts liegen in MariaDB und werden deshalb zusätzlich als bereinigter SQL-Seed versioniert. Details zu Export, Import und den bewusst ausgeschlossenen Daten stehen in [database/README.md](database/README.md).
|
||
|
||
Die Seed-Integritätsprüfungen ausführen:
|
||
|
||
```powershell
|
||
Invoke-Pester .\tests\ContaoBaseline.Tests.ps1
|
||
```
|