游戏记录详情 / 回放查询

使用 VCT 推送到包网的注单资料，查询游戏商的原始注单详情或回放链接。包网只需保留收到的 betId、hubSessionId 和 status；VCT 会定位原记录并处理不同游戏商的查询差异。

查询范围

只能查询当前 Agent 自己收到的注单。VCT 会以已认证 Agent、bet_id、hub_session_id 和 status 一起定位日志，不接受客户端传入的其他 Agent 身份。

环境地址

环境	Base URL
生产环境	https://hub-panel-api.v7stech.com
测试环境	https://hub-panel-api-dev.v7stech.com

接口信息

属性	值
路径	POST /api/partner/v1/gamedetail
认证	Agent Token (Bearer)
Content-Type	application/json

认证 Header 的生成方式见认证机制。

请求参数

参数	类型	必填	说明
bet_id	string	是	回调 wagers[].bet_id，或下游保存后的 betId。
hub_session_id	string	是	回调 wagers[].session_id，或下游保存后的 hubSessionId。这是 VCT 会话 ID，不是包网内部 sessionId。
status	string	是	回调 wagers[].status，例如 BET、SETTLED、BONUS、CANCEL、ROLLBACK、REFUND 或 VOID。用于精确匹配同一注单的不同流水。
round_id	string	否	回调 wagers[].round_id。当原始日志没有更适合的厂商单号时，VCT 将它用作查询单号。
request_id	string	否	调用方唯一请求编号；建议记录，便于联调追踪。未传时 VCT 自动生成。

兼容下游直接转发回调样本：betId、hubSessionId、roundId 和 requestId 与对应 snake_case 字段等效。若同时传入，以 snake_case 为准。

请求示例

以下示例直接使用包网收到的结算记录：

{
  "betId": "02537e2ae3e943f68a8e4eabc41f15a4",
  "hubSessionId": "7fb2b4fd-09cf-41ed-b24f-9c30ed9c08bb",
  "roundId": "wxGPGe3e9cTZNwzRDYyLqa",
  "status": "SETTLED",
  "requestId": "agent-detail-20261007-001"
}

curl -X POST https://hub-panel-api.v7stech.com/api/partner/v1/gamedetail \
  -H "Authorization: Bearer {agent_token}" \
  -H "Content-Type: application/json" \
  -d '{"bet_id":"02537e2ae3e943f68a8e4eabc41f15a4","hub_session_id":"7fb2b4fd-09cf-41ed-b24f-9c30ed9c08bb","round_id":"wxGPGe3e9cTZNwzRDYyLqa","status":"SETTLED","request_id":"agent-detail-20261007-001"}'

VCT 的处理规则

1. 从 Agent Token 确定当前 Agent。
2. 在 VCT 游戏日志中按 Agent、bet_id、hub_session_id 和 status 查找唯一记录。
3. 使用已保存的原始日志准备查询资料。
4. 自动处理不同游戏商的字段和查询规则。
5. 以统一格式返回结构化详情或回放链接。

成功响应

VCT 以统一格式返回查询结果。成功时业务 code 为 0；常见的 data 内容如下：

{
  "code": 0,
  "message": "success",
  "data": {
    "url": "https://provider.example/replay/xxxx",
    "detail": {
      "bet_amount": 0,
      "prize_amount": 42.4
    }
  }
}

• data.url：游戏商提供时为回放或注单详情链接；可能为空。
• data.detail：游戏商返回的结构化详情；字段会随游戏商变化。

游戏商支持范围

以下为 2026-10-07 的当前能力快照。包网可以用它说明功能范围，但不要把名单写成永久业务规则；最终以接口返回为准。

当前不支持 GameDetail

调用以下游戏商的注单会返回 UNSUPPORTED_ACTION，包网应显示“该游戏商暂不提供详情/回放”，且不要自动重试：

fachai、sbobet、ct855、ug、afb、fastspin、odin、nextspin、spadegaming、apollogames、ace333、marioclub、vpower、luckysport

• fachai：游戏商没有按单号查询详情/回放的接口。
• sbobet：游戏商要求额外的 portfolio，当前统一 GameDetail 尚未接入。
• 其余游戏商：VCT 当前尚未提供 GameDetail。

部分支持或有时间限制

游戏商	当前限制	包网处理
microgaming	功能仍在维护中	显示暂不可用，不持续重试
jdb	只支持厂商允许分享回放的游戏；一般要求赢额大于 0（Buy Feature 除外）；只查 60 天内注单；链接有效约 30 天	原样显示厂商错误；不要把无回放当作注单不存在
funkygames	只查最近三个月内的已结算注单	超期时显示不可查询
afbslot	playback 链接只提供给赢单；其他注单仍可能只有 detail	url 为空时继续显示 detail
759gaming	回放链接有效约 1 小时	获取后不要长期缓存链接
rich88	回放链接有效约 3 分钟	需要时重新查询，不长期缓存链接
3sing	赛事结束超过 14 天不返回资料	超期时显示不可查询
allbet	只查 90 天内注单	超期时显示不可查询
metagaming	Gaming Panda 游戏（game code 167000–167035）不支持详情	显示该游戏不支持，不自动重试
scr888h5	只有赢局返回详情链接；输局可能返回游戏商错误	不把无链接当作系统故障

