# Dimension47 - TTRPG Campaign Management Platform

## Projekt-Philosophie

**Qualität vor Geschwindigkeit**: Es ist egal, wie lange die Implementierung dauert - das System soll am Ende gut funktionieren. Keine Shortcuts oder Quick-Fixes, die später Probleme verursachen.

**Lieber langsam und richtig**: Immer den sauberen Weg wählen, auch wenn er länger dauert. Beispiele:
- Prisma Migrations statt `db push` verwenden
- Daten in Datenbank statt direkt aus JSON-Dateien lesen
- Proper Error Handling statt try/catch mit console.log
- TypeScript strict mode, keine `any` Types

## Architektur-Entscheidungen

### Daten-Management
- **Equipment/Items in Datenbank**: Alle Pathfinder 2e Daten (Waffen, Rüstungen, Ausrüstung, Zauber, Talente) werden in die PostgreSQL-Datenbank importiert, NICHT direkt aus JSON-Dateien gelesen.
- **Prisma Seed Scripts**: JSON-Dateien werden via `prisma db seed` in die Datenbank importiert.
- **Übersetzungen gecacht**: Deutsche Übersetzungen werden on-demand via Claude API generiert und in der Translation-Tabelle gespeichert.

### Vorteile des Database-Ansatzes
- Bessere Such- und Filtermöglichkeiten
- Konsistente Datenstruktur
- Eigene Items können hinzugefügt werden
- Relationale Verknüpfungen möglich
- Performance durch Indizes

## Tech Stack

### Frontend
- React 19 + TypeScript
- Vite als Build Tool
- Tailwind CSS v4
- shadcn/ui Komponenten (selbst gebaut)
- Zustand für Client State

### Backend
- NestJS mit TypeScript
- Prisma ORM
- PostgreSQL
- JWT Authentication
- Socket.io für WebSockets

## Ordnerstruktur

```
dimension47/
├── client/                 # React Frontend
│   ├── src/
│   │   ├── app/           # App-Config, Router
│   │   ├── features/      # Feature-Module (auth, campaigns, characters, etc.)
│   │   │   ├── auth/components/
│   │   │   │   ├── login-page.tsx            # Login mit Animationen
│   │   │   │   └── register-page.tsx         # Registrierung
│   │   │   └── characters/
│   │   │       ├── components/
│   │   │       │   ├── character-sheet-page.tsx  # Hauptseite mit Tabs
│   │   │       │   ├── hp-control.tsx            # HP-Management Komponente
│   │   │       │   ├── add-condition-modal.tsx   # Zustand hinzufügen
│   │   │       │   ├── add-item-modal.tsx        # Item aus DB hinzufügen
│   │   │       │   ├── actions-tab.tsx           # Aktionen-Tab
│   │   │       │   ├── alchemy-tab.tsx           # Alchemie-Tab
│   │   │       │   └── rest-modal.tsx            # Rasten-Modal
│   │   │       └── utils/
│   │   │           └── export-character-html.ts  # HTML-Export Funktion
│   │   ├── shared/        # Geteilte Komponenten, Hooks, Types
│   │   │   └── hooks/
│   │   │       └── use-character-socket.ts   # WebSocket Hook für Echtzeit-Sync
│   │   └── assets/
│   └── public/            # Statische Dateien, JSON-Datenbanken
│
└── server/                 # NestJS Backend
    ├── src/
    │   ├── modules/       # Feature-Module
    │   │   ├── auth/      # Authentifizierung
    │   │   ├── campaigns/ # Kampagnenverwaltung
    │   │   ├── characters/# Charakterverwaltung
    │   │   │   ├── characters.gateway.ts  # WebSocket Gateway
    │   │   │   └── alchemy.service.ts     # Alchemie-System Service
    │   │   └── equipment/ # Equipment-Datenbank
    │   ├── common/        # Shared Utilities
    │   └── prisma/        # Prisma Service
    └── prisma/
        ├── schema.prisma  # Datenbank-Schema
        ├── migrations/    # Prisma Migrations
        ├── seed.ts        # Basis-Seed
        ├── seed-equipment.ts # Equipment-Import (5.482 Items)
        └── data/          # JSON-Quelldaten für Equipment
```

## Implementierte Features

### Auth
- JWT-basierte Authentifizierung
- Login/Register/Logout
- Rollen: ADMIN, GM, PLAYER
- **"Anmeldung speichern"** Funktion (localStorage vs sessionStorage)
- **Animierter Login-Screen**:
  - Zweistufiger Flow: Splash → Formular
  - Animierter Sternenhintergrund mit schwebenden Orbs
  - "DIMENSION 47" Titel mit Buchstaben-Animation und Glow-Effekt
  - Logo mit Tap-Glow-Effekt
  - Gestaffelte Formular-Animationen (Komponente für Komponente)

### Kampagnen
- CRUD für Kampagnen
- Mitgliederverwaltung
- GM-Berechtigungen

### Charaktere
- Pathbuilder 2e Import
- HP-Management (mobile-optimiert, Schaden/Heilung/Direkt)
- Zustände (Conditions) mit PF2e-Datenbank
- Fertigkeiten mit deutschen Namen
- Rettungswürfe
- **Inventar-System (komplett)**:
  - Vollständige Equipment-Datenbank (5.482 Items)
  - Item-Suche mit Kategoriefilter und Pagination
  - Bulk-Tracking mit Belastungs-Anzeige
  - Ausrüstungsstatus (angelegt/abgelegt/investiert)
  - Quantity-Management
  - Item-Details mit Eigenschaften, Schaden, etc.
  - Benutzerdefinierte Notizen pro Item
