Der thematische Lernweg berücksichtigt bisher gut gelöste Aufgaben nun bei neuen Schritten. Kürzlich positive Grundlagen führen bevorzugt zu unbekannten, redaktionell freigegebenen Grammatikbeispielen desselben Satzmusters. Ohne neues Beispiel können aktuelle oder unabhängig gestützte positive Ergebnisse weitere identische Grundlagenwiederholungen reduzieren. Ältere, neuere schwache und unbenotete Ergebnisse werden vorsichtig behandelt; Wortbedeutungen bleiben getrennt. Berücksichtigte frühere Übung wird separat vom manuellen Überspringen gezählt, ohne neue Antworten, Noten oder Beherrschungsnachweise zu erzeugen. Gewählte Transferbeispiele bleiben stabil. Lernwegposition, historische Aufgaben und Bewertungen sowie Prüfungen bleiben erhalten; unvollständige Prüfungen und Demoantworten liefern keine positiven Auswahlbelege. Frühere Bewertungen werden bei einer erneut empfohlenen Aufgabe ausdrücklich eingeklappt gekennzeichnet. Validierung: Go-Race-Suite mit eigener lokaler PostgreSQL-Testdatenbank, go vet, Web-Build, Bank-/Varianten-/Sequenzaudit sowie lokale Browser-Smokes für Sprachen, Kurs und vorherige Bewertungen. Geprüft sind unter anderem Nutzertrennung, Zeitabstände, neue Fehler, unbenotete Antworten und stabile Transferbeispiele beim Sprachwechsel. Keine zusätzlichen Modellaufrufe oder Produktionsänderungen.
123 lines
7.0 KiB
Markdown
123 lines
7.0 KiB
Markdown
# 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.
|
|
|
|
### Evidence-aware scaffold repetition
|
|
|
|
The additive `reused_steps` counter distinguishes earlier practice taken into
|
|
account from explicit skipping. Neither counter is graded evidence. The stored
|
|
`practice_reason` identifies foundation, transfer or refresh; recommendations
|
|
expose these fields and `selection_revision`. The step layout remains
|
|
`thematic-A1-v1`; selection metadata/policy is versioned separately, so this update
|
|
preserves existing cursors. Already active assignments remain stable, including a
|
|
chosen transfer example across request retries and native-language changes.
|
|
|
|
Editorial `alternatives` are allowed only for grammar choice tasks in the same
|
|
module and learning goal, with explicitly reviewed comparable sentence patterns.
|
|
There is no automatic replacement based on broad goal labels alone, nor any
|
|
replacement of vocabulary meanings. The new chosen example remains an ordinary
|
|
immutable assignment with its own original canonical/evidence identity.
|
|
|
|
Selection reads owned, non-demo answers scoped by target language and course
|
|
version, at most the latest 2,000 in a 30-day module window. Incomplete exam
|
|
answers/grades never influence it. The latest answer for each canonical item
|
|
must be graded and >=85, no older than seven days. Fresh exact-item success has
|
|
a 30-minute cooldown; after that, fewer repetitions require positive answers at
|
|
least 24 hours apart or, for grammar, three different approved examples with
|
|
recent positive latest answers. Locale variants and same-day repetitions do not
|
|
multiply distinct examples. Newer weak or ungraded answers block the item's
|
|
positive assumption. Unseen approved grammar examples take priority over reuse;
|
|
assignments in any exam are also excluded from being called unseen examples.
|
|
Only grammar/vocabulary scaffold positions may reuse earlier practice. The
|
|
remaining thematic stages, manual skill selection and exams retain their behavior.
|
|
No synthetic attempt, grade, progress event or pronunciation measurement is created.
|
|
|
|
The frontend folds prior feedback for an active presentation awaiting a new
|
|
answer into an explicitly labeled previous-attempt disclosure. Stored feedback,
|
|
answer keys and the existing exam disclosure rules are unchanged.
|