hy/hyapp-server
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
hyapp-server/docs/flutter对接/等级体系Flutter对接.md
zhx 72d9824580 等级，成就，徽章系统
2026-05-14 17:44:16 +08:00

8.9 KiB
Raw Permalink Blame History

等级体系 Flutter 对接

地址

Base URL：https://<gateway-host>

功能 Method Path
我的等级总览 GET /api/v1/levels/me/overview
单轨道等级详情 GET /api/v1/levels/tracks/{track}
我的等级奖励记录 GET /api/v1/levels/rewards

请求参数

Headers：

Header 必填 说明
Authorization 是 Bearer <access_token>
X-App-Code 否 App 编码，默认 lalu

track：

值 说明
wealth 财富等级，送出礼物价值累计
game 游戏等级，游戏消耗累计
charm 魅力等级，收到礼物价值累计

GET /api/v1/levels/me/overview

无 query。

GET /api/v1/levels/tracks/{track}

Path：

字段 必填 说明
track 是 wealth / game / charm

GET /api/v1/levels/rewards

Query：

字段 必填 默认 说明
track 否 全部 wealth / game / charm
status 否 全部 pending / running / granted / failed
page 否 1 页码，从 1 开始
page_size 否 20 每页数量，最大 100

返回值

统一 envelope：

{
  "code": "OK",
  "message": "ok",
  "request_id": "req_xxx",
  "data": {}
}

我的等级总览

{
  "code": "OK",
  "message": "ok",
  "request_id": "req_xxx",
  "data": {
    "tracks": [
      {
        "track": "wealth",
        "name": "财富等级",
        "level": 12,
        "tier_id": 2,
        "total_value": 158000,
        "current_level_required_value": 150000,
        "next_level": 13,
        "next_level_required_value": 180000,
        "display_avatar_frame_resource_id": 7001,
        "display_badge_resource_id": 7002,
        "reward_pending_count": 1,
        "sort_order": 10
      }
    ],
    "server_time_ms": 1710000000000
  }
}

tracks[]：

字段 类型 说明
track string 等级轨道
name string 轨道展示名
level int 当前等级
tier_id int64 当前命中的等级层 ID，没有则为 0
total_value int64 当前累计值
current_level_required_value int64 当前等级门槛值
next_level int 下一等级，没有则为 0
next_level_required_value int64 下一等级门槛值，没有则为 0
display_avatar_frame_resource_id int64 当前等级层头像框资源 ID，没有则为 0
display_badge_resource_id int64 当前等级层徽章资源 ID，没有则为 0
reward_pending_count int64 待发放或发放中的等级奖励数量
sort_order int 排序

单轨道等级详情

{
  "code": "OK",
  "message": "ok",
  "request_id": "req_xxx",
  "data": {
    "overview": {
      "track": "wealth",
      "name": "财富等级",
      "level": 12,
      "tier_id": 2,
      "total_value": 158000,
      "current_level_required_value": 150000,
      "next_level": 13,
      "next_level_required_value": 180000,
      "display_avatar_frame_resource_id": 7001,
      "display_badge_resource_id": 7002,
      "reward_pending_count": 1,
      "sort_order": 10
    },
    "rules": [
      {
        "track": "wealth",
        "level": 13,
        "required_value": 180000,
        "name": "财富13级",
        "status": "active",
        "reward_resource_group_id": 9001,
        "sort_order": 13,
        "display_config_json": "{\"long_badge_resource_id\":7003}",
        "created_by_admin_id": 1,
        "updated_by_admin_id": 1,
        "created_at_ms": 1710000000000,
        "updated_at_ms": 1710000000000
      }
    ],
    "tiers": [
      {
        "tier_id": 2,
        "track": "wealth",
        "min_level": 11,
        "max_level": 20,
        "name": "财富11-20级",
        "display_avatar_frame_resource_id": 7001,
        "display_badge_resource_id": 7002,
        "reward_resource_group_id": 9002,
        "status": "active",
        "display_config_json": "{}",
        "created_by_admin_id": 1,
        "updated_by_admin_id": 1,
        "created_at_ms": 1710000000000,
        "updated_at_ms": 1710000000000
      }
    ],
    "server_time_ms": 1710000000000
  }
}

rules[]：

