Engagement Platform - Achievement, Badge, Reward and Batch System

Purpose

• Thiết kế hệ thống toàn diện cho:
  • Achievement System (logic mở khóa),
  • Badge System (sưu tập và hiển thị),
  • Reward System (điểm/quà),
  • Batch System (đánh giá và cấp thưởng ổn định ở quy mô lớn).
• Giữ trải nghiệm user đơn giản dù backend đầy đủ.

Product Principles

• Simple surface, complete engine:
  • bề mặt chính ít thành phần, backend xử lý đầy đủ.
• Achievement-first:
  • mọi badge/reward phải xuất phát từ achievement hợp lệ.
• Fair and replay-safe:
  • idempotent, anti-cheat, audit được.
• No stale logic:
  • rule thay đổi phải versioned và có deprecation path.

System Boundaries (Minimal UX, Full Backend)

• User chỉ thấy:
  • tiến độ hiện tại,
  • badge mới mở khóa,
  • điểm có thể dùng.
• User không phải thấy:
  • cửa sổ batch,
  • trạng thái retry/reconcile,
  • complexity dual-ledger.
• Hệ thống phải làm ở backend:
  • chuẩn hóa event đa module,
  • tính toán idempotent,
  • tự sửa sai lệch bằng reconciliation.

Source of Truth and Anti-drift Policy

• Canonical source cho Achievement + Badge + Reward + Batch là file này (ENG_12).
• ENG_04, ENG_05, ENG_06 giữ vai trò governance tóm tắt và contract phụ trợ.
• Khi có xung đột rule:
  • ưu tiên ENG_12,
  • cập nhật file phụ trợ trong cùng chu kỳ thay đổi.
• Rule thay đổi phải đi kèm:
  • rule_version,
  • changelog,
  • trạng thái deprecated cho rule cũ (không xóa lịch sử).

Canonical Domain Model

Entity	Purpose	Core fields
AchievementDefinition	Định nghĩa điều kiện mở khóa	achievement_id, group, type, scope, criteria, tier, rule_version, status
AchievementProgress	Tiến độ user theo từng achievement	user_id, achievement_id, progress_value, state, updated_at
BadgeDefinition	Vật phẩm hiển thị cho achievement	badge_id, achievement_id, rarity, visual_set, share_template, status
BadgeAward	Lịch sử cấp badge	user_id, badge_id, awarded_at, award_key, source_event_ref
RewardDefinition	Danh mục phần thưởng	reward_id, reward_type, cost, stock_state, eligibility_rules
RewardLedger	Sổ điểm/đổi quà	user_id, lifetime_points, spendable_points, entries[]
BatchJob	Phiên xử lý batch	batch_job_id, job_type, window_start, window_end, status, retry_count
BatchCheckpoint	Điểm checkpoint cho backfill/reconcile	job_type, cursor, last_success_at

Achievement Taxonomy (Comprehensive)

Group	Purpose	Typical scopes
starter	Kích hoạt hành vi ban đầu	program + skill
volume	Ghi nhận số lượng bài làm hợp lệ	program, skill, global
time	Ghi nhận thời lượng học hợp lệ	program, global
quality	Ghi nhận chất lượng làm bài	program + score profile
consistency	Ghi nhận nhịp học ổn định	global
participation	Ghi nhận tham gia hoạt động/challenge	campaign/event/global
recovery	Ghi nhận phục hồi sau decline/high-attention	global/program
seasonal	Ghi nhận thành tựu theo mùa/sự kiện giới hạn thời gian	seasonal scope

Badge Catalog Strategy

Program-Skill Starter Badges

• Mỗi program + skill có badge “First Qualified Attempt”.
• Ví dụ:
  • IELTS Reading First Step,
  • IELTS Writing First Step,
  • IELTS Speaking First Step,
  • áp dụng tương tự cho TOEIC/SAT/khác.

Tiered Progress Badges

• Attempt tiers (configurable default):
  • 1, 5, 10, 30, 50, 100.
• Effective-time tiers (configurable default):
  • 30m, 120m, 300m, 900m, 1800m.
• Quality tiers:
  • dựa trên điểm chuẩn hóa + min qualified attempts để tránh may mắn ngắn hạn.

Participation Badges

• Tham gia challenge đầu tiên.
• Hoàn thành event milestone.
• Đóng góp cộng đồng có kiểm duyệt.

Achievement -> Badge -> Reward Mapping

• Mapping chuẩn:
  • achievement unlocked -> badge awarded -> reward points granted (nếu có).
• Reward points theo tier:
  • tier thấp thưởng nhỏ, tier cao thưởng lớn hơn nhưng có cap chu kỳ.
• Không thưởng lặp:
  • cùng achievement_id + tier + rule_version chỉ cấp 1 lần.

Reward Architecture (Comprehensive but Clear)

• Lifetime points:
  • dùng cho level/progression dài hạn.
• Spendable points:
  • dùng đổi quà/quyền lợi.
• Reward sources:
  • achievement unlock,
  • campaign/event,
  • manual adjustment có audit.
• Reward sink:
  • redemption,
  • expiration,
  • penalty/reversal theo policy.
• Reward grant policy:
  • grant phải idempotent,
  • grant có thể delayed qua batch nếu cần kiểm tra anti-abuse.

Batch System Architecture (Full)

Processing modes

