feat(demo): prepared sample requests from recorded AI answers

[Fluory]

Warum

Fixes #71 · Teil von Epic #19 (Showcase-Review 2026-09-27, P0)

Arbeitsstand

• Ziel: Jeder Besucher des Showcase sieht ohne eigene Datei einen vollständigen Fall – Original, erkannte Werte mit Quellen, Prüfentscheidung und Exportbeleg –, auch wenn der Modellanbieter gerade überlastet ist.
• Nicht-Ziele: nächtlicher Reset, öffentlicher Gastzugang, neue Extraktionslogik.
• Erledigt: Quelle sample + Migration 0019; Modul samples, pnpm seed:samples, pnpm samples:record; beide Aufnahmen; Kennzeichnung in Liste und Detail; Befunde des frischen Reviews: Export: die Freigabe reiht den Export-Job wie immer ein, der Seed führt genau diesen Job sofort aus (spätere Zustellung → skipped; ERP-Ausfall → die Warteschlange wiederholt), Quelle in der Intake-Transaktion, nur „eingeschwungene“ Status zählen, Fehlerpfad → ERROR ohne Live-Reprocess, Aufnahme per Vertrags-Schema validiert, keine Tokens/Latenz für das Abspielen; Unit-, Integrations- und E2E-Tests; Doku.
• Offen: Merge (Freigabe des Orchestrators liegt vor, 2026-09-27 „OK“); danach Migration im Showcase (pnpm setup:deploy), pnpm seed:samples, Screenshots.
• Annahmen: Die Demo-Firmen existieren (Seed pnpm seed:demo bzw. Runbook §6).
• Nächster kleinster Schritt: Merge, dann Migration und Seed im Showcase.

Was ist passiert (Klartext)

Bisher gab es im Showcase nur Anfragen, die jemand selbst hochgeladen hat – und wenn Googles Modell gerade überlastet ist, sieht ein Besucher nur Fehlversuche (so am 27.09. einen halben Nachmittag lang). Jetzt legt ein Befehl feste Beispiel-Anfragen an: eine zum Prüfen (mit einem unsicheren Liefertermin und einer fehlenden Angabe) und eine, die schon freigegeben und ans ERP übergeben ist, mit sichtbarer ERP-Nummer. Ihre KI-Auswertung wurde einmal aufgezeichnet und wird beim Anlegen wiederverwendet, sodass sie nie vom Modellanbieter abhängt. Beide sind in Liste und Detailansicht als „Vorbereitetes Beispiel – aufgezeichnete KI-Antwort“ gekennzeichnet. Der Befehl lässt sich jederzeit wiederholen und legt nur an, was fehlt; bricht er ab, bleibt nichts halb fertig „in Verarbeitung“ hängen. Die Datenbank bekommt dafür eine kleine zusätzliche Prüfregel (Herkunft einer Anfrage: Upload oder Beispiel).

Plan-Pflicht (SYSTEM.md §4)

• Kein Auslöser – keine Modulgrenze, öffentliche API, Migration, Auth/Rechte, kein Zahlungs-/Daten-/Infrapfad, höchstens zwei Module, keine Architekturvarianten, umkehrbar
• Auslöser zutreffend – Impact Manifest ausgefüllt (Plan vor Code)

Impact Manifest

