werkstaetten-app/README.md
Friederich Loheide 21a54da2e3 Erscheinungsbild je Einrichtung: Vorlagen, Schriften, Farben, mehrere Installationen
- Drei Design-Vorlagen (Kreis, Klar, Kacheln) mit Feinschliff: vier gut lesbare
  Schriften, eckig/rund/sehr rund, Hausfarben mit Live-Kontrastprüfung und
  „Farbe anpassen“; der Server lehnt zu helle Farben mit Vorschlag ab
- Fertige Farbpaare alle mit mindestens 4,5:1 zu Weiß
- Markenfarben greifen jetzt zuverlässig (Spezifität der eingebetteten Variablen);
  dunkle Darstellung wird aus der Hauptfarbe abgeleitet statt fest Indigo
- Checkliste „Erste Schritte“ im Dashboard für neue Einrichtungen
- Startwerte (APP_NAME, ORG_NAME, BRAND_COLOR, ACCENT_COLOR) beim ersten Start
- deploy/: neue-einrichtung.sh, aktualisieren.sh, sichern.sh für eine
  Installation je Kunde mit gemeinsamem Image
- mobile/: KUNDE=<kurzname> baut die App einer Einrichtung aus mobile/kunden/<kurzname>/
  inklusive deren Firebase-Dateien

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-09 17:54:11 +00:00

153 lines
9.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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`)
- 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
- **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).
## 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`.
| 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) |
| `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 |
| `deploy/aktualisieren.sh [kurzname …]` | Image neu bauen, alle (oder die genannten) Einrichtungen nacheinander neu starten – Migrationen laufen automatisch |
| `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
Push-Benachrichtigungen (Web Push), E-Mail-Weiterleitung des Kontaktformulars, Umfragen,
Mehrsprachigkeit, Standort-Filter für Speisepläne.