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.
This commit is contained in:
Eugenius Naumenko
2026-11-01 23:23:27 +00:00
parent e274eaab2b
commit 2c24c18614
7 changed files with 1108 additions and 54 deletions
+44 -54
View File
@@ -1,21 +1,51 @@
# Speech Learning App
Sprachlern-App für Ausspracheübungen auf A1-Niveau. Die Web-App nimmt Sprache auf und zeigt Übungen sowie Bewertungen an. Die Go-API steuert den Ablauf, speichert den Lernverlauf in PostgreSQL, lässt Flowise neue Übungen erzeugen und ruft Azure Speech zur Aussprachebewertung auf.
Hinweise für Coding-Agenten und Beitragsarbeit: [AGENTS.md](AGENTS.md).
## Klare offene Aufgaben (01.11.2026)
Die 140 freien Sprech- und Schreibaufgaben benennen ihre Anforderungen konkret und erlauben eigene oder erfundene Angaben. Beim freien Sprechen zeigt die App die KI-Bewertung als **Inhalt und Sprache**, den erkannten Text und den separaten Azure-Aussprachewert. Korrigierte Aufgaben erhalten neue IDs; historische Aufgaben und Bewertungen bleiben erhalten. Nach dem API-/Web-Neubau eine neue Aufgabe anfordern.
## Statistisches Aussprachetraining (29.10.2026)
`PRONUNCIATION_STRATEGY=statistical` bündelt echte Azure-Nachsprechmessungen aus Aussprache und A1-Kurs. Derselbe Laut wird über mehrere Wörter hinweg betrachtet. Go ermittelt Nachweisdichte, Entwicklung und Wiederholungstermine und speichert den Trainingsauftrag; das bestehende Modellprofil `next_exercise` gestaltet daraus einen Satz. Neue Wortkontexte bleiben bis zur passenden Azure-Messung unbestätigt. Im Fortschritt sind Lautprofile und Beispielwörter sichtbar, bei Übungen der Grund für die Auswahl.
Unbekannte historische Messherkunft wird nicht nachträglich als Azure bestätigt. Alte Antworten bleiben erhalten; der Verlauf kann deshalb mehr Versuche enthalten als das neue Lautprofil. `PRONUNCIATION_STRATEGY=recent` behält die bisherige Auswahl bei, während die neue Messgrundlage weiter gesammelt und angezeigt werden kann. Details und Prüfanleitung stehen in [docs/AI_OPERATIONS.md](docs/AI_OPERATIONS.md).
## Geprüfter Aufgabenbestand (26.10.2026)
Der A1-Kurs verwendet standardmäßig `COURSE_TASK_MODE=bank`: **840 vorbereitete Englischaufgaben**, 20 je Modul und Lernbereich. Go wählt anhand gespeicherter Bewertungen neue Aufgaben und passende Wiederholungen aus. Für Erstellung, Auswahl und Fortschrittsanzeige werden dabei keine Modelle aufgerufen. Der bisherige Generator bleibt mit `COURSE_TASK_MODE=ai` verfügbar. Der separate Aussprachebereich behält seine bisherige Modellanbindung.
Offene Antworten können ohne KI gespeichert und anhand von Beispielen und Kriterien selbst verglichen werden. Sie erhalten dann ausdrücklich keine Note. Eine spätere KI-Bewertung benötigt ein aktiviertes, eingerichtetes Bewertungsprofil und ausreichendes Budget. Azure Speech bleibt für Hörtexte und Sprachmessungen zuständig und hat eigene Kosten.
Betriebsanleitung: [docs/AI_OPERATIONS.md](docs/AI_OPERATIONS.md). Die echte `.env`, Modellprofile, Budgets und laufende VPS-Dienste wurden durch den Bankumbau nicht geändert. Historische Aufgaben und Lernantworten bleiben erhalten.
## Aktueller Funktionsumfang
- Registrierung, Login und Lernerprofil mit Zielsprache, Oberflächensprache und Tagesziel
- Kurze englische `repeat_sentence`-Übungen aus Flowise; Seed-Übungen als Fallback
- Kurze englische `repeat_sentence`-Übungen aus direkten Modellaufrufen; Seed-Übungen als Fallback
- Audioaufnahme im Browser und Aussprachebewertung über Azure Speech
- Gesamt-, Wort- und bei echten Azure-Antworten auch Phonemwerte
- Feedback zum Versuch sowie Fortschrittsansicht mit schwachen Wörtern und Lauten
- Mock-Modus für lokale Entwicklung ohne Azure-Zugang
- Adaptiver A1-Kurs mit sieben Modulen, sechs Bereichen, persönlicher Aufgabenplanung und zwölfteiligem A1-Test
- Bisheriger fester Kurs „Sich vorstellen“ bleibt über eine eigene Schaltfläche erreichbar
Weitere Übungstypen, ein `evaluate_attempt`-Flowise-Task und ein langfristiges Fähigkeitsmodell pro Wort sind noch nicht implementiert.
Auswahlantworten bewertet die Go-API anhand des gespeicherten Lösungsschlüssels. Offene Kursantworten und freie Sprache werden nur bei verfügbarem Bewertungsmodell anhand der gespeicherten Rubrik benotet; andernfalls bleiben sie gespeichert und unbenotet. Der bisherige Aussprachebereich verwendet weiter seinen eigenen `next_exercise`-Aufruf und seine bestehende Feedbacklogik.
## A1-Kurs
Der Menüpunkt **A1-Kurs** öffnet sieben frei wählbare Module mit Grammatik, Wortschatz, Hören, Lesen, Sprechen und Schreiben. **Nächste Aufgabe** wählt aus dem geprüften Bestand: noch nicht gezeigte Aufgaben zuerst, bei belegtem Lernbedarf passende Lernziele, nach Ausschöpfen des Bereichs Wiederholungen. Schwierigkeit und Wiederholung beruhen auf tatsächlich bewerteten Antworten. Auch bereits gezeigte, noch unbeantwortete Aufgaben zählen als gesehen, nicht als Leistungsnachweis. Im Browser stehen Herkunft und verbleibender Bestand.
Die 840 Aufgaben liegen in 42 versionierten JSON-Dateien unter `apps/api/internal/store/coursebank/en-US/a1-v2/`. Ihre redaktionellen Quellen und der an Dateiprüfsummen gebundene Prüfvermerk liegen unter `tools/course_bank/`. Es gibt 560 Auswahlaufgaben, je 70 kurze und freie Schreibaufgaben sowie je 70 Nachsprech- und freie Sprechaufgaben. Hörtexte bleiben bis zur zulässigen Freigabe privat. Alte Reserven bleiben als Rückfall erhalten.
Der A1-Test besteht aus zwölf vor der ersten Antwort eingefrorenen Aufgaben, zwei je Lernbereich, mit Abdeckung der sechs Lernmodule. Nach zwölf Abgaben ohne vollständige Bewertung erscheint **Abgegeben – Bewertung ausstehend**. Erst nach vollständiger Bewertung werden Lösungen und Gesamtnote gezeigt. Gespeicherte unbenotete Antworten begründen keinen Modulabschluss. Das Testergebnis ist eine interne Lerneinschätzung, kein Zertifikat.
`GET /course/catalog` liefert das aktive Sprachprofil, Module und Lernstand; `POST /course/modules/{id}/tasks/next` nimmt `request_id` und optional `skill` entgegen und liefert einen Auftrag (HTTP 202). Der Browser verfolgt ihn über `/course/jobs/{id}`. Vollständige API- und KI-Verträge stehen in [docs/AI_OPERATIONS.md](docs/AI_OPERATIONS.md). Nutzer, Zielsprache und Kursversion trennen alle neuen Kursdaten. Der alte feste Kurs und seine bisherigen Endpunkte bleiben erhalten; historische Versuche werden idempotent in den neuen Lernstand übernommen.
## Adminbereich
Die App besitzt einen geschützten Adminbereich unter dem Menüpunkt **Adminbereich**. Er zeigt die Zahl aller Konten, aktive Nutzer der letzten sieben Tage (mindestens ein Sprechversuch), alle Sprechversuche, die Zahl gespeicherter Flowise-Übungen und die durchschnittliche Gesamtbewertung. Die Nutzerliste kann nach E-Mail durchsucht werden, zeigt Registrierungsdatum, Rolle und aggregierte Lernaktivität und lädt höchstens 25 Konten pro Seite. Audio und vollständige Versuchstexte werden dort nicht angezeigt.
Die App besitzt einen geschützten Adminbereich unter dem Menüpunkt **Adminbereich**. Er zeigt die Zahl aller Konten, aktive Nutzer der letzten sieben Tage (mindestens ein Sprechversuch), alle Sprechversuche, die Zahl gespeicherter KI-Übungen und die durchschnittliche Gesamtbewertung. Die Nutzerliste kann nach E-Mail durchsucht werden, zeigt Registrierungsdatum, Rolle und aggregierte Lernaktivität und lädt höchstens 25 Konten pro Seite. Audio und vollständige Versuchstexte werden dort nicht angezeigt.
Adminrechte werden **bei jedem Admin-API-Aufruf** aus PostgreSQL gelesen. Ein Lernender bekommt für `GET /admin/overview` und `GET /admin/users` HTTP 403; ohne Anmeldung ist es HTTP 401. Eine versteckte Web-Seite allein wäre kein Zugriffsschutz. Öffentliche Registrierung erstellt ausschließlich Konten mit der Rolle `learner`. Die Rolle wird beim Start der API auch für bestehende Datenbanken als neue Spalte angelegt. Wenn Debug aktiviert ist, sind die Debug-Endpunkte ebenfalls nur für Admins zugänglich.
@@ -40,7 +70,7 @@ Es gibt bewusst keinen öffentlichen Endpunkt, über den Nutzer sich selbst Admi
### Vorbereitung für ein Kaufprodukt
Der Adminbereich ist derzeit eine **Betriebs- und Nutzerübersicht**. Er zeigt keine Umsätze oder Abonnements, weil die App noch keinen Produktkatalog, Zahlungsanbieter oder Kaufberechtigungen besitzt. Für den Verkauf sind als nächste Ausbaustufen sinnvoll:
Der Adminbereich ist derzeit eine **Betriebs-, KI- und Nutzerübersicht**. Er zeigt keine Umsätze oder Abonnements, weil die App noch keinen Produktkatalog, Zahlungsanbieter oder Kaufberechtigungen besitzt. Für den Verkauf sind als nächste Ausbaustufen sinnvoll:
1. Produkte und Tarife mit Preis, Laufzeit und enthaltenen Lernfunktionen definieren.
2. Einen Zahlungsanbieter anbinden und signierte Webhooks verarbeiten. Zahlungen und Rückerstattungen müssen nachvollziehbar gespeichert werden.
@@ -52,25 +82,12 @@ Solange diese Teile fehlen, bleibt die Lern-App für registrierte Nutzer unabhä
## Architektur und Datenfluss
```text
Browser/Web-App ──► Go-API ──► Flowise (nächste Übung)
│
├──────► Azure Speech (Aussprachebewertung, TTS)
├──────► PostgreSQL (Profile, Übungen, Versuche)
└──────► Redis
Browser/Web-App → Go-API → PostgreSQL (Bestand, Auswahl, Antworten, Fortschritt)
├→ Azure Speech (Aussprache, Transkription und TTS)
└→ DeepSeek / Mistral (optionale Bewertung bzw. KI-Modus)
```
Der Browser spricht nur mit der Go-API. API-Schlüssel für Flowise und Azure bleiben serverseitig. Die Go-API authentifiziert Nutzer, prüft Flowise-Antworten und entscheidet, was dauerhaft gespeichert wird. PostgreSQL ist die verbindliche Quelle für Übungen und Lernverlauf. Flowise erzeugt didaktisch passende Aufgaben, ändert aber keinen Lernstatus in PostgreSQL.
Eine Übungsrunde läuft so ab:
1. Die Web-App lädt das Dashboard oder fordert über `POST /lessons/next` eine neue Übung an.
2. Die Go-API liest Profil und letzte Versuche aus PostgreSQL. Sie erstellt daraus einen kompakten Kontext und sendet `task: "next_exercise"` an Flowise.
3. Die Go-API prüft die erzeugte `repeat_sentence`-Übung und speichert sie. Falls Flowise ausfällt oder keine gültige Übung liefert, verwendet die API eine Seed-Übung.
4. Die Web-App zeigt den Satz, nimmt Sprache auf und sendet Audio und `exercise_id` an `POST /practice/attempts`.
5. Die Go-API schickt das Audio mit dem Referenzsatz an Azure Speech, verarbeitet die Bewertung und speichert den Versuch in PostgreSQL.
6. Die Web-App zeigt Ergebnis und Lehrerfeedback. `GET /progress` liefert die letzten Versuche sowie daraus berechnete schwache Wörter und Laute.
Flowise wird bei der **unmittelbaren Bewertung** eines Versuchs derzeit nicht aufgerufen. Das Lehrerfeedback entsteht in der Go-API anhand der Azure-Werte. Insbesondere entscheidet Flowise weder über „gemeistert“ noch über einen Niveauwechsel.
Der Browser verwendet nur die Go-API. API-Schlüssel bleiben serverseitig. Im Bankbetrieb übernimmt Go die Auswahl aus dem gespeicherten Bestand. Im optionalen KI-Modus analysieren Modelle Lernstände, planen, erzeugen und prüfen Aufgaben. Go verwaltet gespeicherte Nachweise und technische Verträge. Redis ist in Compose vorhanden, die Kurs-Queue liegt in PostgreSQL. Die unmittelbare Bewertung im bisherigen Aussprachebereich nutzt weiterhin Azure plus bestehendes Go-Feedback; offene Kursantworten bewertet der KI-Lehrer. Der einfache Dialog behält seinen bisherigen Funktionsumfang.
## Aussprachebewertung auf Phonemebene
@@ -115,35 +132,9 @@ PostgreSQL speichert `phoneme_scores` als Teil des bestehenden `attempts.word_sc
Das ist eine **Momentaufnahme aus den letzten Versuchen**, keine dauerhafte Diagnose oder ein über alle Zeiten berechneter Beherrschungsgrad. Schwache Wörter werden unabhängig davon ebenfalls aus dem jüngsten Wortwert im betrachteten Fenster berechnet.
## Flowise-Anbindung
## KI-Einrichtung und Verbrauch
Die Go-API ruft `POST /api/v1/prediction/{FLOWISE_CHATFLOW_ID}` auf. Das Feld `question` enthält den Lernkontext als JSON-String; `overrideConfig.sessionId` ordnet die Anfrage der Übungssitzung zu. Der derzeit unterstützte Task heißt `next_exercise`.
Zum Kontext gehören unter anderem `profile`, `progress`, `recent_weak_words`, `recent_weak_phonemes`, `preferred_type` und die zuletzt benutzten Sätze unter `avoid_reference_texts`. Einzelne rohe `phoneme_scores` aus allen jüngsten Versuchen werden vor dem Flowise-Aufruf entfernt; die kompakte Liste `recent_weak_phonemes` transportiert den relevanten Lautfokus. Flowise soll einen anderen Satz als die zuletzt verwendeten erzeugen, kann aber dasselbe Zielwort erneut üben.
Der Flowise-Flow braucht weiterhin einen Learning Planner und einen Exercise Generator. In der bestehenden Flowise-Oberfläche ist die Eingabe als `{{question}}` verfügbar. Ergänze im **Planner-Prompt** sinngemäß diese Regel:
```text
Lies recent_weak_phonemes aus dem Eingabe-JSON. Wenn dort gemessene niedrige Werte stehen, darfst du das zugehörige Wort für eine Ausspracheübung wählen. Nenne einen konkreten Laut nur, wenn er mit Messwert übergeben wurde. Ein niedriger Wortwert allein belegt keinen bestimmten Lautfehler. Erfinde keine Lautprobleme, Trends oder abgeschlossenen Lernstufen.
```
Der **Generator** soll das vom Planner gewählte Zielwort in einen kurzen natürlichen A1-Satz aufnehmen. `focus_points` dürfen einen konkreten Laut nur nennen, wenn der Planner ihn aus einem gemessenen `recent_weak_phonemes`-Eintrag übernommen hat. Das Antwortschema bleibt unverändert:
```json
{
"exercise_type": "repeat_sentence",
"target_language": "en-US",
"cefr_level": "A1",
"reference_text": "I drink water every day.",
"display_prompt": "Sprich den Satz nach. Achte besonders auf water.",
"tts_text": "I drink water every day.",
"focus_points": ["water"],
"success_criteria": ["Sprich den vollständigen Satz gut verständlich nach."],
"reason_for_choice": "Water wurde in den übergebenen Daten als schwierig bewertet."
}
```
Die Go-API validiert die Antwort und vergibt selbst die Übungs-ID. Die Flowise-Prompts werden in der Flowise-Oberfläche verwaltet; eine Änderung am Go-Code aktualisiert die dort gespeicherten Prompts nicht automatisch. Weitere Hinweise stehen in [flowise/README.md](flowise/README.md) und [flowise/agentflow-v2-setup.md](flowise/agentflow-v2-setup.md).
Siehe [Betriebsanleitung](docs/AI_OPERATIONS.md). Prompts und Schemas werden in das Go-Binary eingebettet und im Adminbereich angezeigt. Kein Kopieren von Schemas in Flowise erforderlich. Modelllisten und Verbindungstests werden ausdrücklich ausgelöst. Testgenerierungen und Qualitätsprüfungen sind kostenpflichtige, protokollierte Modellaufrufe und verändern keine Kursfortschritte.
## Start auf dem VPS
@@ -155,7 +146,7 @@ docker compose up -d --build
- Web-App: https://speech.v2202510301049387828.goodsrv.de
- API-Healthcheck: https://speech.v2202510301049387828.goodsrv.de/api/health
- Flowise: vorhandene Instanz über `FLOWISE_BASE_URL`
- KI-Modelle: direkte DeepSeek-/Mistral-API, im Adminbereich eingerichtet
Nach einem Git-Update, das API und Web-App ändert, die beiden Dienste neu bauen:
@@ -164,7 +155,7 @@ git pull
docker compose up -d --build speech-api speech-web
```
Für echte Phonemwerte müssen in `.env` `AZURE_SPEECH_KEY` und `AZURE_SPEECH_REGION` gesetzt sein sowie `AZURE_ENABLE_MOCK=false`. Fehlt ein Azure-Schlüssel oder die Region, schaltet die API auch bei deaktiviertem Mock-Schalter auf Mock-Bewertung um. Für Flowise müssen `FLOWISE_BASE_URL` und `FLOWISE_CHATFLOW_ID` auf den verwendeten Flow zeigen.
Für echte Phonemwerte müssen in `.env` `AZURE_SPEECH_KEY` und `AZURE_SPEECH_REGION` gesetzt sein sowie `AZURE_ENABLE_MOCK=false`. Fehlt ein Azure-Schlüssel oder die Region, schaltet die API auch bei deaktiviertem Mock-Schalter auf Mock-Bewertung um. Für KI-Aufrufe zusätzlich DeepSeek-/Mistral-Schlüssel setzen und im Adminbereich Profile, Preise und Budget konfigurieren.
## Lokale Entwicklung
@@ -175,13 +166,12 @@ docker compose -f docker-compose.dev.yml up --build
- Web-App: http://localhost:5173
- API-Healthcheck: http://localhost:8080/health
- Flowise: http://localhost:3000
Mit `AZURE_ENABLE_MOCK=true` funktioniert die Wortbewertung ohne Azure-Zugang; Lautwerte gibt es dann nicht. Für echte Bewertungen Azure-Zugangsdaten setzen und `AZURE_ENABLE_MOCK=false` verwenden.
## Prüfung nach dem Deployment
1. Einloggen und eine neue Übung öffnen. In den API-Logs sollte für eine von Flowise angenommene Übung `source: "flowise"` erscheinen; bei einem Fehler wird eine Seed-Übung verwendet.
1. Einloggen und eine neue Übung öffnen. In den API-Logs sollte für eine direkt erzeugte Übung `source: "ai"` erscheinen; bei einem Fehler wird eine Seed-Übung verwendet.
2. Den Satz aufnehmen. Nach dem Absenden sollten Gesamt- und Wortwerte sowie unter **Lautanalyse** bewertete IPA-Laute erscheinen.
3. **Fortschritt** öffnen. Ein Laut unter `75` sollte unter **Schwierige Laute** auftauchen. Nach einer neueren guten Bewertung desselben Lauts im selben Wort sollte er dort verschwinden, sofern er noch im betrachteten Versuchsfenster liegt.
4. Wenn **Lautanalyse** „keine Lautwerte verfügbar“ zeigt, zunächst Azure-Konfiguration und `provider` in der Antwort von `POST /practice/attempts` prüfen. `provider: "mock"` hat keine Phonemwerte. Auch echte Azure-Antworten können für einzelne Laute keinen Wert liefern.