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
+6 -4
View File
@@ -37,14 +37,16 @@ func scanCourseJob(row interface{ Scan(...any) error }) (domain.CourseJob, error
}
if len(result) > 0 {
var r struct {
TaskID string `json:"task_id"`
Source string `json:"source"`
Review bool `json:"review"`
TaskID string `json:"task_id"`
Recommendation *domain.SequenceRecommendation `json:"recommendation"`
Source string `json:"source"`
Review bool `json:"review"`
}
if err = json.Unmarshal(result, &r); err != nil {
return j, err
}
j.TaskID = r.TaskID
j.Recommendation = r.Recommendation
j.Source = r.Source
j.Review = r.Review
}
@@ -91,7 +93,7 @@ func (s *AdaptiveStore) Finish(ctx context.Context, j domain.CourseJob, task *do
if failure != "" {
status = "failed"
}
_, err := s.db.ExecContext(ctx, `UPDATE course_v2_jobs SET status=$3,stage=$3,result=COALESCE($4,result),error=$5,lease_until=NULL WHERE id=$1 AND lease=$2 AND status='running'`, j.ID, j.Lease, status, result, failure)
_, err := s.db.ExecContext(ctx, `UPDATE course_v2_jobs SET status=$3,stage=$3,result=COALESCE(result,'{}'::jsonb)||COALESCE($4,'{}'::jsonb),error=$5,lease_until=NULL WHERE id=$1 AND lease=$2 AND status='running'`, j.ID, j.Lease, status, result, failure)
return err
}
func (s *AdaptiveStore) RetryEvaluation(ctx context.Context, user, language, attemptID string) (domain.CourseJob, error) {
+17 -3
View File
@@ -171,7 +171,10 @@ func (s *AdaptiveStore) InstallBank(ctx context.Context) error {
if err != nil {
return err
}
if _, err = s.db.ExecContext(ctx, bankSchema); err != nil {
if _, err = bundledSequences(); err != nil {
return err
}
if _, err = s.db.ExecContext(ctx, bankSchema+sequenceSchema); err != nil {
return err
}
tx, err := s.db.BeginTx(ctx, nil)
@@ -375,7 +378,11 @@ func (s *AdaptiveStore) AssignBankTask(ctx context.Context, j domain.CourseJob)
hb := sha256.Sum256([]byte(j.UserID + b.entry.ID))
return strings.Compare(hex.EncodeToString(ha[:]), hex.EncodeToString(hb[:])) < 0
})
chosen := candidates[0]
selection, index, err := selectSequence(ctx, tx, j, candidates)
if err != nil {
return domain.AdaptiveTask{}, err
}
chosen := candidates[index]
t := chosen.entry.Task
t.Source = "curated"
t.Review = chosen.seen
@@ -403,7 +410,14 @@ func (s *AdaptiveStore) AssignBankTask(ctx context.Context, j domain.CourseJob)
if err != nil {
return domain.AdaptiveTask{}, err
}
data, _ := json.Marshal(map[string]any{"task_id": t.ID, "source": "curated", "review": chosen.seen})
if err = saveSequenceSelection(ctx, tx, j, selection, t.ID); err != nil {
return domain.AdaptiveTask{}, err
}
var recommendation *domain.SequenceRecommendation
if selection != nil {
recommendation = selection.Recommendation
}
data, _ := json.Marshal(map[string]any{"task_id": t.ID, "source": "curated", "review": chosen.seen, "recommendation": recommendation})
if _, err = tx.ExecContext(ctx, `UPDATE course_v2_jobs SET result=$2 WHERE id=$1`, j.ID, data); err != nil {
return domain.AdaptiveTask{}, err
}
+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
}
@@ -0,0 +1,63 @@
package store
import (
"encoding/json"
"testing"
)
func TestReviewedSequencesProtectPreparation(t *testing.T) {
pack, err := bundledSequences()
if err != nil {
t.Fatal(err)
}
base, err := BundledBank()
if err != nil {
t.Fatal(err)
}
if len(pack.Sequences) != 60 {
t.Fatal(len(pack.Sequences))
}
copyPack := func() sequencePack {
raw, _ := json.Marshal(pack)
var copy sequencePack
if err := json.Unmarshal(raw, &copy); err != nil {
t.Fatal(err)
}
return copy
}
t.Run("no free speech first", func(t *testing.T) {
copy := copyPack()
copy.Sequences[0].Steps[0] = copy.Sequences[0].Steps[len(copy.Sequences[0].Steps)-1]
if validateSequences(copy, base) == nil {
t.Fatal("unprepared speaking accepted")
}
})
t.Run("no unrelated writing at the end", func(t *testing.T) {
copy := copyPack()
n := len(copy.Sequences[0].Steps)
other := copy.Sequences[1]
copy.Sequences[0].Steps[n-2] = other.Steps[len(other.Steps)-2]
if validateSequences(copy, base) == nil {
t.Fatal("unrelated writing accepted")
}
})
t.Run("both native titles required", func(t *testing.T) {
copy := copyPack()
delete(copy.Sequences[0].Titles, "ru-RU")
if validateSequences(copy, base) == nil {
t.Fatal("missing Russian topic accepted")
}
})
for _, module := range []string{"introductions", "family", "numbers_time", "daily_life", "food_shopping", "home_city"} {
positions := sequencePositions(pack, "a1_"+module+"_v1")
if len(positions) == 0 || positions[0].Step.Phase != "listen" {
t.Fatal("no listening entry", module)
}
for _, native := range []string{"de-DE", "ru-RU"} {
r := recommendationAt(pack, positions, 0, 0, "", native)
if r.Topic != 1 || r.Topics != 10 || r.Title == "" || r.Complete {
t.Fatal(r)
}
}
}
}
@@ -1,7 +1,7 @@
{
"revision": "en-A1-bank-v2",
"total": 840,
"editorial_review_sha256": "a64cc0b862192e996265420c7e6d8ac82c3543449c97fbdd99dc816a270e141a",
"editorial_review_sha256": "6018e163c0e4a79dd12828c368db42c4382398be51f0c70c3343ba512278a42d",
"files": {
"introductions.grammar.json": "e166492fa3e9e13760620bda1af2c0bb6472d91216a4c46808360264450c5ebc",
"introductions.vocabulary.json": "d72c534e3c7422d85b2aa03f2988b77da31163637c70ac511ca07f278d1fdd81",
@@ -0,0 +1,3 @@
{
"sha256": "808b5b14d40eeee0d4cd47f584532e71c6bbb1a9c090d0166fd055861213efa8"
}
File diff suppressed because it is too large Load Diff