NON-PRODUCTION

Achievement CMS

REST JSON trên admin-api-gateway. Mọi đọc/ghi cấu hình đi thẳng Mongo, không qua cache loader của engine.

1. Tổng quan

Mục	Giá trị
Gateway	admin-api-gateway · `/api/v1/achievement/*`
Auth	CMS JWT, `Authorization: Bearer <token>`
Success	HTTP 200 `{"code":0,"msg":...}`
Bind lỗi	HTTP 400
Domain / internal	HTTP 500

type là metric id. category + target + filter là cấu hình. Engine dùng chung một cách đo cho mọi achievement cùng type. Không cần handler Go mới khi thêm achievement.

2. Auth & role

Role	ID	Dùng cho
`AchievementView`	90003	GET constants, metrics, list, detail, user progress
`AchievementEdit`	90004	create / update / delete. Cũng được gọi GET constants

3. Achievement

{
  "id": 12,
  "name": "Play 10 slots",
  "translations": [{ "country": "KH", "description": "Chơi 10 ván slot" }],
  "url": "https://cdn.example.com/a.png",
  "type": "game_play_count",
  "category": "slot",
  "target": 10,
  "enable": true,
  "filter": {
    "game_ids": ["zeus"],
    "countries": ["KH"],
    "mission_periods": []
  },
  "created_at": 1756227600,
  "updated_at": 1756227600
}

type không đổi sau khi tạo. Filter rỗng nghĩa là tất cả. leaderboard_rank chưa hỗ trợ, create/update sẽ bị từ chối.

4. Metrics

type	Đo	Category
`game_play_count`	Số ván	slot, pvp, betting, minigame, fishing
`game_played_amount`	Tổng thắng + trị tuyệt đối tiền thua	game
`game_win_amount` / `game_win_count`	Tiền thắng / số ván thắng	game
`win_multiplier`	Max tiền thắng / bet	game
`cashout_multiplier`	Cùng tỉ lệ, chỉ `game_id = crash`	minigame
`win_streak`	Chuỗi thắng	game
`game_collection`	Số game khác nhau	game
`boss_kill_count`	Số boss bị hạ	fishing
`jackpot_count`	Số lần nổ jackpot	game
`deposit_amount` / `deposit_count`	Nạp tiền	topup
`referral_count`	Mời bạn	invite
`mission_completed_count`	Nhiệm vụ hoàn thành	mission
`login_streak`	Chuỗi ngày đăng nhập UTC+7	login

5. Constants cho Create / Edit

GET /api/v1/achievement/constants

Gọi một lần khi mở form. Không hardcode danh sách type, category, filter. Role AchievementView hoặc AchievementEdit.

{
  "metrics": [
    {
      "value": "game_play_count",
      "label": "Game play count",
      "aggregation": "add",
      "categories": ["slot", "pvp", "betting", "minigame", "fishing"],
      "filters": ["game_ids", "countries"],
      "supported": true
    }
  ],
  "categories": [
    { "value": "slot", "label": "Slot" }
  ],
  "filters": [
    { "value": "game_ids", "label": "Game IDs" },
    { "value": "countries", "label": "Countries" },
    { "value": "mission_periods", "label": "Mission periods" }
  ],
  "mission_periods": [
    { "value": "daily", "label": "Daily" },
    { "value": "weekly", "label": "Weekly" },
    { "value": "monthly", "label": "Monthly" },
    { "value": "event", "label": "Event" }
  ]
}

Dropdown type chỉ hiện metric supported: true. Sau khi chọn type, category chỉ được chọn trong metrics[].categories, và chỉ hiện filter nằm trong metrics[].filters. mission_periods chỉ dùng khi filter đó được phép. leaderboard_rank có supported: false — không cho tạo.

value là giá trị lưu xuống API create/update. label chỉ để hiển thị trên CMS.

6. List metrics

GET /api/v1/achievement/metrics

[
  {
    "type": "game_play_count",
    "aggregation": "add",
    "categories": ["slot", "pvp", "betting", "minigame", "fishing"],
    "filters": ["game_ids", "countries"],
    "supported": true
  }
]

7. List

GET /api/v1/achievement?name=&page=1&page_size=20

name tìm một phần, không phân biệt hoa thường. Bỏ trống thì lấy tất cả, kể cả achievement tắt.

Chỉ page = 1 có total_records và total_pages. Trang 1 chưa đầy thì không đếm DB. Trang sau luôn trả tổng bằng 0.

{
  "list": [],
  "page": 1,
  "page_size": 20,
  "total_pages": 1,
  "total_records": 3
}

8. Get

GET /api/v1/achievement/detail?id=12 — đọc thẳng DB.

9. Create

POST /api/v1/achievement/create. Body là object achievement, không gửi id. Response là bản đã có id.

10. Update

POST /api/v1/achievement/update. Bắt buộc id. Đổi target/filter/category không reset progress và không hoàn thành/thu hồi tại lúc lưu.

11. Delete

POST /api/v1/achievement/delete

{ "id": 12 }

Xóa định nghĩa. Không xóa progress của user.

12. User progress

GET /api/v1/achievement/user-achievements

Query	Ý nghĩa
`page`, `page_size`	Mặc định 1 và 20. Quy tắc tổng giống list.
`user_id`	Tuỳ chọn. Bỏ hoặc 0 thì không lọc user.
`achievement_id`	Tuỳ chọn.
`completed`	`false` bỏ qua. `true` chỉ lấy progress đã hoàn thành.

{
  "list": [
    {
      "user_id": 7,
      "achievement_id": 12,
      "progress": 10,
      "completed_at": 1756228000,
      "selected": true,
      "updated_at": 1756228000,
      "last_event_at": 1756228000,
      "distinct_ids": []
    }
  ],
  "page": 1,
  "page_size": 20,
  "total_pages": 1,
  "total_records": 1
}