Social - Leaderboards (Logic)

Purpose

• Xếp hạng theo môn và tổng thể để tạo động lực học, công bằng và minh bạch.

Home Community Teaser Baseline (V2)

• Home chỉ dùng leaderboard/challenge ở mức teaser, không thay thế màn chuyên sâu.
• Signal ưu tiên của teaser: streak consistency (thói quen học ổn định).
• Cửa sổ dữ liệu mặc định cho teaser: 7 ngày.
• Với user chưa có lịch sử:
  • vẫn hiển thị teaser dạng empty-state,
  • có CTA để tham gia/chuyển vào luồng challenge.
• CTA teaser route:
  • đi vào Practice Management với context/tab challenge,
  • không route sang trang leaderboard standalone trong baseline V2.

Scope

• Loại bảng: theo môn (week/month/all), Overall (chuẩn hoá điểm), theo season.
• Bộ lọc: subject, period, cohort/khóa, campus/nhóm (nếu có dữ liệu).
• Opt‑out: người dùng có thể ẩn khỏi bảng xếp hạng.
• Governance nền tảng tham chiếu:
  • ../Engagement Platform/ENG_03_Leaderboard_Governance.md.

Entities

• ScoreRecord: { userId, subject, type: “practice”|“official”, score, takenAt, verifiedAt? }.
• LeaderboardEntry: { scope, period, seasonId?, rank, scoreRef }.
• Season: { id, title, startAt, endAt }.

Logic

• Eligibility: tính điểm từ bài practice hợp lệ; “thi thật” có type="official" và verifiedAt.
• Normalization (Overall): chuẩn hoá từng subject về thang chung trước khi cộng.
• Tie‑break local override (đã versioned cho Social scope):
  • điểm bằng nhau -> ưu tiên takenAt sớm -> số lần practice hợp lệ ít hơn.
  • nếu đổi tie-break, bắt buộc tăng rule_version theo governance.
• Opt‑out (optional): ẩn tên/người khỏi bảng công khai; vẫn tính nội bộ cho gợi ý cá nhân.
• Anti‑cheat: phát hiện submit dày đặc bất thường/điểm lặp lại → flag để review; loại khỏi bảng cho tới khi xử lý.

Flows

• Compute leaderboard: ETL theo period/season → normalize → sort/tie‑break → cache.
• Publish: render theo bộ lọc; ẩn user opt‑out/private.

Edge cases

• Hồ sơ private: hiển thị ẩn danh hoặc ẩn hoàn toàn theo cài đặt.
• Thay đổi timezone/locale: period xác định theo locale hệ thống → không backshift.
• Retraction: điểm bị xác định gian lận → loại và re‑rank; log sự kiện.

Technical Notes

• Time windows: tuần/tháng theo locale; season cấu hình theo kỳ.
• Cache theo key: scope:period:seasonId:filters để tránh quá tải.
• Nguồn dữ liệu: ScoreRecord có source để truy vết khi khiếu nại.

Change log

• 2026-02-19: Chốt baseline community teaser ở Home: ưu tiên streak consistency, window 7 ngày, cold-start vẫn hiển thị empty-state + CTA, và CTA đi Practice Management challenge context.