hyapp-server/docs/H5自研猜拳接入接口.md

H5 自研猜拳接入接口

本文只记录独立自研猜拳 rock/rps 的 H5 接口。所有地址都有 /api/v1 前缀，所有接口都需要 Authorization: Bearer <access_token>。

成功响应统一格式：

{
  "code": "OK",
  "message": "ok",
  "request_id": "req_xxx",
  "data": {}
}

时间字段都是 Unix epoch milliseconds。用户 ID 建议 H5 按字符串字段使用。

1. 获取游戏列表

地址：

GET /api/v1/games

参数：

字段	位置	必填	说明
scene	query	否	场景，语音房传 voice_room。
room_id	query	否	房间 ID。

返回值：

字段	类型	说明
games	array	游戏列表。
games[].game_id	string	猜拳是 rock。
games[].name	string	游戏名称。
games[].launch_mode	string	H5 打开方式。
games[].enabled	bool	是否可进入。
games[].maintenance	bool	是否维护中。
server_time_ms	number	服务端时间。

相关 IM：无。

2. 创建 H5 启动会话

地址：

POST /api/v1/games/rock/launch
Content-Type: application/json

参数：

字段	类型	必填	说明
scene	string	否	场景，语音房传 voice_room。
room_id	string	否	房间 ID。

返回值：

字段	类型	说明
session_id	string	H5 启动会话 ID。
launch_url	string	H5 页面地址。真实地址由后台配置，不在客户端拼。
expires_at_ms	number	启动会话过期时间。
orientation	string	页面方向。
safe_height	number	安全高度。
safeHeight	number	同 safe_height。
server_time_ms	number	服务端时间。

相关 IM：无。

3. 查询猜拳配置

地址：

GET /api/v1/games/rps/config

参数：

字段	位置	必填	说明
game_id	query	否	固定是 rock，不传也按 rock 处理。

返回值：

字段	类型	说明
config.game_id	string	固定返回 rock。
config.status	string	active 才能玩。
config.stake_options	array	可下注金币档位。
config.fee_bps	number	平台抽水，万分比。
config.pool_bps	number	奖池入池，万分比。
config.min_players	number	最少人数。
config.max_players	number	最多人数。
config.robot_enabled	bool	是否启用机器人补位。
config.robot_match_wait_ms	number	等待机器人补位时间。
config.pool_balance_coin	number	当前奖池余额。
server_time_ms	number	服务端时间。

stake_options 字段：

字段	类型	说明
stake_coin	number	下注金币。
enabled	bool	是否可选。
sort_order	number	排序。

相关 IM：无。

4. 快速匹配

地址：

POST /api/v1/games/rps/match
Content-Type: application/json

参数：

字段	类型	必填	说明
stake_coin	number	是	下注金币，必须是配置里的启用档位。
gesture	string	是	本人提前选择的手势：rock、paper、scissors。
rps_gesture	string	否	同 gesture，两个字段传一个即可。
game_id	string	否	固定是 rock。
room_id	string	否	房间 ID。

返回值：

字段	类型	说明
match	object	当前局详情，字段见“局详情字段”。
server_time_ms	number	服务端时间。

相关 IM：无。H5 可以轮询详情，也可以等后续接入 IM 后按 IM 刷新。

5. 创建等待局

地址：

POST /api/v1/games/rps/matches
Content-Type: application/json

参数：

字段	类型	必填	说明
stake_coin	number	是	下注金币。
gesture	string	是	本人提前选择的手势。
rps_gesture	string	否	同 gesture。
game_id	string	否	固定是 rock。
room_id	string	否	房间 ID。
min_players	number	否	最少人数，不传用配置。
max_players	number	否	最多人数，不传用配置。

返回值：

字段	类型	说明
match	object	当前局详情，字段见“局详情字段”。
server_time_ms	number	服务端时间。

相关 IM：无。

6. 加入等待局

地址：

POST /api/v1/games/rps/matches/{match_id}/join
Content-Type: application/json

参数：

