From 6d7a5ba3488d658327844bfd0049861474b62881 Mon Sep 17 00:00:00 2001 From: Alexander Zielonka Date: Mon, 27 Apr 2026 09:24:08 +0200 Subject: [PATCH] docs: initialize project --- .planning/PROJECT.md | 139 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 .planning/PROJECT.md diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md new file mode 100644 index 0000000..32f5b05 --- /dev/null +++ b/.planning/PROJECT.md @@ -0,0 +1,139 @@ +# Dimension47 + +## What This Is + +Dimension47 ist eine selbst gehostete Web-App für Pathfinder-2e-Tischrunden auf Deutsch. Sie verwaltet Kampagnen, Charakterbögen mit komplettem PF2e-Regelumfang (HP, Zustände, Inventar, Talente, Aktionen, Alchemie) und stellt einen GM-Battle-Screen mit 3D-Druck-Tisch-Display bereit — alles in Echtzeit synchronisiert. Zielgruppe ist die eigene Spielgruppe, nicht die breite Öffentlichkeit. + +## Core Value + +Am Tisch funktioniert alles in Echtzeit und regelkonform: Spieler lesen ihren Charakterbogen am Handy, der GM steuert vom Laptop aus den Battle-Screen, der eingelassene Tisch-Display zeigt die Spielsicht — ohne Reibung, ohne falsche Werte, ohne Reload. + +## Requirements + +### Validated + + + +- ✓ JWT-Auth mit Rollen (ADMIN/GM/PLAYER), Login-Persistenz, animierter Login-Screen — existing +- ✓ Kampagnen-CRUD mit Mitgliederverwaltung und GM-Berechtigungen — existing +- ✓ Pathbuilder-2e-Import als Charakter-Erstellungspfad — existing +- ✓ HP-Management mit Schaden/Heilung/Direkt + Temp-HP, mobile-optimiert — existing +- ✓ Zustände (Conditions) mit PF2e-Datenbank, hinzufügen/entfernen/aktualisieren — existing +- ✓ Fertigkeiten mit deutschen Namen, Rettungswürfe, Wahrnehmung mit korrekter PF2e-Berechnung — existing +- ✓ Inventar mit 5.482-Item-Equipment-DB, Bulk-Tracking, Belastung, Equip-Status, benutzerdefinierte Notizen — existing +- ✓ Talente-Tab mit allen Charaktertalenten kategorisiert (Klasse/Abstammung/Allgemein/Fertigkeit/Bonus/Archetyp) — existing +- ✓ Aktionen-Tab mit 99 PF2e-Aktionen, Suche, Aktionstyp-Icons — existing +- ✓ Alchemie-Tab mit Phiolen, Formelbuch, Vorbereitung, Quick/Craft-Alchemy, Forschungsgebieten, infundierten Items — existing +- ✓ Rest-System mit HP-Heilung, Zustands-Reduktion, Ressourcen-Reset, Alchemie-Reset — existing +- ✓ HTML-Export des Charakterbogens — existing +- ✓ WebSocket-Sync (Socket.io) für HP, Zustände, Inventar, Equip-Status, Geld, Level, Alchemie — existing +- ✓ Battle-Screen MVP: Sessions, Map+Tokens mit Drag-Drop (GM), HP/Init pro Token, Round-Counter, WebSocket-Sync — existing +- ✓ GM-Library für Battle-Maps und NPC-Templates (Combatants) — existing +- ✓ Equipment-DB mit Kategorien-API und Such-Endpunkten — existing + +### Active + + + +**Level-Up-System (regelkonform PF2e)** +- [ ] Charakter levelt regelkonform auf nächste Stufe mit allen Wahlpfaden (Attribute Boosts, Klassentalente, Allgemeine Talente, Fertigkeitstalente, Skill-Increases, Klassenmerkmale, Archetyp-Optionen) +- [ ] Voraussetzungen werden validiert (z.B. Talent erfordert bestimmte Fertigkeitsstufe oder Vorgängertalent) +- [ ] Level-Up ist undo-bar bis bestätigt; bestätigtes Level-Up erzeugt nachvollziehbare Änderung in Charakterhistorie +- [ ] Stat-Recompute (HP-Max, Save-Boni, Skill-Boni, AC) folgt automatisch aus Level-Up-Wahlen + +**Mobile-First-PWA** +- [ ] App ist als PWA installierbar (Manifest, Icons, Splash, Service Worker) +- [ ] Charakterbogen, Inventar, Talente, Aktionen, Alchemie sind offline lesbar (Cache-First für gelesene Charaktere) +- [ ] Web-Push-Notifications für GM→Spieler-Pings (Würfelaufforderung, Battle-Turn-Alert, Custom-Nachrichten) +- [ ] Bestehende Charakter-Screens werden auf Mobile-First-Touch-Targets und Layout durchgegangen, wo nötig poliert + +**Battle-Screen-Ausbau (GM-Laptop + Tisch-Display)** +- [ ] Separater Display-Mode (read-only Player-View) auf eigener Route, optimiert für eingelassenen Tisch-Bildschirm — zeigt nur Map, Tokens, Initiative-Reihenfolge, Token-Status +- [ ] Initiative-Tracker als sortierte Liste mit „Wer ist dran"-Highlight, nicht nur Badges auf Tokens +- [ ] Effekte/Auren/Buffs/Debuffs pro Token (Modell + UI + Echtzeit-Sync) +- [ ] Token-Add/Remove als WebSocket-Event (heute nur Query-Invalidate) +- [ ] Touch-/Tablet-Steuerung am GM-Laptop ist nutzbar (kein Pflicht-Mobile, aber auch nicht kaputt) + +**Würfeln & Chat in Echtzeit** +- [ ] In-App-Würfler mit PF2e-Notation (z.B. `1d20+7`, Crit-Erkennung, Persistent Damage) +- [ ] Roll-Log pro Kampagne und pro Battle-Session, sichtbar für alle Teilnehmer +- [ ] In-Game-Chat pro Kampagne und Battle, Echtzeit, mit Roll-Einbettung + +**GM-Live-Tools** +- [ ] GM kann live HP/Conditions/Items/Geld bei Spieler-Charakteren setzen (über bestehendes WebSocket-Modell, neue GM-UI) +- [ ] GM kann gezielte Push-/Chat-Nachrichten an einzelne oder alle Spieler senden + +**Obsidian-Vault-Anbindung (Read-only Browser)** +- [ ] App liest Markdown aus selbst-gehostetem Vault-Endpoint (vermutlich eigener Server, Protokoll noch zu wählen) +- [ ] Vault-Browser in der App: Ordner-Navigation, Datei-Lesen, Suche +- [ ] Markdown-Rendering inkl. Wikilinks (klickbar zu anderer Note), eingebetteten Bildern, Code-Blöcken +- [ ] Vault-Inhalte sind auch offline lesbar (zuletzt gelesene Notes gecacht) + +### Out of Scope + +- **Bidirektionales Vault-Sync** — schreibender Zugriff in den Vault wurde bewusst auf später verschoben; reine Lese-App reicht für aktuelle Nutzung +- **Offline-Bearbeiten mit Sync-Queue** — kein Edit ohne Netz; Offline-Modus deckt nur Lesen ab. Konflikt-Logik wäre teuer und das Spiel passiert sowieso live am Tisch +- **Native iOS/Android-App über Capacitor o.ä.** — Web Push reicht; PWA-Installation ersetzt Native-App-Bedürfnis +- **Charakter-Erstellung von null in der App** — Pathbuilder-Import bleibt der Erstellungspfad; in-App-Erstellung wäre Doppelarbeit +- **Andere TTRPG-Systeme als PF2e** — Datenmodell und UI sind PF2e-spezifisch, kein Generalisierungs-Ziel +- **Öffentlicher Mehrmandanten-Betrieb** — App läuft für die eigene Gruppe selbst gehostet; kein Account-Onboarding-Flow, keine Marketing-Site +- **Presence/Awareness-Indikatoren** („wer ist online", „wer schaut wo hin") — wurde bewusst aus den geplanten WebSocket-Erweiterungen ausgeschlossen, weil Mehrwert klein und Komplexität hoch + +## Context + +**Bestehende Codebase:** Reife Brownfield-App. NestJS 11 + React 19 + Prisma 7 + PostgreSQL + Socket.io + Tailwind v4. TypeScript strict mode überall. Codebase ist gemappt unter `.planning/codebase/` (ARCHITECTURE.md, STACK.md, STRUCTURE.md, CONVENTIONS.md, INTEGRATIONS.md, CONCERNS.md, TESTING.md). + +**Domain-Spezifika:** +- PF2e ist regelseitig komplex (Action-Economy, drei Aktionen pro Runde, Proficiency-Stufen, Boost-Regeln alle 5 Level, Archetypen, Free Archetype). Equipment-DB hat 5.482 Items, Aktionen-DB hat 99 Einträge, deutsche Übersetzungen werden via Claude-API on-demand generiert und in Translation-Tabelle gecacht. +- Spielgruppe nutzt 3D-gedruckte Miniaturen auf einem in den Spieltisch eingelassenen Bildschirm. Battle-Screen muss zwei Sichten bedienen: GM-Steuerung (Laptop) und Tisch-Display (read-only Spielsicht). + +**Current state:** +- Battle-Screen ist heute nicht mobil benutzbar (fixe Sidebar-Layouts, Maus-Drag-Drop, kein Display-Mode). Bewusst gewollt — bleibt Laptop+Tisch-Bildschirm-Anwendung. +- Charakterbogen ist heute mobile-optimiert mit 44 px+ Touch-Targets. +- WebSocket-Infrastruktur ist solide — Erweiterungen folgen bestehendem Gateway-Pattern. + +**Philosophie (aus CLAUDE.md übernommen):** Qualität vor Geschwindigkeit. Keine Shortcuts. Prisma-Migrations statt `db push`. Daten in DB, nicht aus JSON. Proper Error Handling. Keine `any`-Types. Deutsch in der UI. Keine Emojis. + +## Constraints + +- **Tech-Stack**: NestJS 11 + React 19 + Prisma 7 + PostgreSQL + Socket.io + Tailwind v4 — gesetzt durch Bestand, kein Stack-Wechsel sinnvoll +- **Sprache**: Deutsche UI durchgehend — alle neuen Texte ebenfalls Deutsch +- **Design**: Mobile-First für alle nutzerseitigen Screens (Charakterbogen, Vault-Browser, Würfler, Chat); Battle-GM-Screen darf desktop-fokussiert bleiben; Tisch-Display ist eigener Layout-Modus +- **Daten-Persistenz**: Alle PF2e-Daten gehören in die DB (Prisma-Seeds aus JSON), nichts wird zur Laufzeit aus JSON-Dateien gelesen +- **Migrationen**: Schema-Änderungen ausschließlich über `prisma migrate dev`, niemals `db push` +- **Code-Qualität**: TypeScript strict, keine `any`-Types, kein Quick-Fix der später wehtut +- **Hosting-Modell**: Self-hosted für eigene Spielgruppe — keine Multi-Tenant-/SaaS-Anforderungen +- **Push-Plattform**: Web Push (Service-Worker-basiert), kein FCM/APNs-Native-Wrapper +- **Vault-Endpoint**: Selbst-gehosteter Endpoint (vermutlich auf eigenem Server) — konkretes Protokoll wird in der Vault-Phase entschieden, nicht jetzt + +## Key Decisions + +| Decision | Rationale | Outcome | +|----------|-----------|---------| +| Level-Up wird voll regelkonform implementiert (statt Re-Import-only) | Volle Kontrolle in der App, weniger Reibung am Tisch, validierte Werte | — Pending | +| PWA mit Web Push, kein Native-Wrapper | Funktioniert plattformübergreifend (Android-Chrome, iOS-Safari ab installierter PWA), kein Build-/Store-Aufwand | — Pending | +| Offline-Bearbeiten ist explizit raus, nur Offline-Lesen | Konflikt-Logik wäre teuer; Spielsessions sind online | — Pending | +| Battle-Screen bleibt Laptop+Tisch-Display, kein Pflicht-Mobile | Spielablauf am realen Tisch mit 3D-Minis braucht großen Screen | — Pending | +| Obsidian-Anbindung ist v1 nur lesend | Lesen deckt 100 % des aktuellen Bedarfs; Schreiben verdoppelt Komplexität | — Pending | +| Vault wird selbst-gehostet (statt Git-Repo / Cloud-Storage) | User hat eigenen Server; passt zum Self-Hosted-Charakter der App | — Pending | +| Keine Eile, Qualität zählt | Übernommen aus CLAUDE.md-Philosophie; bestimmt Phasen-Schnitt (lieber breite Phasen sauber als hektisch) | — Pending | + +## Evolution + +This document evolves at phase transitions and milestone boundaries. + +**After each phase transition** (via `/gsd-transition`): +1. Requirements invalidated? → Move to Out of Scope with reason +2. Requirements validated? → Move to Validated with phase reference +3. New requirements emerged? → Add to Active +4. Decisions to log? → Add to Key Decisions +5. "What This Is" still accurate? → Update if drifted + +**After each milestone** (via `/gsd-complete-milestone`): +1. Full review of all sections +2. Core Value check — still the right priority? +3. Audit Out of Scope — reasons still valid? +4. Update Context with current state + +--- +*Last updated: 2026-04-27 after initialization*