Files
Speech/docs/data-model.md
T
Eugenius Naumenko 7499491ae8 Thematische Lernwege im A1-Kurs standardmäßig empfehlen
Die bisherige Auswahl verbindet Lernbereiche nicht thematisch und kann freies
Sprechen ohne passende Vorbereitung anbieten. Der Bankbetrieb empfiehlt nun
60 redaktionell verknüpfte Themen in sechs Lernmodulen: Hören, Wortschatz,
Lesen, Nachsprechen, Grammatik, angeleitetes und freies Schreiben, freies Sprechen.

Speichert die Lernwegposition getrennt von Leistungsnachweisen. Unbeantwortete
Schritte bleiben empfohlen und sind explizit überspringbar; nach einer tatsächlich
bewerteten schwachen Antwort gibt es höchstens eine Wiederholung ohne Notensperre.
Bereichswahl, Muttersprache, historische Aufgaben und A1-Tests bleiben unabhängig.
Deutsch und Russisch zeigen Thema und Schritt; vorhandene Aufgabeninhalte und
Bewertungen werden nicht umgeschrieben. Keine zusätzlichen Modellaufrufe.

Validierung: Go-Race-Suite mit eigener lokaler PostgreSQL-Testdatenbank, go vet,
Web-Build, Bank-/Varianten-/Sequenzaudits und lokale Kurs-/Sprachen-/Admin-Smokes.
Regressionsfall: passendes Schreiben vor freiem Sprechen über zwei Freunde.
Keine Live-Anbieterprüfung oder Produktionsänderung.
2026-11-11 17:51:32 +00:00

4.8 KiB

Data Model

Core tables are created automatically by the Go API at startup:

  • users
  • learner_profiles
  • language_profiles
  • lessons
  • exercises
  • attempts
  • progress_events
  • conversation_sessions
  • conversation_turns

The MVP seeds en-US A1 lessons and exercises. Additional languages should be added by inserting a new language_profiles row and matching lessons/exercises.

Language roles

  • learner_profiles.target_language: language being learned; evidence is scoped by authenticated learner, target language and course version.
  • users.native_language: shared GUI and explanation language (de-DE/ru-RU).
  • users.ui_language and users.instruction_language: compatibility aliases, constrained to equal native_language. No independent preferences remain.

PATCH /me/preferences accepts the canonical native field and preserves omitted profile values atomically. Conflicting aliases fail before writes. Registration, auth responses and /me expose the canonical field. The deprecated PUT /course/instruction-language updates all aliases together. Initial migration keeps supported old GUI values, otherwise selects German; task and attempt data remain untouched. Repeated startup preserves the canonical preference.

Reviewed task presentations

course_v2_bank_variants stores immutable IDs, base-entry references, canonical identity, explanation language, revision, reviewed data and checksum. A partial unique index allows one active presentation per base entry/explanation language; retired rows remain for frozen assignments. course_v2_tasks.variant_id links new variant snapshots. Its assignment uniqueness includes the variant, allowing separate frozen language presentations. Original German bank entries and old assigned JSON remain unchanged.

New task JSON may include instruction_language, instruction, stimulus, variant_id, content_revision, canonical_task_id, option language/role and private reference-answer language. The compatible combined prompt remains. Public(false) still removes solutions and listening transcripts and always removes the internal evidence_task_id.

New equivalent presentations reuse the earliest matching owned assignment's evidence_task_id (or its ID for legacy snapshots). Graded attempts remain separate; distinct-task aggregation uses that identity. New scripted speech observations also use it for repetition grouping. Previously stored observations and historical attempt JSON are unchanged; this does not retrospectively dedupe all old exam copies. Adaptations have new canonical/evidence identities.

course_v2_jobs.instruction_language freezes the effective preference when the job is inserted. Startup fills this additive field once for older jobs; retries and request replays keep it. Both native languages provide 840 task presentations, seven modules and the internal A1 exam. All Russian entries are translations with shared base canonical IDs. Retired English pilot variants remain in existing databases for frozen history but are no longer offered.

Thematic learning paths

course_v2_sequence_progress is additive state scoped by user, target language, course version, module and editorial sequence revision. It stores a cursor, current assignment, presentation timestamp, skipped count and bounded review flag. It is navigation/participation state, never mastery evidence or an exam result. Only a new non-demo saved answer for the current presentation or an explicit skip advances the cursor. A known graded error may offer one repeat; grades never gate progress. Native changes share the cursor, while task snapshots remain frozen. Selections and cursor changes commit together under the existing per-user/course advisory lock. Job results retain recommendation metadata across finalization and idempotent replay. Direct skill selection and exams do not move this cursor.

GET /course/catalog adds sequence_recommendations by module. Recommendations include localized topic title, current phase and step, topic count, active task, review/answer-needed flags and explicit skipped count. Completed paths indicate only that steps were worked through or skipped. POST /course/modules/{id}/tasks/next with empty skill uses the path; optional skip_task_id explicitly skips the current owned assignment. Stale/foreign skips fail without changing progress. The field is rejected alongside an explicit skill or in AI mode. Request replay must preserve the original skip subject. Existing clients may omit the new field.

Immutable thematic links are embedded separately from the task/variant banks. Their source and compiler are pinned by a separate editorial review and manifest; changing the path requires a new revision. The 840 base entries and Russian presentations are unchanged. Initial activation begins at the first topic without reinterpreting historical grades or rewriting existing assignments.