hy/hyapp-server

Fork 0

zhx 8955a0d118 明确comand_id语义

2026-05-12 20:07:49 +08:00

22 KiB

Raw Permalink Blame History

游戏接入架构

本文定义语音房 H5 弹窗游戏的服务边界、平台接入、金币改账、App 游戏列表、后台管理和补单对账方案。游戏可以来自百顺、灵仙、即构、小游等多个平台，但 App 侧看到的是一个合并后的游戏列表。

目标

在语音房内打开 H5 弹窗游戏，支持多个第三方游戏平台并行接入。
App 获取统一游戏列表，不关心游戏来自哪个平台，但返回字段必须包含 platform_code 便于排查和埋点。
第三方平台回调可以获取用户信息、查询余额、变更用户金币和补单。
后台增加一级菜单 游戏管理，二级菜单 游戏列表，列表按平台筛选和维护。
所有金币变化仍由 wallet-service 落账，游戏平台、gateway、admin 和 room-service 都不能直接改金币余额。

非目标

不把游戏状态放进 Room Cell。房间只负责展示入口、房间上下文和必要的 IM 通知。
不让第三方平台直接访问 wallet-service 或 user-service。
不用 Redis 保存金币、订单或补单事实。Redis 只可用于短期 launch token、限流和幂等热缓存。
不把不同平台的协议字段直接扩散到 App、room-service 或 wallet-service。

服务边界

新增 game-service，端口建议使用 13008，MySQL 数据库建议使用 hyapp_game。

服务	职责
`gateway-service`	App HTTP 入口；游戏列表、启动游戏、第三方平台公网回调入口；鉴权、协议转换、原始请求体透传。
`game-service`	游戏平台配置、游戏目录、展示规则、H5 启动会话、平台回调验签、平台协议适配、游戏订单、补单和对账任务 owner。
`wallet-service`	用户 `COIN` 的唯一 owner；处理游戏扣款、派奖、退款、补单入账和幂等流水。
`user-service`	用户基础资料 owner；向 game-service 提供平台回调需要的用户资料投影。
`room-service`	语音房状态 owner；只提供 `room_id` 上下文和可选的在房校验，不处理游戏订单或金币。
`server/admin`	后台 RBAC、菜单、审计和后台 HTTP API；通过 game-service gRPC 管理平台和游戏配置。
`cron-service`	只触发 game-service 的补单/对账批处理，不直接扫游戏表或修改钱包。

flowchart LR
  App["App voice room"] -->|"GET /api/v1/games"| Gateway["gateway-service"]
  App -->|"POST /api/v1/games/{game_id}/launch"| Gateway
  Provider["game platform callback"] -->|"provider HTTP callback"| Gateway
  Admin["admin frontend"] -->|"admin HTTP"| AdminServer["server/admin"]

  Gateway -->|"gRPC"| Game["game-service"]
  AdminServer -->|"gRPC"| Game
  Game -->|"gRPC ApplyGameCoinChange"| Wallet["wallet-service"]
  Game -->|"gRPC user profile"| User["user-service"]
  Game -. optional .->|"validate room context"| Room["room-service"]

  Game --> GameDB[("hyapp_game")]
  Wallet --> WalletDB[("hyapp_wallet")]

平台适配模型

每个平台实现一个 adapter，把第三方协议转换成内部统一命令。

type PlatformAdapter interface {
    VerifyCallback(rawBody []byte, headers map[string]string, query map[string]string, secret PlatformSecret) error
    ParseOperation(path string, rawBody []byte) (ProviderOperation, error)
    BuildResponse(result ProviderResult) ([]byte, string, error)
    BuildLaunchURL(session LaunchSession, user GameUser, game GameConfig) (string, error)
}

内部统一操作只保留业务语义：

内部操作	说明
`get_user_info`	平台获取用户 ID、昵称、头像、余额等启动或运行信息。
`get_balance`	平台查询用户当前金币余额。
`change_coin`	平台发起扣款、派奖、退款、冲正等金币变化。
`repair_order`	平台或后台补单，重放遗漏订单或修复平台异常订单。
`query_order`	平台查询内部订单处理结果。

