rpg-westreiche/westreiche_website/README.md

153 lines
7.5 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.

# Westreiche – Charakterverwalter
Geschlossene Web-App für die Westreiche-Runde: Charakterbögen für OSE-alike
Charaktere pflegen, Zauber und Liturgien aus dem Vault zuordnen, Inventar
führen und den Bogen als PDF mitnehmen.
Technische Basis wie beim Schwester-Repo `drink-it-cold`: PHP 8.1+, MariaDB,
server-gerendertes HTML, kein Composer, keine Build-Tools. Theme analog
`zauberturm.de` (Nachtblau/Schwarz/Gold, Pergament, Glutfunken, Cinzel/EB
Garamond) mit Animationen.
## Funktionsumfang
- **Geschlossene Benutzergruppe**: Der Spielleiter legt Konten an oder erzeugt
eine **Einladung** (Link, 7 Tage gültig, einmal verwendbar) – der Eingeladene
setzt sein Passwort selbst. Anmeldung mit **Benutzername oder E-Mail**.
- **Rollen**: `admin` (Spielleiter, sieht und bearbeitet alle Bögen, verwaltet
Konten und Kataloge) und `user` (eigene Bögen).
- **Charaktere**: Name, Beiname, Klasse (12 Westreiche-Klassen), Stufe, EP,
TP, Rüstungsklasse (aufsteigend), Angriff, Gold, die sechs Attribute mit
automatischem Attributsbonus nach Hausregel V1.1, Rettungswürfe, Gottheit,
Alter/Größe/Gewicht, Erscheinung, Hintergrund, Notizen, Status
(im Spiel / gefallen / Ruhestand).
- **Rettungswürfe**: kommen aus der Klassentabelle (`WS_SAVE_TABLES` in
`app/rules.php`, OSE-SRD-Grundwerte) und werden bei Änderung von Klasse
oder Stufe automatisch nachgezogen; einzelne Werte bleiben überschreibbar.
- **Bewaffnung & Rüstung**: Waffe oder Rüstungsteil zunächst aus dem Katalog
wählen (`weapons`/`armors`), danach ist jeder Eintrag frei änderbar
(Name, Schadenswürfel, Trefferbonus, RK-Bonus, Notiz, geführt/angelegt).
Daraus abgeleitet: **Trefferwurf** = Grundangriff + Attributsbonus
(Nahkampf Stärke, Fernkampf Geschick) + Waffenbonus, **Schaden** = Würfel +
Attributsbonus, **Rüstungsklasse** = 10 + Geschick + angelegte Rüstung
(ein Eintrag im Feld „Rüstungsklasse“ überschreibt die Automatik).
- **Fertigkeiten**: Katalog (`skills`) genau wie auf dem Charakterbogen
(`RPG/6-Dokumente/Charakterbogen.pdf`) in den Gruppen **Körper, Wildnis,
Sozial, Wissen** – Quelle ist `WS_SKILL_CATALOG` in `app/rules.php`
(33 Fertigkeiten, Attribut + Gruppe). Anzeige und PDF führen je Gruppe eine
Tabelle mit Fertigkeit · Attribut · **MOD** (Attributsbonus) · **Stufe**
(Bonus) · Notiz. Freie Zusatzfertigkeiten sind weiterhin möglich. Beim Anlegen bekommt **jede** Katalogfertigkeit ihren
Startwert (Fertigkeitsstufe = Attributsbonus des zugeordneten Attributs) und
erscheint in der Gruppe seines Charakterbogens.
Attributsänderungen ziehen diese Startwerte mit, solange sie nicht manuell
gesteigert wurden; „Startwerte auffrischen“ erledigt das auf Wunsch auch
für alle Werte.
- **Zauber und Liturgien**: Katalog mit 147 arkanen Zaubern und 74 Liturgien
aus `RPG/5-Regeln/Zauber/…` (Schule, Grad, Klasse, Dauer, Reichweite,
Kurztext) und Zuordnung pro Charakter (keine Vorbereitungspflicht – die
Hausregel kennt kein Vorbereiten von Zaubern).
- **Inventar**: Gegenstände mit Anzahl, Art, Gewicht, Wert, Notiz und
„angelegt“-Status.
- **Porträt**: Upload per Formular (JPEG/PNG/WebP, max. 5 MB) – serverseitig
über GD neu als JPEG kodiert (Metadaten weg, max. 900 px), gespeichert in
`uploads/portraits/`. Ohne eigenes Bild greift ein gemaltes
**Platzhalterporträt der Klasse** aus `assets/portraits/*.webp`
(12 Klassen, per fal.ai erzeugt). Das Porträt steht auch auf dem PDF-Bogen.
- **PDF-Export**: eigener kleiner PDF-Writer (kein Composer, kein GD) rendert
ein A4-Pergamentblatt mit Goldrahmen, Attributkästen, Kampfblock,
Rettungswürfen, Fertigkeiten, Zaubern nach Grad, Inventar und Notizen –
bei Bedarf über mehrere Seiten.
## Installation
```bash
# 1. Deployment (erzeugt app/config.local.php aus credentials.txt)
./tools/deploy_app.sh # oder --dry-run
# 2. Im Browser öffnen
https://zauberturm.de/westreiche_website/install.php?token=<INSTALL_TOKEN>
```
Der Installer legt Tabellen, Zauber-/Fertigkeitengrundlage und das erste
Admin-Konto an. Danach kann `install.php` stehen bleiben – bei vorhandenen
Konten zeigt es nur noch einen Hinweis.
### Einladungen per E-Mail (SMTP)
`app/mailer.php` ist ein eigener kleiner SMTP-Client (kein Composer): STARTTLS
auf 587 oder SSL auf 465, AUTH PLAIN/LOGIN, Textmails UTF-8-kodiert. Die Werte
kommen aus `credentials.txt` (`MAIL_HOST`, `MAIL_PORT`, `MAIL_SECURE`,
`MAIL_USER`, `MAIL_PASSWORD`, `MAIL_FROM`, `MAIL_FROM_NAME`) und landen beim
Deployment im Abschnitt `'mail'` von `app/config.local.php`.
- Fehlt `MAIL_*` (oder `MAIL_PASSWORD`), gilt der Versand als nicht
eingerichtet: Einladungslinks werden wie bisher nur angezeigt.
- `MAIL_HOST` muss ein Name sein, der im Server-Zertifikat steht – bei Hetzner
also `www19.your-server.de`; `mail.zauberturm.de` zeigt zwar auf denselben
Server, passt aber nicht zum Zertifikat (`*.your-server.de`).
- Fehler landen per `error_log` in `storage/logs/php.log`; die Admin-Maske
meldet dann „Versand fehlgeschlagen – Link bitte kopieren“.
## Lokal entwickeln
```bash
cp app/config.example.php app/config.local.php # DB-Zugang eintragen
php -S 127.0.0.1:8099 -t . tools/router.php
# http://127.0.0.1:8099/install.php?token=<install_token>
```
## Datenmodell
| Tabelle | Zweck |
|---|---|
| `users` | Konten (Benutzername/E-Mail, Rolle, Status, `auth_epoch`) |
| `user_invites` | Einladungstokens (nur SHA-256-Hash) |
| `auth_tokens` | „Angemeldet bleiben“ (Selector/Validator) |
| `login_attempts` | Ratenbegrenzung je IP und Konto |
| `characters` | Charakterbogen-Basisdaten |
| `skills`, `character_skills` | Fertigkeiten-Katalog und Zuordnung |
| `spells`, `character_spells` | Zauber/Liturgien-Katalog und Zuordnung |
| `character_items` | Inventar |
| `weapons`, `armors` | Waffen- und Rüstungskatalog (Seed: `sql/seed_equipment.sql`) |
| `character_weapons`, `character_armors` | geführte Waffen und Rüstungsteile |
Porträts liegen als Datei in `uploads/portraits/` (gitignored); die Spalte
`characters.portrait` hält nur den relativen Pfad.
Sprache und Zeit: Zeitstempel in UTC, Anzeige in Europe/Berlin.
## Kataloge pflegen
Der Zauberkatalog wird aus dem Vault erzeugt:
```bash
python3 ../tools/build_spell_seed.py # schreibt sql/seed_spells.sql
```
Nach neuen Zauberdateien im Vault also den Seed neu bauen und die Datei
hochladen; der Installer führt sie bei einer Neuinstallation aus.
Der Seed schreibt mit `INSERT … ON DUPLICATE KEY UPDATE`, aktualisiert also
bestehende Zeilen (Kurztext, Dauer, Reichweite, Klassen und den vollständigen
Regeltext `body` aus „Wirkung“ + „Regelhinweisen“). Nach einem Vault-Update
also einfach `seed_spells.sql` hochladen und einmal einspielen – z. B.
```bash
.venv/bin/python tools/build_spell_seed.py # im Repo-Wurzelverzeichnis
```
Schema-Erweiterungen für **bestehende** Installationen stehen in
`app/migrations.php` (`WS_MIGRATIONS`); sie laufen beim ersten `db()`-Aufruf
automatisch und werden in `schema_migrations` vermerkt. Neue Änderung immer
hinten mit neuer Versionsnummer anhängen.
Fertigkeiten pflegt der Spielleiter direkt unter *Leitung → Fertigkeiten*.
## Sicherheit
- Passwörter mit Argon2id (Fallback bcrypt), Rehash beim Login.
- CSRF-Token in jedem Formular, Sessions mit `use_strict_mode` und
SameSite=Lax, Session-Epoch-Erhöhung bei Passwortwechsel.
- `app/`, `views/`, `sql/` und `storage/` per `.htaccess` gesperrt; in
`uploads/` ist die PHP-Ausführung abgeschaltet (nur Bilder werden
ausgeliefert);
`config.local.php` liegt nur auf dem Server (in `.gitignore`).
- CSP ohne externe Quellen, `X-Robots-Tag: noindex` (geschlossene Runde).