# Nexumi – Vollständige Feature-Spezifikation (Cursor-Prompt)

Baue „Nexumi", einen vollwertigen, **öffentlichen** Discord-Bot mit Web-Dashboard. Domain: `https://nexumi.de`. Repository: `https://git.hexahost.dev/smueller/Nexumi`. Der Name „Nexumi" wird konsistent verwendet: Bot-Präsenz, WebUI-Branding, Embed-Footer, Docker-Image-Namen, Dokumentation. Halte dich an diese Spezifikation. Frage nach, bevor du Module weglässt oder den Stack änderst.

## Tech-Stack & Architektur

- **Bot:** TypeScript, discord.js v14+, ausschließlich Slash Commands, Context-Menu-Commands, Buttons, Select Menus, Modals. Keine Message-Prefix-Commands.
- **Datenbank:** PostgreSQL als Container im Compose-Stack. Kein veröffentlichter Port – erreichbar ausschließlich über das interne Docker-Netz von Bot und WebUI. Zugangsdaten per `.env`, Daten in einem Named Volume, Healthcheck im Compose (Bot und WebUI starten erst nach erfolgreichem `pg_isready`). Automatisches Backup: täglicher `pg_dump` als BullMQ-Job in ein Backup-Volume, Aufbewahrungsdauer konfigurierbar, Restore-Anleitung im README. Prisma ORM; Postgres-Features (JSONB, Volltextsuche) dürfen genutzt werden. Redis für Cache, Cooldowns, Rate Limits, Sessions und die Job-Queue.
- **WebUI:** Next.js (App Router) mit API-Routes oder separatem Fastify-Backend. Discord OAuth2 Login. WebSocket/SSE für Live-Updates.
- **Deployment:** Ein Docker-Compose-Stack: Bot, WebUI, PostgreSQL, Redis, optional Lavalink – `docker compose up -d` startet alles. Bot und WebUI aus einem gemeinsamen Monorepo mit Multi-Stage-Dockerfiles. Traefik-kompatible Labels am WebUI-Service. `.env`-basierte Konfiguration, keine Secrets im Code. Named Volumes für Postgres-Daten, Redis-Persistenz und Backups.
- **Struktur:** Modulares Feature-System. Jedes Modul ist einzeln pro Server aktivierbar/deaktivierbar. Command-Handler, Event-Handler, Jobs (Scheduler) sauber getrennt.
- **Skalierung:** Öffentlicher Bot. Sharding von Anfang an aktiv (discord.js ShardingManager, Shard-Anzahl automatisch nach Discord-Empfehlung), alle Shards auf einem Host. Kein Zustand nur im Speicher, der einen Neustart nicht überleben darf – persistenter Zustand liegt in PostgreSQL und Redis.
- **Jobs:** Alle zeitgesteuerten Aufgaben (Scheduler-Nachrichten, Giveaway-Enden, Temp-Ban-Abläufe, Feed-Polling, Geburtstage, Ticket-Auto-Close) laufen über BullMQ auf Redis statt über In-Process-Timer, damit sie Neustarts überleben und exakt einmal ausgeführt werden.
- **Monitoring:** Prometheus-Metrics-Endpoint (`/metrics`, per Token geschützt) mit Command-Latenzen, Fehlerrate, Event-Durchsatz, Shard-Ping, Guild-Anzahl, DB-Pool-Auslastung – zur Anbindung an bestehendes Grafana. Sentry-SDK in Bot und WebUI (DSN per `.env`, Release-Tagging mit Versionsnummer, Source Maps für das Frontend).
- **i18n:** Deutsch und Englisch, pro Server einstellbar. Alle User-facing Strings über Locale-Dateien.
- **Qualität:** ESLint, Prettier, Zod-Validierung für alle Eingaben (Commands und API), strukturierte Logs (pino), zentrale Fehlerbehandlung, Unit-Tests für Kernlogik.

## Grundprinzipien