平台差异只能停留在 adapter 层。进入 game-service 领域层以后，所有金额单位、订单 ID、用户 ID、游戏 ID、状态机和错误码都必须统一。

数据模型

game_platforms

游戏平台配置表。

game_platforms(
  app_code VARCHAR(32) NOT NULL,
  platform_code VARCHAR(64) NOT NULL,
  platform_name VARCHAR(128) NOT NULL,
  status VARCHAR(32) NOT NULL,
  api_base_url VARCHAR(512) NOT NULL DEFAULT '',
  callback_secret_ciphertext VARCHAR(1024) NOT NULL DEFAULT '',
  callback_ip_whitelist JSON NULL,
  adapter_config JSON NULL,
  sort_order INT NOT NULL DEFAULT 0,
  created_at_ms BIGINT NOT NULL,
  updated_at_ms BIGINT NOT NULL,
  PRIMARY KEY(app_code, platform_code)
);

status 建议取值：

状态	语义
`active`	可展示、可启动、可接收回调。
`maintenance`	App 可展示维护态，不允许启动新会话；已发生订单仍可接收回调。
`disabled`	不展示、不允许启动；回调只允许查询历史订单或按配置拒绝。

game_catalog

第三方游戏目录表，一条记录对应一个平台下的一个游戏。

game_catalog(
  app_code VARCHAR(32) NOT NULL,
  game_id VARCHAR(96) NOT NULL,
  platform_code VARCHAR(64) NOT NULL,
  provider_game_id VARCHAR(128) NOT NULL,
  game_name VARCHAR(128) NOT NULL,
  category VARCHAR(64) NOT NULL DEFAULT '',
  icon_url VARCHAR(512) NOT NULL DEFAULT '',
  cover_url VARCHAR(512) NOT NULL DEFAULT '',
  launch_mode VARCHAR(32) NOT NULL DEFAULT 'h5_popup',
  orientation VARCHAR(32) NOT NULL DEFAULT 'portrait',
  min_coin BIGINT NOT NULL DEFAULT 0,
  status VARCHAR(32) NOT NULL,
  sort_order INT NOT NULL DEFAULT 0,
  tags JSON NULL,
  created_at_ms BIGINT NOT NULL,
  updated_at_ms BIGINT NOT NULL,
  PRIMARY KEY(app_code, game_id),
  UNIQUE KEY uk_game_provider(app_code, platform_code, provider_game_id),
  KEY idx_game_platform_status(app_code, platform_code, status, sort_order)
);

game_id 是内部稳定 ID，App、订单和补单都使用它；provider_game_id 只在 adapter 和平台请求中使用。

game_display_rules

控制游戏在 App 内的展示范围。

game_display_rules(
  app_code VARCHAR(32) NOT NULL,
  rule_id VARCHAR(96) NOT NULL,
  game_id VARCHAR(96) NOT NULL,
  scene VARCHAR(64) NOT NULL,
  region_id BIGINT NOT NULL DEFAULT 0,
  language VARCHAR(32) NOT NULL DEFAULT '',
  platform VARCHAR(16) NOT NULL DEFAULT '',
  visible TINYINT(1) NOT NULL DEFAULT 1,
  enabled TINYINT(1) NOT NULL DEFAULT 1,
  sort_order INT NOT NULL DEFAULT 0,
  created_at_ms BIGINT NOT NULL,
  updated_at_ms BIGINT NOT NULL,
  PRIMARY KEY(app_code, rule_id),
  KEY idx_game_display(app_code, scene, region_id, visible, sort_order)
);

scene 当前先支持 voice_room，后续可以扩展首页、活动页或个人中心入口。region_id=0 表示全区域默认规则，具体区域规则优先级高于默认规则。

game_launch_sessions

启动会话表，绑定用户、房间、游戏和平台短期令牌。

