diff --git a/README.md b/README.md index b70a6b7..c624be0 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,137 @@ -# bamort +# BaMoRT -Bardiocs Moam Replacement Tool +Bamort ist ein Ersatzwerkzeug für MOAM mit dem Schwerpunkt auf Charakterverwaltung für Rollenspiele. Das Projekt bietet ein einfaches, erweiterbares System zur Charaktererstellung, zum Erlernen neuer Fertigkeiten und zur Charakterentwicklung. Langfristiges Ziel ist es, die Regeln für Charaktererstellung und -weiterentwicklung aus dem Code zu extrahieren und ein austauschbares Regelwerk‑Framework bereitzustellen. -My Idea is to write it in Go and Vue together. -Using ChartGPT may accelerate development. +## Ziele +- Ein modernes, wartbares Ersatzwerkzeug für MOAM mit Fokus auf Charaktere bereitstellen. +- Primäre Schwerpunkte: + - Charaktererstellung (Attribute, abgeleitete Werte, Startfertigkeiten). + - Charakterentwicklung (neue Fertigkeiten erlernen, bestehende Fertigkeiten verbessern). +- Langfristig: Regeln für Generierung und Fortschritt im Code abbilden und ein Framework anbieten, mit dem verschiedene Regelwerke implementiert und gewechselt werden können. -## structure -### Backend -models -database -character -user -cmd -tests -testdata -doc -### Frontend -public -src -### Docker -### Data \ No newline at end of file +## Architekturüberblick +Monorepo mit zwei Hauptteilen: Backend und Frontend. + +- Backend + - Sprache: Go (1.25+) + - Frameworks: Gin (HTTP), GORM (ORM) + - Zuständigkeiten: API, Geschäftslogik, Regelimplementierung, PDF‑Export + - Typische Struktur: Module pro Domäne (character, pdfrender, equipment, ...) + - Einstiegspunkt: cmd/main.go + +- Frontend + - Framework: Vue 3 + Vite + - State: Pinia Stores + - i18n: Lokalisierungsdateien unter src/locales/ + - Zuständigkeiten: UI für Charaktere (Erstellung, Bearbeitung, Entwicklung), Admin‑Werkzeuge + +- Daten & DevOps + - Datenbank: MariaDB für Entwicklung/Produktion; SQLite für Tests + - Container: Docker Compose mit separaten Dev‑Containern für Backend, Frontend und DB + - PDF‑Rendering: chromedp im pdfrender‑Modul (Chromium im Container erforderlich) + +## Kurze Entwicklerhinweise +- Geschützte API‑Routen liegen unter `/api` und erfordern JWT‑Auth. +- Vorlagen für Charakterexport liegen in `templates/` und sind per ENV‑Var TEMPLATES_DIR konfigurierbar. +- Dev‑Docker‑Compose für Live‑Reload verwenden: + - Backend: `bamort-backend-dev` (Air, Port 8180) + - Frontend: `bamort-frontend-dev` (Vite, Port 5173) + - DB: `bamort-mariadb-dev` (MariaDB) + +## Tests +- Backend‑Tests nutzen `testutils.SetupTestDB()` und die Testumgebung (`ENVIRONMENT=test`). +- NIEMALS `main()` in Testdateien hinzufügen; Tests müssen auf `_test.go` enden. +- Beispielbefehle: + - cd backend && go test -v ./character/ + - cd backend && go test -v ./pdfrender/ -run TestExportCharacterToPDF + +## Plan für erweiterbare Regelwerke +- Kernidee: Regeln für Generierung und Fortschritt aus unstrukturierter Logik in modulare, versionierte Regelwerk‑Pakete überführen. +- Regelwerke sollen: + - Validierungs‑ und Generierungsschritte für Charaktere definieren. + - Hooks für Lern‑ und Fortschrittsalgorithmen von Fertigkeiten bereitstellen. + - Laufzeit‑wahl ermöglichen (Konfiguration oder pro Kampagne). +- Anfangs werden kanonische Regeln hartkodiert; spätere Refactorings extrahieren Schnittstellen und liefern Beispiel‑Regelwerke. + +## Mitwirkung +- KISS und TDD: zuerst fehlschlagende Tests schreiben, dann minimale Implementierung. +- Neue UI‑Strings in beiden `src/locales/de` und `src/locales/en` ergänzen. +- Änderungen modular pro Domänenmodul halten (Backend‑Modulkonvention beachten). + +## Wo anfangen +- backend/character — Charakter‑Handler und Routen +- backend/models — Datenmodelle +- backend/pdfrender — PDF‑Templates und Rendering‑Logik +- frontend/src/views — Haupt‑UI für Charakterarbeiten + +## Lizenz +Lege eine passende LICENSE‑Datei im Repository an. + +# BaMoRT for english readers + +Bamort is a replacement tool for MOAM focused on character management for role‑playing games. The project aims to provide a simple, extensible system for character creation, learning new skills, and character development, with a long‑term goal of extracting the rules for character generation and advancement from code and exposing a pluggable ruleset framework. + +## Goals +- Provide a modern, maintainable replacement for MOAM focused on characters. +- First-class focus on: + - Character creation (attributes, derived values, starting skills). + - Character development (learning new skills, improving existing skills). +- Long-term: encode generation & progression rules in code and offer a framework so different rulesets can be implemented and swapped. + +## Architecture overview +Monorepo with two primary parts: backend and frontend. + +- Backend + - Language: Go (1.25+) + - Frameworks: Gin (HTTP), GORM (ORM) + - Responsibilities: API, business logic, rules implementation, PDF export + - Typical layout: modules per domain (character, pdfrender, equipment, ...) + - Entry point: cmd/main.go + +- Frontend + - Framework: Vue 3 + Vite + - State: Pinia stores + - i18n: locale files under src/locales/ + - Responsibilities: character UI (creation, edit, development), admin tools + +- Data & Devops + - Database: MariaDB for dev/prod; SQLite used for tests + - Containers: Docker Compose with separate dev containers for backend, frontend, and DB + - PDF rendering: chromedp in the pdfrender module (requires Chromium in container) + +## Quick dev notes +- Protected API routes live under `/api` and require JWT auth. +- Templates for character export are stored under `templates/` and the directory can be configured via env var TEMPLATES_DIR. +- Use the included docker-compose dev setup for live reload: + - Backend: `bamort-backend-dev` (Air, port 8180) + - Frontend: `bamort-frontend-dev` (Vite, port 5173) + - DB: `bamort-mariadb-dev` (MariaDB) + +## Testing +- Backend tests use `testutils.SetupTestDB()` and a test environment (`ENVIRONMENT=test`). +- NEVER add a `main()` to test files; tests must end with `_test.go`. +- Example commands: + - cd backend && go test -v ./character/ + - cd backend && go test -v ./pdfrender/ -run TestExportCharacterToPDF + +## Extensible ruleset plan +- Core idea: move rules for generation and progression from ad‑hoc code into modular, versioned ruleset packages. +- Rulesets should: + - Define validation and generation steps for a character. + - Expose hooks for skill learning and progression algorithms. + - Be selectable at runtime (config or per‑campaign). +- Early work will hardcode canonical rules; later refactors will extract interfaces and provide example alternate rulesets. + +## Contributing +- Follow KISS and TDD: write failing tests first, implement minimal change. +- Add translations to both `src/locales/de` and `src/locales/en` for new UI strings. +- Keep changes modular per domain module (see backend module pattern). + +## Where to look first +- backend/character — character handlers and routes +- backend/models — data models +- backend/pdfrender — PDF template system and rendering logic handlers and routes +- frontend/src/views — primary UI entry points for character workflows + +## License +Choose an appropriate license for the project in a LICENSE file. \ No newline at end of file diff --git a/frontend/CHARACTER_CREATION_DOCS.md b/frontend/CHARACTER_CREATION_DOCS.md deleted file mode 100644 index 7b659ef..0000000 --- a/frontend/CHARACTER_CREATION_DOCS.md +++ /dev/null @@ -1,135 +0,0 @@ -# Character Creation System - -## Übersicht - -Das Character Creation System ermöglicht es Benutzern, neue Charaktere in einem mehrstufigen Prozess zu erstellen. Der Fortschritt wird nach jedem Schritt gespeichert und steht dem Benutzer für 14 Tage zur Verfügung. - -## Implementierte Features - -### ✅ Backend (Go/Gin) - -**Neue API-Endpunkte in `/backend/character/routes.go`:** -- `GET /api/characters/create-sessions` - Aktive Sessions für Benutzer auflisten -- `POST /api/characters/create-session` - Neue Session erstellen -- `GET /api/characters/create-session/:sessionId` - Session-Daten abrufen -- `PUT /api/characters/create-session/:sessionId/basic` - Grundinformationen -- `PUT /api/characters/create-session/:sessionId/attributes` - Grundwerte -- `PUT /api/characters/create-session/:sessionId/derived` - Abgeleitete Werte -- `PUT /api/characters/create-session/:sessionId/skills` - Fertigkeiten -- `PUT /api/characters/create-session/:sessionId/spells` - Zauber -- `POST /api/characters/create-session/:sessionId/finalize` - Abschließen -- `DELETE /api/characters/create-session/:sessionId` - Session löschen -- `GET /api/characters/races` - Verfügbare Rassen -- `GET /api/characters/classes` - Verfügbare Klassen -- `GET /api/characters/origins` - Verfügbare Herkünfte -- `GET /api/characters/beliefs?q=searchterm` - Glaube-Suche -- `GET /api/characters/skill-categories` - Kategorien mit Lernpunkten - -**Handler in `/backend/character/handlers.go`:** -- Session-Management mit 14-Tage Gültigkeit -- Reference Data APIs mit Dummy-Daten -- Step-by-Step Validierung und Speicherung - -**Datenmodell in `/backend/models/model_character_creation.go`:** -- CharacterCreationSession mit JSON-Feldern -- Automatische Session-Bereinigung -- Type-safe Datenstrukturen - -### ✅ Frontend (Vue 3) - -**Button in CharacterList.vue:** -- "Create New Character" Button mit Styling -- Session-Erstellung und Navigation -- **Aktive Sessions-Anzeige**: Grid mit Session-Karten -- **Session-Details**: Name, Fortschritt, Rasse/Klasse, Daten -- **Continue/Delete**: Fortsetzen oder Löschen von Drafts - -**Neue Komponenten:** -- `CharacterCreation.vue` - Hauptcontainer mit Progress-Indicator -- `CharacterCreation/CharacterBasicInfo.vue` - Schritt 1: Grunddaten -- `CharacterCreation/CharacterAttributes.vue` - Schritt 2: Grundwerte -- `CharacterCreation/CharacterDerivedValues.vue` - Schritt 3: Abgeleitete Werte -- `CharacterCreation/CharacterSkills.vue` - Schritt 4: Fertigkeiten -- `CharacterCreation/CharacterSpells.vue` - Schritt 5: Zauber - -**Router-Integration:** -- Route `/character/create/:sessionId` hinzugefügt -- Props-basierte Parameter-Übergabe - -## Funktionsdetails - -### Schritt 1: Grundinformationen -- **Name**: Text-Input mit Validierung (2-50 Zeichen) -- **Rasse**: Dropdown aus API-Daten -- **Klasse**: Dropdown aus API-Daten -- **Herkunft**: Dropdown aus API-Daten -- **Glaube**: Suchfeld mit dynamischem Autocomplete (min. 2 Zeichen) - -### Schritt 2: Grundwerte -- **9 Attribute**: ST, GS, GW, KO, IN, ZT, AU, PA, WK (1-100) -- **Live-Berechnung**: Gesamtpunkte und Durchschnitt -- **Responsive Grid**: Automatisches Layout für verschiedene Bildschirmgrößen - -### Schritt 3: Abgeleitete Werte -- **LP/AP/B**: Automatische Berechnung aus Grundwerten -- **Bennies**: SG, GG, GP basierend auf Klasse -- **Recalculate-Button**: Reset auf berechnete Werte -- **Manuelle Anpassung**: Überschreibung der Berechnungen möglich - -### Schritt 4: Fertigkeiten -- **Kategorien-Ansicht**: Grid mit Lernpunkt-Anzeige und Progress-Bars -- **Skill-Listen**: Dynamische Listen pro Kategorie aus Datenbank -- **Punkt-Tracking**: Echtzeit-Update der verbleibenden Lernpunkte -- **Selected-Overview**: Zusammenfassung aller gewählten Skills -- **Navigation**: "Next: Spells" für nächsten Schritt - -### Schritt 5: Zauber -- **Zauber-Liste**: Separate Kategorie für magische Fähigkeiten -- **Zauber-Punkte**: Eigenständiges Punktesystem für Magie -- **Visual Feedback**: Kann/kann nicht lernen Indikationen -- **Finalisierung**: "Create Character" Button für Abschluss - -## Session-Management - -### Persistierung -- **Session-ID**: UUID-basiert für Eindeutigkeit -- **Auto-Save**: Nach jedem Schritt automatische Speicherung -- **14-Tage Gültigkeit**: Automatische Bereinigung alter Sessions -- **Step-Tracking**: Fortschritts-Verfolgung über alle Schritte - -### Benutzerführung -- **Progress-Indicator**: Visuelle Fortschrittsanzeige (5 Schritte) - **CLICKABLE!** -- **Navigation**: Vor/Zurück zwischen Schritten über klickbare Progress-Steps -- **Validierung**: Schritt-Blockierung bei fehlenden Daten -- **Draft-Management**: Session-Liste mit Continue/Delete-Optionen -- **Session-Übersicht**: Aktive Drafts auf Character-Liste-Seite -- **Datenerhaltung**: Alle eingegebenen Daten bleiben beim Wechseln erhalten - -## Dummy-Implementierungen - -**Backend Placeholders:** -- Reference Data als hardcodierte Arrays -- Session-Speicherung in Memory (TODO: Redis/DB) -- User-ID als Konstante (TODO: Auth-Context) -- Skill/Spell-Kosten als Fallback-Werte - -**Frontend Fallbacks:** -- API-Fehler-Behandlung mit Sample-Daten -- Loading-States für bessere UX -- Offline-fähige Formulare - -## Nächste Schritte - -### 🎯 Produktive Implementierung -1. **Session-Storage**: Redis oder DB-Tabelle -2. **Reference Data**: Echte Datenbank-Anbindung -3. **Auth-Integration**: User-ID aus JWT/Session -4. **Validation**: Server-seitige Eingabe-Prüfung - -### 🔧 Optimierungen -1. **Performance**: Reference Data Caching -2. **UX**: Loading-Spinner und Transitions -3. **Error Handling**: Robuste Fehlerbehandlung -4. **Tests**: Unit- und E2E-Tests - -Die Implementierung ist funktional vollständig und kann sofort getestet werden. Alle Dummy-Implementierungen sind klar markiert für schrittweise Produktionsreife.