# Nexumi – Phasen-Tracking

Dieses Dokument hält den aktuellen Implementierungsstand fest. Es wird bei jedem Arbeitsfortschritt aktualisiert.

## Assets

- Bot-Logo vorhanden: `docs/logo/nexumi-logo.svg`

## Phase 1 – Fundament (Status: abgeschlossen, manuelle Discord-Tests ausstehend)

### Bereits abgeschlossen

- Monorepo-Basis mit Workspaces:
  - `apps/bot`
  - `packages/shared`
- Basis-Tooling:
  - TypeScript strict
  - ESLint
  - Prettier
  - Vitest
  - Turbo
- Docker-Compose-Grundstack:
  - `postgres` mit Healthcheck
  - `redis` mit Healthcheck
  - `bot`
  - `webui`-Scaffold-Service (temporär)
  - `backups` Volume angebunden
- Prisma-Grundmodell inkl. Moderationsdaten:
  - `Guild`
  - `GuildSettings`
  - `User`
  - `Case`
  - `Warning`
  - `ModNote`
  - `EscalationRule`
- Bot-Grundarchitektur:
  - Sharding-Startpfad
  - Command-Registrierung
  - Command-Routing
  - zentraler Permission-Check
  - Basis-i18n in `@nexumi/shared`
  - Guild-Locale-Auflösung über DB-Settings mit Fallback auf Env-Default
  - Health-Endpoint (`/health`) und token-geschütztes `/metrics`-Scaffold
- BullMQ-Integration:
  - Moderation-Queue
  - Temp-Ban-Expire-Job
  - täglicher Backup-Job (`pg_dump`)
  - Backup-Retention-Cleanup
- Moderation als Referenzmodul (implementiert):
  - `/ban`, `/unban`, `/kick`, `/timeout`, `/untimeout`
  - `/warn add|list|remove|clear`
  - `/warn escalation-set|escalation-list|escalation-remove`
  - `/purge` (Filter: User, Bots, Links, Attachments, Regex)
  - `/slowmode`, `/lock`, `/unlock`
  - `/nick set|reset`
  - `/case view|edit|delete`
  - `/modnote add|list`
  - user-facing Reply-Strings im Moderationsfluss auf i18n-Keys umgestellt (`de`/`en`)
  - Slash-Command-Beschreibungen und Optionstexte lokalisiert (`de` + `en-US` via Discord-Localizations)
  - Bestätigungsflow für destruktive Aktionen (`/ban`, `/purge`, `/case delete`) mit Buttons
  - standardisierte Case-Audit-Metadaten über `@nexumi/shared` (`buildCaseMetadata`)
- Docker-Build/Runtime-Fixes für E2E:
  - `.dockerignore` ergänzt
  - Prisma-Migration beim Bot-Start (`prisma migrate deploy`)
  - Bot-Healthcheck auf `/health`
- E2E-Verifikation (automatisiert, lokal):
  - `docker compose up -d --build` erfolgreich
  - Postgres/Redis healthy
  - Migration `20260722123000_init` angewendet
  - Bot online (`Nexumi#9122`), 13 Slash-Commands registriert
  - Bot-Container healthy
- Tests (aktuell vorhanden):
  - `packages/shared/src/i18n.test.ts`
  - `packages/shared/src/audit.test.ts`
  - `apps/bot/src/modules/moderation/duration.test.ts`

### Manuelle Discord-Tests (noch offen)

- Bot auf Test-Server einladen (falls noch nicht geschehen)
- Slash-Commands testen: `/ban`, `/warn add`, `/purge`, `/case view`
- Bestätigungsbuttons bei `/ban` und `/purge` prüfen

## Phase 2 – AutoMod, Logging, Welcome, Verifizierung (Status: implementiert, manuelle Tests ausstehend)

### Abgeschlossen

- Prisma-Erweiterung + Migration `20260722140000_phase2_modules`:
  - `AutoModConfig`, `AutoModRule`
  - `LoggingConfig`, `LogChannel`
  - `WelcomeConfig`
  - `VerificationConfig`
- Shared-Schemas und Hilfsfunktionen (`packages/shared/src/phase2.ts`)
- **AutoMod** (`apps/bot/src/modules/automod/`):
  - Filter: Spam, Massen-Mentions, Caps, Invite-Links, externe Links, Wortfilter, Duplikate, Emoji-Spam, Zalgo, Phishing-Blockliste
  - Standardregeln werden pro Guild beim ersten Zugriff angelegt
  - Anti-Raid (Join-Rate → Lockdown)
  - Anti-Nuke (Massen-Bans/Channel-Löschungen → Rechteentzug)
  - `/automod status`
  - Phishing-Listen-Refresh via BullMQ (alle 6h + beim Start)
