修复(半自动履约): 虎牙绑定仅核验角色名与区服

This commit is contained in:
yml
2026-11-20 17:01:16 +08:00
parent 98ac7e7d1b
commit f4806fb758
15 changed files with 149 additions and 111 deletions
@@ -2,13 +2,13 @@
type: external-platform-protocol-reference
description: 虎牙绑定 WUP/TAF 解码、角色字段、换绑时间与游戏角色 UID 边界。
status: reference
version: 1.0
version: 1.1
updated_at: 2026-11-20
evidence_har: 11.20-虎牙换绑角色-1.har
evidence_sha256: da089fb13d21ce120e1e6cdc522b456e2dfeae144e1f4a69916ebde025684a6e
---
# 虎牙绑定协议解码与角色 UID 参考 v1.0
# 虎牙绑定协议解码与角色 UID 参考 v1.1
> 本文是外部平台协议和排障参考,不定义订单、履约、成本或财务业务口径。
> 业务口径仍以 [统一订单履约与财务模型-权威版](../统一订单履约与财务模型-权威版.md) 为准。
@@ -28,7 +28,7 @@ evidence_sha256: da089fb13d21ce120e1e6cdc522b456e2dfeae144e1f4a69916ebde025684a6
### 2.1 本文版本
当前版本:`1.0`。
当前版本:`1.1`。
版本规则:
@@ -311,8 +311,9 @@ partitionName
gameOpenId
```
如果 `gameRoleStr` 第二段是纯数字,并且与客户填写的游戏角色 UID 一致,才能作为
`platform_game_role_uid` 的真实来源。
如果 `gameRoleStr` 第二段是纯数字,可以作为 `platform_game_role_uid` 的候选真实来源。
即使取得该值,它也只用于可选展示和排障留档,不参与虎牙绑定自动判定,也不要求与客户填写的
游戏角色 UID 一致。
## 9. 项目当前处理规则
@@ -320,16 +321,17 @@ gameOpenId
| --- | --- | --- | --- |
| 虎牙账号 UID | 登录 Cookie / 登录响应 | WUP 请求身份 | 可展示账号 UID |
| 虎牙 `roleId` | `gameRole.roleId` | 平台前后角色一致性判断 | 不展示 |
| 客户游戏角色 UID | 客户填写 | 订单目标角色资料 | 可展示为目标 UID |
| 平台游戏角色 UID | `gameSerial` / `extendInfo` 明确数值字段 | 与客户 UID 比对 | 仅真实返回时展示 |
| 腾讯 `gameRoleStr.roleId` | 腾讯角色接口 | 候选真实 UID | 需要先抓包确认 |
| 客户游戏角色 UID | 客户填写 | 可选订单资料留档 | 可展示为目标 UID |
| 平台游戏角色 UID | `gameSerial` / `extendInfo` 明确数值字段 | 可选观测和展示,不参与绑定门禁 | 仅真实返回时展示 |
| 腾讯 `gameRoleStr.roleId` | 腾讯角色接口 | 候选真实 UID,仅可选留档 | 需要先抓包确认 |
当前自动比对规则:
1. 角色名和区服必须一致。
2. 平台明确返回数值 UID 时,再额外比较 UID。
2. 客户游戏角色 UID 和平台数值角色 UID 都不参与绑定 verdict;UID 缺失、不同或未返回都不阻断绑定。
3. 加密 `roleId` 只用于判断 current 与 pending 是否变化。
4. 没有真实 UID 时不得伪造,也不得声称已经拿到平台角色 UID。
5. 平台数值 UID 可以展示和留档,但不得改变角色名、区服决定的绑定结果。
只读审计命令:
@@ -426,4 +428,5 @@ gameRoleStr
| 版本 | 日期 | 变更 |
| --- | --- | --- |
| 1.1 | 2026-11-20 | 业务核验规则收口为角色名和平台区服;客户游戏角色 UID 改为可选留档,平台数值角色 UID 只作可选观测,均不参与绑定门禁 |
| 1.0 | 2026-11-20 | 建立文档;完整解析虎牙绑定 WUP/TAF;确认 `roleId` 为不透明 token、`gameSerial` 和 `extendInfo` 为空;修正 `changeBindTime` 为下一次可换绑时间;确认腾讯侧存在 `gameRoleStr` 角色接口但本 HAR 未调用 |
@@ -3,7 +3,7 @@ type: 权威架构与实施计划
description: 订单、内部 SKU、履约路由、履约执行、商品、成本与财务的唯一权威口径及重构计划。
tags: [订单, 内部SKU, 履约, 商品, 成本, 财务, 迁移]
status: authoritative
version: 2.32
version: 2.33
updated_at: 2026-11-20
---
@@ -318,20 +318,21 @@ manual fulfillment
- 半自动任务必须在 manual 渠道判定、人工配置保存/重匹配或 Carrier 补配成功后按订单项主动物化,
不能依赖客户先打开 `/c/<订单号>` 或客服先打开半自动任务列表。后台和客户页的幂等回填仅作为兜底。
- 虎牙客户页流程固定为「填写资料 → 登录虎牙账号 → 绑定角色 → 客服处理」:
① 资料三项(区服、游戏角色 UID、角色名)必须先保存,未填全时不得展示虎牙登录或生成绑定二维码,
页面状态显示「待客户填写资料」;
① 必填资料为区服和角色名,二者必须先保存;未填全时不得展示虎牙登录或生成绑定二维码,
页面状态显示「待客户填写资料」。游戏角色 UID 是选填订单资料,不阻断登录、绑定或完成履约;
② 虎牙账号 UID(`huya_uid`)只用于 WUP/RPC 请求身份,与客户填写的游戏角色 UID 没有任何对应关系,
禁止互相回退或比较;
③ 虎牙 `gameRole.roleId` 是 40 位加密 opaque token,只可在 Connector 内部用于判断前后两次查询
是否仍是同一角色;客户页、管理端和历史摘要不得展示该标识,也不得把它当角色 UID;
④ 平台返回 `gameSerial` 或 `gameRole.extendInfo` 中明确的数值角色 UID 时,必须分别保存到
`platform_game_role_uid` / `pending_platform_game_role_uid` 并纳入角色比对;当前实际响应可能
不返回独立数值 UID,此时页面只能展示客户填写的目标角色 UID,并明确平台未提供绑定角色 UID,
不得由加密 token、账号 UID 或客户 UID 互相回填;
④ 客户填写的游戏角色 UID 只作可选留档;平台返回 `gameSerial` 或 `gameRole.extendInfo` 中明确的
数值角色 UID 时,可分别保存到 `platform_game_role_uid` / `pending_platform_game_role_uid`
供展示和排障,但不得纳入绑定 verdict。当前实际响应可能不返回独立数值 UID,页面不得由加密 token、
账号 UID 或客户 UID 互相回填;
⑤ 客户确认前必须通过 outer/inner 双路查询得到本次 pending 角色;确认绑定必须先呈现 pending 角色,
客户明确提交后才调用 `confirmBindActAccount`,写后回查 current 角色与 pending 一致才能进入
`binding_status = confirmed`。确认请求必须携带页面已核对的角色名、role token 与渠道快照,
Connector 发现 pending 已变化时拒绝写入;轮询和二维码刷新不得自动提交平台写操作。
自动判定固定只比较角色名与平台区服,客户明确提交后才调用 `confirmBindActAccount`,写后回查
current 角色与 pending 的角色名、区服和 role token 一致才能进入 `binding_status = confirmed`。
确认请求必须携带页面已核对的角色名、role token 与渠道快照,Connector 发现 pending 已变化时
拒绝写入;轮询和二维码刷新不得自动提交平台写操作。
- 角色不一致时客户页固定提供两个动作:「重新扫码换绑」和「上一步修改资料」。
平台已有旧角色导致首次不一致、扫码绑定后不一致、换绑被虎牙拒绝或未生效时,以重新扫码换绑为主;
换绑后仍不一致时以「上一步修改资料」为主。取消「直接使用原角色」的快捷确认:
@@ -339,10 +340,11 @@ manual fulfillment
平台未返回角色名或比对缺项时,只提供「复制订单号联系客服」和「刷新状态」。
- 客户点「上一步修改资料」时清空当前绑定与换绑失败状态:`binding_status` 回到 `not_started`,
清空 `bind_game_*`、`bound_at`、`last_error` 与换绑失败痕迹(`rebindUnchanged`/`rebindConfirmState` 等),
但保留登录状态、`credential_id`、`connector_session_id` 和客户已填资料三项。页面回到第一步并保留资料可编辑,
但保留登录状态、`credential_id`、`connector_session_id`、客户角色名与区服,以及已填写的可选 UID。
页面回到第一步并保留资料可编辑,
客户重新「提交资料」后重新识别平台角色、重新生成绑定二维码,不能复用旧的换绑失败状态。
- 登录状态和执行状态保存于 `semi_auto_tasks`,不得写入 `material_json` 作为正式状态。
`binding_status`、`bind_game_*`、`bind_game_role_token`、pending 角色、`bound_at` 和客户资料三项
`binding_status`、`bind_game_*`、`bind_game_role_token`、pending 角色、`bound_at` 和客户角色资料
属于正式绑定流程,
迁移 `168`、`169` 已落库;绑定确认后执行状态才进入 `waiting_operator`。
- 平台 CK 是账号级凭证,唯一持久化真源为 `semi_auto_credentials`。Cookie 集合按平台 UID 唯一保存,
@@ -403,8 +405,8 @@ manual fulfillment
- 半自动履约状态采用与斗鱼领取一致的同步原则:客户操作、Connector 回调和后台操作都是状态快照输入,
统一由一个状态收敛服务在任务行锁内写入正式字段并追加事件;多个入口不得各自拼接或覆盖状态。
- 账号绑定能力由平台声明,不由页面或业务服务按平台散落判断。虎牙、斗鱼、微博均为 `game_role`:
虎牙必需字段为 `roleName / serverZone`;平台若未来明确返回独立数值游戏角色 UID,才额外启用
`roleId` 核验,`gameRole.roleId` 加密 token 本身不参与客户资料比对;
虎牙必需字段为 `roleName / serverZone`;客户游戏角色 UID 和平台可能返回的独立数值游戏角色 UID
都只作可选留档,不启用额外 `roleId` 核验,`gameRole.roleId` 加密 token 本身也不参与客户资料比对;
斗鱼必需字段 `roleName / serverZone`,由 live-hub 查询和提交换绑;
微博必需字段 `roleName`,由 order_site 查询,微信/QQ 扫码完成绑定或换绑,不要求客户重复填写角色资料。
公共策略还必须声明 `confirmationMode` 与 `rebindMode`:虎牙、斗鱼为客户资料比对确认,
@@ -751,10 +753,11 @@ has_active_cost
```
- 虎牙三步进度固定为「填写游戏资料 → 登录虎牙账号 → 绑定游戏角色」,当前步骤高亮,已完成为勾选。
- 资料三项(区服 / 游戏角色 UID / 角色名)未填全时不展示虎牙登录和绑定二维码;资料保存后才引导登录。
- 绑定角色页分别展示虎牙账号 UID、当前平台角色、本次待确认角色与客户资料;角色名和区服一致才允许确认绑定,
客户游戏角色 UID 不与虎牙账号 UID 或平台加密 role token 比对;平台返回独立数值角色 UID 时同时展示
当前角色与待确认角色 UID,未返回时只能展示客户填写的目标角色 UID,不得把加密 role token 显示成 UID;
- 必填资料为区服和角色名,未填全时不展示虎牙登录和绑定二维码;游戏角色 UID 为选填留档,不影响门禁。
- 绑定角色页分别展示虎牙账号 UID、当前平台角色、本次待确认角色与客户资料;自动判定固定只比较角色名与
平台区服,角色名和区服一致才允许确认绑定。客户游戏角色 UID、平台可能返回的数值角色 UID 都不参与
绑定 verdict,也不与虎牙账号 UID 或加密 role token 比较;数值 UID 可展示和留档,不得把加密 role token
显示成 UID;
不一致时固定显示「重新扫码换绑」「上一步修改资料」,换绑后仍不一致时以修改资料为主。
- 微博登录成功后直接展示微信/QQ 绑定入口;平台返回已绑定角色时直接进入等待客服,
未绑定时展示扫码二维码,扫码后重新读取平台角色,角色名发生变化才视为换绑成功。
@@ -1208,12 +1211,14 @@ pending 角色快照、`role_identity_source` 与 `verification_basis`。
允许旧任务保留审计、新配置创建新的活动任务。确认绑定写平台前先持久化 `submitting`,重启或超时后
只按数据库 pending 与平台 current 回查收敛,不得重复提交平台写操作。
迁移 `179` 将当前角色与待确认角色的平台数值 UID 分开持久化,禁止把待确认角色 UID 写入当前角色字段;
加密 role token 与数值角色 UID 是两个独立字段,任何情况下都不得互相回填。
迁移 `169` 增加客户游戏角色资料三项(`customer_game_role_name` / `customer_game_role_id` /
`customer_game_server_zone`),并允许从工单素材回退合并;客户页流程收敛为
「填写资料 → 登录 → 绑定角色」,资料未填全不得展示登录或绑定二维码。
加密 role token 与数值角色 UID 是两个独立字段,任何情况下都不得互相回填。数值角色 UID 仅作可选展示和
排障留档,不进入绑定 verdict。
迁移 `169` 增加客户游戏角色资料字段(`customer_game_role_name` / `customer_game_role_id` /
`customer_game_server_zone`),并允许从工单素材回退合并;其中角色名和区服必填,`customer_game_role_id`
为可选留档。客户页流程收敛为「填写资料 → 登录 → 绑定角色」,必填资料未填全不得展示登录或绑定二维码。
迁移 `170` 增加半自动全链路报文日志,客户页、管理端和外部 Connector 共用同一追踪口径;
虎牙角色自动比对改为角色名与区服;账号 UID、加密 role token、客户游戏角色 UID 三类身份禁止混用。
虎牙角色自动比对固定为角色名与区服;账号 UID、加密 role token、客户游戏角色 UID、平台数值角色 UID
四类身份禁止混用,后两者不参与绑定门禁。
只读审计命令为 `npm run audit:huya-binding-identity -- --strict`。历史 `legacy_*` 留档只用于追溯,
当前字段出现账号 UID 复用、非法 role token、非法平台角色 UID,或平台角色 UID 由账号 UID
回填时,严格审计必须失败。
@@ -1234,8 +1239,8 @@ pending 角色快照、`role_identity_source` 与 `verification_basis`。
6. 半自动平台负责客户登录、账号 CK 获取和游戏角色绑定;微博支持手机号登录、易盾二次验证、
完整域名 Cookie 保存、会话恢复、游戏角色查询和微信/QQ 扫码绑定;虎牙支持客户手动触发的
短信验证码登录和扫码登录。
虎牙客户必须先填写区服 / 游戏角色 UID / 角色名,再登录账号并进入绑定;虎牙账号 UID 只用于登录请求,
客户游戏角色 UID 作为订单目标资料,平台明确返回独立数值角色 UID 时必须另行保存并参与比对。
角色名与区服一致后,客户确认本次 pending 角色才可提交平台绑定;不一致时只能重新扫码换绑或返回
上一步修改资料,不提供直接使用原角色的快捷确认。
虎牙客户必须先填写区服 / 角色名,再登录账号并进入绑定;游戏角色 UID 可选留档,虎牙账号 UID
只用于登录请求。角色名与平台区服一致后,客户确认本次 pending 角色才可提交平台绑定;客户填写的
UID 与平台可能返回的数值角色 UID 不参与自动判定。不一致时只能重新扫码换绑或返回上一步修改资料,
不提供直接使用原角色的快捷确认。
7. 观察期结束后,再单独发布兼容表、旧脚本别名和 `legacy_*` 字段的删除迁移。