# 📘 Clan AI Operations Manual **Version:** 0.0.4.0 **Stand:** 2026-06-13 **Status:** Aktiv / Produktiv --- ## 📑 Inhaltsverzeichnis 1. [Zweck dieses Dokuments](#zweck-dieses-dokuments) 2. [Schnellstart für Mitglieder](#schnellstart-für-mitglieder) 3. [Admin-Workflows & Befehle](#admin-workflows--befehle) 4. [KI-Logik & Coaching-Prompting](#ki-logik--coaching-prompting) 5. [Troubleshooting & Fehlerbehebung](#troubleshooting--fehlerbehebung) 6. [Datenschutz & Identitätssicherheit](#datenschutz--identitätssicherheit) --- ## Zweck dieses Dokuments Dieses Handbuch dient als zentrale Referenz für Admins und aktive Mitglieder des Clans. Es dokumentiert: - Welche Commands existieren und wie sie sicher verwendet werden - Wie die KI entscheidet und warum sie manchmal so antwortet, wie sie antwortet - Workflows für Bewerbungen, Inaktivitätsprüfung und Rollenmanagement - Best Practices zur Vermeidung von Datenverlust oder falschen Annahmen --- ## Schnellstart für Mitglieder ### 🔹 Profil & Deck optimieren | Command | Beschreibung | Beispiel | |---------|--------------|----------| | `!tag #DEIN_TAG` | Speichert deinen Clash Royale Tag dauerhaft im Bot | `!tag #ABCD1234` | | `!verifizierung` | Prüft deinen exakt gespeicherten Tag gegen Clash Royale + Hauptclan und erstellt eine Admin-Review | `!verifizierung` | | `!profil` | Zeigt deine aktuellen Clan-Stats & Trophy-Fortschritt an | `!profil` | | `!deck` | Analysiert dein aktuelles Deck auf Schwächen & Elixier-Balance | `!deck` | | `!analyse [TAG]` | Professionelle Spieleranalyse inkl. Tier, Stärken, Risiken | `!analyse #XYZ98765` | 💡 **Tipp:** Ohne gespeicherten Tag (`!tag`) funktionieren Coaching-Fragen über `!ai` nicht zuverlässig. Der Bot greift dann auf keine echten Daten zu und antwortet generisch. ### 🔹 Persönliche Notizen für den KI-Coach | Command | Beschreibung | Beispiel | |---------|--------------|----------| | `!remember [Notiz]` | Speichert eine persönliche Coaching-Note, die bei jeder KI-Anfrage berücksichtigt wird | `!remember Trainiere Hog-Matchups und brauche Deck-Varianten gegen Balloon` | ### 🔹 KI-Coaching nutzen Nutze `!ai` für strategische Fragen. Die Antwort basiert auf: 1. Deinem gespeicherten Clash-Tag (wenn vorhanden) 2. Deiner aktuellen Profilanalyse & Deckdaten 3. Deinen persönlichen Notizen (`!remember`) 4. Den allgemeinen Coaching-Richtlinien des Clans ✅ **Empfohlene Formulierungen:** - `!ai Wie verbessere ich mein aktuelles Deck gegen Balloon-Luna-Golem?` - `!ai Welche Karten sollte ich tauschen, um schneller zu cycle'n?` - `!ai Analysiere meinen Profilfortschritt und gib mir einen Push-Fokus.` --- ## Admin-Workflows & Befehle ### 🖥️ Dashboard-Workflow (lokal) ### 🔐 Sicherer Remote-Zugriff für Leader/Admins - Das Dashboard soll **nicht öffentlich ins Internet** exponiert werden, solange keine echte produktive Authentifizierung/SSO aktiv ist. - Für Leader/Co-Leader/Admin-Zugriff außerhalb des lokalen Rechners nur private Netze verwenden, z. B. **Tailscale**, **ZeroTier** oder ein eigenes VPN. - Zugriff nur auf vertrauenswürdige reale Clan-Mitglieder mit vorhandener `dashboard_access`-Freigabe beschränken. - Öffentliche Portfreigaben auf Router/Cloud-Host sind für den aktuellen Reifegrad ausdrücklich **nicht** vorgesehen. - Das lokale Dashboard läuft über `python web/app.py` und ist standardmäßig nur auf `127.0.0.1:5000` erreichbar. - Für den Entwicklungs-Build gibt es jetzt Root-Startskripte: `START_BOT.cmd`, `START_DASHBOARD.cmd`, `VERIFY_BUILD.cmd`. - Bereiche: **Übersicht**, **Login**, **Admin Center**, **Mitgliederbereich**, **Bewerbungsportal**. - Aktuelles Zugriffsmodell in Stufe 2: **Admin** darf `/admin` und `/members`; **Mitglieder** dürfen `/members`. - Die Discord-Rolle **`47 United AI`** bleibt eine reine Bot-/Service-Rolle und ist bewusst **kein** menschlicher Dashboard-Login. - Im **Mitgliederbereich** gibt es jetzt zusätzlich einen Abschnitt **Dashboard-Zugriffsstatus**, der lokale Freigaben/Vormerkungen für den späteren echten Member-Login zeigt. - Im **Admin Center** werden Entscheidungen für Bewerbungen, Mitglieder-Verifizierungen, Rollenfreigaben und jetzt auch lokale Dashboard-Zugangsfreigaben direkt im UI getroffen. - Bestehende Dashboard-Zugriffe können dort außerdem aktiv verwaltet werden: `approved`, `pending`, `denied` sowie Rollenwechsel `Mitglied` ↔ `Admin`. - Diese Zugriffe sind jetzt zusätzlich in getrennte Statuslisten aufgeteilt, damit Admins pro Zustand nur die jeweils passenden Folgeaktionen sehen. - Für größere Mitgliederzahlen gibt es jetzt zusätzlich Such-/Filterfelder nach Discord-ID, Name, Clash-Tag, Status und Rolle. - Der Dashboard-Login verlangt jetzt exakte Discord-ID + Zugriffscode + passende `dashboard_access`-Freigabe + bestätigte Mitglieder-Verifizierung. - Laufende Sessions werden bei jedem Request erneut gegen diese Freigaben geprüft; entzogene Zugriffe verlieren sofort ihren Zugang und Admin-Downgrades greifen ohne erneuten Login. - Dashboard-Zugriffe unterstützen jetzt zusätzlich `expires_at`, `locked_at` und `lock_reason`, damit temporäre Freigaben und Sicherheitsstopps lokal erzwungen werden können. - Das Admin Center zeigt außerdem **Clan-Mismatch / Neuprüfung**: approved Verifizierungen mit falschem Clan-Match können direkt neu geprüft werden; dabei werden aktive Sessions beendet und der Dashboard-Zugang vorsorglich pausiert. - Offene Re-Verification-Fälle landen danach in einer eigenen Queue **Offene Neuprüfungen**; dort können Admins den Zugang wieder freigeben oder endgültig sperren. - Diese Fälle zeigen jetzt zusätzlich sichtbare Statusbadges und einen kompakten **Re-Verification-Verlauf** pro Mitglied direkt im Admin Center. - Zusätzlich gibt es jetzt eine priorisierte Schnellansicht **Problemfälle im Fokus**, über die Admins nur offene Neuprüfungen, nur Clan-Mismatches, nur final gesperrte oder nur wieder freigegebene Fälle anzeigen können. - In dieser Schnellansicht zeigen KPI-Karten jetzt sofort, wie viele offene Neuprüfungen, Clan-Mismatches, finale Sperren und Wiederfreigaben aktuell vorliegen. - Der echte Home-Clan ist jetzt auf `#Y8G8QQJR` gesetzt; Login und laufende Sessions akzeptieren approved Mitglieder-Verifizierungen nur noch für genau diesen Clan. - Das Admin Center zeigt jetzt aktive Dashboard-Sessions mit `claim_version`, `auth_source` und Claim-Scope und erlaubt das sofortige Beenden einzelner Sessions. - Das selbstgehostete Dashboard sendet jetzt zusätzliche Sicherheitsheader (`CSP`, `X-Frame-Options`, `nosniff`, `no-store`), damit Browser-Angriffsfläche und Caching-Risiken sinken. - Dashboard-Sessions enden jetzt serverseitig automatisch nach Inaktivität bzw. nach maximaler Gesamtlaufzeit; die Standardwerte sind `120` Minuten idle und `12` Stunden absolut. - Wiederholte Login-Fehlversuche werden pro Client/Rolle/Discord-ID begrenzt; damit ist der lokale Login für 24/7-Selbsthosting robuster gegen stumpfe Brute-Force-Versuche. - Für späteren HTTPS-Betrieb hinter Reverse Proxy kann per `DASHBOARD_COOKIE_SECURE=1` das `Secure`-Flag für Session-Cookies aktiviert werden. - Für Self-Hosting auf dem eigenen PC gibt es jetzt einen offenen JSON-Healthcheck unter `/healthz`; der Root-Wrapper `CHECK_DASHBOARD_HEALTH.cmd` prüft diesen Endpunkt automatisiert. - Dashboard-Starts und Requests werden jetzt in `logs/dashboard.log` mit Client-IP, Methode, Pfad und Scheme protokolliert. - Neue Backup-/Restore-Helfer sichern den Dashboard-Zustand lokal: `BACKUP_DASHBOARD.cmd`, `scripts/backup_dashboard_state.py` und `scripts/restore_dashboard_backup.py`. - Unter `selfhost/` liegen jetzt konkrete Vorlagen für Reverse Proxy + HTTPS auf dem eigenen PC (`Caddyfile.example`) sowie empfohlene Dashboard-Umgebungsvariablen (`dashboard.env.example`). - `INSTALL_DASHBOARD_AUTOSTART.cmd` legt auf Wunsch einen Windows-Task an, der beim Systemstart das Dashboard-Skript startet; nach Aktivierung immer Healthcheck und Logs prüfen. - `web/app.py` lädt jetzt automatisch `selfhost/dashboard.env` und optional `selfhost/dashboard.local.env`; damit bleiben lokale Self-Hosting-Werte persistent, ohne dass jedes Mal Shell-Variablen gesetzt werden müssen. - `INSTALL_DASHBOARD_MAINTENANCE_TASKS.cmd` legt reale Windows-Tasks für Healthcheck (15 Minuten) und Backup (03:30 täglich) an; `UNINSTALL_DASHBOARD_TASKS.cmd` entfernt diese wieder. - Wenn `schtasks` auf diesem System Start-/Logon-Tasks verweigert, erzeugt `scripts/install_dashboard_tasks.py` automatisch einen Fallback im Windows-Startup-Ordner unter `%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup`. - Der Mitgliederbereich zeigt der eingeloggten Person jetzt zusätzlich eine personalisierte Identitätskarte mit Discord-ID, Clash-Tag, Rolle und Claims. - Jede Dashboard-Entscheidung wird zusätzlich im **Entscheidungslog** gespeichert, damit Leader/Admins Änderungen nachvollziehen können. ### 📝 Bewerbungsmanagement | Command | Beschreibung | Beispiel | |---------|--------------|----------| | `!bewerbung_approve ID Grund` | Nimmt Bewerber auf, setzt Status auf `approved`, sendet Welcome-Nachricht | `!bewerbung_approve 1234567890 Begründung: Hohe Aktivität & Erfahrung` | | `!bewerbung_deny ID Grund` | Lehnt Bewerbung ab, löscht Pending-Eintrag, informiert respektvoll | `!bewerbung_deny 1234567890 Begründung: Unzureichende Ladder-Ränge` | ### 👥 Mitglieder-Verifizierung, Rollenempfehlung & Prüfung | Command | Beschreibung | Beispiel | |---------|--------------|----------| | `!verifizierung` | Erstellt eine Pending-Verifizierung aus exaktem gespeicherten Clash-Tag + aktuellem Hauptclan-Status | `!verifizierung` | | `!verifizierung_approve ID Begründung` | Bestätigt die sichere Mitglieder-Verifizierung als finale Identitätsfreigabe | `!verifizierung_approve 12 Tag und Clan passen exakt` | | `!verifizierung_deny ID Begründung` | Lehnt die Verifizierung ab und dokumentiert die Prüfung | `!verifizierung_deny 12 Clanstatus unklar` | | `!rollencheck` | Generiert eine Pending-Empfehlung basierend auf Aktivität und approved Mitglieder-Verifizierung | `!rollencheck` | | `!rolle_approve ID Begründung` | Bestätigt die Empfehlung → Mitglied erhält finale Rolle (manuell oder via Cron) | `!rolle_approve 42 Begründung: Erfüllt alle Kriterien` | | `!rolle_deny ID Begründung` | Lehnt Empfehlung ab, archiviert Eintrag | `!rolle_deny 42 Begründung: Inaktivität > 14 Tage` | ### 🚨 Inaktivitäts- & War-Benachrichtigungen | Command | Beschreibung | Beispiel | |---------|--------------|----------| | `!inaktiv_hinweis DISCORD_ID [YYYY-MM-DD]` | Generiert einen respektvollen Hinweistext für ein Mitglied (keine automatische Sanktion!) | `!inaktiv_hinweis 9876543210 2026-06-01` | | `!entschuldigung Grund` | Speichert eine Abwesenheitsnotiz → unterdrückt zukünftige Inaktivitäts-Alerts für diesen Zeitraum | `!entschuldigung Urlaub bis 15. Juni` | ### 📢 Aktivität & Ausrufe | Command | Beschreibung | Beispiel | |---------|--------------|----------| | `!ausruf` | Generiert öffentliche Anerkennungstexte basierend auf dem aktuellen Activity Ranking (ohne automatische Rollenvergabe!) | `!ausruf` | --- ## KI-Logik & Coaching-Prompting ### Wie der Bot entscheidet Der KI-Assistent nutzt einen strukturierten Prompt-Flow: 1. **System-Richtlinie:** Loyal zum Clan, kompetitiv, respektvoll, Deutsch, kurz & direkt 2. **Coaching-Kontext:** Discord-Name, Clash Tag (exakt!), Beitrittsdatum, letzte Aktivität 3. **Verbindliche Daten:** Profilanalyse + Deckanalyse werden nur geladen, wenn ein gespeicherter Tag existiert 4. **Persönliche Constraints:** Notizen aus `!remember` werden explizit als "zwingend zu berücksichtigen" markiert ### ⚠️ Wichtige Grenzen der KI - Die KI **verändert keine externen IDs** (Clash Tags, Discord IDs) still oder automatisch. - Sie antwortet nur mit Daten, die aus dem gespeicherten Tag + API stammen können. Fehlt dieser, bleibt sie transparent: "Kein Clash-Royale-Profil verknüpft." - Coaching-Empfehlungen sind **strategische Vorschläge**, keine automatischen Entscheidungen für Clan-Wars oder Rollenvergabe. --- ## Troubleshooting & Fehlerbehebung | Symptom | Ursache | Lösung | |---------|---------|--------| | `Dein Deck fehlt!` / generische Antwort bei `!ai Analysiere mein Deck...` | Kein gespeicherter Clash Tag vorhanden | Nutze zuerst `!tag #DEIN_TAG`, dann erneut `!ai ...` | | `Kritischer Fehler: 401 Unauthorized` | Falscher oder abgelaufener Clash Royale API Token in `config.yml` | Prüfe Token unter developer.clashroyale.com → aktualisiere `CLASH_API_TOKEN` in Config | | `!bewerbung_approve` sagt "Bewerbung nicht gefunden" | ID wurde gelöscht, Tippfehler oder falscher Format | Nutze `!bewerbungen`, um aktuelle Pending-Einträge zu prüfen. IDs sind numerisch und eindeutig. | | KI antwortet auf Deutsch, aber erwartet englische Fachbegriffe? | Prompt ist explizit auf "auf Deutsch antworten" gesetzt | Füge in deiner Frage hinzu: "Nutze englische Fachbegriffe wo sinnvoll." | --- ## Datenschutz & Identitätssicherheit ### 🔒 Prinzipien 1. **Exakte ID-Bewahrung:** Clash Tags und Discord IDs werden niemals umgedeutet, korrigiert oder durch Lookalikes ersetzt (`#ABCDUSWL` bleibt `#ABCDUSWL`). 2. **Keine stillen Rollenänderungen:** Der Bot vergibt keine Discord-Rollen automatisch. Alle Änderungen erfolgen explizit via Admin-Command oder manuellem Cron-Job. 3. **Verifizierungs-Gate vor Rollenlogik:** Mitgliedsrollen werden nur empfohlen, wenn eine `approved` Mitglieder-Verifizierung für den exakt gespeicherten Clash-Tag existiert. 4. **Transparenz bei API-Fehlern:** Wenn Clash-Daten nicht geladen werden können, dokumentiert der Bot den Fehler im Prompt statt zu raten. 5. **Respektvolle Kommunikation:** Inaktivitäts-Hinweise und Ausrufe sind bewusst ohne Sanktionen formuliert und verweisen auf `!entschuldigung Grund` als Rückkanal. ### 📂 Datenhaltung - Alle Nutzerdaten liegen lokal in `clan_bot.db` (SQLite) - Channel-Memory wird pro Discord-Kanal getrennt gespeichert (`channel_memory`) - Keine externen Cloud-Synchronisation oder Tracking --- *Dieses Dokument wird bei jeder neuen Iteration aktualisiert. Aktuelle Version: v0.0.4.0 | Stand: 2026-06-13* *Direkt konvertierbar zu PDF via Pandoc, VS Code Markdown Preview oder LibreOffice.* ## v0.0.4.1 Kurzstand - Dashboard-Übersicht zeigt jetzt den echten Clash-Royale-Clan-Roster-Abgleich: live im Clan, verbunden, noch nicht verbunden und alte/falsche Verknüpfungen. - Wichtige operative Erklärungen erfolgen im Hermes-Chat statt als zusätzliche Erklärdateien im Produktordner.