- Jede Aktion mit Berechtigungsprüfung (Discord-Permissions + eigene Rollen-Regeln aus dem Dashboard).
- Alle destruktiven Aktionen (Ban, Purge, Backup-Restore) mit Bestätigung und Audit-Eintrag.
- Alle Module schreiben in ein zentrales Audit-/Case-System.
- Ephemere Antworten als Standard bei Verwaltungs-Commands.

---

## Feature-Module und Commands

### 1. Moderation
- `/ban`, `/unban`, `/kick`, `/timeout` (Dauer), `/untimeout`
- `/warn add`, `/warn list`, `/warn remove`, `/warn clear`
- `/purge` (Anzahl, Filter: User, Bots, Links, Anhänge, Regex)
- `/slowmode`, `/lock`, `/unlock` (Kanal oder Server)
- `/nick set`, `/nick reset`
- `/case view`, `/case edit`, `/case delete` – zentrales Fall-System mit Case-IDs
- `/modnote add|list` – interne Notizen zu Usern
- Eskalationsregeln: konfigurierbare automatische Strafen ab X Warns
- Temp-Bans mit automatischem Unban (Scheduler)

### 2. Auto-Moderation
- Filter: Spam, Massen-Mentions, Caps, Invite-Links, externe Links (Whitelist/Blacklist), Wortfilter (Wortlisten + Regex), Duplikat-Nachrichten, Emoji-Spam, Zalgo
- Phishing-/Scam-Link-Erkennung über aktuelle Blocklisten
- Anti-Raid: Join-Rate-Erkennung, automatischer Verifizierungs-/Lockdown-Modus
- Anti-Nuke: Schutz vor Massen-Bans/Channel-Löschungen durch kompromittierte Admin-Accounts (Aktions-Limits, automatische Rechteentziehung)
- Pro Regel konfigurierbar: Aktion (löschen, warnen, timeout, kick, ban), Ausnahmen (Rollen, Kanäle), Schwellenwerte
- `/automod status` – aktive Regeln anzeigen

### 3. Logging
- Getrennte, pro Event-Typ konfigurierbare Log-Kanäle
- Events: Nachricht bearbeitet/gelöscht (mit Inhalt), Bulk-Delete, Member Join/Leave, Ban/Unban, Rollen-Änderungen, Nickname-Änderungen, Kanal erstellt/gelöscht/geändert, Voice Join/Leave/Move, Invite erstellt, Emoji/Sticker-Änderungen, Thread-Events, Server-Einstellungen geändert
- Mod-Action-Log verknüpft mit Case-System
- Ignore-Listen (Kanäle, Rollen, Bots)

### 4. Willkommen & Abschied
- Welcome-/Leave-Nachricht: Text, Embed oder generierte Bild-Karte (Canvas)
- Platzhalter-System (`{user}`, `{server}`, `{memberCount}` usw.)
- Autoroles bei Join (getrennt für User und Bots)
- Optionale Welcome-DM
- `/welcome test`, `/welcome preview`

### 5. Verifizierung
- Button-Verify, Captcha-Verify (über WebUI-Seite), Rollen-Gating
- Konfigurierbar: Mindest-Accountalter, Aktion bei Fehlschlag
- `/verify setup`, `/verify panel`

### 6. Leveling & XP
- `/rank`, `/leaderboard` (Server + Web-Ansicht)
- Text-XP und Voice-XP, konfigurierbare Raten, Cooldowns, Multiplikatoren (pro Rolle/Kanal)
- No-XP-Kanäle und -Rollen
- Rollen-Belohnungen bei Levelstufen (stapelnd oder ersetzend)
- Level-Up-Nachricht: Kanal, DM oder aus
- `/xp give|remove|reset` (Admin)
- Rank-Card anpassbar (Farbe, Hintergrund)

