Engagement Platform - Practice and Vocabulary Point Conversion System

Purpose

• Thiết kế cơ chế quy đổi điểm thống nhất từ:
  • quá trình làm bài tập (Practice),
  • quá trình học từ vựng (Vocabulary).
• Dùng một mô hình chung để:
  • xếp hạng global công bằng,
  • cấp reward minh bạch,
  • vẫn giữ semantics riêng của từng module.

Current-state Findings (from existing docs)

• Practice đã có thang điểm chuẩn PracticePoints (0..100), gồm quality + volume + duration:
  • xem ENG_11.
• Vocabulary có SRS/garden rất mạnh (F/D, tier, mastery, recovery) nhưng chưa có chuẩn quy đổi global thống nhất:
  • xem VOCV2_Data_Model, VOCV2_Gamification_Strategy, VOCV2_Leaderboard_Mechanics.
• Social/Reward đã có dual-ledger (lifetime + spendable) và policy tách điểm xếp hạng với điểm đổi quà:
  • xem ENG_05, SOC_Points_Rewards_Logic.

Design Principles

• Simple for user:
  • user chỉ thấy một điểm tổng hợp để theo dõi/rank.
• Local model preserved:
  • giữ công thức gốc của Practice và SRS Vocab, chỉ thêm lớp quy đổi.
• Quality first:
  • không cộng điểm nếu activity không đạt điều kiện hợp lệ.
• Anti-farm by design:
  • dùng cap, saturation, idempotency, và anti-cheat gates.
• Points-only current rollout:
  • current rollout chỉ mở hệ points/xp để theo dõi, rank, và reward conversion.
  • không mở account level hoặc ladder progression riêng cho user ở giai đoạn này.

Canonical Terms

• PracticePointsWeek:
  • điểm tuần của Practice (0..100), lấy từ ENG_11.
• VocabCarePointsWeek:
  • điểm tuần của Vocabulary (0..100), định nghĩa trong tài liệu này.
• LearningPointsWeek:
  • điểm tuần global (0..100), dùng để xếp hạng toàn nền tảng.
• RankingPointsLedger:
  • ledger không spendable, chỉ dùng rank/season.
• RewardPointsLedger:
  • ledger spendable + lifetime theo ENG_05.

Explicit non-goal

• Không dùng account level làm trục xếp hạng hoặc bề mặt tiến trình chính trong current rollout.
• Nếu cần progression dài hạn, ưu tiên:
  • badge/history,
  • season rank,
  • reward ledger đã có.
• Mọi leaderboard current-state đều neo vào points, không neo vào level.

Naming Compatibility (Deprecation)

• Canonical term cho trục Vocabulary là vocab_care_points.
• Alias cũ:
  • vocab_points,
  • vocab_xp.
• Rule áp dụng:
  • không tạo event/báo cáo mới dùng alias cũ,
  • pipeline cũ chỉ giữ read-compatibility trong giai đoạn migrate, không mở thêm dependency mới.

Module 1 - Practice Contribution

• Nguồn chuẩn:
  • PracticePointsWeek theo ENG_11 với công thức:
  • PracticePoints = 0.50 * ScoreIndex + 0.30 * VolumeIndex + 0.20 * DurationIndex.
• Qualification gate:
  • chỉ tính attempt hợp lệ (qualified activity) và không có anti-cheat flag.

Module 2 - Vocabulary Contribution

Vocab qualification gate

• valid_vocab_touches_week >= 20.
• Touch chỉ hợp lệ khi:
  • là item từ queue hợp lệ (tier/review/new theo SoT hardening),
  • không vi phạm gate chống cày (2 + 3) ở card practice,
  • không bị integrity flag.

Vocab component indices (0..100)

• RetentionIndex:
  • tỷ lệ item due giữ trạng thái Healthy.
  • RetentionIndex = clamp(100 * healthy_due_items / max(1, due_items), 0, 100).
• RecoveryIndex:
  • hiệu quả cứu item Urgent/Withered về Healthy.
  • RecoveryIndex = clamp(100 * rescued_items / recovery_target_week, 0, 100).
  • recovery_target_week mặc định: 20.
• MasteryIndex:
  • tăng trưởng item lên Mature/Flowering.
  • MasteryIndex = clamp(100 * mastered_delta_items / mastery_target_week, 0, 100).
  • mastery_target_week mặc định: 15.
• ConsistencyIndex:
  • độ đều đặn học vocab theo ngày.
  • ConsistencyIndex = clamp(100 * active_vocab_days / 7, 0, 100).