• Betroffene Module: neues Modul samples (src/features/samples/) mit Einstiegen src/seed-samples.ts und src/samples-record.ts; requests (source bei createRequest, countSamples()); intake (optionale Quelle bei submitUpload, Standard upload); jobs (markProcessingFailed = bisheriges markError öffentlich; reprocessRequest lehnt die Verarbeitung eines Beispiels ab); extraction (parseExtractResponse() – derselbe Parser für Live-Antworten und Aufnahmen); app (Kennzeichnung, kein „Erneut verarbeiten“ für ein Beispiel im Verarbeitungsfehler); DB-Schema (Migration 0019). Genutzt, nicht geändert: review (Freigabe), export (Export-Job, ERP-Adapter).
• Schnittstellen / Datenänderungen: Migration 0019 – additiver CHECK source in ('upload', 'sample'), alle bestehenden Zeilen sind upload. Keine API-Änderung. Der Seed legt pro Demo-Firma bis zu zwei Anfragen mit source = 'sample' an.
• Akzeptanzkriterien: die aus feat(demo): prepared sample request that is always viewable #71, inklusive des ergänzten exportierten Beispiels.
• Testplan: Integration gegen Postgres + pg-boss + S3 mit ERP-Mock in-process: Beispiel in Prüfung (uncertain + missing, Lauf recorded:…, 0 Tokens/Latenz), exportiertes Beispiel mit genau einer Export-Zeile, ERP-Referenz und einem Audit-Ereignis, keine Jobs in der Warteschlange; Idempotenz; ERP-Ausfall → APPROVED + Export-Job; Abbruch → ERROR, Reprocess abgelehnt, nächster Lauf ersetzt; Constraint (SQLSTATE 23514). Unit: Aufnahmen gültig, aufgezeichneter Client, frische Message-ID. E2E: Kennzeichnung in Liste und Detail, ERP-Referenz.
• Verifizierte Fakten: requests.source existiert (Standard upload, ohne CHECK); processRequestJob ist idempotent und nimmt den KI-Client als Abhängigkeit; submitUpload nimmt einen JobSender als Abhängigkeit; approveRequest stellt den Export-Job transaktional ein.
• Offene Annahmen: keine – die Aufzeichnung werk-ost enthält uncertain und missing (geprüft); die Message-ID ist in keiner Aufzeichnung ein Segment (geprüft), der Austausch pro Seed ändert also keinen Beleg.
• Nicht-Ziele: nächtlicher Reset, Gastzugang.
• Risiken und Rollback: Migration umkehrbar per DROP CONSTRAINT; Beispiel-Anfragen sind normale synthetische Anfragen und lassen sich ablehnen. Menschliche Freigabe vor dem Merge (Migration, SYSTEM.md §5).

Geändert

• src/db/schema/app.ts, src/db/migrations/0019_request_source_check.sql: Quelle sample + CHECK source in ('upload', 'sample')
• src/features/samples/ (neu): samples.ts (Definitionen, frische Message-ID je Seed, validierte Aufnahmen, aufgezeichneter Client: Modell-ID recorded:…, 0 Tokens/Latenz), seed.ts (seedSamples(): Intake mit Quelle sample → Verarbeitung inline mit Aufnahme, nie eingereiht → bei exported Freigabe (Export-Job wie immer eingereiht) und sofortige Ausführung genau dieses Jobs; Abbruch der Verarbeitung → ERROR), data/ (2 synthetische Mails + Aufnahmen), samples.test.ts, index.ts
• src/seed-samples.ts (pnpm seed:samples), src/samples-record.ts (pnpm samples:record [key …]): Operator-Skripte; eslint.config.mjs: no-console-Ausnahme wie für src/seed.ts, Begründung ergänzt
• src/features/requests/: source in NewRequest, countSamples()
• src/features/intake/submit.ts: optionale Quelle { source } (Standard upload) in derselben Transaktion
• src/features/jobs/: markProcessingFailed exportiert (bisher privat markError); reprocessRequest lehnt ein Beispiel im Verarbeitungsfehler ab
• src/features/extraction/ai-client.ts: parseExtractResponse() – derselbe Parser für Live-Antworten und Aufnahmen
• src/app/requests/sample-label.ts (neu), page.tsx, [id]/page.tsx: Kennzeichnung in Liste und Detail; kein „Erneut verarbeiten“ für ein Beispiel im Verarbeitungsfehler
• tests/integration/samples.test.ts (neu), tests/e2e/sample-smoke.spec.ts (neu), tests/e2e/global-setup.ts (seed:samples)
• docs/technical/architecture.md (Modul samples), docs/technical/deployment-vercel.md §6, CHANGELOG.md

Nachweis (SYSTEM.md §11)

