172 lines
5.9 KiB
Markdown
172 lines
5.9 KiB
Markdown
# 幸运礼物 Flutter 对接
|
||
|
||
本文只描述 App 需要接入的 HTTP、送礼返回、错误处理和腾讯云 IM 自定义消息。所有接口响应都使用 gateway 业务 envelope：
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "",
|
||
"request_id": "req_xxx",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
## 1. 送礼前检查
|
||
|
||
`POST /api/v1/activities/lucky-gifts/check`
|
||
|
||
请求头：
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
| --- | --- | --- |
|
||
| `Authorization` | 是 | `Bearer <access_token>` |
|
||
| `X-App-Code` | 否 | 不传时使用默认 App |
|
||
|
||
请求体：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `room_id` | string | 是 | 当前房间 ID |
|
||
| `gift_id` | string | 是 | 实际送出的礼物 ID，例如 `rose` |
|
||
| `pool_id` | string | 是 | 幸运礼物奖池 ID，例如 `lucky`、`super_lucky` |
|
||
|
||
返回 `data`：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `enabled` | bool | 是否可按幸运礼物发送 |
|
||
| `reason` | string | `enabled`、`not_configured`、`disabled` |
|
||
| `room_id` | string | 请求房间 ID |
|
||
| `gift_id` | string | 请求礼物 ID |
|
||
| `pool_id` | string | 生效奖池 ID |
|
||
| `gift_price` | int | 单次抽奖价格，金币 |
|
||
| `rule_version` | int | 后端规则版本 |
|
||
| `target_rtp_ppm` | int | RTP 目标，ppm |
|
||
| `experience_pool` | string | `novice`、`intermediate`、`advanced` |
|
||
|
||
客户端处理：
|
||
|
||
- `enabled=true`：允许用户继续点击送礼。
|
||
- `enabled=false`：不要走幸运礼物送礼；可降级普通礼物或提示当前不可用。
|
||
- 检查结果只用于展示和拦截，最终仍以送礼接口为准。
|
||
|
||
## 2. 发送礼物
|
||
|
||
`POST /api/v1/rooms/gift/send`
|
||
|
||
请求体关键字段：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `room_id` | string | 是 | 房间 ID |
|
||
| `target_user_id` | int/string | 是 | 收礼用户 ID |
|
||
| `gift_id` | string | 是 | 礼物 ID，例如 `rose` |
|
||
| `gift_count` | int | 是 | 数量，必须大于 0 |
|
||
| `pool_id` | string | 幸运礼物必填 | `lucky` 或 `super_lucky` |
|
||
| `client_sequence` | string | 建议 | 客户端幂等序列 |
|
||
|
||
返回 `data.lucky_gift`：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `draw_id` | string | 抽奖 ID，客户端去重锚点 |
|
||
| `command_id` | string | 送礼命令 ID |
|
||
| `pool_id` | string | 生效奖池 |
|
||
| `gift_id` | string | 礼物 ID |
|
||
| `rule_version` | int | 抽奖规则版本 |
|
||
| `experience_pool` | string | 体验池 |
|
||
| `selected_tier_id` | string | 命中奖档 |
|
||
| `multiplier_ppm` | int | 倍率，`2000000` 表示 2 倍 |
|
||
| `base_reward_coins` | int | RTP 基础返奖 |
|
||
| `room_atmosphere_reward_coins` | int | 房间气氛池返奖 |
|
||
| `activity_subsidy_coins` | int | 活动补贴返奖 |
|
||
| `effective_reward_coins` | int | 用户实际获得金币 |
|
||
| `reward_status` | string | 初始通常为 `pending`，到账由后端 outbox 补偿 |
|
||
| `stage_feedback` | bool | 是否阶段反馈，可播放轻量中奖表现 |
|
||
| `high_multiplier` | bool | 是否高倍 |
|
||
| `created_at_ms` | int | UTC epoch ms |
|
||
|
||
客户端处理：
|
||
|
||
- `data.lucky_gift != null`：立即调用 `_applyLuckyGiftResult()`，播放中奖内容和数量 SVGA。
|
||
- `effective_reward_coins > 0`：展示中奖金额；余额不要本地相加，以 `WalletBalanceChanged` 或余额刷新为准。
|
||
- `data.lucky_gift == null`：按普通礼物表现处理。
|
||
|
||
## 3. 错误处理
|
||
|
||
| code | 场景 | 客户端处理 |
|
||
| --- | --- | --- |
|
||
| `INVALID_ARGUMENT` | 参数缺失、数量非法、pool_id 缺失 | 停止提交，提示用户重试或刷新礼物面板 |
|
||
| `UNAUTHENTICATED` | token 失效 | 重新登录 |
|
||
| `INSUFFICIENT_BALANCE` | 金币不足 | 打开充值入口或提示余额不足 |
|
||
| `RULE_NOT_ACTIVE` | 幸运礼物规则未启用 | 降级普通礼物或刷新礼物配置 |
|
||
| `UPSTREAM_ERROR`/`UNAVAILABLE` | 内部服务或 IM/钱包临时不可用 | 不重复扣本地余额；允许用户稍后重试 |
|
||
| `IDEMPOTENCY_CONFLICT`/`CONFLICT` | 同一客户端命令参数变化 | 重新生成 `client_sequence` 后再提交 |
|
||
|
||
送礼失败时后端不会返回 `lucky_gift`，客户端不要播放中奖 UI。送礼成功但返奖到账延迟时，房间 IM 和钱包 IM 会继续补偿。
|
||
|
||
## 4. 房间 IM
|
||
|
||
腾讯云 IM 群自定义消息：
|
||
|
||
| 字段 | 值 |
|
||
| --- | --- |
|
||
| `MsgType` | `TIMCustomElem` |
|
||
| `Desc` | `lucky_gift_drawn` |
|
||
| `Ext` | `room_system_message` |
|
||
| `Data` | JSON 字符串 |
|
||
|
||
`Data` 示例：
|
||
|
||
```json
|
||
{
|
||
"event_type": "lucky_gift_drawn",
|
||
"event_id": "lucky_gift_drawn:lucky_draw_xxx",
|
||
"draw_id": "lucky_draw_xxx",
|
||
"command_id": "cmd_xxx",
|
||
"pool_id": "super_lucky",
|
||
"room_id": "room_1",
|
||
"gift_id": "rose",
|
||
"gift_count": 1,
|
||
"user_id": 42,
|
||
"sender_user_id": 42,
|
||
"target_user_id": 99,
|
||
"coin_spent": 100,
|
||
"multiplier_ppm": 2000000,
|
||
"effective_reward_coins": 200,
|
||
"stage_feedback": true,
|
||
"high_multiplier": false,
|
||
"created_at_ms": 1760000000000
|
||
}
|
||
```
|
||
|
||
处理规则：
|
||
|
||
- 只处理 `Desc == "lucky_gift_drawn"` 且 `event_type == "lucky_gift_drawn"`。
|
||
- 用 `event_id` 或 `draw_id` 去重；同一抽奖不要重复播放。
|
||
- 当前用户已通过 HTTP 送礼响应播放过同一 `draw_id` 时，收到 IM 只更新状态，不重复播放。
|
||
|
||
## 5. 钱包余额 IM
|
||
|
||
中奖金币到账后，wallet-service 会写 `WalletBalanceChanged`，notice-service 通过腾讯云 IM C2C 投递。
|
||
|
||
| 字段 | 值 |
|
||
| --- | --- |
|
||
| `MsgType` | `TIMCustomElem` |
|
||
| `Desc` | `WalletBalanceChanged` |
|
||
| `Ext` | `wallet_notice` |
|
||
|
||
客户端处理：
|
||
|
||
- 只处理 `Desc == "WalletBalanceChanged"`。
|
||
- 用 `event_id` 去重。
|
||
- 当 `asset_type == "COIN"` 时，用 `available_after` 更新金币余额；字段缺失时调用 `GET /api/v1/wallet/me/balances` 刷新。
|
||
|
||
## 6. 接入顺序
|
||
|
||
1. 礼物面板拿到 `pool_id` 后调用 check。
|
||
2. check 可用后调用送礼接口，并把 `pool_id` 放入请求。
|
||
3. 送礼响应含 `data.lucky_gift` 时立即播放本机中奖 UI。
|
||
4. 房间内监听 `lucky_gift_drawn`，给其他用户同步中奖 UI。
|
||
5. 私聊监听 `WalletBalanceChanged`，更新金币余额。
|