diff --git a/docs/README.md b/docs/README.md index 2e31b5f0..1f2a69ba 100644 --- a/docs/README.md +++ b/docs/README.md @@ -35,6 +35,7 @@ | [行业电子凭证](行业电子凭证/) | 快手行业电子凭证协议 | | [发货平台-2](发货平台-2/) | 历史发货平台协议 | | [履约配置](履约配置/) | 专项接入与排障参考 | +| [虎牙绑定协议解码与角色 UID](履约配置/虎牙绑定协议解码与角色UID.md) | WUP/TAF、角色字段、`roleId` 与真实 UID 边界 | | [微博微豆-CK接口与兑换链路确认-2026-11-07](微博微豆-CK接口与兑换链路确认-2026-11-07.md) | 微博微豆接口与兑换链路 | | [打手重复奖励核对-2026-10-27](打手重复奖励核对-2026-10-27.md) | 历史财务核对记录 | diff --git a/docs/履约配置/虎牙绑定协议解码与角色UID.md b/docs/履约配置/虎牙绑定协议解码与角色UID.md new file mode 100644 index 00000000..3b72e26f --- /dev/null +++ b/docs/履约配置/虎牙绑定协议解码与角色UID.md @@ -0,0 +1,429 @@ +--- +type: external-platform-protocol-reference +description: 虎牙绑定 WUP/TAF 解码、角色字段、换绑时间与游戏角色 UID 边界。 +status: reference +version: 1.0 +updated_at: 2026-11-20 +evidence_har: 11.20-虎牙换绑角色-1.har +evidence_sha256: da089fb13d21ce120e1e6cdc522b456e2dfeae144e1f4a69916ebde025684a6e +--- + +# 虎牙绑定协议解码与角色 UID 参考 v1.0 + +> 本文是外部平台协议和排障参考,不定义订单、履约、成本或财务业务口径。 +> 业务口径仍以 [统一订单履约与财务模型-权威版](../统一订单履约与财务模型-权威版.md) 为准。 + +## 1. 文档用途 + +本文记录以下内容: + +- 虎牙绑定 HTTP/WSS 报文的实际解码链路。 +- `checkUserBindGameAccount` 和 `confirmBindActAccount` 的字段结构。 +- 虎牙 `roleId`、腾讯角色 ID、虎牙账号 UID、客户游戏角色 UID 的区别。 +- `changeBindTime` 和 `changeBindDay` 的真实语义。 +- 新抓包到来时如何验证协议是否升级。 +- 当前尚未拿到的字段和下一步抓包目标。 + +## 2. 版本与证据基线 + +### 2.1 本文版本 + +当前版本:`1.0`。 + +版本规则: + +| 变更类型 | 版本变化 | 示例 | +| --- | --- | --- | +| 文字澄清、样例修正、无字段变化 | Patch | `1.0 -> 1.0.1` | +| 新抓包验证、新增兼容字段、新增旁路接口 | Minor | `1.0 -> 1.1` | +| WUP 外层、TAF 结构、角色语义或绑定流程变化 | Major | `1.0 -> 2.0` | + +每次更新必须同时修改: + +1. 顶部 `version`。 +2. 顶部 `updated_at`。 +3. 文末“版本记录”。 +4. 新抓包的证据基线和结论。 + +### 2.2 本版证据 + +| 项目 | 值 | +| --- | --- | +| 抓包日期 | 2026-11-20 | +| 文件名 | `11.20-虎牙换绑角色-1.har` | +| 文件大小 | `58,588,070` 字节 | +| HAR 条目数 | `490` | +| SHA-256 | `da089fb13d21ce120e1e6cdc522b456e2dfeae144e1f4a69916ebde025684a6e` | +| 场景 | 已有绑定角色,换绑到另一角色,确认绑定成功后回查 | + +原始 HAR 属于本机证据,不提交仓库。文档只记录字段结论和脱敏样例。 + +## 3. 完整解码链路 + +### 3.1 报文层级 + +```text +HAR + → _webSocketMessages[].payload.buffer + → Base64 解码 + → HUYA.WebSocketCommand + → command + vData + → WUP + → WUP tag7 sBuffer + → Map + → TAF 结构体 + → checkUserBindGameAccount / confirmBindActAccount 字段 +``` + +关键点: + +- WUP/TAF 是二进制序列化协议,不是业务加密。 +- WebSocket `command=0x03` 表示 RPC 请求,`command=0x04` 表示 RPC 响应。 +- WUP 的 tag7 是 `sBuffer`,其中通常是 `tReq` 或 `tRsp`。 +- `tRsp` 是独立 TAF 结构体,需要按字段 tag 继续解码。 +- TAF 解析必须消费结构结束标记,并跳过服务端新增的兼容字段。 + +### 3.2 项目内解析代码 + +| 文件 | 用途 | +| --- | --- | +| `apps/backend/src/services/semi-auto/huya-native/taf.ts` | TAF/WUP 编解码、tag 查找、结构体尾部兼容 | +| `apps/backend/src/services/semi-auto/huya-native/huya-rpc.ts` | 虎牙 RPC 请求和绑定结构体字段解析 | +| `apps/backend/src/services/semi-auto/huya-native/huya-native-connector.ts` | 登录、查询、换绑确认、会话状态 | +| `apps/backend/src/services/semi-auto/binding-role-id.ts` | 加密 role token 与数值角色 UID 类型判断 | +| `apps/backend/scripts/audit-huya-binding-identity.ts` | 账号 UID、role token、客户角色 UID 只读审计 | + +## 4. `checkUserBindGameAccount` 完整字段 + +### 4.1 顶层 `tRsp` + +| tag | 字段 | 类型 | 说明 | +| --- | --- | --- | --- | +| 0 | `status` | int | `200` 表示成功 | +| 1 | `msg` | string | 平台消息 | +| 2 | `accountData` | struct | 账号和角色绑定事实 | +| 3 | `gameName` | string | 游戏名称 | +| 4 | `gameAuthScene` | string | 授权场景 | +| 5 | `changeBindDay` | int | 平台配置的换绑窗口天数 | + +### 4.2 `accountData` + +| tag | 字段 | 类型 | 说明 | +| --- | --- | --- | --- | +| 0 | `isBindAccount` | int | 是否已绑定游戏账号 | +| 1 | `isBindRole` | int | 是否已绑定角色 | +| 2 | `isNeedActCheck` | int | 平台活动检查标志 | +| 3 | `gameAccount` | struct | 游戏账号信息 | +| 4 | `gameRole` | struct | 游戏角色信息 | +| 5 | `changeBindTime` | int | 下一次可换绑时间的 Unix 秒 | +| 6 | 未命名兼容字段 | int | 2026-11-20 抓包固定为 `0`,不是 UID | + +### 4.3 `gameAccount` + +| tag | 字段 | 2026-11-20 实测 | +| --- | --- | --- | +| 0 | `openId` | 空 | +| 1 | `appId` | 空 | +| 2 | `type` | `wx` 或 `qq` | +| 3 | `faceUrl` | 空 | +| 4 | `nick` | 游戏账号昵称,例如 `微信用户`、`随遇而安` | +| 5 | `accessToken` | 空 | +| 6 | `extendInfo` | 空 | + +这些字段中可能有游戏账号昵称,但没有游戏角色 UID。 + +### 4.4 `gameRole` + +| tag | 字段 | 2026-11-20 实测 | +| --- | --- | --- | +| 0 | `roleId` | 40 位十六进制不透明角色 token,可能是加密值或摘要 | +| 1 | `roleName` | 有值,例如 `吃鸡199706` | +| 2 | `areaName` | 有值,例如 `微信`、`手Q` | +| 3 | `platName` | 有值,例如 `苹果(iOS)` | +| 4 | `partitionName` | 空 | +| 5 | `gameSerial` | 空 | +| 6 | `extendInfo` | 空 | + +完整解析后,`gameRole` 没有遗漏的 tag7、tag8 或其他隐藏字段。 + +## 5. 本版换绑事实 + +### 5.1 换绑前 + +同一时间存在当前角色和待确认角色: + +| 类型 | 角色名 | 区服 | role token | +| --- | --- | --- | --- | +| 当前角色 | `巫师基尔斯84` | `苹果(iOS) / 微信` | `e5649c6b...456b4c89` | +| 待确认角色 | `吃鸡199706` | `苹果(iOS) / 手Q` | `4245d97f...8103cf` | + +### 5.2 确认换绑 + +`confirmBindActAccount` 请求只携带账号授权、`gid` 和活动参数,不携带独立游戏角色 UID。 + +平台响应: + +```text +status = 200 +msg = 请求成功 +``` + +### 5.3 换绑后 + +回查时当前角色变成: + +| 字段 | 值 | +| --- | --- | +| `roleName` | `吃鸡199706` | +| `areaName` | `手Q` | +| `platName` | `苹果(iOS)` | +| `roleId` | `4245d97f...8103cf` | + +结论: + +- `roleId` 在同一角色重复查询时保持稳定。 +- 换到不同角色后 `roleId` 变化。 +- 因此 `roleId` 可以作为平台角色身份变化判断,但不是可展示的游戏角色 UID。 + +## 6. `roleId` 的性质和边界 + +### 6.1 已确认 + +- 长度为 40 个十六进制字符。 +- 二进制长度为 20 字节。 +- 线路上没有密钥、IV、加密块边界或明文字段。 +- 相同角色稳定,不同角色不同。 +- 不能把 `roleId` 与 9 到 19 位数字游戏角色 UID 直接比较。 +- 不能用虎牙账号 UID、客户角色 UID 或腾讯账号 UID 回填该字段。 + +### 6.2 未确认 + +仅凭当前报文无法证明其具体算法。它可能是: + +- SHA-1/HMAC 一类的角色指纹。 +- 平台侧不可逆映射。 +- 平台内部加密后只暴露 token。 + +对本项目而言,结论一致:把它当作不透明 token 使用。 + +允许: + +- 在 Connector 内判断前后两次查询是否仍是同一角色。 +- 在确认 pending 角色时防止页面快照和平台 pending 不一致。 + +禁止: + +- 展示为客户游戏角色 UID。 +- 从 token 推导 UID。 +- 用 token 与客户填写的 UID 比较。 +- 把 token 写入 `platform_game_role_uid`。 + +## 7. `changeBindTime` 语义 + +2026-11-20 换绑 HAR 实证: + +| 场景 | `changeBindTime` | `changeBindDay` | +| --- | --- | --- | +| 换绑前当前角色 | `1794758400`,即 `2026-11-16 00:00 +08:00` | `7` | +| 换绑后当前角色 | `1795708800`,即 `2026-11-27 00:00 +08:00` | `7` | + +结论: + +- `changeBindTime` 是平台给出的“下一次可换绑时间”。 +- `changeBindDay` 是平台配置的窗口天数。 +- 不得把 `changeBindTime` 当成上次换绑时间再叠加 7 天。 +- 当 `changeBindTime` 缺失时,才允许用 `changeBindDay` 做保守估算。 + +## 8. 腾讯 `livelink` 侧的真实角色标识 + +### 8.1 本 HAR 实际调用的接口 + +本次虎牙绑定页实际只调用了腾讯二维码链路: + +```text +POST /api/qrcode/getMiniAppQrcode +POST /api/qrcode/poolingQrcodeStatus +``` + +二维码状态只有: + +```json +{ + "isScan": true, + "isExpired": false, + "isCompleted": true +} +``` + +没有返回角色名或角色 UID。 + +### 8.2 腾讯前端包中存在的角色接口 + +`livelink.qq.com` 前端包声明了以下接口: + +```text +POST /api/h5/getBoundGameRoleInfoInH5 +POST /api/h5/GetBoundGameRoleInfoWithSessionInH5 +POST /api/h5/getGameRolesByGameInfo +POST /api/h5/getRelatedGameRolesByGameToken +``` + +前端使用字段: + +```text +gameRoleStr = gameOpenId|roleId|platId|areaId|partitionId +``` + +前端代码会把 `gameRoleStr` 按 `|` 拆成五段: + +```js +const [gameOpenId, roleId, platId, areaId, partitionId] = gameRoleStr.split('|') +``` + +其中第二段 `roleId` 才是腾讯角色 UID 的候选来源。 + +### 8.3 为什么本 HAR 仍拿不到 + +本次用户在微信或 QQ 小程序里选择角色,角色列表请求发生在小程序网络环境, +没有被 Chrome HAR 捕获。 + +本 HAR 没有调用: + +```text +/api/h5/getGameRolesByGameInfo +/api/h5/getBoundGameRoleInfoInH5 +/api/h5/getRelatedGameRolesByGameToken +``` + +因此当前只能确认腾讯侧存在角色 ID,不能确认其具体值,也不能确认它和虎牙 +40 位 `roleId` 的映射关系。 + +### 8.4 下一次需要补抓的报文 + +需要补抓上述任一接口的成功响应,重点保存: + +```text +gameRoleStr +roleName +platName +areaName +partitionName +gameOpenId +``` + +如果 `gameRoleStr` 第二段是纯数字,并且与客户填写的游戏角色 UID 一致,才能作为 +`platform_game_role_uid` 的真实来源。 + +## 9. 项目当前处理规则 + +| 身份 | 来源 | 用途 | 是否可展示 | +| --- | --- | --- | --- | +| 虎牙账号 UID | 登录 Cookie / 登录响应 | WUP 请求身份 | 可展示账号 UID | +| 虎牙 `roleId` | `gameRole.roleId` | 平台前后角色一致性判断 | 不展示 | +| 客户游戏角色 UID | 客户填写 | 订单目标角色资料 | 可展示为目标 UID | +| 平台游戏角色 UID | `gameSerial` / `extendInfo` 明确数值字段 | 与客户 UID 比对 | 仅真实返回时展示 | +| 腾讯 `gameRoleStr.roleId` | 腾讯角色接口 | 候选真实 UID | 需要先抓包确认 | + +当前自动比对规则: + +1. 角色名和区服必须一致。 +2. 平台明确返回数值 UID 时,再额外比较 UID。 +3. 加密 `roleId` 只用于判断 current 与 pending 是否变化。 +4. 没有真实 UID 时不得伪造,也不得声称已经拿到平台角色 UID。 + +只读审计命令: + +```bash +cd apps/backend +npm run audit:huya-binding-identity +npm run audit:huya-binding-identity -- --strict +``` + +## 10. 新抓包更新流程 + +### 10.1 保存证据 + +1. 新 HAR 使用“日期-场景-序号”命名。 +2. 记录文件大小、条目数和 SHA-256。 +3. 原始 HAR 不提交,保留在本机抓包目录。 +4. 文档只记录脱敏字段和结论。 + +### 10.2 解析 WSS 帧 + +1. 读取 `_webSocketMessages[].payload.buffer`。 +2. Base64 解码。 +3. 解 WebSocket command 和 `vData`。 +4. 解 WUP tag7 `sBuffer`。 +5. 解 `tReq` / `tRsp` TAF 结构。 +6. 记录所有顶层、嵌套结构实际出现的 tag。 +7. 检查结构结束标记之后是否还有新增字段。 + +### 10.3 必查接口 + +```text +webActUI.checkUserBindGameAccount +webActUI.confirmBindActAccount +webActUI.getLiveLinkParam +huyauserui.getUserProfile +``` + +如果页面进入腾讯角色列表,还要检查: + +```text +/api/h5/getGameRolesByGameInfo +/api/h5/getBoundGameRoleInfoInH5 +/api/h5/getRelatedGameRolesByGameToken +``` + +### 10.4 必查字段 + +```text +roleName +roleId +gameSerial +extendInfo +gameAccount.openId +gameAccount.extendInfo +changeBindTime +changeBindDay +gameRoleStr +``` + +### 10.5 版本更新 + +1. 字段语义不变,只补样例或说明:Patch。 +2. 新增字段、新旁路接口或新 HAR 验证:Minor。 +3. WUP/TAF 外形或角色语义改变:Major。 +4. 更新顶部版本、日期、证据哈希和文末版本记录。 +5. 如果业务规则发生变化,只更新唯一权威文档,不在本文另立业务口径。 + +## 11. 数据安全 + +文档和日志禁止记录: + +- 完整 Cookie。 +- `udb_cred`、`udb_biztoken`。 +- 二维码 token。 +- 短信验证码。 +- 完整账号级凭证。 + +允许记录: + +- 字段名。 +- 字段类型。 +- 脱敏后的角色 token。 +- 角色名和区服样例。 +- 接口路径和解析结论。 + +## 12. 当前未解决问题 + +1. 虎牙 `roleId` 的具体生成算法没有证据,按不透明 token 处理。 +2. 当前 HAR 没有腾讯角色接口响应,真实游戏角色 UID 仍未取得。 +3. 腾讯 `gameRoleStr` 第二段是否就是目标游戏角色 UID,需要新抓包验证。 +4. 小程序内角色选择请求需要小程序抓包或腾讯 H5 登录链路才能覆盖。 + +## 13. 版本记录 + +| 版本 | 日期 | 变更 | +| --- | --- | --- | +| 1.0 | 2026-11-20 | 建立文档;完整解析虎牙绑定 WUP/TAF;确认 `roleId` 为不透明 token、`gameSerial` 和 `extendInfo` 为空;修正 `changeBindTime` 为下一次可换绑时间;确认腾讯侧存在 `gameRoleStr` 角色接口但本 HAR 未调用 |