# Speech Learning App 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 direkten Modellaufrufen; Seed-Übungen als Fallback - Audioaufnahme im Browser und Aussprachebewertung über Azure Speech - Audio-Monitoring ist für eine spätere Erprobung im Code erhalten, derzeit aber in allen Aufnahmebereichen ausgeblendet und deaktiviert. Bei einem manuellen Test mit USB-Headset unter Debian/Firefox wurden etwa 900 ms Verzögerung berichtet; die Ursache ist nicht geklärt. Eine spätere Freigabe erfolgt ausdrücklich über die Komponenten-Option `enableMonitoring`; Schalter und Mithörlautstärke (0–100 %) bleiben vorbereitet. - 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 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 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. ### Erstes Admin-Konto einrichten 1. Ein eigenes Konto über die normale Registrierung erstellen. Ein bereits vorhandenes eigenes Konto kann ebenfalls verwendet werden. 2. Auf dem VPS mit PostgreSQL verbinden (Datenbankname und Nutzer aus der `.env` verwenden): ```bash docker compose exec speech-postgres psql -U speech -d speech ``` 3. **Nur das eigene Konto** anhand der E-Mail-Adresse zum Admin machen: ```sql UPDATE users SET role = 'admin' WHERE email = 'eigene-adresse@beispiel.de'; ``` 4. Die Web-App neu laden. Die API liefert die aktuelle Rolle über `GET /me`; danach erscheint der Adminbereich in der Navigation. Es gibt bewusst keinen öffentlichen Endpunkt, über den Nutzer sich selbst Adminrechte geben können. Für spätere Teamverwaltung braucht es einen gesonderten Ablauf mit Änderungsprotokoll und stärkeren Anmeldeschutzmaßnahmen. ### Vorbereitung für ein Kaufprodukt 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. 3. Den Zugang zu bezahlten Funktionen über serverseitig geprüfte Berechtigungen steuern. 4. Im Adminbereich Bestellungen, Zahlungsstatus, Supportfälle und einen Änderungsverlauf für Adminaktionen anzeigen. Solange diese Teile fehlen, bleibt die Lern-App für registrierte Nutzer unabhängig von einem Kauf zugänglich. ## Architektur und Datenfluss ```text 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 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 Die Go-API fordert Azure Pronunciation Assessment mit `Granularity: "Phoneme"`, `GradingSystem: "HundredMark"` und `PhonemeAlphabet: "IPA"` an. Azure kann dabei neben Satz- und Wortwerten auch Genauigkeitswerte für einzelne Laute liefern. Die API übernimmt nur tatsächlich vorhandene Phonemwerte; ein fehlender Wert wird nicht als `0` interpretiert. Ein echter Wert `0` bleibt dagegen erhalten. Ein vereinfachter Ausschnitt aus einem gespeicherten Versuch und der Antwort von `POST /practice/attempts`: ```json { "word_scores": [ { "word": "water", "accuracy": 72, "phonemes": ["w", "ɔ", "t", "ə"], "phoneme_scores": [ { "phoneme": "w", "accuracy": 91, "highlight": "good" }, { "phoneme": "t", "accuracy": 58, "highlight": "weak" } ], "highlight": "weak" } ] } ``` `phonemes` enthält die von Azure gelieferten Lautbezeichnungen. `phoneme_scores` enthält nur Laute, für die Azure auch einen Genauigkeitswert geliefert hat. Die Beispielzahlen oben sind illustrativ und keine erwarteten Werte für „water“. Die Einstufung in der aktuellen App ist eine einfache Anzeigeregel: unter `75` = `weak`, `75` bis unter `85` = `ok`, ab `85` = `good`. Das ist keine Aussage darüber, welcher konkrete Artikulationsfehler vorlag. Die Lautanalyse nach einem Versuch zeigt die bewerteten Laute pro Wort. Bei einem gemessenen schwachen Laut kann das Lehrerfeedback das Wort, das Phonem und dessen Punktzahl nennen; bei sehr hohen Satzwerten empfiehlt es eine neue Übung. PostgreSQL speichert `phoneme_scores` als Teil des bestehenden `attempts.word_scores_json`-Felds. Dafür ist keine neue Tabelle und keine Migration nötig. Alte Versuche enthalten diese Werte nicht rückwirkend. Der Mock-Modus liefert derzeit nur Wortwerte; dort zeigt die Web-App entsprechend an, dass keine Lautwerte verfügbar sind. ### Schwache Laute im Fortschritt `GET /progress` enthält zusätzlich `weak_phonemes`. Die Go-API berechnet diese Liste aus den letzten **20** Versuchen; bei der nächsten Übung betrachtet sie die letzten **10**. Pro Kombination aus Wort und Laut zählt der neueste bewertete Versuch. Wird derselbe Laut in diesem Versuch mehrfach bewertet, zählt der niedrigste Wert. Ein neuerer guter Wert entfernt damit eine ältere Schwäche aus dem betrachteten Fenster. Ausgelassene Wörter (`Omission`) werden für die Lautliste übersprungen. Die Liste ist nach niedrigstem Wert sortiert und auf 12 Einträge begrenzt. ```json { "weak_phonemes": [ { "word": "water", "phoneme": "t", "accuracy": 58 } ] } ``` 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. ## KI-Einrichtung und Verbrauch 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 Die Standard-Compose-Datei ist für den VPS vorgesehen. `speech-web` und `speech-api` hängen am vorhandenen Docker-Netzwerk `web`; die Datenbank liegt auf einem persistenten Docker-Volume. ```bash docker compose up -d --build ``` - Web-App: https://speech.v2202510301049387828.goodsrv.de - API-Healthcheck: https://speech.v2202510301049387828.goodsrv.de/api/health - KI-Modelle: direkte DeepSeek-/Mistral-API, im Adminbereich eingerichtet Nach einem Git-Update, das API und Web-App ändert, die beiden Dienste neu bauen: ```bash 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 KI-Aufrufe zusätzlich DeepSeek-/Mistral-Schlüssel setzen und im Adminbereich Profile, Preise und Budget konfigurieren. ## Lokale Entwicklung ```bash cp .env.example .env docker compose -f docker-compose.dev.yml up --build ``` - Web-App: http://localhost:5173 - API-Healthcheck: http://localhost:8080/health 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 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. API-Logs auf dem VPS: ```bash docker compose logs --since=10m speech-api ``` Tests und Web-Build im Quellverzeichnis: ```bash cd apps/api && go test ./... cd ../web && npm run build ``` ## Debug Debug-Endpunkte und der Navigationspunkt **Debug** lassen sich über `.env` aktivieren. Sie sind nur für Admins zugänglich: ```env DEBUG_ENABLED=true LOG_LEVEL=debug ``` Danach die API neu erstellen: ```bash docker compose up -d --force-recreate speech-api ``` Die Debug-Ausgaben sind maskiert und geben keine Zugangsschlüssel aus.