game_launch_sessions(
  app_code VARCHAR(32) NOT NULL,
  session_id VARCHAR(96) NOT NULL,
  user_id BIGINT NOT NULL,
  display_user_id VARCHAR(32) NOT NULL,
  room_id VARCHAR(96) NOT NULL DEFAULT '',
  scene VARCHAR(64) NOT NULL,
  platform_code VARCHAR(64) NOT NULL,
  game_id VARCHAR(96) NOT NULL,
  provider_game_id VARCHAR(128) NOT NULL,
  launch_token_hash VARCHAR(128) NOT NULL,
  status VARCHAR(32) NOT NULL,
  expires_at_ms BIGINT NOT NULL,
  created_at_ms BIGINT NOT NULL,
  updated_at_ms BIGINT NOT NULL,
  PRIMARY KEY(app_code, session_id),
  KEY idx_game_launch_user(app_code, user_id, created_at_ms),
  KEY idx_game_launch_token(app_code, launch_token_hash)
);

H5 URL 里只放短期 session_token 或 provider 需要的签名参数，不直接暴露钱包能力。会话过期后不允许继续用它拉用户信息，但历史订单仍按 provider order id 幂等处理。

game_orders

游戏金币变化订单表。

game_orders(
  app_code VARCHAR(32) NOT NULL,
  order_id VARCHAR(96) NOT NULL,
  platform_code VARCHAR(64) NOT NULL,
  provider_order_id VARCHAR(160) NOT NULL,
  provider_round_id VARCHAR(160) NOT NULL DEFAULT '',
  game_id VARCHAR(96) NOT NULL,
  provider_game_id VARCHAR(128) NOT NULL,
  user_id BIGINT NOT NULL,
  room_id VARCHAR(96) NOT NULL DEFAULT '',
  op_type VARCHAR(32) NOT NULL,
  coin_amount BIGINT NOT NULL,
  status VARCHAR(32) NOT NULL,
  wallet_transaction_id VARCHAR(96) NOT NULL DEFAULT '',
  wallet_balance_after BIGINT NOT NULL DEFAULT 0,
  request_hash VARCHAR(128) NOT NULL,
  raw_payload_ref VARCHAR(256) NOT NULL DEFAULT '',
  failure_code VARCHAR(64) NOT NULL DEFAULT '',
  failure_message VARCHAR(256) NOT NULL DEFAULT '',
  created_at_ms BIGINT NOT NULL,
  updated_at_ms BIGINT NOT NULL,
  PRIMARY KEY(app_code, order_id),
  UNIQUE KEY uk_game_provider_order(app_code, platform_code, provider_order_id),
  KEY idx_game_order_user_time(app_code, user_id, created_at_ms),
  KEY idx_game_order_round(app_code, platform_code, provider_round_id)
);

op_type 建议取值：

类型	钱包语义
`debit`	用户下注或购买局内道具，扣 `COIN`。
`credit`	用户中奖或平台派奖，加 `COIN`。
`refund`	扣款后失败退款，加 `COIN`，必须关联原订单。
`reverse`	平台冲正，按平台规则转成扣款或退款，不允许直接传负数。

订单状态机：

stateDiagram-v2
  [*] --> received
  received --> wallet_applying
  wallet_applying --> succeeded
  wallet_applying --> failed
  wallet_applying --> conflict
  succeeded --> refunded
  succeeded --> reversed
  failed --> repair_pending
  repair_pending --> wallet_applying

game_callback_logs

回调日志表用于审计、排错和补偿，不作为金币事实。

game_callback_logs(
  app_code VARCHAR(32) NOT NULL,
  callback_id VARCHAR(96) NOT NULL,
  platform_code VARCHAR(64) NOT NULL,
  operation VARCHAR(64) NOT NULL,
  request_id VARCHAR(96) NOT NULL DEFAULT '',
  provider_request_id VARCHAR(160) NOT NULL DEFAULT '',
  signature_valid TINYINT(1) NOT NULL DEFAULT 0,
  request_hash VARCHAR(128) NOT NULL,
  response_code VARCHAR(64) NOT NULL DEFAULT '',
  response_body_hash VARCHAR(128) NOT NULL DEFAULT '',
  status VARCHAR(32) NOT NULL,
  created_at_ms BIGINT NOT NULL,
  PRIMARY KEY(app_code, callback_id),
  KEY idx_game_callback_platform_time(app_code, platform_code, created_at_ms)
);

