hyapp-server/docs/猜拳对战游戏方案.md

猜拳对战游戏方案

本文定义 game-service 内新增猜拳对战模块的产品规则、服务边界、数据模型、接口和 IM 事件。当前方案基于仓库现状：App HTTP 入口在 gateway-service，游戏事实 owner 在 game-service，客户端长连接和实时投递使用腾讯云 IM，服务端私有/群消息投递能力复用 notice-service 和 pkg/tencentim。

结论

• 猜拳对战状态归 game-service 持有，不放到 room-service，也不让 gateway 承载业务状态。
• 客户端出拳必须走 HTTP 到 gateway，再转 game-service gRPC。IM 只做服务端事件下发，客户端不能通过 IM 直接提交手势。
• 1v1 对战使用腾讯云 IM C2C 自定义消息投递给双方；不为每局创建 IM 群，避免大量临时群创建和清理成本。
• 服务端所有时间使用 UTC epoch milliseconds，IM payload 带 server_time_ms、deadline_ms 和 match_version，客户端按服务端时间展示倒计时。
• 首版按免费对战设计，field.stake_coin 预留为 0。若产品后续要求金币场，再用现有 wallet ApplyGameCoinChange 结算投注和派奖。

游戏规则

大厅和场次

大厅展示三个场：

field_code	名称	匹配池	stake_coin
rookie	新手场	新手独立池	0
intermediate	中级场	中级独立池	0
advanced	高级场	高级独立池	0

字段预留：

• min_balance：付费场入场余额要求。
• stake_coin：每局投注额。首版为 0。
• choice_timeout_ms：每小局选手势时间，建议 8000。
• match_start_countdown_ms：匹配成功后开局倒计时，固定 3000。
• reveal_countdown_ms：双方都选好后展示 3、2、1，固定 3000。

对战流程

1. 用户进入大厅，选择新手场、中级场或高级场。
2. 点击进入匹配，服务端把用户放入对应 field_code 的等待队列。
3. 找到同场等待用户后创建 match，状态为 matched，设置 start_at_ms = now + 3000。
4. 开局后进入第 1 小局，双方在 choice_deadline_ms 前提交 rock/paper/scissor。
5. 双方都提交后，服务端设置 reveal_at_ms = now + 3000，通过 IM 通知客户端展示 3,2,1。
6. 到 reveal_at_ms 后，服务端公开双方手势，判定本小局胜负。
7. 先拿到 2 个胜场的用户获胜。
8. 平局不计胜场，继续下一小局；为防止无限平局，最多 5 小局，5 小局后仍未分出 2 胜则整场平局。

超时规则

• 一方未在 choice_deadline_ms 前出拳，另一方已出拳：未出拳方本小局失败。
• 双方都未出拳：本小局平局。
• 用户断线不直接判输，以提交超时为准；客户端重连后调用查询接口恢复当前状态。

服务端边界

game-service

新增模块建议：

• services/game-service/internal/domain/rps：状态、规则、胜负计算。
• services/game-service/internal/service/rps：匹配、出拳、结算、超时推进。
• services/game-service/internal/storage/mysql/rps_repository.go：MySQL 持久化和行锁。
• services/game-service/internal/transport/grpc：新增猜拳 RPC 适配。

职责：

• 持有匹配队列、对战、轮次、出拳、结算事实。
• 写入实时事件 outbox。
• 提供查询接口，供客户端丢 IM 或重连后恢复状态。

gateway-service

职责：

• 提供 /api/v1/games/rps... HTTP 接口。
• 从 JWT 上下文拿 user_id，不信任客户端传入的玩家 ID。
• 转换 HTTP 参数到 game-service gRPC。

notice-service / Tencent IM

职责：

• 消费 game-service 的猜拳实时事件 outbox。
• 使用 pkg/tencentim.PublishUserCustomMessage 给双方发 C2C 自定义消息。
• 记录投递状态和重试，客户端按 event_id 去重。

数据模型

game_rps_fields

