feat(vocab): implement SRS features and enhance vocabulary management

- Added new endpoints in vocabController for retrieving SRS due items and reviewing SRS items, improving spaced repetition support.
- Updated vocabService to handle SRS item creation and scheduling, ensuring effective tracking of vocabulary exposure.
- Enhanced vocabRouter with new routes for SRS functionalities, facilitating user interaction with spaced repetition features.
- Modified VocabPracticeDialog and VocabCourseView to integrate SRS due items, providing users with timely review opportunities.
- Updated translations and UI elements to reflect new SRS features, enhancing user experience and accessibility.

backend/services/vocabService.js

@@ -7,6 +7,7 @@ import VocabCourseProgress from '../models/community/vocab_course_progress.js';
 import VocabGrammarExerciseType from '../models/community/vocab_grammar_exercise_type.js';
 import VocabGrammarExercise from '../models/community/vocab_grammar_exercise.js';
 import VocabGrammarExerciseProgress from '../models/community/vocab_grammar_exercise_progress.js';
+import VocabSrsItem from '../models/community/vocab_srs_item.js';
 import UserParamType from '../models/type/user_param.js';
 import UserParam from '../models/community/user_param.js';
 import { sequelize } from '../utils/sequelize.js';
@@ -15,6 +16,144 @@ import { Op } from 'sequelize';
 import { BISAYA_PHASE1_DIDACTICS, BISAYA_DIDACTICS_FRAGMENTS } from '../scripts/bisaya-course-phase1.js';
 
 export default class VocabService {
+  _normalizeSrsText(value) {
+    return String(value || '')
+      .trim()
+      .toLowerCase()
+      .normalize('NFKC')
+      .replace(/[\p{P}\p{S}]+/gu, ' ')
+      .replace(/\s+/g, ' ')
+      .trim();
+  }
+
+  _buildSrsItemKey({ courseId, lessonId = null, learning, reference, direction = 'BOTH' }) {
+    const raw = [
+      Number(courseId) || 0,
+      lessonId == null ? 'course' : Number(lessonId) || 0,
+      String(direction || 'BOTH').toUpperCase(),
+      this._normalizeSrsText(learning),
+      this._normalizeSrsText(reference)
+    ].join('|');
+    return crypto.createHash('sha1').update(raw).digest('hex');
+  }
+
+  _decorateSrsVocabs(vocabs = [], { courseId, lessonId = null } = {}) {
+    return (Array.isArray(vocabs) ? vocabs : [])
+      .map((entry) => {
+        const learning = String(entry?.learning || '').trim();
+        const reference = String(entry?.reference || '').trim();
+        if (!learning || !reference || this._normalizeSrsText(learning) === this._normalizeSrsText(reference)) {
+          return null;
+        }
+        const direction = String(entry?.direction || 'BOTH').toUpperCase();
+        const itemKey = this._buildSrsItemKey({ courseId, lessonId, learning, reference, direction });
+        return {
+          ...entry,
+          id: entry?.id || itemKey,
+          itemKey,
+          courseId: Number(courseId) || null,
+          lessonId: lessonId == null ? null : Number(lessonId),
+          learning,
+          reference,
+          direction
+        };
+      })
+      .filter(Boolean);
+  }
+
+  _calculateSrsSchedule(item, { correct, rating = null } = {}) {
+    const now = new Date();
+    const previousStage = Math.max(0, Number(item?.stage) || 0);
+    const previousInterval = Math.max(0, Number(item?.intervalDays) || 0);
+    const normalizedRating = String(rating || '').toLowerCase();
+    const isCorrect = Boolean(correct) && normalizedRating !== 'again';
+
+    if (!isCorrect) {
+      return {
+        stage: Math.max(0, previousStage - 1),
+        intervalDays: 0,
+        nextDueAt: new Date(now.getTime() + 10 * 60 * 1000),
+        lapseDelta: 1
+      };
+    }
+
+    const intervals = [0, 1, 3, 7, 14, 30, 60, 120, 240];
+    let nextStage = Math.min(intervals.length - 1, previousStage + 1);
+
+    if (normalizedRating === 'hard') {
+      nextStage = Math.max(1, previousStage);
+    }
+    if (normalizedRating === 'easy') {
+      nextStage = Math.min(intervals.length - 1, previousStage + 2);
+    }
+
+    let intervalDays = intervals[nextStage] ?? Math.max(1, previousInterval * 2);
+    if (normalizedRating === 'hard') {
+      intervalDays = Math.max(1, Math.ceil(Math.max(previousInterval, 1) * 1.2));
+    }
+
+    return {
+      stage: nextStage,
+      intervalDays,
+      nextDueAt: new Date(now.getTime() + intervalDays * 24 * 60 * 60 * 1000),
+      lapseDelta: 0
+    };
+  }
+
+  async _ensureSrsItems(userId, { courseId, lessonId = null, vocabs = [] } = {}) {
+    const decorated = this._decorateSrsVocabs(vocabs, { courseId, lessonId });
+    if (!decorated.length) {
+      return [];
+    }
+
+    const existing = await VocabSrsItem.findAll({
+      where: {
+        userId,
+        itemKey: {
+          [Op.in]: decorated.map((entry) => entry.itemKey)
+        }
+      }
+    });
+    const existingByKey = new Map(existing.map((entry) => [entry.itemKey, entry]));
+    const now = new Date();
+
+    const createdItems = [];
+    for (const entry of decorated) {
+      if (existingByKey.has(entry.itemKey)) {
+        continue;
+      }
+      const created = await VocabSrsItem.create({
+        userId,
+        courseId: Number(courseId),
+        lessonId: entry.lessonId,
+        itemKey: entry.itemKey,
+        learning: entry.learning,
+        reference: entry.reference,
+        direction: entry.direction,
+        nextDueAt: now
+      });
+      createdItems.push(created);
+      existingByKey.set(entry.itemKey, created);
+    }
+
+    return decorated.map((entry) => {
+      const item = existingByKey.get(entry.itemKey);
+      return {
+        ...entry,
+        srs: item ? {
+          stage: item.stage,
+          intervalDays: item.intervalDays,
+          lastReviewedAt: this._normalizeIsoDate(item.lastReviewedAt),
+          nextDueAt: this._normalizeIsoDate(item.nextDueAt),
+          correctCount: item.correctCount,
+          wrongCount: item.wrongCount,
+          lapseCount: item.lapseCount,
+          isNew: createdItems.some((created) => created.itemKey === entry.itemKey)
+        } : null
+      };
+    });
+  }
+
   _normalizeIsoDate(value) {
     if (!value) {
       return '';
@@ -1502,6 +1641,11 @@ export default class VocabService {
       if (!entry?.learning || !entry?.reference) return;
       mergedVocabs.set(`${entry.learning}-${entry.reference}`, entry);
     });
+    const vocabs = await this._ensureSrsItems(user.id, {
+      courseId: lesson.courseId,
+      lessonId: lesson.id,
+      vocabs: Array.from(mergedVocabs.values())
+    });
 
     return {
       lesson: {
@@ -1510,7 +1654,7 @@ export default class VocabService {
         courseId: lesson.courseId,
         courseTitle: lesson.course.title
       },
-      vocabs: Array.from(mergedVocabs.values())
+      vocabs
     };
   }
 
@@ -1612,9 +1756,167 @@ export default class VocabService {
       mergedVocabs.set(`${entry.learning}-${entry.reference}`, entry);
     });
 
+    const vocabs = await this._ensureSrsItems(user.id, {
+      courseId: course.id,
+      lessonId: null,
+      vocabs: Array.from(mergedVocabs.values())
+    });
+
     return {
       courseId: course.id,
-      vocabs: Array.from(mergedVocabs.values())
+      vocabs
+    };
+  }
+
+  async getCourseSrsDue(hashedUserId, courseId, query = {}) {
+    const user = await this._getUserByHashedId(hashedUserId);
+    const course = await VocabCourse.findByPk(courseId);
+
+    if (!course) {
+      const err = new Error('Course not found');
+      err.status = 404;
+      throw err;
+    }
+
+    if (course.ownerUserId !== user.id && !course.isPublic) {
+      const err = new Error('Access denied');
+      err.status = 403;
+      throw err;
+    }
+
+    const limit = this._clampInteger(query?.limit, { min: 1, max: 100, fallback: 30 });
+    const now = new Date();
+    const rows = await VocabSrsItem.findAll({
+      where: {
+        userId: user.id,
+        courseId: Number(course.id),
+        nextDueAt: {
+          [Op.lte]: now
+        }
+      },
+      order: [
+        ['nextDueAt', 'ASC'],
+        ['wrongCount', 'DESC'],
+        ['stage', 'ASC']
+      ],
+      limit
+    });
+
+    return {
+      courseId: course.id,
+      dueAt: now.toISOString(),
+      count: rows.length,
+      items: rows.map((item) => ({
+        itemKey: item.itemKey,
+        courseId: item.courseId,
+        lessonId: item.lessonId,
+        learning: item.learning,
+        reference: item.reference,
+        direction: item.direction,
+        stage: item.stage,
+        intervalDays: item.intervalDays,
+        lastReviewedAt: this._normalizeIsoDate(item.lastReviewedAt),
+        nextDueAt: this._normalizeIsoDate(item.nextDueAt),
+        correctCount: item.correctCount,
+        wrongCount: item.wrongCount,
+        lapseCount: item.lapseCount
+      }))
+    };
+  }
+
+  async reviewSrsItem(hashedUserId, payload = {}) {
+    const user = await this._getUserByHashedId(hashedUserId);
+    const courseId = this._clampInteger(payload?.courseId, { min: 1, max: 1_000_000, fallback: 0 });
+    if (!courseId) {
+      const err = new Error('Missing course id');
+      err.status = 400;
+      throw err;
+    }
+
+    const course = await VocabCourse.findByPk(courseId);
+    if (!course) {
+      const err = new Error('Course not found');
+      err.status = 404;
+      throw err;
+    }
+    if (course.ownerUserId !== user.id && !course.isPublic) {
+      const err = new Error('Access denied');
+      err.status = 403;
+      throw err;
+    }
+
+    const learning = this._sanitizeShortString(payload?.learning, 1200);
+    const reference = this._sanitizeShortString(payload?.reference, 1200);
+    if (!learning || !reference) {
+      const err = new Error('Missing SRS item text');
+      err.status = 400;
+      throw err;
+    }
+
+    const lessonId = payload?.lessonId == null
+      ? null
+      : this._clampInteger(payload.lessonId, { min: 1, max: 1_000_000, fallback: 0 }) || null;
+    const direction = String(payload?.direction || 'BOTH').toUpperCase().slice(0, 8);
+    const itemKey = this._sanitizeShortString(payload?.itemKey, 80)
+      || this._buildSrsItemKey({ courseId, lessonId, learning, reference, direction });
+
+    const [item] = await VocabSrsItem.findOrCreate({
+      where: {
+        userId: user.id,
+        itemKey
+      },
+      defaults: {
+        userId: user.id,
+        courseId,
+        lessonId,
+        itemKey,
+        learning,
+        reference,
+        direction,
+        nextDueAt: new Date()
+      }
+    });
+
+    if (
+      item.learning !== learning ||
+      item.reference !== reference ||
+      item.direction !== direction ||
+      item.lessonId !== lessonId
+    ) {
+      item.learning = learning;
+      item.reference = reference;
+      item.direction = direction;
+      item.lessonId = lessonId;
+    }
+
+    const correct = Boolean(payload?.correct);
+    const schedule = this._calculateSrsSchedule(item, {
+      correct,
+      rating: payload?.rating
+    });
+
+    item.stage = schedule.stage;
+    item.intervalDays = schedule.intervalDays;
+    item.lastReviewedAt = new Date();
+    item.nextDueAt = schedule.nextDueAt;
+    if (correct) {
+      item.correctCount += 1;
+    } else {
+      item.wrongCount += 1;
+      item.lapseCount += schedule.lapseDelta;
+    }
+    await item.save();
+
+    return {
+      itemKey: item.itemKey,
+      correct,
+      stage: item.stage,
+      intervalDays: item.intervalDays,
+      lastReviewedAt: this._normalizeIsoDate(item.lastReviewedAt),
+      nextDueAt: this._normalizeIsoDate(item.nextDueAt),
+      correctCount: item.correctCount,
+      wrongCount: item.wrongCount,
+      lapseCount: item.lapseCount
     };
   }