VocabCarePointsWeek formula

• VocabCarePointsWeek = 0.45 * RetentionIndex + 0.20 * RecoveryIndex + 0.20 * MasteryIndex + 0.15 * ConsistencyIndex.
• Lý do trọng số:
  • ưu tiên giữ nhớ bền (Retention) thay vì chỉ tăng số lượng.

Global Point Conversion (Practice + Vocabulary)

Eligibility-aware weighting

• Default weights:
  • PracticeWeight = 0.65,
  • VocabWeight = 0.35.
• Nếu một module không đủ eligibility:
  • module còn lại được chuẩn hóa weight về 1.0.
• Nếu cả hai module không đủ eligibility:
  • LearningPointsWeek = 0.

LearningPointsWeek formula

• LearningPointsWeek = round(PracticeWeight * PracticePointsWeek + VocabWeight * VocabCarePointsWeek).
• LearningPointsWeek nằm trong 0..100.
• LearningPointsSeason = sum(LearningPointsWeek) theo chu kỳ season.

Ranking and Reward Conversion

Ranking layer (non-spendable)

• Ghi vào RankingPointsLedger:
  • ranking_points_week = LearningPointsWeek.
• Leaderboard global dùng:
  1. LearningPointsWeek,
  2. PracticePointsWeek,
  3. VocabCarePointsWeek,
  4. earlier_qualified_at.

Reward layer (spendable + lifetime)

• Reward quy đổi từ điểm học tuần:
  • RewardEarnedWeek = min(20, floor(LearningPointsWeek / 5)).
• Ghi ledger:
  • Spendable += RewardEarnedWeek,
  • Lifetime += RewardEarnedWeek.
• Achievement bonus:
  • cộng thêm theo mapping ở ENG_12,
  • vẫn phải idempotent theo grant_key.

Safety and Anti-farm Rules

• Không cấp điểm cho action bị flag anti-cheat.
• Không tính trùng sự kiện theo idempotency_key.
• Vocab recovery anti-gaming:
  • tối đa 1 rescue credit/item/week.
• Reward cap:
  • tối đa 20 điểm quy đổi/tuần từ LearningPointsWeek (không tính bonus achievement).

Event Contracts (required additions)

• vocab_care_points_computed_event
• learning_points_week_computed_event
• learning_points_rank_published_event
• learning_points_reward_granted_event
• Payload tối thiểu:
  • practice_points_week
  • vocab_care_points_week
  • learning_points_week
  • module_eligibility (practice | vocab | both | none)
  • rule_version

Minimal UX Surfaces

• Home:
  • chỉ hiển thị Learning Points + rank delta.
• Practice surface:
  • giữ PracticePoints breakdown riêng.
• Vocabulary surface:
  • giữ Garden metrics riêng (Retention/Recovery/Mastery), không ép user học thêm thuật ngữ mới.
• Profile:
  • hiển thị snapshot gồm Learning Points (global), Practice contribution, Vocabulary contribution.

Worked Examples

• Case A (cân bằng):
  • PracticePointsWeek=78, VocabCarePointsWeek=70.
  • LearningPointsWeek=round(0.65*78 + 0.35*70)=75.
  • RewardEarnedWeek=floor(75/5)=15.
• Case B (chỉ học vocab tuần này):
  • Practice không đủ eligibility.
  • VocabCarePointsWeek=82 -> LearningPointsWeek=82.
  • RewardEarnedWeek=16.
• Case C (bị flag integrity):
  • LearningPointsWeek vẫn có thể tính cho audit,
  • RewardEarnedWeek=0 cho đến khi clearance.

Rollout Plan (Low-risk)

1. Shadow mode:

• tính VocabCarePointsWeek và LearningPointsWeek nhưng chưa hiển thị.

2. Internal validation:

• so sánh fairness theo cohort và check anti-farm leakage.

3. Public rollout:

• mở Home teaser + Profile snapshot.

4. Reward activation:

• bật RewardEarnedWeek sau khi quality gates ổn định.

Change log

• 2026-03-04: Thiết kế cơ chế quy đổi điểm thống nhất Practice + Vocabulary thành Learning Points dùng cho rank và reward conversion.
• 2026-03-05: Chuẩn hóa deprecation note cho alias vocab_points/vocab_xp, khóa canonical term vocab_care_points.
• 2026-03-09: Chốt current rollout theo hướng points-only; chưa mở account level.