API & Server Actions — Überblick

Die School-SaaS-Plattform setzt nicht auf ein klassisches REST-CRUD-API. Datenmutationen (Anlegen, Ändern, Löschen von Schülern, Klassen, Fächern, Lehrkräften usw.) laufen über Next.js Server Actions in lib/*/actions.ts. HTTP-API-Routen (app/api/**/route.ts) existieren nur dort, wo eine externe Gegenstelle (Stripe, Cron, OAuth-Callback, E-Mail-Links) oder ein eigenständiges Session-System (Portal) eine echte URL benötigt.

Datenzugriff: Server Actions statt REST

Es gibt keine Endpoints wie /api/students, /api/teachers, /api/classes oder /api/subjects. Das CRUD für diese Domänen findet über Server Actions statt:

// Beispiel: lib/student/actions.ts
'use server';

import { auth } from '@/auth';
import { hasPermission } from '@/lib/permissions';

export async function createStudent(input: StudentInput) {
    const session = await auth();
    if (!session?.user?.tenantId) throw new Error('Nicht angemeldet');

    const allowed = await hasPermission(session, 'students', 'create');
    if (!allowed) throw new Error('Keine Berechtigung');

    // Zod-Validierung → DB-Funktion in lib/student/db.ts
}

• Datenfetching erfolgt in Server Components direkt über die DB-Funktionen in lib/*/db.ts (gefiltert nach tenant_id aus der Session).
• Mutationen laufen über Server Actions, die auth(), hasPermission() und Zod-Validierung kombinieren und anschließend revalidatePath() aufrufen.

Details: Architektur-Übersicht und Berechtigungssystem.

Tatsächlich vorhandene HTTP-API-Routen

Verzeichnis: app/api/. Diese Routen werden in proxy.ts teilweise von der Auth-Prüfung ausgenommen (siehe apiRoutes).

Auth (/api/auth/*)

Route	Methode	Zweck
/api/auth/[...nextauth]	GET/POST	NextAuth-Handler (Callbacks, Session, Sign-in/out)
/api/auth/login	POST	Credentials-Login
/api/auth/logout	POST	Abmeldung
/api/auth/refresh	POST	Session/Token-Refresh
/api/auth/verify	GET	Session-Verifikation
/api/auth/cleanup-sessions	GET/POST	Admin: Sessions inaktiver User bereinigen / Statistiken

Registrierung & E-Mail

Route	Methode	Zweck
/api/verify-email	—	E-Mail-Verifikation auslösen
/api/verify-email/[token]	—	Verifikations-Token einlösen
/api/set-password	POST	Passwort nach Verifikation setzen

Stripe (/api/stripe/*)

Route	Zweck
/api/stripe/webhook	Stripe-Webhook-Empfänger (Signatur-Verifikation)
/api/stripe/create-setup-intent	Setup-Intent für regulären Checkout (Elements)
/api/stripe/create-checkout-session	Checkout-Session erzeugen
/api/stripe/create-subscription-checkout-session	Subscription-Checkout
/api/stripe/create-trial-checkout-session	Trial-Checkout (Hosted Checkout)
/api/stripe/create-portal-session	Stripe Customer Portal
/api/stripe/get-all-products	Aktive Produkte/Preise live aus Stripe laden

Siehe Stripe Integration Setup.

File Storage (/api/files/*, /api/admin/files/*)

Route	Methode	Zweck
/api/files	GET	Dateiliste (Filter, Pagination)
/api/files/upload	POST	Datei hochladen (FormData)
/api/files/[id]/download	GET	Datei herunterladen (Permission-Check)
/api/files/public/[id]	GET	Öffentliche Datei (anonym, Redirect zur Blob-URL)
/api/admin/files	GET	Admin: Dateien auflisten
/api/admin/files/[id]	DELETE	Admin: Datei löschen
/api/admin/files/[id]/archive	POST	Admin: Datei archivieren

Siehe File Storage — Architektur.

Cron (/api/cron/*)

Route	Schedule	Zweck
/api/cron/check-expired-files	täglich 02:00	Abgelaufene Dateien markieren
/api/cron/delete-non-critical-files	täglich 03:00	Unkritische abgelaufene Dateien physisch löschen

Authentifizierung per CRON_SECRET (Bearer-Token). Schedules in vercel.json.

Portal (/api/portal/*)

Eigenständiges Session-System für das Schüler-/Eltern-Portal (unabhängig von NextAuth).

Route	Zweck
/api/portal/auth/login	Portal-Login
/api/portal/auth/logout	Portal-Logout
/api/portal/auth/session	Portal-Session abrufen
/api/portal/activate	Portal-Zugang über Einladungs-/Aktivierungslink aktivieren
/api/admin/portal/invite	Admin: Portal-Einladung erstellen

User & Sonstiges

Route	Zweck
/api/user/subscription	Abonnement-Status des aktuellen Users
/api/user/set-professional-plan	Plan auf Professional setzen
/api/test/trial-expired	Test-Endpoint für abgelaufenen Trial

Authentifizierung & Zugriffsschutz

• Backend-Routen werden über proxy.ts (Next.js-Middleware) geschützt — siehe Session-Sicherheit.
• Server Actions und geschützte API-Routen prüfen die Session zusätzlich serverseitig (auth() bzw. getSession() für das Portal) plus hasPermission() für granulare Rechte.
• Es gibt keinen API-Key-Mechanismus für externe Konsumenten; der Zugriff erfolgt über die Session-Cookies der jeweiligen App.