# 等级体系 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：

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

### 我的等级总览

```json
{
  "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 | 排序 |

### 单轨道等级详情

```json
{
  "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 | 更新时间 |

### 我的等级奖励记录

```json
{
  "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：

```json
{
  "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`：

```json
{
  "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` |