Hub 回调接口概述 (Hub Callbacks Overview)

本文档面向 Client / 包网系统接入方与开发人员，详细说明 VCT 游戏控制器平台在向包网客户端系统发起的 3 个核心回调接口及其 Body 签名机制。

1. 运行机制与同步流程

在最新的高并发稳健架构下，平台采用 进入游戏验资 + 离线结算与流水推送 的轻量级同步模式，大幅减少了实时交互的频率，提高了双边系统的稳定性。

mermaid

sequenceDiagram
    autonumber
    participant P as 玩家 (Player)
    participant H as VCT 游戏控制器 (Hub)
    participant C as 客户端系统 (Client API)

    P->>H: 1. 打开/启动游戏
    H->>C: POST /api/v1/balance (实时查询主钱包余额，验证资金池)
    C-->>H: 返回最新可用余额 (balance)
    
    rect rgb(240, 240, 240)
    Note over P,H: 玩家在游戏内畅玩 (Hub 端内部记账)
    P->>H: 2. 玩家离线/退出游戏/超时
    end
    
    H->>C: 3. POST /api/v1/callback/offline (离线对账回调，同步最终余额)
    C-->>H: 返回接收状态 (status: "success")
    
    H-->>C: 4. POST /api/v1/bet-push (单向异步推送完整流水日志，供后台报表展示)

核心节点说明

进入游戏与余额查询 (/balance)：
- 玩家进入游戏大厅或打开游戏时，Hub 调用 Client 余额查询接口 (/api/v1/balance)，获取玩家最新的包网主钱包可用余额，作为入场凭证与内部额度参考。
离线对账结算 (/offline)：
- 当玩家主动退出游戏、网络断开，或者经过 30 分钟无操作被系统超时踢出时，Hub 会向 Client 发起 离线对账回调 (/api/v1/callback/offline)，将玩家退出时的最终资金通过 reclaimed_amount 传回，供包网系统做最终的对账与日志记录。
注单流水日志推送 (/bet-push)：
- Hub 异步单向调用 Client 投注数据推送接口 (/api/v1/bet-push) 投递完整的游戏流水明细，供 Client 侧后台进行数据落库、报表展示及对账。

2. 签名认证机制

Hub 发起的每一个 POST 请求体中均包含防篡改的签名 sign。包网系统接收后需使用约定的密钥对请求体参数进行验签。

Request Body 签名 (`sign`)

请求 JSON Body 中固定包含 sign 字段：

/balance, /offline 待签名字符串：username (或 member_id) + "." + timestamp
/bet-push 待签名字符串：apiKey + "." + timestamp
签名算法：HexEncode(HMAC-SHA256(待签名字符串, apiSecret))

3. 回调接口清单

接口名称	请求路径	请求方法	说明
余额查询回调	`/api/v1/balance`	POST	实时查询玩家在 Client 侧的主钱包可用余额
离线对账回调	`/api/v1/callback/offline`	POST	玩家退出游戏或超时断线时同步最后对账数据
投注数据推送	`/api/v1/bet-push`	POST	异步推送完整游戏流水日志用于后台对账与报表展示

Hub 回调接口概述 (Hub Callbacks Overview) ​

1. 运行机制与同步流程 ​

核心节点说明 ​

2. 签名认证机制 ​