- **Logging** (`apps/bot/src/modules/logging/`):
  - Event-Handler für alle SPEC-Events (Nachrichten, Member, Bans, Rollen, Kanäle, Voice, Invites, Emoji/Sticker, Threads, Guild-Update)
  - Mod-Action-Log verknüpft mit Case-System (`logModAction` in `createCase`)
  - Ignore-Listen (Kanäle, Rollen, Bots) über DB
  - Log-Kanal-Zuordnung über `LogChannel`-Tabelle (Konfiguration künftig WebUI)
- **Welcome/Leave** (`apps/bot/src/modules/welcome/`):
  - Text-, Embed- und Bild-Karten (Canvas via `@napi-rs/canvas`)
  - Platzhalter-System
  - Autoroles (User/Bots getrennt)
  - Welcome-DM
  - `/welcome test`, `/welcome preview`
- **Verifizierung** (`apps/bot/src/modules/verification/`):
  - `/verify setup`, `/verify panel`
  - Button-Verify und Captcha-Verify (Captcha-Seite unter `/verify/captcha` am Health-Server)
  - Mindest-Accountalter, Fehlschlag-Aktionen (Kick/Ban/None)
  - Unverified-Rolle bei Join
- Bot-Intents erweitert:
  - `GuildMembers`, `GuildMessages`, `MessageContent`, `GuildModeration`, `GuildVoiceStates`, `GuildEmojisAndStickers`, `GuildInvites`
- Neue Env-Variable: `PUBLIC_BASE_URL` (Captcha-Links)
- Tests: `packages/shared/src/phase2.test.ts`

### Manuelle Discord-Tests (noch offen)

- **Privileged Intents** im Developer Portal aktivieren:
  - `SERVER MEMBERS INTENT`
  - `MESSAGE CONTENT INTENT`
- AutoMod: Spam-/Invite-Testnachrichten senden
- `/automod status` prüfen
- Logging: Log-Kanäle per DB/ später WebUI setzen, Events auslösen
- `/welcome preview` und `/welcome test` (Konfiguration zunächst per DB oder später WebUI)
- `/verify setup` + `/verify panel`, Button- und Captcha-Flow testen
- `PUBLIC_BASE_URL` auf erreichbare URL setzen (für Captcha außerhalb localhost)

### Hinweise

- Welcome-/Logging-Konfiguration erfolgt in Phase 2 über die Datenbank; die WebUI-Editoren kommen in Phase 7.
- Captcha-Seite läuft am Bot-Health-Port (`HEALTH_PORT`); in Produktion muss `PUBLIC_BASE_URL` darauf zeigen oder über Reverse-Proxy geroutet werden.

## Phase 3 – Leveling, Economy, Utility, Fun (Status: implementiert, manuelle Tests ausstehend)

### Abgeschlossen

- Prisma-Migration `20260722150000_phase3_modules`:
  - `LevelingConfig`, `MemberLevel`, `LevelReward`
  - `EconomyConfig`, `MemberEconomy`, `ShopItem`, `InventoryItem`
  - `Poll`, `PollVote`, `Reminder`, `AfkStatus`
- Shared-Helfer `packages/shared/src/phase3.ts` + Tests
- Commands und Events in Root verdrahtet (`commands.ts`, `index.ts`)

### Leveling (`apps/bot/src/modules/leveling/`)

- `/rank` (Canvas-Rankkarte), `/leaderboard`, `/xp give|remove|reset`
- Text-XP (Cooldown Redis) und Voice-XP
- Multiplikatoren, No-XP-Kanäle/-Rollen, Level-Rewards, Level-Up CHANNEL/DM/OFF

### Economy (`apps/bot/src/modules/economy/`)

- `/balance`, `/daily`, `/weekly`, `/work`, `/pay`
- `/gamble`, `/slots`, `/blackjack` (Buttons), `/coinflip` (Wette)
- `/shop view|buy`, `/inventory`, `/eco leaderboard|give|remove|reset`
- Währung pro Server in `EconomyConfig`

### Utility (`apps/bot/src/modules/utility/`)