UI 建议

包网收到的 bet-push 不保证包含可直接判断能力的游戏商字段，所以不要仅靠前端硬编码名单隐藏按钮。可以显示“查询详情”，调用后按 code、message 和 error.error_code 展示结果；已明确返回 UNSUPPORTED_ACTION 的记录可在本地缓存能力结果。

常见失败

失败时 code 为非 0。错误可能出现在 message、error.error_code 和 error.error_message；包网应同时读取，不要只判断 HTTP 200。

message / error.error_code	说明	是否自动重试
err.hub.game_detail_lookup_fields_required	缺少 bet_id、hub_session_id 或 status	否；修正请求字段
err.hub.game_log_not_found	当前 Agent 下找不到匹配日志；也可能日志尚未送达	否；允许用户稍后手动再查
err.hub.game_log_lookup_ambiguous	匹配到多条记录，VCT 不会猜测	否；联系 VCT 支持
err.hub.game_log_storage_unavailable	VCT 日志存储暂不可用	是；有限重试
MISSING_REQUIRED_FIELD	VCT 恢复出的游戏商查询资料不完整	否；记录响应并联系 VCT 支持
INVALID_PROVIDER	当前游戏商不可用	否；联系 VCT 支持
UNSUPPORTED_ACTION	该游戏商或游戏不支持 GameDetail	否；显示不支持
PROVIDER_API_ERROR	游戏商调用失败、拒绝、注单超期或没有可用回放	默认否；保留原始响应供排查
网络错误、HTTP 5xx	请求未完成或服务暂不可用	是；指数退避，最多 2–3 次

游戏商并不一定提供回放或详情。即使查询成功，url 仍可能为空；包网应保留原注单资料作为审计依据。

给 Coding Agent 的实现规范（可直接复制）

请在当前包网项目中实现 VCT 游戏记录详情 / 回放查询，并完成后端、前端、审计与测试。

接口：POST {VCT_BASE_URL}/api/partner/v1/gamedetail
Content-Type：application/json
Authorization：Bearer {agent_token}，由包网后端使用现有 VCT Agent 凭证为每次请求即时生成；Token 不得复用或发送到浏览器。
请求字段：bet_id、hub_session_id、status 必填；round_id、request_id 可选。也兼容 betId、hubSessionId、roundId、requestId。

实现要求：
1. 字段必须取自同一条 bet-push：bet_id=wagers[].bet_id，hub_session_id=wagers[].session_id，status=wagers[].status，round_id=wagers[].round_id。
2. hub_session_id 是 VCT 会话 ID；不得误用包网内部 sessionId。
3. 只发送本接口请求参数表中定义的字段，不自行扩展未定义参数。
4. 调用必须由包网后端发出。每次调用使用新的秒级 timestamp 生成 Agent Token；API Key、Secret 和 Bearer Token 不得进入浏览器、前端 bundle、URL、普通日志或错误信息。
5. 只有业务 code=0 才算成功，HTTP 200 不代表业务成功。失败时同时读取 message、error.error_code 和 error.error_message。
6. 成功时：data.url 非空则只允许 http/https URL，并用 rel="noopener noreferrer" 的新标签页打开；data.detail 非空则按原始 JSON 格式化展示。url 为空仍可能是正常成功，不得丢弃 detail；两者都为空时显示“游戏商未提供回放或详情”。
7. UNSUPPORTED_ACTION 显示“该游戏商或游戏暂不支持详情/回放”，不得自动重试。不要把当前不支持名单写成永久前端规则；接口响应是最终依据。
8. game_log_not_found、game_log_lookup_ambiguous、参数错误、INVALID_PROVIDER 和 MISSING_REQUIRED_FIELD 不自动重试。网络错误、HTTP 5xx、game_log_storage_unavailable 最多重试 2–3 次，并使用指数退避。PROVIDER_API_ERROR 默认不自动重试。
9. 保存审计日志：request_id、查询时间、bet_id、hub_session_id、status、HTTP 状态、业务 code/message、error_code/error_message、耗时及原始响应。不得记录 Agent Secret、完整 Bearer Token 或游戏商凭证。
10. 此功能严格只读，不得修改钱包、注单金额、结算状态、回调处理状态或游戏会话。
11. 复用现有 HTTP Client、认证服务、注单详情页和错误组件，不新增第二套签名、HTTP 或 JSON 封装。

必须增加的测试：
- snake_case 与 camelCase 字段映射，并验证 snake_case 优先；
- 每次请求生成新 Token，凭证不会出现在前端或日志；
- code=0 + URL、code=0 + detail、code=0 + 空 URL、URL 非 http/https；
- 缺字段、日志不存在、日志歧义、UNSUPPORTED_ACTION、PROVIDER_API_ERROR；
- 网络超时、HTTP 5xx、有限重试次数；
- 同一 bet_id 在不同 hub_session_id/status 下不会查错记录；
- 查询操作不会写钱包、注单、结算或 session。

完成标准：后端代理、前端入口、错误状态、审计日志和测试全部完成；提供修改文件清单、测试命令与结果，不允许用 mock 成功结果替代真实响应解析。