Chi tiết khóa học - Leaderboard (Learning Management)

Purpose

• Tạo động lực nhẹ bằng bảng xếp hạng trong từng khóa học, giữ vai trò phụ sau Worklist/Overview.
• Phản hồi tiến bộ theo từng loại bài (final test, assignment, practice, vocab) để khuyến khích duy trì streak và hoàn thành đủ điều kiện.

Elements / Scope

• Một tab riêng trong Course Detail, thuộc nhóm thống kê khóa.
• Mỗi category đại diện cho một loại hoạt động chính (Final test, Assignment, Online test, Exercise, Vocabulary, Dictation); có thể mở rộng thêm subtype (ví dụ: Assignment Speaking/Writing).
• Mỗi category hiển thị podium top 3 + danh sách hạng 4–10 (nếu có).
• Trạng thái đủ/thiếu điều kiện: nếu chưa đủ điều kiện xếp hạng, hiển thị empty state + CTA quay về tab luyện tập tương ứng.
• Chỉ tính dữ liệu của khóa hiện tại; không gộp liên khóa.

Logic / Rules

• Data source: kết quả bài trong khóa hiện tại (tham chiếu ../CM_Course_Activity_Model.md).
• Scope boundary:
  • đây là leaderboard cục bộ của khóa, không phải cross-area leaderboard toàn nền tảng.
  • tab này không dùng user/account level.
• Điều kiện tham gia và cách tính điểm theo loại:
  • Final test: 1 bài; dùng điểm bài làm. Điều kiện: có điểm (>=1 attempt).
  • Assignment (có thể tách Speaking/Writing): nhiều bài, thang 1–10; dùng điểm trung bình các bài đã chấm. Điều kiện: đã được chấm ≥1 bài.
  • Exercise: nhiều bài, tính % đúng mỗi bài; dùng % trung bình các bài đã làm. Điều kiện: hoàn thành ≥3 bài.
  • Online test: nhiều bài, tính % đúng mỗi bài; dùng % trung bình các bài đã làm. Điều kiện: hoàn thành ≥2 bài.
  • Vocabulary: nhiều pack, điểm = tổng số từ “thành thạo”; cộng dồn across pack. Điều kiện: hoàn thành ≥2 pack.
  • Dictation: nhiều bài, tính % đúng mỗi bài; dùng % trung bình các bài đã làm. Điều kiện: hoàn thành ≥2 bài.
• Ranking rule: chỉ xếp hạng người đủ điều kiện; sort theo điểm desc → số bài đủ điều kiện desc → thời gian hoàn thành mới nhất (tăng). Ties hiển thị cùng hạng nếu điểm và điều kiện trùng.
• Refresh: cập nhật realtime/near-realtime khi hoàn thành bài; đồng bộ với Worklist state.
• Privacy: chỉ hiển thị học viên trong cùng lớp/khóa; không public liên lớp.
• Closing rule: leaderboard mở đến 7 ngày sau ngày kết thúc khóa để nhận đủ bài chấm; sau mốc này khóa và không cập nhật thêm.
• Badges: chốt hạng khi khóa; top 1/2/3 nhận huy hiệu tương ứng; huy hiệu lưu tại khóa và trong Profile (có metadata: môn/loại bài, hạng, số người tham gia/đánh bại, ngày chốt).
• Recognition boundary:
  • huy hiệu top 1/2/3 là snapshot ghi nhận thành tích,
  • không tự đổi công thức rank của leaderboard khác nếu không có pipeline quy đổi riêng.
• Exception: lớp có bài chấm tay (assignment) có thể kéo dài lock nếu SLA chấm trễ; lock time configurable per lớp.

UI / Behavior

• Podium 3 vị trí với crown/medal; danh sách hạng 4–10 ở cột phải (scroll ngắn).
• Mỗi category card: icon/illustration, mô tả ngắn (loại điểm), chỉ báo điều kiện (đã đủ/thiếu), nút mở rộng/thu gọn danh sách.
• Empty/lock state: “Chưa có học viên được xếp hạng” + CTA “Làm luyện tập” (deeplink tới tab liên quan: Assignment/Exercise/Online test/Vocabulary/Dictation/Final test).
• Tooltip/legend: giải thích cách tính điểm và điều kiện tối thiểu.
• Adaptive: nếu ít hơn 3 người, podium hiển thị số slot tương ứng; nếu không đủ điều kiện, chỉ hiển thị empty state.
• Loading/skeleton cho từng category; lỗi dữ liệu hiển thị banner nhẹ và retry.
• Locked state: sau khi khóa (H+7 sau ngày kết thúc khóa), hiển thị badge kết quả và nhãn “Đã chốt xếp hạng”; không cho refresh hoặc thay đổi thứ hạng.
• Memory Capsule: hiển thị bộ sưu tập huy hiệu của khóa (read-only) để gợi nhớ thành tích nhóm.
• Transparency: always-on info block “Cách tính xếp hạng” mô tả điểm, điều kiện tối thiểu, thời gian chốt; đếm ngược “Còn X ngày chốt” trước H+7.
• Transparency block phải nói rõ:
  • metric cục bộ đang dùng của khóa,
  • đây không phải account level,
  • huy hiệu là lớp ghi nhận sau khi khóa bảng.
• Publish events: khi chốt hạng, gửi sự kiện “badge earned” tới Home (info strip) và Profile > Achievements; link deeplink về trang Leaderboard read-only.

Edge cases

• User chưa đủ điều kiện: hiển thị điều kiện còn thiếu (ví dụ: “Cần làm thêm 1 bài để được xếp hạng”).
• Khóa ít học viên (<3): podium thu gọn theo số người; danh sách bên phải ẩn nếu không có thêm hạng.
• Dữ liệu lệch timezone: dùng thời gian của khóa để xác định “đã hoàn thành”/attempt.
• Trường hợp điểm bằng nhau nhiều người: hiển thị cùng hạng, vẫn giữ thứ tự ổn định theo thời gian hoàn thành.
• User rời lớp/hủy khóa: ẩn khỏi leaderboard của khóa đó.
• Sau khi khóa leaderboard, các bài nộp/chấm muộn hơn mốc H+7 không ảnh hưởng thứ hạng; hiển thị message “Leaderboard đã khóa”.
• Nhóm nhỏ vẫn xếp hạng để duy trì động lực; nếu <3 người đủ điều kiện, vẫn trao huy hiệu theo thứ hạng hiện có.

Change log

• 2026-03-09: Bổ sung boundary rõ cho tab Leaderboard: metric cục bộ theo khóa, không dùng user/account level, và badge top 1/2/3 là recognition snapshot riêng.
• 2026-01-19: Bổ sung publish event sang Home strip & Profile Achievements khi chốt hạng.
• 2026-01-19: Bổ sung lưu huy hiệu vào khóa/Profile, Memory Capsule trưng bày, transparency block, metadata huy hiệu, ngoại lệ lock cho chấm trễ, áp dụng cho nhóm nhỏ.
• 2026-01-19: Thêm rule chốt xếp hạng sau 7 ngày kết thúc khóa và huy hiệu cho top 1/2/3; trạng thái locked read-only.
• 2026-01-19: Khởi tạo tab Leaderboard (Course Detail) với logic tính điểm per-activity và guardrails động lực phụ.