Files
Speech/docs/data-model.md
T
Eugenius Naumenko 16cceae28a Muttersprache koppeln und russischen A1-Kurs ergänzen
GUI und neue Erklärungen verwenden gemeinsam native_language. Deutsch und
Russisch sind die beiden Muttersprachen; Englisch bleibt die Lernsprache.
Kompatibilitätsfelder werden atomar gekoppelt, widersprüchliche Eingaben
abgewiesen und bestehende Profile sowie eingefrorene Inhalte erhalten.

Ergänzt vollständige russische GUI-Kataloge und 840 geprüfte Aufgabenansichten
in sieben Modulen einschließlich A1-Test, mit getrennten Sprachrollen für
Ausgangs- und Lernmaterial. Äquivalente Ansichten teilen ihre Nachweisidentität.
Stabile API-Fehlercodes, neue deterministische Hilfen und Trainingsbegründungen
berücksichtigen die Muttersprache. Dokumentiert das Sprachmodell in AGENTS.md.

Validierung: Go-Race-Suite mit eigener lokaler PostgreSQL-Testdatenbank, go vet,
Web-Build, Offline-Bank-/Variantenaudit, Diff-Prüfung sowie lokale Browser-Smokes
für Sprachen, Kurs, Administration, Aussprache und Aufnahme. Keine Live-Anbieter,
Produktionsprofile, Deployment-Schritte oder historischen Neubewertungen.
2026-11-07 17:02:17 +00:00

3.0 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.