- Speiseplan: Wochenansicht mit Linien, Standorten, Kennzeichnung und Allergenen (LMIV), „Heute gibt es“ auf der Startseite, Pflege in der Redaktion mit „Vorwoche übernehmen“ - Übersetzungen per KI in acht Sprachen für Meldungen und Seiten – gekennzeichnet, mit Original-Ansicht, lang/dir für Screenreader und Rechts-nach-links-Satz, Vorlesen in der jeweiligen Sprache; Ausgabe wird wie bisher bereinigt - Statistik: anonyme Aufrufzahlen je Tag/Seite/Web-App/Sprachfassung, ohne Cookies und IP-Adressen; Datenschutzvorlage ergänzt und automatisch nummeriert - Betrieb: /health, Fehlermeldungen an ALERT_EMAIL (gedrosselt), Version in der Redaktion, deploy/uebersicht.sh, aktualisieren.sh holt Images aus der Registry und prüft jede Einrichtung nach dem Start - Tests: Vitest (Logik und Server mit Test-Datenbank) und Playwright (Leser mobil, Redaktion desktop, KI über Testdienst, axe hell/dunkel) - Forgejo Actions: Prüfung bei jedem Push, Release-Image bei Versions-Tags - Barrierefreiheit: Schalter mit role=switch, Logo-Link und Kalender-Einträge nennen den sichtbaren Text zuerst (WCAG 2.5.3) Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
185 lines
12 KiB
Markdown
185 lines
12 KiB
Markdown
# Werkstatt-App
|
||
|
||
Eine moderne, werbefreie Info-App für Werkstätten für Menschen mit Behinderung (WfbM) –
|
||
mit einfachem Redaktions-Backend. Läuft als installierbare Web-App (PWA) auf Handy,
|
||
Tablet und Desktop.
|
||
|
||
## Funktionen
|
||
|
||
**App (öffentlich)**
|
||
|
||
- Startseite je nach Vorlage – z. B. großes Titelbild mit Akzentkreis und umlaufendem Text –, Hinweis-Fahne (Schließzeit oder
|
||
angeheftete Meldung), Suche, Bereichen, Neuigkeiten und Terminen
|
||
- Meldungen mit Titelbild, Galerie, Video (datensparsam erst nach Klick), Dateien und Ansprechpartnern
|
||
- Infoseiten in beliebiger Tiefe (z. B. „Dienste → Sozialer Dienst“)
|
||
- Termine & Schließzeiten, gruppiert nach Monat, mit Kalender-Abo (`/termine.ics`)
|
||
- **Speiseplan** pro Woche mit Linien (z. B. „Menü 1“), Standorten, Kennzeichnung (vegan, vegetarisch,
|
||
Fisch …) und den 14 Allergenen nach LMIV; „Heute gibt es“ auf der Startseite
|
||
- **Andere Sprachen per KI:** Meldungen und Seiten auf Englisch, Türkisch, Arabisch, Ukrainisch, Russisch,
|
||
Polnisch, Rumänisch oder Persisch – für Angehörige; gekennzeichnet, mit „Original anzeigen“,
|
||
Arabisch/Persisch von rechts nach links, Vorlesen in der jeweiligen Sprache
|
||
- Ansprechpartner-Verzeichnis, Kontaktformular, Volltextsuche
|
||
- **Barrierearm:** klare Schrift (selbst gehostet, wählbar), 3 Schriftgrößen, Hell/Dunkel,
|
||
**Leichte Sprache** pro Seite/Meldung – geprüfte Fassung (auch als KI-Entwurf erstellt) oder, wenn so
|
||
eingestellt, automatisch per KI übertragen (gekennzeichnet, mit „Fehler melden“)
|
||
- **Vorlesen** jeder Seite (Knopf in der Kopfzeile) oder eines Artikels: satzweise, der gelesene Satz
|
||
wird markiert und mitgescrollt, mit Pause, Satz vor/zurück und langsamem Tempo
|
||
- **Push-Benachrichtigungen** zu Neuigkeiten und Schließzeiten (Themen frei wählbar, jederzeit abbestellbar)
|
||
- Merkliste (lokal auf dem Gerät), Teilen, offline lesbar, als App installierbar
|
||
- Seite **Barrierefreiheit** mit Erklärung und Formular „Barriere melden“
|
||
- Keine Werbung, kein Tracking, keine externen Schriften oder CDNs
|
||
|
||
**Redaktion (`/admin`)**
|
||
|
||
- **Redaktionskalender** fürs Team: Planungen mit Status (Idee → In Arbeit → Zur Freigabe → Geplant →
|
||
Erledigt), Zuständigkeit, Frist, Notizen und Kommentaren; Monatsansicht mit Meldungen und Terminen,
|
||
Board nach Status, Liste; Ziehen & Ablegen (mit Tastatur-Alternative), Ideenspeicher,
|
||
„Meldung daraus erstellen“, „Meine Aufgaben“ auf der Übersicht
|
||
- **Ansprechpartner** einmal anlegen und in beliebig vielen Seiten und Meldungen verwenden – mit Suche,
|
||
Reihenfolge, Anlegen direkt aus dem Auswahlfeld und „Verwendet in“
|
||
- Meldungen (Entwurf, geplante Veröffentlichung, anheften), Seitenbaum, Termine,
|
||
Startseiten-Bereiche, Mediathek, Postfach
|
||
- Text-Editor mit Formatierungen, Links und Bildern
|
||
- **Leichte Sprache per KI** (Einstellungen): Anbieter Anthropic (Claude), OpenAI, Mistral (EU), DeepSeek oder Ollama,
|
||
Modell wählbar, Schlüssel verschlüsselt gespeichert, Verbindungstest, Tageslimit. Arbeitsweise
|
||
**„Mit Prüfung“** (Knopf „Mit KI erstellen“ → Entwurf prüfen → speichern) oder **„Automatisch für Leser“**
|
||
- Bilder werden automatisch gedreht, verkleinert und als WebP gespeichert
|
||
- **Speiseplan** pflegen: Wochenansicht, Gericht per Dialog, „Vorwoche übernehmen“, Linien und Standorte
|
||
- **Statistik:** anonyme Aufrufzahlen (ohne Cookies und IP-Adressen) – Verlauf, meistgelesene Inhalte,
|
||
Anteil App/Web, Nutzung von Leichter Sprache und Übersetzungen
|
||
- **Benachrichtigungen:** beim Erscheinen einer Meldung (auch zeitgesteuert), automatisch am Vortag einer
|
||
Schließzeit, oder von Hand – mit Vorschau und Verlauf
|
||
- **Rechtliches:** Impressum und Datenschutzerklärung aus Vorlagen, die genau beschreiben, was die App
|
||
verarbeitet (bitte trotzdem prüfen lassen); Erklärung zur Barrierefreiheit; Barriere-Meldungen im Postfach
|
||
- **Sicherheit:** Zwei-Faktor-Anmeldung (Authenticator-App, Wiederherstellungscodes, für Admins
|
||
verpflichtend schaltbar), „Passwort vergessen“ per E-Mail, dauerhafte Sperren gegen Durchprobieren,
|
||
Content-Security-Policy
|
||
- Rollen: **Redakteur** (Inhalte) und **Administrator** (zusätzlich Benutzer & Einstellungen)
|
||
- **Erscheinungsbild** je Einrichtung: drei Vorlagen (*Kreis*, *Klar*, *Kacheln*) mit Feinschliff –
|
||
Hausfarben mit Kontrastprüfung („Farbe anpassen“ dunkelt zu helle Töne ab), vier gut lesbare
|
||
Schriften (u. a. Atkinson Hyperlegible), eckig/rund/sehr rund. Das App-Symbol wird daraus erzeugt.
|
||
- Checkliste **„Erste Schritte“** im Dashboard führt neue Einrichtungen durch die Einrichtung
|
||
|
||
## Native Apps (iOS und Android)
|
||
|
||
Im Ordner [`mobile/`](mobile/README.md) liegt die Capacitor-Hülle für App Store und Play Store – mit
|
||
Push-Nachrichten über Firebase, nativem Vorlesen, App-Links und Symbolen aus den Einstellungen.
|
||
Gebaut wird auf einem Mac mit Xcode bzw. Android Studio; die Schritte stehen in
|
||
[`mobile/README.md`](mobile/README.md). Die Apps laden die Inhalte von der Web-App, neue Inhalte
|
||
brauchen also kein App-Update.
|
||
|
||
## Barrierefreiheit
|
||
|
||
App und Redaktion werden mit [axe-core](https://github.com/dequelabs/axe-core) gegen WCAG 2.2 AA geprüft
|
||
(hell und dunkel, Handy und Desktop) – aktuell ohne Befund. Dazu u. a.: Sprunglinks zum Inhalt,
|
||
sichtbarer Tastaturfokus, beschriftete Bedienelemente, Ansagen für Screenreader bei Änderungen,
|
||
Tastatur-Alternativen zu Ziehen & Ablegen, `prefers-reduced-motion`, Kontrast ≥ 4,5 : 1.
|
||
Schriftgröße und Farbschema lassen sich auch in der Redaktion einstellen (Mein Konto).
|
||
|
||
## Tests
|
||
|
||
```bash
|
||
npm run test:unit # Vitest: Logik und Server-Funktionen mit eigener Test-Datenbank
|
||
npm run build
|
||
npm run test:e2e # Playwright: Leser (Handy) und Redaktion (Desktop) inkl. axe-Prüfung, hell und dunkel
|
||
```
|
||
|
||
Die Ende-zu-Ende-Tests starten die gebaute App mit frischer Demo-Datenbank und einem nachgebauten
|
||
KI-Dienst (`tests/e2e/`). Einmalig `npx playwright install chromium` – oder mit `PW_CHROMIUM=/pfad/zu/chrome`
|
||
ein vorhandenes Chromium nutzen.
|
||
|
||
**Forgejo Actions:** `.forgejo/workflows/ci.yml` prüft jeden Push (Typen, Unit-Tests, Build, Ende-zu-Ende).
|
||
`.forgejo/workflows/release.yml` baut bei einem Tag `v1.2.0` das Docker-Image und legt es als
|
||
`git.loheide.cloud/friloo/werkstaetten-app:1.2.0` (und `:latest`) in die Registry. Dafür braucht es einen
|
||
Forgejo-Runner mit dem Label `docker` (für den Release-Job mit Zugriff auf den Docker-Socket) und das
|
||
Repository-Secret `REGISTRY_TOKEN` (Token mit „package: write“). Änderungen stehen in [`CHANGELOG.md`](CHANGELOG.md).
|
||
|
||
## Technik
|
||
|
||
SvelteKit 2 (Svelte 5) · Tailwind CSS 4 · SQLite (better-sqlite3) mit Drizzle ORM · sharp · Tiptap.
|
||
Bewusst schlank: ein Node-Prozess, eine SQLite-Datei, ein Upload-Ordner (~200 MB RAM im Betrieb).
|
||
|
||
## Loslegen (Entwicklung)
|
||
|
||
```bash
|
||
npm install
|
||
npm run db:seed # Demo-Inhalte (fiktive „Lindenhof Werkstätten“)
|
||
npm run user:create -- admin@example.org ein-langes-passwort admin "Vorname Name"
|
||
npm run dev
|
||
```
|
||
|
||
App: http://localhost:5173 · Redaktion: http://localhost:5173/admin
|
||
|
||
## Betrieb
|
||
|
||
```bash
|
||
cp .env.example .env # ORIGIN, ADMIN_EMAIL, ADMIN_PASSWORD setzen
|
||
docker compose up -d --build
|
||
```
|
||
|
||
Alle Daten (Datenbank + Uploads) liegen in `./data` – das ist das Einzige, was gesichert werden muss.
|
||
Der Container lauscht auf `127.0.0.1:3000`; davor einen Reverse-Proxy mit HTTPS (z. B. Caddy) setzen.
|
||
Ohne Docker: `npm ci && npm run build && ORIGIN=https://… BODY_SIZE_LIMIT=30M node build`.
|
||
|
||
**Überwachung:** `GET /health` antwortet mit Status, Version und Datenbank-Zustand (HTTP 503 bei
|
||
Problemen) – geeignet für Uptime-Kuma, Healthchecks o. ä. Unerwartete Fehler landen im Log und, mit
|
||
`ALERT_EMAIL`, im Postfach der Betreuung. Die Version steht unten in der Seitenleiste der Redaktion.
|
||
|
||
| Variable | Bedeutung |
|
||
| --------------------------------- | --------------------------------------------------------------- |
|
||
| `ORIGIN` | Öffentliche URL (Pflicht in Produktion, sonst schlagen Formulare fehl) |
|
||
| `DATA_DIR` | Ordner für `app.db` und `uploads/` (Standard `./data`) |
|
||
| `ADMIN_EMAIL` / `ADMIN_PASSWORD` | Erster Admin, wird angelegt, solange es noch keinen Benutzer gibt |
|
||
| `APP_NAME`, `ORG_NAME`, `BRAND_COLOR`, `ACCENT_COLOR` | Optionale Startwerte beim allerersten Start |
|
||
| `BODY_SIZE_LIMIT` | Max. Upload-Größe (im Docker-Image auf 30M gesetzt) |
|
||
| `ALERT_EMAIL` | Bekommt unerwartete Fehler per E-Mail (gleiche Fehler höchstens stündlich, max. 20/Tag; braucht SMTP) |
|
||
| `APP_VERSION` | Beim Bauen: Versionsnummer für `/health` und die Redaktion (Standard: aus `package.json`) |
|
||
| `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS`, `SMTP_FROM` | E-Mail-Versand für „Passwort vergessen“. Ohne SMTP steht der Link im Server-Log |
|
||
| `GOOGLE_TOKEN_URL`, `FCM_API_URL` | Nur für Tests: andere Adressen für Firebase |
|
||
| `VAPID_PUBLIC_KEY` / `VAPID_PRIVATE_KEY` | Optional – sonst werden die Push-Schlüssel automatisch erzeugt und gespeichert |
|
||
|
||
## Mehrere Einrichtungen
|
||
|
||
Jede Werkstatt bekommt eine **eigene Installation**: eigener Container, eigene Datenbank, eigene
|
||
Domain – Daten und Zugänge bleiben strikt getrennt, und jede Einrichtung gestaltet ihre App selbst
|
||
(Vorlage, Farben, Schrift, Logo unter *Einstellungen → Erscheinungsbild*). Alle nutzen dasselbe Image.
|
||
|
||
```bash
|
||
docker build -t werkstatt-app:latest . # einmal bzw. bei jedem Update
|
||
|
||
APP_NAME="Lindenhof-App" ORG_NAME="Lindenhof Werkstätten" BRAND_COLOR=#0f4c5c \
|
||
deploy/neue-einrichtung.sh lindenhof app.lindenhof-werkstaetten.de it@lindenhof.de
|
||
cd /srv/werkstatt-apps/lindenhof && docker compose up -d
|
||
```
|
||
|
||
Das Skript legt `/srv/werkstatt-apps/<kurzname>/` mit `.env`, `compose.yml` und `data/` an, wählt
|
||
einen freien Port, erzeugt ein Admin-Passwort und gibt den passenden Caddy-Block aus. `APP_NAME`,
|
||
`ORG_NAME`, `BRAND_COLOR` und `ACCENT_COLOR` gelten nur für den allerersten Start (zu helle Farben
|
||
werden automatisch abgedunkelt); danach zählt, was in den Einstellungen steht.
|
||
|
||
| Skript | Zweck |
|
||
| ------ | ----- |
|
||
| `deploy/neue-einrichtung.sh <kurzname> <domain> [admin-mail]` | Einrichtung anlegen |
|
||
| `VERSION=1.2.0 deploy/aktualisieren.sh [kurzname …]` | Image aus der Registry holen (ohne `VERSION`: lokal bauen), Einrichtungen nacheinander neu starten und per `/health` prüfen – Migrationen laufen automatisch |
|
||
| `deploy/uebersicht.sh` | Tabelle aller Einrichtungen: Container, App-Zustand, Version, letzte Sicherung (Rückgabewert 1, wenn eine ausfällt – für cron) |
|
||
| `deploy/sichern.sh [kurzname …]` | Datenbank (konsistente Kopie im laufenden Container) und Uploads sichern, 14 Tage aufbewahren |
|
||
|
||
Jede Einrichtung braucht etwa 100–150 MB RAM (Limit 384 MB). Für eigene Apps im Store je
|
||
Einrichtung siehe [`mobile/README.md`](mobile/README.md#mehrere-einrichtungen).
|
||
|
||
## Erweitern
|
||
|
||
- **Neues Feld / neuer Inhaltstyp:** `src/lib/server/db/schema.ts` ändern → `npm run db:generate`
|
||
erzeugt eine Migration in `drizzle/`, die beim nächsten Start automatisch eingespielt wird.
|
||
- **Admin-Bereiche** folgen alle demselben Muster: `src/routes/admin/(panel)/<bereich>/`
|
||
mit Liste (`+page`) und Bearbeiten (`[id]/+page`, `neu` = anlegen). Bausteine liegen in `src/lib/admin/`.
|
||
- **Icons** für Bereiche/Seiten: `src/lib/icons.ts`. **Farben** kommen aus den Einstellungen; alle übrigen
|
||
Töne leitet `src/app.css` daraus ab.
|
||
- **Design-Vorlagen, Schriften, Rundungen:** `src/lib/theme.ts`. Eine Vorlage bestimmt Kopfbereich
|
||
(`src/lib/components/Hero*.svelte`), Bereichs-Kacheln (`Tile.svelte`) und Termine auf der Startseite;
|
||
Rundungen wirken über `data-radius` an `<html>` und die `--radius-*`-Variablen in `src/app.css`.
|
||
- **Öffentliche Seiten:** `src/routes/(app)/`, Datenabfragen gebündelt in `src/lib/server/content.ts`.
|
||
|
||
## Ideen für später
|
||
|
||
E-Mail-Weiterleitung des Kontaktformulars, Umfragen, Bedienoberfläche in weiteren Sprachen.
|