Engagement Platform - Vocabulary Achievement, Badge and Reward System

Purpose

• Thiết kế cơ chế khen thưởng/huy hiệu cho hành vi học từ vựng theo hướng:
  • rõ ràng, dễ hiểu với user,
  • khó farm/gian lận,
  • vận hành ổn định dài hạn.
• Bám sát các hành vi bạn đề xuất:
  • lưu danh sách đầu tiên,
  • tạo danh sách đầu tiên,
  • học từ vựng đầu tiên,
  • đạt mốc số lượng từ,
  • đạt mốc hoàn thành danh sách.

Scope and Dependencies

• Scope:
  • achievement criteria,
  • badge tiers,
  • reward mapping,
  • anti-abuse policy,
  • event contract cho Vocabulary.
• Dependencies:
  • ENG_12_Achievement_Badge_Reward_and_Batch_System.md
  • ENG_13_Practice_and_Vocabulary_Point_Conversion_System.md
  • Vocab v2 SoT hardening (VOCV2_Product_Spec_Hardening_v1.md) cho logic học lõi.

Product Principles

• Celebrate meaningful progress:
  • thưởng cho tiến bộ có chất lượng, không thưởng click rỗng.
• Simple visible model:
  • user thấy badge + lý do đạt rõ ràng, không thấy complexity kỹ thuật.
• One action, one credit:
  • mỗi hành động định danh chỉ được tính 1 lần theo rule.
• Local semantics preserved:
  • vẫn giữ metaphor Garden trong Vocabulary; chỉ nối sang layer global ở lớp engagement.

Canonical Achievement Families (Vocabulary)

A. List Curation

• save_list:
  • lưu danh sách từ Community/Course vào My Lists.
• create_list:
  • tạo danh sách cá nhân.

B. Learning Activation

• first_vocab_study:
  • hoàn thành phiên học từ vựng đầu tiên hợp lệ.
• first_vocab_word_learned:
  • đạt từ đầu tiên ở trạng thái học hợp lệ.

C. Word Milestones

• learned_words_count:
  • mốc số lượng từ học hợp lệ.
• mastered_words_count:
  • mốc số lượng từ đạt trạng thái Mature/Flowering.

D. List Completion Milestones

• completed_lists_count:
  • mốc số lượng list hoàn thành.

Qualification Definitions (Anti-spam First)

• Qualified Vocab Session:
  • vocab_session_end với items_seen >= 5, không integrity flag.
• Qualified Learned Word:
  • item có is_new=true và đạt tối thiểu 2 lượt chạm hợp lệ trong flow học (không tính spam click).
• Qualified Mastered Word:
  • item đạt điều kiện Mature/Flowering theo SoT Vocab.
• Qualified Completed List:
  • list có >= 20 items,
  • >= 80% items ở Mature/Flowering,
  • list active ít nhất 24h (chống tạo/xóa nhanh để farm).
• Qualified Saved List:
  • tính theo unique list_id per user; un-save/re-save không cộng lại.
• Qualified Created List:
  • list cá nhân có >= 10 items hoặc có ít nhất 1 phiên học hợp lệ từ list đó trong 14 ngày.

Badge Catalog (Proposed)

1) Save List Badges

• Bookmark First:
  • mốc 1 saved list.
• Collector:
  • mốc 5.
• Library Hunter:
  • mốc 10.
• Archive Keeper:
  • mốc 25.

2) Create List Badges

• List Maker I:
  • mốc 1 created list.
• List Maker II:
  • mốc 3.
• Curator:
  • mốc 5.
• Curriculum Crafter:
  • mốc 10.

3) First-study Badges

• First Step:
  • hoàn thành phiên học vocab đầu tiên.
• First Bloom:
  • đạt từ đầu tiên ở trạng thái học hợp lệ.

4) Learned-word Badges

• Word Explorer:
  • mốc 10 từ.
• Word Builder:
  • mốc 50.
• Word Grower:
  • mốc 100.
• Word Mentor:
  • mốc 300.
• Word Architect:
  • mốc 500.
• Lexicon Master:
  • mốc 1000.

5) Completed-list Badges

• List Finisher I:
  • mốc 1 list hoàn thành.
• List Finisher II:
  • mốc 3.
• List Finisher III:
  • mốc 5.
• List Marathoner:
  • mốc 10.
• List Grandmaster:
  • mốc 20.

Rarity Mapping

• Common: starter và mốc thấp.
• Rare: mốc trung bình.
• Epic: mốc cao.
• Legendary: mốc rất cao (>=500 từ, >=20 list).

