Vocabulary - Session Flow (Vocab v2)

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.

Purpose

• Quản lý vòng đời một phiên học từ vựng (Start → Learning Loop → End/Recap).
• Định nghĩa logic chọn bài (Priority Queue), cấu hình thời gian (Timed/Untimed) và xử lý kết quả thời gian thực.
• Xem thêm: Mô phỏng 1 phiên học mẫu (Sample Experience)

Elements

• Session Timer: Bộ đếm ngược (Timed mode) hoặc đếm xuôi (Untimed).
• Priority Queue: Hàng đợi các item cần học/ôn, được sắp xếp theo thuật toán SRS.
• Card Template: Giao diện hiển thị item (Flashcard/Quiz) tùy theo kỹ năng/môn học.
• Recap Screen: Màn hình tổng kết sau phiên.

Flow

1. Trigger & Initialization

Người dùng bấm nút “Bắt đầu học” (Start Learning).

1. Xác định trạng thái từ vựng (F_now):

   • Hệ thống dựa trên thời gian thực (NOW) để xác định giá trị F_now của toàn bộ ItemLearner.
   • Δt (thời gian trôi qua từ lần học cuối) luôn sẵn sàng làm tham số để tính độ suy giảm (Decay) phục vụ cho việc sắp xếp hàng đợi.

2. Khởi tạo hàng đợi (Priority Queue):

   • Lọc và sắp xếp item vào hàng đợi dựa trên bảng ưu tiên (xem mục Logic Chọn Bài).
   • Tải nhóm item đầu tiên (Initial Batch) vào bộ nhớ đệm (Web: 10; Mobile: 5).

3. Cấu hình Timer:

   • Timed Mode (Mặc định): 10 phút.
     • Logic tăng thời gian: +1 phút mỗi ngày học liên tục (Max 20 phút).
     • Logic giảm thời gian: -1 phút mỗi ngày bỏ học (Min 10 phút).
   • Untimed Mode: Không giới hạn, chạy theo queue cuốn chiếu cho đến khi user bấm dừng. Nếu pool chính tạm cạn mà user vẫn muốn học tiếp, hệ thống có thể chuyển sang Deep Review.

2. Learning Loop (Trong phiên)

Vòng lặp hiển thị item cho user tương tác:

1. Hiển thị Item:

   • Lấy item tiếp theo từ Priority Queue.
   • Coherence Check: Nếu item thuộc Mental Model A (nhóm ngữ nghĩa), hệ thống ưu tiên hiển thị tiếp các item cùng Model A có trong hàng đợi để duy trì sự liền mạch, trước khi chuyển sang Model B.

2. User Interaction:

   • User trả lời (Đúng/Sai) hoặc chọn “Tôi đã biết” / “Tôi chưa biết”.

3. Real-time Update (Xử lý tức thì):

   • Nếu Đúng (Success):
     • successCount +1, failCount giảm (theo công thức).
     • F tăng, D giảm (nhớ lâu hơn).
   • Nếu Sai (Fail):
     • failCount +1, successCount giảm (knock-down).
     • F giảm (về ngưỡng thấp hơn), D tăng (cần ôn sớm hơn).
   • lastReviewedAt = NOW.

4. Điều hướng & Continuous Loading:

   • Nếu Timer > Threshold (vd: 1 phút):
     • Chuyển sang item tiếp theo trong Batch.
     • Pre-fetch: Nếu Batch hiện tại sắp hết (còn < 2 items), hệ thống tự động tải ngầm Batch tiếp theo.
   • Nếu Timer < Threshold hoặc = 0:
     • Không nạp thêm Batch mới.
     • Cho phép user hoàn thành nốt item đang dở dang rồi kết thúc phiên.

3. Session End & Recap

Phiên học kết thúc khi hết thời gian quy định (Timed Mode) hoặc user bấm dừng. Số lượng từ học được không bị giới hạn bởi Batch size ban đầu mà phụ thuộc tốc độ của user.

Màn hình Recap hiển thị:

1. Thống kê phiên:
   • Tổng số từ đã ôn / đã học mới.
   • Độ chính xác (% Success).
2. Danh sách từ cần lưu ý:
   • Liệt kê các item có F < threshold (nguy cơ quên cao).
   • Badge cảnh báo cho các từ sai nhiều (failCount cao).
3. Call to Action:
   • “Học tiếp” (Start new session).
   • “Xem chi tiết mục tiêu” (Về Dashboard).

Logic Đề Xuất & Trộn Bài (Queue Composition - Hardening)

1. Cơ chế Batching & Buffering

Hệ thống hoạt động theo Rolling Buffer:

• Selection logic luôn chạy theo micro-batch cố định 5 item.
• Micro-batch 5 là planning window, không phải checklist 5 item cố định.
• Preload ban đầu:
  • Web: 10 item (2 micro-batch)
  • Mobile: 5 item (1 micro-batch)
