Type Deep Dive — Gift Mission And Giveaway Engine

1. Mission Engine

Campaign config lưu missions trong gamification_mission với các trường chính:

• condition
• quantity_per_completed
• limit_range
• description

FE map mission.scope:

• daily -> limit_range = daily
• ngược lại -> whole_event_time (CampaignCreateUpdate.tsx:1090-1110)

gamificationLogShareSuccess là một ví dụ mission runtime thật:

• lấy customerID từ auth context,
• gọi store.LogMission(...) với condition share success,
• trả về mission_completed và shake_turns_added (gamification_log_share_success.go:23-46).

2. Gift Config Engine

FE step 2 tạo hai nhóm:

• gifts -> gf_own_gift_config
• friendGifts -> gf_giveaway_gift_config

Khi build payload:

• allow_gifting = true cho giveaway gift,
• gift_type được map FE <-> BE bằng helper giftTypeMapper,
• value_data thay đổi theo loại quà:
  • greeting -> { greeting }
  • voucher discount / percent -> { discount_value }
  • service / cosmetic -> { value }

3. Own Gift vs Giveaway Gift

Loại	Runtime chính
gf_own_gift_config	Kết quả trực tiếp từ lượt lắc; xuất hiện ở Shake History
gf_giveaway_gift_config	Kho quà để người chơi gửi cho bạn bè; xuất hiện ở Gift History khi đã gửi

Giveaway gift có thêm:

• giveaway_send_limit
• giveaway_receive_limit
• validity_duration

4. Gift To Friend Flow

gamificationGiftToFriend hỗ trợ hai đầu vào:

• voucher_id: tặng từ voucher cá nhân đã có
• gift_config_id: tặng từ giveaway pool

Validation chính:

• phải tìm được receiver theo phone,
• không được tặng cho chính mình,
• voucher cá nhân phải thuộc sender và đang activated,
• giveaway gift phải có type gf_giveaway_gift_config,
• sender không vượt giveaway_send_limit (gamification_gift_to_friend.go:46-210).

Sau đó backend insert gamification_claim_logs với:

• gifted_from = gifted_from_friend
• status = gift_pending
• sender_id, receiver_id, gift_message, gift_image_url (gamification_gift_to_friend.go:213-251).

5. Receive Gift Flow

gamificationReceiveGift validate:

• claim log tồn tại,
• receiver đúng là current user,
• status hiện tại là gift_pending (receive_gamification_gift.go:44-80).

Hai nhánh tiếp theo:

5.1 Gift từ voucher cá nhân

• update user_vouchers.customer_id sang receiver,
• giữ nguyên voucher hiện có.

5.2 Gift từ giveaway pool

• load gift_config,
• check giveaway_receive_limit,
• parse value_data,
• generate voucher code mới,
• insert user_vouchers cho receiver,
• set channel_source = gamification_giveaway,
• set gift_from = gifted_from_friend,
• nếu có validity_duration thì tính expired_at (receive_gamification_gift.go:105-257).

Cuối cùng claim log được update sang gift_received và gắn voucher_id nếu có (receive_gamification_gift.go:260-287).

6. Claim Log Semantics

gamification_claim_logs hiện mang nhiều nghĩa cùng lúc:

• log customer nhận outcome từ game,
• link sang voucher tạo từ gift,
• log friend-gifting pending,
• log receive-gift completed.

Đây là lý do cùng một bảng vừa feed ShakeHistory, vừa feed GiftHistory, vừa là input cho statistics.

7. QA Focus

1. Mission share success có cộng lượt lắc đúng theo quantity_per_completed.
2. Tặng voucher cá nhân cho bạn bè và kiểm tra ownership transfer sau khi receiver accept.
3. Tặng quà từ giveaway pool và kiểm tra voucher mới được tạo với đúng gift_type, gift_order_type, expired_at.
4. Vượt send limit / receive limit để xác minh error path.
5. Blessing gift, discount gift, service gift, cosmetic gift để xác minh mapping value_data.

8. Rủi ro / Findings kỹ thuật

ID	Mức	Finding
GM-F01	P1	gamification_claim_logs đang overloading nhiều semantics, khiến tên bảng dễ gây hiểu nhầm là chỉ log claim từ spin.
GM-F02	P1	Gift-to-friend từ voucher cá nhân phụ thuộc voucher status activated; nếu workflow voucher đổi semantics, flow này sẽ gãy ngầm.
GM-F03	P1	Receive-gift từ giveaway pool tự tạo voucher mới, nên boundary gamification thực tế chạm sâu vào engine voucher/ecommerce.