场次配置。

关键字段：

• app_code
• field_code
• field_name
• status
• sort_order
• stake_coin
• min_balance
• choice_timeout_ms
• match_start_countdown_ms
• reveal_countdown_ms
• created_at_ms
• updated_at_ms

主键：(app_code, field_code)

game_rps_match_queue

匹配等待队列。

关键字段：

• app_code
• queue_id
• field_code
• user_id
• status: waiting/matched/cancelled/expired
• match_id
• created_at_ms
• updated_at_ms

索引：

• idx_rps_queue_match(app_code, field_code, status, created_at_ms, queue_id)
• idx_rps_queue_user(app_code, user_id, status, created_at_ms)

game_rps_matches

对战主表。

关键字段：

• app_code
• match_id
• field_code
• status: matched/countdown/playing/finished/cancelled
• player1_user_id
• player2_user_id
• winner_user_id
• player1_score
• player2_score
• round_no
• match_version
• start_at_ms
• finished_at_ms
• created_at_ms
• updated_at_ms

索引：

• idx_rps_match_player(app_code, player1_user_id, status, updated_at_ms)
• idx_rps_match_player2(app_code, player2_user_id, status, updated_at_ms)
• idx_rps_match_timeout(app_code, status, updated_at_ms)

game_rps_rounds

小局表。

关键字段：

• app_code
• match_id
• round_no
• status: picking/reveal_countdown/revealed
• choice_deadline_ms
• reveal_at_ms
• player1_choice
• player2_choice
• winner_user_id
• result: player1_win/player2_win/draw
• created_at_ms
• updated_at_ms

主键：(app_code, match_id, round_no)

game_rps_realtime_outbox

实时 IM 事件 outbox。不要复用现有 game_outbox，因为现有 gamemq.GameOutboxMessage 是订单/统计事件，要求 order_id、op_type、coin_amount > 0，不适合匹配、倒计时和揭晓这种非订单事件。

关键字段：

• app_code
• event_id
• event_type
• match_id
• target_user_id
• payload_json
• status: pending/running/delivered/retryable/failed
• worker_id
• lock_until_ms
• retry_count
• next_retry_at_ms
• last_error
• created_at_ms
• updated_at_ms

索引：

• idx_rps_realtime_claim(app_code, status, next_retry_at_ms, created_at_ms, event_id)
• idx_rps_realtime_target(app_code, target_user_id, created_at_ms)

内部 gRPC

在 api/proto/game/v1/game.proto 的 GameAppService 增加：

• ListRPSFields
• JoinRPSMatch
• CancelRPSMatch
• GetRPSMatch
• SubmitRPSChoice

核心消息：

• RPSField
• RPSMatch
• RPSPlayer
• RPSRound
• RPSChoice

RequestMeta.request_id 继续只做链路追踪，不做幂等键。出拳幂等靠 (app_code, match_id, round_no, user_id) 唯一事实保证。

HTTP 接口

1. 大厅场次

地址：GET /api/v1/games/rps/fields

参数：

• 无

返回值：

• fields: 场次列表
• server_time_ms

相关 IM：

• 无

2. 进入匹配

地址：POST /api/v1/games/rps/fields/{field_code}/match

参数：

• field_code: rookie/intermediate/advanced

返回值：

• status: waiting/matched
• queue_id
• match_id
• start_at_ms
• server_time_ms

相关 IM：

• rps_match_found
• rps_match_start_countdown

3. 取消匹配

地址：DELETE /api/v1/games/rps/match

参数：

• 无

返回值：

• cancelled: bool
• server_time_ms

相关 IM：

• rps_match_cancelled

4. 查询当前对战

地址：GET /api/v1/games/rps/matches/{match_id}

参数：

• match_id

返回值：

• match
• current_round
• server_time_ms

相关 IM：

• 无。这个接口用于补偿 IM 丢失、乱序和客户端重连。

5. 提交手势

地址：POST /api/v1/games/rps/matches/{match_id}/choices

