Michess/Plan.md

Plan.md — MiChess Entwicklungsplan

---

Vision

MiChess ist eine selbst-gehostete Schachplattform für eine private Community, inspiriert von Lichess.org. Läuft als Docker-Container auf einer Synology/QNAP NAS, komplett ohne Cloud-Abhängigkeit.

---

Phase 1: Foundation (Basis)

1.1 Projekt-Setup

• chessu (MIT) als Basis klonen
• Brain.md & Plan.md erstellen
• Git remote auf https://git.mischlabs.de/MrDiderot/MiChess.git setzen
• Initaler Push (chessu-Basis + eigene Dateien)

1.2 Rebranding chessu → MiChess

• package.json Namen anpassen
• README durch MiChess-README ersetzen
• Alle Titel/Meta-Tags im Frontend ändern
• Logo-Platzhalter anpassen

1.3 Docker NAS-Deployment

• docker-compose.yml überarbeiten (michess-app, postgres, eigene Secrets)
• .env.example erstellen mit allen benötigten Variablen
• Stockfish in Docker-Image einbauen (apk add stockfish)
• Update-Script: scripts/update.sh (git pull + docker restart)
• Deployment-README schreiben (einziger Befehl für NAS)

---

Phase 2: Datenbank-Erweiterungen

2.1 Schema-Änderungen

-- User: Admin-Rolle hinzufügen
ALTER TABLE "user" ADD COLUMN role VARCHAR(16) DEFAULT 'user';

-- Freundschaftsanfragen
CREATE TABLE IF NOT EXISTS "friend_request" (
    id SERIAL PRIMARY KEY,
    from_id INT REFERENCES "user"(id) ON DELETE CASCADE,
    to_id INT REFERENCES "user"(id) ON DELETE CASCADE,
    status VARCHAR(16) DEFAULT 'pending', -- pending | accepted | rejected
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(from_id, to_id)
);

-- Freunde (bidirektional, normalisiert als kleinere_id + größere_id)
CREATE TABLE IF NOT EXISTS "friendship" (
    id SERIAL PRIMARY KEY,
    user_id_1 INT REFERENCES "user"(id) ON DELETE CASCADE,
    user_id_2 INT REFERENCES "user"(id) ON DELETE CASCADE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(user_id_1, user_id_2)
);

---

Phase 3: Stockfish AI-Integration

3.1 Backend

• stockfish npm-Paket als Server-Dependency
• server/src/controllers/stockfish.controller.ts — Stockfish-Prozess-Manager
• Schwierigkeitsgrade:

  Level	Name	Stockfish Skill	Depth
  1	Anfänger	0	1
  2	Leicht	3	3
  3	Mittel	8	5
  4	Fortgeschritten	14	10
  5	Experte	18	15
  6	Meister	20	20

• Socket-Events: ai:move, ai:game_start, ai:game_end

3.2 Frontend

• "Gegen KI spielen" Button auf Startseite
• Schwierigkeitsgrad-Auswahl Modal
• KI-Spielpartie-UI (keine zweite Socket-Session nötig, nur lokal)

---

Phase 4: Admin-Panel

4.1 Backend

• isAdmin Middleware für /v1/admin/*
• GET /v1/admin/users — alle Nutzer auflisten (paginiert)
• PATCH /v1/admin/users/:id — Nutzer sperren/entsperren, Rolle ändern
• DELETE /v1/admin/users/:id — Nutzer löschen
• POST /v1/admin/update — git pull + trigger restart
• GET /v1/admin/stats — Nutzerzahl, Spiele, etc.

4.2 Frontend

• /admin Route (nur für Admins sichtbar)
• Dashboard mit Statistiken
• Nutzertabelle mit Such-/Filterfunktion
• "Website aktualisieren" Button mit Bestätigung
• Nutzer sperren/entsperren/löschen

4.3 Erster Admin

• ADMIN_EMAIL env-Variable
• Beim Server-Start: wenn User mit dieser E-Mail existiert → Role = 'admin'
• Alternativ: ADMIN_SETUP_TOKEN für initiale Admin-Einrichtung

---

Phase 5: Freundessystem

5.1 Backend

• POST /v1/friends/request — Anfrage senden (via Username)
• GET /v1/friends/requests — eigene Anfragen (eingehend + ausgehend)
• PATCH /v1/friends/requests/:id — annehmen/ablehnen
• GET /v1/friends — eigene Freundesliste
• DELETE /v1/friends/:id — Freundschaft beenden
• GET /v1/users/search?q= — Nutzer suchen

5.2 Frontend

• Freundesliste im User-Profil
• "Freund hinzufügen" Button auf fremden Profilseiten
• Benachrichtigungs-Badge bei ausstehenden Anfragen
• "Freund herausfordern" → direktes Spiel erstellen

---

Phase 6: Registrierungs-Flow

Aktueller chessu-Flow:

name + email + password → Account erstellt

Gewünschter MiChess-Flow:

1. email + password → Account erstellt (noch kein Nutzername)
2. Weitergeleitet zu "Nutzername wählen" (einmalig, nicht änderbar)
3. Nutzername prüfen: verfügbar? gültig? → bestätigen
4. Account aktiv

• name Feld nullable machen in DB (bis Schritt 2)
• POST /v1/auth/choose-username Endpoint
• "Username wählen"-Seite im Frontend

---

Phase 7: Sonstige Verbesserungen

• Zeitkontrolle für Partien (Bullet/Blitz/Rapid/Classical)
• Rating-System (Elo) für Nutzer-vs-Nutzer
• Rematch-Funktion
• Spectator-Verbesserungen (Live-Zuschauer)
• Mobile-Optimierung

---

Deployment-Anleitung (Ziel-Zustand)

# Einmalige Erstinstallation auf der NAS:
git clone https://git.mischlabs.de/MrDiderot/MiChess.git michess
cd michess
cp .env.example .env
# .env anpassen (Passwörter, Admin-Email, etc.)
docker compose up -d

# Update (manuell oder per Admin-Panel):
./scripts/update.sh
# oder via Admin-Panel "Website aktualisieren" Button

---

Git-Strategie

• main — Production-Branch (immer deploybar)
• Features werden direkt auf main entwickelt (kleines Team)
• Issues aus git.mischlabs.de als Feature-Tracker
• Commit-Messages: feat:, fix:, admin:, docker:, ui: Prefixe

---

Prioritäten (Reihenfolge)

1. P0: Foundation + Docker + Git (läuft auf NAS)
2. P0: Stockfish AI (Kernfeature)
3. P1: Admin-Panel (Verwaltbarkeit)
4. P1: Freundessystem (Social)
5. P2: Registrierungs-Flow verfeinern
6. P3: Zeitkontrolle + Rating