Engagement Platform - Event Contracts

Purpose

• Đồng bộ naming, payload tối thiểu và quality checks cho event liên quan engagement.

Event Naming Convention

• <domain>_<entity>_<action>_event
• Ví dụ:
  • practice_attempt_submitted_event
  • leaderboard_rank_published_event
  • achievement_unlocked_event
  • reward_redemption_finalized_event

Required Meta Fields (All Events)

• event_id
• event_name
• occurred_at
• user_id (nếu có)
• source_module
• context_scope
• idempotency_key
• rule_version
• batch_job_id (optional, bắt buộc với batch-generated events)

Required Engagement Fields (Leaderboard/Points Events)

• axis_type (duration | volume | score | global_points | vocab_care_points | learning_points)
• axis_value
• qualified_activity_count
• effective_learning_minutes
• normalized_score_profile_id

Naming Compatibility (Deprecation)

• vocab_points là alias cũ, chuyển sang vocab_care_points.
• Không tạo event mới dùng alias cũ.
• Pipeline hiện có dùng alias cũ phải migrate dần theo change-control.

Engagement Event Families

• Attempt/Result:
  • submit success/failure, scoring ready, sync state, recommendation render/click/attempt.
• Leaderboard:
  • rank computed, rank published, rank locked, re-rank due to moderation.
  • practice axis scored, practice points computed, practice points rank published.
  • vocab care points computed, learning points computed, learning points rank published.
• Achievement:
  • progress updated, unlocked, revoked.
  • achievement batch evaluated, badge awarded, badge revoked.
  • vocabulary list saved/created, vocabulary list completed, vocabulary word learned qualified.
  • canonical vocab events: vocab_list_saved_event, vocab_list_created_event, vocab_word_learned_qualified_event, vocab_list_completed_event, vocab_achievement_unlocked_event.
• Reward:
  • points earned/spent/expired/refunded, redemption started/finalized/failed.
  • reward grant issued, reward grant reconciled.
  • vocabulary achievement reward granted.
• Recovery/Habit:
  • streak updated, rescue prompt shown/skipped, high-attention entered/exited.

Quality Gates

• Hard gate 1: Không publish leaderboard nếu event score chưa qua anti-cheat check.
• Hard gate 2: Không settle reward nếu redemption chưa qua inventory lock.
• Hard gate 3: Không unlock achievement nếu thiếu rule_version.
• Hard gate 4: Không award badge/reward nếu thiếu idempotency key hợp lệ (award_key/grant_key).

Data Reliability Rules

• Event phải replay-safe theo idempotency_key.
• Late-arriving event cần policy xử lý thứ tự (event_time ưu tiên hơn ingest_time).
• Mọi event quan trọng cần trạng thái xử lý: queued | processed | failed_retrying.

Cross-module Contract Notes

• Home teaser chỉ đọc aggregate signals, không tự tính rank/award.
• Practice/LM/VOC/CM emit domain events; Social/Data tổng hợp publish ở layer nền tảng.

Change log

• 2026-03-04: Tạo chuẩn event naming, payload tối thiểu, hard gates và reliability rules cho Engagement Platform.
• 2026-03-04: Bổ sung event fields/families cho mô hình practice leaderboard đa trục và global points.
• 2026-03-04: Bổ sung batch-generated event policy và gates cho achievement/badge/reward awarding.
• 2026-03-04: Mở rộng contract cho điểm quy đổi Practice + Vocabulary (vocab_care_points, learning_points).
• 2026-03-04: Bổ sung event family cho Vocabulary achievements (list actions, word milestones, completion milestones).
• 2026-03-04: Chuẩn hóa naming và deprecate alias vocab_points.