# Papo Discord Bot

## 1. Projektueberblick
Papo ist ein Discord-Bot (discord.js 14, TypeScript) mit Web-Dashboard. Implementiert sind:
- Ticketsystem: Ticket-Channel pro Nutzer, Slash-Commands (/ticket, /claim, /close, /ticketpriority, /ticketstatus, /transcript, /ticketpanel), Panel-Erstellung via Bot und Dashboard; Transcripts als Textdatei unter `./transcripts`. Inklusive Support-Login-Panel (Rolle vergeben/entfernen, On-Duty-Logging).
- Automod: Link-Filter mit Whitelist, Spam- und Caps-Erkennung, Bad-Word-Filter mit Custom-Listen, Zeitueberschreitung bei Spam, Logging der Aktionen.
- Musik-Modul: Wiedergabe via play-dl, Queue mit Loop/Skip/Stop/Pause/Resume, per Slash-Commands; Modul pro Guild abschaltbar.
- Welcome-Modul: Begruessungs-Embeds mit konfigurierbarer Farbe, Titel, Beschreibung, Footer, Thumbnails/Bilder (Upload oder URL), Aktivierung pro Guild, Vorschau im Dashboard; Fallback auf Text-Begruesung, wenn nur `welcomeChannelId` gesetzt ist.
- Logging-Modul: Join/Leave, Message Edit/Delete, Automod/Ticket/Musik-Events, konfigurierbarer Log-Channel und Kategorien.
- Leveling: XP/Level pro Nachricht, Anzeige via /rank, Toggle ueber Settings.
- Dynamische Voice Channels: Lobby-gestuetzte Erstellung privater Voice-Channels mit automatischem Move und Berechtigungen.
- Birthday-Modul: /birthday zum Setzen des Geburtsdatums, konfigurierbare Channel-/Template-Einstellungen, automatische Glueckwuensche.
- Reaction Roles: Dashboard-Konfiguration, Bot reagiert auf Reactions und vergibt Rollen.
- Termine/Events: Einmalige/recurring Events (taeglich/woechentlich/monatlich), Reminder, An-/Abmelde-Buttons, pro Event eigener Channel/Ping-Rolle.
- Modul-Management im Dashboard: Toggles fuer Tickets, Automod, Welcome, Musik, Leveling, Dynamische Voice, Statuspage, Birthday, Reaction Roles, Events.
- Dashboard: Sidebar-Navigation (Uebersicht, Tickets, Automod, Welcome, Dynamic Voice, Statuspage, Birthday, Reaction Roles, Events, Module, Einstellungen), OAuth2-Login (Scopes identify, guilds), Guild-Auswahl und modulabhaengige Sichtbarkeit.

## 2. Installation / Setup
Voraussetzungen:
- Node.js 18+ (CommonJS, ts-node fuer Dev)
- Postgres-Datenbank zugaenglich per Connection-String
- Discord-Anwendung/Bot mit Berechtigungen: Slash Commands, Nachrichten senden/lesen, Embed Links, Dateien senden, Channels verwalten (Tickets), Nachrichten loeschen/timeouts (Automod), Voice Connect/Speak (Musik)
- OAuth Redirect: `http://localhost:PORT/auth/callback` oder eigener `DASHBOARD_BASE_URL`

Schritte:
1) Repository klonen und ins Projekt wechseln.  
2) Abhaengigkeiten installieren: npm install.  
3) .env aus .env.example kopieren und Variablen setzen (siehe Liste unten).  
4) Prisma vorbereiten: npx prisma generate, danach npx prisma migrate dev --name init (legt Migrationen an; bei neuen Features ggf. weitere wie `add-events-module`).  
5) Entwicklung starten: npm run dev (ts-node).  
6) Produktion: npm run build, dann npm start (nutzt dist/index.js). Dashboard laeuft im selben Prozess auf PORT (default 3000).  
7) Slash-Commands werden beim Start fuer alle IDs in DISCORD_GUILD_IDS (oder global) registriert.

Environment-Variablen:
- DISCORD_TOKEN (Bot Token, Pflicht)
- DISCORD_CLIENT_ID (Client ID, Pflicht)
- DISCORD_CLIENT_SECRET (fuer Dashboard-OAuth erforderlich)
- DISCORD_GUILD_ID (optionale Einzel-Guild fuer Command-Registrierung)
- DISCORD_GUILD_IDS (kommagetrennte Liste fuer mehrere Guilds)
- DATABASE_URL (Postgres-URL, Pflicht)
- PORT (Webserver/Dashboard-Port, Standard 3000)
- SESSION_SECRET (Express Session Secret, Standard papo_dev_secret)
- DASHBOARD_BASE_URL (optional, Basis-URL fuer OAuth Redirects)
- WEB_BASE_PATH (optional, z.B. /ucp)
- OWNER_IDS (kommagetrennte Bot-Owner fuer Admin-UI)
- SUPPORT_ROLE_ID (optionale Support-Rolle fuer Tickets/Support-Login)

