# 房内猜拳接口文档

本文只记录房内猜拳 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`：应战后的挑战单
- 超时错误：HTTP `409`，`code=ROOM_RPS_CHALLENGE_EXPIRED`。客户端应关闭当前挑战弹窗并提示“猜拳已过期”。
- 相关 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` 必填。