Hält positive Nutzererfahrungen der Konkurrenz mit Quellen fest und ordnet sie in priorisierte Arbeitspakete mit Abnahmekriterien und Fortschrittsprotokoll. Verweist aus README und AGENTS auf die Roadmap; verändert keine Produktfunktion.
Speech Learning App
Hinweise für Coding-Agenten und Beitragsarbeit: AGENTS.md.
Geplante Verbesserungen mit Prioritäten und Abnahmekriterien: Roadmap für das Lernerlebnis.
Mehrsprachigkeit
Es gibt genau zwei Sprachrollen: Muttersprache und Lernsprache.
Die Muttersprache steuert gemeinsam Oberfläche, neue Aufgabenanweisungen,
Erklärungen und Rückmeldungen. Zur Auswahl stehen Deutsch (de-DE) und Russisch
(ru-RU). Die Lernsprache des vorhandenen A1-Kurses bleibt Englisch (en-US).
Eine separate Einstellung für GUI- oder Erklärungssprache gibt es nicht.
Vor dem Login wird die Muttersprache im Browser gespeichert; nach dem Login gilt die Kontoeinstellung. Ein Wechsel erhält Lernsprache, Niveau, Tagesziel, Lernfortschritt, eingegebene Antworten und laufende Aufnahmen. Historische Aufgaben, Bewertungen und Rückmeldungen behalten ihren eingefrorenen Inhalt und ihre Sprache. Technische Rohdaten, Prompts, Schemas und Anbieterdiagnosen werden nicht automatisch übersetzt. Die normale Fehleranzeige verwendet übersetzte stabile API-Fehlercodes.
Navigation, Anmeldung, Dashboard, Fortschritt und Ausspracheprofil, Kursbedienung, Aufnahme, Dialog, Administration und Debug verwenden deutsche und russische Textkataloge. Datums-, Zahlen-, Kosten- und Pluralanzeigen folgen der Muttersprache. Neue deterministische Aussprache- und Dialoghilfen berücksichtigen diese ebenfalls.
Aufgabenvarianten
Die 840 deutschen Basisaufgaben bleiben unverändert. Zusätzlich gibt es 840 russische Aufgabenansichten, verteilt auf sieben Module und sechs Lernbereiche mit jeweils 20 Aufgaben. Auch der interne A1-Test mit zwölf Aufgaben steht mit russischen Anweisungen zur Verfügung. Russischsprachige Bedeutungsoptionen und Ausgangssätze sind redaktionelle Quelldaten; englische Lücken, Lesetexte, Hörtexte und Nachsprechsätze bleiben Lernmaterial auf Englisch. Räumliche und zeitliche Bedeutungen werden kontextabhängig übersetzt.
Alle russischen Ansichten sind äquivalente Übersetzungen und teilen die fachliche Kennung ihrer Basisaufgabe. Sprachansichten werden getrennt eingefroren, erhöhen aber nicht die Zahl unterschiedlicher Aufgaben oder die Aussprache-Nachweisdichte. Versuche bleiben einzeln erhalten. Lösungen und Hörtranskripte bleiben bis zur vorgesehenen Freigabe geschützt; offene Antworten ohne Bewertungsprofil bleiben unbenotet. Der interne Test ist kein Zertifikat.
instruction, stimulus mit Sprachrolle, Optionssprache, Variantenkennung und
Revision trennen Anweisung, Ausgangsmaterial und Lerninhalt. Das kombinierte
prompt bleibt für kompatible Clients erhalten. Hintergrundaufträge frieren die
Muttersprache beim Einreihen ein; wiederholte Anfragen behalten den ursprünglichen
Auftrag. Alte englische Pilotansichten in vorhandenen Datenbanken werden deaktiviert,
aber weder gelöscht noch an bereits zugewiesenen Aufgaben verändert.
Redaktionelle Quellen liegen in tools/course_bank/russian/*.tsv und
variant_sources.json; variant_review.json bindet die Durchsicht an Prüfsummen.
Generierte Ansichten liegen unter apps/api/internal/store/coursebank/variants/.
Die dokumentierte Codex-Durchsicht ist keine unabhängige Lehrkräfte-Zertifizierung.
python tools/course_bank/build.py
python tools/course_bank/audit.py
Beide Befehle prüfen Basisbank und Varianten offline. Geänderte fachliche Inhalte benötigen neue IDs beziehungsweise Revisionen; historische Daten werden nicht umgeschrieben oder neu bewertet.
Kontoeinstellung und Kompatibilität
users.native_language ist die maßgebliche Einstellung. PATCH /me/preferences
akzeptiert {"native_language":"ru-RU"}. Die bisherigen Felder ui_language und
instruction_language bleiben als gekoppelte Kompatibilitätsfelder erhalten.
Alle drei Werte müssen gleich sein; widersprüchliche Angaben liefern HTTP 400
mit native_language_conflict, nicht unterstützte Werte native_language_unsupported.
Eine Datenbankbedingung schützt die Kopplung auch bei direkten Schreibzugriffen.
PUT /course/instruction-language bleibt ein veralteter Kompatibilitätsendpunkt
und ändert ebenfalls die gesamte Muttersprache.
Die additive Migration übernimmt eine vorhandene deutsche/russische GUI-Einstellung;
andere alte GUI-Werte werden auf Deutsch gesetzt. Vorhandene Aufgaben, Aufträge,
Bewertungen und Messungen werden dabei nicht übersetzt. Wiederholte Starts erhalten
die bereits gesetzte Muttersprache. Profil und Sprache werden atomar aktualisiert.
KI-Verträge behalten vorerst den Wire-Namen ui_language; dessen Wert stammt aus
der eingefrorenen Muttersprache. GET /course/catalog liefert Muttersprache,
verfügbare Muttersprachen, Bestand und Testverfügbarkeit. Fehlende Sprachpakete
führen zu course_variant_unavailable, ohne stillen Rückfall auf Deutsch.
Die historische feste Kursansicht und gespeicherte Rückmeldungen bleiben historische Inhalte. Die festen Recorder-Anweisungen sind übersetzte Oberflächenvorlagen; neue statistische Trainingsbegründungen werden mit der Muttersprache gespeichert. Neue Lernsprachen benötigen eigene Kursinhalte und geprüfte Speech-Unterstützung. Lokale Fixturetests bestätigen keine Live-Modellqualität oder echte Audioqualität. Preise, Produktionsprofile und Budgets werden durch die Spracherweiterung nicht geändert.
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 Lernsprache, Muttersprache 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. Im Bankbetrieb ist der Empfohlene Lernweg der Standard: 60 redaktionell verknüpfte Themen, zehn in jedem der sechs Lernmodule. Jede Folge beginnt mit Hören und führt über Wortschatz, Lesen, Nachsprechen, passende Grammatik und kurze Schreibaufgaben zum freien Schreiben und erst danach zum freien Sprechen über dasselbe Thema. Vorlagen und eigene Angaben dürfen unterschiedlich sein; es geht um übertragbare Wörter und Satzmuster, nicht um das Auswendiglernen eines Lösungssatzes.
Nächste Aufgabe setzt den gespeicherten Lernweg fort. Eine unbeantwortete Aufgabe bleibt der aktuelle Schritt; Diesen Schritt überspringen geht bewusst weiter. Nach einem bereits bewerteten Fehler unter 80 Punkten wird pro Schritt höchstens eine Wiederholung empfohlen. Eine weitere Antwort oder explizites Überspringen setzt den Weg ohne Mindestnote fort. Gespeicherte unbenotete Antworten zählen als Bearbeitung, niemals als Beherrschung. Demoantworten und bloßes Klicken auf „Nächste Aufgabe“ zählen nicht als Bearbeitung.
Bereits gut bearbeitete Grundlagen werden seltener erneut angeboten. Nur für Grammatik gibt es ausdrücklich redaktionell freigegebene neue Beispiele zum selben Satzmuster; ein grob gemeinsames Lernziel allein reicht nicht aus. Wortschatzaufgaben behalten ihre konkrete Wortbedeutung. Hören, Lesen, Nachsprechen und die Schreib-/Sprechaufgaben zum Thema bleiben erhalten.
Für diese Auswahl zählen nur eigene, echte Bewertungen derselben Lernsprache und Kursversion. Demoantworten, unbenotete Antworten und noch nicht abgeschlossene Tests liefern keine positiven Nachweise. Eine neuere unbenotete Antwort oder ein neuerer Fehler verdrängt die bisherige positive Auswahlannahme. Bereits zugewiesene Aufgaben bleiben während eines Schritts stabil, auch bei Neuladen oder Sprachwechsel.
Eine gerade gut gelöste identische Grundlage wird innerhalb von 30 Minuten nicht unnötig wiederholt, sofern kein unbekanntes freigegebenes Grammatikbeispiel angeboten werden kann. Danach begründen zwei gute Antworten mit mindestens 24 Stunden Abstand oder bei Grammatik gute Ergebnisse in drei verschiedenen freigegebenen Beispielen weniger Wiederholungen. Die jüngste passende Bewertung muss mindestens 85 Punkte haben und höchstens sieben Tage alt sein; betrachtet werden bis zu 2.000 jüngste Antworten der letzten 30 Tage pro Modul. Ältere oder unzureichende Nachweise führen zum Auffrischen. Das sind Auswahlheuristiken, keine Beherrschungsdiagnose. Berücksichtigte frühere Übungsschritte werden getrennt vom manuellen Überspringen gezählt; es entstehen keine neuen Antworten oder Noten.
Frühere Bewertungen einer erneut empfohlenen Aufgabe erscheinen eingeklappt als Bewertung deines vorherigen Versuchs. Eine neue Antwort erhält weiterhin ihren eigenen Versuch und gegebenenfalls eine eigene Bewertung.
Die Oberfläche zeigt Thema und Schritt auf Deutsch beziehungsweise Russisch. Neuladen, ein Modulwechsel und der Wechsel der Muttersprache erhalten den Lernweg. Die sechs Lernbereiche bleiben direkt auswählbar und verändern den Lernweg nicht. Dabei, nach Abschluss des Lernwegs und bei der Wiederholung im siebten Modul bleibt die bisherige Auswahl nach ungesehenen Aufgaben, tatsächlichen Bewertungen und Wiederholungen verfügbar. Der A1-Test verwendet seine eigene eingefrorene Auswahl; weder Lernwege noch Überspringen verändern Testnoten oder Lösungen.
Die Verknüpfungen liegen separat in tools/course_bank/sequence_sources.json,
mit eigenem Prüfvermerk in sequence_review.json. Build und Audit berücksichtigen
sie automatisch. Bestehende Aufgaben-IDs, Aufgabeninhalte, Messungen und Bewertungen
bleiben unverändert. Es gibt keinen zusätzlichen Modellaufruf und noch keinen
Button „Grammatik erklären“. Der alternative KI-Kursmodus behält seine eigene
Planung. Die redaktionelle Codex-Durchsicht ist keine unabhängige Lehrkräfteprüfung.
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 für den deutschen Bestand und den alternativen KI-Modus erhalten; fehlende muttersprachliche Bankvarianten werden nicht dadurch ersetzt.
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.