UI Logic Mapping - Recommendation Engine (Cơ chế gợi ý)

Hardening Note (SoT precedence): Tài liệu này tuân theo ../Core Logic/VOCV2_Product_Spec_Hardening_v1.md. Nếu có mâu thuẫn, ưu tiên SoT hardening.

Component 1: “Start Session” Button (Nút Vào học)

1. Mục đích & Ý nghĩa (Why?)

Nút này trả lời câu hỏi: “Hôm nay tôi nên học cái gì?”. User không cần tự lục lọi danh sách 1000 từ. Hệ thống tự động chọn ra các item quan trọng nhất theo micro-batch 5 để xử lý ngay lúc này.

2. Logic Quyết định (Decision Logic)

Khi user bấm nút, Backend chạy thuật toán Priority Queue để bốc bài. Quy tắc như sau:

A. Ai được ưu tiên? (The Hierarchy)

Hệ thống quét toàn bộ kho từ của user và sắp xếp theo thứ tự “Cấp cứu”:

1. Top 1: Sắp chết (Critical Urgent): Những từ đã thuộc rồi nhưng đang bị lãng quên dưới ngưỡng an toàn (F < Threshold).
   • Tại sao: Cứu cây sắp chết quan trọng hơn gieo hạt mới.
2. Top 2: Đang học dở (Learning): Những từ mới học hôm qua (Mầm cây), cần củng cố để rễ bám sâu.
3. Top 3: Từ mới (New Items): Chỉ khi đã cứu hết các ca cấp cứu, hệ thống mới lấy thêm hạt giống mới để gieo.

B. Quy tắc trộn (Debt-aware Mixing)

Session trộn theo 3 trạng thái:

• State A - Hard Debt: Nếu debt_total >= 20 -> 100% review.
• State B - Soft Emergency: Nếu Tier #1 chiếm >50% batch -> 4 review + 1 new.
• State C - Stable: Target 30% new / 70% review, biểu diễn bằng mix cycle 10 item:
  • Batch lẻ: 3 review + 2 new
  • Batch chẵn: 4 review + 1 new

3. Data Requirements (Input cho nút Start)

• User ID: Để query DB.
• Current Session Config: Timer mode, scope, và preload (web=10, mobile=5).

---

Component 2: Next Exercise (Bài tập tiếp theo)

1. Mục đích & Ý nghĩa (Why?)

Sau khi chọn được TỪ (VD: “Apple”), hệ thống cần chọn DỤNG CỤ (Dạng bài tập) để kiểm tra. Mục tiêu: “Đúng người, đúng việc”.

2. Logic Chọn Bài (Selection Logic)

A. Skill Matching (Đúng kỹ năng)

Mỗi từ vựng có một “Skill Tag” chính. Bài tập phải phục vụ Tag đó.

• Từ “Intonation” (Skill: Speaking) -> Ưu tiên: Bài tập Mic thu âm (Speaking Drill).
• Từ “Vocabulary” (Skill: Writing) -> Ưu tiên: Bài tập Gõ phím (Typing).
• Lý do: Không bắt con cá leo cây. Kỹ năng nào rèn công cụ đó.

B. Difficulty Scaling (Đúng trình độ)

Độ khó bài tập đi thẳng theo level của từ (max_stage):

• Level 0: 100/0/0
• Level 1: 90/10/0
• Level 2: 75/25/0
• Level 3: 45/40/15
• Level 4: 25/45/30
• Level 5: 15/35/50
• Safety override: nếu failCount>=1 hoặc F_now=0 thì force EASY trong 2 touches.
• Lý do: dễ hiểu, dễ QA, vẫn có cơ chế cứu khi user sai.

C. Skill Distribution (Đúng trọng tâm kỹ năng)

Skill ratio hoạt động theo skill profile độc lập với Difficulty:

• CORE: 75/20/5
• NEW_RAMP: 90/10/0
• URGENT_REPAIR: 95/5/0
• MASTERY_EXPAND: 60/25/15
• Rule khẩn cấp: Tier 1/2 giới hạn Cross <= 10%.
• Writing catalog hiện tại là HARD-only:
  • Level 0-2: ưu tiên Reading/Speaking/Listening EASY-MEDIUM làm lớp đệm.
  • Level 3+: tăng dần tỷ lệ Writing HARD để quay lại đúng kỹ năng đích.
• Availability guarantee:
  • Nếu bucket không có bài: fallback theo ladder PRIMARY -> ADJACENT -> CROSS -> difficulty gần nhất an toàn -> Learning Card.
  • Giữ primary floor theo cửa sổ 10 lượt để tránh lệch skill (đặc biệt với Writing ở level thấp).

Lưu ý kiến trúc: Skill profile không phụ thuộc trực tiếp vào difficulty ratio. Hai nhánh chỉ liên hệ gián tiếp vì Skill Controller chọn trên candidate pool đã qua difficulty filter.

3. Data Requirements

• item_skill: (speaking, reading…)
• difficulty_level: (max_stage 0..5)
• skill_profile: (core/new_ramp/urgent_repair/mastery_expand)
• exercise_pool: Danh sách các template bài tập khả dụng.
• window_history: lịch sử hiển thị để tính ratio deficits.

---

4. Tài liệu References (Source of Truth)

• Về Thứ tự Ưu tiên (Priority Queue): Xem VOCV2_Item_Prioritization_Logic.md (Mục 3).
• Về Luật trộn Session (70-30): Xem VOCV2_Item_Prioritization_Logic.md (Mục 7).
• Về Contract tỷ lệ hiển thị câu hỏi trong LEARN: Xem VOCV2_LEARN_Question_Rules.md.
• Về Content completeness & fallback data: Xem VOCV2_Content_Generation_Strategy.md.