原始请求体如果较大，存对象存储或压缩表；主表只保留 hash 和引用，避免日志表膨胀影响查询。

game_repair_orders

补单任务表，来源可以是平台回调、后台手动、对账任务。

game_repair_orders(
  app_code VARCHAR(32) NOT NULL,
  repair_id VARCHAR(96) NOT NULL,
  platform_code VARCHAR(64) NOT NULL,
  provider_order_id VARCHAR(160) NOT NULL,
  reason VARCHAR(128) NOT NULL,
  status VARCHAR(32) NOT NULL,
  operator_admin_id BIGINT NOT NULL DEFAULT 0,
  attempts INT NOT NULL DEFAULT 0,
  next_run_at_ms BIGINT NOT NULL DEFAULT 0,
  last_error_code VARCHAR(64) NOT NULL DEFAULT '',
  created_at_ms BIGINT NOT NULL,
  updated_at_ms BIGINT NOT NULL,
  PRIMARY KEY(app_code, repair_id),
  UNIQUE KEY uk_game_repair_provider_order(app_code, platform_code, provider_order_id)
);

补单只能重放到 game_orders 和 wallet-service 幂等命令，不能直接 UPDATE wallet_accounts。

钱包改账

钱包底层统一表达为“用户金币增加或减少 + 业务类型”，最终都落到 wallet_transactions 和 wallet_entries。RPC 层不要暴露裸的通用 ChangeCoin(user_id, amount, type) 给所有业务直接调用，而是按业务场景封装入口；游戏场景固定由 game-service 调 wallet-service 的 ApplyGameCoinChange，wallet-service 内部再转换成统一账本分录。

game-service 调 wallet-service 新增内部 RPC：

message ApplyGameCoinChangeRequest {
  RequestMeta meta = 1;
  string command_id = 2;
  int64 user_id = 3;
  string platform_code = 4;
  string game_id = 5;
  string provider_order_id = 6;
  string provider_round_id = 7;
  string op_type = 8;
  int64 coin_amount = 9;
  string room_id = 10;
  string request_hash = 11;
}

message ApplyGameCoinChangeResponse {
  string wallet_transaction_id = 1;
  int64 balance_after = 2;
  bool idempotent_replay = 3;
}

command_id 固定为：

game:{platform_code}:{provider_order_id}

钱包侧要求：

coin_amount 必须是正整数，方向由 op_type 决定。
op_type 只表达业务方向，最终统计口径落在 wallet_transactions.biz_type 和 wallet_entries.available_delta。
app_code + command_id 唯一幂等，同一命令重复请求返回同一结果。
同一 command_id 携带不同 request_hash 必须返回冲突，不允许二次改账。
debit 余额不足时不写成功交易、不写分录、不写 outbox。
credit/refund/reverse 必须写 wallet_transactions、wallet_entries 和 wallet_outbox。
游戏账务 biz_type 至少包括 game_debit、game_credit、game_refund、game_reverse。

统一账本落账示例：

游戏动作	`op_type`	`wallet_transactions.biz_type`	`wallet_entries.asset_type`	`wallet_entries.available_delta`
下注扣金币	`debit`	`game_debit`	`COIN`	`-coin_amount`
中奖派奖	`credit`	`game_credit`	`COIN`	`+coin_amount`
失败退款	`refund`	`game_refund`	`COIN`	`+coin_amount`
平台冲正	`reverse`	`game_reverse`	`COIN`	按冲正规则转换

用户金币收支统计只查 wallet_entries：

SELECT biz_type, SUM(available_delta) AS coin_delta
FROM wallet_entries
WHERE app_code = ?
  AND user_id = ?
  AND asset_type = 'COIN'
  AND created_at_ms >= ?
  AND created_at_ms < ?
