From f4806fb758d5042462002b9a84a9d0e6b1df632f Mon Sep 17 00:00:00 2001 From: yml Date: Fri, 20 Nov 2026 17:01:16 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E5=A4=8D(=E5=8D=8A=E8=87=AA=E5=8A=A8?= =?UTF-8?q?=E5=B1=A5=E7=BA=A6):=20=E8=99=8E=E7=89=99=E7=BB=91=E5=AE=9A?= =?UTF-8?q?=E4=BB=85=E6=A0=B8=E9=AA=8C=E8=A7=92=E8=89=B2=E5=90=8D=E4=B8=8E?= =?UTF-8?q?=E5=8C=BA=E6=9C=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../src/services/semi-auto/binding-role-id.ts | 2 +- .../semi-auto/huya-binding-policy.test.ts | 20 +++++++ .../services/semi-auto/huya-binding-policy.ts | 31 ++++------ .../huya-native/huya-native-connector.ts | 6 +- .../semi-auto/semi-auto-binding-role.test.ts | 36 ++++++++--- .../semi-auto/semi-auto-customer-service.ts | 6 +- .../services/semi-auto/semi-auto-task-core.ts | 20 ++----- .../semi-auto-task.integration.test.ts | 4 +- .../pages/admin/AdminSemiAutoTasksPage.tsx | 4 +- .../CustomerFulfillmentPage.tsx | 25 ++++---- ...stomer-fulfillment-binding-compare.test.ts | 20 +++++-- ...customer-fulfillment-rebind-return.test.ts | 2 +- .../tests/semi-auto-task-readiness.test.ts | 4 +- docs/履约配置/虎牙绑定协议解码与角色UID.md | 21 ++++--- docs/统一订单履约与财务模型-权威版.md | 59 ++++++++++--------- 15 files changed, 149 insertions(+), 111 deletions(-) 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_*` 字段的删除迁移。