### 7. Economy
- `/balance`, `/daily`, `/weekly`, `/work`, `/pay`
- `/gamble`, `/slots`, `/blackjack`, `/coinflip bet`
- `/shop view|buy`, `/inventory`, Shop-Items mit Rollen-Belohnung
- `/eco leaderboard`, Admin: `/eco give|remove|reset`
- Währungsname und -symbol pro Server konfigurierbar

### 8. Utility
- `/userinfo`, `/serverinfo`, `/roleinfo`, `/channelinfo`, `/avatar`, `/banner`
- `/poll create` (Buttons, Mehrfachauswahl, Ablaufzeit, anonyme Option)
- `/remindme` (einmalig und wiederkehrend), `/reminders list|delete`
- `/afk set` mit automatischer Antwort bei Mention
- `/emoji add|remove|steal`, `/sticker add`
- `/timestamp` (Discord-Timestamp-Generator)
- `/translate` (Context-Menu auf Nachrichten)
- `/snipe`, `/editsnipe` (optional aktivierbar, Datenschutz-Hinweis)
- `/embed builder` – Embed per Modal bauen und senden

### 9. Fun & Games
- `/8ball`, `/dice`, `/coinflip`, `/rps`, `/choose`
- `/trivia`, `/tictactoe`, `/connect4`, `/hangman` (Button-basiert)
- `/meme`, `/cat`, `/dog` (API-basiert, abschaltbar)

### 10. Giveaways
- `/giveaway start` (Dauer, Gewinneranzahl, Preis, Anforderungen: Rolle, Level, Serverzugehörigkeit-Dauer)
- `/giveaway end|reroll|list|delete|pause`
- Button-Teilnahme, automatische Gewinnerziehung, DM an Gewinner

### 11. Ticket-System
- `/ticket panel create` – Panel mit Buttons/Dropdown und Kategorien
- Ticket öffnen als privater Kanal oder Thread
- `/ticket close|claim|add|remove|rename|priority`
- Support-Rollen pro Kategorie, Öffnungs-Formular (Modal) pro Kategorie
- HTML-Transkripte, im WebUI einsehbar, optional per DM
- Auto-Close bei Inaktivität, Bewertungs-Abfrage nach Schließung

### 12. Reaction Roles / Self Roles
- Modi: Buttons, Dropdown, klassische Reaktionen
- Verhalten: normal, unique (nur eine), verify (nur hinzufügen), temporär
- `/selfroles panel create|edit|delete`
- Builder primär im WebUI

### 13. Custom Commands / Tags
- `/tag create|edit|delete|list|info`
- Antworttypen: Text, Embed, mit Platzhaltern und einfachen Variablen (User, Server, Argumente, Random)
- Optionale Auto-Responder (Trigger-Wort → Antwort)
- Berechtigungen und Kanal-Beschränkungen pro Tag

### 14. Starboard
- Konfigurierbar: Emoji, Schwellenwert, Ziel-Kanal, Self-Star erlaubt/verboten, ignorierte Kanäle
- NSFW-Kanal-Ausschluss

### 15. Vorschläge (Suggestions)
- `/suggest` mit Voting-Buttons, Thread-Diskussion optional
- `/suggestion approve|deny|consider|implement` mit Begründung, User-Benachrichtigung
- Getrennte Kanäle für offen/angenommen/abgelehnt

### 16. Geburtstage
- `/birthday set|remove|next|list`
- Automatische Glückwunsch-Nachricht, optionale Geburtstagsrolle für 24 h
- Zeitzonen-Handling

### 17. Temp-Voice (Join to Create)
- Auto-Erstellung eines eigenen Voice-Kanals beim Join in Hub-Kanal
- Steuerung per `/voice` und Control-Panel (Buttons): rename, limit, lock, hide, kick, transfer, claim
- Auto-Löschung bei Leere

### 18. Server-Statistiken & Invite-Tracking
- Stats-Kanäle (Mitgliederzahl, Online, Boosts) mit Auto-Update
- Invite-Tracking: wer hat wen eingeladen, `/invites`, `/invites leaderboard`
- Fake-/Leave-Erkennung bei Invites
- Aktivitäts-Statistiken (Nachrichten/Voice pro Kanal/User) für das Dashboard

