VOCSet – Progress & Word State Logic

Word State Model

• unknown: chưa tương tác; default khi nhập set mới.
• aware (Biết dần): người học đã xem định nghĩa/flashcard ít nhất một lần.
• memorized (Ghi nhớ): trả lời đúng ≥2 lần trong quick practice/matching hoặc đánh dấu “Nhớ rồi”.
• mastered (Thành thạo): đạt tiêu chí quiz mastery (≥80% đúng hoặc chuỗi 5 câu đúng liên tiếp).
• regressed: (optional) trạng thái tạm khi người học sai nhiều → dùng để ưu tiên ôn lại.

Mỗi trạng thái lưu lastReviewedAt, correctStreak, incorrectStreak và activitySource.

Progress Summary Tiles

• Tính toán realtime từ WordState.
• Hover tooltip giải thích tiêu chí.
• CTA “Ôn nhanh” → mở quick practice với bộ từ thuộc state đó.
• Khi mastered ≥80% → hiển thị badge “Sẵn sàng kiểm tra”.

State Transition Rules (đề xuất)

From	Trigger	To	Ghi chú
unknown	Xem flashcard hoặc mở chi tiết từ	aware	Cần hành động có chủ đích, không auto khi lướt.
aware	Trả lời đúng 2 lần liên tiếp (quick practice/matching) hoặc mark “Nhớ rồi”	memorized	Lưu correctStreak.
aware	Sai 3 lần liên tiếp	unknown	Nhắc người học quay lại Study Mode.
memorized	Quiz mastery đạt ≥80% và không sai từ đó	mastered	Áp dụng cho từng từ.
memorized	Sai trong quiz ≥2 lần liên tiếp	aware	Giảm 1 bậc, ghi log.
mastered	Không ôn >X ngày hoặc sai quiz	memorized	X ngày cấu hình (default 21).

Spaced Repetition

• Cron job (client) kiểm tra mỗi lần mở module:
  • Nếu mastered nhưng lastReviewedAt > 21 ngày → highlight trong danh sách “Cần ôn”.
  • Gợi ý quick practice “Ôn lại từ cũ”.

Dataset & Persistence

• WordState lưu cục bộ (localStorage) trước, đồng bộ server khi API sẵn.
• Custom deck & activity progress cũng lưu theo moduleId.
• Khi logout (xóa session) → giữ WordState? (đề xuất: giữ để tránh mất dữ liệu, tách khỏi session).

UX Feedback

• Khi chuyển state → toast mini “account ➜ Ghi nhớ”.
• Trong word card: badge màu và icon thay đổi ngay.
• Progress summary animate increment.

Risks & Mitigation

• Downgrade quá nhanh → đặt ngưỡng sai hợp lý, show explanation popover.
• Mastered ảo (do chỉ đánh dấu) → quiz mastery bắt buộc cho state final.
• Không đồng bộ → hiển thị trạng thái loading khi sync (future API).