字段 类型 说明
track string 等级轨道
level int 等级
required_value int64 达到该等级需要的累计值
name string 等级展示名
status string active / disabled
reward_resource_group_id int64 达到该级发放的资源组 ID，没有则为 0
sort_order int 排序
display_config_json string JSON 字符串；长徽章素材取 long_badge_resource_id
created_at_ms int64 创建时间
updated_at_ms int64 更新时间

tiers[]：

字段 类型 说明
tier_id int64 等级层 ID
track string 等级轨道
min_level int 起始等级
max_level int 结束等级
name string 等级层展示名
display_avatar_frame_resource_id int64 该等级层头像框资源 ID，没有则为 0
display_badge_resource_id int64 该等级层徽章资源 ID，没有则为 0
reward_resource_group_id int64 进入该等级层发放的资源组 ID，没有则为 0
status string active / disabled
display_config_json string JSON 字符串
created_at_ms int64 创建时间
updated_at_ms int64 更新时间

我的等级奖励记录

{
  "code": "OK",
  "message": "ok",
  "request_id": "req_xxx",
  "data": {
    "rewards": [
      {
        "reward_job_id": "greward_xxx",
        "user_id": 10001,
        "track": "wealth",
        "reward_source_type": "level",
        "reward_source_id": "13",
        "resource_group_id": 9001,
        "wallet_command_id": "growth_level_reward:greward_xxx",
        "wallet_grant_id": "grant_xxx",
        "status": "granted",
        "attempt_count": 1,
        "failure_reason": "",
        "created_at_ms": 1710000000000,
        "updated_at_ms": 1710000001000
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}

rewards[]：

字段 类型 说明
reward_job_id string 奖励任务 ID
user_id int64 当前用户 ID
track string 等级轨道
reward_source_type string level 单级奖励；tier 等级层奖励
reward_source_id string level 时为等级；tier 时为等级层 ID
resource_group_id int64 发放资源组 ID
wallet_command_id string 钱包发放幂等命令 ID
wallet_grant_id string 钱包发放记录 ID；未成功时为空
status string pending / running / granted / failed
attempt_count int 发放尝试次数
failure_reason string 失败原因
created_at_ms int64 创建时间
updated_at_ms int64 更新时间

错误处理

错误 envelope：

{
  "code": "INVALID_ARGUMENT",
  "message": "invalid argument",
  "request_id": "req_xxx"
}
HTTP code 场景 Flutter 处理
400 INVALID_ARGUMENT track 非法、page / page_size 非正整数 不重试，修正参数
401 UNAUTHORIZED token 缺失、无效或过期 重新登录或刷新 token
403 PROFILE_REQUIRED 当前用户资料未完成 跳转资料补全
404 NOT_FOUND 后端返回目标不存在 刷新页面或展示空态
409 CONFLICT 后端状态冲突 刷新后重试
502 UPSTREAM_ERROR activity-service / wallet-service 暂不可用 可提示稍后重试
500 INTERNAL_ERROR 服务端内部错误 记录 request_id

只有 code == "OK" 时读取 data。

IM 消息接收

当前无等级专属 TIMCustomElem。

等级奖励资源组内包含钱包资产时，可能收到钱包 C2C 自定义消息：

字段 值
MsgType TIMCustomElem
Desc WalletBalanceChanged
Ext / extension wallet_notice
CloudCustomData 与 TIMCustomElem.Data 相同的 JSON 字符串

TIMCustomElem.Data：

{
  "event_type": "WalletBalanceChanged",
  "event_id": "wev_xxx",
  "app_code": "lalu",
  "transaction_id": "tx_xxx",
  "command_id": "resource_group_grant:growth_level_reward:greward_xxx:item:1:asset:COIN",
  "user_id": "10001",
  "asset_type": "COIN",
  "available_delta": 100,
  "frozen_delta": 0,
  "available_after": 1000,
  "frozen_after": 0,
  "balance_version": 18,
  "created_at_ms": 1710000000000,
  "source_created_at_ms": 1710000000000,
  "metadata": {}
}

处理：

条件 处理
event_type != "WalletBalanceChanged" 忽略
event_id 已处理 忽略
asset_type == "COIN" 更新金币余额
command_id 包含 growth_level_reward 刷新 /api/v1/levels/me/overview 和 /api/v1/levels/rewards