hyapp-server/docs/房内猜拳接口文档.md

房内猜拳接口文档

本文只记录房内猜拳 App 端接口。独立猜拳本阶段不接入。Flutter 详细字段看 房内猜拳 Flutter 对接。

查询配置

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