Flowise-Übungen stabilisieren und Lernfortschritt korrigieren

Vermeide kürzlich angezeigte Sätze bei neuen Übungen und frage Flowise bei Wiederholungen einmal erneut. Validiere strukturierte Antworten, protokolliere die Übungsquelle und schütze nutzerspezifische Übungs-IDs.

Berechne schwierige Wörter anhand der neuesten Aussprache pro Wort. Passe das Lehrerfeedback an gute Bewertungen an und verbessere das Laden neuer Übungen im Web. Ergänze gezielte Go-Tests.
This commit is contained in:
Eugenius Naumenko
2026-10-07 20:52:02 +00:00
parent 74a4caa1c6
commit bac840e091
11 changed files with 572 additions and 119 deletions
+11 -9
View File
@@ -92,15 +92,17 @@ type ProgressSummary struct {
}
type GeneratedExerciseRequest struct {
UserID string `json:"user_id"`
Profile LearnerProfile `json:"profile"`
Progress ProgressSummary `json:"progress"`
TargetLanguage string `json:"target_language"`
CEFRLevel string `json:"cefr_level"`
UILanguage string `json:"ui_language"`
SessionID string `json:"session_id"`
RecentWeakWords []WordScore `json:"recent_weak_words"`
PreferredType string `json:"preferred_type"`
UserID string `json:"user_id"`
Profile LearnerProfile `json:"profile"`
Progress ProgressSummary `json:"progress"`
TargetLanguage string `json:"target_language"`
CEFRLevel string `json:"cefr_level"`
UILanguage string `json:"ui_language"`
SessionID string `json:"session_id"`
RecentWeakWords []WordScore `json:"recent_weak_words"`
PreferredType string `json:"preferred_type"`
AvoidReferenceText string `json:"avoid_reference_text,omitempty"`
AvoidReferenceTexts []string `json:"avoid_reference_texts,omitempty"`
}
type GeneratedExercise struct {
+52 -16
View File
@@ -21,9 +21,9 @@ type DataStore interface {
UpdatePreferences(ctx context.Context, userID, uiLanguage, targetLanguage, cefrLevel string, dailyGoalMinutes int) (domain.LearnerProfile, error)
ListLanguages(ctx context.Context) ([]domain.LanguageProfile, error)
GetLanguage(ctx context.Context, code string) (domain.LanguageProfile, error)
NextLessonAndExercise(ctx context.Context, profile domain.LearnerProfile) (domain.Lesson, domain.Exercise, error)
NextLessonAndExercise(ctx context.Context, profile domain.LearnerProfile, avoidReferenceText ...string) (domain.Lesson, domain.Exercise, error)
SaveGeneratedExercise(ctx context.Context, userID string, generated domain.GeneratedExercise) (domain.Lesson, domain.Exercise, error)
GetExercise(ctx context.Context, id string) (domain.Exercise, error)
GetExercise(ctx context.Context, id, userID string) (domain.Exercise, error)
SaveAttempt(ctx context.Context, attempt domain.Attempt) (domain.Attempt, error)
Progress(ctx context.Context, userID string, limit int) (domain.ProgressSummary, error)
CreateConversationSession(ctx context.Context, userID, targetLanguage, cefrLevel string) (domain.ConversationSession, error)
@@ -190,7 +190,7 @@ func (s *Server) dashboard(w http.ResponseWriter, r *http.Request) {
writeError(w, http.StatusInternalServerError, err)
return
}
lesson, exercise, err := s.nextAgentExercise(r.Context(), user, profile, progress)
lesson, exercise, err := s.nextAgentExercise(r.Context(), user, profile, progress, nil)
if err != nil {
writeError(w, http.StatusNotFound, err)
return
@@ -211,6 +211,31 @@ func (s *Server) progress(w http.ResponseWriter, r *http.Request) {
func (s *Server) nextLesson(w http.ResponseWriter, r *http.Request) {
userID := currentUserID(r)
var req struct {
PreviousExerciseID string `json:"previous_exercise_id"`
RecentExerciseIDs []string `json:"recent_exercise_ids"`
}
if err := decodeJSON(r, &req); err != nil && !errors.Is(err, io.EOF) {
writeError(w, http.StatusBadRequest, err)
return
}
recentIDs := req.RecentExerciseIDs
if req.PreviousExerciseID != "" && (len(recentIDs) == 0 || recentIDs[len(recentIDs)-1] != req.PreviousExerciseID) {
recentIDs = append(recentIDs, req.PreviousExerciseID)
}
if len(recentIDs) > 3 {
writeError(w, http.StatusBadRequest, errors.New("at most three recent exercises are allowed"))
return
}
avoidReferenceTexts := make([]string, 0, len(recentIDs))
for _, id := range recentIDs {
previous, err := s.store.GetExercise(r.Context(), id, userID)
if err != nil {
writeError(w, http.StatusNotFound, err)
return
}
avoidReferenceTexts = append(avoidReferenceTexts, previous.TargetText)
}
user, err := s.store.GetUser(r.Context(), userID)
if err != nil {
writeError(w, http.StatusNotFound, err)
@@ -226,7 +251,7 @@ func (s *Server) nextLesson(w http.ResponseWriter, r *http.Request) {
writeError(w, http.StatusInternalServerError, err)
return
}
lesson, exercise, err := s.nextAgentExercise(r.Context(), user, profile, progress)
lesson, exercise, err := s.nextAgentExercise(r.Context(), user, profile, progress, avoidReferenceTexts)
if err != nil {
writeError(w, http.StatusNotFound, err)
return
@@ -234,21 +259,28 @@ func (s *Server) nextLesson(w http.ResponseWriter, r *http.Request) {
writeJSON(w, http.StatusOK, map[string]any{"lesson": lesson, "exercise": exercise})
}
func (s *Server) nextAgentExercise(ctx context.Context, user domain.User, profile domain.LearnerProfile, progress domain.ProgressSummary) (domain.Lesson, domain.Exercise, error) {
func (s *Server) nextAgentExercise(ctx context.Context, user domain.User, profile domain.LearnerProfile, progress domain.ProgressSummary, avoidReferenceTexts []string) (domain.Lesson, domain.Exercise, error) {
avoidReferenceText := ""
if len(avoidReferenceTexts) > 0 {
avoidReferenceText = avoidReferenceTexts[len(avoidReferenceTexts)-1]
}
generated, err := s.teacher.NextExercise(ctx, domain.GeneratedExerciseRequest{
UserID: user.ID,
Profile: profile,
Progress: progress,
TargetLanguage: profile.TargetLanguage,
CEFRLevel: profile.CEFRLevel,
UILanguage: user.UILanguage,
SessionID: flowiseSessionID(user.ID, profile.TargetLanguage, "practice"),
RecentWeakWords: progress.WeakWords,
PreferredType: "repeat_sentence",
UserID: user.ID,
Profile: profile,
Progress: progress,
TargetLanguage: profile.TargetLanguage,
CEFRLevel: profile.CEFRLevel,
UILanguage: user.UILanguage,
SessionID: flowiseSessionID(user.ID, profile.TargetLanguage, "practice"),
RecentWeakWords: progress.WeakWords,
PreferredType: "repeat_sentence",
AvoidReferenceText: avoidReferenceText,
AvoidReferenceTexts: avoidReferenceTexts,
})
if err == nil && generated.Source == "flowise" && strings.TrimSpace(generated.ReferenceText) != "" {
lesson, exercise, saveErr := s.store.SaveGeneratedExercise(ctx, user.ID, generated)
if saveErr == nil {
s.logger.Info("next exercise selected", "request_id", ctx.Value(requestIDKey), "source", exercise.Source, "exercise_id", exercise.ID)
return lesson, exercise, nil
}
s.logger.Warn("saving generated exercise failed, using seed fallback", "error", saveErr)
@@ -256,7 +288,11 @@ func (s *Server) nextAgentExercise(ctx context.Context, user domain.User, profil
if err != nil {
s.logger.Warn("flowise next exercise failed, using seed fallback", "error", err)
}
return s.store.NextLessonAndExercise(ctx, profile)
lesson, exercise, err := s.store.NextLessonAndExercise(ctx, profile, avoidReferenceTexts...)
if err == nil {
s.logger.Info("next exercise selected", "request_id", ctx.Value(requestIDKey), "source", exercise.Source, "exercise_id", exercise.ID)
}
return lesson, exercise, err
}
func (s *Server) createAttempt(w http.ResponseWriter, r *http.Request) {
@@ -265,7 +301,7 @@ func (s *Server) createAttempt(w http.ResponseWriter, r *http.Request) {
return
}
exerciseID := r.FormValue("exercise_id")
exercise, err := s.store.GetExercise(r.Context(), exerciseID)
exercise, err := s.store.GetExercise(r.Context(), exerciseID, currentUserID(r))
if err != nil {
writeError(w, http.StatusNotFound, err)
return
+69
View File
@@ -0,0 +1,69 @@
package httpapi
import (
"bytes"
"context"
"mime/multipart"
"net/http"
"net/http/httptest"
"testing"
"speech-learning-api/internal/domain"
"speech-learning-api/internal/store"
)
type exerciseLookupStore struct {
DataStore
exerciseID string
userID string
}
func (s *exerciseLookupStore) GetExercise(_ context.Context, exerciseID, userID string) (domain.Exercise, error) {
s.exerciseID = exerciseID
s.userID = userID
return domain.Exercise{}, store.ErrNotFound
}
func TestCreateAttemptScopesExerciseLookupToCurrentUser(t *testing.T) {
var body bytes.Buffer
form := multipart.NewWriter(&body)
if err := form.WriteField("exercise_id", "ex_other_user"); err != nil {
t.Fatal(err)
}
if err := form.Close(); err != nil {
t.Fatal(err)
}
req := httptest.NewRequest(http.MethodPost, "/practice/attempts", &body)
req.Header.Set("Content-Type", form.FormDataContentType())
req = req.WithContext(context.WithValue(req.Context(), userIDKey, "usr_current"))
recorder := httptest.NewRecorder()
lookup := &exerciseLookupStore{}
server := &Server{store: lookup}
server.createAttempt(recorder, req)
if recorder.Code != http.StatusNotFound {
t.Fatalf("status = %d, want 404", recorder.Code)
}
if lookup.exerciseID != "ex_other_user" || lookup.userID != "usr_current" {
t.Fatalf("lookup used exercise %q and user %q", lookup.exerciseID, lookup.userID)
}
}
func TestNextLessonScopesPreviousExerciseToCurrentUser(t *testing.T) {
req := httptest.NewRequest(http.MethodPost, "/lessons/next", bytes.NewBufferString(`{"previous_exercise_id":"ex_other_user"}`))
req = req.WithContext(context.WithValue(req.Context(), userIDKey, "usr_current"))
recorder := httptest.NewRecorder()
lookup := &exerciseLookupStore{}
server := &Server{store: lookup}
server.nextLesson(recorder, req)
if recorder.Code != http.StatusNotFound {
t.Fatalf("status = %d, want 404", recorder.Code)
}
if lookup.exerciseID != "ex_other_user" || lookup.userID != "usr_current" {
t.Fatalf("lookup used exercise %q and user %q", lookup.exerciseID, lookup.userID)
}
}
+112 -36
View File
@@ -10,6 +10,8 @@ import (
"net/http"
"strings"
"time"
"unicode"
"unicode/utf8"
"speech-learning-api/internal/config"
"speech-learning-api/internal/domain"
@@ -53,18 +55,20 @@ func (f *FlowiseTeacher) NextExercise(ctx context.Context, input domain.Generate
Source: "fallback",
}
payload := map[string]any{
"task": "next_exercise",
"user_id": input.UserID,
"target_language": input.TargetLanguage,
"cefr_level": input.CEFRLevel,
"ui_language": input.UILanguage,
"profile": input.Profile,
"progress": input.Progress,
"recent_weak_words": input.RecentWeakWords,
"preferred_type": valueOr(input.PreferredType, "repeat_sentence"),
"rules": "Generate one A1 English pronunciation exercise. Return valid JSON only with fields: exercise_type, target_language, cefr_level, reference_text, display_prompt, tts_text, focus_points, success_criteria, reason_for_choice.",
"task": "next_exercise",
"user_id": input.UserID,
"target_language": input.TargetLanguage,
"cefr_level": input.CEFRLevel,
"ui_language": input.UILanguage,
"profile": input.Profile,
"progress": input.Progress,
"recent_weak_words": input.RecentWeakWords,
"preferred_type": valueOr(input.PreferredType, "repeat_sentence"),
"avoid_reference_text": input.AvoidReferenceText,
"avoid_reference_texts": input.AvoidReferenceTexts,
"rules": "Generate one A1 English pronunciation exercise. Return valid JSON only with fields: exercise_type, target_language, cefr_level, reference_text, display_prompt, tts_text, focus_points, success_criteria, reason_for_choice. The reference_text must differ from every sentence in avoid_reference_texts. The same target word may still be used.",
}
return f.askExercise(ctx, payload, input.SessionID, fallback)
return f.askExercise(ctx, payload, input, fallback)
}
func (f *FlowiseTeacher) FeedbackForAttempt(ctx context.Context, targetText string, result domain.PronunciationResult, weakWords []domain.WordScore) (domain.TeacherResponse, error) {
@@ -100,7 +104,7 @@ func (f *FlowiseTeacher) ContinueConversation(ctx context.Context, targetLanguag
}, nil
}
func (f *FlowiseTeacher) askExercise(ctx context.Context, payload any, sessionID string, fallback domain.GeneratedExercise) (domain.GeneratedExercise, error) {
func (f *FlowiseTeacher) askExercise(ctx context.Context, payload map[string]any, input domain.GeneratedExerciseRequest, fallback domain.GeneratedExercise) (domain.GeneratedExercise, error) {
if f.cfg.FlowiseChatflow == "" || f.cfg.FlowiseBaseURL == "" {
return fallback, nil
}
@@ -108,7 +112,7 @@ func (f *FlowiseTeacher) askExercise(ctx context.Context, payload any, sessionID
reqBody, _ := json.Marshal(map[string]any{
"question": string(body),
"overrideConfig": map[string]any{
"sessionId": sessionID,
"sessionId": input.SessionID,
},
})
endpoint := strings.TrimRight(f.cfg.FlowiseBaseURL, "/") + "/api/v1/prediction/" + f.cfg.FlowiseChatflow
@@ -137,11 +141,20 @@ func (f *FlowiseTeacher) askExercise(ctx context.Context, payload any, sessionID
return fallback, nil
}
if exercise, ok := parseGeneratedExerciseEnvelope(respBody); ok {
exercise.TargetLanguage = valueOr(exercise.TargetLanguage, fallback.TargetLanguage)
exercise.CEFRLevel = valueOr(exercise.CEFRLevel, fallback.CEFRLevel)
exercise.ExerciseType = valueOr(exercise.ExerciseType, fallback.ExerciseType)
exercise.DisplayPrompt = valueOr(exercise.DisplayPrompt, fallback.DisplayPrompt)
exercise.TTSText = valueOr(exercise.TTSText, exercise.ReferenceText)
if reason := generatedExerciseValidationError(exercise, input); reason != "" {
if strings.HasPrefix(reason, "reference_text repeats") && payload["retry_instruction"] == nil {
f.logger.Info("flowise repeated a recent exercise, requesting another sentence")
retryPayload := make(map[string]any, len(payload)+1)
for key, value := range payload {
retryPayload[key] = value
}
retryPayload["retry_instruction"] = "The previous reference_text was rejected because it repeats a recent exercise. Choose a different natural A1 sentence that is not in avoid_reference_texts. Keep the required JSON format."
return f.askExercise(ctx, retryPayload, input, fallback)
}
f.logger.Warn("flowise exercise response failed validation", "reason", reason)
return fallback, nil
}
exercise.ID = "" // Exercise IDs are assigned by the API, never by Flowise.
exercise.Source = "flowise"
return exercise, nil
}
@@ -149,20 +162,74 @@ func (f *FlowiseTeacher) askExercise(ctx context.Context, payload any, sessionID
return fallback, nil
}
func parseGeneratedExerciseEnvelope(body []byte) (domain.GeneratedExercise, bool) {
var envelope struct {
Text string `json:"text"`
JSON json.RawMessage `json:"json"`
func validGeneratedExercise(exercise domain.GeneratedExercise, input domain.GeneratedExerciseRequest) bool {
return generatedExerciseValidationError(exercise, input) == ""
}
func generatedExerciseValidationError(exercise domain.GeneratedExercise, input domain.GeneratedExerciseRequest) string {
if input.AvoidReferenceText != "" && sameReferenceText(exercise.ReferenceText, input.AvoidReferenceText) {
return "reference_text repeats the previous exercise"
}
if err := json.Unmarshal(body, &envelope); err == nil {
if envelope.Text != "" {
if parsed, ok := parseGeneratedExercise(envelope.Text); ok {
return parsed, true
}
for _, previous := range input.AvoidReferenceTexts {
if sameReferenceText(exercise.ReferenceText, previous) {
return "reference_text repeats a recent exercise"
}
if len(envelope.JSON) > 0 && string(envelope.JSON) != "null" {
if parsed, ok := parseGeneratedExerciseJSON(envelope.JSON); ok {
return parsed, true
}
if exercise.ExerciseType != "repeat_sentence" {
return "unsupported exercise_type"
}
if exercise.TargetLanguage != input.TargetLanguage {
return "target_language does not match the request"
}
if exercise.CEFRLevel != input.CEFRLevel {
return "cefr_level does not match the request"
}
for _, field := range []struct {
name string
value string
limit int
}{
{"reference_text", exercise.ReferenceText, 160},
{"display_prompt", exercise.DisplayPrompt, 240},
{"tts_text", exercise.TTSText, 160},
{"reason_for_choice", exercise.ReasonForChoice, 300},
} {
if !validExerciseText(field.value, field.limit) {
return field.name + " is missing or invalid"
}
}
if len(exercise.FocusPoints) < 1 || len(exercise.FocusPoints) > 5 || len(exercise.SuccessCriteria) < 1 || len(exercise.SuccessCriteria) > 5 {
return "focus_points or success_criteria has an invalid count"
}
for _, point := range exercise.FocusPoints {
if !validExerciseText(point, 80) {
return "focus_points contains an invalid value"
}
}
for _, criterion := range exercise.SuccessCriteria {
if !validExerciseText(criterion, 120) {
return "success_criteria contains an invalid value"
}
}
return ""
}
func sameReferenceText(a, b string) bool {
return strings.EqualFold(strings.Join(strings.Fields(a), " "), strings.Join(strings.Fields(b), " "))
}
func validExerciseText(value string, limit int) bool {
return strings.TrimSpace(value) != "" && utf8.RuneCountInString(value) <= limit && strings.IndexFunc(value, unicode.IsControl) == -1
}
func parseGeneratedExerciseEnvelope(body []byte) (domain.GeneratedExercise, bool) {
var envelope map[string]json.RawMessage
if err := json.Unmarshal(body, &envelope); err == nil {
for _, key := range []string{"text", "json", "output"} {
if raw := envelope[key]; len(raw) > 0 && string(raw) != "null" {
if parsed, ok := parseGeneratedExerciseJSON(raw); ok {
return parsed, true
}
}
}
}
@@ -193,22 +260,31 @@ func parseGeneratedExerciseJSON(value json.RawMessage) (domain.GeneratedExercise
}
func mockFeedback(targetText string, result domain.PronunciationResult) domain.TeacherResponse {
weak := "den roten Woertern"
weakWord := ""
for _, word := range result.WordScores {
if word.Highlight == "weak" {
weak = fmt.Sprintf("'%s'", word.Word)
weakWord = word.Word
break
}
}
feedback := fmt.Sprintf("Guter Versuch. Uebe jetzt besonders %s. Sprich langsam und halte die Endlaute klar.", weak)
if result.OverallScore >= 85 {
feedback = "Sehr solide. Wiederhole den Satz einmal etwas natuerlicher und mit ruhigem Rhythmus."
feedback := "Der Satz braucht noch etwas Übung. Sprich ihn noch einmal nach."
nextRecommendation := "Wiederhole diese Übung."
switch {
case result.OverallScore >= 95 && result.AccuracyScore >= 95 && result.FluencyScore >= 95 && result.CompletenessScore >= 95:
feedback = "Ausgezeichnet gesprochen! Die Aussprache dieses Satzes wurde sehr hoch bewertet."
nextRecommendation = "Du kannst mit einer neuen Übung weitermachen."
case weakWord != "":
feedback = fmt.Sprintf("Das Wort %q wurde noch unsicher bewertet. Übe es im Satz noch einmal.", weakWord)
nextRecommendation = fmt.Sprintf("Wiederhole den Satz und achte besonders auf %q.", weakWord)
case result.OverallScore >= 85:
feedback = "Gut gesprochen! Die Aussprache dieses Satzes wurde hoch bewertet."
nextRecommendation = "Du kannst mit einer neuen Übung weitermachen."
}
return domain.TeacherResponse{
ExerciseType: "repeat_sentence",
TargetText: targetText,
TeacherFeedback: feedback,
TTSText: targetText,
NextRecommendation: "Noch einmal sprechen und auf die markierten Woerter achten.",
NextRecommendation: nextRecommendation,
}
}
+180 -4
View File
@@ -7,12 +7,38 @@ import (
"log/slog"
"net/http"
"net/http/httptest"
"strings"
"testing"
"speech-learning-api/internal/config"
"speech-learning-api/internal/domain"
)
func TestFeedbackForPerfectPronunciationRecommendsNextExercise(t *testing.T) {
result := domain.PronunciationResult{
OverallScore: 100, AccuracyScore: 100, FluencyScore: 100, CompletenessScore: 100,
WordScores: []domain.WordScore{{Word: "water", Accuracy: 100, Highlight: "good"}},
}
feedback := mockFeedback("I drink water.", result)
if strings.Contains(feedback.TeacherFeedback, "noch einmal") || strings.Contains(feedback.NextRecommendation, "Wiederhole") {
t.Fatalf("perfect pronunciation should not require repetition: %#v", feedback)
}
if !strings.Contains(feedback.NextRecommendation, "neuen Übung") {
t.Fatalf("expected recommendation to continue: %#v", feedback)
}
}
func TestFeedbackForWeakWordNamesObservedProblem(t *testing.T) {
result := domain.PronunciationResult{
OverallScore: 78,
WordScores: []domain.WordScore{{Word: "water", Accuracy: 61, Highlight: "weak"}},
}
feedback := mockFeedback("I drink water.", result)
if !strings.Contains(feedback.TeacherFeedback, "water") || !strings.Contains(feedback.NextRecommendation, "Wiederhole") {
t.Fatalf("expected focused repetition: %#v", feedback)
}
}
func TestFlowiseNextExerciseSendsSessionAndParsesResponse(t *testing.T) {
var requestBody map[string]json.RawMessage
@@ -25,6 +51,7 @@ func TestFlowiseNextExerciseSendsSessionAndParsesResponse(t *testing.T) {
}
response := domain.GeneratedExercise{
ID: "flowise-controlled-id",
ExerciseType: "repeat_sentence",
TargetLanguage: "en-US",
CEFRLevel: "A1",
@@ -51,10 +78,12 @@ func TestFlowiseNextExerciseSendsSessionAndParsesResponse(t *testing.T) {
}, slog.New(slog.NewTextHandler(io.Discard, nil)))
exercise, err := teacher.NextExercise(context.Background(), domain.GeneratedExerciseRequest{
UserID: "usr_1",
TargetLanguage: "en-US",
CEFRLevel: "A1",
SessionID: "usr_1:en-US:practice",
UserID: "usr_1",
TargetLanguage: "en-US",
CEFRLevel: "A1",
SessionID: "usr_1:en-US:practice",
AvoidReferenceText: "I would like some water.",
AvoidReferenceTexts: []string{"Can I have some water, please?", "I would like some water."},
})
if err != nil {
t.Fatalf("NextExercise: %v", err)
@@ -65,6 +94,9 @@ func TestFlowiseNextExerciseSendsSessionAndParsesResponse(t *testing.T) {
if exercise.Source != "flowise" {
t.Fatalf("unexpected source %q", exercise.Source)
}
if exercise.ID != "" {
t.Fatalf("Flowise must not assign exercise IDs, got %q", exercise.ID)
}
var override struct {
SessionID string `json:"sessionId"`
@@ -90,6 +122,142 @@ func TestFlowiseNextExerciseSendsSessionAndParsesResponse(t *testing.T) {
if question["task"] != "next_exercise" {
t.Fatalf("unexpected task %#v", question["task"])
}
if question["avoid_reference_text"] != "I would like some water." {
t.Fatalf("unexpected avoid_reference_text %#v", question["avoid_reference_text"])
}
if texts, ok := question["avoid_reference_texts"].([]any); !ok || len(texts) != 2 {
t.Fatalf("unexpected avoid_reference_texts %#v", question["avoid_reference_texts"])
}
}
func TestValidGeneratedExerciseRejectsEarlierRecentSentence(t *testing.T) {
exercise := domain.GeneratedExercise{
ExerciseType: "repeat_sentence", TargetLanguage: "en-US", CEFRLevel: "A1",
ReferenceText: "Can I have some water, please?", DisplayPrompt: "Sprich den Satz nach.",
TTSText: "Can I have some water, please?", FocusPoints: []string{"water"},
SuccessCriteria: []string{"Sprich den Satz verständlich nach."}, ReasonForChoice: "Übung mit water.",
}
input := domain.GeneratedExerciseRequest{
TargetLanguage: "en-US", CEFRLevel: "A1",
AvoidReferenceTexts: []string{"Can I have some water, please?", "I would like some water."},
}
if validGeneratedExercise(exercise, input) {
t.Fatal("an earlier recent sentence was accepted")
}
exercise.ReferenceText = "Please pass me the water."
exercise.TTSText = exercise.ReferenceText
if !validGeneratedExercise(exercise, input) {
t.Fatal("a new sentence was rejected")
}
}
func TestFlowiseNextExerciseRetriesRepeatedSentence(t *testing.T) {
calls := 0
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
calls++
var request struct {
Question string `json:"question"`
}
if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
t.Errorf("decode request: %v", err)
return
}
var question map[string]any
if err := json.Unmarshal([]byte(request.Question), &question); err != nil {
t.Errorf("decode question: %v", err)
return
}
if calls == 2 && question["retry_instruction"] == nil {
t.Error("second request lacks retry instruction")
}
reference := "Can I have some water, please?"
if calls == 2 {
reference = "I drink water every day."
}
response := domain.GeneratedExercise{
ExerciseType: "repeat_sentence", TargetLanguage: "en-US", CEFRLevel: "A1",
ReferenceText: reference, DisplayPrompt: "Sprich den Satz nach.", TTSText: reference,
FocusPoints: []string{"water"}, SuccessCriteria: []string{"Sprich den Satz verständlich nach."},
ReasonForChoice: "Übt das Wort water.",
}
_ = json.NewEncoder(w).Encode(response)
}))
defer server.Close()
teacher := NewFlowiseTeacher(config.Config{FlowiseBaseURL: server.URL, FlowiseChatflow: "chatflow-id"}, slog.New(slog.NewTextHandler(io.Discard, nil)))
exercise, err := teacher.NextExercise(context.Background(), domain.GeneratedExerciseRequest{
TargetLanguage: "en-US", CEFRLevel: "A1", AvoidReferenceTexts: []string{"Can I have some water, please?"},
})
if err != nil {
t.Fatalf("NextExercise: %v", err)
}
if calls != 2 || exercise.Source != "flowise" || exercise.ReferenceText != "I drink water every day." {
t.Fatalf("expected a new Flowise sentence after one retry, got calls=%d exercise=%#v", calls, exercise)
}
}
func TestFlowiseNextExerciseRejectsInvalidResponse(t *testing.T) {
valid := domain.GeneratedExercise{
ExerciseType: "repeat_sentence",
TargetLanguage: "en-US",
CEFRLevel: "A1",
ReferenceText: "Can I have water, please?",
DisplayPrompt: "Sprich den Satz nach.",
TTSText: "Can I have water, please?",
FocusPoints: []string{"water"},
SuccessCriteria: []string{"clear final sounds"},
ReasonForChoice: "Practice a weak word.",
}
tests := []struct {
name string
change func(*domain.GeneratedExercise)
}{
{"unsupported type", func(e *domain.GeneratedExercise) { e.ExerciseType = "short_dialogue" }},
{"wrong language", func(e *domain.GeneratedExercise) { e.TargetLanguage = "es-ES" }},
{"wrong level", func(e *domain.GeneratedExercise) { e.CEFRLevel = "B2" }},
{"empty reference", func(e *domain.GeneratedExercise) { e.ReferenceText = "" }},
{"empty prompt", func(e *domain.GeneratedExercise) { e.DisplayPrompt = "" }},
{"control character", func(e *domain.GeneratedExercise) { e.ReferenceText = "Hello\nWorld" }},
{"missing focus", func(e *domain.GeneratedExercise) { e.FocusPoints = nil }},
{"same previous sentence", func(e *domain.GeneratedExercise) { e.ReferenceText = " can I HAVE water, please? " }},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
response := valid
tt.change(&response)
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if err := json.NewEncoder(w).Encode(response); err != nil {
t.Errorf("encode response: %v", err)
}
}))
defer server.Close()
teacher := NewFlowiseTeacher(config.Config{FlowiseBaseURL: server.URL, FlowiseChatflow: "chatflow-id"}, slog.New(slog.NewTextHandler(io.Discard, nil)))
exercise, err := teacher.NextExercise(context.Background(), domain.GeneratedExerciseRequest{TargetLanguage: "en-US", CEFRLevel: "A1", AvoidReferenceText: "Can I have water, please?"})
if err != nil {
t.Fatalf("NextExercise: %v", err)
}
if exercise.Source != "fallback" {
t.Fatalf("invalid response was accepted: %#v", exercise)
}
})
}
}
func TestFlowiseNextExerciseUsesFallbackOnServerError(t *testing.T) {
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusServiceUnavailable)
}))
defer server.Close()
teacher := NewFlowiseTeacher(config.Config{FlowiseBaseURL: server.URL, FlowiseChatflow: "chatflow-id"}, slog.New(slog.NewTextHandler(io.Discard, nil)))
exercise, err := teacher.NextExercise(context.Background(), domain.GeneratedExerciseRequest{TargetLanguage: "en-US", CEFRLevel: "A1"})
if err != nil {
t.Fatalf("NextExercise: %v", err)
}
if exercise.Source != "fallback" {
t.Fatalf("server error did not use fallback: %#v", exercise)
}
}
func TestParseGeneratedExerciseEnvelope(t *testing.T) {
@@ -106,3 +274,11 @@ func TestParseGeneratedExerciseEnvelope(t *testing.T) {
t.Fatalf("unexpected focus points %#v", exercise.FocusPoints)
}
}
func TestParseGeneratedExerciseEnvelopeWithStructuredText(t *testing.T) {
body := []byte(`{"text":{"exercise_type":"repeat_sentence","target_language":"en-US","cefr_level":"A1","reference_text":"Please pass me the water.","display_prompt":"Sprich den Satz nach.","tts_text":"Please pass me the water.","focus_points":["water"],"success_criteria":["Sprich den Satz verständlich nach."],"reason_for_choice":"Übt ein Alltagswort."}}`)
exercise, ok := parseGeneratedExerciseEnvelope(body)
if !ok || exercise.ReferenceText != "Please pass me the water." {
t.Fatalf("structured Flowise text was not parsed: %#v, %v", exercise, ok)
}
}
+32 -31
View File
@@ -83,7 +83,7 @@ func (s *PostgresStore) SaveGeneratedExercise(ctx context.Context, userID string
return domain.Lesson{}, domain.Exercise{}, err
}
exercise := domain.Exercise{
ID: valueOr(generated.ID, NewID("exg")),
ID: NewID("exg"),
LessonID: lesson.ID,
TargetLanguage: targetLanguage,
CEFRLevel: cefrLevel,
@@ -103,21 +103,6 @@ func (s *PostgresStore) SaveGeneratedExercise(ctx context.Context, userID string
success_criteria_json, reason_for_choice, agent_context_json
)
VALUES ($1, $2, $3, $4, $5, $6, $7, $8, 'flowise', $9, $10, $11, $12, $13, $14)
ON CONFLICT (id) DO UPDATE SET
lesson_id = EXCLUDED.lesson_id,
target_language = EXCLUDED.target_language,
cefr_level = EXCLUDED.cefr_level,
type = EXCLUDED.type,
prompt_text = EXCLUDED.prompt_text,
target_text = EXCLUDED.target_text,
difficulty = EXCLUDED.difficulty,
source = EXCLUDED.source,
created_by_user_id = EXCLUDED.created_by_user_id,
tts_text = EXCLUDED.tts_text,
focus_points_json = EXCLUDED.focus_points_json,
success_criteria_json = EXCLUDED.success_criteria_json,
reason_for_choice = EXCLUDED.reason_for_choice,
agent_context_json = EXCLUDED.agent_context_json
RETURNING id, lesson_id, target_language, cefr_level, type, prompt_text, target_text, difficulty, source
`, exercise.ID, exercise.LessonID, exercise.TargetLanguage, exercise.CEFRLevel, exercise.Type,
exercise.PromptText, exercise.TargetText, exercise.Difficulty, userID, generated.TTSText,
@@ -289,7 +274,7 @@ func (s *PostgresStore) GetLanguage(ctx context.Context, code string) (domain.La
return lang, nil
}
func (s *PostgresStore) NextLessonAndExercise(ctx context.Context, profile domain.LearnerProfile) (domain.Lesson, domain.Exercise, error) {
func (s *PostgresStore) NextLessonAndExercise(ctx context.Context, profile domain.LearnerProfile, avoidReferenceText ...string) (domain.Lesson, domain.Exercise, error) {
var lesson domain.Lesson
var exercise domain.Exercise
row := s.db.QueryRowContext(ctx, `
@@ -299,14 +284,18 @@ func (s *PostgresStore) NextLessonAndExercise(ctx context.Context, profile domai
FROM exercises e
JOIN lessons l ON l.id = e.lesson_id
WHERE e.target_language = $1 AND e.cefr_level = $2
AND (COALESCE(e.source, 'seed') = 'seed' OR e.created_by_user_id = $3)
AND COALESCE(e.source, 'seed') = 'seed'
AND NOT EXISTS (
SELECT 1 FROM jsonb_array_elements_text($4::jsonb) AS avoided(sentence)
WHERE lower(trim(avoided.sentence)) = lower(trim(e.target_text))
)
ORDER BY (
SELECT COUNT(*)
FROM attempts a
WHERE a.exercise_id = e.id AND a.user_id = $3
), e.difficulty, e.id
LIMIT 1
`, profile.TargetLanguage, profile.CEFRLevel, profile.UserID)
`, profile.TargetLanguage, profile.CEFRLevel, profile.UserID, mustJSON(avoidReferenceText))
if err := row.Scan(
&lesson.ID, &lesson.TargetLanguage, &lesson.CEFRLevel, &lesson.Topic, &lesson.Title,
&exercise.ID, &exercise.LessonID, &exercise.TargetLanguage, &exercise.CEFRLevel, &exercise.Type,
@@ -320,13 +309,13 @@ func (s *PostgresStore) NextLessonAndExercise(ctx context.Context, profile domai
return lesson, exercise, nil
}
func (s *PostgresStore) GetExercise(ctx context.Context, id string) (domain.Exercise, error) {
func (s *PostgresStore) GetExercise(ctx context.Context, id, userID string) (domain.Exercise, error) {
var e domain.Exercise
row := s.db.QueryRowContext(ctx, `
SELECT id, lesson_id, target_language, cefr_level, type, prompt_text, target_text, difficulty, COALESCE(source, 'seed')
FROM exercises
WHERE id = $1
`, id)
WHERE id = $1 AND (COALESCE(source, 'seed') = 'seed' OR created_by_user_id = $2)
`, id, userID)
if err := row.Scan(&e.ID, &e.LessonID, &e.TargetLanguage, &e.CEFRLevel, &e.Type, &e.PromptText, &e.TargetText, &e.Difficulty, &e.Source); err != nil {
if errors.Is(err, sql.ErrNoRows) {
return domain.Exercise{}, ErrNotFound
@@ -393,26 +382,38 @@ func (s *PostgresStore) Progress(ctx context.Context, userID string, limit int)
}
defer rows.Close()
weakByWord := map[string]domain.WordScore{}
for rows.Next() {
attempt, err := scanAttempt(rows)
if err != nil {
return domain.ProgressSummary{}, err
}
summary.RecentAttempts = append(summary.RecentAttempts, attempt)
}
if err := rows.Err(); err != nil {
return domain.ProgressSummary{}, err
}
summary.WeakWords = latestWeakWords(summary.RecentAttempts)
return summary, nil
}
// RecentAttempts are ordered newest first. A newer successful score clears an
// older weak score for the same word within the progress window.
func latestWeakWords(attempts []domain.Attempt) []domain.WordScore {
seen := make(map[string]bool)
var weak []domain.WordScore
for _, attempt := range attempts {
for _, word := range attempt.WordScores {
key := strings.ToLower(strings.TrimSpace(word.Word))
if key == "" || seen[key] {
continue
}
seen[key] = true
if word.Accuracy < 75 {
existing, ok := weakByWord[strings.ToLower(word.Word)]
if !ok || word.Accuracy < existing.Accuracy {
weakByWord[strings.ToLower(word.Word)] = word
}
weak = append(weak, word)
}
}
}
for _, word := range weakByWord {
summary.WeakWords = append(summary.WeakWords, word)
}
return summary, rows.Err()
return weak
}
func (s *PostgresStore) CreateConversationSession(ctx context.Context, userID, targetLanguage, cefrLevel string) (domain.ConversationSession, error) {
+25
View File
@@ -0,0 +1,25 @@
package store
import (
"testing"
"speech-learning-api/internal/domain"
)
func TestLatestWeakWordsUsesNewestScorePerWord(t *testing.T) {
attempts := []domain.Attempt{
{WordScores: []domain.WordScore{
{Word: "Water", Accuracy: 100},
{Word: "coffee", Accuracy: 60},
}},
{WordScores: []domain.WordScore{
{Word: "water", Accuracy: 61},
{Word: "Coffee", Accuracy: 90},
{Word: "please", Accuracy: 68},
}},
}
weak := latestWeakWords(attempts)
if len(weak) != 2 || weak[0].Word != "coffee" || weak[1].Word != "please" {
t.Fatalf("latest scores should clear water and keep coffee/please weak, got %#v", weak)
}
}
+21 -3
View File
@@ -1,17 +1,35 @@
import { request } from './client';
import type { Dashboard, Exercise, Lesson, ProgressSummary } from './types';
let pendingDashboardRequest: Promise<Dashboard> | null = null;
export function fetchDashboard() {
return request<Dashboard>('/dashboard');
if (!pendingDashboardRequest) {
pendingDashboardRequest = request<Dashboard>('/dashboard').finally(() => {
pendingDashboardRequest = null;
});
}
return pendingDashboardRequest;
}
export function fetchProgress() {
return request<ProgressSummary>('/progress');
}
export function fetchNextLesson() {
export async function fetchNextLesson(fresh = false, recentExerciseIds: string[] = []) {
if (!fresh && pendingDashboardRequest) {
try {
const dashboard = await pendingDashboardRequest;
return { lesson: dashboard.next_lesson, exercise: dashboard.next_exercise };
} catch {
// A failed dashboard request should not prevent a direct practice request.
}
}
return request<{ lesson: Lesson; exercise: Exercise }>('/lessons/next', {
method: 'POST',
body: JSON.stringify({})
body: JSON.stringify(recentExerciseIds.length ? {
previous_exercise_id: recentExerciseIds[recentExerciseIds.length - 1],
recent_exercise_ids: recentExerciseIds
} : {})
});
}
+14 -2
View File
@@ -2,6 +2,7 @@ import { BookOpen, Bug, ChartNoAxesColumnIncreasing, LogOut, Mic, MessageCircle
import { useEffect, useState } from 'react';
import { clearToken, getToken } from '../api/client';
import { fetchDebugStatus } from '../api/debug';
import type { Exercise, Lesson } from '../api/types';
import { DashboardPage } from '../pages/DashboardPage';
import { LoginPage } from '../pages/LoginPage';
import { RegisterPage } from '../pages/RegisterPage';
@@ -14,6 +15,7 @@ import { useHashRoute } from './useHashRoute';
export function App() {
const [route, setRoute] = useHashRoute(getToken() ? 'dashboard' : 'login');
const [debugAvailable, setDebugAvailable] = useState(false);
const [practiceSelection, setPracticeSelection] = useState<{ lesson: Lesson; exercise: Exercise } | null>(null);
const authed = Boolean(getToken());
useEffect(() => {
@@ -34,15 +36,25 @@ export function App() {
};
}, [authed]);
useEffect(() => {
if (route !== 'practice') setPracticeSelection(null);
}, [route]);
function handleAuthed() {
setRoute('dashboard');
}
function logout() {
clearToken();
setPracticeSelection(null);
setRoute('login');
}
function openDashboardExercise(lesson: Lesson, exercise: Exercise) {
setPracticeSelection({ lesson, exercise });
setRoute('practice');
}
if (!authed) {
return (
<main className="auth-shell">
@@ -92,8 +104,8 @@ export function App() {
</aside>
<main className="main-view">
{route === 'dashboard' && <DashboardPage onPractice={() => setRoute('practice')} />}
{route === 'practice' && <PracticePage />}
{route === 'dashboard' && <DashboardPage onLoaded={(lesson, exercise) => setPracticeSelection({ lesson, exercise })} onPractice={openDashboardExercise} />}
{route === 'practice' && <PracticePage initialSelection={practiceSelection} />}
{route === 'conversation' && <ConversationPage />}
{route === 'progress' && <ProgressPage />}
{route === 'debug' && <DebugPage />}
+16 -5
View File
@@ -1,18 +1,29 @@
import { ArrowRight, Clock, Gauge } from 'lucide-react';
import { useEffect, useState } from 'react';
import { fetchDashboard } from '../api/lessons';
import type { Dashboard } from '../api/types';
import type { Dashboard, Exercise, Lesson } from '../api/types';
type Props = {
onPractice: () => void;
onPractice: (lesson: Lesson, exercise: Exercise) => void;
onLoaded: (lesson: Lesson, exercise: Exercise) => void;
};
export function DashboardPage({ onPractice }: Props) {
export function DashboardPage({ onPractice, onLoaded }: Props) {
const [dashboard, setDashboard] = useState<Dashboard | null>(null);
const [error, setError] = useState('');
useEffect(() => {
fetchDashboard().then(setDashboard).catch((err) => setError(err instanceof Error ? err.message : 'Dashboard konnte nicht geladen werden'));
let cancelled = false;
fetchDashboard()
.then((data) => {
if (cancelled) return;
setDashboard(data);
onLoaded(data.next_lesson, data.next_exercise);
})
.catch((err) => {
if (!cancelled) setError(err instanceof Error ? err.message : 'Dashboard konnte nicht geladen werden');
});
return () => { cancelled = true; };
}, []);
if (error) return <p className="form-error">{error}</p>;
@@ -25,7 +36,7 @@ export function DashboardPage({ onPractice }: Props) {
<p className="eyebrow">Heute</p>
<h1>A1 Aussprachetraining</h1>
</div>
<button className="primary-button" onClick={onPractice}>
<button className="primary-button" onClick={() => onPractice(dashboard.next_lesson, dashboard.next_exercise)}>
<ArrowRight size={18} /> Naechste Uebung
</button>
</header>
+40 -13
View File
@@ -1,5 +1,5 @@
import { RotateCcw, Send } from 'lucide-react';
import { useEffect, useState } from 'react';
import { useEffect, useRef, useState } from 'react';
import { fetchNextLesson } from '../api/lessons';
import { submitAttempt } from '../api/practice';
import type { AttemptResponse, Exercise, Lesson } from '../api/types';
@@ -7,28 +7,46 @@ import { AudioRecorder } from '../components/AudioRecorder';
import { PronunciationText } from '../components/PronunciationText';
import { ScoreBadge } from '../components/ScoreBadge';
export function PracticePage() {
const [lesson, setLesson] = useState<Lesson | null>(null);
const [exercise, setExercise] = useState<Exercise | null>(null);
type Props = {
initialSelection?: { lesson: Lesson; exercise: Exercise } | null;
};
export function PracticePage({ initialSelection }: Props) {
const [lesson, setLesson] = useState<Lesson | null>(initialSelection?.lesson ?? null);
const [exercise, setExercise] = useState<Exercise | null>(initialSelection?.exercise ?? null);
const [audio, setAudio] = useState<Blob | null>(null);
const [result, setResult] = useState<AttemptResponse | null>(null);
const [loading, setLoading] = useState(false);
const [loadingNext, setLoadingNext] = useState(false);
const [error, setError] = useState('');
const [notice, setNotice] = useState('');
const recentExerciseIds = useRef<string[]>(initialSelection?.exercise.id ? [initialSelection.exercise.id] : []);
useEffect(() => {
loadNext();
if (!initialSelection) void loadNext();
}, []);
async function loadNext() {
async function loadNext(fresh = false) {
if (loadingNext) return;
setLoadingNext(true);
setError('');
setNotice('');
setAudio(null);
setResult(null);
try {
const next = await fetchNextLesson();
const next = await fetchNextLesson(fresh, fresh ? recentExerciseIds.current : []);
if (fresh && exercise?.target_text.trim().toLowerCase() === next.exercise.target_text.trim().toLowerCase()) {
setNotice('Der Agent hat denselben Satz erneut erzeugt. Bitte versuche es noch einmal.');
}
setLesson(next.lesson);
setExercise(next.exercise);
if (next.exercise.id && recentExerciseIds.current[recentExerciseIds.current.length - 1] !== next.exercise.id) {
recentExerciseIds.current = [...recentExerciseIds.current, next.exercise.id].slice(-3);
}
} catch (err) {
setError(err instanceof Error ? err.message : 'Uebung konnte nicht geladen werden');
} finally {
setLoadingNext(false);
}
}
@@ -45,8 +63,14 @@ export function PracticePage() {
}
}
if (error) return <p className="form-error">{error}</p>;
if (!lesson || !exercise) return <p className="muted">Lade Uebung...</p>;
if (!lesson || !exercise) {
return (
<div className="view-stack">
<p className={error ? 'form-error' : 'muted'}>{error || 'Lade Uebung...'}</p>
{error && <button className="ghost-button" disabled={loadingNext} onClick={() => void loadNext(true)}>Erneut versuchen</button>}
</div>
);
}
return (
<div className="view-stack">
@@ -55,17 +79,20 @@ export function PracticePage() {
<p className="eyebrow">{lesson.title}</p>
<h1>Aussprache</h1>
</div>
<button className="ghost-button" onClick={loadNext}>
<RotateCcw size={18} /> Andere Uebung
<button className="ghost-button" disabled={loadingNext || loading} onClick={() => void loadNext(true)}>
<RotateCcw size={18} /> {loadingNext ? 'Lade neue Uebung...' : 'Andere Uebung'}
</button>
</header>
{error && <p className="form-error">{error}</p>}
{notice && <p className="muted">{notice}</p>}
<section className="panel practice-panel">
<p className="muted">{exercise.prompt_text}</p>
<PronunciationText targetText={exercise.target_text} words={result?.attempt.word_scores} />
<div className="action-row">
<AudioRecorder onRecorded={setAudio} disabled={loading} />
<button className="primary-button" disabled={!audio || loading} onClick={submit}>
<AudioRecorder onRecorded={setAudio} disabled={loading || loadingNext} />
<button className="primary-button" disabled={!audio || loading || loadingNext} onClick={submit}>
<Send size={18} /> Bewerten
</button>
</div>