feat: AI_INSTRUCTIONS.md und package-files hinzufügen

2026-05-08 10:49:18 +02:00
parent ddaf5839a5
commit 6f4f7fcf8d
3 changed files with 1431 additions and 0 deletions
@@ -0,0 +1,152 @@
+# 🏰 Der letzte Auftrag – AI-Befehle
+
+## Projektbeschreibung
+
+"Der letzte Auftrag" ist ein interaktives Brautabschied-Spiel (Heldenspiel/Drill) als Web-App.
+Der Bräutigam (der "Held") muss 8 Quests absolvieren, um alle Besitztümer für die Braut zu erbeuten.
+
+## Architektur
+
+- **Frontend:** Single-page HTML (CSS + Vanilla JS), keine Frameworks
+- **Backend:** Node.js/Express auf Port 8082
+- **Datenbank:** SQLite (better-sqlite3), Dateiname `data.db`
+- **Deployment:** systemd Service auf 192.168.0.187, nginx Reverse Proxy
+
+## API-Endpunkte
+
+### Game State
+```
+GET    /api/game          – Full game state + spieler + notes + stats
+POST   /api/game/start    – {"name": "Spielname"} – Spiel starten
+POST   /api/game/reset    – Alles zurücksetzen
+POST   /api/game/save-state – {"items":[...], "drinks": N, "quests":[...]} – Zustand speichern
+POST   /api/game/drink    – {"amount": ±N} – Trinken hinzufügen/abziehen
+POST   /api/game/drink/reset – Null trinken
+POST   /api/game/toggle-item – {"index": 0-7} – Inventar-Toggle
+POST   /api/game/toggle-quest – {"index": 0-7} – Quest-Toggle
+```
+
+### Spieler (Participants)
+```
+GET    /api/spieler       – Alle Spieler
+POST   /api/spieler       – {"name": "...","rolle": "...","quest_id": N|null}
+PUT    /api/spieler/:id   – {"rolle": "...","quest_id": N|null}
+DELETE /api/spieler/:id   – Spieler entfernen
+```
+
+### Notes
+```
+GET    /api/game (im state.notes) – Alle Notizen
+POST   /api/notes         – {"body": "Text"}
+```
+
+### Stats
+```
+GET    /api/game/stats    – {collected, total, questsDone, questsTotal, drinks, gameName, spielerCount, spieler}
+```
+
+## Rolen-System
+
+| Rolle | Code | Bedeutung |
+|-------|------|-----------|
+| Held | `held` | Der Bräutigam – löst alle Quests |
+| Spielleiter | `spielleiter` | Organisator, kennt alle Aufgaben |
+| Hüter | `hüter` | Bewacht ein Besitztum |
+| Ratsmitglied | `ratsmitglied` | Erfahrener RPG-Spieler |
+| Einsteiger | `einsteiger` | Tabletop-Neuling |
+| Gast | `gast` | Schaut zu, trinkt mit |
+
+## Quest-System
+
+8 Quests mit 3 Schwierigkeitsstufen:
+- **EINSTEIGER** (0-3): Brief, Ring, Schlüssel, Blume
+- **MITTEL** (4-5): Foto, Schuh
+- **HERAUSFORDERUNG** (6-7): Maskottchen, Urkunde
+
+Jede Quest hat: id, badge, badgeLabel, name, holder, item, desc, success, fail, details
+
+## Frontend-Struktur
+
+```
+index.html (Single File)
+├── Lines 1-1257: HTML-Struktur + CSS (NICHT ÄNDERN!)
+└── Lines 1258+: JavaScript (API-basiert)
+    ├── PART 1-2: API-Helpers, State-Sync, Quest-Daten
+    ├── PART 3-6: UI-Funktionen (Stars, Tabs, Quests, Items, Drinks, Status)
+    ├── PART 7: Würfelfunktionen (W4, W6, W8, W10, W12, W20, W100)
+    └── PART 8: Spieler-Management (API-Version)
+```
+
+## Backend-Struktur
+
+```
+server/
+├── server.js     – Express-Server mit SQLite-Backend
+├── package.json  – Abhängigkeiten (express, better-sqlite3)
+├── data.db       – SQLite-Datenbank (wird erstellt)
+└── node_modules/
+```
+
+## Datenbank-Schema
+
+```sql
+CREATE TABLE state (key TEXT PRIMARY KEY, value TEXT);
+CREATE TABLE spieler (id INTEGER PRIMARY KEY, name TEXT, rolle TEXT, quest_id INTEGER, created_at DATETIME);
+CREATE TABLE notes (id INTEGER PRIMARY KEY, body TEXT, created_at DATETIME);
+CREATE TABLE drinks_log (id INTEGER PRIMARY KEY, amount INTEGER, note TEXT, created_at DATETIME);
+```
+
+## Deployment
+
+### systemd Service
+```ini
+[Unit]
+Description=Der letzte Auftrag Server
+After=network.target
+
+[Service]
+Type=simple
+User=www-data
+WorkingDirectory=/opt/der_letzte_auftrag/server
+ExecStart=/usr/bin/node server.js
+Restart=on-failure
+Environment=NODE_ENV=production
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### Nginx Konfiguration
+```nginx
+location / {
+    proxy_pass http://127.0.0.1:8082;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_read_timeout 30s;
+    proxy_send_timeout 30s;
+}
+```
+
+## AI-Anweisungen
+
+### Bei Änderungen am Frontend:
+1. ÄNDERE NIE die HTML-Struktur (Zeilen 1-1257)
+2. ÄNDERE NIE das CSS
+3. Nutze IMMER die API-Helpers (apiGet/apiPost/apiPut/apiDelete)
+4. Lokal State nach API-Call: syncState() und refreshUI()
+5. Keine localStorage mehr – alles geht über die API
+
+### Bei Änderungen am Backend:
+1. Neue Endpunkte: Immer PUT für Updates, DELETE für Löschungen, POST für Creates
+2. Datenbanken: Immer `initState()` aufrufen vor state-Leseoperationen
+3. Fehlerbehandlung: Immer auf null/undefined prüfen
+4. WAL-Modus aktiviert für bessere Concurrent-Performance
+
+### Deployment-Schritte:
+1. `git push origin main`
+2. SSH zum Server (192.168.0.187): `git pull`
+3. `cd server && npm install`
+4. `systemctl restart der-letzte-auftrag`
+5. Test: `curl http://localhost:8082/api/game`
@@ -0,0 +1,13 @@
+{
+  "name": "der-letzte-auftrag",
+  "version": "2.0.0",
+  "description": "Interaktive JGA-Quest-App mit Synchronisation",
+  "main": "server.js",
+  "scripts": {
+    "start": "node server.js"
+  },
+  "dependencies": {
+    "express": "^4.21.2",
+    "better-sqlite3": "^11.8.1"
+  }
+}