Mehrsprachige Bedienung und versionierte Aufgabenvarianten einführen

Übersetzungskataloge, getrennte Sprachpräferenzen und einen versionierten Aufgabenpilot ergänzen. Historische Aufgaben und Bewertungen bleiben erhalten; äquivalente Ansichten teilen Nachweise. Lokal mit Race-Tests und PostgreSQL, Vet, Web-Build, Bank-Audits und Browser-Fixtures geprüft. Dieser Stand dient als Ausgangspunkt für die anschließend beauftragte Zusammenführung zur Muttersprache.
This commit is contained in:
Eugenius Naumenko
2026-11-07 16:26:26 +00:00
parent 87684ba0fd
commit f3d42ee2b6
68 changed files with 3895 additions and 481 deletions
+270
View File
@@ -0,0 +1,270 @@
package store
import (
"context"
"crypto/sha256"
"database/sql"
"embed"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"strings"
"speech-learning-api/internal/domain"
)
//go:embed coursebank/variants/*.json
var variantFiles embed.FS
var ErrCourseVariantUnavailable = errors.New("no reviewed exercises are available for this explanation language")
const variantSchema = `
CREATE TABLE IF NOT EXISTS course_v2_bank_variants (
id TEXT PRIMARY KEY,base_entry_id TEXT NOT NULL REFERENCES course_v2_bank(id),
canonical_task_id TEXT NOT NULL,instruction_language TEXT NOT NULL,revision TEXT NOT NULL,
data JSONB NOT NULL,checksum TEXT NOT NULL,active BOOLEAN NOT NULL DEFAULT true);
CREATE UNIQUE INDEX IF NOT EXISTS course_v2_variant_active_presentation ON course_v2_bank_variants(base_entry_id,instruction_language) WHERE active;
CREATE INDEX IF NOT EXISTS course_v2_variant_lookup ON course_v2_bank_variants(instruction_language,base_entry_id) WHERE active;
ALTER TABLE course_v2_tasks ADD COLUMN IF NOT EXISTS variant_id TEXT REFERENCES course_v2_bank_variants(id);
CREATE INDEX IF NOT EXISTS course_v2_task_canonical ON course_v2_tasks(owner_id,language,version,(COALESCE(NULLIF(data->>'canonical_task_id',''),bank_entry_id))) WHERE exam_id IS NULL;
-- Separate frozen presentations are allowed; their evidence identity is shared
-- only when the editorial review classifies them as equivalent translations.
DROP INDEX IF EXISTS course_v2_bank_assignment;
CREATE UNIQUE INDEX IF NOT EXISTS course_v2_bank_variant_assignment ON course_v2_tasks(owner_id,bank_entry_id,COALESCE(variant_id,'')) WHERE exam_id IS NULL AND bank_entry_id IS NOT NULL;
`
func BundledVariants(base []domain.BankEntry) ([]domain.BankVariant, error) {
manifestData, err := variantFiles.ReadFile("coursebank/variants/manifest.json")
if err != nil {
return nil, err
}
var manifest struct {
Total int `json:"total"`
Files map[string]string `json:"files"`
}
if err = json.Unmarshal(manifestData, &manifest); err != nil {
return nil, err
}
variants := []domain.BankVariant{}
for name, digest := range manifest.Files {
if strings.ContainsAny(name, "/\\") || name == "manifest.json" {
return nil, errors.New("invalid variant manifest path")
}
data, err := variantFiles.ReadFile("coursebank/variants/" + name)
if err != nil {
return nil, err
}
sum := sha256.Sum256(data)
if hex.EncodeToString(sum[:]) != digest {
return nil, fmt.Errorf("variant checksum mismatch: %s", name)
}
var batch []domain.BankVariant
dec := json.NewDecoder(strings.NewReader(string(data)))
dec.DisallowUnknownFields()
if err = dec.Decode(&batch); err != nil {
return nil, err
}
variants = append(variants, batch...)
}
if len(variants) != manifest.Total || manifest.Total == 0 {
return nil, errors.New("invalid variant count")
}
return variants, ValidateVariants(base, variants)
}
func ValidateVariants(base []domain.BankEntry, variants []domain.BankVariant) error {
entries := map[string]domain.BankEntry{}
for _, entry := range base {
entries[entry.ID] = entry
}
seen := map[string]bool{}
presentations := map[string]bool{}
moduleLabels := map[string]string{}
for _, v := range variants {
original, ok := entries[v.BaseEntryID]
t := v.Task
b := original.Task
if !ok || v.ID == "" || seen[v.ID] || !v.Reviewed || v.Revision == "" || v.InstructionLanguage == "" || t.ID != "" || t.Source != "" || t.ExamID != "" || t.EvidenceTaskID != "" || t.VariantID != v.ID || t.ContentRevision != v.Revision || t.CanonicalTaskID != v.CanonicalTaskID || t.InstructionLanguage != v.InstructionLanguage || t.SchemaVersion != b.SchemaVersion || t.ModuleID != b.ModuleID || t.TargetLanguage != b.TargetLanguage || t.CourseVersion != b.CourseVersion || t.CEFRLevel != b.CEFRLevel || t.Skill != b.Skill || t.Kind != b.Kind || t.AnswerKey == nil || t.Instruction == "" || len([]rune(t.Prompt)) > 2000 || strings.Contains(t.Prompt, "<") {
return fmt.Errorf("invalid task variant: %s", v.ID)
}
if _, exists := entries[v.ID]; exists {
return fmt.Errorf("variant identity collides with a base entry: %s", v.ID)
}
if v.ModuleTitle == "" || v.ModuleDescription == "" {
return fmt.Errorf("variant module labels missing: %s", v.ID)
}
labelKey := t.ModuleID + ":" + v.InstructionLanguage
labelValue := v.ModuleTitle + "\n" + v.ModuleDescription
if previous, exists := moduleLabels[labelKey]; exists && previous != labelValue {
return fmt.Errorf("inconsistent module labels: %s", v.ID)
}
moduleLabels[labelKey] = labelValue
seen[v.ID] = true
presentation := v.BaseEntryID + ":" + v.InstructionLanguage
if presentations[presentation] {
return fmt.Errorf("duplicate active locale presentation: %s", v.ID)
}
presentations[presentation] = true
referenceLanguage := t.TargetLanguage
if t.Skill == "vocabulary" {
referenceLanguage = t.InstructionLanguage
}
if t.AnswerKey.ReferenceAnswerLanguage != referenceLanguage {
return fmt.Errorf("invalid reference language: %s", v.ID)
}
if (v.Equivalence != "translation" && v.Equivalence != "adaptation") || (v.Equivalence == "translation" && v.CanonicalTaskID != v.BaseEntryID) || (v.Equivalence == "adaptation" && v.CanonicalTaskID != v.ID) {
return fmt.Errorf("invalid variant identity: %s", v.ID)
}
prompt := t.Instruction
if t.Stimulus != nil {
stimulus := t.Stimulus
if stimulus.Text == "" || stimulus.Language == "" || (stimulus.Role == "target" && stimulus.Language != t.TargetLanguage) || !bankMember(stimulus.Role, []string{"target", "source", "context"}) || (stimulus.Role == "source" && stimulus.Language == t.TargetLanguage) || t.Skill == "listening" {
return fmt.Errorf("invalid public stimulus: %s", v.ID)
}
prompt += " " + stimulus.Text
}
if t.Prompt != prompt || t.AudioText != b.AudioText || t.Passage != b.Passage || t.ReferenceText != b.ReferenceText || len(t.Options) != len(b.Options) || t.AnswerKey.CorrectOptionID != b.AnswerKey.CorrectOptionID || t.AnswerKey.Explanation == "" || len(t.AnswerKey.Rubric) == 0 || t.AnswerKey.ReferenceAnswerLanguage == "" {
return fmt.Errorf("variant changes protected task content: %s", v.ID)
}
labels := map[string]bool{}
for i, option := range t.Options {
label := strings.ToLower(strings.TrimSpace(option.Label))
expectedRole := "target"
expectedLanguage := t.TargetLanguage
if t.Skill == "vocabulary" {
expectedRole = "meaning"
expectedLanguage = t.InstructionLanguage
}
if option.Role != expectedRole || option.Language != expectedLanguage {
return fmt.Errorf("invalid option language role: %s", v.ID)
}
if expectedRole == "meaning" && v.Equivalence == "translation" && t.InstructionLanguage == t.TargetLanguage {
return fmt.Errorf("same-language meanings need a reviewed adaptation: %s", v.ID)
}
if option.ID != b.Options[i].ID || option.Language == "" || label == "" || labels[label] || (v.Equivalence == "translation" && option.Role == "target" && option.Label != b.Options[i].Label) {
return fmt.Errorf("invalid variant options: %s", v.ID)
}
labels[label] = true
if option.ID == t.AnswerKey.CorrectOptionID && option.Label != t.AnswerKey.ReferenceAnswer {
return fmt.Errorf("variant reference/key mismatch: %s", v.ID)
}
}
if v.Equivalence == "translation" && t.Skill != "vocabulary" && t.AnswerKey.ReferenceAnswer != b.AnswerKey.ReferenceAnswer {
return fmt.Errorf("translation changes reference: %s", v.ID)
}
}
return nil
}
func (s *AdaptiveStore) installVariants(ctx context.Context, base []domain.BankEntry) error {
variants, err := BundledVariants(base)
if err != nil {
return err
}
if _, err = s.db.ExecContext(ctx, variantSchema); err != nil {
return err
}
tx, err := s.db.BeginTx(ctx, nil)
if err != nil {
return err
}
defer tx.Rollback()
if _, err = tx.ExecContext(ctx, `UPDATE course_v2_bank_variants v SET active=false FROM course_v2_bank b WHERE v.base_entry_id=b.id AND b.language='en-US' AND b.version=$1`, domain.CourseVersion); err != nil {
return err
}
for _, v := range variants {
data, err := json.Marshal(v)
if err != nil {
return err
}
sum := sha256.Sum256(data)
checksum := hex.EncodeToString(sum[:])
var old string
err = tx.QueryRowContext(ctx, `SELECT checksum FROM course_v2_bank_variants WHERE id=$1`, v.ID).Scan(&old)
if err == nil && old != checksum {
return fmt.Errorf("variant revision is immutable: %s", v.ID)
}
if err != nil && !errors.Is(err, sql.ErrNoRows) {
return err
}
if _, err = tx.ExecContext(ctx, `INSERT INTO course_v2_bank_variants(id,base_entry_id,canonical_task_id,instruction_language,revision,data,checksum) VALUES($1,$2,$3,$4,$5,$6,$7) ON CONFLICT(id) DO UPDATE SET active=true`, v.ID, v.BaseEntryID, v.CanonicalTaskID, v.InstructionLanguage, v.Revision, data, checksum); err != nil {
return err
}
}
return tx.Commit()
}
// availableBank joins a locale presentation to its original curriculum entry.
// Existing German entries are left byte-for-byte intact in the bank.
const availableBank = `WITH available AS (
SELECT b.id AS base_id,''::text AS variant_id,b.id AS canonical_id,b.data AS entry,b.module_id,b.skill
FROM course_v2_bank b WHERE b.active AND b.language=$2 AND b.version=$3 AND $4='de-DE'
UNION ALL
SELECT b.id,v.id,v.canonical_task_id,jsonb_build_object('id',v.id,'revision',v.revision,'learning_goal_id',b.goal,'difficulty',b.difficulty,'reviewed',true,'task',v.data->'task'),b.module_id,b.skill
FROM course_v2_bank_variants v JOIN course_v2_bank b ON b.id=v.base_entry_id
WHERE v.active AND b.active AND b.language=$2 AND b.version=$3 AND v.instruction_language=$4
)`
func (s *AdaptiveStore) InstructionLanguages(ctx context.Context, language string) ([]string, error) {
rows, err := s.db.QueryContext(ctx, `SELECT 'de-DE' WHERE EXISTS(SELECT 1 FROM course_v2_bank WHERE active AND language=$1 AND version=$2) UNION SELECT DISTINCT v.instruction_language FROM course_v2_bank_variants v JOIN course_v2_bank b ON b.id=v.base_entry_id WHERE v.active AND b.active AND b.language=$1 AND b.version=$2 ORDER BY 1`, language, domain.CourseVersion)
if err != nil {
return nil, err
}
defer rows.Close()
out := []string{}
for rows.Next() {
var value string
if err = rows.Scan(&value); err != nil {
return nil, err
}
out = append(out, value)
}
return out, rows.Err()
}
func (s *AdaptiveStore) SetInstructionLanguage(ctx context.Context, user, language, instruction string) error {
options, err := s.InstructionLanguages(ctx, language)
if err != nil {
return err
}
if !bankMember(instruction, options) {
return ErrCourseVariantUnavailable
}
_, err = s.db.ExecContext(ctx, `UPDATE users SET instruction_language=$2 WHERE id=$1`, user, instruction)
return err
}
// A request replay may resume its frozen German exam after the learner has
// chosen another explanation language. Availability applies to new sessions.
func (s *AdaptiveStore) HasExamRequest(ctx context.Context, user, language, request string) (bool, error) {
var exists bool
err := s.db.QueryRowContext(ctx, `SELECT EXISTS(SELECT 1 FROM course_v2_exams WHERE user_id=$1 AND language=$2 AND version=$3 AND request_id=$4)`, user, language, domain.CourseVersion, request).Scan(&exists)
return exists, err
}
// Module labels are derived display content, never a rewrite of stored course
// packs, task snapshots or learning-goal identifiers.
func (s *AdaptiveStore) localizeModuleLabels(ctx context.Context, language, instruction string, modules []domain.AdaptiveModule) error {
if instruction == "" || instruction == "de-DE" {
return nil
}
rows, err := s.db.QueryContext(ctx, `SELECT DISTINCT b.module_id,v.data->>'module_title',v.data->>'module_description' FROM course_v2_bank_variants v JOIN course_v2_bank b ON b.id=v.base_entry_id WHERE v.active AND b.active AND b.language=$1 AND b.version=$2 AND v.instruction_language=$3`, language, domain.CourseVersion, instruction)
if err != nil {
return err
}
defer rows.Close()
for rows.Next() {
var id, title, description string
if err = rows.Scan(&id, &title, &description); err != nil {
return err
}
for i := range modules {
if modules[i].ID == id {
modules[i].Title = title
modules[i].Description = description
}
}
}
return rows.Err()
}