### 19. Social-Feeds & Benachrichtigungen
- Twitch-Live-Benachrichtigungen, YouTube-Uploads, RSS-Feeds, Reddit
- Pro Feed: Ziel-Kanal, Rollen-Ping, Nachrichtenvorlage
- `/feeds add|remove|list|test`

### 20. Scheduler & Ankündigungen
- Geplante und wiederkehrende Nachrichten (Cron-ähnlich)
- `/schedule create|list|delete`
- Ankündigungs-Command mit Embed und Rollen-Ping

### 21. Musik (optional, eigenes Modul)
- Lavalink-basiert, Quellen konfigurierbar
- `/play`, `/pause`, `/resume`, `/skip`, `/stop`, `/queue`, `/nowplaying`, `/shuffle`, `/loop`, `/volume`, `/seek`, `/filter`, `/playlist save|load`
- DJ-Rolle, Vote-Skip
- Hinweis im Code dokumentieren: Quellen-ToS beachten, Modul standardmäßig deaktiviert

### 22. KI-Funktionen (optional, pro Server abschaltbar)
- `/ask` – Chat mit konfigurierbarem LLM-Backend (OpenAI-kompatible API, damit auch selbst gehostete Modelle wie Ollama/vLLM nutzbar)
- `/summarize` – Zusammenfassung der letzten N Nachrichten eines Kanals
- KI-gestützte AutoMod-Bewertung als optionale zweite Stufe
- Token-/Kosten-Limits pro Server, Provider und API-Key nur global vom Owner konfigurierbar

### 23. Backup
- `/backup create|list|info|delete|restore`
- Sichert: Kanäle, Rollen, Berechtigungen, Einstellungen (keine Nachrichten)
- Restore nur durch Server-Owner mit doppelter Bestätigung

---

## Öffentlicher Bot – zusätzliche Anforderungen

- Landing Page auf `https://nexumi.de`: Feature-Übersicht, Invite-Button, Link zum Support-Server, Live-Statistiken (Server-/User-Anzahl), Login zum Dashboard. Gleiche Design-Sprache wie das Dashboard.
- Dashboard unter `https://nexumi.de/dashboard`, OAuth2-Callback `https://nexumi.de/api/auth/callback` (im Discord Developer Portal eintragen).
- Rechtliche Seiten: Impressum und Datenschutzerklärung (deutscher Betreiber, Pflicht nach DDG/DSGVO) sowie Terms of Service (Deutsch und Englisch). ToS- und Privacy-URLs im Developer Portal hinterlegen – Voraussetzung für die Bot-Verifizierung.
- Privilegierte Intents (Server Members, Message Content) sind aktiviert; Begründungen für den Verifizierungsantrag in `docs/verification.md` sammeln (welches Modul welchen Intent wofür braucht).
- Basis-Commands: `/help` (auto-generierte Command-Übersicht nach Modulen), `/info` (Version, Uptime, Shard, Links), `/invite`, `/support`.
- Premium-System aktiv nutzen, nicht nur vorbereiten: Stufen Free/Premium, Feature- und Limit-Zuordnung pro Stufe im Owner-Panel konfigurierbar (z. B. Anzahl Custom Commands, Feeds, Backups). Zahlungsanbindung vorerst außen vor, Zuweisung manuell über das Owner-Panel.
- Status-/Uptime-Seite unter `https://nexumi.de/status` (Shard-Status, API-Latenz, Incidents aus dem Changelog-System).

## WebUI – Design-Vorgaben (gelten für Landing Page, Dashboard und Owner-Panel)

