# Speech Learning App Hinweise für Coding-Agenten und Beitragsarbeit: [AGENTS.md](AGENTS.md). Geplante Verbesserungen mit Prioritäten und Abnahmekriterien: [Roadmap für das Lernerlebnis](docs/LEARNING_EXPERIENCE_ROADMAP.md). ## 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. ```bash 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](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 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](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.