1. Realtime evaluator:
   • xử lý các mốc cần phản hồi nhanh (first attempt, low-tier milestones).
2. Scheduled batch evaluator:
   • chạy định kỳ để tính các achievement nặng (cross-module aggregates, seasonal).
3. Reconciliation batch:
   • quét late events, failed jobs, hoặc mismatch ledger.

Batch job types

• achievement_eval_batch
• badge_award_batch
• reward_grant_batch
• leaderboard_recompute_batch
• reconciliation_batch

Batch orchestration defaults

• achievement_eval_batch: mỗi 15-30 phút theo window trượt.
• badge_award_batch: mỗi 15-30 phút, chạy sau eval.
• reward_grant_batch: mỗi 30-60 phút, chạy sau award.
• reconciliation_batch: hằng ngày + phiên weekly deep reconcile.
• leaderboard_recompute_batch: theo kỳ leaderboard và trigger moderation.

Idempotency and replay safety

• award_key = user_id + achievement_id + tier + rule_version
• grant_key = user_id + award_key
• replay event/batch không được tạo cấp thưởng trùng.

Failure handling

• Retry theo backoff.
• Quá ngưỡng retry -> DLQ + alert.
• Re-run theo batch_job_id phải deterministic theo snapshot window.

Late-event policy

• Event đến trễ:
  • được đưa vào reconciliation window.
  • nếu tạo thay đổi award/rank thì phát event điều chỉnh có audit trail.

Safety states (batch pipeline)

• queued -> processing -> completed
• processing -> retrying -> completed
• processing/retrying -> failed_terminal -> manual_review hoặc reconcile_replay

Qualification and Anti-abuse Gates

• Qualified attempt chỉ tính khi:
  • completion ratio đạt ngưỡng,
  • submit hợp lệ,
  • không bị anti-cheat flag.
• Time-based badges:
  • chỉ tính effective learning minutes.
• Volume-based badges:
  • giới hạn anti-spam theo cadence.
• Participation badges:
  • chỉ tính hành vi hợp lệ, không tính self-interaction spam.

Lifecycle State Machines

AchievementProgress

• not_started -> in_progress -> unlocked
• unlocked -> revoked (chỉ khi có lý do audit hợp lệ)

BadgeAward

• pending -> awarded
• pending -> rejected (anti-abuse/moderation)
• awarded -> revoked (exceptional path)

RewardGrant

• pending -> granted -> spendable
• granted -> reversed (refund/reversal policy)
• pending -> expired (nếu quá thời hạn settlement)

UX Surfaces (Minimal)

• Home:
  • 1 card “progress + next badge”.
  • 1 card “recent unlock”.
• Result page:
  • tối đa 1 unlock toast cho mỗi attempt.
• Profile:
  • badge board đầy đủ, lọc theo program | group | rarity.
  • pin tối đa N badge để khoe (configurable).
• Leaderboard:
  • bảng điểm global và bảng chi tiết theo trục ở màn chuyên dụng.

User-facing Journey (Simple)

1. User hoàn thành activity hợp lệ.
2. Hệ thống cập nhật progress ngay (nếu realtime) hoặc trong batch gần nhất.
3. Nếu đạt mốc:
   • mở achievement,
   • cấp badge,
   • cấp reward (nếu có).
4. User nhận tối đa 1 tín hiệu nổi bật tại result/home, archive đầy đủ ở profile.
5. Nếu có điều chỉnh batch/reconcile, user chỉ thấy trạng thái cuối cùng đã xác thực.

Notification Policy (for badges/rewards)

• Unlock notifications đi qua global governor.
• Gộp nhiều unlock thành digest nếu cùng phiên/ngày.
• Không làm gián đoạn flow làm bài.

Analytics and Ops Metrics

• Achievement:
  • unlock rate theo group/tier,
  • time-to-first-badge,
  • unlock-to-next-attempt uplift.
• Reward:
  • grant rate, redeem rate, refund rate.
• Batch:
  • batch success rate,
  • reconciliation lag,
  • duplicate-award prevention hit rate.
• Safety:
  • flagged-award rate,
  • abuse false-positive rate.

Operational SLO Baseline

• Award latency:
  • realtime path: p95 <= 2 phút,
  • batch path: p95 <= 60 phút.
• Reconciliation lag:
  • p95 <= 24 giờ.
• Duplicate award rate:
  • mục tiêu ~= 0, cảnh báo nếu > 0.01%.
• Settlement reliability:
  • reward grant success >= 99.9% mỗi ngày.

Rule Versioning and Deprecation

• Mọi rule/badge mapping phải có rule_version.
• Khi thay rule:
  • không xóa lịch sử cấp cũ,
  • mark deprecated cho definition cũ,
  • mở definition mới với version tăng.
• Deprecation có sunset date + migration note.

Implementation Order (Comprehensive but Controlled)

1. Khóa taxonomy + data contracts + idempotency keys.
2. Mở realtime awards cho starter + low-tier.
3. Mở batch evaluator cho tier cao + seasonal + reconciliation.
4. Mở reward grant full + redemption integration.
5. Mở social showcase hoàn chỉnh (profile board + share cards).

Change log

• 2026-03-04: Thiết lập kiến trúc toàn diện cho Achievement/Badge/Reward/Batch theo hướng long-term stable và simple-by-default.
• 2026-03-04: Bổ sung anti-drift source-of-truth policy, batch orchestration defaults, state machines và SLO vận hành.