Shared Rules — Gamification Lucky Shaking

1. Thuật ngữ chuẩn

Thuật ngữ	Nghĩa trong code hiện tại	Ghi chú
Gamification campaign	gamification	Campaign shell của trò chơi
Mission	gamification_mission	Điều kiện để cộng lượt lắc
Mission log	gamification_mission_logs	Log hoàn thành nhiệm vụ theo customer
Own gift	gamification_gift_config.type = gf_own_gift_config	Kho quà phát sinh trực tiếp từ lượt lắc
Giveaway gift	gamification_gift_config.type = gf_giveaway_gift_config	Kho quà để người chơi tặng bạn bè
Claim log	gamification_claim_logs	Log runtime chung cho spin, gift, receive
Gift pending	status = gift_pending	Quà đã gửi cho bạn bè, chờ người nhận accept
Gift received	status = gift_received	Quà đã được người nhận xác nhận
Notification config	gamification_notification_config	Cấu hình gửi thông báo theo condition
Statistics view	gamification_statistics	Read-model tổng hợp dùng cho list cards

2. Status Matrix

Status	Ý nghĩa
gf_status_draft	Bản nháp
gf_status_published	Đang phát hành
gf_status_paused	Tạm dừng
gf_status_ended	Kết thúc
gf_status_cancelled	Đã hủy

Điểm đáng chú ý:

• FE action menu dùng trực tiếp các status string ở trên.
• Scheduler chỉ auto-end campaign đang published và đã quá to.
• FE constants file vẫn giữ gf_status_active, nhưng DB và phần còn lại của runtime dùng gf_status_published.

3. Gift Matrix

Trục	Giá trị thực
Gift config type	gf_own_gift_config, gf_giveaway_gift_config
Gift type	gift_type_greeting, gift_type_discount_vnd, gift_type_cosmetic, gift_type_discount_percent, gift_type_service
Gifted source	gifted_from_gamification, gifted_from_friend
Gift runtime status	gift_pending, gift_received

4. History Matrix

Surface	Filter semantics
Shake history	gift_config.type = gf_own_gift_config và sender_id is null
Gift history	gifted_from = gifted_from_friend
Statistics	Đọc functions/view thay vì query thẳng log raw

Hệ quả:

• gamification_claim_logs là nguồn chung,
• mỗi tab chỉ là một lens/filter khác nhau trên cùng runtime,
• sửa logic claim log sẽ ảnh hưởng đồng thời nhiều màn hình.

5. Master Data Drift cần nhớ

constants/master-data.ts nói rõ “should match DB”, nhưng hiện đang lệch:

Nhóm	FE constant	DB thật
Status active	gf_status_active	gf_status_published
Gift config type	voucher, point, product, blessing	gf_own_gift_config, gf_giveaway_gift_config
Mission condition	order_count, order_value, product_quantity, first_order	runtime lấy từ query master data, không khớp constants file
Notification condition	on_start, on_end, on_claim	gf_noti_new_gift, gf_noti_send_gift_success, gf_noti_after_gifting, ...
Stop condition	out_of_gifts, end_date, manual	gf_stop_voucher_used, gf_stop_game_paused, gf_stop_game_ended
File type	image, video, audio	gf_file_banner, gf_file_terms_and_conditions, ...

Runtime hiện đỡ bị nổ toàn module vì nhiều dropdown và label dùng GetGamificationMasterData query thật (useGamificationMasterData.ts:1-120), nhưng constants lệch vẫn là technical debt rõ ràng.

6. Invariants quan trọng

SR-001: Publish có hai đường

• create mới có thể insert trực tiếp với status = gf_status_published,
• campaign đã tồn tại thì publish đi qua action changeGamificationStatus.

Vì vậy “publish” không phải một engine duy nhất.

SR-002: claim_logs là runtime source-of-truth cho history

• shake outcome,
• gift pending,
• gift received,
• voucher linkage

đều tụ vào bảng này. Các tab/history functions đều đọc lại từ đây hoặc từ projection dựa trên đây.

SR-003: Giveaway receive có thể tạo voucher mới

Nếu gift đến từ gift_config_id thay vì voucher có sẵn, gamificationReceiveGift sẽ:

• check receive limit,
• generate voucher code,
• create user_vouchers,
• update claim log sang gift_received.

SR-004: Blessing không được tính như quà vật chất trong statistics view

gamification_statistics view loại gift_type_greeting khỏi total_gift_quantity và claimed_gift_count. Vì vậy tỷ lệ claim và tổng quà trên dashboard không phản ánh full mọi outcome.

7. Boundary Checklist

Khi phân tích bug hoặc change request trong vùng này, luôn hỏi:

1. Case này là campaign admin flow, runtime gift flow, hay read-model/reporting flow?
2. Publish diễn ra lúc insert mới hay qua status action?
3. Gift đang là own gift, gift từ bạn bè, hay gift từ giveaway pool?
4. Màn hình đang đọc raw claim_logs, view gamification_statistics, hay RPC function?
5. Notification config đang dùng manual template, template reference, hay ZNS/SMS hybrid?

8. Rủi ro / Findings

ID	Finding
SR-F01	Constants FE và DB master data đang lệch thật, nên bất kỳ chỗ nào không dùng query master data đều có nguy cơ sai ngầm.
SR-F02	Publish/cancel semantics hiện chia giữa FE insert path, action popup và scheduler auto-end, nên state transition không tập trung hoàn toàn vào một engine.
SR-F03	gamification_claim_logs bị overload nhiều semantics; rất dễ bị hiểu nhầm là “chỉ log lượt lắc”.