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.
This commit is contained in:
Eugenius Naumenko
2026-11-11 17:51:32 +00:00
parent 16cceae28a
commit 7499491ae8
28 changed files with 5489 additions and 43 deletions
+288
View File
@@ -0,0 +1,288 @@
package store
import (
"context"
"crypto/sha256"
"database/sql"
_ "embed"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"sync"
"speech-learning-api/internal/domain"
)
//go:embed coursebank/sequences.json
var sequenceData []byte
//go:embed coursebank/sequence_manifest.json
var sequenceManifest []byte
const sequenceSchema = `
CREATE TABLE IF NOT EXISTS course_v2_sequence_progress (
user_id TEXT NOT NULL REFERENCES users(id),language TEXT NOT NULL,version TEXT NOT NULL,
module_id TEXT NOT NULL,revision TEXT NOT NULL,cursor INT NOT NULL DEFAULT 0 CHECK(cursor>=0),
active_task_id TEXT REFERENCES course_v2_tasks(id),presented_at TIMESTAMPTZ,
skipped_steps INT NOT NULL DEFAULT 0 CHECK(skipped_steps>=0),
reviewed BOOLEAN NOT NULL DEFAULT false,
PRIMARY KEY(user_id,language,version,module_id,revision));
ALTER TABLE course_v2_sequence_progress ADD COLUMN IF NOT EXISTS reviewed BOOLEAN NOT NULL DEFAULT false;
`
type sequencePack struct {
Revision string `json:"revision"`
Review string `json:"editorial_review_sha256"`
Sequences []domain.LearningSequence `json:"sequences"`
}
var sequencesOnce sync.Once
var sequencesPack sequencePack
var sequencesError error
func bundledSequences() (sequencePack, error) {
sequencesOnce.Do(func() {
var manifest struct {
SHA string `json:"sha256"`
}
if sequencesError = json.Unmarshal(sequenceManifest, &manifest); sequencesError != nil {
return
}
sum := sha256.Sum256(sequenceData)
if hex.EncodeToString(sum[:]) != manifest.SHA {
sequencesError = errors.New("sequence checksum mismatch")
return
}
if sequencesError = json.Unmarshal(sequenceData, &sequencesPack); sequencesError != nil {
return
}
base, err := BundledBank()
if err != nil {
sequencesError = err
return
}
sequencesError = validateSequences(sequencesPack, base)
})
return sequencesPack, sequencesError
}
func validateSequences(pack sequencePack, base []domain.BankEntry) error {
if pack.Revision == "" || len(pack.Review) != 64 || len(pack.Sequences) == 0 {
return errors.New("missing sequence review")
}
entries := map[string]domain.BankEntry{}
for _, entry := range base {
entries[entry.ID] = entry
}
seen := map[string]bool{}
phases := []string{"listen", "vocabulary", "read", "repeat", "grammar", "write", "compose", "speak"}
kinds := []string{"choice", "choice", "choice", "repeat_sentence", "choice", "short_text", "free_text", "free_speech"}
skills := []string{"listening", "vocabulary", "reading", "speaking", "grammar", "writing", "writing", "speaking"}
for _, seq := range pack.Sequences {
if seq.ID == "" || seen[seq.ID] || seq.Titles["de-DE"] == "" || seq.Titles["ru-RU"] == "" {
return fmt.Errorf("invalid sequence: %s", seq.ID)
}
seen[seq.ID] = true
phase := -1
for _, step := range seq.Steps {
entry, ok := entries[step.BankEntryID]
next := phase
if next < 0 || step.Phase != phases[next] {
next++
}
if next >= len(phases) || step.Phase != phases[next] || !ok || entry.Task.ModuleID != seq.ModuleID || entry.Task.Kind != kinds[next] || entry.Task.Skill != skills[next] {
return fmt.Errorf("invalid sequence step: %s/%s", seq.ID, step.BankEntryID)
}
phase = next
}
if phase != len(phases)-1 {
return fmt.Errorf("incomplete sequence: %s", seq.ID)
}
last := seq.Steps[len(seq.Steps)-1]
previous := seq.Steps[len(seq.Steps)-2]
if entries[last.BankEntryID].Task.AnswerKey.ReferenceAnswer != entries[previous.BankEntryID].Task.AnswerKey.ReferenceAnswer {
return fmt.Errorf("unrelated final writing/speech: %s", seq.ID)
}
}
return nil
}
type sequencePosition struct {
Sequence domain.LearningSequence
Step domain.LearningSequenceStep
StepIndex int
TopicIndex int
Topics int
}
func sequencePositions(pack sequencePack, module string) []sequencePosition {
out := []sequencePosition{}
topics := 0
for _, seq := range pack.Sequences {
if seq.ModuleID == module {
topics++
}
}
topic := 0
for _, seq := range pack.Sequences {
if seq.ModuleID != module {
continue
}
for n, step := range seq.Steps {
out = append(out, sequencePosition{seq, step, n, topic, topics})
}
topic++
}
return out
}
func recommendationAt(pack sequencePack, positions []sequencePosition, cursor, skipped int, task, native string) *domain.SequenceRecommendation {
r := &domain.SequenceRecommendation{Revision: pack.Revision, Complete: cursor >= len(positions), SkippedSteps: skipped}
if r.Complete {
return r
}
pos := positions[cursor]
r.SequenceID = pos.Sequence.ID
r.Title = pos.Sequence.Titles[native]
r.Phase = pos.Step.Phase
r.Step = pos.StepIndex + 1
r.Steps = len(pos.Sequence.Steps)
r.Topic = pos.TopicIndex + 1
r.Topics = pos.Topics
r.TaskID = task
return r
}
// This cursor records participation/explicit skipping, never success. It is
// independent of native language, variant and grades. Exams never use it.
func (s *AdaptiveStore) SequenceRecommendation(ctx context.Context, user, language, module, native string) (*domain.SequenceRecommendation, error) {
if language != "en-US" {
return nil, nil
}
pack, err := bundledSequences()
if err != nil {
return nil, err
}
positions := sequencePositions(pack, module)
if len(positions) == 0 {
return nil, nil
}
var cursor, skipped int
var reviewed bool
var task string
err = s.db.QueryRowContext(ctx, `SELECT cursor,skipped_steps,COALESCE(active_task_id,''),reviewed FROM course_v2_sequence_progress WHERE user_id=$1 AND language=$2 AND version=$3 AND module_id=$4 AND revision=$5`, user, language, domain.CourseVersion, module, pack.Revision).Scan(&cursor, &skipped, &task, &reviewed)
if err != nil && !errors.Is(err, sql.ErrNoRows) {
return nil, err
}
r := recommendationAt(pack, positions, cursor, skipped, task, native)
r.Review = reviewed
if task != "" && !r.Complete {
answered, err := sequenceAnswered(ctx, s.db, domain.CourseJob{UserID: user, Language: language, ModuleID: module}, pack.Revision)
if err != nil {
return nil, err
}
r.NeedsAnswer = !answered
}
return r, nil
}
type sequenceSelection struct {
Reset bool
Reviewed bool
Cursor int
Skipped int
Recommendation *domain.SequenceRecommendation
}
func selectSequence(ctx context.Context, tx *sql.Tx, j domain.CourseJob, candidates []bankCandidate) (*sequenceSelection, int, error) {
if j.Language != "en-US" || j.Skill != "" || j.Kind != "next" {
return nil, 0, nil
}
pack, err := bundledSequences()
if err != nil {
return nil, 0, err
}
positions := sequencePositions(pack, j.ModuleID)
if len(positions) == 0 {
if j.SubjectID != "" {
return nil, 0, ErrCourseConflict
}
return nil, 0, nil
}
_, err = tx.ExecContext(ctx, `INSERT INTO course_v2_sequence_progress(user_id,language,version,module_id,revision) VALUES($1,$2,$3,$4,$5) ON CONFLICT DO NOTHING`, j.UserID, j.Language, domain.CourseVersion, j.ModuleID, pack.Revision)
if err != nil {
return nil, 0, err
}
var cursor, skipped int
var reviewed bool
reset := false
var active string
err = tx.QueryRowContext(ctx, `SELECT cursor,skipped_steps,COALESCE(active_task_id,''),reviewed FROM course_v2_sequence_progress WHERE user_id=$1 AND language=$2 AND version=$3 AND module_id=$4 AND revision=$5 FOR UPDATE`, j.UserID, j.Language, domain.CourseVersion, j.ModuleID, pack.Revision).Scan(&cursor, &skipped, &active, &reviewed)
if err != nil {
return nil, 0, err
}
if j.SubjectID != "" && (j.SubjectID != active || cursor >= len(positions)) {
return nil, 0, ErrCourseConflict
}
if cursor < len(positions) && active != "" {
answered, err := sequenceAnswered(ctx, tx, j, pack.Revision)
if err != nil {
return nil, 0, err
}
if answered && !reviewed && j.SubjectID == "" {
// One optional review after an actually graded mistake. No pass mark
// gates the path; a second answer or explicit skip continues it.
var weak bool
err = tx.QueryRowContext(ctx, `SELECT COALESCE((SELECT a.status='graded' AND (a.evaluation->>'score')::float8<80 FROM course_v2_attempts a JOIN course_v2_sequence_progress p ON p.active_task_id=a.task_id WHERE p.user_id=$1 AND p.language=$2 AND p.version=$3 AND p.module_id=$4 AND p.revision=$5 AND a.user_id=$1 AND NOT a.demo AND a.exam_id IS NULL AND a.created_at>=p.presented_at ORDER BY a.created_at DESC,a.id DESC LIMIT 1),false)`, j.UserID, j.Language, domain.CourseVersion, j.ModuleID, pack.Revision).Scan(&weak)
if err != nil {
return nil, 0, err
}
if weak {
reviewed = true
reset = true
answered = false
}
}
if answered || j.SubjectID != "" {
cursor++
reviewed = false
reset = true
if !answered {
skipped++
}
active = ""
}
}
r := recommendationAt(pack, positions, cursor, skipped, active, j.InstructionLanguage)
r.Review = reviewed
selection := &sequenceSelection{Cursor: cursor, Skipped: skipped, Recommendation: r, Reviewed: reviewed, Reset: reset}
if r.Complete {
return selection, 0, nil
}
for n, candidate := range candidates {
if candidate.bankEntryID == positions[cursor].Step.BankEntryID {
return selection, n, nil
}
}
return nil, 0, ErrCourseVariantUnavailable
}
func saveSequenceSelection(ctx context.Context, tx *sql.Tx, j domain.CourseJob, selection *sequenceSelection, taskID string) error {
if selection == nil {
return nil
}
r := selection.Recommendation
if r.Complete {
taskID = ""
}
r.TaskID = taskID
r.NeedsAnswer = taskID != ""
_, err := tx.ExecContext(ctx, `UPDATE course_v2_sequence_progress SET cursor=$6,skipped_steps=$7,presented_at=CASE WHEN $9 OR active_task_id IS DISTINCT FROM NULLIF($8,'') THEN now() ELSE presented_at END,active_task_id=NULLIF($8,''),reviewed=$10 WHERE user_id=$1 AND language=$2 AND version=$3 AND module_id=$4 AND revision=$5`, j.UserID, j.Language, domain.CourseVersion, j.ModuleID, r.Revision, selection.Cursor, selection.Skipped, taskID, selection.Reset, selection.Reviewed)
return err
}
func sequenceAnswered(ctx context.Context, db interface {
QueryRowContext(context.Context, string, ...any) *sql.Row
}, j domain.CourseJob, revision string) (bool, error) {
var answered bool
err := db.QueryRowContext(ctx, `SELECT EXISTS(SELECT 1 FROM course_v2_attempts a JOIN course_v2_sequence_progress p ON p.active_task_id=a.task_id WHERE p.user_id=$1 AND p.language=$2 AND p.version=$3 AND p.module_id=$4 AND p.revision=$5 AND a.user_id=$1 AND a.exam_id IS NULL AND NOT a.demo AND a.status IN ('graded','ungraded','pending') AND a.created_at>=p.presented_at)`, j.UserID, j.Language, domain.CourseVersion, j.ModuleID, revision).Scan(&answered)
return answered, err
}