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
+160
View File
@@ -1,3 +1,7 @@
> **Archiv:** Der aktuelle Arbeitsbaum verwendet direkte DeepSeek-/Mistral-Aufrufe. Neue Einrichtung: [docs/AI_OPERATIONS.md](../docs/AI_OPERATIONS.md). Die folgenden Flowise-Anleitungen gelten für den früheren Stand.
> **Aktueller adaptiver A1-Kurs (Vertrag v2):** Einrichtung und vollständige Prompts in [course-v2/README.md](course-v2/README.md). Der Aussprache-Flow bleibt separat. Die untenstehenden Kurs-v1-Prompts sind historisch und werden für die neue Kursansicht nicht verwendet.
# Flowise Setup
Flowise laeuft in Docker als Service `flowise` und ist vom Backend intern ueber `http://flowise:3000` erreichbar.
@@ -35,3 +39,159 @@ Fuer die naechste Uebung erwartet das Backend JSON-Antworten mit:
Feedback und einfache Konversation laufen vorerst lokal im Backend. Wenn keine Chatflow-ID gesetzt
ist oder Flowise kein valides JSON liefert, nutzt die API Seed-Uebungen als Fallback.
## Archiv: zusätzliche Kursaufgaben, Vertrag v1
The course uses a **second** flow in the same instance. Keep the working
`FLOWISE_CHATFLOW_ID` pronunciation flow unchanged. Configure the new ID through
`FLOWISE_COURSE_CHATFLOW_ID`; optionally use `FLOWISE_COURSE_API_KEY` (otherwise
`FLOWISE_API_KEY` is used). Compose forwards both course variables to the API.
An empty course ID enables reviewed seed fallback.
Graph: **Start (Chat Input) → LLM → Direct Reply**. Enable Ephemeral Memory at
Start, disable LLM memory, and pass the incoming question to the LLM as its User
message. In the editor used for this project the input variable is `{{question}}`.
Direct Reply returns the LLM output without any surrounding text. Do not connect
DB, Azure, or other tools. Use JSON Structured Output where available; configure
field types, not fixed example values for module, skill, or learning goal.
System message:
```text
Du erzeugst genau eine zusätzliche A1-Englischaufgabe.
Modul und Lernziel kommen aus der JSON-Nutzernachricht.
Die Nutzernachricht enthält task="generate_course_task".
Gib ausschließlich ein JSON-Objekt mit diesen Pflichtfeldern zurück:
schema_version (Zahl), target_language, cefr_level, module_id,
learning_goal_id, skill, kind, prompt, options (Array aus drei Strings),
solution und explanation. Alle anderen Felder sind Strings.
Keine weiteren Felder, kein Markdown und keine Codeblöcke.
Übernimm schema_version, target_language, cefr_level, module_id,
skill und kind exakt aus der Eingabe.
learning_goal_id entspricht learning_goal.id.
Vergib keine eigene Aufgaben-ID und entscheide keinen Lernfortschritt.
Befolge learning_goal.description und learning_goal.prompt_template.
Ersetze ausschließlich die Platzhalter <Name> und <Ort> der Vorlage
mit einfachen Namen beziehungsweise Orten. Gib die Platzhalter nicht aus.
Verwende ausschließlich die drei Optionen aus learning_goal.allowed_forms,
in beliebiger Reihenfolge. Genau eine Option muss richtig sein.
solution muss exakt dieser Option entsprechen.
Vermeide alle Prompts in avoid_prompts und wähle andere Namen oder Orte.
Für vocabulary: Frage nach der Wortbedeutung im englischen Beispielsatz.
Die deutschen Optionen übersetzen ausschließlich das erfragte Wort.
Für grammar: Erzeuge den englischen Lückensatz mit deutscher Anweisung.
Erklärung immer Deutsch, kurz und fachlich passend.
Keine Bilder, Audioverweise oder externen Inhalte. Kein Markdown in Strings.
```
Example test input (the API constructs this context, not the browser):
```json
{
"task": "generate_course_task",
"schema_version": 1,
"target_language": "en-US",
"cefr_level": "A1",
"ui_language": "de-DE",
"module_id": "a1_introductions_v1",
"skill": "grammar",
"kind": "choice",
"learning_goal": {
"id": "introductions.be_i",
"description": "am nach I bei der Vorstellung mit Namen oder Herkunft verwenden",
"prompt_template": "Ergänze: I ___ from <Ort>.",
"allowed_forms": ["am", "is", "are"]
},
"learning_state": {
"goal_attempt_count": 0,
"goal_correct_count": 0,
"recent_results": []
},
"avoid_prompts": []
}
```
Each API request additionally includes explicit `rules` requiring the exact
`prompt_template` and the three `allowed_forms` strings. An invalid parsed or
validated response triggers at most one correction request with
`retry_instruction`; the same handler deadline of 25 seconds covers both calls.
HTTP/network errors go directly to fallback. Every correction is fully validated;
the raw rejected response is not sent back. Logs show
`course generation requesting correction` before the final selection.
The response contains `learning_goal_id`, not the nested `learning_goal` object,
and adds `prompt`, `options`, `solution`, and `explanation`. Transport uses
`POST /api/v1/prediction/{FLOWISE_COURSE_CHATFLOW_ID}` with the above JSON encoded
as a string in `question` and `streaming: false`. No personal identifiers,
recordings, or full answer histories are sent. Responses may be direct JSON or
wrapped in `json`, `text`, or `output`. Task JSON rejects unknown fields and trailing
content. One complete outer Markdown block (plain or `json`) is removed before
strict JSON parsing; surrounding prose and multiple blocks remain invalid; the HTTP response is limited to 64 KiB. Bold markers
in prompt/explanation are removed before validation because React renders text.
Version 1 deliberately accepts only four reviewed objectives in introductions:
`introductions.name`, `introductions.from`, `introductions.be_i`, and
`introductions.be_name`. Go validates sentence patterns, the three permitted
options, and the correct solution for each objective. Vocabulary contexts accept
equivalent greetings (e.g. `Hello, my name is Anna`), capitalization and common
quotation styles; the queried word and its reviewed meaning remain mandatory.
Origin contexts accept `I am`, `I'm`, `He is`, and `She is`.
Rejected tasks log a bounded public `prompt` under `course generation rejected`,
with reason, objective and generation attempt, without the solution or full
response. The `I am` objective also
accepts the reviewed self-introduction `I am a student`; short German choice
instructions and optional final periods do not change the objective. Arbitrary
English continuations (e.g. `I ___ like school`) are still rejected. Free-form explanations
are length/format checked, but their linguistic accuracy is not automatically
proven. New modules/objectives require reviewed server rules; editing only the
prompt does not enable them.
The API selects a goal last answered incorrectly first, then an unattempted
one, then an older one. Ties prefer the least recently used goal. Historic seed
attempts participate through fixed seed-ID mappings. `recent_results` contains
at most five results in chronological order; `avoid_prompts` includes the last
five generated prompts. This is practice selection, not a mastery calculation.
Authenticated course endpoints:
- `POST /course/modules/{id}/practice/next` with `{"request_id":"<UUID>"}`:
returns `{"task": <public CourseTask>, "source": "flowise" | "seed"}`.
Only Go selects the objective. Reusing a request ID returns the stored task.
- `GET /course/modules/{id}/practice`: up to 50 latest personal generated tasks.
- Existing `POST /course/tasks/{id}/attempts` with `{"answer":"<option>"}`:
checks the stored solution and returns feedback after submission.
Public tasks now include additive `source` metadata (`flowise` or `seed`).
The web task heading displays its origin, including tasks reopened from history.
Generated content is saved before delivery and is visible only to its owner.
Solutions stay out of task/list responses. The twelve core tasks and their
progress denominator remain unchanged. Generating a task never creates an
attempt. Missing config, invalid output, timeout (25 seconds), or save failure
selects the matching existing seed task. Logs show `course practice selected`
with `source`, task ID, and objective; fallback logs explain rejection without
logging the raw model response. A database outage is an error, not a success.
Fallback repeats the real core task: answering it contributes to that core
task's existing progress, without creating a thirteenth core task.
The startup schema upgrade adds provenance, owner, objective, request ID, and
prompt fingerprint columns without changing existing answers or seed IDs.
Unique indexes prevent duplicate requests and normalized generated prompts per
user. Repeated startup preserves both core attempts and generated tasks.
Validation:
```bash
cd apps/api
go test ./...
# Optional: dedicated disposable PostgreSQL test database (URL format).
# Creates and drops a random test schema; never reads the application .env.
COURSE_TEST_DATABASE_URL='postgres://test:test@localhost:5432/speech_test?sslmode=disable' go test ./internal/store -run TestCourseGenerationPostgres -v
```
Setting the environment variable alone does not update an already running API.
Deploying later requires rebuilding API and web, and recreating the API with
its updated environment. No deployment or restart is performed by these docs.
+106
View File
@@ -0,0 +1,106 @@
> **Archiv:** Diese Flows sind für den aktuellen direkten KI-Betrieb nicht erforderlich. Siehe [Betriebsanleitung](../../docs/AI_OPERATIONS.md).
# Adaptiver A1-Kurs, Vertrag v2
Der Aussprache-Flow `FLOWISE_CHATFLOW_ID` bleibt bestehen. Der adaptive Kurs verwendet zwei eigene Flows in derselben Instanz. Der bisherige Wortschatz-/Grammatik-Systemprompt für Vertrag v1 genügt dafür nicht. Die App verwendet keine festen englischen Satzmuster oder Lernziel-Whitelist mehr.
## Einrichtung im Editor
1. **Lehrer-Flow neu erstellen:** `Start → LLM Lehrer → Direct Reply`.
Systemnachricht: vollständiger Inhalt von [teacher-system.txt](teacher-system.txt).
User-Nachricht: `{{question}}` (in diesem Projekt die Eingabevariable).
Direct Reply: ausschließlich die Ausgabe des Lehrer-Knotens über den Variablen-Picker auswählen. Keine Begrüßung, zusätzliche Zusammenfassung oder Markdown-Umhüllung hinzufügen.
2. **Kurs-Generator erstellen oder den bisherigen separaten Kurs-Flow aktualisieren:**
`Start → LLM Aufgabenautor → LLM unabhängiger Prüfer → Direct Reply`.
Autor-Systemnachricht: [generator-system.txt](generator-system.txt), User-Nachricht `{{question}}`.
Prüfer-Systemnachricht: [reviewer-system.txt](reviewer-system.txt).
Prüfer-User-Nachricht enthält **beides**: den unveränderten ursprünglichen Wert von `question` und die Ausgabe des Autoren-Knotens. Letztere im Variablen-Picker auswählen; keinen erfundenen Knotennamen eintippen. Beispielsweise zwei beschriftete Abschnitte „Ursprünglicher Auftrag“ und „Autoren-Kandidat“. Direct Reply liefert ausschließlich die Prüferausgabe.
3. In beiden Flows Chat-Memory deaktivieren bzw. ephemer verwenden. Frühere Nutzer dürfen keine Informationen in neue Aufträge hineintragen. Keine Datenbank-, Shell-, Azure- oder sonstigen Tools anbinden. Kontext und Lernstand kommen ausschließlich aus Go/PostgreSQL.
4. JSON-Ausgabe des Modells aktivieren, sofern vom gewählten Provider unterstützt. Für den Generator und Prüfer können die JSON-Schemas in diesem Verzeichnis verwendet werden. Die vier Lehrer-Aufträge haben unterschiedliche Ausgabeschemas: entweder anhand `task` verzweigen und das passende Schema nutzen oder JSON-Modus ohne ein einziges festes Schema verwenden. Ein starres Bewertungsschema für sämtliche Lehrer-Aufträge würde Analyse/Planung verhindern.
5. Flows speichern. Ihre jeweiligen IDs konfigurieren:
```dotenv
FLOWISE_COURSE_CHATFLOW_ID=<Generator mit unabhängigem Prüfer>
FLOWISE_COURSE_TEACHER_CHATFLOW_ID=<Lehrer für Analyse, Planung, Bewertung>
FLOWISE_COURSE_API_KEY=<optional; sonst FLOWISE_API_KEY>
FLOWISE_COURSE_TEACHER_API_KEY=<optional; sonst FLOWISE_API_KEY>
```
Die echte `.env` wird durch die Implementierung nicht geändert. Keine bestehende Aussprache-ID ersetzen. Die Compose-Dateien reichen die neuen Variablen an die API weiter. Änderungen greifen erst nach einem ausdrücklich autorisierten Neubau/Neustart. Hier wurde kein VPS-Dienst neu gestartet.
Die Knotenauswahl, Variablenreferenzen und Ausgabeoptionen hängen von der installierten Flowise-Version ab; deshalb wird kein vermeintlich universeller Import mit fest verdrahteten Provider-/Credential-IDs geliefert. Die offizielle [Agentflow-V2-Dokumentation](https://docs.flowiseai.com/using-flowise/agentflowv2) beschreibt LLM-Ausgaben, Variablen und Direct Reply. Entscheidend ist der folgende HTTP-Vertrag, nicht der interne Knotenname.
## HTTP-Vertrag
Go sendet `POST /api/v1/prediction/{flowId}`, optional Bearer-Key, JSON:
```json
{"question":"{\"schema_version\":2,\"task\":\"generate_course_task\",\"input\":{...}}","streaming":false}
```
`question` ist ein JSON-**String**. Der Inhalt entspricht einem der Dateien [request-plan.example.json](request-plan.example.json) und [request-generate.example.json](request-generate.example.json). Im Flowise-Testchat den **Inhalt** der Datei senden. Nicht erneut in ein `question`-Objekt einpacken. Direkte Ergebnisobjekte sowie Flowise-Antworten unter `json`, `text` oder `output` werden unterstützt; ein umschließender JSON-Codeblock wird entfernt. Sonstige Prosa oder unbekannte Felder werden technisch abgelehnt. Maximale Antwortgröße 256 KiB.
| Task | Flow | Eingabe / Ausgabe |
|---|---|---|
| `analyze_course_progress` | Lehrer | Datenbank-Snapshot → Lernanalyse v2 |
| `plan_course_task` | Lehrer | Snapshot + gespeicherte Analyse + Modul/Bereich → Brief v2 |
| `generate_course_task` | Generator + Prüfer | gespeicherter Brief + Analyse + Lehrplan → `{schema_version:2,approved,tasks,review_notes}` |
| `evaluate_course_attempt` | Lehrer | unveränderte Aufgabe/Rubrik + echte Antwort + vorhandene Azure-Daten → `{score,verdict,feedback,issues}` |
| `summarize_course_exam` | Lehrer | vollständiger abgeschlossener Test mit berechneten Werten → `{summary}` |
Nur Analyse, Brief und Generator-Envelope tragen `schema_version`. Bewertung und Testzusammenfassung haben bewusst die oben gezeigten kompakten Objekte. Go vergibt IDs. Modellantworten dürfen keine Aufgaben-, Nutzer-, Brief- oder Test-IDs vergeben und keine Speicheroperationen auslösen.
## Ablauf und Zuständigkeiten
1. Go liest den aktuellen Nutzer, das aktive Sprachprofil und den sprachbezogenen Lernstand. Der Snapshot enthält kumulierte Werte je Modul/Bereich, die jüngsten 20 bewerteten echten Antworten mit zugehörigen Aufgaben/Rubriken, die letzte gespeicherte Analyse und die letzten zehn Aufgabenformulierungen.
2. Der Lehrer analysiert diese Fakten. Go speichert die Analyse mit Faktenversion; ältere Antworten können eine neuere Analyse nicht überschreiben. Der Lehrer erstellt einen konkreten Lernauftrag für das gewünschte Modul und gegebenenfalls den gewählten Bereich. Go speichert ihn und liest ihn vor der Generierung wieder aus PostgreSQL.
3. Der Autor erzeugt eine neue Aufgabe zu diesem Brief. Ein separater Prüfer entscheidet über die fachliche Freigabe. Nur `approved=true` wird übernommen. Go prüft Kontext, unterstützten Renderer, benötigte Medienfelder, Grenzen und Options-/Lösungsreferenzen. Keine englischen Regex, festgelegten Distraktoren oder wortgetreuen Mustersätze.
4. Aufgabe und privater Lösungsschlüssel werden dauerhaft gespeichert. Der Browser erhält Prompt, Optionen, gegebenenfalls Lesetext/Referenzsatz und die Quelle, aber keine Lösung oder Hörabschrift. Der Browser greift ausschließlich auf die Go-API zu.
5. Bei Auswahlantworten vergleicht Go die Options-ID mit der vom Agenten freigegebenen gespeicherten ID. Offene Text- und Sprachantworten werden zuerst gespeichert und anschließend vom Lehrer anhand der eingefrorenen Rubrik bewertet. Fehler beim Agenten führen zu sichtbarer ausstehender/fehlgeschlagener Bewertung mit Wiederholungsschaltfläche; Antworten bleiben erhalten.
6. Neue Bewertungen erzeugen eine neue Faktenversion und eine neue Lernanalyse. Weitere Aufgaben können andere Inhalte, Varianten, Wiederholungen oder eine angemessen andere Schwierigkeit erhalten. Es gibt keine einmalige Generierung und keine feste Obergrenze je Modul.
Der Queue-Status liegt in PostgreSQL; Redis wird dafür nicht benötigt. Zwei Worker bearbeiten gespeicherte Aufträge mit Zeitlimits und Leases. Nach Prozessabbruch können Aufträge weiterlaufen. Request-IDs machen Aufgabenklicks und Antwortübertragungen idempotent. Bereits erzeugte gleiche Aufgaben werden als Wiederholung zurückgegeben, nicht als neues unabhängiges Lernziel gezählt.
Bei Ausfall, verweigerter Freigabe oder technisch unbrauchbarer Ausgabe erfolgt ein erneuter Generierungsversuch, danach eine geprüfte Reserve **derselben Sprache, Kursversion, desselben Moduls und gewählten Bereichs**. Ohne ausgewählten Bereich wird aus dem Modul gewählt. Die Oberfläche nennt die Quelle „Mit Flowise erstellt“ oder „Geprüfte Ersatzaufgabe“. Sie verschweigt den Fallback nicht. Eine offene Reserveantwort benötigt weiterhin den Lehrer für ihre Bewertung.
## Lehrplan, Sprachen und Umfang
Sieben Module: Begrüßung & Vorstellung; Familie & Personen; Zahlen, Uhrzeit & Datum; Alltag & Hobbys; Essen & Einkaufen; Zuhause & Stadt; Wiederholung & A1-Test. Jedes bietet Grammatik, Wortschatz, Hören, Lesen, Sprechen und Schreiben. Alle Module bleiben frei zugänglich; die KI empfiehlt einen Einstieg oder eine Fortsetzung.
`target_language` ist die Zielsprache, `ui_language` die Anweisungssprache; das ist keine Kopplung an Englisch oder Deutsch. Nutzer, Sprache und Kursversion bilden den Lernkontext. Ein Sprachwechsel aktiviert ein anderes Profil und erhält den bisherigen Lernstand. Englisch besitzt das erste vollständige geprüfte Paket (42 Reserveaufgaben plus historische Aufgaben). Weitere Sprachen benötigen ein vollständiges redaktionell geprüftes Paket aus sieben Modulen und Reserven für alle sechs Bereiche sowie passende Sprach-/Stimmenkonfiguration. `InstallPack` ist der Importpunkt. Zweitsprachen-Fixtures in Tests sind **keine veröffentlichten Sprachkurse**.
Die KI entscheidet didaktisch, ob ein Modulziel erreicht ist. Go lässt diese Kennzeichnung nur zu, wenn tatsächlich bewertete echte Nachweise in allen sechs Bereichen dieses Moduls vorhanden sind. Generierungsanzahl, Klicks, Demo-Messungen und unbewertete Antworten zählen nicht als Nachweis. Es gibt keine erzwungene feste Aufgabenanzahl für einen Abschluss.
## Test und Audio
Ein Test enthält genau zwölf vorab gespeicherte Aufgaben/Rubriken: zwei je Bereich, insgesamt Inhalte aus allen sechs Lernmodulen. Neue Teststarts können neue Aufgaben liefern. Eine laufende Testsitzung bleibt unverändert, auch nach Neuladen. Je Aufgabe gibt es eine unveränderliche Testantwort; wiederholtes Senden erzeugt keine zweite Bewertung. Lösungen, Bewertungen und Hörabschriften werden bis zu zwölf ausgewerteten Antworten serverseitig zurückgehalten. Der Gesamtwert ist das Mittel der sechs Bereichswerte. Eine eventuell fehlgeschlagene KI-Zusammenfassung ändert bereits gespeicherte Werte nicht und kann separat erneut angefordert werden. Es ist eine interne Lerneinschätzung.
Aufnahmen werden im Browser auf 30 Sekunden begrenzt und als WAV PCM16, mono, 16 kHz geprüft. Rohaufnahmen werden nicht in PostgreSQL gespeichert. Bei freiem Sprechen wird zunächst wirklich transkribiert und bei unterstützter Sprache zusätzlich Azure-Aussprache gegen die tatsächliche Transkription gemessen. Das ist **keine native unscripted Content-Assessment-Auswertung**: inhaltliche Bewertung übernimmt der Lehrer-Agent. Referenzvollständigkeit wird bei freiem Sprechen nicht als Inhaltsscore gewertet. Bei fehlender Azure-Konfiguration entsteht keine erfundene Kursmessung; die Aufnahme bleibt bis zur erfolgreichen Übertragung im aktuellen Browser erhalten. Hintergrundbewertungen nutzen die gespeicherte Transkription/Messung. Sprache ohne Ausspracheunterstützung kann tatsächlich transkribiert, aber nicht mit erfundenen Aussprachewerten versehen werden.
## Validierung und noch nötige Live-Konfiguration
Go-Tests enthalten Transportverträge, Schema-/Datenschutzprüfungen und opt-in PostgreSQL-Integrationstests für Migration, persistierte Briefs, Antworten, Wiederaufnahme, Sprach-/Nutzertrennung, unveränderliche Tests und Nachweise. `COURSE_TEST_DATABASE_URL` muss ausdrücklich auf eine wegwerfbare Testdatenbank zeigen; Tests verwenden eigene temporäre Schemas. Browser-Smoke: `apps/web/tests/adaptive-course.e2e.cjs`, mit einer lokalen Test-API und `course-agent.fixture.py` als deterministischem Flowise-Ersatz. Diese Tests belegen keine Modellqualität und keine Live-Azure-/Flowise-Verbindung.
Vor echter Verwendung die beiden Flows mit den neuen Prompts konfigurieren und verschiedene Lernziele und alle sechs Bereiche prüfen. Die Referenzbeispiele sind Formate, keine fest verdrahteten Aufgaben. Zugangsdaten und die laufende Flowise-Instanz wurden hier nicht verändert.
## Kurs-API für die Web-App
Alle Routen benötigen den angemeldeten Nutzer. Der Server bestimmt das aktive Sprachprofil selbst; Nutzer-/Sprachfelder aus einer Antwort werden nicht übernommen.
| Route | Verhalten |
|---|---|
| `GET /course/catalog` | Profile, sieben Module, aggregierte Nachweise, Analyse mit Faktenversion, Analyseauftrag und gespeicherte Tests |
| `POST /course/modules/{id}/tasks/next` | JSON `{request_id,skill}`; skill darf leer sein für KI-Empfehlung; HTTP 202 mit gespeichertem Job |
| `GET /course/jobs/{id}` | queued/running/succeeded/failed, Phase, task_id und sichtbare Quelle |
| `POST /course/jobs/{id}/retry` | Fehlgeschlagenen eigenen Auftrag erneut einreihen |
| `GET /course/modules/{id}/tasks?offset=0` | Eigener Aufgabenverlauf, 25 Einträge je Seite, ohne Schlüssel |
| `GET /course/tasks/{id}` | Aufgabe und eigener letzter Versuch; Freigabe privater Felder erst nach Bewertung bzw. vollständigem Test |
| `GET /course/tasks/{id}/audio` | Azure-TTS für privaten Hörtext oder sichtbaren Nachsprechtext |
| `POST /course/tasks/{id}/attempts` | JSON `{request_id,answer}`; bei choice Options-ID; HTTP 201 mit Bewertung oder 202 mit gespeichertem Versuch und Bewertungsauftrag |
| `POST /course/tasks/{id}/audio-attempts` | Multipart `request_id` und `audio`; zuerst echte Spracherkennung/Messung, danach dauerhafter Versuch und Bewertungsauftrag |
| `GET /course/attempts/{id}` | Gespeicherter Versuch und gegebenenfalls freigegebene Bewertung |
| `POST /course/attempts/{id}/retry` | Fehlgeschlagene Hintergrundbewertung ohne neue Antwort wiederholen |
| `POST /course/exams` | JSON `{request_id}`; dauerhafte Testsitzung plus Vorbereitungsauftrag |
| `GET /course/exams/{id}` | Eingefrorene Testaufgaben und eigene Antworten; Feedback erst am Ende |
Request-IDs: 8–80 Zeichen aus Buchstaben, Ziffern, `_` oder `-`. Gleiche ID und gleicher Vorgang liefern den bereits gespeicherten Vorgang; Kontextkonflikte liefern HTTP 409. Ungültige Eingaben 400, unzugängliche Aufgaben 404, fehlende Audiofunktion 503. Alte Auswahl-Clients ohne `request_id` behalten beim Antwort-Endpunkt ihr bisheriges `CourseAttemptResult`-Format. Die bisherigen `/course/modules`- und `/practice`-Routen bleiben als Kompatibilitätsansicht erhalten; neue Clients verwenden `/course/catalog` und die asynchronen Task-Routen.