• Khi progress đạt 3/5, prefetch micro-batch kế tiếp trong nền.
• Micro-batch kế tiếp luôn được sinh từ trạng thái mới nhất của queue sau các lượt đúng/sai vừa xảy ra.

2. Debt-aware Mixing Rule (single truth)

A. Định nghĩa debt

• debt_total: số item thuộc Tier 1/2/3 trong scope.
• debt_critical: số item Tier 1.

B. State A - Hard Debt

• Điều kiện: debt_total >= 20.
• Rule: 100% review, chặn từ mới.

C. State B - Soft Emergency

• Điều kiện: không ở State A nhưng Tier 1 chiếm >50% batch.
• Rule: 4 review + 1 new (oxygen rule).
• Nếu không còn new: slot new dùng reinforce low.

D. State C - Stable

• Điều kiện: không thuộc A/B.
• Mục tiêu: 30% new, 70% review.
• Cách biểu diễn với batch 5: dùng mix cycle 10 item
  • Batch lẻ: 3 review + 2 new
  • Batch chẵn: 4 review + 1 new

3. Luân phiên trong phiên (In-Session Rotation)

• Nếu Success: item rời hàng đợi ngắn hạn.
• Nếu Fail: item vào retry buffer để gặp lại sau 1-2 item.
• Với Tier 1/2 khi gặp lại: bắt buộc Learning Card -> Active Exercise.

4. Learn Question Rules (Hardening)

• Với mỗi item được chọn, engine chọn exercise theo pipeline:
  • Difficulty Controller (level-first) + Skill Controller (độc lập) -> Final Selection.
• Difficulty Controller (level-based):
  • 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.
• Skill Controller (profile-based, độ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.
• New item ramp:
  • Touch 1: Learning Card
  • Touch 2: Quick Check EASY + profile NEW_RAMP
  • Touch 3-4: Difficulty 90/10/0 (Level 1) + profile NEW_RAMP
• Guardrails:
  • Fail streak >=2: force Difficulty=EASY + profile URGENT_REPAIR trong 2 touches.
  • Tier 1/2: giới hạn Cross-skill <=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 Writing HARD.
  • Nếu bucket không có bài khả dụng: chạy Availability Ladder (PRIMARY -> ADJACENT -> CROSS -> difficulty gần nhất an toàn -> Learning Card).
  • Primary floor theo cửa sổ 10 lượt để không lệch skill (chi tiết ở Question Rules).
• Chi tiết đầy đủ: Learn Question Rules

Logic Ưu Tiên Chi Tiết (Priority Queue)

1. Tier 1 - Critical Urgent: failCount >= 3.0 AND F_now <= threshold.
2. Tier 2 - Urgent: 1.0 <= failCount < 3.0 AND F_now <= threshold.
3. Tier 3 - Normal Review: failCount < 1.0 AND F_now <= threshold.
4. Tier 4 - New Words: item unseen (chưa có ItemLearner record).
5. Tier 5 - Reinforce Low: successCount < 3.0 AND F_now >= threshold.
6. Tier 6 - Reinforce High: successCount >= 3.0 AND F_now >= threshold.
7. Tier 7 - Mastered: successCount >= 5 AND F_now >= threshold+10.
8. Tier 8 - Just Seen: item vừa xuất hiện trước đó (tránh lặp gần).

Threshold theo skill:

• Speaking: 80
• Writing: 75
• Reading: 70
• Listening: 70 (nếu áp dụng)

Tie-break:

• Cùng tier: chọn F_now thấp hơn trước.

Error & Edge Cases

• Thoát giữa chừng:
  • Dữ liệu của các item đã trả lời được lưu lại ngay lập tức.
  • Dữ liệu của item đang hiển thị (chưa trả lời) không được tính.
  • Lần vào sau sẽ tính lại F_now và tạo hàng đợi mới (không resume hàng đợi cũ).
• Collocation dài:
  • Một số cụm từ dài có thể được tách thành 2 phần hoặc yêu cầu 2 lượt tương tác. Tránh hiển thị 2 lượt này liên tiếp trong cùng một phiên ngắn.
• Mất kết nối:
  • Client cache kết quả item hiện tại. Sync về server ngay khi có mạng.

Technical Notes

• Real-time Optimization (High Performance):
  • Thay vì tính toán lại liên tục, hệ thống sử dụng chiến lược Reverse Calculation (xem Data Model).
  • Trigger: Service chỉ cần quét Index DB (WHERE next_review_at < NOW) để tìm ra ngay lập tức các user cần được nhắc nhở.
  • Hiệu quả: Loại bỏ gánh nặng tính toán realtime, đảm bảo chi phí vận hành thấp nhất trong khi vẫn giữ trải nghiệm “Real-time” cho người dùng.
  • Action:
    1. Gửi Notification.
    2. Đẩy item vào hàng đợi ưu tiên.