- `/userinfo`, `/serverinfo`, `/roleinfo`, `/channelinfo`, `/avatar`, `/banner`
- `/poll create` (Buttons, DB, Ablauf via BullMQ)
- `/remindme`, `/reminders list|delete` (BullMQ)
- `/afk set`, `/emoji add|remove|steal`, `/sticker add`, `/timestamp`
- Context-Menu **Translate**, `/snipe`, `/editsnipe`, `/embed builder`

### Fun (`apps/bot/src/modules/fun/`)

- `/8ball`, `/dice`, `/flip` (freier Münzwurf; Economy behält `/coinflip`)
- `/rps`, `/choose`, `/trivia`, `/tictactoe`, `/connect4`, `/hangman`
- `/meme`, `/cat`, `/dog` (abschaltbar via Redis `fun:config:{guildId}`)

### Manuelle Discord-Tests (Phase 3 – bestätigt)

- Manuell auf Test-Server bestätigt (User-Freigabe).

## Phase 4 – Giveaways … Temp-Voice (Status: abgeschlossen, manuell bestätigt)

- Manuell auf Test-Server bestätigt (User-Freigabe).

## Phase 5 – Stats/Invites, Feeds, Scheduler, Guild-Backup (Status: abgeschlossen, manuell bestätigt)

### Abgeschlossen

- Prisma-Migration `20260722170000_phase5_modules` (deployed)
- Shared `packages/shared/src/phase5.ts` + Tests
- Module verdrahtet in `commands.ts`, `index.ts`, `jobs.ts`
- Queues/Worker: `stats`, `feeds`, `schedules`, `guild-backups`
- Optional: `TWITCH_CLIENT_ID` / `TWITCH_CLIENT_SECRET`
- E2E: `docker compose up -d --build bot` OK; Bot ready; 74 Guild-Commands registriert
- Manuell auf Test-Server bestätigt (User-Freigabe)
- Temp-Voice Control-Panel postet in den Voice-Kanal-Chat (statt DM)

## Phase 6 – WebUI-Fundament (Status: implementiert, manuelle Tests ausstehend)

### Abgeschlossen

