GSM/docs/discord-bot.md

# Discord Bot

Der GSM Discord Bot bietet Live-Status-Updates für alle Gameserver direkt in Discord. Der Bot kann auf mehreren Discord-Servern gleichzeitig laufen.

## Features

- **Live-Status**: Automatisch aktualisiertes Embed mit Server-Status, Spielerzahlen und Metriken
- **Alerts**: Benachrichtigungen wenn Server online/offline gehen oder Spieler joinen/leaven
- **Multi-Guild**: Kann auf beliebig vielen Discord-Servern eingesetzt werden
- **Auto-Setup**: Erstellt automatisch alle nötigen Channels beim Beitreten

## Bot einladen

### Invite-Link

```
https://discord.com/oauth2/authorize?client_id=1458251194806833306&permissions=34359831568&integration_type=0&scope=bot+applications.commands
```

Der Link ist auch im GSM Dashboard unter den Server-Cards verfügbar.

### Benötigte Permissions

| Permission | Verwendung |
|------------|------------|
| View Channels | Channels sehen |
| Manage Channels | Channels erstellen |
| Send Messages | Nachrichten senden |
| Manage Messages | Eigene Nachrichten bearbeiten |
| Embed Links | Rich Embeds für Status |
| Read Message History | Alte Nachrichten lesen |
| Create Public Threads | Forum-Threads erstellen |

## Automatisch erstellte Channel-Struktur

Wenn der Bot einem Server beitritt, erstellt er automatisch folgende Struktur:

```
🎮 Gameserver (Kategorie)
├── ℹ️│info          - Informationen zum GSM System
├── 📊│status        - Live-Status aller Gameserver (Auto-Update)
├── 📢│alerts        - Server-Events und Spieler-Benachrichtigungen
├── 📰│updates       - Ankündigungen zu neuen Gameservern
├── 💬│diskussion    - Diskussions-Channel (User können schreiben)
└── 💡│requests      - Forum für Gameserver-Vorschläge
```

### Channel-Permissions

| Channel | @everyone | Bot |
|---------|-----------|-----|
| Kategorie | Lesen | Schreiben |
| info | Lesen | Schreiben |
| status | Lesen | Schreiben |
| alerts | Lesen | Schreiben |
| updates | Lesen | Schreiben |
| diskussion | Lesen + Schreiben | Schreiben |
| requests | Lesen + Threads erstellen | Schreiben |

## Datenbank

### guild_settings Tabelle

Speichert die Channel-IDs für jeden Discord-Server:

```sql
CREATE TABLE guild_settings (
  guild_id TEXT PRIMARY KEY,
  category_id TEXT,
  info_channel_id TEXT,
  status_channel_id TEXT,
  status_message_id TEXT,
  alerts_channel_id TEXT,
  updates_channel_id TEXT,
  discussion_channel_id TEXT,
  requests_channel_id TEXT,
  requests_info_thread_id TEXT,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
```

### DB-Funktionen

In `backend/db/init.js`:

```javascript
initGuildSettings()           // Tabelle erstellen
getGuildSettings(guildId)     // Settings für einen Server
getAllGuildSettings()         // Alle Server-Settings
setGuildSettings(guildId, {}) // Settings speichern
deleteGuildSettings(guildId)  // Settings löschen (bei Bot-Kick)
```

## Bot-Events

### guildCreate

Wird ausgelöst wenn der Bot einem neuen Server beitritt:

1. Erstellt Kategorie und alle Channels
2. Postet Info-Nachricht im `ℹ️│info` Channel
3. Erstellt Info-Thread im `💡│requests` Forum
4. Speichert alle Channel-IDs in der Datenbank
5. Sendet erste Status-Nachricht

### guildDelete

Wird ausgelöst wenn der Bot von einem Server entfernt wird:

1. Löscht alle Settings aus der Datenbank

## Status-Updates

Der Bot aktualisiert die Status-Nachricht in allen registrierten Guilds alle 30 Sekunden:

```javascript
async function updateAllGuildStatus() {
  const guilds = getAllGuildSettings();
  for (const guild of guilds) {
    await updateGuildStatus(guild);
  }
}
```

Jeder Server bekommt ein eigenes Embed mit:
- Server-Name und Status (Online/Offline)
- Aktuelle Spielerzahl
- CPU und RAM Auslastung
- Verbindungsadresse

## Konfiguration

### Umgebungsvariablen (.env)

```env
DISCORD_CLIENT_ID=1458251194806833306
DISCORD_CLIENT_SECRET=xxx
DISCORD_BOT_TOKEN=xxx
DISCORD_GUILD_ID=729865854329815051        # Haupt-Server für Login
DISCORD_ADMIN_ROLE_ID=1024693717434650736
DISCORD_MOD_ROLE_ID=1024693170958766141
```

**Hinweis**: `DISCORD_GUILD_ID` wird nur für den Discord OAuth Login verwendet, nicht für den Bot selbst.

### Developer Portal Einstellungen

1. Gehe zu https://discord.com/developers/applications
2. Wähle die Bot-Application
3. **Bot** Tab:
   - "Public Bot" aktivieren (damit andere einladen können)
   - Privileged Gateway Intents:
     - Server Members Intent: Optional
     - Message Content Intent: Nicht benötigt

## Dateien

| Datei | Beschreibung |
|-------|--------------|
| `backend/services/discordBot.js` | Bot-Logik und Event-Handler |
| `backend/db/init.js` | Guild-Settings DB-Funktionen |
| `frontend/src/pages/Dashboard.jsx` | Invite-Button im Dashboard |

## Troubleshooting

### Bot erstellt keine Channels

- Prüfen ob Bot "Manage Channels" Permission hat
- Prüfen ob Bot-Rolle hoch genug in der Rollen-Hierarchie ist

### Status-Nachricht wird nicht aktualisiert

```bash
pm2 logs gameserver-backend --lines 50
```

Suche nach `[DiscordBot]` Log-Einträgen.

### Bot aus Datenbank entfernen

```bash
sqlite3 /opt/gameserver-monitor/backend/users.sqlite
DELETE FROM guild_settings WHERE guild_id = 'xxx';
```

## Login vs. Bot

| Feature | Login (OAuth) | Bot |
|---------|--------------|-----|
| Erfordert Mitgliedschaft | Haupt-Discord | Nein |
| Server-Steuerung | Ja (je nach Rolle) | Nein |
| Status sehen | Ja | Ja |
| Alerts erhalten | Nein | Ja |
| Verfügbar für | Haupt-Discord Mitglieder | Alle mit Bot |

Der Login zur Webapp erfordert Mitgliedschaft im Haupt-Discord-Server (DISCORD_GUILD_ID). Der Bot ist davon unabhängig und zeigt nur passive Status-Updates.