340 lines
9.4 KiB
Markdown
340 lines
9.4 KiB
Markdown
# H5 自研猜拳接入接口
|
||
|
||
本文只记录独立自研猜拳 `rock/rps` 的 H5 接口。所有地址都有 `/api/v1` 前缀，所有接口都需要 `Authorization: Bearer <access_token>`。
|
||
|
||
成功响应统一格式：
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "ok",
|
||
"request_id": "req_xxx",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
时间字段都是 Unix epoch milliseconds。用户 ID 建议 H5 按字符串字段使用。
|
||
|
||
## 1. 获取游戏列表
|
||
|
||
地址：
|
||
|
||
```http
|
||
GET /api/v1/games
|
||
```
|
||
|
||
参数：
|
||
|
||
| 字段 | 位置 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `scene` | query | 否 | 场景，语音房传 `voice_room`。 |
|
||
| `room_id` | query | 否 | 房间 ID。 |
|
||
|
||
返回值：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `games` | array | 游戏列表。 |
|
||
| `games[].game_id` | string | 猜拳是 `rock`。 |
|
||
| `games[].name` | string | 游戏名称。 |
|
||
| `games[].launch_mode` | string | H5 打开方式。 |
|
||
| `games[].enabled` | bool | 是否可进入。 |
|
||
| `games[].maintenance` | bool | 是否维护中。 |
|
||
| `server_time_ms` | number | 服务端时间。 |
|
||
|
||
相关 IM：无。
|
||
|
||
## 2. 创建 H5 启动会话
|
||
|
||
地址：
|
||
|
||
```http
|
||
POST /api/v1/games/rock/launch
|
||
Content-Type: application/json
|
||
```
|
||
|
||
参数：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `scene` | string | 否 | 场景，语音房传 `voice_room`。 |
|
||
| `room_id` | string | 否 | 房间 ID。 |
|
||
|
||
返回值：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `session_id` | string | H5 启动会话 ID。 |
|
||
| `launch_url` | string | H5 页面地址。真实地址由后台配置，不在客户端拼。 |
|
||
| `expires_at_ms` | number | 启动会话过期时间。 |
|
||
| `orientation` | string | 页面方向。 |
|
||
| `safe_height` | number | 安全高度。 |
|
||
| `safeHeight` | number | 同 `safe_height`。 |
|
||
| `server_time_ms` | number | 服务端时间。 |
|
||
|
||
相关 IM：无。
|
||
|
||
## 3. 查询猜拳配置
|
||
|
||
地址：
|
||
|
||
```http
|
||
GET /api/v1/games/rps/config
|
||
```
|
||
|
||
参数：
|
||
|
||
| 字段 | 位置 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `game_id` | query | 否 | 固定是 `rock`，不传也按 `rock` 处理。 |
|
||
|
||
返回值：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `config.game_id` | string | 固定返回 `rock`。 |
|
||
| `config.status` | string | `active` 才能玩。 |
|
||
| `config.stake_options` | array | 可下注金币档位。 |
|
||
| `config.fee_bps` | number | 平台抽水，万分比。 |
|
||
| `config.pool_bps` | number | 奖池入池，万分比。 |
|
||
| `config.min_players` | number | 最少人数。 |
|
||
| `config.max_players` | number | 最多人数。 |
|
||
| `config.robot_enabled` | bool | 是否启用机器人补位。 |
|
||
| `config.robot_match_wait_ms` | number | 等待机器人补位时间。 |
|
||
| `config.pool_balance_coin` | number | 当前奖池余额。 |
|
||
| `server_time_ms` | number | 服务端时间。 |
|
||
|
||
`stake_options` 字段：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `stake_coin` | number | 下注金币。 |
|
||
| `enabled` | bool | 是否可选。 |
|
||
| `sort_order` | number | 排序。 |
|
||
|
||
相关 IM：无。
|
||
|
||
## 4. 快速匹配
|
||
|
||
地址：
|
||
|
||
```http
|
||
POST /api/v1/games/rps/match
|
||
Content-Type: application/json
|
||
```
|
||
|
||
参数：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `stake_coin` | number | 是 | 下注金币，必须是配置里的启用档位。 |
|
||
| `gesture` | string | 是 | 本人提前选择的手势：`rock`、`paper`、`scissors`。 |
|
||
| `rps_gesture` | string | 否 | 同 `gesture`，两个字段传一个即可。 |
|
||
| `game_id` | string | 否 | 固定是 `rock`。 |
|
||
| `room_id` | string | 否 | 房间 ID。 |
|
||
|
||
返回值：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `match` | object | 当前局详情，字段见“局详情字段”。 |
|
||
| `server_time_ms` | number | 服务端时间。 |
|
||
|
||
相关 IM：无。H5 可以轮询详情，也可以等后续接入 IM 后按 IM 刷新。
|
||
|
||
## 5. 创建等待局
|
||
|
||
地址：
|
||
|
||
```http
|
||
POST /api/v1/games/rps/matches
|
||
Content-Type: application/json
|
||
```
|
||
|
||
参数：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `stake_coin` | number | 是 | 下注金币。 |
|
||
| `gesture` | string | 是 | 本人提前选择的手势。 |
|
||
| `rps_gesture` | string | 否 | 同 `gesture`。 |
|
||
| `game_id` | string | 否 | 固定是 `rock`。 |
|
||
| `room_id` | string | 否 | 房间 ID。 |
|
||
| `min_players` | number | 否 | 最少人数，不传用配置。 |
|
||
| `max_players` | number | 否 | 最多人数，不传用配置。 |
|
||
|
||
返回值：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `match` | object | 当前局详情，字段见“局详情字段”。 |
|
||
| `server_time_ms` | number | 服务端时间。 |
|
||
|
||
相关 IM：无。
|
||
|
||
## 6. 加入等待局
|
||
|
||
地址：
|
||
|
||
```http
|
||
POST /api/v1/games/rps/matches/{match_id}/join
|
||
Content-Type: application/json
|
||
```
|
||
|
||
参数：
|
||
|
||
| 字段 | 位置 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `match_id` | path | 是 | 局 ID。 |
|
||
| `gesture` | body | 是 | 本人提前选择的手势。 |
|
||
| `rps_gesture` | body | 否 | 同 `gesture`。 |
|
||
|
||
返回值：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `match` | object | 当前局详情，字段见“局详情字段”。 |
|
||
| `server_time_ms` | number | 服务端时间。 |
|
||
|
||
相关 IM：无。
|
||
|
||
## 7. 查询局详情
|
||
|
||
地址：
|
||
|
||
```http
|
||
GET /api/v1/games/rps/matches/{match_id}
|
||
```
|
||
|
||
参数：
|
||
|
||
| 字段 | 位置 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `match_id` | path | 是 | 局 ID。 |
|
||
|
||
返回值：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `match` | object | 当前局详情，字段见“局详情字段”。 |
|
||
| `server_time_ms` | number | 服务端时间。 |
|
||
|
||
相关 IM：无。
|
||
|
||
## 8. 揭晓并结算
|
||
|
||
地址：
|
||
|
||
```http
|
||
POST /api/v1/games/rps/matches/{match_id}/roll
|
||
Content-Type: application/json
|
||
```
|
||
|
||
参数：
|
||
|
||
| 字段 | 位置 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `match_id` | path | 是 | 局 ID。 |
|
||
| `gesture` | body | 否 | 可以不传；如果传，必须等于创建或加入时的预选手势。 |
|
||
| `rps_gesture` | body | 否 | 同 `gesture`。 |
|
||
|
||
返回值：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `match` | object | 已结算局详情。 |
|
||
| `server_time_ms` | number | 服务端时间。 |
|
||
|
||
说明：猜拳不会随机出拳。服务端用双方提前选择的 `gesture` 比输赢，然后扣款、派奖和更新余额。
|
||
|
||
相关 IM：无。
|
||
|
||
## 9. 取消等待局
|
||
|
||
地址：
|
||
|
||
```http
|
||
POST /api/v1/games/rps/matches/{match_id}/cancel
|
||
```
|
||
|
||
参数：
|
||
|
||
| 字段 | 位置 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `match_id` | path | 是 | 局 ID。 |
|
||
|
||
返回值：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `match` | object | 取消后的局详情。 |
|
||
| `server_time_ms` | number | 服务端时间。 |
|
||
|
||
相关 IM：无。
|
||
|
||
## 10. 局详情字段
|
||
|
||
`match` 字段：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `match_id` | string | 局 ID。 |
|
||
| `game_id` | string | 固定是 `rock`。 |
|
||
| `room_id` | string | 房间 ID。 |
|
||
| `region_id` | number | 用户区域 ID。 |
|
||
| `min_players` | number | 最少人数。 |
|
||
| `max_players` | number | 最多人数。 |
|
||
| `current_players` | number | 当前人数。 |
|
||
| `stake_coin` | number | 本局下注金币。 |
|
||
| `round_no` | number | 当前轮次。 |
|
||
| `status` | string | `created`、`ready`、`settled`、`canceled`。 |
|
||
| `phase` | string | `waiting`、`countdown`、`settled`、`canceled`。 |
|
||
| `phase_deadline_ms` | number | 当前阶段截止时间。 |
|
||
| `result` | string | 当前用户视角结果：`win`、`lose`、`draw`。 |
|
||
| `participants` | array | 参与者列表。 |
|
||
| `join_deadline_ms` | number | 等待加入截止时间。 |
|
||
| `ready_at_ms` | number | 匹配完成时间。 |
|
||
| `settled_at_ms` | number | 结算时间。 |
|
||
| `canceled_at_ms` | number | 取消时间。 |
|
||
| `fee_bps` | number | 平台抽水。 |
|
||
| `pool_bps` | number | 奖池入池。 |
|
||
| `match_mode` | string | `human` 或 `robot`。 |
|
||
| `forced_result` | string | 机器人奖池不足时的强制结果。 |
|
||
| `pool_delta_coin` | number | 本局奖池变化。 |
|
||
|
||
`participants` 字段：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `user_id` | string | 用户 ID，H5 优先用这个字段。 |
|
||
| `user_id_number` | number | 用户 ID 数字值。 |
|
||
| `seat_no` | number | 座位号。 |
|
||
| `status` | string | `joined`、`settled`、`canceled`。 |
|
||
| `stake_coin` | number | 下注金币。 |
|
||
| `gesture` | string | 预选手势。 |
|
||
| `rps_gesture` | string | 同 `gesture`。 |
|
||
| `result` | string | `win`、`lose`、`draw`。 |
|
||
| `payout_coin` | number | 派彩金币。 |
|
||
| `balance_after` | number | 结算后余额。 |
|
||
| `joined_at_ms` | number | 加入时间。 |
|
||
| `updated_at_ms` | number | 更新时间。 |
|
||
| `participant_type` | string | `user` 或 `robot`。 |
|
||
| `is_robot` | bool | 是否机器人。 |
|
||
| `user.display_user_id` | string | 展示 ID。 |
|
||
| `user.nickname` | string | 昵称。 |
|
||
| `user.avatar` | string | 头像。 |
|
||
| `avatar_frame` | object | 头像框资源。 |
|
||
|
||
## 11. H5 推荐流程
|
||
|
||
1. App 调 `GET /api/v1/games`，看到 `game_id=rock` 后展示入口。
|
||
2. App 调 `POST /api/v1/games/rock/launch` 打开 H5。
|
||
3. H5 调 `GET /api/v1/games/rps/config` 展示下注档位。
|
||
4. 用户先选择 `rock`、`paper` 或 `scissors`。
|
||
5. H5 调 `POST /api/v1/games/rps/match` 快速匹配。
|
||
6. 返回 `phase=countdown` 后，H5 用 `phase_deadline_ms` 做倒计时。
|
||
7. 倒计时结束后，H5 调 `POST /api/v1/games/rps/matches/{match_id}/roll` 揭晓并结算。
|
||
8. H5 读返回的 `participants[].gesture/result/payout_coin/balance_after` 展示结果。
|
||
|
||
相关 IM：当前独立猜拳没有 IM。H5 用 HTTP 返回和详情轮询刷新。
|