Refactor giveaway job processing and update environment documentation

- Improved the `giveawayCreate` job handling in the bot's job processing, ensuring consistent functionality with existing commands.
- Enhanced the `.env.example` file to provide clearer instructions on the usage of `BOT_TOKEN` for both the bot and WebUI.
- Added the `bullmq` dependency to the WebUI package for better job management capabilities.

apps/webui/src/app/api/guilds/[guildId]/guildbackup/[backupId]/download/route.ts

@@ -0,0 +1,29 @@
+import { type NextRequest, NextResponse } from 'next/server';
+import { requireGuildAccess, toApiErrorResponse } from '@/lib/auth';
+import { getGuildBackupRecord } from '@/lib/module-configs/guildbackup';
+
+interface RouteParams {
+  params: Promise<{ guildId: string; backupId: string }>;
+}
+
+export async function GET(_request: NextRequest, { params }: RouteParams) {
+  const { guildId, backupId } = await params;
+  try {
+    await requireGuildAccess(guildId);
+    const backup = await getGuildBackupRecord(guildId, backupId);
+    if (!backup) {
+      return NextResponse.json({ error: 'Backup not found' }, { status: 404 });
+    }
+
+    const filename = `nexumi-backup-${backup.name.replace(/[^a-z0-9-_]+/gi, '_')}-${backup.id}.json`;
+    return new NextResponse(JSON.stringify(backup.payload, null, 2), {
+      status: 200,
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Disposition': `attachment; filename="${filename}"`
+      }
+    });
+  } catch (error) {
+    return toApiErrorResponse(error);
+  }
+}

apps/webui/src/app/api/guilds/[guildId]/guildbackup/[backupId]/restore/route.ts

@@ -0,0 +1,47 @@
+import { type NextRequest, NextResponse } from 'next/server';
+import { ForbiddenError, requireGuildAccess, toApiErrorResponse } from '@/lib/auth';
+import { writeDashboardAudit } from '@/lib/audit';
+import { fetchDiscordUserGuildsCached } from '@/lib/discord-oauth';
+import { enqueueGuildBackupRestore, getGuildBackupRecord } from '@/lib/module-configs/guildbackup';
+import { prisma } from '@/lib/prisma';
+
+interface RouteParams {
+  params: Promise<{ guildId: string; backupId: string }>;
+}
+
+/**
+ * Restore is intentionally restricted to the Discord server owner, per SPEC
+ * ("Restore nur durch Server-Owner mit doppelter Bestätigung"). The double
+ * confirmation itself happens client-side before this request is sent.
+ */
+export async function POST(_request: NextRequest, { params }: RouteParams) {
+  const { guildId, backupId } = await params;
+  try {
+    const session = await requireGuildAccess(guildId);
+
+    const guilds = await fetchDiscordUserGuildsCached(session.accessToken);
+    const guild = guilds.find((entry) => entry.id === guildId);
+    if (!guild?.owner) {
+      throw new ForbiddenError('Only the Discord server owner can restore a backup');
+    }
+
+    const backup = await getGuildBackupRecord(guildId, backupId);
+    if (!backup) {
+      return NextResponse.json({ error: 'Backup not found' }, { status: 404 });
+    }
+
+    await enqueueGuildBackupRestore(backupId, guildId, session.user.id);
+
+    await writeDashboardAudit(prisma, {
+      guildId,
+      actorUserId: session.user.id,
+      action: 'guildbackup.restore',
+      path: `/dashboard/${guildId}/backup`,
+      after: { backupId }
+    });
+
+    return NextResponse.json({ ok: true, queued: true });
+  } catch (error) {
+    return toApiErrorResponse(error);
+  }
+}

apps/webui/src/app/api/guilds/[guildId]/guildbackup/[backupId]/route.ts

@@ -0,0 +1,54 @@
+import { GuildBackupPayloadSchema } from '@nexumi/shared';
+import { type NextRequest, NextResponse } from 'next/server';
+import { requireGuildAccess, toApiErrorResponse } from '@/lib/auth';
+import { writeDashboardAudit } from '@/lib/audit';
+import { deleteGuildBackupDashboard, getGuildBackupRecord } from '@/lib/module-configs/guildbackup';
+import { prisma } from '@/lib/prisma';
+
+interface RouteParams {
+  params: Promise<{ guildId: string; backupId: string }>;
+}
+
+export async function GET(_request: NextRequest, { params }: RouteParams) {
+  const { guildId, backupId } = await params;
+  try {
+    await requireGuildAccess(guildId);
+    const backup = await getGuildBackupRecord(guildId, backupId);
+    if (!backup) {
+      return NextResponse.json({ error: 'Backup not found' }, { status: 404 });
+    }
+    const parsed = GuildBackupPayloadSchema.safeParse(backup.payload);
+    return NextResponse.json({
+      id: backup.id,
+      name: backup.name,
+      createdById: backup.createdById,
+      createdAt: backup.createdAt.toISOString(),
+      payload: parsed.success ? parsed.data : null
+    });
+  } catch (error) {
+    return toApiErrorResponse(error);
+  }
+}
+
+export async function DELETE(_request: NextRequest, { params }: RouteParams) {
+  const { guildId, backupId } = await params;
+  try {
+    const session = await requireGuildAccess(guildId);
+    const deleted = await deleteGuildBackupDashboard(guildId, backupId);
+    if (!deleted) {
+      return NextResponse.json({ error: 'Backup not found' }, { status: 404 });
+    }
+
+    await writeDashboardAudit(prisma, {
+      guildId,
+      actorUserId: session.user.id,
+      action: 'guildbackup.delete',
+      path: `/dashboard/${guildId}/backup`,
+      before: { backupId }
+    });
+
+    return NextResponse.json({ ok: true });
+  } catch (error) {
+    return toApiErrorResponse(error);
+  }
+}

apps/webui/src/app/api/guilds/[guildId]/guildbackup/route.ts

@@ -0,0 +1,44 @@
+import { GuildBackupCreateDashboardSchema } from '@nexumi/shared';
+import { type NextRequest, NextResponse } from 'next/server';
+import { requireGuildAccess, toApiErrorResponse } from '@/lib/auth';
+import { writeDashboardAudit } from '@/lib/audit';
+import { createGuildBackupDashboard, listGuildBackupsDashboard } from '@/lib/module-configs/guildbackup';
+import { prisma } from '@/lib/prisma';
+
+interface RouteParams {
+  params: Promise<{ guildId: string }>;
+}
+
+export async function GET(_request: NextRequest, { params }: RouteParams) {
+  const { guildId } = await params;
+  try {
+    await requireGuildAccess(guildId);
+    const backups = await listGuildBackupsDashboard(guildId);
+    return NextResponse.json({ backups });
+  } catch (error) {
+    return toApiErrorResponse(error);
+  }
+}
+
+export async function POST(request: NextRequest, { params }: RouteParams) {
+  const { guildId } = await params;
+  try {
+    const session = await requireGuildAccess(guildId);
+    const body = await request.json();
+    const input = GuildBackupCreateDashboardSchema.parse(body);
+
+    const backup = await createGuildBackupDashboard(guildId, input.name, session.user.id);
+
+    await writeDashboardAudit(prisma, {
+      guildId,
+      actorUserId: session.user.id,
+      action: 'guildbackup.create',
+      path: `/dashboard/${guildId}/backup`,
+      after: backup
+    });
+
+    return NextResponse.json(backup, { status: 201 });
+  } catch (error) {
+    return toApiErrorResponse(error);
+  }
+}