diff --git a/apps/backend/src/services/semi-auto/binding-role-id.ts b/apps/backend/src/services/semi-auto/binding-role-id.ts
index d7b937c6..80d121a8 100644
--- a/apps/backend/src/services/semi-auto/binding-role-id.ts
+++ b/apps/backend/src/services/semi-auto/binding-role-id.ts
@@ -1,4 +1,4 @@
-/** 只有平台独立返回的纯数字游戏角色 UID 才能作为自动核验依据。 */
+/** 判断平台是否独立返回了纯数字游戏角色 UID;该值只作可选留档,不参与绑定核验。 */
export function isNumericBindingRoleId(value: unknown): boolean {
return /^\d+$/.test(String(value ?? '').trim())
}
diff --git a/apps/backend/src/services/semi-auto/huya-binding-policy.test.ts b/apps/backend/src/services/semi-auto/huya-binding-policy.test.ts
index ce0f8874..11dc16be 100644
--- a/apps/backend/src/services/semi-auto/huya-binding-policy.test.ts
+++ b/apps/backend/src/services/semi-auto/huya-binding-policy.test.ts
@@ -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({
diff --git a/apps/backend/src/services/semi-auto/huya-binding-policy.ts b/apps/backend/src/services/semi-auto/huya-binding-policy.ts
index 53760e5d..324b16a4 100644
--- a/apps/backend/src/services/semi-auto/huya-binding-policy.ts
+++ b/apps/backend/src/services/semi-auto/huya-binding-policy.ts
@@ -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,
}
diff --git a/apps/backend/src/services/semi-auto/huya-native/huya-native-connector.ts b/apps/backend/src/services/semi-auto/huya-native/huya-native-connector.ts
index 07fe3044..4166187e 100644
--- a/apps/backend/src/services/semi-auto/huya-native/huya-native-connector.ts
+++ b/apps/backend/src/services/semi-auto/huya-native/huya-native-connector.ts
@@ -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,
diff --git a/apps/backend/src/services/semi-auto/semi-auto-binding-role.test.ts b/apps/backend/src/services/semi-auto/semi-auto-binding-role.test.ts
index b50395ad..d36993ef 100644
--- a/apps/backend/src/services/semi-auto/semi-auto-binding-role.test.ts
+++ b/apps/backend/src/services/semi-auto/semi-auto-binding-role.test.ts
@@ -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区' }),
- /请完整填写区服/,
+ /请完整填写区服和角色名/,
)
})
})
diff --git a/apps/backend/src/services/semi-auto/semi-auto-customer-service.ts b/apps/backend/src/services/semi-auto/semi-auto-customer-service.ts
index 495bf8e5..aa79719f 100644
--- a/apps/backend/src/services/semi-auto/semi-auto-customer-service.ts
+++ b/apps/backend/src/services/semi-auto/semi-auto-customer-service.ts
@@ -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,
diff --git a/apps/backend/src/services/semi-auto/semi-auto-task-core.ts b/apps/backend/src/services/semi-auto/semi-auto-task-core.ts
index 66739183..9fc2726f 100644
--- a/apps/backend/src/services/semi-auto/semi-auto-task-core.ts
+++ b/apps/backend/src/services/semi-auto/semi-auto-task-core.ts
@@ -257,12 +257,10 @@ export function normalizeOrderNo(value: unknown): string {
/** 客户资料以 TASK_SELECT 合并后的字段为准:优先任务表,回退工单资料。 */
export function hasCustomerProfile(
- task: Pick,
+ task: Pick,
): 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,
diff --git a/apps/backend/src/services/semi-auto/semi-auto-task.integration.test.ts b/apps/backend/src/services/semi-auto/semi-auto-task.integration.test.ts
index 2d30c77b..7f8ccdac 100644
--- a/apps/backend/src/services/semi-auto/semi-auto-task.integration.test.ts
+++ b/apps/backend/src/services/semi-auto/semi-auto-task.integration.test.ts
@@ -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虎牙用户')
diff --git a/apps/frontend/src/pages/admin/AdminSemiAutoTasksPage.tsx b/apps/frontend/src/pages/admin/AdminSemiAutoTasksPage.tsx
index 3a30a51b..3fcc71a2 100644
--- a/apps/frontend/src/pages/admin/AdminSemiAutoTasksPage.tsx
+++ b/apps/frontend/src/pages/admin/AdminSemiAutoTasksPage.tsx
@@ -849,9 +849,7 @@ export default function AdminSemiAutoTasksPage() {
}
>
{detail.comparison?.verdict === 'match'
- ? detail.comparison.verificationBasis === 'platform_numeric_uid'
- ? '角色名、区服和平台角色 UID 一致,可提交平台绑定'
- : '角色名与区服一致,可提交平台绑定'
+ ? '角色名与区服一致,可提交平台绑定'
: detail.comparison?.verdict === 'mismatch'
? '资料与平台角色不一致'
: '信息不完整,需人工核实'}
diff --git a/apps/frontend/src/pages/customer-fulfillment/CustomerFulfillmentPage.tsx b/apps/frontend/src/pages/customer-fulfillment/CustomerFulfillmentPage.tsx
index b86d2bde..c23e5cbd 100644
--- a/apps/frontend/src/pages/customer-fulfillment/CustomerFulfillmentPage.tsx
+++ b/apps/frontend/src/pages/customer-fulfillment/CustomerFulfillmentPage.tsx
@@ -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({
{profileComplete
? '修改目标角色资料后会重新核对虎牙账号当前绑定角色;角色名与区服一致后才能确认绑定。'
- : '第一步:请填写区服、游戏角色 UID 和角色名。游戏角色 UID 与稍后登录的虎牙账号 UID 不是同一个编号。'}
+ : '第一步:请填写区服和角色名。游戏角色 UID 为选填资料,不参与绑定核验。'}
- 目标角色 UID
+ 目标角色 UID(选填)
{targetRoleUid || '未填写'}
{pendingRoleName ? (
@@ -1669,7 +1666,7 @@ export default function CustomerFulfillmentPage({
: '请使用微信APP扫码进行游戏角色绑定'}
- 扫码后系统会核对待确认角色的名称与区服,不会用虎牙账号 UID 代替游戏角色 UID。
+ 扫码后系统只核对角色名称与区服,UID 不参与绑定判定。
{selectedTask?.bindingStatus === 'scanned'
@@ -2008,7 +2005,7 @@ export default function CustomerFulfillmentPage({
>
- 请核对角色名称与区服。游戏角色 UID 单独留档,不会与虎牙登录账号 UID 比对。
+ 请核对角色名称与区服。游戏角色 UID 为选填留档,不参与绑定判定。
@@ -2019,7 +2016,7 @@ export default function CustomerFulfillmentPage({
{bindingComparison?.customerRoleName || '未填写'}
-
{bindingComparison?.customerRoleId || '未填写游戏角色 UID'}
+
{bindingComparison?.customerRoleId || '未填写游戏角色 UID(不影响绑定)'}
diff --git a/apps/frontend/tests/customer-fulfillment-binding-compare.test.ts b/apps/frontend/tests/customer-fulfillment-binding-compare.test.ts
index c72f4326..ca706b41 100644
--- a/apps/frontend/tests/customer-fulfillment-binding-compare.test.ts
+++ b/apps/frontend/tests/customer-fulfillment-binding-compare.test.ts
@@ -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('平台已返回加密角色标识'))
diff --git a/apps/frontend/tests/customer-fulfillment-rebind-return.test.ts b/apps/frontend/tests/customer-fulfillment-rebind-return.test.ts
index 1f6ca480..ccba5c6f 100644
--- a/apps/frontend/tests/customer-fulfillment-rebind-return.test.ts
+++ b/apps/frontend/tests/customer-fulfillment-rebind-return.test.ts
@@ -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'))
diff --git a/apps/frontend/tests/semi-auto-task-readiness.test.ts b/apps/frontend/tests/semi-auto-task-readiness.test.ts
index a3200438..6d65eba8 100644
--- a/apps/frontend/tests/semi-auto-task-readiness.test.ts
+++ b/apps/frontend/tests/semi-auto-task-readiness.test.ts
@@ -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('后台不再展示虎牙加密角色标识', () => {
diff --git a/docs/履约配置/虎牙绑定协议解码与角色UID.md b/docs/履约配置/虎牙绑定协议解码与角色UID.md
index 3b72e26f..5b4c42de 100644
--- a/docs/履约配置/虎牙绑定协议解码与角色UID.md
+++ b/docs/履约配置/虎牙绑定协议解码与角色UID.md
@@ -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 未调用 |
diff --git a/docs/统一订单履约与财务模型-权威版.md b/docs/统一订单履约与财务模型-权威版.md
index 47232e49..26c5b218 100644
--- a/docs/统一订单履约与财务模型-权威版.md
+++ b/docs/统一订单履约与财务模型-权威版.md
@@ -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_*` 字段的删除迁移。