Files
LektorenPlan/web/README.md
T

236 lines
10 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.
# LektorenPlan Web
Browserbasierte, funktional entsprechende Umsetzung der macOS-App
**LektorenPlan**: Gottesdienstplan, Gottesdienstordnung, Teamverwaltung,
Statistik, Austausch, liturgischer Kalender, PDF/ Druck und eine
Mehrbenutzerverwaltung mit Mandanten.
Die Webversion läuft als einzelner Go-Prozess mit einer SQLite-Datenbank. Sie
ist **CGO-frei** und lässt sich damit unkompliziert für Linux/arm64 (z. B.
Raspberry Pi, ARM-Server, Docker) bauen. Die bestehende macOS-App bleibt
unverändert nutzbar.
## Funktionsumfang
- **Gottesdienstplan** mit Tageszeilen, Lesungen, Kirchenspalten, Feiertagen
und farblich markierter Liturgie; Lesungen verlinken direkt auf die
Tagesliturgie bei Schott
- **Zeitstrahl** mit Marken des Kalender- und Kirchenjahres sowie erkennbaren
Monaten mit vorhandenen Planungsdaten
- **Zeitraum-Presets** für Quartale, Weihnachts- und Osterzeit sowie 3, 6 oder
12 Monate im Anschluss an die letzten Planungsdaten
- **Personenfilter** im Plan: Leser filtern nach ihrer verknüpften Person,
Redakteure nach beliebigen Personen
- **Automatische Planung** mit Ausschlüssen, Präferenzen, Fairness und
Doppelrollen-Regeln; manuelle Nachsteuerung inklusive Sperren
- **Gottesdienstordnung** mit wiederkehrenden Vorlagen, Ausnahmen und
Sondergottesdiensten (auch außerhalb der Kirche)
- **Team & Abwesenheiten** mit Rollen, Präferenzen, Monatslimits und
Einsatzhistorie
- **Eigene Kontaktdaten für Leser:** Wer mit einer Person verknüpft ist, kann
die eigene E-Mail-Adresse selbst pflegen; Redakteure können Adressen für alle
Personen setzen. Alle Adressen werden verschlüsselt gespeichert
- **Statistik** über Besetzung, Fairness, Monatsverlauf und Kirchenverteilung
- **Austausch** per JSON-Export und zweistufigem Import mit Vorschau
- **Liturgischer Kalender** für das Erzbistum Köln mit Online-Aktualisierung,
Offline-Snapshot und lokaler Berechnung als Rückfallebene
- **PDF/Druck** in zwei Varianten: A4 quer als vollständiger Plan und A4 hoch
als kompakte Gottesdienstliste
- **Mandanten, Konten und Kirchen** zentral über die Administration verwalten
- **Sichere Anmeldung** mit initialem Passwort und erzwungener eigener
Passwortvergabe beim ersten Login; Administratoren können Passwörter
zurücksetzen
- **Administrator-konfigurierbarer Anmeldespruch** unter dem Logo; globale
Website-Einstellungen sind ausschließlich für Administratoren sichtbar
## Schnellstart
Voraussetzung: Go 1.27 oder neuer.
```bash
cd web
go run . -seed-demo -demo
```
Anschließend <http://localhost:8080> öffnen.
Die Demo-Datenbank wird beim ersten Start angelegt. Mit den dokumentierten
Demo-Zugängen erhält man sofort einen vollständigen Plan:
| Konto | Passwort | Rolle |
|----------|------------|---------------|
| `admin` | `admin123` | Administrator |
| `editor` | `editor123`| Redakteur |
| `reader` | `reader123`| Leser |
> Beim ersten Anmelden muss für jedes Konto ein eigenes Passwort vergeben
> werden. Die Demo-Zugänge sind ausschließlich für lokale Tests gedacht. In
> einer produktiven Installation `-seed-demo` weglassen und ein eigenes
> Administratorkonto anlegen.
Ohne `-seed-demo` und ohne vorhandene Konten erzeugt der Server automatisch
einen Administrator. Wird kein Passwort übergeben, wird ein einmaliges
Zufallspasswort im Log ausgegeben:
```bash
go run . -db /var/lib/lektorenplan/lektorenplan.db \
-admin-user admin -admin-password 'ein-sicheres-passwort'
```
## Konfiguration
Alle Flags lassen sich auch über Umgebungsvariablen setzen:
| Flag | Umgebungsvariable | Standard | Bedeutung |
|------|-------------------|----------|-----------|
| `-addr` | `LP_ADDR` | `:8080` | HTTP-Listenadresse |
| `-db` | `LP_DB` | `lektorenplan.db` | Pfad zur SQLite-Datei |
| `-seed-demo` | `LP_SEED_DEMO` | `false` | Demo-Mandanten und Demo-Konten anlegen |
| `-admin-user` | `LP_ADMIN_USER` | `admin` | Benutzername des ersten Administrators |
| `-admin-password` | `LP_ADMIN_PASSWORD` | – | Passwort des ersten Administrators |
| `-secure-cookies` | `LP_SECURE_COOKIES` | `false` | Cookies nur über HTTPS senden |
| `-demo` | `LP_DEMO_MODE` | `false` | Demo-Hinweis in der Oberfläche anzeigen |
| `-sync-liturgy` | `LP_SYNC_LITURGY` | `true` | Liturgischen Kalender täglich im Hintergrund aktualisieren |
## Rollen und Mandanten
Jedes Konto hat genau eine globale Rolle:
- **Administrator** verwaltet alle Mandanten, Konten und Kirchen und darf überall
planen.
- **Redakteur** bearbeitet die ihm freigegebenen Mandanten.
- **Leser** sieht die ihm freigegebenen Mandanten ausschließlich lesend. Wird
ein Leser-Konto mit einer Person verknüpft, darf es deren Stammdaten,
Präferenzen, Abwesenheiten und die eigene E-Mail-Adresse selbst bearbeiten
und den Plan nach dieser Person filtern; ohne Verknüpfung bleiben Teamdaten
für Leser unsichtbar.
Planungsdaten (Kirchen, Personen, Vorlagen, Gottesdienste, Einteilungen,
Abwesenheiten und Einstellungen) sind immer einem Mandanten zugeordnet.
Administratoren sehen alle Mandanten; Redakteure und Leser nur die in
`memberships` eingetragenen. Der aktive Mandant wird über die Seitenleiste
gewechselt.
## Verschlüsselte Kontaktdaten
E-Mail-Adressen und SMTP-Zugangsdaten liegen nicht im Klartext in der
Datenbank.
- Jedes Konto mit Schlüsselbedarf (Redakteur oder Leser) besitzt ein
X25519-Schlüsselpaar. Der private Schlüssel wird mit AES-GCM verschlüsselt
gespeichert; den Schlüssel dafür leitet Argon2id aus dem Anmeldepasswort ab.
- Die E-Mail-Adresse einer Person wird mit einem eigenen Datenschlüssel
verschlüsselt. Derselbe Datenschlüssel wird für jeden Redakteur des
Mandanten und für den verknüpften Leser mit dessen öffentlichem Schlüssel
verpackt. So entschlüsselt jeder Beteiligte die Adresse mit dem aus seinem
Login abgeleiteten Schlüssel; Administratoren erhalten bewusst keinen
Zugriff.
- Legt ein Leser seine Adresse selbst an oder ändert er sie, wird sie sofort
für alle vorhandenen Redakteure neu verpackt. Wird später ein Redakteur
angelegt, erhält er die vorhandenen Datenschlüssel bei der nächsten
Anmeldung eines Lesers oder eines bereits entsperrten Redakteurs.
- Redakteure können Adressen für beliebige Lektoren und Kommunionhelfer
setzen. Eine später vom Leser selbst gepflegte Adresse ersetzt diesen Wert.
- Nach einem Serverneustart sind die Schlüssel nur im Arbeitsspeicher und
müssen über „Daten entsperren“ mit dem eigenen Passwort erneut geöffnet
werden. Exportdateien enthalten keine Kontaktdaten.
> Ein administrativer Passwort-Reset erzeugt ein temporäres Passwort und
> schützt damit ein neues Schlüsselpaar, bis der Betroffene ein eigenes
> Passwort setzt. In dieser kurzen Phase ist der Zugriff auf die
> verschlüsselten Daten technisch möglich; danach nicht mehr.
## Bauen und testen
```bash
cd web
gofmt -l .
go vet ./...
go test ./...
go build ./...
# statisches Linux/arm64-Binary
./scripts/build-linux-arm64.sh
# → dist/lektorenplan-linux-arm64
```
Das Binary ist statisch gelinkt und benötigt auf dem Zielsystem weder libc
noch eine SQLite-Installation.
## Deployment (Linux/arm64)
Beispiel für eine Installation unter `/opt/lektorenplan`:
```bash
# Binary auf den Server kopieren
scp dist/lektorenplan-linux-arm64 server:/tmp/lektorenplan
ssh server
sudo useradd --system --home /opt/lektorenplan --shell /usr/sbin/nologin lektorenplan
sudo install -d -o lektorenplan -g lektorenplan /opt/lektorenplan /var/lib/lektorenplan
sudo install -m 0755 -o lektorenplan -g lektorenplan \
/tmp/lektorenplan /opt/lektorenplan/lektorenplan
```
Dienst einrichten (Vorlage: [`scripts/lektorenplan.service`](scripts/lektorenplan.service)):
```bash
sudo cp scripts/lektorenplan.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now lektorenplan
```
Empfohlen ist ein Reverse Proxy mit TLS (Caddy, nginx oder Traefik), der auf
`127.0.0.1:8080` weiterleitet. Dabei `LP_SECURE_COOKIES=true` setzen. Der
Server sollte nicht direkt öffentlich erreichbar sein.
### Betrieb und Sicherheit
- **Backups:** SQLite-Datei regelmäßig sichern, idealerweise mit
`sqlite3 /var/lib/lektorenplan/lektorenplan.db ".backup ..."` oder im
laufenden Betrieb über einen Dateisystem-Snapshot. WAL-Dateien
(`-wal`, `-shm`) gehören zum konsistenten Stand.
- **Passwörter:** bcrypt-Hashes, serverseitige Sitzungen, HttpOnly-Cookies,
CSRF-Schutz auf allen schreibenden Formularen.
- **Erster Login:** Jedes neu angelegte Konto muss beim ersten Anmelden ein
eigenes Passwort setzen. Demo-Konten nach dem Test entfernen bzw. deaktivieren.
- **Updates:** Neue Binärdatei austauschen und Dienst neu starten. Das
Datenbankschema wird beim Start automatisch migriert.
- **Netzwerk:** Der Prozess lauscht standardmäßig auf allen Interfaces. Für
einen Proxy-Betrieb `-addr 127.0.0.1:8080` verwenden.
## Projektstruktur
```
web/
├── main.go Start, Flags, Bootstrap, täglicher Liturgie-Sync
├── domain/ Modelle, Datumslogik, Planer, Statistik, Liturgie
├── liturgy/ Online-API, Offline-Snapshot, lokale Berechnung
├── store/ SQLite-Schema, Mandanten, Konten, Planungsdaten
├── pdf/ PDF-Renderer (A4 quer und A4 hoch)
├── web/ HTTP-Server, Handler, Templates, CSS/JS
│ ├── templates/ serverseitige html/template-Seiten
│ └── static/ Stylesheet und progressive JavaScript-Helfer
└── scripts/ Build- und Deployment-Vorlagen
```
## Liturgische Daten
Der liturgische Kalender stammt von
[www.eucharistiefeier.de](https://www.eucharistiefeier.de). Für die Jahre
2025–2028 ist ein Offline-Snapshot eingebettet. Die Anwendung aktualisiert den
aktuellen und den Folgejahrgang täglich im Hintergrund, sofern
`LP_SYNC_LITURGY` nicht deaktiviert ist. Schlägt der Online-Abruf fehl, werden
fehlende Tage lokal berechnet, damit Planung und PDF-Export weiterhin
funktionieren.
> Daten von www.eucharistiefeier.de – fair use, ausschließlich zur Anzeige.
> Die Daten bleiben Eigentum der Quelle.
## Hinweis zur macOS-App
Die Webversion liegt vollständig unter `web/` und verwendet ein eigenes
Go-Modul. Die SwiftUI-App unter `Sources/` wird dadurch nicht verändert. Beide
Varianten können parallel gebaut und betrieben werden.