- **Talente-Tab (komplett)**:
  - Alle Charaktertalente aus Pathbuilder-Import
  - Kategorisiert nach Quelle (Klasse, Abstammung, Allgemein, Fertigkeit, Bonus, Archetyp)
  - Einklappbare Kategorien
  - Talentdetails mit Beschreibung und Voraussetzungen
- **Aktionen-Tab** mit PF2e-Aktionsdatenbank (99 Aktionen)
  - Kategorien: Allgemein, Kampf, Bewegung, Interaktion, Spezial
  - Einklappbare Kategorien (standardmäßig eingeklappt)
  - Aktionstyp-Icons (Aktion, Reaktion, Freie Aktion, etc.)
  - Suchfunktion
- **WebSocket Real-Time Sync** für:
  - HP (aktuell, temporär, max)
  - Zustände (hinzufügen, entfernen, aktualisieren)
  - Inventar (Items hinzufügen, entfernen, aktualisieren)
  - Ausrüstungsstatus (angelegt/abgelegt)
  - Geld (Credits)
  - Level
  - Alchemie (Phiolen, Formeln, vorbereitete Items)
- **Alchemie-Tab (komplett)**:
  - Vielseitige Phiolen mit Tracker
  - Formelbuch mit allen bekannten Formeln
  - Tägliche Vorbereitung (Advanced Alchemy)
  - Schnelle Alchemie (Quick Alchemy)
  - Handwerkliche Alchemie (Craft Alchemy)
  - Forschungsgebiete (Bomber, Chirurg, Mutageniker, Toxikologe)
  - Infundierte Items mit Effekt-Anzeige und Schadenswerten
- **Rest-System**:
  - HP-Heilung basierend auf CON-Mod × Level
  - Zustands-Management (Erschöpft entfernt, Verdammt/Entkräftet reduziert)
  - Ressourcen-Reset (Zauberplätze, Fokuspunkte)
  - Alchemie-Reset (infundierte Items verfallen, Phiolen aufgefüllt)
- **Status-Tab Erweiterungen**:
  - Wahrnehmung mit korrekter PF2e-Berechnung
  - Geschwindigkeit
  - Rüstungsklasse mit Übungsstufe
  - Rettungswürfe mit Übungsstufen
- **HTML-Export**:
  - Vollständiger Charakterbogen als druckbare HTML-Datei
  - Alle Attribute, Fertigkeiten, Talente, Ausrüstung
  - Zauber und Alchemie (wenn vorhanden)

### Noch zu implementieren (Character Screen)
- **Level-Up System**: Stufenaufstieg mit Attributs-, Talent- und Fertigkeitenwahl

### Equipment-Datenbank
- **5.482 Items** aus Pathfinder 2e importiert
- Waffen mit Schaden, Schadentyp, Reichweite, Eigenschaften
- Rüstungen mit RK, DEX-Cap, Penalties
- Verbrauchsgüter und allgemeine Ausrüstung
- Durchsuchbar nach Name, Kategorie, Level, Eigenschaften
- API-Endpunkte: `/equipment`, `/equipment/categories`, `/equipment/weapons`, etc.

## Design-Prinzipien

- **Mobile-First**: Touch-optimiert mit 44px+ Touch-Targets
- **Dark Mode**: Primärfarbe #c26dbc (Magenta)
- **Deutsch**: Alle UI-Texte auf Deutsch
- **Keine Emojis**: Nur Lucide Icons

## Environment-Variablen

### Server (`server/.env`)
```bash
PORT=5000                    # Server-Port
DATABASE_URL="postgresql://..." # PostgreSQL Connection String
JWT_SECRET="..."             # JWT Signing Key
ANTHROPIC_API_KEY="..."      # Claude API für Übersetzungen
```

### Client (`client/.env`)
```bash
VITE_API_URL=http://localhost:5000/api  # Muss mit Server PORT übereinstimmen
```

**Wichtig**: Die WebSocket-URL wird automatisch aus `VITE_API_URL` abgeleitet (ohne `/api` Suffix).

Beispiel-Dateien: `server/.env.example` und `client/.env.example`

## Entwicklung

```bash
# Backend starten (Port 5000, konfigurierbar via PORT in .env)
cd server && npm run start:dev

# Frontend starten (Port 5173)
cd client && npm run dev

# Prisma Migrations (IMMER Migrations verwenden, NIEMALS db push!)
cd server && npm run db:migrate:dev      # Neue Migration erstellen & anwenden
cd server && npm run db:migrate:deploy   # Migrations in Produktion anwenden
cd server && npm run db:migrate:status   # Status der Migrations prüfen
cd server && npm run db:migrate:reset    # DB zurücksetzen (Dev only!)

# Prisma Sonstiges
cd server && npm run db:studio           # DB Browser
cd server && npm run db:generate         # Prisma Client generieren
cd server && npm run db:seed             # Basis-Seed-Daten laden
cd server && npm run db:seed:equipment   # Equipment-Datenbank laden
```