# 猜拳后台管理技术文档

本文只记录本阶段已接入的房内猜拳后台接口。独立猜拳本阶段不接入后台。

## 房内猜拳配置

### 查询配置

- 地址：`GET /admin/game/room-rps/config`
- 权限：`game:view`
- 参数：无
- 返回值：
  - `config.status`：`active` / `disabled`
  - `config.challengeTimeoutMs`：发起后无人应战的超时时间，毫秒
  - `config.revealCountdownMs`：双方出拳后的揭晓倒计时，毫秒
  - `config.stakeGifts`：4 个礼物下注档位
- 相关 IM：无

### 更新配置

- 地址：`PATCH /admin/game/room-rps/config`
- 权限：`game:update`
- 参数：
  - `status`：`active` / `disabled`
  - `challengeTimeoutMs`：默认 `600000`
  - `revealCountdownMs`：默认 `3000`
  - `stakeGifts`：必须正好 4 档
  - `stakeGifts[].giftId`：礼物 ID
  - `stakeGifts[].enabled`：是否启用
  - `stakeGifts[].sortOrder`：排序
- 返回值：更新后的 `config`
- 相关 IM：无

## 房内猜拳订单

### 订单列表

- 地址：`GET /admin/game/room-rps/challenges`
- 权限：`game:view`
- 参数：
  - `roomId` / `room_id`：房间 ID，可选
  - `status`：订单状态，可选
  - `initiatorUserId` / `initiator_user_id`：发起人，可选
  - `challengerUserId` / `challenger_user_id`：应战人，可选
  - `startTimeMs` / `start_time_ms`：开始时间，可选
  - `endTimeMs` / `end_time_ms`：结束时间，可选
  - `pageSize` / `page_size`：默认 50
  - `cursor`：下一页游标
- 返回值：
  - `items`：订单列表
  - `nextCursor`：下一页游标
  - `pageSize`：本次页大小
- 相关 IM：无

### 订单详情

- 地址：`GET /admin/game/room-rps/challenges/:challenge_id`
- 权限：`game:view`
- 参数：
  - `challenge_id`：挑战单 ID
- 返回值：
  - `challenge.status`：`pending` / `matched` / `revealing` / `finished` / `timeout` / `settlement_failed` / `cancelled`
  - `challenge.initiator`：发起人手势和结果
  - `challenge.challenger`：应战人手势和结果
  - `challenge.settlementStatus`：结算状态
  - `challenge.failureReason`：结算失败原因
- 相关 IM：无

### 重试结算

- 地址：`POST /admin/game/room-rps/challenges/:challenge_id/retry-settlement`
- 权限：`game:update`
- 参数：
  - `challenge_id`：挑战单 ID
- 返回值：重试后的 `challenge`
- 限制：只允许 `settlement_failed`
- 相关 IM：成功后由 game-service 按订单状态决定是否补发房间 IM

### 手动过期

- 地址：`POST /admin/game/room-rps/challenges/:challenge_id/expire`
- 权限：`game:update`
- 参数：
  - `challenge_id`：挑战单 ID
- 返回值：过期后的 `challenge`
- 限制：只允许未被应战的 `pending`
- 相关 IM：成功后由 game-service 按订单状态决定是否补发房间 IM