- `apps/webui` als `@nexumi/webui` (Next.js 15 App Router, Tailwind 4, React 19), Scripts `dev/build/start/lint/typecheck/test/prisma:generate`
- `next.config.ts`: `output: 'standalone'`, `transpilePackages: ['@nexumi/shared']`, `outputFileTracingRoot` auf Monorepo-Root
- Env-Validierung (`src/lib/env.ts`, Zod): `DATABASE_URL`, `REDIS_URL`, `BOT_CLIENT_ID`, `BOT_CLIENT_SECRET`, `WEBUI_URL`, `SESSION_SECRET` (≥32 Zeichen), `SENTRY_DSN` optional, `DEFAULT_LOCALE`
- Discord-OAuth2-Login (`src/lib/discord-oauth.ts`): Authorize-URL, Code-Exchange, `/users/@me`, `/users/@me/guilds` (mit kurzlebigem Redis-Cache)
- Redis-Sessions (`src/lib/session.ts`): Cookie `nexumi_session` (httpOnly, sameSite=lax, secure in Produktion, 7 Tage), signiert via HMAC (`SESSION_SECRET`), Redis-Key `webui:session:{id}`
- Auth-Helfer (`src/lib/auth.ts`): `requireAuth`/`requireAuthOrRedirect`, `requireGuildAccess`/`requireGuildAccessOrRedirect` (Manage-Guild-Check + Bot-Präsenz in der DB), `toApiErrorResponse`
- `src/lib/guilds.ts`, `src/lib/guild-settings.ts`, `src/lib/modules.ts`, `src/lib/access-rules.ts`, `src/lib/audit.ts` (Dashboard-Audit-Log lesen/schreiben)
- Modul-Status-Aggregation (`getModuleStatuses`/`updateModuleStatuses`) über bestehende Prisma-Configs (AutoMod, Logging, Welcome, Verification, Leveling, Economy, Tickets, Starboard, Suggestions, Birthdays, TempVoice, Stats), Fun-Redis-Config (`fun:config:{guildId}`, neues Feld `enabled`) sowie einen generischen Redis-Hash `dashboard:modules:{guildId}` für Module ohne eigenes Enabled-Flag (Giveaways, Tags, Selfroles, Feeds, Scheduler, Guildbackup)
- Settings-Framework (`src/components/settings/`): `settings-form.tsx` (Dirty-Tracking, Sticky-Save-Bar, Toasts, Inline-Fehler), `save-bar.tsx`, `general-settings-form.tsx`, `module-toggles-form.tsx`, `access-rules-form.tsx`
- Layout (`src/components/layout/`): `theme-provider.tsx` (next-themes, Dark als Standard), `sidebar.tsx` (Modul-Gruppen aus `DASHBOARD_MODULES`), `server-switcher.tsx`, `user-menu.tsx`, `dashboard-shell.tsx`
- shadcn-artige UI-Komponenten (`src/components/ui/`): Button, Card, Input, Label, Switch, Select, Separator, Skeleton, Avatar, Badge, Dropdown-Menu — Indigo-Akzent (`#6366F1`) über CSS-Variablen in `globals.css`, Inter-Font via `next/font/google`
- i18n (`src/lib/i18n.ts`, `src/messages/de.json`, `src/messages/en.json`): Cookie `nexumi_locale`, vollständige de/en-Strings für Login, Dashboard, Settings, Module, Access, Fehler
- Seiten: `/`, `/login`, `/dashboard`, `/dashboard/[guildId]` (Übersicht mit Modul-Status + letzten 10 Audit-Einträgen), `/dashboard/[guildId]/settings`, `/dashboard/[guildId]/modules`, `/dashboard/[guildId]/access`, `/dashboard/[guildId]/[module]` (Platzhalter „Modul-Einstellungen kommen in Phase 7", i18n) — Skeleton-Ladezustände über `loading.tsx` je Route
- `middleware.ts`: leichte Edge-Prüfung auf vorhandenes Session-Cookie für `/dashboard/*`; vollständige Session-/Berechtigungsprüfung serverseitig in den Layouts
- API-Routen (alle Zod-validiert, Auth-geprüft, schreiben Dashboard-Audit bei PATCH/PUT): `GET /api/health`, `GET /api/auth/login`, `GET /api/auth/callback`, `POST /api/auth/logout`, `GET /api/auth/me`, `GET /api/guilds`, `GET|PATCH /api/guilds/[guildId]/settings`, `GET|PATCH /api/guilds/[guildId]/modules`, `GET|PUT /api/guilds/[guildId]/access-rules`, `GET /api/guilds/[guildId]/audit`
- `apps/webui/Dockerfile` (Multi-Stage: `pnpm --filter @nexumi/shared build`, `prisma generate --schema=../bot/prisma/schema.prisma`, `next build`, Standalone-Runner, `HEALTHCHECK` auf `/api/health`, `EXPOSE 3000`)
- `docker-compose.yml`: `webui`-Service baut jetzt aus `apps/webui/Dockerfile`, `env_file: .env`, `depends_on` Postgres/Redis (healthy), Healthcheck, bestehende Traefik-Labels beibehalten
- `.env.example` ergänzt um `WEBUI_URL`, `SESSION_SECRET` (Kommentar: ≥32 Zeichen); lokale `.env` um `WEBUI_URL` und generiertes `SESSION_SECRET` ergänzt (keine bestehenden Werte überschrieben)
- Tests: `src/lib/utils.test.ts` (`cn()`), bestehende `packages/shared/src/phase6.test.ts` (Zod-Schemas, `hasManageGuildPermission`)

### Manuelle Tests (noch offen)

- Discord Developer Portal: OAuth2-Redirect `http://localhost:3000/api/auth/callback` (bzw. `https://nexumi.de/api/auth/callback` in Produktion) unter „OAuth2 → Redirects" eintragen
- Login-Flow Ende-zu-Ende (`http://localhost:3000/login` → Discord → `/dashboard`)
- Zugriff ohne „Server verwalten" prüfen
- Modul-Toggles + Access-Rules speichern; Audit-Log prüfen

### Deploy-Verifikation (automatisiert)

- `docker compose up -d --build bot webui` OK
- Migration `20260722180000_phase6_webui` angewendet (`DashboardAccessRule`, `DashboardAuditLog`, `GuildSettings.timezone`)
- Bot healthy + ready; WebUI healthy (`/api/health` → `{"ok":true}`), Login-Seite erreichbar
- Checks: shared tests 23, webui typecheck/lint/test grün

## Nächster geplanter Schritt

- Nach Freigabe der manuellen Phase-6-Tests: Phase 7 (Modul-Seiten je Modul + Owner-Panel).