der_letzte_auftrag/AI_INSTRUCTIONS.md

🏰 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

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

[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

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