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

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
@@ -1,4 +1,4 @@
/** 只有平台独立返回的纯数字游戏角色 UID 才能作为自动核验依据。 */
/** 判断平台是否独立返回了纯数字游戏角色 UID;该值只作可选留档,不参与绑定核验。 */
export function isNumericBindingRoleId(value: unknown): boolean {
return /^\d+$/.test(String(value ?? '').trim())
}
@@ -3,6 +3,7 @@ import test from 'node:test'
import {
classifyHuyaRebindFailure,
compareHuyaBindingRole,
resolveHuyaBindingDecision,
resolveHuyaRoleRebindAvailability,
roleSnapshotsFromLegacyFields,
@@ -90,6 +91,25 @@ test('已有角色且就是目标角色时直接确认当前角色', () => {
assert.equal(decision.primaryAction, 'confirm_current_role')
})
test('平台数值角色 UID 与客户填写值不同,也不阻断角色名区服核验', () => {
const decision = resolveHuyaBindingDecision(
input({
current: role({
roleName: TARGET.roleName,
platformRoleUid: '99887766',
}),
bindingStatus: 'role_ready',
}),
)
assert.equal(decision.targetRoleMatch, 'match')
assert.equal(decision.flowState, 'current_role_confirmable')
assert.equal(decision.comparison.verificationBasis, 'role_name_zone')
const direct = compareHuyaBindingRole(TARGET, role({ roleName: TARGET.roleName }))
assert.equal(direct.verdict, 'match')
assert.equal(direct.verificationBasis, 'role_name_zone')
})
test('平台原始状态为 confirmed 时仍以唯一决策器的目标匹配结果为准', () => {
const matched = resolveHuyaBindingDecision(
input({
@@ -146,31 +146,30 @@ function comparisonBase(customer: HuyaCustomerRoleSnapshot, role: HuyaRoleSnapsh
const roleName = readString(role?.roleName)
const roleToken = readString(role?.roleToken)
const platformRoleUid = readString(role?.platformRoleUid)
const numericPlatformRoleUid = isNumericBindingRoleId(platformRoleUid) ? platformRoleUid : ''
const boundZone = resolveServerZone(role?.channel)
return {
customerRoleName,
customerRoleId,
customerZone,
boundRoleName: roleName,
boundRoleId: platformRoleUid || roleToken,
boundRoleIdKind: platformRoleUid
boundRoleId: numericPlatformRoleUid || roleToken,
boundRoleIdKind: numericPlatformRoleUid
? ('game_role_uid' as const)
: isHuyaRoleToken(roleToken)
? ('huya_role_token' as const)
: ('missing' as const),
boundZone,
verificationBasis: platformRoleUid
? ('platform_numeric_uid' as const)
: ('role_name_zone' as const),
platformRoleUid,
verificationBasis: 'role_name_zone' as const,
platformRoleUid: numericPlatformRoleUid,
}
}
/**
* 虎牙角色比对的唯一入口。
*
* 当前虎牙只稳定返回角色名、区服和可选的数值平台角色 UID。
* 40 位加密 role token 只用于判断平台前后角色是否变化,不参与客户资料比对。
* 绑定放行固定只比较角色名和平台区服。可选的数值平台角色 UID 仅用于展示和留档;
* 40 位加密 role token 只用于判断平台前后角色是否变化,二者都不参与客户资料放行。
*/
export function compareHuyaBindingRole(
customer: HuyaCustomerRoleSnapshot,
@@ -179,9 +178,7 @@ export function compareHuyaBindingRole(
const base = comparisonBase(customer, role)
const policy = getAccountBindingPolicy('huya')
const comparison = compareBindingIdentity({
requiredFields: base.platformRoleUid
? [...policy.requiredFields, 'roleId']
: policy.requiredFields,
requiredFields: policy.requiredFields,
customer: {
roleName: base.customerRoleName,
roleId: base.customerRoleId,
@@ -205,19 +202,15 @@ export function compareHuyaBindingRole(
}
}
if (comparison.verdict === 'mismatch') {
const message = comparison.mismatched.includes('roleId')
? '两侧游戏角色 UID 不一致,无法提交平台绑定'
: comparison.mismatched.includes('roleName')
? '两侧角色名称不一致,无法提交平台绑定'
: '两侧区服不一致,无法提交平台绑定'
const message = comparison.mismatched.includes('roleName')
? '两侧角色名称不一致,无法提交平台绑定'
: '两侧区服不一致,无法提交平台绑定'
return { ...base, verdict: 'mismatch', message, missing, mismatched }
}
return {
...base,
verdict: 'match',
message: base.platformRoleUid
? '两侧区服、角色名称、平台角色 UID 一致,可提交平台绑定'
: '角色名称与区服一致,请确认绑定本次待确认角色',
message: '角色名称与区服一致,请确认绑定本次待确认角色',
missing,
mismatched,
}
@@ -1749,11 +1749,7 @@ export class HuyaNativeConnector {
: binding.role
? 'huya_outer_current'
: '',
verificationBasis: binding.roleUid
? 'platform_numeric_uid'
: binding.role
? 'role_name_zone'
: '',
verificationBasis: binding.role || binding.pendingRole ? 'role_name_zone' : '',
roleIdVerified,
requiresSupport,
hasExistingBinding: binding.hasExistingBinding,
@@ -5,6 +5,7 @@ import { isHuyaRoleToken, isNumericBindingRoleId } from './binding-role-id.js'
import {
compareBindingRole,
detectServerZone,
hasCustomerProfile,
normalizeCustomerProfile,
} from './semi-auto-task-service.js'
@@ -116,7 +117,7 @@ describe('虎牙角色比对', () => {
assert.match(missingZone.message, /客户区服/)
})
it('平台明确返回数值角色 UID 时才启用数值核验', () => {
it('平台返回数值角色 UID 时仍只按角色名与区服核验', () => {
const result = compareBindingRole(task('落地盒子怪cc', '4212063544', '安卓Q区'), {
bindGameRole: '落地盒子怪cc',
bindGameRoleToken: HUYA_ROLE_TOKEN,
@@ -125,22 +126,43 @@ describe('虎牙角色比对', () => {
})
assert.equal(result.verdict, 'match')
assert.equal(result.boundRoleIdKind, 'game_role_uid')
assert.equal(result.verificationBasis, 'platform_numeric_uid')
assert.equal(result.verificationBasis, 'role_name_zone')
})
it('平台未来返回数值角色 UID 时,数值不同也不能确认', () => {
it('平台返回数值角色 UID 且与客户填写值不同,仍按角色名区服放行', () => {
const result = compareBindingRole(task('落地盒子怪cc', '4212063544', '安卓Q区'), {
bindGameRole: '落地盒子怪cc',
bindGameRoleToken: HUYA_ROLE_TOKEN,
bindGameChannel: '安卓(android) · QQ',
platformGameRoleUid: '4212063545',
})
assert.equal(result.verdict, 'mismatch')
assert.match(result.message, /游戏角色 UID/)
assert.equal(result.verdict, 'match')
assert.equal(result.verificationBasis, 'role_name_zone')
assert.match(result.message, /角色名称与区服一致/)
})
})
describe('客户角色资料校验', () => {
it('角色名和区服齐全时,游戏角色 UID 可以留空', () => {
const profile = normalizeCustomerProfile({
roleName: '落地盒子怪cc',
roleId: '',
serverZone: '安卓Q区',
})
assert.deepEqual(profile, {
roleName: '落地盒子怪cc',
roleId: '',
serverZone: '安卓Q区',
})
assert.equal(
hasCustomerProfile({
customer_game_role: '落地盒子怪cc',
customer_server_zone: '安卓Q区',
}),
true,
)
})
it('清理空白并保留纯数字游戏角色 UID', () => {
const profile = normalizeCustomerProfile({
roleName: ' 落地盒子怪cc ',
@@ -168,10 +190,10 @@ describe('客户角色资料校验', () => {
)
})
it('角色名称与游戏角色 UID 都为空时拒绝保存', () => {
it('角色名称为空时拒绝保存', () => {
assert.throws(
() => normalizeCustomerProfile({ roleName: ' ', roleId: '', serverZone: '安卓Q区' }),
/请完整填写区服/,
/请完整填写区服和角色名/,
)
})
})
@@ -123,8 +123,8 @@ export function normalizeCustomerProfile(input: CustomerProfileInput = {}) {
errorCode: 'semi_auto_profile_server_zone_invalid',
})
}
if (!roleName || !roleId) {
throw createHttpError('请完整填写区服、游戏角色 UID 和角色名', {
if (!roleName || !serverZone) {
throw createHttpError('请完整填写区服和角色名', {
statusCode: 400,
errorCode: 'semi_auto_profile_required',
})
@@ -134,7 +134,7 @@ export function normalizeCustomerProfile(input: CustomerProfileInput = {}) {
/**
* 半自动订单没有 work_orders,客户资料在授权页 /c/<订单号>(虎牙)或 /d/<订单号>(微博)收集。
* 虎牙先保存目标角色资料,再登录账号;保存后立即参与平台角色比对。
* 虎牙先保存目标角色名和区服,再登录账号;游戏角色 UID 可选留档,不参与绑定核验。
*/
export async function savePublicTaskProfile(
orderNoInput: unknown,
@@ -257,12 +257,10 @@ export function normalizeOrderNo(value: unknown): string {
/** 客户资料以 TASK_SELECT 合并后的字段为准:优先任务表,回退工单资料。 */
export function hasCustomerProfile(
task: Pick<TaskRow, 'customer_game_id' | 'customer_game_role' | 'customer_server_zone'>,
task: Pick<TaskRow, 'customer_game_role' | 'customer_server_zone'>,
): boolean {
return Boolean(
String(task.customer_game_id || '').trim() &&
String(task.customer_game_role || '').trim() &&
String(task.customer_server_zone || '').trim(),
String(task.customer_game_role || '').trim() && String(task.customer_server_zone || '').trim(),
)
}
@@ -433,12 +431,7 @@ export function displayStatus(task: TaskRow, decision = resolveTaskHuyaBindingDe
return status('processing', '处理中', 'operator', '客服继续履约')
}
if (bindingPolicy.requiresCustomerProfile && !hasCustomerProfile(task)) {
return status(
'waiting_profile',
'待客户填写资料',
'customer',
'客户填写区服、游戏角色 UID 和角色名',
)
return status('waiting_profile', '待客户填写资料', 'customer', '客户填写区服和角色名')
}
if (task.login_status === 'authenticated') {
if (task.platform === 'huya' && decision) {
@@ -754,7 +747,7 @@ export function assertHuyaTask(task: TaskRow) {
/**
* 半自动订单没有工单时,客户资料在登录后由 /c/<订单号> 收集;
* 任务表为空但工单素材已有资料时,TASK_SELECT 会合并回退字段。
* 进入绑定/确认/换绑前必须已有完整三项资料。
* 进入绑定/确认/换绑前必须已有角色名和区服;游戏角色 UID 可选。
*/
export function assertCustomerProfileReady(task: TaskRow) {
if (!getAccountBindingPolicy(task.platform).requiresCustomerProfile) return
@@ -1354,9 +1347,8 @@ export function detectServerZone(channel: unknown): string {
}
/**
* 虎牙账号 UID 与游戏角色 UID 无关。当前虎牙接口只稳定返回角色名、区服和
* opaque role token,因此自动放行依据固定为角色名 + 区服。客户角色 UID
* 只作为订单资料留档,除非平台明确返回独立数值角色 UID,否则不参与比对。
* 虎牙账号 UID 与游戏角色 UID 无关。自动放行依据固定为角色名 + 平台区服;
* 客户角色 UID 和平台可能返回的数值角色 UID 都只作可选留档,不参与比对。
*/
export function compareBindingRole(
task: Pick<TaskRow, 'customer_game_id' | 'customer_game_role' | 'customer_game_server_zone'>,
@@ -1396,9 +1396,9 @@ test(
const saved = await savePublicTaskProfile(orderNo, result.taskId, {
roleName: 'Mock虎牙角色',
roleId: '1192083858',
serverZone: '安卓V区',
})
assert.equal(saved.task.customerGameRoleId, '')
assert.equal(saved.task.loginStatus, 'waiting_login')
assert.equal(saved.task.displayStatus.label, '等待客户授权')
@@ -1427,7 +1427,7 @@ test(
assert.equal(tasks[0]?.executionStatus, 'waiting_customer')
assert.equal(tasks[0]?.displayStatus.label, '等待客户绑定角色')
assert.equal(tasks[0]?.customerGameRoleName, 'Mock虎牙角色')
assert.equal(tasks[0]?.customerGameRoleId, '1192083858')
assert.equal(tasks[0]?.customerGameRoleId, '')
assert.equal(tasks[0]?.credentialSource, 'sms')
assert.ok(tasks[0]?.huyaUid)
assert.equal(tasks[0]?.platformNickname, 'Mock虎牙用户')
@@ -849,9 +849,7 @@ export default function AdminSemiAutoTasksPage() {
}
>
{detail.comparison?.verdict === 'match'
? detail.comparison.verificationBasis === 'platform_numeric_uid'
? '角色名、区服和平台角色 UID 一致,可提交平台绑定'
: '角色名与区服一致,可提交平台绑定'
? '角色名与区服一致,可提交平台绑定'
: detail.comparison?.verdict === 'mismatch'
? '资料与平台角色不一致'
: '信息不完整,需人工核实'}
@@ -116,11 +116,10 @@ export default function CustomerFulfillmentPage({
),
)
const isWeibo = selectedTask?.platform === 'weibo'
// 虎牙流程:填写资料(区服/游戏角色 UID/角色名)→ 登录 → 绑定角色。
// 虎牙流程:填写资料(区服/角色名,UID 可选)→ 登录 → 绑定角色。
// 资料齐全前不生成绑定二维码,避免客户在资料缺失时先绑错角色。
const profileComplete = Boolean(
String(selectedTask?.customerServerZone || '').trim() &&
String(selectedTask?.customerGameRoleId || '').trim() &&
String(selectedTask?.customerGameRoleName || '').trim(),
)
@@ -931,15 +930,15 @@ export default function CustomerFulfillmentPage({
async function handleSaveProfile() {
if (!selectedTask) return
if (!profileServerZone.trim() || !profileRoleId.trim() || !profileRoleName.trim()) {
message.warning('请完整填写区服、游戏角色 UID 和角色名')
if (!profileServerZone.trim() || !profileRoleName.trim()) {
message.warning('请完整填写区服和角色名')
return
}
if (!SERVER_ZONE_OPTIONS.includes(profileServerZone.trim())) {
message.warning('请选择区服')
return
}
if (!/^\d+$/.test(profileRoleId.trim())) {
if (profileRoleId.trim() && !/^\d+$/.test(profileRoleId.trim())) {
message.warning('游戏角色 UID 只能是数字')
return
}
@@ -1221,7 +1220,7 @@ export default function CustomerFulfillmentPage({
<p>
{profileComplete
? '修改目标角色资料后会重新核对虎牙账号当前绑定角色;角色名与区服一致后才能确认绑定。'
: '第一步:请填写区服、游戏角色 UID 和角色名。游戏角色 UID 与稍后登录的虎牙账号 UID 不是同一个编号。'}
: '第一步:请填写区服和角色名。游戏角色 UID 为选填资料,不参与绑定核验。'}
</p>
<div className="customer-profile-form">
<label className="customer-collect-label">
@@ -1235,14 +1234,12 @@ export default function CustomerFulfillmentPage({
placeholder="请选择区服"
options={SERVER_ZONE_OPTIONS.map((value) => ({ value, label: value }))}
/>
<label className="customer-collect-label">
游戏角色 UID <span>*</span>
</label>
<label className="customer-collect-label">游戏角色 UID(选填)</label>
<Input
className="customer-collect-input"
value={profileRoleId}
onChange={(event) => setProfileRoleId(event.target.value)}
placeholder="请输入游戏角色 UID"
placeholder="选填,仅用于订单资料留档"
maxLength={64}
inputMode="numeric"
/>
@@ -1590,7 +1587,7 @@ export default function CustomerFulfillmentPage({
<strong>{currentRoleName || '未识别到角色'}</strong>
</div>
<div>
<span>目标角色 UID</span>
<span>目标角色 UID(选填)</span>
<strong>{targetRoleUid || '未填写'}</strong>
</div>
{pendingRoleName ? (
@@ -1669,7 +1666,7 @@ export default function CustomerFulfillmentPage({
: '请使用微信APP扫码进行游戏角色绑定'}
</p>
<p className="customer-binding-qr-hint">
扫码后系统会核对待确认角色的名称与区服,不会用虎牙账号 UID 代替游戏角色 UID。
扫码后系统只核对角色名称与区服,UID 不参与绑定判定。
</p>
<p className="customer-binding-qr-tip">
{selectedTask?.bindingStatus === 'scanned'
@@ -2008,7 +2005,7 @@ export default function CustomerFulfillmentPage({
>
<Space direction="vertical" size={14} style={{ width: '100%' }}>
<p style={{ margin: 0 }}>
请核对角色名称与区服。游戏角色 UID 单独留档,不会与虎牙登录账号 UID 比对。
请核对角色名称与区服。游戏角色 UID 为选填留档,不参与绑定判定。
</p>
<div className="customer-binding-compare">
<div className="customer-binding-compare-side">
@@ -2019,7 +2016,7 @@ export default function CustomerFulfillmentPage({
</Button>
</div>
<strong>{bindingComparison?.customerRoleName || '未填写'}</strong>
<em>{bindingComparison?.customerRoleId || '未填写游戏角色 UID'}</em>
<em>{bindingComparison?.customerRoleId || '未填写游戏角色 UID(不影响绑定)'}</em>
</div>
<div className="customer-binding-compare-side">
<div className="customer-binding-compare-head">
@@ -50,6 +50,19 @@ test('虎牙客户页固定先填写资料,再登录并绑定角色', () => {
assert.ok(source.includes('(isWeibo || profileComplete) &&'))
})
test('资料完整只要求区服和角色名,游戏角色 UID 可选', () => {
const profileStart = source.indexOf('const profileComplete = Boolean(')
const profileEnd = source.indexOf('\n\n const load =', profileStart)
const profileSource = source.slice(profileStart, profileEnd)
assert.ok(profileSource.includes('customerServerZone'))
assert.ok(profileSource.includes('customerGameRoleName'))
assert.ok(!profileSource.includes('customerGameRoleId'))
assert.ok(source.includes('请完整填写区服和角色名'))
assert.ok(source.includes('游戏角色 UID 为选填资料,不参与绑定核验'))
assert.ok(source.includes('游戏角色 UID(选填)'))
assert.ok(source.includes('if (profileRoleId.trim() && !/^\\d+$/.test(profileRoleId.trim()))'))
})
test('登录和绑定专用同步阶段暂停整单轮询', () => {
assert.ok(source.includes('const dedicatedLoginPoll ='))
assert.ok(source.includes('const dedicatedBindingPoll ='))
@@ -74,10 +87,9 @@ test('角色名和区服一致才出现确认绑定,不一致时展示原因',
assert.ok(source.includes('customer-binding-modal-error'))
})
test('二维码区明确区分虎牙账号 UID 与游戏角色 UID', () => {
assert.ok(source.includes('扫码后系统会核对待确认角色的名称与区服'))
assert.ok(source.includes('不会用虎牙账号 UID'))
assert.ok(source.includes('游戏角色 UID 与稍后登录的虎牙账号 UID 不是同一个编号'))
test('二维码区明确只核验角色名与区服,UID 不参与绑定', () => {
assert.ok(source.includes('扫码后系统只核对角色名称与区服,UID 不参与绑定判定'))
assert.ok(source.includes('游戏角色 UID 为选填留档,不参与绑定判定'))
assert.ok(source.includes('本次待确认角色'))
assert.ok(source.includes('虎牙账号 UID'))
assert.ok(!source.includes('平台已返回加密角色标识'))
@@ -39,7 +39,7 @@ test('取消直接使用原角色的快捷确认路径', () => {
test('点击上一步修改资料会回到第一步并隐藏绑定区', () => {
// 步骤条把编辑资料视为第一步,即使资料原本已完整。
assert.ok(source.includes('profileEditing || !profileComplete'))
assert.ok(source.includes("'第一步:请填写区服、游戏角色 UID 和角色名"))
assert.ok(source.includes("'第一步:请填写区服和角色名"))
assert.ok(source.includes('返回绑定角色'))
// 资料步骤隐藏二维码、失败提示和比对操作,避免与第二步混在一起。
assert.ok(source.includes('!profileEditing'))
@@ -60,10 +60,10 @@ test('换绑冷却明确指向虎牙登录账号', () => {
assert.ok(adminPage.includes("rebind_blocked_account: '虎牙账号换绑冷却中'"))
})
test('虎牙默认只声明角色名与区服一致,不把客户角色 UID 冒充已核验', () => {
test('虎牙只声明角色名与区服一致,平台角色 UID 不参与核验', () => {
assert.ok(!adminPage.includes('三项一致,可提交平台绑定'))
assert.ok(adminPage.includes('角色名与区服一致,可提交平台绑定'))
assert.ok(adminPage.includes('角色名、区服和平台角色 UID 一致,可提交平台绑定'))
assert.ok(!adminPage.includes('角色名、区服和平台角色 UID 一致,可提交平台绑定'))
})
test('后台不再展示虎牙加密角色标识', () => {
@@ -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_*` 字段的删除迁移。