• verify:changed: grün – vitest unit samples.test.ts ai-client.test.ts 34/34; vitest integration samples.test.ts 6/6. Reihenfolge ehrlich: die Tests entstanden nach dem Code, deshalb Gegenproben – Idempotenz-Prüfung ausgeschaltet → Test rot; der Review-Test fand zudem eine wirkungslose Prüfung (Abfrage ohne Mandantenkontext lieferte 0 Zeilen, every auf leerer Liste) – jetzt im Mandanten mit Längenprüfung
• verify: lokal grün bis auf den bekannten Windows-Fall – lint 0, typecheck, depcruise (Exit 0) grün; Unit 226/232 (die 6 Fehlschläge ausschließlich tests/architecture/dependency-rules.test.ts unter Windows, fix(tests): architecture test cannot start dependency-cruiser on Windows #78; Linux-CI grün); Integration 141/141 gegen Postgres + S3 (Migration 0019 auf der Test-DB angewendet); build grün
• verify:full / E2E-Spec: E2E lokal 3/3 grün (neu sample-smoke.spec.ts: Kennzeichnung in Liste und Detail, Zur Prüfung mit Aufmerksamkeits-Hinweis, Exportiert mit ERP-Referenz; bestehende Smoke-Flows unverändert grün); der zweite Setup-Lauf meldete „samples still in place“ (Idempotenz im echten Ablauf)
• Manueller Prüfnachweis: Aufnahmen gegen den Showcase-KI-Dienst (2026-09-27, gemini-3.5-flash): werk-ost 4× found, Liefertermin uncertain („KW 48“, calendar_week_only), zusätzliche Anforderungen missing, 3 Positionen; pumpe-p204 6× found, 2 Positionen. Seed und Screenshots im Showcase nach dem Merge.
• Frischer Review (P1 vor Ready-for-review; Architektur/API/DB immer): feat(demo): prepared sample requests from recorded AI answers #83 (comment) – changes requested; alle 7 Befunde bearbeitet (3033f21). Re-Review: feat(demo): prepared sample requests from recorded AI answers #83 (comment) – 6 von 7 erledigt, ein neuer Important (Freigabe ohne Job) behoben in b71cc84, Positivtest ergänzt, Aufräumen als chore(samples): settle samples left over by an aborted seed run #84. Abweichung zu Befund 2: ein abgebrochenes Beispiel endet in ERROR statt REJECTED (die Statusmaschine erlaubt PROCESSING → REJECTED nicht); stattdessen lehnt reprocessRequest die Verarbeitung eines Beispiels ab und die Liste zeigt dafür keinen Knopf – kein Live-Aufruf möglich.

Doku-Entscheidung (genau eine)

• Keine langlebige Doku betroffen – Begründung: –
• Doku betroffen und im selben PR aktualisiert:
  • Produktdoku (P0: README): –
  • Technische Doku: Runbook §6 (pnpm seed:samples, Aufnahme, Kennzeichnung)
  • Architekturkarte: Modul samples
  • ADR: –
  • CHANGELOG [Unreleased] (sichtbares Feature oder Verhalten – im selben PR, nie „später"): Added-Eintrag feat(demo): prepared sample request that is always viewable #71

Entferntes oder Umbenanntes: docs/ + README gegrept, Treffer bereinigt: nichts entfernt

Dateigrößen und neue Bausteine (SYSTEM.md §7)

Dateien über 500 Zeilen im Diff (Ausnahmen: generierter Code, Lockfiles, Fixtures, Migrationen, Schemas, Ressourcen, Doku, Konfiguration):

• keine
• bewusst belassen – Begründung: –
• im selben PR nach fachlicher Verantwortung geteilt
• Folge-Issue –

Über 800 Zeilen mit neuer Fachlogik oder über 1000 Zeilen (P1/P2): nicht betroffen

Neue Shared-Komponente, Utility-Datei, Adapter oder fachlicher Service:

• nein
• ja – gesucht nach: vorhandenem Seed (src/seed.ts), Test-Fixtures für KI-Antworten (syntheticExtractResponse), Replay-Modus der Evals (services/ai --replay) und Upload-/Verarbeitungspfad; gefunden: seed.ts legt nur Firmen und Konten an; syntheticExtractResponse ist ein handgeschriebener Test-Stub, keine Aufzeichnung; der Eval-Replay lebt im Python-Dienst. Neu ist deshalb nur der Seed-Ablauf, der die vorhandenen Pfade (Intake, Verarbeitung, Freigabe) mit einem aufgezeichneten Client aufruft.

Subagent-Einsätze

Keine.

Risiken / offene Punkte

• Braucht die Freigabe des Orchestrators vor dem Merge (Migration 0019).
• Reste eines abgebrochenen Laufs bleiben sichtbar (ERROR/NEW) → Folge-Issue chore(samples): settle samples left over by an aborted seed run #84.
• CHANGELOG [Unreleased] hat jetzt 101 Zeilen (Doku-Guard-Warnung): ein Release ist fällig – nicht Teil dieses PRs.
• Blocker (extern, 2026-09-27 ab ca. 15:30): Die Aufnahme von pumpe-p204 scheiterte in drei Anläufen (24 Versuche über ~20 min) an Gemini 503 (Logs requestflow-ai: model_call_retry 503 ×2 → 502 model_error). Hypothese „mailspezifisch“ widerlegt: eine Probe mit beiden Mails scheiterte gleich, obwohl werk-ost eine Stunde zuvor sofort durchlief. Ursache: Überlast des Free Tiers beim Anbieter – genau der Fall, gegen den dieser PR den Showcase absichert.

---

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
requestflow	Ready	Preview	Sep 27, 2026 8:39pm UTC
requestflow-ai	Ready	Preview	Sep 27, 2026 8:39pm UTC

[Fluory]

Frischer Review (/review-pr) – unabhängiger Reviewer-Agent ohne Umsetzungskontext, 2026-09-27

[Blocker]   – src/features/samples/seed.ts:34, tests/integration/samples.test.ts:62-63, docs/technical/deployment-vercel.md:121-122, CHANGELOG.md:9 – AK 5 („freigegeben und exportiert … ERP-Referenz ohne Schreibaktion“) ist nicht erfüllt. Der Seed endet bei APPROVED mit einem eingereihten Export-Job. Die ERP-Referenz entsteht erst beim nächsten Drain, also durch after() nach einer Schreibaktion eines Besuchers oder durch den Cron einmal am Tag (Runbook §7). Die Testplan-Zeile „export row with ERP reference, exactly one“ fehlt; der Test zählt nur den Job. Der CHANGELOG behauptet trotzdem „exported“. – Besucher sehen bis zu ~24 h „Freigegeben“ ohne Exportbeleg. – Nach der Freigabe den normalen Exportpfad ausführen (`drainExports` mit dem ERP-Adapter) oder im Runbook einen Drain-Schritt per curl ergänzen. Dazu ein Integrationstest: Status EXPORTED, genau eine `request_exports`-Zeile mit Referenz (Muster: `tests/integration/export.test.ts`).
[Important] – seed.ts:11, 44-51 – Ein abgebrochener Seed blockiert die Idempotenz. Beispiele haben nie einen Queue-Job; NEW/PROCESSING bedeutet bei ihnen also nur „Seed abgebrochen“. Wirft `processRequestJob` nach dem Claim (process-request.ts:58-63), bleibt die Anfrage dauerhaft PROCESSING: kein markError, kein Expiry. Jeder weitere Lauf zählt sie als „still serving“ und repariert sie nie. Ein Abbruch zwischen `submitUpload` und `markSample` (getrennte Transaktionen) hinterlässt eine unmarkierte NEW-Upload-Anfrage ohne Job. – Das ist genau das Symptom von #71, nur mit Beispiel-Label. – `source='sample'` in der Intake-Transaktion setzen; `review: ["REVIEW"]`; bei einem Fehler auf REJECTED setzen (nicht auf ERROR(processing), das böte „Erneut verarbeiten“ und damit einen Live-Modell-Aufruf); den Fehlerpfad testen.
[Important] – PR-Beschreibung – Veraltet. Der Arbeitsstand nennt pumpe-p204 als offen, obwohl es seit d51ad56 committed ist. Der Nachweis steht überall auf „folgt“: kein verify, kein Screenshot, kein Mutationscheck im PR gefunden. Die Doku steht auf „folgt“, ist aber erledigt. – Nach AGENTS-Regel 3 nicht ready-for-review. – Beschreibung aktualisieren, Ergebnis von verify und den Mutationscheck eintragen.
[Important] – src/app/requests/page.tsx:129-136, [id]/page.tsx:87-91, samples.ts:47-56 – Es fehlen die Testplan-Zeile „label visible“ (Komponenten- oder E2E-Test) und die im Impact Manifest zugesagten Unit-Tests für den Client und die Anzeige. – Das Label-AK ist unbewiesen. – Unit-Test für `recordedAiClient` sowie ein E2E-Check auf `sample-label`/`sample-notice`.
[Note]      – samples.ts:39-41 – Die Aufzeichnung wird per `as ExtractResponse` geladen, ohne das Zod-Schema des Live-Clients. Tokens und Latenz (3558 Tokens, 24,7 s) werden gespeichert, als wären sie verbraucht worden (extraction/repository.ts:41-42). – Eine beschädigte Aufzeichnung umgeht die Validierung; die Kennzahlen sind irreführend. – Mit `responseSchema` parsen; Tokens und Latenz auf 0 setzen.
[Note]      – samples.test.ts:78-81 – `rejects.toThrow()` akzeptiert jeden Fehler. – Der Test kann aus dem falschen Grund grün sein. – Auf SQLSTATE 23514 bzw. `requests_source_check` prüfen.
[Note]      – eslint.config.mjs:15-17 – Die Ausnahme gilt jetzt auch für zwei neue Skripte, die Begründung nennt aber nur seed/setup. Die Skripte selbst sind in Ordnung: sie geben keine Secrets aus und schließen ihre Ressourcen im finally. – Kommentar ergänzen.

Geprüft und ohne Befund: kein Weg zum Live-Modell (kein processRequest-Job, „Erneut verarbeiten“ nur aus ERROR(processing)); companyId aus der Session; frische Message-ID → kein Duplikat (getestet); Belege konsistent (documentId aus dem Outcome, Message-ID kein Segment); Migration 0019 additiv, Rollback benannt, CI auf frischer DB grün, keine konkurrierende Migration; Fixtures synthetisch (example.com, „Beispiel“-Namen; 555-Rufnummern nicht geprüft); Architekturkarte und Runbook §6 vorhanden; tests/integration/samples.test.ts lokal 3/3 grün.

Urteil: „changes requested“ – AK 5 (Exportbeleg) ist nicht erfüllt, und ein abgebrochener Seed blockiert sich selbst dauerhaft. Danach braucht es wegen Migration 0019 zusätzlich die menschliche Freigabe.

[Fluory]

Frischer Re-Review (/review-pr) – unabhängiger Reviewer-Agent ohne Umsetzungskontext, 2026-09-27 (Fix 3033f21)

[Important] – src/features/samples/seed.ts:83-84, :91 (mit :16) – Die Freigabe committet jetzt ohne Export-Job, weil `inlineSender` die Einreihung ersetzt, die `approveRequest` in derselben Transaktion vornimmt (review.ts:241, ADR-0001 D9). Zwei Fälle hinterlassen eine Anfrage in APPROVED ohne Job: Der Seed wird zwischen Freigabe und Ende des ERP-Aufrufs abgebrochen (bis ERP_TIMEOUT_MS = 10 s, env.ts:43; Strg+C, Kill, Setup-Timeout), oder die Ersatz-Einreihung (:91) scheitert. Da `STILL_SERVING.exported` APPROVED mitzählt, repariert kein weiterer Lauf diese Anfrage. Einen Sweeper gibt es nicht, und Reprocess greift nur aus ERROR. – Das ist Befund 2 der ersten Runde, jetzt in der Exportstufe: kein Exportbeleg bis zu einem Eingriff in die DB. Vor dem Fix war dieser Fall ausgeschlossen. – Mit dem echten `deps.boss` freigeben, dann liegt der Job in der Freigabe-Transaktion. Danach `exportRequestJob` inline aufrufen. Der eingereihte Job findet später EXPORTED vor und endet als `skipped` (export-job.ts:47-50). Die Zeilensperre serialisiert gegen einen parallelen Drain, der Ersatzzweig entfällt. Test anpassen und bei ERP-Ausfall zusätzlich `getExportRecord` = null prüfen.
[Note]      – seed.ts:76, status.ts:25 – Ein abgebrochenes Beispiel bleibt als ERROR-Zeile („bitte das Anlegen der Beispiele wiederholen“) für Besucher sichtbar. Der nächste Lauf legt ein neues an, das alte bleibt stehen. In der UI lässt es sich nicht entfernen: reject geht nur aus REVIEW, ERROR→REJECTED nur für Duplikate (review.ts:275). Nach einem harten Abbruch bleiben NEW/PROCESSING-Reste ebenso stehen. – Showcase-Rauschen, aber nichts blockiert. – Aufräumschritt in Runbook §6 oder Folge-Issue.
[Note]      – tests/integration/samples.test.ts:137, src/app/requests/page.tsx:157 – Die Sperre ist nur negativ getestet. Kein Test belegt, dass ein Beispiel in ERROR(export) weiter erneut exportiert werden kann. – Eine auf `source === "sample"` verbreiterte Sperre bliebe grün. – Fall ergänzen: ERROR(export) → `reprocessRequest` → APPROVED und ein Export-Job.

Geprüft und ohne Befund: Export in einer Transaktion (keine halbe Exportzeile); kein doppeltes Einreihen (singleton + exclusive); kein doppelter Export (Zeilensperre, unique, Idempotency-Key); processing.failed aus NEW erlaubt; submitUpload setzt weiter upload als Standard; Live-Client mit parseExtractResponse unverändert; Sperre nur für die Verarbeitungsstufe; lokal Unit 3/3, Integration 19/19; CI check grün.

Befund der ersten Runde	Stand	Grund
1 Blocker AK 5 (Exportbeleg)	erledigt	Export inline über exportRequestJob; Test prüft EXPORTED, ERP-Referenz, genau ein request.exported, 0 Jobs; Runbook angepasst
2 Abgebrochener Seed blockiert	teilweise	Quelle in der Intake-Transaktion, nur REVIEW zählt, Fehler → ERROR; Abweichung zu REJECTED akzeptabel (Reprocess serverseitig gesperrt, getestet); neu hängen bleiben kann es aber in APPROVED (Important)
3 PR-Beschreibung	erledigt	Nachweis, verify, Gegenproben und Abweichung eingetragen
4 Label-/Client-Tests	erledigt	E2E prüft sample-label, sample-notice, erp-reference; Unit-Test für recordedAiClient
5 Schema, Tokens/Latenz	erledigt	Validierung über das Vertrags-Schema; 0 Tokens und 0 Latenz getestet
6 toThrow() zu breit	erledigt	prüft SQLSTATE 23514 und requests_source_check
7 ESLint-Kommentar	erledigt	Begründung nennt alle vier Skripte

Urteil: „changes requested“ – wegen des Important-Befunds (kleiner Fix); sonst blockiert nichts. Wegen Migration 0019 braucht es danach ohnehin die menschliche Freigabe.

---

Bearbeitung (b71cc84): Important behoben – die Freigabe reiht den Export-Job wieder in ihrer eigenen Transaktion ein, der Seed führt genau diesen Job sofort aus; eine spätere Zustellung endet als skipped (getestet), bei ERP-Ausfall bleibt nichts halb geschrieben (getestet). Note 2 → Positivtest „ERROR(export) → erneut exportierbar“ ergänzt. Note 1 → Folge-Issue #84.

[Fluory]

Merge auf ausdrückliche Freigabe des Orchestrators (2026-09-27: „OK“, „Merge“) – menschliche Freigabe für Migration 0019 erteilt.