hyapp-server/server/admin/docs/猜拳后台管理技术文档.md

猜拳后台管理技术文档

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

房内猜拳配置

查询配置

• 地址：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