- Modern und professionell, kein Spielzeug-Look: Tailwind CSS + shadcn/ui als Komponentenbasis, Schrift Inter, Icons von Lucide.
- Dark Mode als Standard, Light Mode umschaltbar. Akzentfarbe Indigo (`#6366F1`), sonst neutrale Grautöne, sparsame Farbverwendung (Farbe nur für Status und Aktionen).
- Layout: schmale Sidebar mit Modul-Gruppen und Server-Switcher oben, Content-Bereich max. ~1200 px breit, konsistente Karten mit einheitlichem Spacing.
- Formulare: Sticky-Save-Bar bei ungespeicherten Änderungen („Du hast ungespeicherte Änderungen – Speichern/Verwerfen"), Validierungsfehler inline, Erfolg per Toast.
- Ladezustände als Skeletons statt Spinner, durchdachte Empty States mit Handlungsaufforderung (z. B. „Noch kein Ticket-Panel – jetzt erstellen").
- Responsiv bis Tablet; Mobile funktional, aber nicht Priorität.
- Keine Stock-Illustrationen, keine Gradients über Vollflächen, keine Marketing-Floskeln im Interface.

## WebUI – Server-Dashboard (für Server-Admins)

**Zugang:** Discord OAuth2, Server-Auswahl (nur Server mit Manage-Server-Recht), rollenbasierter Dashboard-Zugriff zusätzlich konfigurierbar (z. B. Mods dürfen nur Moderation/Tickets sehen).

**Pro Server einstellbar:**
- Übersicht: Aktivitäts-Charts (Mitgliederentwicklung, Nachrichten, Voice), letzte Mod-Aktionen, Modul-Status
- Module einzeln aktivieren/deaktivieren
- Command-Verwaltung: jeden Command aktivieren/deaktivieren, pro Rolle/Kanal erlauben/sperren, Cooldowns setzen
- Sprache und Zeitzone des Servers
- Moderation: Eskalationsregeln, Case-Browser mit Suche/Filter, Warn-Verwaltung
- AutoMod: alle Regeln mit Schwellenwerten, Wortlisten-Editor, Ausnahmen
- Logging: Event-zu-Kanal-Zuordnung per Matrix, Ignore-Listen
- Welcome/Leave: Editor mit Live-Vorschau (Text, Embed, Bild-Karte), Autoroles
- Verifizierung: Modus, Anforderungen
- Leveling: Raten, Multiplikatoren, Rollen-Belohnungen, No-XP-Listen, Rank-Card-Design, XP von Usern editieren
- Economy: Währung, Shop-Editor, Beträge der Einkommens-Commands
- Reaction-Roles-Builder (Drag & Drop, Vorschau)
- Embed-Builder mit Senden in Kanal
- Custom-Commands-/Tag-Editor
- Ticket-System: Kategorien, Formulare, Support-Rollen, Panel-Builder, Transkript-Archiv mit Viewer
- Giveaway-Verwaltung (erstellen, beenden, reroll aus dem Browser)
- Suggestions-Verwaltung
- Starboard-, Birthday-, Temp-Voice-, Scheduler-Einstellungen
- Social-Feeds-Verwaltung
- Backup-Verwaltung (erstellen, herunterladen, wiederherstellen)
- Öffentliche Seiten (optional aktivierbar): Leaderboard, Server-Statistiken
- Audit-Log des Dashboards: wer hat welche Einstellung wann geändert

---

## WebUI – Bot-Owner-Panel (nur globale Owner/Team)

- **Übersicht:** Guild-Anzahl, User-Anzahl, Shard-Status und -Latenzen, RAM/CPU, Uptime, Command-Nutzungs-Statistiken (Top-Commands, Fehlerrate), Event-Durchsatz
- **Shard-Management:** Shard-Übersicht mit Status, Latenz und Guild-Verteilung; einzelne Shards neu starten, kompletter Neustart, Wartungsmodus (Bot antwortet nur mit Wartungshinweis)
- **Guild-Verwaltung:** Liste aller Server mit Suche, Details einsehen (aktivierte Module, Größe), Server verlassen, Server-Blacklist
- **User-Verwaltung:** globale User-Blacklist (Bot ignoriert User überall), Notizen
- **Feature-Flags:** Module global aktivieren/deaktivieren, Rollout pro Guild-Prozentsatz oder Whitelist (für neue Features)
- **KI-Konfiguration:** Provider, API-Keys, Modelle, globale Limits
- **Fehler-Monitoring:** Sentry als primäres Fehler-Tracking (Deep-Links vom Panel zu Sentry-Issues), zusätzlich eigener Viewer für die letzten Fehler mit Guild-/Command-Kontext
- **Ankündigungen:** Nachricht an alle Server-Owner oder System-Kanäle senden (mit Vorschau und Bestätigung)
- **Bot-Präsenz:** Status, Aktivitätstext, rotierende Status-Nachrichten
- **Premium-Verwaltung** (vorbereitet, auch wenn initial ungenutzt): Premium-Stufen pro Guild/User zuweisen, Feature-Zuordnung zu Stufen
- **Team-Verwaltung:** weitere Owner/Admins mit abgestuften Rechten (Viewer, Support, Admin, Owner)
- **Datenbank/Jobs:** Status der Scheduler-Jobs, fehlgeschlagene Jobs neu starten, Migrations-Status
- **Changelog:** Versionshinweise pflegen, die im Server-Dashboard angezeigt werden
- **Sicherheit:** Alle Owner-Aktionen im globalen Audit-Log. Kein Eval-/Code-Ausführungs-Feature im WebUI.

---

## Nichtfunktionale Anforderungen

- DSGVO-freundlich: `/privacy`-Command, Datenlöschung pro User auf Anfrage (`/gdpr delete`), konfigurierbare Log-Aufbewahrungsdauer, Snipe-Modul standardmäßig aus
- Rate-Limit-Handling der Discord-API sauber implementieren (discord.js-Queue respektieren, keine eigenen Massen-Loops)
- Graceful Shutdown (laufende Giveaways/Timer überleben Neustarts, Zustand in DB)
- Health-Endpoints für Bot und WebUI (Docker Healthchecks)
- Setup-Dokumentation: README mit Docker-Compose-Quickstart, `.env.example`, Migrationsanleitung

---

## Vorgehen beim Bau (für den Agenten verbindlich)

Baue nicht alles auf einmal. Arbeite in Phasen und liefere nach jeder Phase einen lauffähigen, committbaren Stand (Build, Lint und Tests grün, Bot startet gegen einen Test-Server):

1. **Fundament:** Monorepo, Compose-Stack, Prisma-Schema der Kern-Tabellen (Guilds, Guild-Settings, Users, Cases), Modul-Framework mit Command-/Event-Loader, Berechtigungs-Layer, i18n-Grundgerüst, BullMQ-Anbindung. Dazu das Referenzmodul **Moderation** vollständig – es definiert die Muster für alle weiteren Module.
2. AutoMod, Logging, Welcome/Leave, Verifizierung.
3. Leveling, Economy, Utility, Fun.
4. Giveaways, Tickets, Reaction Roles, Custom Commands, Starboard, Suggestions, Geburtstage, Temp-Voice.
5. Statistiken/Invite-Tracking, Social-Feeds, Scheduler, Backup.
6. WebUI-Fundament: OAuth, Layout, Settings-Framework (generische Modul-Seiten mit Save-Bar), API-Schicht mit Zod-Schemas, die Bot und WebUI teilen.
7. WebUI-Seiten je Modul, danach Owner-Panel.
8. Landing Page, Status-Seite, Rechtsseiten-Gerüst. Musik und KI-Modul zuletzt und nur auf Zuruf.

Regeln: keine Platzhalter-TODOs oder Stub-Implementierungen in abgeschlossenen Phasen; ein Modul gilt erst als fertig, wenn Commands, Datenbank, Jobs und (ab Phase 7) die zugehörige WebUI-Seite funktionieren; bei Unklarheiten nachfragen statt raten.
