Mithörpfad mit separater Lautstärke und Schalter in der gemeinsamen Aufnahme-Komponente vorbereiten. In allen bestehenden Aufnahmebereichen bleiben Bedienung und Mithörpfad standardmäßig deaktiviert; eine spätere Erprobung erfordert enableMonitoring. Validiert: Web-Build, synthetischer Audio-Monitoring-Browsertest inklusive ausgeblendetem Standard, Bank- und Aussprache-Browser-Smokes gegen lokale PostgreSQL-Fixtures, Bank-Audit und git diff --check. Keine Live-Audioqualität oder VPS-Bereitstellung geprüft.
16 KiB
Speech Learning App
Hinweise für Coding-Agenten und Beitragsarbeit: 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.
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. 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. 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
-
Ein eigenes Konto über die normale Registrierung erstellen. Ein bereits vorhandenes eigenes Konto kann ebenfalls verwendet werden.
-
Auf dem VPS mit PostgreSQL verbinden (Datenbankname und Nutzer aus der
.envverwenden):docker compose exec speech-postgres psql -U speech -d speech -
Nur das eigene Konto anhand der E-Mail-Adresse zum Admin machen:
UPDATE users SET role = 'admin' WHERE email = 'eigene-adresse@beispiel.de'; -
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:
- Produkte und Tarife mit Preis, Laufzeit und enthaltenen Lernfunktionen definieren.
- Einen Zahlungsanbieter anbinden und signierte Webhooks verarbeiten. Zahlungen und Rückerstattungen müssen nachvollziehbar gespeichert werden.
- Den Zugang zu bezahlten Funktionen über serverseitig geprüfte Berechtigungen steuern.
- 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
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:
{
"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.
{
"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. 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.
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:
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
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
- 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. - Den Satz aufnehmen. Nach dem Absenden sollten Gesamt- und Wortwerte sowie unter Lautanalyse bewertete IPA-Laute erscheinen.
- Fortschritt öffnen. Ein Laut unter
75sollte 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. - Wenn Lautanalyse „keine Lautwerte verfügbar“ zeigt, zunächst Azure-Konfiguration und
providerin der Antwort vonPOST /practice/attemptsprüfen.provider: "mock"hat keine Phonemwerte. Auch echte Azure-Antworten können für einzelne Laute keinen Wert liefern.
API-Logs auf dem VPS:
docker compose logs --since=10m speech-api
Tests und Web-Build im Quellverzeichnis:
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:
DEBUG_ENABLED=true
LOG_LEVEL=debug
Danach die API neu erstellen:
docker compose up -d --force-recreate speech-api
Die Debug-Ausgaben sind maskiert und geben keine Zugangsschlüssel aus.