GROUP BY biz_type;

App 接口

获取合并游戏列表

GET /api/v1/games?scene=voice_room&room_id={room_id}

{
  "games": [
    {
      "game_id": "bs_rocket_001",
      "platform_code": "baishun",
      "name_key": "game.bs_rocket_001.name",
      "name": "Rocket",
      "icon_url": "https://cdn.example.com/game/rocket.png",
      "cover_url": "https://cdn.example.com/game/rocket-cover.png",
      "category": "casual",
      "launch_mode": "h5_popup",
      "orientation": "portrait",
      "min_coin": 100,
      "enabled": true,
      "maintenance": false,
      "sort_order": 10
    }
  ],
  "server_time_ms": 1778490000000
}

列表聚合规则：

只返回 game_platforms.status in active/maintenance 且 game_catalog.status in active/maintenance 的游戏。
maintenance=true 时可以展示但不能启动。
根据用户区域、语言、平台和 scene 过滤 game_display_rules。
返回是多个平台合并排序，不按平台分组；后台才按平台筛选。

启动游戏

POST /api/v1/games/{game_id}/launch

请求：

{
  "scene": "voice_room",
  "room_id": "room_123"
}

{
  "session_id": "game_sess_1778490000_abcd",
  "launch_url": "https://provider.example.com/h5?...",
  "expires_at_ms": 1778490900000,
  "orientation": "portrait"
}

启动时校验：

用户必须已登录且 onboarding completed。
游戏和平台不能是 disabled。
maintenance 状态拒绝启动。
如果 scene=voice_room 且产品要求必须在房间内，game-service 通过 room-service 做只读校验；校验失败不创建启动会话。

第三方平台回调

公网入口统一放 gateway-service：

POST /api/v1/game-callbacks/{platform_code}/{operation}

gateway 行为：

保留原始 body、query、header，不提前解析成统一 JSON。
生成 request_id 并透传到内部调用。
按 platform_code 转发给 game-service。
回调响应不套 App 业务 envelope，因为第三方通常要求固定响应格式。

game-service 行为：

读取平台配置和 adapter。
验签、IP 白名单、时间戳/nonce 防重放。
写 game_callback_logs。
adapter 解析为内部 ProviderOperation。
需要用户资料时读 user-service；需要余额或改账时读/写 wallet-service。
写 game_orders 或 game_repair_orders。
adapter 构造平台要求的响应。

补单和对账

补单来源：

平台主动补单回调。
后台管理员按 platform_code + provider_order_id 手动补单。
cron-service 触发 game-service 扫描 game_repair_orders。
后续平台支持订单查询时，由 game-service 拉取平台订单对账。

补单约束：

补单必须复用原始 provider_order_id 生成同一个钱包 command_id。
钱包幂等命中时视为补单成功，但必须记录 idempotent_replay=true。
原订单请求 hash 不一致时进入 conflict，需要人工处理。
后台手动补单必须写 admin 审计，包含操作人、原因和平台订单号。

后台管理

新增一级菜单：

游戏管理
└── 游戏列表

游戏列表默认按平台 tab 或筛选展示：

字段	说明
平台	百顺、灵仙、即构、小游等 `platform_code/platform_name`。
游戏 ID	内部 `game_id` 和平台 `provider_game_id`。
名称/图标	App 展示资源。
类目	casual、slot、board 等运营类目。
状态	active、maintenance、disabled。
展示范围	scene、区域、语言、端。
最低金币	App 展示和启动前提示用。
排序	合并列表排序。
回调状态	最近回调成功率、最近错误码。

后台接口由 server/admin 提供：

GET    /api/v1/admin/game/platforms
POST   /api/v1/admin/game/platforms
PATCH  /api/v1/admin/game/platforms/{platform_code}
GET    /api/v1/admin/game/games?platform_code=baishun
POST   /api/v1/admin/game/games
PATCH  /api/v1/admin/game/games/{game_id}
PATCH  /api/v1/admin/game/games/{game_id}/status
GET    /api/v1/admin/game/orders
GET    /api/v1/admin/game/callback-logs
POST   /api/v1/admin/game/repair-orders

