Werkzeug-Musterstrecke

Referenzimplementierung für Upload → Verarbeitung → Download. Sync oder asynchron als Job (@/jobs). Ohne Datenbank, ohne Auth.

Datei verarbeiten

Text-Datei hochladen — der Server analysiert Inhalt (Bytes, Zeichen, Wörter, Zeilen) und erzeugt ein herunterladbares Ergebnis-Dokument.

Lange Verarbeitung (asynchron als Job) — z. B. OCR/KI

Die Zustände

Das Zustandsmodell der Upload-Zone — explizit als Union, nicht als Boolean-Kombinatorik. Der asynchrone Pfad (#21) ergänzt queued.

idle

Initialzustand — Dropzone sichtbar, keine Datei ausgewählt.

validating

Datei ausgewählt — Client-Prüfung (Endung/Größe) läuft.

processing

Synchron: Client-Prüfung bestanden — Server verarbeitet im Request.

queued

Async (#21): Job über @/jobs eingereicht — Status wird per Polling abgefragt.

error

Fehler (falscher Typ, zu groß, Job fehlgeschlagen) — mit deutscher Meldung.

done

Verarbeitung abgeschlossen — Ergebnis kann heruntergeladen werden.

Datei-Struktur (was wo anpassen)

Vier Dateien bilden die Musterstrecke — tauschen Sie die Beispiele aus.

src/lib/werkzeug.tsPure Logik

Regeln + Verarbeitung (hier: Textanalyse). Ersetze analyzeText/formatResult.

src/lib/werkzeug.test.tsTests

Vitest-Tests für die Pure Functions (neben der Quelle, Repo-Konvention).

src/pages/api/werkzeug/process.tsAPI-Route

HTTP-Dünnschicht: Body-Limit, Auth, FormData. Zwei Pfade (mode=sync/async); async reicht über @/jobs submit() ein.

src/components/react/UploadZone.tsxReact-Island

Zustandsmodell + Dropzone + Download. Async-Pfad mit Polling (api/jobs/[id]) und localStorage-Wiederherstellung.

Lange Verarbeitungen: asynchron über @/jobs (Issue #21)

Aktivieren Sie den Umschalter „Lange Verarbeitung (asynchron)" in der Upload-Zone, läuft die Verarbeitung als Hintergrund-Job über die öffentliche @/jobs-Schnittstelle (submit). Die Seite pollt api/jobs/[id] bis zum Ergebnis. Sie können den Tab schließen und zurückkehren — der Job läuft serverseitig weiter, die Job-ID wird clientseitig (mit Ablauf) gespeichert und beim Laden wiederhergestellt.

Einschränkung (In-Memory, ADR-0008): laufende Jobs gehen bei einem Container-Neustart verloren, fertige Ergebnisse nach Ablauf der TTL. Für dauerhaften Betrieb lässt sich @/jobs später durch einen Valkey-Adapter ersetzen (Rezept-Ticket #22) — ohne Änderung an dieser Strecke, da ausschließlich die öffentliche Schnittstelle verwendet wird.