84 lines
3.7 KiB
Markdown
84 lines
3.7 KiB
Markdown
# 房内猜拳接口文档
|
||
|
||
本文只记录房内猜拳 App 端接口。独立猜拳本阶段不接入。Flutter 详细字段看 [房内猜拳 Flutter 对接](flutter对接/房内猜拳Flutter对接.md)。
|
||
|
||
## 查询配置
|
||
|
||
- 地址：`GET /api/v1/games/room-rps/config`
|
||
- 参数：无
|
||
- 返回值：
|
||
- `config.status`：`active` / `disabled`
|
||
- `config.challenge_timeout_ms`：发起后无人应战的超时时间，默认 10 分钟
|
||
- `config.reveal_countdown_ms`：双方出拳后的揭晓倒计时，默认 3 秒
|
||
- `config.stake_gifts`：礼物下注档位
|
||
- 相关 IM：无
|
||
|
||
## 查询房间挑战单
|
||
|
||
- 地址：`GET /api/v1/games/room-rps/challenges`
|
||
- 参数：
|
||
- `room_id`：房间 ID，必填
|
||
- `status`：状态，可选
|
||
- `page_size`：页大小，默认 20
|
||
- `cursor`：下一页游标
|
||
- 返回值：
|
||
- `challenges`：挑战单列表
|
||
- `challenges[].initiator.user.nickname`：发起人昵称
|
||
- `challenges[].initiator.user.avatar`：发起人头像
|
||
- `challenges[].challenger.user.nickname`：应战人昵称；未应战时为空
|
||
- `challenges[].challenger.user.avatar`：应战人头像；未应战时为空
|
||
- `next_cursor`：下一页游标
|
||
- `page_size`：本次页大小
|
||
- 相关 IM：无。客户端漏掉 IM 后可以用这个接口补拉当前房间挑战单。
|
||
|
||
## 发起挑战
|
||
|
||
- 地址：`POST /api/v1/games/room-rps/challenges/create`
|
||
- 参数：
|
||
- `room_id`：房间 ID
|
||
- `gift_id`：后台配置的礼物档位 ID
|
||
- `gesture`：`rock` / `paper` / `scissors`
|
||
- 返回值：
|
||
- `challenge`：挑战单
|
||
- 相关 IM：
|
||
- `room_rps_challenge_created`：服务端向房间群发 `[PK]` 消息，带 `challenge_id`、发起人头像昵称、礼物档位和超时时间。
|
||
|
||
## 应战
|
||
|
||
- 地址：`POST /api/v1/games/room-rps/challenges/:challenge_id/accept`
|
||
- 参数：
|
||
- `challenge_id`：挑战单 ID
|
||
- `gesture`：`rock` / `paper` / `scissors`
|
||
- 返回值：
|
||
- `challenge`：应战后的挑战单
|
||
- 相关 IM：
|
||
- `room_rps_challenge_accepted`：服务端通知房间挑战已被锁定，带发起人和应战人头像昵称。
|
||
- `room_rps_reveal_countdown`：服务端通知双方展示 3 秒倒计时，带发起人和应战人头像昵称。
|
||
- `room_rps_finished`：服务端通知胜负、退款或礼物结算结果，带发起人和应战人头像昵称。
|
||
|
||
## 查询挑战详情
|
||
|
||
- 地址：`GET /api/v1/games/room-rps/challenges/:challenge_id`
|
||
- 参数：
|
||
- `challenge_id`：挑战单 ID
|
||
- 返回值：
|
||
- `challenge.status`：`pending` / `matched` / `revealing` / `finished` / `timeout` / `settlement_failed` / `cancelled`
|
||
- `challenge.initiator`：发起人
|
||
- `challenge.initiator.user.nickname`：发起人昵称
|
||
- `challenge.initiator.user.avatar`：发起人头像
|
||
- `challenge.challenger`：应战人
|
||
- `challenge.challenger.user.nickname`：应战人昵称；未应战时为空
|
||
- `challenge.challenger.user.avatar`：应战人头像；未应战时为空
|
||
- `challenge.winner_user_id`：胜者，平局为空或 0
|
||
- `challenge.settlement_status`：结算状态
|
||
- 相关 IM：无。客户端收到 IM 后可以用这个接口刷新挑战事实。
|
||
|
||
## 相关 IM 字段
|
||
|
||
- 所有房内猜拳 IM 都是腾讯 IM `TIMCustomElem`，`data` 是 JSON 字符串。
|
||
- 通用字段：`event_id`、`event_type`、`room_id`、`challenge_id`、`server_time_ms`、`challenge`。
|
||
- `challenge.initiator.user.nickname`：发起人昵称，必填。
|
||
- `challenge.initiator.user.avatar`：发起人头像，必填。
|
||
- `challenge.challenger.user.nickname`：应战人昵称；`room_rps_challenge_accepted`、`room_rps_reveal_countdown`、`room_rps_finished` 必填。
|
||
- `challenge.challenger.user.avatar`：应战人头像；`room_rps_challenge_accepted`、`room_rps_reveal_countdown`、`room_rps_finished` 必填。
|