## 3. Datenbank & Migrationen
- Prisma-Schema: `prisma/schema.prisma` (alias in `src/database/schema.prisma`).
- Migrationen per `npx prisma migrate dev --name <name>`; danach `npx prisma generate`.
- Wesentliche Tabellen:
  - GuildSettings: Module-Flags + Config (automod/welcome/logging/music/dynamicVoice/statuspage/birthday/reactionRoles/events/supportLogin).
  - Ticket: id, ticketNumber, userId, channelId, guildId, topic, priority, status, claimedBy, transcript.
  - TicketSupportSession: guildId, userId, roleId, startedAt/endedAt, durationSeconds.
  - Event / EventSignup: Events mit Wiederholung/Reminder, Signups mit canceledAt.
  - Birthday, ReactionRoleSet, Level.

## 4. Module & Features (Details)
- Ticketsystem: Slash-Commands fuer Anlage/Claim/Close/Prioritaet/Status; Ticket-Panel per Command oder Dashboard (/api/tickets/panel). Dashboard zeigt Ticket-Liste, Detail-Modal, Close-Aktion; Transcripts via /api/tickets/:id/transcript; Tickets pro Guild deaktivierbar (Module-Toggle); Support-Rolle fuer Channel-Overwrites optional.
- Automod: Link-Filter mit Whitelist, Bad-Word-Filter (Default + Custom), Caps-Erkennung, Spam-Tracker (Threshold/Window/Timeout), Rollenausnahmen, Log-Channel; konfigurierbar im Dashboard (Switches, Whitelist-Felder, Log-Channel, Sensitivitaet). Aktionen werden optional geloggt.
- Musik: Queue-Handling mit play/skip/stop/pause/resume/loop, Status-Abfrage im Dashboard (activeGuilds) und Modul-Toggle; stopAll-Hook bei Deaktivierung; nutzt play-dl + @discordjs/voice.
- Welcome: Embeds im Dashboard konfigurierbar (Channel, Farbe, Titel, Beschreibung, Footer, Thumbnails/Bilder als URL oder Upload), Preview im UI; Bot sendet Embeds bei Join, faellt auf Text-Begruesung zurueck wenn nur welcomeChannelId gesetzt ist.
- Logging: Kategorien joinLeave/messageEdit/messageDelete/automodActions/ticketActions/musicEvents, Log-Channel im Dashboard konfigurierbar; nutzt LoggingService fuer Events.
- Leveling: XP pro Nachricht, /rank Anzeige, Toggle ueber Settings. Unique Constraint pro Guild/User.
- Dynamische Voice: Lobby-Channel erzeugt private Voice-Channels mit Name-Template, optionalem Userlimit; Benutzer wird automatisch verschoben, leere erzeugte Channels werden entfernt.
- Modulverwaltung: Dashboard-Seite Module mit Toggles fuer ticketsEnabled/automodEnabled/welcomeEnabled/musicEnabled/levelingEnabled; API /api/modules liefert Status pro Guild.
- Dashboard/Backend: OAuth2 Login (/auth/discord, /auth/callback), Session-Handling, Guild-Auswahl; API-Endpoints mit Auth-Guard (/api/me, /api/guilds, /api/overview, /api/tickets, /api/tickets/:id/messages, /api/tickets/:id/close, /api/tickets/panel, /api/settings GET/POST, /api/modules). Sidebar-Abschnitte Uebersicht/Tickets/Automod/Welcome/Module/Einstellungen mit modulabhaengiger Sichtbarkeit; Settings-Form fuer welcome/log/supportRole, Logging-Optionen, Automod- und Welcome-Formulare.
- Commands (implementiert): Admin (/ban, /tempban, /kick, /mute, /unmute, /timeout, /clear), Music (/play, /pause, /resume, /skip, /stop, /queue, /loop), Tickets (/ticket, /claim, /close, /ticketpriority, /ticketstatus, /transcript, /ticketpanel), Utility (/configure, /help, /ping, /rank, /serverinfo, /welcome).

## 5. Roadmap / Planung
- SupportBot: Ansagen, Supportzeiten, Wartemusik (geplant)
- Embed-Builder (geplant)
- Team-Systeme: Abwesenheiten melden, Team-Dashboard (geplant)

## 6. Credits & Lizenz
- Autoren/Maintainer: nicht angegeben.
- Lizenz: nicht angegeben (bitte vor Nutzung pruefen).