Files

TheOnlyMace 8c02b95934 Update README and localization files to remove "self-hosted" references

- Revised the README.md to simplify the description of Nexumi.
- Updated layout.tsx to reflect the change in the bot's description.
- Modified German and English localization files to remove "self-hosted" from the bot's description and terms of service.

2026-07-22 19:10:17 +02:00

18 KiB

Raw Permalink Blame History

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

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):

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.
AutoMod, Logging, Welcome/Leave, Verifizierung.
Leveling, Economy, Utility, Fun.
Giveaways, Tickets, Reaction Roles, Custom Commands, Starboard, Suggestions, Geburtstage, Temp-Voice.
Statistiken/Invite-Tracking, Social-Feeds, Scheduler, Backup.
WebUI-Fundament: OAuth, Layout, Settings-Framework (generische Modul-Seiten mit Save-Bar), API-Schicht mit Zod-Schemas, die Bot und WebUI teilen.
WebUI-Seiten je Modul, danach Owner-Panel.
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.

18 KiB Raw Permalink Blame History Unescape Escape