Files
Speech/PROJECT_CONTEXT.md
T
Eugenius Naumenko 2c24c18614 Projektregeln und Betriebsanleitung für Coding-Agenten dokumentieren
Zentrale AGENTS.md mit Architektur, Lern- und Bewertungsregeln, Schutz
historischer Daten, Umgang mit Modellkosten und Grenzen produktiver Eingriffe.
Verbindliche Prüfabläufe unterscheiden lokale Fixtures und echte Anbieterqualität.

README, KI-Betriebsanleitung, Browser-Testhinweise und historische Flowise-
Dokumentation beschreiben die direkte Modellanbindung, versionierte Kursbank
und statistische Ausspracheplanung. Die Qualitäts-API dokumentiert nun beide
Grammatik- und Schreibsuites mit ihren Kosten und begrenzter Aussagekraft.

Projektkontext hält die Übergabe und erfolgreiche lokale Verifikation fest.
Keine Schlüssel, Produktionsprofile oder personenbezogenen Aufnahmen enthalten.
2026-11-01 23:23:27 +00:00

292 lines
49 KiB
Markdown

## Projektanleitung und Übergabe — 01.11.2026
Die zentrale AGENTS.md beschreibt dauerhafte Architektur-, Lern-, Bewertungs-,
Datenschutz- und Betriebsregeln einschließlich der lokalen Prüfabläufe. Dieses
Dokument bleibt eine datierte Entwicklungshistorie; ältere Modellfreigaben und
Konfigurationsangaben sind keine Aussage über aktuelle Produktionsprofile.
Vom Nutzer bereitgestellte Live-Ergebnisse zeigen vier bestandene Grammatik-
und Schreibfälle mit DeepSeek Pro ohne Denkmodus. Das ist eine begrenzte
Modellabnahme, keine Garantie für sämtliche Bewertungsfälle. Profilpreise und
Budgets liegen in der Datenbank und werden nicht durch Git ausgeliefert.
Vor Übergabe lokal erfolgreich geprüft: Go mit Race Detector und separater
PostgreSQL-Testdatenbank, go vet, Web-Build, Audit aller 840 Bankaufgaben und
die drei sequenziellen Browser-Smokes für Administration, Kursbank und
Aussprachestatistik. Anbieter und Speech sind dort lokale Fixtures. Keine
Live-Aufrufe, Produktionsänderungen oder Dienstneustarts für diese Übergabe.
## Schreibbewertung: Artikel, Rechtschreibung und Qualitätsprüfung — 01.11.2026
Nutzerfall: „my name is Jack Hill. I live in city. My hobby is shwiming.“ wurde mit falschem Hinweis city→City und falscher Satzanzahl bewertet. Evaluatorprompt prüft jetzt die Zielsprache getrennt von deutscher Feedbacksprache, Artikel sowie echte Großschreibungsregeln und vermeidet überflüssige falsche Satzzählung. Zusätzlich optionale Qualitäts-Suite writing am vorhandenen POST /admin/ai/quality: zwei explizit kostenpflichtige Fälle (richtige Vorstellung und gemeldete fehlerhafte Variante). Default grammar bleibt erhalten, separate Operation-IDs verhindern die Vermischung der Suites. Adminbutton unter Antwortbewertung; keine automatischen zusätzlichen Modellaufrufe. Die bekannten Englisch-Checks sind nur Qualitätsfixtures, keine produktiven Go-Grammatikregeln und kein allgemeiner Modellnachweis. Keine alten Bewertungen, Profile, Budgets oder echte .env geändert, keine bezahlten Tests und kein VPS-Neustart. Für Übernahme API und Web neu bauen.
# Aktuell: klare offene Kursaufgaben — 01.11.2026
- Alle 140 free_speech/free_text-Aufgaben erhalten konkrete, redaktionell formulierte Arbeitsaufträge statt des pauschalen „über diese Situation“. Quelle tools/course_bank/open_instructions.json enthält 84 eindeutige Anweisungen/Kriterien für Haupt- und Wiederholungsinhalte. Eigene oder erfundene Namen/Orte/Angaben sind ausdrücklich erlaubt; Beispiele sind keine versteckten Vorgaben.
- Neue Kennungen nur für diese 140 Aufgaben: a1bank_en_v2_*, Revision en-A1-bank-v2. Die übrigen 700 bleiben v1. Manifest/Prüfvermerk aktualisiert; aktive Verteilung unverändert 840/42 Buckets. Alter Bankimport deaktiviert alte Vorlagen, verändert aber keine zugewiesenen Aufgaben, Antworten oder Bewertungen. Migrationstest mit originaler Jack-Hill-v1-Aufgabe und alter 70/94-Bewertung prüft Bestandsschutz.
- Freies Sprechen bekommt evaluation_scope=content_and_language, answer_source=speech_transcript und pronunciation_displayed_separately. Originalaufgabe, Rubrik, Transkript und Sprachmessung bleiben im Modellauftrag. Bewerterprompt verbietet zusätzliche Situationsanforderungen, berücksichtigt erlaubte Angaben und Transkriptunsicherheit; Aussprache wird nicht in diese Inhaltspunktzahl gemischt oder im Feedback bestritten. Autoren-/Prüferprompts verlangen sichtbare, konkrete Anforderungen.
- UI zeigt bei free_speech „Inhalt und Sprache“ und den erkannten Text neben dem getrennten Aussprachewert. Historische 70-Punkte-Ergebnisse werden nicht automatisch neu benotet.
- Kein Push, kein VPS-Neustart, keine Änderungen an echter .env, Profilen oder Budgets und keine bezahlten Modell-/Azure-Aufrufe. Für Übernahme API und Web neu bauen; anschließend eine neue Aufgabe anfordern. Bestehende eingefrorene Aufgaben bleiben historisch.
# Aktuell: statistisches Aussprachetraining — 29.10.2026
Dieser Abschnitt hat Vorrang vor der darunter dokumentierten Auswahl nach Einzelwerten. Keine echte .env verändert, keine Produktionsprofile/Budgets geändert, keine Container neu gestartet, kein Push und keine bezahlten Anbieteraufrufe.
- `internal/pronunciation` berechnet pronunciation-v1: gemeinsame Lautkennungen über Wörter, 90-Tage-/30-Beobachtungsfenster, Aktualitätsgewichtung, begrenztes Gewicht von Wiederholungen, Evidenzzustände, Trend und zeitversetzte Wiederholung. Reine Funktionen mit kontrollierter Testzeit.
- Additive `pronunciation_assessments`, `pronunciation_observations`, `pronunciation_plans` sowie Anbieter-/Messmetadaten an neuen Ausspracheversuchen. Atomare Speicherung in beiden Aufnahmewegen. Bestätigte Kurs-Nachsprechhistorie wird wiederholbar übernommen; unbekannte alte Ausspracheherkunft bleibt unbestätigt. Demo, freies Sprechen, unvollendete Tests und importierte Kopien zählen nicht als zusätzliche Ausspracheevidenz.
- `PRONUNCIATION_STRATEGY=statistical` ist Default; `recent` bewahrt die bisherige Auswahl und erlaubt Statistikvorschau. Go speichert den Trainingsauftrag (60/25/15-Mix), das bestehende next_exercise-Profil gestaltet den Satz. Neue Transferwörter sind bis zur passenden tatsächlichen Phonemmessung unbestätigt. Keine extra KI-Planungsaufrufe.
- Authentifizierter GET /pronunciation/profile für die aktive Zielsprache. Fortschrittsansicht zeigt Laut-/Wortkontexte und Nachweisdichte; Übungen zeigen gespeicherte Auswahlbegründung. Alte Endpunkte und Azure-Punkte bleiben erhalten. Alle Regeln/Betriebsgrenzen: docs/AI_OPERATIONS.md.
- Lokale Datenbank-/Race- und Browserprüfungen verwenden wegwerfbare Schemas, Modell- und Speech-Fixtures. Keine Aussage über echte Azure-/Modellqualität oder den laufenden VPS-Stand. Für Übernahme API und Web neu bauen; additive Migration erfolgt erst bei deren API-Start.
## Aussprache: Trainingswort verbindlich — 28.10.2026
Echte Ministral-Ausgabe ersetzte cat (Wortwert29, /k/19) durch dog und behauptete unbelegte Verwechslungen. `required_practice_words` enthält jetzt das am niedrigsten bewertete Wort bzw. Wort eines gemessenen schwachen Phonems. Direkte Aussprachegenerierung prüft dessen Vorkommen in Referenzsatz und focus_points sowie identischen TTS-/Referenztext. Keine Satzschablonen oder sprachlichen Lösungsregeln; Unicode-Wortgrenzen mit Unterstützung ungetrennter Schriften. Bei Abweichung ein gezielter Korrekturversuch, danach bestehender Fallback. Prompt unterscheidet gesperrte ganze Sätze von erlaubten Trainingswörtern und verbietet nicht gemessene Ersatzlautdiagnosen. Zusätzlich doppelt maskiertes Steuerzeichenmuster in pronunciation.json korrigiert; normaler Text und echte Steuerzeichen separat getestet. Keine Produktionsprofile, Budgets oder Container geändert, keine Live-Modellaufrufe. API-Neubau erforderlich.
## Aussprache: Feldgrenzen und gezielte Korrektur — 28.10.2026
VPS-Fallback `reason_for_choice is missing or invalid` erlaubt ohne Rohantwort keine Unterscheidung zwischen fehlendem, zu langem und mehrzeiligem Feld. Die Validierung meldet diese Fälle nun getrennt. Alle bisherigen Längengrenzen bleiben erhalten. Neues eingebettetes `pronunciation.json` wird bei next_exercise im JSON-Modus dem Prompt und bei aktiviertem Mistral-Schemamodus als Schema mitgegeben. Prompt nennt die Grenzen, insbesondere kurze einzeilige Begründung bis 300 Zeichen. Der einmalige Korrekturversuch erhält die konkrete Validierungsabweichung; das Ergebnisobjekt wird vor jedem Versuch zurückgesetzt. Keine Live-Aufrufe oder Änderungen an Produktionsprofilen/Budgets. API-Neubau nötig.
## Aussprache: aktuelle Schwächen und persistenter Wiederholungsschutz — 28.10.2026
Der Generator erhält keine rohe Versuchshistorie mehr, nur aktuelle Wort-/Phonemschwächen, `evidence_window_attempts` und `training_mode` (general/targeted). Leere Listen sind Arrays; general verbietet eine persönliche Fehlerdiagnose. Zusätzlich lädt `RecentPronunciationTexts` die letzten fünf unterschiedlichen generierten/versuchten Sätze aus PostgreSQL nach Nutzer, Sprache und Niveau, auch unbeantwortete generierte Aufgaben. `nextAgentExercise` ergänzt damit die Generierungssperrliste auf Dashboard und lessons/next; feste Ersatzaufgaben behalten die bisherige Browser-Sperrliste, damit der begrenzte Bestand verfügbar bleibt. Keine Produktionsdaten geändert, keine Modelle aufgerufen, keine Container neu gestartet. API-Neubau erforderlich.
## KI-Verbrauch: sichtbare Aufrufdetails — 28.10.2026
Der Anzeigen-Button in AIAdmin lädt Details nun mit sichtbarem Ladezustand und eigener Fehlermeldung direkt im Verbrauchsbereich. Die Detailansicht steht oberhalb der Tabelle, erhält Fokus und wird ins Sichtfeld gescrollt; Schließen gibt den Fokus an den auslösenden Button zurück. Keine API-/Datenbankänderung und keine Anbieteraufrufe für das Anzeigen gespeicherter Details.
## Profilkorrektur — 28.10.2026
VPS-Logs zeigen abgelehnte Profil-PUTs (400) und Mistral-400 wegen `reasoning_effort` auf einem nicht unterstützten Modell. Modell-/Anbieterwechsel im Adminformular setzt den Denkaufwand jetzt auf Nicht senden zurück. Für Ministral wird auch ein historisches `none` nicht als reasoning_effort verschickt; andere explizite Denkstufen werden vor dem Speichern verständlich abgelehnt. Fehlende Modell-ID und nicht bestätigte Preise erhalten getrennte Meldungen, zusätzlich direkt am Speicherbutton. Keine Profile/Budgets in Produktion geändert; Deployment weiterhin erforderlich.
## Ergänzung: gezielte Aussprachegenerierung — 28.10.2026
`next_exercise` erhält explizit schwierige Wörter und gemessene Phoneme samt Wortkontext aus den aktuellen Nachweisen derselben Zielsprache. Neuere Verbesserungen ersetzen alte Schwächen; Auslassungen liefern keine Phonemdiagnose. Der neue Prompt verlangt kurze neue Sätze mit ein bis zwei belegten Trainingswörtern. Keine Personen-IDs oder alten Lehrerkommentare im Anbieterauftrag. Tests prüfen Sprachtrennung, Verbesserung, Auslassung, Messwertweitergabe und leeren Einstieg. Azure und der Bankkurs bleiben unverändert. Modellprofil auf dem VPS weiterhin separat unter Aussprachegenerierung aktivieren; hier keine Produktionsprofile oder Budgets geändert, keine Live-Anbieteraufrufe und keine Container-Neustarts.
# Aktuell: geprüfter A1-Aufgabenbestand — 26.10.2026
Dieser Abschnitt hat Vorrang vor den darunter dokumentierten früheren Laufzeitmodi. Kein Push, keine Änderungen an echter `.env`, Modellprofilen oder Budgets, keine VPS-Neustarts.
- Standardkonfiguration `COURSE_TASK_MODE=bank`; der frühere Generator bleibt mit `ai` ausdrücklich nutzbar. Der separate Aussprachebereich bleibt unverändert.
- 840 vorbereitete Aufgaben: 20 je sieben Modulen/sechs Bereichen, 8/8/4 Schwierigkeitsverteilung. 560 choice, je 70 short_text/free_text/repeat_sentence/free_speech. Quellen und an Prüfsummen gebundener redaktioneller Prüfvermerk unter `tools/course_bank/`; erzeugte Dateien unter `apps/api/internal/store/coursebank/en-US/a1-v2/`. Kein Modellaufruf zum Erstellen dieser Inhalte. Keine externe Lehrerzertifizierung behauptet.
- `domain/course_bank.go`, `store/course_bank.go`: additive Banktabelle, atomarer wiederholbarer Import mit unveränderlichen IDs/Inhaltsprüfsummen. Vorlagen werden pro Nutzer in bestehende Aufgaben kopiert. Alte Aufgaben, Antworten und Tests bleiben unverändert. `curated` kennzeichnet die neue Herkunft.
- Auswahl verwendet echte Bewertungen, Lernziel/Schwierigkeit und Präsentationshistorie; neue Aufgaben vor Wiederholungen, nutzerbezogene Serialisierung gegen Doppelzuweisung, gespeichertes Auftragsergebnis für Wiederaufnahme. Ungelesene/bloß angezeigte/unbenotete Antworten sind keine bewerteten Lernnachweise.
- Offene Antworten ohne verfügbares Bewertungsmodell: `ungraded`, keine Note, Übungsbeispiel/Rubrik zum Selbstvergleich. Bestehende Retry-Routen erlauben spätere optionale Bewertung. Azure bleibt für Audio/Messungen zuständig. Modelle werden nicht für Bankauswahl oder Hintergrundanalyse aufgerufen.
- Zwölfteiliger Test bleibt offen: `submitted` nach zwölf gespeicherten Antworten ohne vollständige Bewertung, Gesamtergebnis/Lösungen weiterhin verborgen. Spätere Bewertung derselben Antworten ermöglicht Abschluss. Kein automatischer KI-Zusammenfassungsaufruf im Bankbetrieb.
- Web-App zeigt Herkunft, Bestandszahlen und Wiederholungen; unterstützt unbenotete Antworten, Wiederaufnahme und ausstehende Testbewertung. Alte KI-/Flowise-Herkünfte und fester Kurs bleiben erreichbar.
- Nach Implementierung lokal geprüft: vollständiger Korpusvertrag, Offline-Audit, Go-Tests mit separatem PostgreSQL und Race Detector, Web-Build und Browser-Smoketest für alle Bereiche, Neuladen, offenes Schreiben und eingefrorenen abgegebenen Test. Audio/Modellantworten in diesen Integrationstests sind ausdrücklich lokale Fixtures. Keine neuen echten Anbieteraufrufe und keine Produktionsdatenbank-Migration ausgeführt. Details: `docs/AI_OPERATIONS.md`.
## Vorheriger Stand: direkte Modell-APIs und Live-Prüfung
# Aktuell: direkte Modell-APIs — 26.10.2026
Dieser Abschnitt ersetzt für den aktuellen Arbeitsbaum die darunter archivierten Aussagen zur aktiven Flowise-Anbindung. Kein Push, keine Änderungen an `.env`, keine VPS-Dienstneustarts.
- `main.go` verdrahtet `AIService` direkt mit Kursengine und Aussprache. DeepSeek/Mistral-Zugang über `DEEPSEEK_API_KEY`/`MISTRAL_API_KEY`. Normale Compose-Konfiguration und Entwicklung starten/benötigen kein Flowise mehr. Die alten Adapter und Dateien bleiben historische Referenzen/Tests; alte `FLOWISE_*`-Werte werden beim normalen Start ignoriert.
- Neue Dateien: `domain/ai.go`, `store/ai.go`, `services/ai.go` mit eingebetteten getrennten Prompts/Schemas unter `services/aiprompts/`, `httpapi/ai.go`, Web-Komponente `AIAdmin.tsx`. Neun Profile, getrennte Test-/Einzelaufgabenlimits, automatisches Einbetten der Schemas, unveränderte technische Prüfung und sechs Lernbereiche.
- Admin: Profilversionen, Modelllisten, Verbindungstest, Promptansicht, beliebige Testeingabe, zwei ausdrücklich ausgelöste Bewertungs-Qualitätsfälle, Verbrauchsfilter und Details sowie dokumentierter Abgleich unbekannten Verbrauchs. Schlüssel werden nicht ans Web ausgeliefert. Details enthalten echte Lernkontexte und sind nur für Admins zugänglich.
- Additive Tabellen `ai_*` speichern Profile/Preisversionen, Budgethistorie, beim ersten Bearbeitungsschritt eingefrorene Auftragskonfiguration, Aufrufantworten und Verbrauch. Erfolgreiche identische Aufrufe werden wiederverwendet. Maximal zwei Modellaufrufe je Arbeitsschritt/KI-Auftragsrevision. Ein ausdrücklicher Retry eines fehlgeschlagenen Jobs erhöht ai_revision und darf aktuelle Profile verwenden; reine Wiederaufnahme nach Absturz behält dieselbe Revision. Kosten bleiben Schätzungen mit Rechnung beim Anbieter als Referenz.
- Globales USD-Monatsbudget plus optionales Tageslimit, UTC, Warnung ab 80 Prozent. Atomare Reservierung vor jedem Aufruf; konservative Kontextobergrenze und Eingabebegrenzung. Ohne Usage/bei unklarer Unterbrechung bleibt Geld reserviert. Nach Prozessabbruch werden verwaiste Aufrufe als unbekannt markiert. Profil-Defaults deaktiviert, kein Modell, keine angenommenen Preise, Budget null: keine automatischen Live-Kosten.
- Neue Aufgabenherkunft `ai`, Anzeige „Mit KI erstellt“. Historische `flowise`-Daten und gespeicherte Bewertungen bleiben unverändert. Falsche historische 80-/85-Punkte-Bewertungen werden durch Promptwechsel nicht still korrigiert. Azure Speech und die bisherigen Kursendpunkte bleiben erhalten.
- Vollständige Einrichtung, API-Verträge, Grenzen und Testanleitung: [docs/AI_OPERATIONS.md](docs/AI_OPERATIONS.md).
Validiert am 25.10.2026: Go-Tests mit Race Detector und opt-in PostgreSQL-Integration gegen die ausschließlich lokale wegwerfbare PostgreSQL-16-Instanz, `go vet`, Web-Build und Chromium-Smoke mit echter lokaler Go-API/PostgreSQL sowie simulierten direkten Anbieterantworten. Abgedeckt sind Profil-/Preisversionen, eingefrorene laufende Konfiguration, tatsächliche Usage/Cache-/Reasoning-Teilmengen, fehlende Usage, Fehler/Abbruch, atomare Budgetreservierung bei Konkurrenz, Tageslimit, dokumentierter Abgleich, Antwortwiederverwendung und Retry mit unveränderter gespeicherter Antwort. Browser: Adminprofile, Preise, Budget, Modellliste, zwei erfasste Qualitäts-Testfälle, private Details, direkte Autor-/Prüfer-Aufgaben, Hintergrundbewertung, Neuladen, zwölfteiliger Test mit Lösungsschutz und Reserve bei Budgetsperre. Keine echten DeepSeek-/Mistral-/Azure-Aufrufe; deren Qualität/Erreichbarkeit muss nach Konfiguration im Adminbereich bewusst getestet werden. Docker ist in dieser Agentenumgebung nicht verfügbar; keine Images gebaut oder VPS-Dienste verändert.
## Zusätzliche Live-Prüfung und Korrekturen — 26.10.2026
- Neue Mistral-Zugangsdaten sind in der laufenden API angekommen; Modellliste erfolgreich. Tests ausschließlich mit Mistral, keine DeepSeek-Aufrufe. Reale API-/Azure-/Browserprüfungen erfolgten mit einem separaten Testkonto; dessen zeitweilige Adminrolle wird nach den Tests entfernt. Persönliche Lernantworten bleiben unverändert.
- Reale kleine Modelle lieferten syntaktisch gültige, aber teilweise fachlich falsche Aufgaben/Freigaben. Der direkte Prüfervertrag ist jetzt `aiprompts/review.json`: Auswahl-Lösungsschlüssel/Erklärung werden ausgeblendet, jede Option wird unabhängig mit ID, Wahrheitswert und Begründung geprüft. Go verlangt vollständige eindeutige Optionsabdeckung, genau eine richtige Antwort und Übereinstimmung mit dem Autor. Prüfer können Aufgaben nicht umschreiben. Offene Aufgaben behalten ihre Rubrik. Der historische Flowise-Vertrag wird nicht geändert.
- Mistrals nativer Schemamodus bekommt eine kompatible Struktur ohne nicht unterstützte bedingte Operatoren. Aufgabenanzahl und Rendererfelder werden aus dem gespeicherten Auftrag eingegrenzt, ohne sprachliche Satzmuster in Go. Die vollständige technische Prüfung bleibt bestehen. Im normalen JSON-Modus wird das Originalschema im Systemprompt mitgesendet.
- Kürzere getrennte Autoren-, Prüfer-, Bewertungs- und Analyseprompts. Anbieterfehler erfassen auch Mistrals oberstes `message`-Feld; nach ausgeschöpften Versuchen bleibt die konkrete Ursache erhalten. HTTP 429 wird nicht sofort identisch wiederholt.
- Echte Browserprüfung gegen die isolierte aktuelle Go-Testinstanz mit eigenen PostgreSQL-Lerndaten: erzeugte Wortschatzaufgabe, Auswahlbewertung, Neuladen sowie asynchrone offene KI-Bewertung erfolgreich. Modellaufrufe dieser Instanz wurden im echten zentralen Budget/Verbrauchsprotokoll als Tests erfasst. Die Produktionscontainer wurden vom Agenten nicht neu gestartet; die Code-/Promptkorrekturen benötigen einen API-Neubau.
- Neun Mistral-Profile mit Preisen, Token-/Kontextgrenzen und Zeitlimits vorbereitet. Globales Testbudget unverändert 0,25 USD monatlich und täglich. Profile bleiben deaktiviert: Die Modellabnahme ist trotz einzelner erfolgreicher Aufgaben und sechs bestandener Bewertungsfälle insgesamt nicht bestanden. Auch Codestral/Ministral bestätigten unlösbare Aufgaben oder beurteilten Optionen falsch. Größere Modelle und zeitweise Ministral meldeten HTTP 429/fehlende Kapazität. Abbrüche ohne Usage behalten ihre Kostenreservierung; nicht als nachgewiesene Nullkosten behandeln.
## Archiv: vorherige Kurs-/Flowise-Implementierung
# Aktueller Stand: adaptive Kursarchitektur v2 — 21.10.2026
Diese Ergänzung beschreibt den aktuellen lokalen Arbeitsbaum und ersetzt für den A1-Kurs die darunter archivierte v1-Beschreibung. Nicht gepusht, nicht committed, keine VPS-Container neu gestartet und `.env` nicht geändert. Der Live-Stand von Flowise/Azure ist weiterhin nicht verifiziert.
- Hauptansicht `CoursePage.tsx`: sieben frei zugängliche Module mit Grammatik, Wortschatz, Hören, Lesen, Sprechen, Schreiben; Aufgabenquelle sichtbar; unbegrenzt weitere Aufgaben, Verlauf, Wiederaufnahme und Hintergrundbewertung. `LegacyCoursePage.tsx` erhält den bisherigen festen Kurs.
- Domäne: `internal/domain/adaptive.go`; Persistenz: `store/adaptive*.go`; orchestration/technische Prüfung: `services/adaptive_agent.go`, `services/adaptive_engine.go`; neue HTTP-Endpunkte: `httpapi/adaptive.go`. API-Start initialisiert additive `course_v2_*`-Tabellen, migriert historische Kursnachweise idempotent ohne Originaltabellen zu ändern und startet zwei PostgreSQL-Queue-Worker. Historische Aussprachewerte ohne bekannte Provider-Herkunft bleiben sichtbar, gelten aber nicht als bestätigte echte Messungen.
- Flowise-Lehrer: `analyze_course_progress`, `plan_course_task`, `evaluate_course_attempt`, `summarize_course_exam`; Generator mit unabhängigem Prüfer: `generate_course_task`, Vertrag `schema_version=2`. Go liest Fakten, speichert und liest den Agenten-Brief wieder aus PostgreSQL; der Generator bekommt diesen gespeicherten Brief und die gespeicherte Analyse. Keine sprachlichen Satz-Regex/Whitelist mehr im Kurspfad. Anleitung/Prompts/Schemas und Beispiele: [flowise/course-v2/README.md](flowise/course-v2/README.md).
- Go prüft Format, Renderbarkeit, Nutzer/Sprache/Version/Modul, Feldgrenzen und eindeutige Options-/Lösungsreferenzen. Fachliche Freigabe erfolgt im separaten Flowise-Prüfer. Auswahlantworten: Vergleich mit gespeicherter Options-ID. Offene Text-/Sprachantworten: persistierter Versuch mit pending/graded/failed, Lehrer-Bewertung anhand der gespeicherten Rubrik, wiederholbar ohne Antwortverlust.
- Lernstände/Analysen sind nach Nutzer, Zielsprache und Kursversion getrennt. `users.active_profile_id` macht den Sprachwechsel explizit; alte Profile bleiben erhalten. Analysen tragen Faktenversionen, ältere Ergebnisse überschreiben keine neueren. Modulziele werden von der KI eingeschätzt und nur mit bewerteten echten Nachweisen in allen sechs Bereichen angezeigt. Anzahl generierter Aufgaben ist kein Abschlusskriterium.
- EnglishCoursePack: sieben Curriculum-Module und 42 geprüfte Reserven. Weitere Sprachen über `InstallPack` mit vollständigem geprüftem Paket; Zweitsprachen-Testfixtures sind kein freigeschalteter Spanischkurs. Keine Übersetzung englischer Regeln im Go-Code.
- A1-Test: zwölf vor Beginn eingefrorene Aufgaben/Rubriken, zwei je Bereich, alle sechs Lernmodule; je Aufgabe eine Testantwort. Schlüssel/Feedback/Hörtexte bleiben bis zu zwölf bewerteten Antworten verborgen, auch in separaten GET-Endpunkten. Gesamtwert = Mittelwert der sechs Bereichswerte. KI-Zusammenfassung kann separat erneut angefordert werden.
- Audio: Browser nimmt maximal 30 s PCM16/mono/16 kHz auf; API prüft tatsächlichen Header und Frames. Freies Sprechen nutzt echte Azure-Transkription, optional echte Aussprachemessung gegen das Transkript; inhaltliche Bewertung durch Lehrer, keine native unscripted Content-Assessment-Auswertung. Rohaufnahmen werden nicht gespeichert; fehlgeschlagene Übertragung behält den Blob im aktuellen Browser. Demo-Messungen ersetzen keine echten Kursnachweise.
- Neu in Konfigurationsvorlagen und Compose: `FLOWISE_COURSE_TEACHER_CHATFLOW_ID`, `FLOWISE_COURSE_TEACHER_API_KEY`; der getrennte Kurs-Generator und der bestehende Aussprache-Flow bleiben separat. Der bisherige v1-Kurs-Flow muss für v2 umgebaut werden; er funktioniert nicht unverändert als neuer Generator.
Validiert: Go-Tests einschließlich Integration gegen eine ausschließlich lokale wegwerfbare PostgreSQL-16-Instanz; Migration/Wiederholung, gespeicherter Brief, Agenten-Transport, Wiederaufnahme, Antwort-Idempotenz, Sprach-/Nutzertrennung, Reservewahl, Test-Unveränderlichkeit/Feedbackschutz/gleichgewichtete Werte. Web-Build und Chromium-Smoke mit realer lokaler API/PostgreSQL und deterministischem Agenten-Ersatz: sieben Module, sechs Bereiche, neue Aufgaben, Hintergrundbewertung, Neuladen, Hörtextschutz, freies Sprechen als Renderer und zwölfteiliger Reservetest. Kein echter Azure-/Mikrofon-/Flowise-Modelltest. Kein Docker-Zugriff aus dieser Agentenumgebung; keine Aussage über laufende VPS-Images. Details zur Wiederholung in `apps/web/tests/README.md`.
## Archiv: vorherige Implementierung und Fehleranalyse
Die folgenden Abschnitte dokumentieren den früheren Stand und frühere Entscheidungen. Aussagen über vier feste Lernziele, englische Satzmuster und ausschließlich v1-Kursgenerierung gelten nicht für die neue adaptive Hauptansicht.
# Projektkontext: Speech
Stand der Codeanalyse: 18. Oktober 2026, Git-Branch `main`, Basis-Commit `83944f7` plus lokale, noch nicht veröffentlichte Kurserweiterung. Diese Datei beschreibt den aktuellen Arbeitsbaum. **Nicht verifiziert** sind der Zustand des laufenden VPS, seine Datenbankinhalte, die tatsächlich veröffentlichte Flowise-Konfiguration und die aktuell gesetzten Zugangsdaten. Aussagen aus früheren manuellen Tests werden ausdrücklich als solche gekennzeichnet.
## Ziel und aktueller Stand
Die Anwendung ist ein Prototyp für Sprachlernen mit Schwerpunkt **englische Aussprache auf A1-Niveau**. Lernende erhalten einen kurzen Satz, hören ihn mit Azure-Stimme an, nehmen ihre eigene Aussprache auf und lassen sie durch Azure Speech bewerten. Die Go-API steuert den Ablauf und speichert Übung und Bewertung in PostgreSQL. Flowise kann die nächste Übung erzeugen; bei Fehlern verwendet die API hinterlegte Übungen. Langfristig soll Flowise didaktische Entscheidungen und Lehrerfeedback liefern, während die Go-API und PostgreSQL die verbindlichen Lernstände verwalten.
Der Flowise-Task `next_exercise` erzeugt weiterhin nur `repeat_sentence`. Lokal implementiert ist nun zusätzlich `generate_course_task` über einen separaten Flow; Deployment und echte Flowise-Anbindung sind noch nicht verifiziert. Zusätzlich gibt es ein erstes redaktionell geprüftes A1-Kursmodul „Sich vorstellen“ mit Wortschatz, Hören, Lesen, Grammatik, Schreiben und Aussprache. Es gibt noch keinen umfassenden `learning_state`, keine dauerhafte Fähigkeitsbewertung pro Lerninhalt und keinen Flowise-Task `evaluate_attempt`.
## Struktur und wichtige Dateien
| Pfad | Aufgabe |
| --- | --- |
| `apps/api/cmd/server/main.go` | API-Start, Datenbankverbindung, Schema/Seeds, Verdrahtung der Dienste |
| `apps/api/internal/config/config.go` | Umgebungsvariablen und Standardwerte |
| `apps/api/internal/httpapi/server.go` | HTTP-Routen und Ablauf für Übung, Audio, Bewertung und Dialog |
| `apps/api/internal/httpapi/{middleware,admin,debug}.go` | Authentifizierung, Admin- und Debug-Endpunkte |
| `apps/api/internal/services/{auth,flowise,speech}.go` | Anmeldung/JWT, Flowise-Anfrage, Azure Speech und TTS |
| `apps/api/internal/store/{store,admin}.go` | PostgreSQL-Schema, Seeds, Abfragen und Admin-Auswertungen |
| `apps/api/internal/store/course.go`, `apps/api/internal/httpapi/course.go` | Kursinhalte, Kursversuche, Audio und Kurs-API |
| `apps/api/internal/domain/models.go` | API- und Domänenmodelle |
| `apps/web/src/app/App.tsx` | Navigation, Anmeldung und Seitenwahl |
| `apps/web/src/pages/{Practice,Progress,Dashboard,Conversation,Admin,Debug}Page.tsx` | Wesentliche Web-Ansichten |
| `apps/web/src/pages/CoursePage.tsx`, `apps/web/src/api/course.ts` | Geführter A1-Kurs und sein API-Client |
| `apps/web/src/components/{AudioRecorder,PhonemeAnalysis,PronunciationText}.tsx` | Audioaufnahme und Ausspracheanzeige |
| `apps/web/src/api/` | Typen und HTTP-Client; Token liegt im Browser-`localStorage` |
| `db/seed/` | Zusätzliche SQL-Dateien; die beim API-Start ausgeführten Seeds stehen in `store.go` |
| `flowise/` | Flowise-Beispiel-Flow, Prompts und Agentflow-V2-Anleitung; keine automatische Synchronisierung mit einer laufenden Flowise-Instanz erkennbar |
| `docker-compose.yml`, `docker-compose.prod.yml`, `docker-compose.dev.yml`, `docker-compose.flowise.yml` | Container-Konfigurationen |
| `deploy/caddy/`, `deploy/env.production.example`, `.env.example`, `README.md` | Reverse-Proxy-Beispiele, Konfigurationsvorlagen und weitere Bedienhinweise |
## Architektur und Datenfluss
```text
Browser (React) -> Caddy /api -> Go-API -> PostgreSQL
|-> Flowise /api/v1/prediction/{FLOWISE_CHATFLOW_ID}
|-> Azure Speech (Aussprachebewertung und TTS)
```
- Der Browser spricht über den konfigurierten API-Basispfad mit der Go-API, nicht direkt mit Flowise oder Azure. Die API authentifiziert und prüft Zugriffe, validiert Flowise-Ausgaben und entscheidet, was in PostgreSQL gespeichert wird.
- Für `POST /lessons/next` liest die API Profil und Fortschritt, sendet ein kompaktes JSON als String im Flowise-Feld `question` und setzt `overrideConfig.sessionId`. Der Inhalt enthält `task: next_exercise`, Sprache, Niveau, Profil, letzte Versuche, schwache Wörter/Phoneme und bis zu drei zu vermeidende Sätze. Die Flowise-Antwort muss das vorgegebene Übungsformat erfüllen; wiederholte Sätze führen zu genau einem erneuten Versuch. Anschließend speichert die API die generierte Übung. Bei fehlender/ungültiger Antwort oder Speicherfehler wählt sie eine Seed-Übung. Auch bei Fallback kann der Endpunkt HTTP 200 liefern: die Log-Zeile `next exercise selected` mit `source` zeigt die Herkunft.
- `POST /practice/attempts` nimmt Audio als Multipart-Upload entgegen. Azure liefert Satz-, Wort- und gegebenenfalls gemessene Phonemwerte. Die API erzeugt derzeit regelbasiertes Lehrerfeedback und speichert Bewertung samt Wort-/Phonemdaten in `attempts`. Die Audioaufnahme selbst wird nicht in PostgreSQL gespeichert.
- `GET /practice/exercises/{id}/audio` erzeugt die Referenzstimme über Azure. `mode=normal` spricht den Satz normal, `mode=slow` langsamer; `mode=focus&word=...` spricht ein im Satz vorhandenes Wort langsam, pausiert und spricht danach den Satz langsamer. Die Antwort ist MP3. Ohne echte Azure-TTS-Konfiguration liefert der Mock hier kein Audio und die API antwortet mit 503.
- PostgreSQL ist die verbindliche Datenquelle. Redis ist in Compose vorgesehen und `REDIS_URL` wird eingelesen; eine tatsächliche Redis-Nutzung in der Go-API ist im untersuchten Code nicht erkennbar.
- Die Produktions-Compose-Datei erwartet ein externes Caddy-Netzwerk (Standardname `web`). In der Entwicklung stehen separate Compose-Dateien bereit.
## Persistenz und Fortschrittslogik
`store.go` erstellt beim API-Start Tabellen mit `CREATE TABLE IF NOT EXISTS`, ergänzt einzelne Spalten und führt Go-seitig definierte Seeds aus. Ein separates Migrationswerkzeug ist nicht erkennbar. Tabellen: `users`, `learner_profiles`, `language_profiles`, `lessons`, `exercises`, `attempts`, `progress_events`, `conversation_sessions`, `conversation_turns` sowie `course_modules`, `course_tasks`, `course_attempts` aus `course.go`. `exercises` speichert bei Flowise-Aufgaben unter anderem Herkunft, Zieltext, TTS-Text, Fokus, Erfolgskriterien und Agent-Kontext. `attempts.word_scores_json` enthält Wortwerte und darin vorhandene Phonemwerte. Kursaufgaben enthalten redaktionelle Lösungen, die der Kurs-GET-Endpunkt nicht ausliefert. Kursversuche werden getrennt gespeichert; Ausspracheaufgaben verknüpfen vorhandene `exercises` und `attempts`.
`store.Progress` berechnet die Anzahl und den Durchschnitt aller Versuche eines Nutzers aus `attempts`. Die jüngsten Versuche sind begrenzt: Dashboard 5, Flowise-Eingabe 10, `/progress` 20. Schwache Wörter werden aus dem **jüngsten** Wert je Wort innerhalb dieses Fensters bei Genauigkeit unter 75 abgeleitet. Schwache Phoneme werden aus dem jüngsten gemessenen Wert je Wort/Phonem abgeleitet, ebenfalls unter 75; höchstens 12 werden zurückgegeben. Bei Wörtern ohne gemessene Phonemwerte wird kein Phonemproblem behauptet. Es gibt derzeit keine gesonderte persistente Review Queue, keinen Status für einzelne Fähigkeiten wie `active_recall` und keine automatische Entscheidung über abgeschlossene Teilniveaus.
## Bereits implementierte Funktionen
- Registrierung, Login, geschützte API-Routen, Nutzerpräferenzen für Sprache/Niveau/Tagesziel sowie Sprach- und Stimmenliste. JWTs gelten 24 Stunden; öffentliche Registrierung erstellt nur die Rolle `learner`.
- Dashboard, Ausspracheübung, Fortschrittsansicht und einfacher textbasierter Dialog. Der Dialog wird derzeit durch feste Antworten in `services/flowise.go` geführt; er ist noch kein dynamischer Agentendialog.
- Flowise-Übungsgenerierung mit Formatprüfung, Wiederholungsschutz, einem erneuten Versuch bei Duplikaten und Seed-Fallback.
- Aufnahme im Browser, Anhören der eigenen Aufnahme, erneutes Aufnehmen vor dem Absenden, Azure-Bewertung, Anzeige der Scores und Wort-/Phonemanalyse. Die Aufnahme wird erst beim expliziten Bewerten hochgeladen.
- Referenzsatz als Azure-TTS-Audio in normaler und langsamer Geschwindigkeit; nach Bewertung langsame Hörhilfe für erkannte schwierige Wörter. Die Web-Seite hält die angeforderten Audio-Clips nur zeitweise im Browser vor.
- A1-Kursmodul „Sich vorstellen“ mit je zwei Aufgaben in sechs Bereichen. Die Go-API bewertet Auswahl- und kurze Schreibantworten; Hörtexte werden über Azure TTS abgespielt und erst nach der Antwort als Abschrift angezeigt. Der Kurs zeigt Bearbeitung und erreichte Aufgabenziele getrennt an. Weitere Module müssen noch erstellt werden.
- Admin-Ansicht mit Gesamtnutzern, in den letzten sieben Tagen anhand von Versuchen aktiven Nutzern, Versuchszahl, Zahl der Flowise-Übungen, Durchschnittswert und durchsuchbarer Nutzerliste. Die API prüft die Admin-Rolle serverseitig. Bei `DEBUG_ENABLED=true` sind zusätzliche Debug-Endpunkte nur für Admins erreichbar.
## Bekannte Grenzen und offene Aufgaben
1. `FeedbackForAttempt` verwendet `mockFeedback` im Go-Code. `evaluate_attempt` ruft Flowise noch nicht auf. Die statischen Lehrerhinweise können daher trotz guter Scores wenig differenziert sein. Für echtes didaktisches Feedback braucht es ein eigenes, validiertes Flowise-Ergebnis und eine klare Trennung von Empfehlung und dauerhaftem Lernstatus.
2. Der gewünschte aggregierte `learning_state` mit Fähigkeiten pro Wort, Trends, Wiederholungsfälligkeit und Lernziel fehlt. Die derzeitige Fortschrittszusammenfassung nutzt nur die oben beschriebenen Versuchsfenster.
3. Die Aussprache-Generierung ist auf `repeat_sentence` ausgerichtet. Der geführte Kurs enthält zwar weitere feste Aufgabentypen, aber noch keinen umfassenden adaptiven Lernplan, keine freie Schreibbewertung, kein Spaced Repetition und keinen dynamischen Dialog. Für das erste Modul gibt es lokal zusätzliche Flowise-Auswahlaufgaben zu vier geprüften Wortschatz-/Grammatikzielen; Auswahl anhand bisheriger Kursversuche, keine Beherrschungsentscheidung.
4. Die Admin-Seite zeigt Daten an. Kauf, Abonnement, Zahlung, Berechtigungen für Produkte und Verwaltungsaktionen sind im untersuchten Code nicht implementiert.
5. TTS setzt echte Azure-Zugangsdaten und `AZURE_ENABLE_MOCK=false` voraus. Der Mock liefert keine echte Referenzstimme und keine gemessenen Phonemwerte.
6. **Historisch beobachtet, aktueller VPS-Zustand nicht verifiziert:** Bei Docker-Builds schlug DNS im Build-Netz fehl (`EAI_AGAIN` für `registry.npmjs.org`). `npm ci` hinterließ damals unvollständige Pakete, weshalb `tsc: not found` erschien. Ein Build mit `buildx --network=host --allow=network.host` funktionierte. Das ist kein nachgewiesener Fehler im Anwendungscode.
## Abhängigkeiten und Befehle
- API: Go 1.23, `pgx/v5` für PostgreSQL; der Docker-Build verwendet vendorte Go-Abhängigkeiten. Web: Node 20 zum Bauen, React 19, TypeScript 5, Vite 6 und Nginx im Produktionsimage. Dienste: PostgreSQL 16, Redis 7 (bereitgestellt), externe Flowise- und Azure-Speech-Dienste; Caddy als Reverse Proxy.
- Erforderliche Produktionswerte laut Compose: `POSTGRES_PASSWORD`, `APP_JWT_SECRET`, `CORS_ORIGINS`. Für echte Azure-Funktionen zusätzlich `AZURE_SPEECH_KEY`, `AZURE_SPEECH_REGION`, `AZURE_ENABLE_MOCK=false`; für Flowise `FLOWISE_BASE_URL`, `FLOWISE_CHATFLOW_ID` und bei geschütztem Flow `FLOWISE_API_KEY`. `VITE_API_BASE_URL` ist ein **Build-Argument** der Web-App, Standard `/api`. Vorlagen: `.env.example` und `deploy/env.production.example`. Zugangsdaten werden nicht ausgegeben. Für einen kurzlebigen lokalen Verbindungscheck wurden ausschließlich die Flowise-Konfigurationswerte aus `.env` verwendet; die Datei blieb unverändert. Der Versuch konnte die Live-Anbindung nicht bestätigen.
```bash
# Entwicklung mit Containern
docker compose -f docker-compose.dev.yml up -d --build
# Prüfungen aus dem Projektverzeichnis
(cd apps/api && go test ./...)
(cd apps/web && npm ci && npm run build)
# Produktions-Compose aus dem Projektverzeichnis
docker compose up -d --build speech-api speech-web
docker compose logs --since=10m speech-api
```
Falls der Docker-Build erneut am **Build-Netz** scheitert, kann nach Prüfung des Host-Netzwerks jedes geänderte Image separat gebaut und anschließend mit Compose gestartet werden:
```bash
docker buildx build --network=host --allow=network.host --load -t speech-speech-api -f apps/api/Dockerfile apps/api
docker buildx build --network=host --allow=network.host --load -t speech-speech-web -f apps/web/Dockerfile.prod apps/web
docker compose up -d --no-build --force-recreate speech-api speech-web
```
Die Image-Namen `speech-speech-*` setzen den Compose-Projektnamen `speech` voraus; bei anderem Projektnamen vorher `docker compose config --images` prüfen. Nach API-**und** Web-Änderungen beide Images neu bauen. `dc` war auf dem früheren VPS ein lokales Kürzel für Compose, kein projektweit bereitgestellter Befehl.
## Hinweise für zukünftige Codex-Sitzungen
- Eingeschränkten aktuellen Stand von Flowise und Dialog nicht mit der Zielarchitektur verwechseln. Die `flowise/`-Dateien beweisen nicht, welcher Flow auf dem Server veröffentlicht ist. Auch die aktuell verwendeten Azure-Stimmen, Zugangsdaten, Datenbankdaten und der erfolgreiche Produktionsbetrieb sind aus dem Repository nicht verifizierbar.
- PostgreSQL und Go-API bleiben zuständig für verbindliche Fortschritts- und Berechtigungsentscheidungen. Flowise-Ausgaben immer validieren; keine Agenten-Aussage als gemeistertes Wort oder Niveauabschluss speichern.
- `README.md` und ältere Flowise-Beispiele können vom Code abweichen. Für aktuelle Endpunkte, Fallbacks und Datenbankstruktur zuerst `server.go`, `services/flowise.go` und `store.go` prüfen.
- `.env` und andere Zugangsdaten nicht ausgeben oder committen. `.gitignore` schließt `.env`, `node_modules/` und `dist/` aus.
- Änderungen möglichst inkrementell halten. Ein Git-Push und ein Neustart auf dem VPS sind eigene Schritte; der Nutzer hat in dieser Unterhaltung den Container-Neustart zuletzt selbst übernommen. Bei Fehlersuche zuerst Herkunft der Übung (`source`) und API-Logs prüfen, dann Flowise-Ausgabe und Validierungsgrund.
**Verifikationsgrenze:** Codeanalyse sowie erfolgreiche Go-Tests, Web-Build, PostgreSQL-16-Integrationstest und lokaler Chromium-Browsertest mit echter Go-API/PostgreSQL und simuliertem Flowise-Dienst. Nicht verifiziert sind die echte Flowise-Integration, Azure und der VPS-Zustand. Keine Produktionsdatenbank abgefragt und keine Aussage darüber, welches Image auf dem VPS gerade läuft.
## Lokale Erweiterung: zusätzliche Kursaufgaben (18. Oktober 2026)
- Zweiter Flow über `FLOWISE_COURSE_CHATFLOW_ID`, optional `FLOWISE_COURSE_API_KEY` (Fallback auf gemeinsamen Key). Bestehender Aussprache-Flow unverändert. Config, Compose und Env-Vorlagen sind ergänzt; reale `.env` wird nicht durch Code bearbeitet.
- Neue Dateien: `domain/course_generation.go`, `services/course_generation.go`, `store/course_generation.go`, `httpapi/course_generation.go` unter `apps/api/internal/`. Vertrag, aktueller Systemprompt und Testeingabe stehen in `flowise/README.md`.
- Neue authentifizierte Endpunkte: `POST /course/modules/{id}/practice/next` (`request_id`), `GET /course/modules/{id}/practice`. Antworten verwenden weiterhin `POST /course/tasks/{id}/attempts`. Öffentliche Aufgaben enthalten keine Lösung.
- Erste Version: nur `en-US`, `A1`, Modul `a1_introductions_v1`, `choice`; Ziele `introductions.name`, `introductions.from`, `introductions.be_i`, `introductions.be_name`. Go übermittelt Ziel, Vorlagen und zulässige Optionen. Die Validierung prüft Kontext, Satzmuster und verbindliche Lösung zusätzlich zur JSON-Struktur. Neue Ziele brauchen geprüfte Serverregeln. Modell-Erklärungen werden auf Format/Länge geprüft, nicht vollständig fachlich bewiesen.
- Kursversuche der festen Aufgaben fließen über Seed-ID-Zuordnung in die Auswahl ein. Letzte falsche Antwort priorisiert, dann unbearbeitete Ziele, dann ältere; keine dauerhafte Mastery. Bis zu fünf aktuelle Ergebnisse und fünf zu vermeidende generierte Prompts werden übermittelt, keine persönlichen Identifikatoren oder Audio.
- `course_tasks` erhält additiv Herkunft, Eigentümer, Ziel, Schema-Version, Zeitstempel, Request-ID und normalisierten Prompt-Fingerprint. Bestehende Seeds und Lösungen bleiben unverändert. Eigentümerprüfung beim Laden des Lösungsschlüssels und Speichern von Versuchen; eindeutige Indizes gegen doppelte Generierungsanfragen und gleiche generierte Prompts pro Nutzer.
- Feste Modulabfragen enthalten weiterhin nur Seeds: zwölf Kernaufgaben. Eigene Zusatzaufgaben werden getrennt angezeigt; Historie auf 50 neueste begrenzt. Generierung selbst verändert keinen Fortschritt. Fallback verwendet eine echte feste Aufgabe; deren Beantwortung zählt wie bisher für diese Kernaufgabe.
- Bei fehlendem Kurs-Flow, Fehler, ungültiger Ausgabe oder Speicherfehler Seed-Fallback; bei vollständigem DB-Ausfall Fehler. Timeout 25 Sekunden, Antwort maximal 64 KiB. Logs: `course generation fallback` mit Grund und `course practice selected` mit Quelle und Aufgaben-ID.
- PostgreSQL-Integrationstest opt-in mit `COURSE_TEST_DATABASE_URL` (separate Testdatenbank, zufälliges Schema). Testet Upgrade aus dem alten Kursschema, Bestandsschutz, wiederholtes Init, Isolation, Antworten und gleichzeitige idempotente Speicherung. Keine Produktionsdatenbank abfragen.
- Noch nicht veröffentlicht: kein Commit, Push oder VPS-Neustart. Bereits bestehende uncommittete Kurserweiterung bleibt erhalten.
### Verifikation dieser Erweiterung
- `go test ./...` erfolgreich, einschließlich `TestCourseGenerationPostgres` gegen eine temporäre lokale PostgreSQL-16-Instanz mit isoliertem Testschema.
- `npm run build` erfolgreich.
- Lokaler Chromium-Test mit realer API, PostgreSQL und simuliertem Flowise erfolgreich: Generierung, Antwort, unveränderter Kernfortschritt bei generierten Aufgaben, persistierte Historie nach Reload, Flowise-Ausfall und erneute Verwendung einer festen Kursaufgabe. Keine Browser-Laufzeitfehler. Browser-Testskript und Hilfsdienste lagen ausschließlich unter `/tmp`, nicht im Repository.
- Ein kurzer Aufruf des echten Kurs-Flows mit der lokalen Flowise-Konfiguration lieferte aus dieser Umgebung keine bestätigte gültige Antwort. Keine Zugangsdaten ausgegeben oder Konfiguration geändert. Daher bleibt der echte API-zu-Flowise-Test offen.
### Korrektur zur Rückmeldung am Zusatzaufgaben-Button (21. Oktober 2026)
- Bei gemeldetem „Klick ändert nichts“ ließ sich ein Frontend-Fehler reproduzieren: Ohne `crypto.randomUUID` scheiterte der Klick vor dem API-Aufruf; der Fehlertext erschien außerhalb des sichtbaren Bereichs. Ob dies die konkrete Ursache auf dem laufenden VPS ist, bleibt ohne Logs/Browsermeldung offen.
- Request-IDs verwenden nun `crypto.getRandomValues` (32 Hex-Zeichen, vom bestehenden API-Vertrag akzeptiert); Wiederholungen nach Fehler behalten dieselbe ID. Ladezustand, Erfolg/Fallback und Generierungsfehler erscheinen direkt beim Button. Geladene Aufgaben werden fokussiert und ins Sichtfeld gescrollt.
- Web-Build und Chromium-Regression mit simulierten API-Antworten geprüft, einschließlich fehlendem `randomUUID`, sichtbarem API-Fehler und Wiederholungs-ID.
- In der aktuellen Agent-Terminalumgebung ist `docker` nicht vorhanden. Laufende VPS-Container und deren Logs konnten hier nicht geprüft werden. Keine Container neu gebaut oder neu gestartet.
### Diagnose anhand der VPS-Logs (21. Oktober 2026)
- Nutzerlogs bestätigen erfolgreiche POSTs auf `/course/modules/a1_introductions_v1/practice/next` (HTTP 200). Beide Aufrufe fallen mit `invalid course task fields` auf `a1i_v1_grammar_1` zurück. Damit erklärt sich die wiederholt gleiche Aufgabe. Die konkrete Abweichung der echten Flowise-Ausgabe ist noch nicht bekannt.
- Der Parser verwarf bisher Fehler aus `json`/`text`/`output` und meldete anschließend nur den Fehler beim Lesen der gesamten Transportantwort. Lokal korrigiert: Herkunft und konkrete Typ-, Pflichtfeld-, unbekannte-Feld- oder Syntaxfehler bleiben erhalten; Markdown-Codeblöcke werden explizit benannt. Keine Rohantworten protokollieren. Ein leeres strukturiertes `json` darf eine gültige `text`-Antwort nicht mehr verdecken.
- Go-Tests einschließlich Regressionstests erfolgreich. Keine Bereitstellung oder Neustarts durch den Agent. Für die endgültige Korrektur wird die tatsächliche Antwort aus Flowise oder die präzisere Fehlermeldung nach Bereitstellung dieser Diagnose benötigt.
### Bestätigte Ursache und Parserkorrektur (21. Oktober 2026)
- Die präziseren VPS-Logs bestätigen: `text` enthält einen Markdown-Codeblock um das JSON. Dies verursachte den Fallback.
- Der Kursparser entfernt nun genau einen vollständigen äußeren Codeblock (ohne Sprachangabe oder `json`, auch CRLF/Großschreibung). Struktur-, Pflichtfeld-, Options-, Lernziel- und Lösungsvalidierung bleiben erhalten. Zusatztext, mehrere Blöcke/Objekte, unbekannte Felder und falsche Lösungen werden weiterhin verworfen.
- Go-Tests einschließlich simulierter Flowise-HTTP-Antworten mit Codeblock sowie Negativfällen erfolgreich. API-Neubau und anschließender echter Klicktest durch den Nutzer stehen noch aus; kein Neustart durch den Agent. Keine weitere Änderung am Flowise-Systemprompt für diese Verpackung nötig.
### Tatsächliche Flowise-Aufgabe und Satzprüfung (21. Oktober 2026)
- Nutzer hat die tatsächliche Ausgabe geliefert: `Ergänze: I ___ a student. (Wähle die richtige Form aus.)`, Lösung `am`. Das ist eine fachlich gültige Selbstvorstellung zum Ziel `introductions.be_i`; die bisherige Prüfung akzeptierte ausschließlich Namen/Herkunft und lehnte den Klammerhinweis ab.
- Satzprüfung erweitert um die geprüfte Form `a student` sowie den optionalen Hinweis `(Wähle die richtige Form aus.)` bei Grammatik. Abschluss-Punkt und mehrfache Leerzeichen sind optional. Keine beliebigen englischen Fortsetzungen zulassen: etwa `I ___ like school` oder ein Wechsel zu `She` bleibt ungültig; verbindliche Lösung bleibt `am` bzw. beim Namensziel `is`.
- Die vollständige reale Antwort ist als Regressionstest erfasst, einschließlich äußerem Flowise-Codeblock. Gesamte Go-Tests erfolgreich. Diese konkrete Antwort wird nun lokal akzeptiert; echte Generierung und Speicherung nach dem API-Neubau sind noch durch den Nutzer zu bestätigen. Kein Neustart/Push durch den Agent.
### Wortschatz-Fallback und sichtbare Herkunft (21. Oktober 2026)
- Weitere echte Antwort des Nutzers: Frage zu `name` in `Hello, my name is Anna.`, Optionen `Vornamen`, `Nachname`, `Name`. Die Antwort weicht von Vorlage und erlaubten Optionen `Name`, `Wohnort`, `Alter` ab; die Optionen sind zudem nicht eindeutig getrennt. Die zugehörigen Logs belegen `source: seed`, also eine bewusst ersetzte Aufgabe. `avoid_prompts` enthielt bereits die gespeicherte generierte student-Aufgabe; es war somit nicht ausschließlich Seed-Betrieb.
- Neue API-Eingabehinweise `rules` verlangen ausdrücklich die Vorlage (nur Platzhalter ersetzen), exakt die erlaubten Optionen und die Ausgabe-Felder. Bei Parser-/Validierungsfehler genau ein Korrekturversuch mit `retry_instruction` und gleichem Kontext innerhalb des gemeinsamen 25-Sekunden-Handlerlimits. Kein automatischer Wiederholungsversuch bei HTTP-/Netzfehlern. Danach unverändert Seed-Fallback. Log: `course generation requesting correction`. Keine Rohantwort im Korrekturkontext.
- Öffentliche Kursaufgaben erhalten additiv `source`. Die UI zeigt bei aktiven Zusatzaufgaben `Mit Flowise erstellt` oder `Feste Kursaufgabe zur Wiederholung`, auch aus der Historie. Herkunft kommt aus PostgreSQL bzw. der tatsächlichen API-Antwort, nicht aus Modellangaben. Kein neues Datenbankschema nötig.
- Go-Tests mit realem ungültigem Wortschatz-Beispiel und simuliertem Korrekturaufruf sowie Web-Build erfolgreich. Weiterhin keine Bereitstellung durch den Agent; API und Web müssen für diese Änderung neu gebaut werden.
### Wiederholter Wortschatz-Fallback trotz Korrekturversuch (21. Oktober 2026)
- Die nächsten Nutzerlogs zeigen drei weitere Seeds für `introductions.name` nach je einem Korrekturversuch. Der tatsächliche korrigierte Prompt fehlt in diesen Logs. Die bisher übermittelte zulässige Kontextvariante `Hello, my name is Anna` scheiterte auch mit korrekten Optionen an der zu wörtlichen Satzprüfung.
- Wortschatzprüfung akzeptiert jetzt äquivalente Kontexte mit optionalem `Hello`/`Hi`, Groß-/Kleinschreibung, gebräuchlichen Anführungszeichen und Fragen mit `bedeutet`/`heißt`. Für Herkunft sind `I am`, `I'm`, `He is` und `She is` zulässig. Erfragtes Wort, Kontext der persönlichen Vorstellung, erlaubte eindeutige Optionen und verbindliche Lösung bleiben erforderlich. Negation, andere Wortbedeutungen und zusätzliche Sätze werden getestet und abgelehnt.
- Neue Diagnose `course generation rejected` protokolliert den auf 240 Zeichen begrenzten öffentlichen Prompt, Lernziel, Versuch und Ablehnungsgrund. Keine Lösungen, vollständigen Modellantworten oder Lernstände loggen. Ungültige Optionen werden mit Verweis auf `learning_goal.allowed_forms` benannt.
- Go-Tests erfolgreich; echte Ausgabe nach dieser API-Korrektur weiterhin vom Nutzer zu prüfen. Keine Container durch den Agent neu gestartet.