Favorite Words & Learn Scope Contract

Purpose

• Chốt logic Yêu thích cho Từ vựng.
• Giải quyết nhu cầu user muốn tự chọn một nhóm từ để quay lại nhanh mà không phá queue SRS mặc định.
• Giữ đúng nguyên tắc: chỉ có một flow LEARN.

Problem

• User đôi khi muốn học ngay một số từ cụ thể trong list hiện tại.
• Canon hiện có review queue, mistakes queue, My Lists, nhưng chưa có contract rõ cho user-curated subset ở cấp item.

Product Decision

• Dùng Yêu thích như một personal signal ở cấp item.
• Yêu thích là lớp additive: thêm khả năng lọc/học theo ý user, không loại item khỏi queue hệ thống.
• LEARN không tách thành flow riêng; session chỉ thay đổi candidate pool.

Canonical Semantics

• favorite word = item user muốn lưu tâm, quay lại, hoặc học riêng trong phạm vi Từ vựng.
• favorite word không đồng nghĩa với:
  • mastered
  • urgent review
  • hidden
  • skip
• favorite word không làm thay đổi F, D, successCount, failCount, hay next_review_at.
• favorite word không loại item khỏi Today Focus, review queue, hay mistakes queue.

Owner Surfaces

• Owner action: list detail trong Từ vựng.
• Owner launch: session launcher / Start Learning bên trong Từ vựng.
• Allowed surfacing:
  • filter Từ yêu thích
  • CTA Học từ yêu thích
  • hint trong AI Tutor hoặc practice surfaces nếu có giá trị rõ
• Không thuộc scope v1:
  • social/public favorites
  • cross-app favorite sync
  • điểm thưởng riêng cho favorite words

Learn Contract (Single Flow)

• Vẫn dùng duy nhất flow LEARN.
• Khi user bấm Học từ yêu thích, input session là:
  • scope = current list/set
  • favorite_only = true
• candidate pool = scope hiện tại ∩ favorite=true.
• Engine vẫn giữ quyền sắp item trong pool theo tier, stage, difficulty, skill profile, và repair logic hiện hành.
• Không auto thêm non-favorite items chỉ để đủ batch size.
• Nếu favorite pool chỉ có 1-2 item, session vẫn hợp lệ:
  • không chặn start
  • không tách flow mới
  • planner tiếp tục dùng logic LEARN thường với exercise rotation phù hợp stage hiện tại của các item đó
  • batch/buffer/preload degrade gracefully theo pool thực tế
• Nếu favorite pool = 0, CTA phải disabled hoặc fallback rõ về Ôn theo hệ thống.

Guardrails

• Không dùng Yêu thích như cách nói đã biết nên loại khỏi học.
• Không dùng favorite=false như rule xoá item khỏi queue.
• Không tạo credit/SRS formula riêng cho item được đánh dấu Yêu thích.
• Nếu user chỉ học vài favorite words, recap có thể gợi ý quay lại Ôn theo hệ thống, nhưng không tự chèn thêm item ngoài pool.

v1 UX Baseline

• Trên từng từ trong list detail: icon sao Yêu thích.
• Filter/tab: Từ yêu thích.
• CTA launcher: Học từ yêu thích.
• Empty state: Chưa có từ yêu thích nào trong danh sách này.

References

• ./VOC_00_Overview.md
• ./Vocab v2/VOCV2_00_Overview.md
• ./Vocab v2/Core Logic/VOCV2_Product_Spec_Hardening_v1.md
• ./Archive/ARCHIVE_Hidden_Item_Feature.md

Change log

• 2026-03-27: Tạo contract canon cho Yêu thích như signal additive và chốt single-flow LEARN khi học theo favorite words.