字段	位置	必填	说明
match_id	path	是	局 ID。
gesture	body	是	本人提前选择的手势。
rps_gesture	body	否	同 gesture。

返回值：

字段	类型	说明
match	object	当前局详情，字段见“局详情字段”。
server_time_ms	number	服务端时间。

相关 IM：无。

7. 查询局详情

地址：

GET /api/v1/games/rps/matches/{match_id}

参数：

字段	位置	必填	说明
match_id	path	是	局 ID。

返回值：

字段	类型	说明
match	object	当前局详情，字段见“局详情字段”。
server_time_ms	number	服务端时间。

相关 IM：无。

8. 揭晓并结算

地址：

POST /api/v1/games/rps/matches/{match_id}/roll
Content-Type: application/json

参数：

字段	位置	必填	说明
match_id	path	是	局 ID。
gesture	body	否	可以不传；如果传，必须等于创建或加入时的预选手势。
rps_gesture	body	否	同 gesture。

返回值：

字段	类型	说明
match	object	已结算局详情。
server_time_ms	number	服务端时间。

说明：猜拳不会随机出拳。服务端用双方提前选择的 gesture 比输赢，然后扣款、派奖和更新余额。

相关 IM：无。

9. 取消等待局

地址：

POST /api/v1/games/rps/matches/{match_id}/cancel

参数：

字段	位置	必填	说明
match_id	path	是	局 ID。

返回值：

字段	类型	说明
match	object	取消后的局详情。
server_time_ms	number	服务端时间。

相关 IM：无。

10. 局详情字段

match 字段：

字段	类型	说明
match_id	string	局 ID。
game_id	string	固定是 rock。
room_id	string	房间 ID。
region_id	number	用户区域 ID。
min_players	number	最少人数。
max_players	number	最多人数。
current_players	number	当前人数。
stake_coin	number	本局下注金币。
round_no	number	当前轮次。
status	string	created、ready、settled、canceled。
phase	string	waiting、countdown、settled、canceled。
phase_deadline_ms	number	当前阶段截止时间。
result	string	当前用户视角结果：win、lose、draw。
participants	array	参与者列表。
join_deadline_ms	number	等待加入截止时间。
ready_at_ms	number	匹配完成时间。
settled_at_ms	number	结算时间。
canceled_at_ms	number	取消时间。
fee_bps	number	平台抽水。
pool_bps	number	奖池入池。
match_mode	string	human 或 robot。
forced_result	string	机器人奖池不足时的强制结果。
pool_delta_coin	number	本局奖池变化。

participants 字段：

字段	类型	说明
user_id	string	用户 ID，H5 优先用这个字段。
user_id_number	number	用户 ID 数字值。
seat_no	number	座位号。
status	string	joined、settled、canceled。
stake_coin	number	下注金币。
gesture	string	预选手势。
rps_gesture	string	同 gesture。
result	string	win、lose、draw。
payout_coin	number	派彩金币。
balance_after	number	结算后余额。
joined_at_ms	number	加入时间。
updated_at_ms	number	更新时间。
participant_type	string	user 或 robot。
is_robot	bool	是否机器人。
user.display_user_id	string	展示 ID。
user.nickname	string	昵称。
user.avatar	string	头像。
avatar_frame	object	头像框资源。

11. H5 推荐流程

1. App 调 GET /api/v1/games，看到 game_id=rock 后展示入口。
2. App 调 POST /api/v1/games/rock/launch 打开 H5。
3. H5 调 GET /api/v1/games/rps/config 展示下注档位。
4. 用户先选择 rock、paper 或 scissors。
5. H5 调 POST /api/v1/games/rps/match 快速匹配。
6. 返回 phase=countdown 后，H5 用 phase_deadline_ms 做倒计时。
7. 倒计时结束后，H5 调 POST /api/v1/games/rps/matches/{match_id}/roll 揭晓并结算。
8. H5 读返回的 participants[].gesture/result/payout_coin/balance_after 展示结果。

相关 IM：当前独立猜拳没有 IM。H5 用 HTTP 返回和详情轮询刷新。