Mission — tài liệu ghép client

Nhiệm vụ của user trên lobby (không phải HTTP game). Client gọi POST /api/v2/rpc trên game-api-gateway, body mã hóa AES giống daily bonus / gold digger. Có 4 kỳ: ngày, tuần, tháng, và sự kiện (khoảng thời gian cố định).

1. Tổng quan

2. Period types

Mỗi mission có period_type. Dùng để chia tab. Không hardcode label — map từ value dưới đây.

3. Auth & envelope

Giống mọi RPC lobby: decrypt data → JSON {"method","data"} → handler → encrypt {"code","msg"}.

POST /api/v2/rpc
Authorization: Bearer <access_token>
Content-Type: application/json

decrypt → {
  "method": "/mission/list",
  "data": {}
}

success → HTTP 200, encrypted { "code": 0, "msg": { ... } }
error   → HTTP 500, encrypted { "code": ..., "msg": ... }

Popup lỗi dùng code = 1000 và msg là chuỗi i18n (khi parse được error từ server).

4. List missions đang chạy

method: /mission/list

data có thể rỗng {} (trả tất cả period) hoặc lọc 1 tab:

data:
{}
// hoặc
{ "period_type": "daily" }     // daily | weekly | monthly | event
                               // sai / lạ → list rỗng cho filter đó, không lỗi

msg:
{
  "missions": [
    {
      "snapshot_id": 1001,
      "name": "Play 10 games",
      "description": "Chơi 10 ván hôm nay",
      "period_type": "daily",
      "from_time": 1756227600,
      "to_time": 1756314000,
      "progress": 4,
      "target": 10,
      "percent": 40,
      "progress_text": "",
      "completed": false,
      "claimed": false,
      "reward_amount": 1000,
      "icon_url": "https://cdn.example.com/missions/play-10.png"
    }
  ]
}

5. Mission detail

method: /mission/detail

Một mission theo snapshot_id lấy từ list. Shape mission giống từng phần tử trong list (kèm target, progress_text).

data:
{ "snapshot_id": 1001 }

msg:
{
  "mission": {
    "snapshot_id": 1001,
    "name": "Weekly ranking",
    "description": "Top bảng xếp hạng tuần này",
    "period_type": "weekly",
    "from_time": 1756227600,
    "to_time": 1756832400,
    "progress": 12000,
    "target": 1,
    "percent": 100,
    "progress_text": "Automatically receive the reward on <color=#e3b602>15-09</color>",
    "completed": true,
    "claimed": false,
    "reward_amount": 5000,
    "icon_url": "https://cdn.example.com/missions/ranking.png"
  }
}

• Dùng khi user mở màn hình chi tiết / tap card — progress được đọc lại từ DB, không chỉ cache list.
• Bắt buộc snapshot_id từ list. Không tự bịa template id.
• snapshot_id <= 0 hoặc snapshot không còn active → lỗi (refresh list).
• Không cần gửi period_type.

6. Claim reward

method: /mission/claim

data:
{ "snapshot_id": 1001 }

msg success:
{ "snapshot_id": 1001, "reward_amount": 1000 }

• Claim 1 lần / snapshot. Gọi lại → lỗi đã nhận.
• Chưa đủ progress → lỗi chưa hoàn thành.
• reward_amount là số chip gửi qua chip mail, không phải số dư ngay. Toast “đã gửi vào hộp thư”.
• snapshot_id <= 0 → invalid input.
• Claim không cần gửi period_type.

7. Gợi ý UI

1. Vào lobby / event → gọi /mission/list với {}.
2. Chia 4 tab theo period_type: Daily / Weekly / Monthly / Event. Tab không có mission thì ẩn hoặc empty state.
3. Card: icon = icon_url (rỗng → icon default local), title = name, sub = description, bar = percent, số = progress / target, chip = reward_amount.
4. Nếu progress_text không rỗng: hiện dòng đó (rich text) thay vì tự viết “nhận thưởng ngày …”. Ranking thưởng tuần sau, không claim tay.
5. Tap card → /mission/detail với snapshot_id để refresh progress trước khi hiện popup chi tiết.
6. Countdown = to_time (unix). Weekly / monthly / event nên hiện “còn X ngày/giờ”.
7. Completed chưa claim: CTA Claim. Đã claim: badge Claimed, disable.
8. Sau claim: cập nhật card hoặc list lại. Có thể poll mail / chip nếu UI đang hiện số dư.
9. Đừng cache list sang ngày khác — daily đổi mỗi 0h UTC+7; weekly/monthly/event đổi theo to_time.

8. Error codes

9. Checklist

• Group hoặc filter theo period_type — 4 tab, không gộp tất cả thành “nhiệm vụ ngày”.
• Hiện countdown từ to_time.
• Số tiến độ = progress / target. Dòng phụ ranking = progress_text (rich text), không tự dịch / tự ghép ngày.
• Màn chi tiết gọi /mission/detail với snapshot_id từ list.
• Claim dùng snapshot_id từ list, không tự bịa.
• Disable double-tap claim.
• Không cộng chip local từ reward_amount vào balance (thưởng nằm ở mail).
• Empty list / empty tab là hợp lệ (VIP này không có mission kỳ đó).
• Dùng description / progress_text server trả về, không tự dịch enum.
• Hiện icon_url trên card; rỗng thì dùng icon mặc định client, không ẩn mission.