Reward Mapping (Vocabulary Achievements)

• Reward grant từ badge vocab dùng grant_key idempotent.
• Baseline reward points mỗi badge:
  • Starter (first_*, mốc 1): +2.
  • Low tier (5-50): +3.
  • Mid tier (100-300): +5.
  • High tier (500-1000, list 10+): +8.
• Guardrail cap:
  • vocab_achievement_reward_cap_week = 15 points/user/tuần.
  • phần vượt cap được defer sang tuần kế tiếp, không mất.

Awarding Pipeline (Realtime + Batch)

Realtime unlocks

• save_list mốc 1.
• create_list mốc 1.
• first_vocab_study.
• first_vocab_word_learned.

Batch unlocks (hourly/daily)

• Tiers của:
  • saved_lists_count,
  • created_lists_count,
  • learned_words_count,
  • completed_lists_count,
  • mastered_words_count.
• Reconciliation hằng ngày sửa drift do late events hoặc retry fail.

Idempotency Keys

• award_key = user_id + achievement_id + tier + rule_version.
• grant_key = user_id + award_key.

Event Contracts (Vocabulary Achievement)

• vocab_list_saved_event
• vocab_list_created_event
• vocab_session_end
• vocab_word_learned_qualified_event
• vocab_list_completed_event
• vocab_achievement_unlocked_event
• vocab_badge_awarded_event
• vocab_achievement_reward_granted_event

Required Payload Fields

• user_id
• list_id (nếu có)
• item_id (nếu có)
• achievement_id
• tier
• rule_version
• idempotency_key
• batch_job_id (nếu batch)

Canonical Achievement IDs (Implementation-ready)

Family	Achievement ID	Type	Milestones
Save list	VOC_SAVE_LIST	tiered	1, 5, 10, 25
Create list	VOC_CREATE_LIST	tiered	1, 3, 5, 10
First study	VOC_FIRST_STUDY	one_off	first qualified vocab session
First learned word	VOC_FIRST_LEARNED_WORD	one_off	first qualified learned word
Learned words	VOC_LEARNED_WORDS	tiered	10, 50, 100, 300, 500, 1000
Mastered words	VOC_MASTERED_WORDS	tiered	25, 100, 250, 500
Completed lists	VOC_COMPLETED_LISTS	tiered	1, 3, 5, 10, 20

Minimal User-facing Copy (Default)

• Save list first time:
  • Bạn vừa lưu danh sách đầu tiên. Bắt đầu trồng vườn thôi!
• Create list first time:
  • Danh sách cá nhân đầu tiên đã sẵn sàng.
• First study:
  • Tuyệt vời, bạn đã hoàn thành phiên học từ vựng đầu tiên.
• List completed:
  • Bạn đã hoàn thành một danh sách từ vựng.
• Tier-up:
  • Huy hiệu mới đã mở khóa: {badge_name}.

Tuning Parameters (Long-term Optimization)

• vocab_completed_list_min_items (default 20)
• vocab_completed_list_mastery_ratio (default 0.80)
• vocab_created_list_min_items (default 10)
• vocab_achievement_reward_cap_week (default 15)
• vocab_badge_toast_per_session_cap (default 1)

UX Surface Rules (Minimal)

• Result/Recap:
  • tối đa 1 badge toast mỗi phiên.
• Vocabulary Dashboard:
  • 1 widget “Next vocab badge”.
• Profile:
  • nhóm riêng “Vocabulary Badges” với filter List Builder | Word Growth | List Completion.
• Không hiển thị quá nhiều popups liên tiếp trong cùng session.

Anti-abuse and Fairness

• Không tính credit cho list bị moderation lock.
• Không tính badge từ list quá nhỏ (<20 items) cho mốc completion.
• Không cho farm bằng create-delete-create nhanh:
  • cùng fingerprint list trong cooldown window không cộng thêm.
• Event flagged integrity:
  • không cấp badge/reward cho đến khi clearance.

Rollout Plan

1. Shadow evaluation:

• tính progress badge vocab nhưng chưa hiển thị.

2. Internal QA:

• kiểm tra duplicate prevention, cap tuần, late-event reconcile.

3. Public rollout:

• mở starter badges + learned words tiers thấp.

4. Full rollout:

• mở list completion tiers cao + reward cap policy.

Change log

• 2026-03-04: Thiết kế hệ thống achievement/badge/reward dành riêng cho Vocabulary, bao gồm mốc save/create list, học từ đầu tiên, mốc số từ và mốc hoàn thành list.