# TacForce Pro — Architektur & Integration

Wie alles zusammenspielt, und **wie du neue Bots einbindest**.

## 1. Gesamtbild

```
                    ┌──────────────────────────────────────────┐
   Browser  ───────▶│  XAMPP: Apache + PHP  →  Laravel-App      │
   (Admin/User)     │  • Website (Landing, Pricing, Features)   │
                    │  • Discord OAuth Login (Socialite)        │
                    │  • Dashboard  /dashboard/{guild}/…        │
                    │  • Admin-Panel /admin (Nutzer/Server/Bots)│
                    └───────────────┬──────────────────────────┘
                                    │ Eloquent (PDO)
                            ┌───────▼────────┐
                            │  MySQL / Maria │  ◀── EINE gemeinsame DB
                            │  (XAMPP)       │
                            └───────▲────────┘
                                    │ mysql2 (Node)
                    ┌───────────────┴──────────────────────────┐
   Discord  ◀──────▶│  bot-worker/ (Node.js + discord.js)       │
   Gateway/API      │  • Multi-Bot-Loader (liest `bots`-Tabelle)│
                    │  • Ticket-, Bewerbungs-, Welcome/Log-Logik│
                    │  • Slash-Commands, Buttons, Modals        │
                    └──────────────────────────────────────────┘
```

**Kernprinzip:** Die Laravel-App und der Bot teilen sich **eine MySQL-Datenbank**. Das Dashboard schreibt Konfiguration (Ticket-Kategorien, Bewerbungsformulare, Settings), der Bot liest sie zur Laufzeit. Der Bot schreibt Ergebnisse zurück (erstellte Tickets, eingegangene Bewerbungen, Audit-Logs), die das Dashboard anzeigt.

## 2. Warum getrennt?

- **Apache/PHP** arbeitet pro HTTP-Request und beendet sich danach → kann keine Dauerverbindung halten.
- **Ein Discord-Bot** braucht eine permanente WebSocket-Verbindung (Gateway) → braucht einen **langlebigen Prozess** = Node.js.
- Lösung: zwei Prozesse, eine DB. Das ist Standard-Architektur für Bot-Dashboards.

## 3. Datenfluss-Beispiel (Ticket)

1. Admin legt im Dashboard eine **Ticket-Kategorie** an → Zeile in `ticket_categories` (MySQL).
2. Admin klickt „Panel senden" → Laravel schreibt einen Auftrag in `bot_jobs` (Outbox-Tabelle) **oder** ruft eine kleine Bot-HTTP-Route auf (siehe §6).
3. Der Bot pollt `bot_jobs` (alle paar Sekunden) → postet das Ticket-Panel in den Discord-Channel.
4. Ein User klickt „Ticket öffnen" → der Bot erstellt einen privaten Channel und eine Zeile in `tickets`.
5. Das Dashboard zeigt das offene Ticket sofort an (liest `tickets`).

> **MVP-Vereinfachung:** Wir nutzen die **Outbox-Tabelle `bot_jobs`** (der Bot pollt sie). Das braucht keinen offenen Port, funktioniert hinter jeder Firewall und ist robust. Später optional: direkte HTTP-Bridge (§6).

## 4. Multi-Bot: Wie man neue Bots einbindet

Das ist bewusst so gebaut, dass du **mehrere Bots** betreiben kannst (z. B. TacForce Operator + White-Label-Bots für Kunden).

### Tabelle `bots`
| Feld | Zweck |
|------|-------|
| `id` | interne ID |
| `name` | Anzeigename (z. B. „TacForce Operator", „AcmeClan Bot") |
| `discord_client_id` | Application-/Client-ID der Discord-App |
| `discord_token` | Bot-Token (**verschlüsselt** gespeichert, siehe unten) |
| `discord_public_key` | für Interaction-Verifizierung |
| `is_active` | an/aus |
| `owner_user_id` | wem gehört der Bot (für White-Label) |
| `avatar_url`, `accent_color` | Branding |
| `created_at`, `updated_at` | |

### So bindest du einen neuen Bot ein (im Admin-Panel `/admin/bots`)
1. **Discord-App anlegen:** https://discord.com/developers/applications → *New Application* → Bot-Tab → Token kopieren, Client-ID + Public Key kopieren.
2. Im Admin-Panel **„Bot hinzufügen"** → Name, Client-ID, Token, Public Key eintragen. Token wird via Laravel `Crypt::encryptString()` verschlüsselt in der DB abgelegt.
3. Speichern → `is_active = true`.
4. Der **Bot-Worker** erkennt den neuen Eintrag beim nächsten Start (oder Reload-Command) und startet automatisch eine weitere `Client`-Instanz mit diesem Token (Multi-Bot-Loader in `bot-worker/src/manager.js`).
5. Slash-Commands für den neuen Bot registrieren: `npm run register -- --bot <id>`.

### Sicherheit der Tokens
- Tokens werden **verschlüsselt** in MySQL gespeichert (Laravel `Crypt`, AES-256, Key aus `APP_KEY`).
- Der Bot-Worker entschlüsselt sie mit **demselben `APP_KEY`** (in `bot-worker/.env` gespiegelt) — deshalb muss `APP_KEY` in beiden `.env` identisch sein.
- Tokens erscheinen **nie** im HTML/Frontend (im Admin nur maskiert: `••••••••1a2b`).

## 5. Berechtigungen

- **Login:** Discord OAuth (Scopes `identify`, `guilds`). Nach Login holt Laravel die Guild-Liste des Users von der Discord-API und filtert auf Server, wo er `MANAGE_GUILD` (oder Admin) hat.
- **Guild-Zugriff:** `GuildPolicy` prüft bei jeder `/dashboard/{guild}/…`-Route, ob der User Rechte auf genau diesem Server hat (`guild_member_permissions`).
- **Admin-Panel:** `EnsureUserIsAdmin`-Middleware — nur User mit `is_admin = true` (in `.env` als `ADMIN_DISCORD_IDS` hinterlegte Betreiber-IDs beim Seed/Login gesetzt).

## 6. Optionale Bot-Bridge (später)

Statt Outbox-Polling kann der Bot eine kleine, **nur lokal erreichbare** Express-Route anbieten (`POST /internal/panel`), die Laravel mit einem geteilten `BOT_INTERNAL_SECRET` aufruft. Für den MVP nicht nötig — Outbox reicht.

## 7. Deployment-Ziel

- **Laravel-App:** in `C:\xampp\htdocs\tacforce\laravel-app` → Apache-vHost auf `public/` (SETUP-XAMPP.md §5).
- **Bot-Worker:** dauerhaft laufender Node-Prozess (lokal `npm start`, später PM2 / Windows-Dienst / kleiner VPS).
- **MySQL:** XAMPP-MySQL, Datenbank `tacforce`.