参数：

• round_no
• choice: rock/paper/scissor

返回值：

• accepted: bool
• round_status
• choice_deadline_ms
• reveal_at_ms
• server_time_ms

相关 IM：

• rps_choice_locked
• rps_reveal_countdown
• rps_round_revealed
• rps_match_finished

IM 事件

所有 IM payload 必须包含：

• event_id
• event_type
• app_code
• match_id
• field_code
• target_user_id
• match_version
• server_time_ms

rps_match_found

用途：双方匹配成功。

关键字段：

• players
• start_at_ms

rps_round_start

用途：进入新小局，可以开始选择。

关键字段：

• round_no
• choice_deadline_ms
• my_score
• opponent_score

rps_choice_locked

用途：告知某个玩家已锁定手势。不给对方展示具体手势。

关键字段：

• round_no
• actor_user_id
• both_ready

rps_reveal_countdown

用途：双方都出完后展示 3、2、1。

关键字段：

• round_no
• reveal_at_ms

rps_round_revealed

用途：公开双方手势和小局结果。

关键字段：

• round_no
• player1_choice
• player2_choice
• result
• winner_user_id
• player1_score
• player2_score

rps_match_finished

用途：整场结束。

关键字段：

• winner_user_id
• result: player1_win/player2_win/draw
• rounds
• finished_at_ms

状态推进

JoinRPSMatch

事务内处理：

1. 检查用户是否已有 waiting/matched/playing 对局。
2. 锁定同 field_code 最早等待用户：FOR UPDATE SKIP LOCKED。
3. 找到对手则创建 game_rps_matches 和第 1 小局。
4. 两个玩家各写一条 rps_match_found outbox。
5. 找不到对手则插入 game_rps_match_queue。

SubmitRPSChoice

事务内处理：

1. 校验用户属于 match。
2. 校验 match 未结束、round 正在 picking。
3. 校验未超过 choice_deadline_ms。
4. 写入对应玩家 choice；重复提交返回当前状态，不覆盖已选手势。
5. 如果双方都已选择，设置 reveal_at_ms = now + 3000，写 rps_reveal_countdown outbox。

Timeout Worker

game-service 增加后台 worker：

• 扫描 picking 且 choice_deadline_ms <= now 的 round。
• 按超时规则补结算。
• 扫描 reveal_countdown 且 reveal_at_ms <= now 的 round。
• 公开本局结果，推进下一局或结束整场。
• 每次状态变化都写 outbox。

幂等和乱序

• 客户端按 event_id 去重。
• 客户端按 match_version 丢弃旧消息。
• 出拳天然幂等：同一用户同一局只能有一个 choice。
• IM 延迟或丢失时，客户端调用 GET /api/v1/games/rps/matches/{match_id} 拉取权威状态。

测试方案

单元测试

• 胜负规则：石头剪刀布、平局、超时。
• 先两胜：2:0、2:1、含平局、最多 5 小局平局。
• 重复出拳不能覆盖已锁定手势。
• 双方都出拳后进入 reveal countdown。

存储测试

• 并发 Join 同一场，只生成一场 match。
• 同一用户不能同时进入多个 waiting/playing。
• SubmitChoice 并发只保留第一条。
• Timeout worker 能推进超时小局。

集成测试

• gateway HTTP -> game-service gRPC -> MySQL。
• game-service outbox -> notice-service fake publisher。
• IM payload 包含 event_id、match_id、match_version、倒计时字段。

开发顺序

1. 增加 proto 和 gateway HTTP 接口。
2. 增加 game_rps_* 表和 runtime Migrate。
3. 增加 domain 胜负规则和 service 匹配/出拳/结算逻辑。
4. 增加 realtime outbox 和 timeout worker。
5. notice-service 增加 game realtime outbox consumer，复用 pkg/tencentim C2C 自定义消息。
6. 增加单元测试、存储测试、gateway handler 测试。
7. 运行 make proto、目标包 go test、docker compose config。