server/admin 只做权限、审计和后台协议；平台配置和游戏目录事实仍写入 game-service。

当前第一期已落地平台配置和游戏目录维护接口，订单查询、回调日志查询和手动补单入口随补单状态机一起实现。

并发与可靠性

game-service 可以多实例无状态部署；订单事实在 MySQL，短期 session 可同时写 MySQL 和 Redis。
同一用户多游戏并发改金币时，由 wallet-service 对 wallet_accounts(app_code,user_id,COIN) 行锁和命令幂等保证余额正确。
平台重复回调必须返回幂等结果，不允许重复扣款或重复派奖。
平台回调乱序时，game-service 只按 provider order id 和 round id 记录事实；是否允许先派奖后扣款由平台 adapter 配置决定。
game_callback_logs 不能作为成功事实；成功事实是 game_orders.status=succeeded 加 wallet 成功交易。
game-service outbox 只发布游戏订单完成、补单完成等事件；钱包余额变化仍以 wallet outbox 为准。

安全要求

每个平台必须独立 secret，支持轮换；后台只能看到 masked secret。
回调验签使用原始 body，不使用重新序列化后的 JSON。
支持 IP 白名单，但 IP 白名单失败不能替代签名校验。
请求时间戳和 nonce 防重放；nonce 可短期放 Redis，最终仍以 provider order id 幂等兜底。
H5 启动 token 短有效期，绑定 app_code/user_id/game_id/platform_code/room_id。
所有 provider 回调、补单、后台状态变更必须写审计日志。
金币金额使用整数，不允许 float，不允许负数金额表达方向。

监控指标

指标	说明
`game_callback_total{platform,operation,status}`	平台回调量和状态。
`game_callback_verify_failed_total{platform}`	验签失败和白名单失败。
`game_order_total{platform,op_type,status}`	游戏订单状态。
`game_wallet_apply_duration_ms{platform,op_type}`	调钱包耗时。
`game_wallet_conflict_total{platform}`	幂等冲突数量。
`game_repair_pending_total{platform}`	待补单数量。
`game_launch_total{platform,game_id,status}`	游戏启动量和失败原因。

落地顺序

新增 game-service 空服务、hyapp_game schema、配置和 docker-compose 端口 13008。
定义 api/proto/game/v1/game.proto，包含 App 列表、启动、后台管理和回调处理 RPC。
wallet-service 增加 ApplyGameCoinChange RPC 和 game_* 账务类型测试。
game-service 实现平台配置、游戏目录、展示规则和 App 合并列表。
game-service 实现 H5 launch session，gateway 暴露 /api/v1/games 和 /api/v1/games/{game_id}/launch。
实现第一个平台 adapter，先打通 get_user_info/get_balance/change_coin。
增加 game_orders、game_callback_logs、补单幂等和冲突处理。
server/admin 增加 游戏管理 / 游戏列表，接入 game-service 管理接口。
增加补单后台入口和 cron-service 触发的 game-service 补偿批处理。
接入第二个平台前，固化 adapter 测试基线，避免平台差异污染核心领域层。

验收清单

App 能在语音房拿到多个平台合并后的游戏列表。
禁用平台、维护平台、禁用游戏、区域不匹配游戏不会被错误启动。
启动游戏返回短期 H5 URL，过期 session 不能再换取用户信息。
平台扣金币成功后 wallet 余额减少，重复回调不重复扣。
平台派奖成功后 wallet 余额增加，重复回调不重复加。
同一 provider order id 不同 payload 返回冲突并进入人工处理。
余额不足时 game_orders 失败，wallet 不写成功交易。
后台可以按平台维护游戏、上下架、排序和查看回调日志。
后台补单只能通过 game-service 和 wallet-service 幂等命令完成，不能直接改余额。
cron-service 只触发补单批处理，不直接拥有游戏或钱包状态。

22 KiB Raw Permalink Blame History Unescape Escape