feat(semi-auto): 首次绑定自动提交并由客户本地确认,统一客户页控件尺寸

1) 首次绑定(isBindAccount/isBindRole 任一为 0)扫码完成后自动调 confirmBindActAccount,新增 bindConfirmState/bindConfirmMessage,失败透出虎牙原文并提示重新扫码。

2) 确认绑定改为纯本地流转:不再调用 confirmBindActAccount,也不再重复查角色;换绑被虎牙拒绝时需 acceptExistingRole 二次确认「仍使用原角色」。新增 bindingSnapshot 只读快照。

3) 客户页资料收集去掉顶部大图,只保留温馨提示;输入框/选择器 48px、主按钮 52px、次级按钮 48px,登录/绑定/资料页统一。

4) 修正已确认/已过期/绑定失败状态仍显示「登录成功,请继续扫码绑定游戏角色」的横幅错误,改为按 bindingStatus 显式映射,确认后只保留「等待客服核实」卡片。
This commit is contained in:
2026-11-16 16:31:56 +08:00
parent 64281aefb0
commit f371cc2c8d
9 changed files with 490 additions and 157 deletions
@@ -105,6 +105,8 @@ export type ConnectorBindingSession = {
rebindUnchanged?: boolean
rebindConfirmState?: 'idle' | 'submitting' | 'accepted' | 'rejected'
rebindConfirmMessage?: string
bindConfirmState?: 'idle' | 'submitting' | 'accepted' | 'rejected'
bindConfirmMessage?: string
rebindCooldownDays?: number
nextRebindAt?: string
platformChangeBindDay?: number
@@ -419,14 +421,34 @@ export async function getHuyaBinding(
)
}
export async function confirmHuyaBinding(
/**
* 只读绑定快照:不触发虎牙查询,供「确认绑定」这类本地动作使用。
* 外部 Connector 没有独立快照端点,只能复用 GET(由 Connector 侧决定是否访问虎牙)。
*/
export async function getHuyaBindingSnapshot(
sessionId: string,
mode: SemiAutoConnectorMode = defaultSemiAutoConnectorMode(),
): Promise<ConnectorBindingSession> {
if (mode === 'embedded') return huyaNativeConnector.confirmBinding(sessionId)
if (mode === 'embedded') return huyaNativeConnector.bindingSnapshot(sessionId)
return callConnector<ConnectorBindingSession>(
`/api/internal/huya-semi-auto/sessions/${encodeURIComponent(sessionId)}/binding`,
{},
mode,
)
}
export async function confirmHuyaBinding(
sessionId: string,
mode: SemiAutoConnectorMode = defaultSemiAutoConnectorMode(),
options: { acceptExistingRole?: boolean } = {},
): Promise<ConnectorBindingSession> {
if (mode === 'embedded') return huyaNativeConnector.confirmBinding(sessionId, options)
return callConnector<ConnectorBindingSession>(
`/api/internal/huya-semi-auto/sessions/${encodeURIComponent(sessionId)}/binding/confirm`,
{ method: 'POST', body: {} },
{
method: 'POST',
body: options.acceptExistingRole ? { acceptExistingRole: true } : {},
},
mode,
)
}
@@ -0,0 +1,96 @@
import assert from 'node:assert/strict'
import test from 'node:test'
import { resolveBindingConfirmDecision, shouldSubmitFirstBind } from './huya-native-connector.js'
test('确认绑定:识别到角色即可本地确认,不需要虎牙接口', () => {
assert.equal(
resolveBindingConfirmDecision({ status: 'role_ready', role: '大鲨鱼伊塞53' }),
'confirm',
)
})
test('确认绑定:换绑被虎牙拒绝时必须由客户二选一', () => {
assert.equal(
resolveBindingConfirmDecision({
status: 'role_ready',
role: '大鲨鱼伊塞53',
rebindRequested: true,
rebindUnchanged: true,
}),
'needs_rebind_decision',
)
})
test('确认绑定:客户确认仍使用原角色后放行', () => {
assert.equal(
resolveBindingConfirmDecision(
{
status: 'role_ready',
role: '大鲨鱼伊塞53',
rebindRequested: true,
rebindUnchanged: true,
},
{ acceptExistingRole: true },
),
'confirm',
)
})
test('确认绑定:换绑还在进行中(未判定失败)不拦截确认', () => {
assert.equal(
resolveBindingConfirmDecision({
status: 'role_ready',
role: '大鲨鱼伊塞53',
rebindRequested: true,
}),
'confirm',
)
})
test('确认绑定:没有角色或状态不对时不能确认', () => {
assert.equal(resolveBindingConfirmDecision({ status: 'role_ready', role: '' }), 'not_ready')
assert.equal(
resolveBindingConfirmDecision({ status: 'qr_pending', role: '大鲨鱼伊塞53' }),
'not_ready',
)
assert.equal(
resolveBindingConfirmDecision({ status: 'confirmed', role: '大鲨鱼伊塞53' }),
'confirm',
)
})
test('首次绑定:没有绑定角色且扫码完成才提交虎牙绑定', () => {
assert.equal(shouldSubmitFirstBind({}, { qrCompleted: true, scanned: true }), true)
assert.equal(shouldSubmitFirstBind({}, { qrCompleted: false, scanned: true }), false)
assert.equal(shouldSubmitFirstBind({}, { qrCompleted: true, scanned: false }), false)
})
test('首次绑定:已有绑定角色或正在换绑时不提交绑定', () => {
assert.equal(
shouldSubmitFirstBind({ hasExistingBinding: true }, { qrCompleted: true, scanned: true }),
false,
)
assert.equal(
shouldSubmitFirstBind(
{ rebindRequested: true, hasExistingBinding: false },
{ qrCompleted: true, scanned: true },
),
false,
)
})
test('首次绑定:同一张码只提交一次', () => {
assert.equal(
shouldSubmitFirstBind({ bindConfirmState: 'accepted' }, { qrCompleted: true, scanned: true }),
false,
)
assert.equal(
shouldSubmitFirstBind({ bindConfirmState: 'rejected' }, { qrCompleted: true, scanned: true }),
false,
)
assert.equal(
shouldSubmitFirstBind({ bindConfirmState: 'submitting' }, { qrCompleted: true, scanned: true }),
false,
)
})
@@ -82,6 +82,11 @@ type NativeBindState = {
rebindConfirmMessage: string
rebindConfirmAt: number
rebindEffectDeadlineMs: number
/** 首次绑定(账号还没有绑定角色)时,扫码后由项目侧提交 confirmBindActAccount 的状态。 */
bindConfirmState: 'idle' | 'submitting' | 'accepted' | 'rejected'
bindConfirmMessage: string
bindConfirmAt: number
bindEffectDeadlineMs: number
rebindCooldownDays: number
nextRebindAt: string
changeBindTime: number
@@ -166,6 +171,10 @@ function defaultBindingState(): NativeBindState {
rebindConfirmMessage: '',
rebindConfirmAt: 0,
rebindEffectDeadlineMs: 0,
bindConfirmState: 'idle',
bindConfirmMessage: '',
bindConfirmAt: 0,
bindEffectDeadlineMs: 0,
rebindCooldownDays: 0,
nextRebindAt: '',
changeBindTime: 0,
@@ -234,6 +243,54 @@ export function resolveRebindCooldown(
return { days: 0, nextRebindAt: '' }
}
export type BindingConfirmDecision = 'confirm' | 'needs_rebind_decision' | 'not_ready'
/**
* 客户点「确认绑定」时只做本地流转:角色已识别即可确认,不调用任何虎牙接口。
* 唯一需要客户决定的情况是「换绑被虎牙拒绝、平台仍返回原角色」:
* 要么重新扫码换绑,要么显式确认继续使用原绑定角色。
*/
export function resolveBindingConfirmDecision(
binding: {
status?: string
role?: string
rebindRequested?: boolean
rebindUnchanged?: boolean
},
options: { acceptExistingRole?: boolean } = {},
): BindingConfirmDecision {
const role = String(binding.role || '').trim()
const status = String(binding.status || '')
if (!role || (status !== 'role_ready' && status !== 'confirmed')) return 'not_ready'
if (
binding.rebindRequested === true &&
binding.rebindUnchanged === true &&
options.acceptExistingRole !== true
) {
return 'needs_rebind_decision'
}
return 'confirm'
}
/**
* 首次绑定:账号还没有绑定角色(isBindAccount / isBindRole 任一为 0)时,
* 扫码完成后必须由项目侧调用 confirmBindActAccount 完成绑定,再读取角色做本地比对。
* 已经有绑定角色、也没发起换绑时不需要任何平台写接口。
*/
export function shouldSubmitFirstBind(
binding: {
rebindRequested?: boolean
hasExistingBinding?: boolean
bindConfirmState?: string
},
input: { qrCompleted: boolean; scanned: boolean },
): boolean {
if (!input.qrCompleted || !input.scanned) return false
if (binding.rebindRequested === true) return false
if (binding.hasExistingBinding === true) return false
return (binding.bindConfirmState || 'idle') === 'idle'
}
function applyRebindMeta(
session: NativeSession,
response: HuyaBindResponse | null,
@@ -861,9 +918,17 @@ export class HuyaNativeConnector {
session.binding.qrUrl = urls.qrUrl
session.binding.qrToken = mini.token
session.binding.expiresAtMs = this.now() + BINDING_QR_TTL_MS
if (!options.forceRebind) {
// 新的绑定码:清掉上一次绑定提交状态,等这次扫码完成后再提交。
session.binding.bindConfirmState = 'idle'
session.binding.bindConfirmMessage = ''
session.binding.bindConfirmAt = 0
session.binding.bindEffectDeadlineMs = 0
session.binding.rebindScanned = false
}
session.binding.message = options.forceRebind
? '请使用虎牙 App 扫码选择需要换绑的游戏角色'
: '请使用虎牙 App 扫码绑定游戏角色'
: '该虎牙账号还没有绑定游戏角色,请用虎牙 App 扫码完成绑定'
return this.bindingView(session)
})
}
@@ -902,6 +967,39 @@ export class HuyaNativeConnector {
}
}
/**
* 首次绑定:账号还没有绑定角色时,扫码完成后由项目侧替客户点「绑定」。
* 与换绑共用 confirmBindActAccount,只是状态记录在 bindConfirmState,避免和换绑失败混淆。
*/
private async submitBindLocked(session: NativeSession, rpc: HuyaRpcClient): Promise<void> {
const { bindActId, outerActId } = configValues()
const now = this.now()
session.binding.bindConfirmState = 'submitting'
session.binding.bindConfirmMessage = ''
session.binding.bindConfirmAt = now
try {
const confirmed = await rpc.confirmBindActAccount({
uid: session.uid,
cookie: session.cookie,
bindActId,
outerActId,
})
if (confirmed && confirmed.status === 200) {
session.binding.bindConfirmState = 'accepted'
session.binding.bindEffectDeadlineMs = now + REBIND_EFFECT_WINDOW_MS
session.binding.message = '已向虎牙提交绑定,正在等待角色生效'
return
}
session.binding.bindConfirmState = 'rejected'
session.binding.bindConfirmMessage = confirmed?.msg || '虎牙未接受本次绑定'
session.binding.message = `虎牙未接受本次绑定:${session.binding.bindConfirmMessage}`
} catch (error) {
session.binding.bindConfirmState = 'rejected'
session.binding.bindConfirmMessage = errorMessage(error)
session.binding.message = `提交绑定失败:${session.binding.bindConfirmMessage}`
}
}
async pollBinding(sessionId: string): Promise<ConnectorBindingSession> {
return this.withLock(sessionId, async () => {
const session = this.requireAuthenticatedSession(sessionId)
@@ -913,7 +1011,11 @@ export class HuyaNativeConnector {
timeoutMs: this.rpcTimeoutMs,
})
if (qrStatus) {
if (qrStatus.isExpired || qrStatus.isFailure) {
// 平台已受理(绑定/换绑)时二维码会先过期,此时要等角色生效,不能直接判过期。
const waitingPlatformEffect =
session.binding.rebindConfirmState === 'accepted' ||
session.binding.bindConfirmState === 'accepted'
if ((qrStatus.isExpired || qrStatus.isFailure) && !waitingPlatformEffect) {
session.binding.status = 'expired'
session.binding.message = '绑定二维码已过期,请重新获取'
return this.bindingView(session)
@@ -943,6 +1045,15 @@ export class HuyaNativeConnector {
) {
await this.submitRebindLocked(session, rpc)
}
// 首次绑定:账号还没有绑定角色时,扫码完成后由项目侧主动提交绑定。
if (
shouldSubmitFirstBind(session.binding, {
qrCompleted,
scanned: session.binding.rebindScanned,
})
) {
await this.submitBindLocked(session, rpc)
}
const response = await rpc.checkUserBindGameAccount({
uid: session.uid,
cookie: session.cookie,
@@ -1001,92 +1112,103 @@ export class HuyaNativeConnector {
if (rebindRequested) {
session.binding.message = '已识别换绑角色,请确认换绑'
}
} else if (
!session.binding.rebindRequested &&
session.binding.bindConfirmState === 'rejected'
) {
session.binding.status = 'failed'
session.binding.message = `虎牙未接受本次绑定:${session.binding.bindConfirmMessage}`
} else if (
!session.binding.rebindRequested &&
session.binding.bindConfirmState === 'accepted'
) {
if (this.now() < session.binding.bindEffectDeadlineMs) {
session.binding.status = 'scanned'
session.binding.message = '已向虎牙提交绑定,正在等待角色生效'
} else {
session.binding.status = 'failed'
session.binding.message = '虎牙已受理绑定,但未返回角色,请重新扫码绑定'
}
} else if (!['scanned', 'expired', 'failed'].includes(session.binding.status)) {
session.binding.status = 'qr_pending'
session.binding.message = '等待扫码绑定游戏角色'
session.binding.message = '该虎牙账号还没有绑定游戏角色,请扫码完成绑定'
}
return this.bindingView(session)
})
}
async confirmBinding(sessionId: string): Promise<ConnectorBindingSession> {
/** 只读绑定状态快照:不访问虎牙,供「确认绑定」这类纯本地动作使用。 */
async bindingSnapshot(sessionId: string): Promise<ConnectorBindingSession> {
return this.withLock(sessionId, async () =>
this.bindingView(this.requireAuthenticatedSession(sessionId)),
)
}
/**
* 客户点「确认绑定」:只做本地状态流转,不调用虎牙接口。
* 虎牙侧的绑定已由扫码(小程序/弹窗)完成,确认绑定只是核对三项后落库;
* 需要调用虎牙接口的地方只有「换绑确认」(submitRebind / pollBinding 自动提交)。
*/
async confirmBinding(
sessionId: string,
options: { acceptExistingRole?: boolean } = {},
): Promise<ConnectorBindingSession> {
return this.withLock(sessionId, async () => {
const session = this.requireAuthenticatedSession(sessionId)
const { bindActId, outerActId } = configValues()
const rpc = new HuyaRpcClient({ fetchImpl: this.fetchImpl, timeoutMs: this.rpcTimeoutMs })
const rebindRequested = session.binding.rebindRequested
if (rebindRequested && session.binding.rebindConfirmState !== 'accepted') {
// 客户点确认前再兜底提交一次,避免小程序扫码后项目没来得及自动提交。
await this.submitRebindLocked(session, rpc)
}
const response = await rpc.checkUserBindGameAccount({
uid: session.uid,
cookie: session.cookie,
bindActId,
outerActId,
})
const role = parseRole(response)
if (!response || response.status !== 200 || !role.role) {
const binding = session.binding
const decision = resolveBindingConfirmDecision(binding, options)
if (decision === 'not_ready') {
throw createHttpError('尚未识别到可确认的绑定角色', {
statusCode: 409,
errorCode: 'huya_bind_role_not_ready',
})
}
applyRebindMeta(session, response, this.now())
if (
rebindRequested &&
session.binding.baselineRoleKey &&
bindingRoleKey(role) === session.binding.baselineRoleKey
) {
// 只有虎牙实际未生效时才拦截;冷却原因以虎牙返回的原文为准。
const rebindRequested = binding.rebindRequested
const acceptExistingRole = options.acceptExistingRole === true
if (decision === 'needs_rebind_decision') {
const reason = readString(binding.rebindConfirmMessage)
throw createHttpError(
rebindFailureMessage(
role.role,
session.binding.rebindConfirmMessage,
session.binding.nextRebindAt,
),
{
statusCode: 409,
errorCode:
session.binding.rebindConfirmState === 'rejected'
? 'huya_bind_rebind_rejected'
: 'huya_bind_rebind_not_effective',
},
`${
reason
? `换绑未成功:${reason}。`
: `换绑未成功:平台仍返回原绑定角色「${binding.role}」。`
}请重新扫码换绑,或确认继续使用原绑定角色`,
{ statusCode: 409, errorCode: 'huya_bind_rebind_decision_required' },
)
}
const useExistingBinding = hasExistingHuyaBinding(response) && !rebindRequested
if (!useExistingBinding && session.binding.rebindConfirmState !== 'accepted') {
const confirmed = await rpc.confirmBindActAccount({
uid: session.uid,
cookie: session.cookie,
bindActId,
outerActId,
})
if (!confirmed || confirmed.status !== 200) {
throw createHttpError(confirmed?.msg || '确认虎牙绑定失败', {
statusCode: 409,
errorCode: 'huya_bind_confirm_failed',
})
}
const role = {
account: binding.account,
role: binding.role,
roleId: binding.roleId,
channel: binding.channel,
}
const useExistingBinding =
binding.hasExistingBinding === true && (!rebindRequested || acceptExistingRole)
this.markRoleReady(session, role, useExistingBinding)
session.binding.status = 'confirmed'
session.binding.hasExistingBinding = true
session.binding.rebindRequested = false
session.binding.rebindScanned = false
session.binding.rebindUnchanged = false
session.binding.rebindConfirmState = 'idle'
session.binding.rebindConfirmMessage = ''
session.binding.rebindConfirmAt = 0
session.binding.rebindEffectDeadlineMs = 0
session.binding.rebindCooldownDays = 0
session.binding.nextRebindAt = ''
session.binding.baselineRoleKey = ''
session.binding.message = useExistingBinding
? '当前虎牙账号已有绑定角色,已确认直接使用'
: rebindRequested
? '虎牙角色换绑已确认'
: '虎牙角色绑定已确认'
binding.status = 'confirmed'
binding.hasExistingBinding = true
binding.rebindRequested = false
binding.rebindScanned = false
binding.rebindUnchanged = false
binding.rebindConfirmState = 'idle'
binding.rebindConfirmMessage = ''
binding.rebindConfirmAt = 0
binding.rebindEffectDeadlineMs = 0
binding.bindConfirmState = 'idle'
binding.bindConfirmMessage = ''
binding.bindConfirmAt = 0
binding.bindEffectDeadlineMs = 0
binding.rebindCooldownDays = 0
binding.nextRebindAt = ''
binding.baselineRoleKey = ''
binding.message =
rebindRequested && acceptExistingRole
? '本次换绑未生效,已按原绑定角色确认'
: useExistingBinding
? '当前虎牙账号已有绑定角色,已确认直接使用'
: rebindRequested
? '虎牙角色换绑已确认'
: '虎牙角色绑定已确认'
return this.bindingView(session)
})
}
@@ -1419,6 +1541,8 @@ export class HuyaNativeConnector {
rebindUnchanged: binding.rebindUnchanged,
rebindConfirmState: binding.rebindConfirmState,
rebindConfirmMessage: binding.rebindConfirmMessage,
bindConfirmState: binding.bindConfirmState,
bindConfirmMessage: binding.bindConfirmMessage,
rebindCooldownDays: binding.rebindCooldownDays,
nextRebindAt: binding.nextRebindAt,
platformChangeBindDay: binding.changeBindDay,
@@ -22,6 +22,7 @@ import {
confirmHuyaBinding,
exportHuyaSessionCredential,
getHuyaBinding,
getHuyaBindingSnapshot,
getHuyaLoginSession,
loginHuyaSms,
revokeHuyaSession,
@@ -959,6 +960,8 @@ function mapBindingUpdate(session: ConnectorBindingSession) {
rebindUnchanged: session.rebindUnchanged === true,
rebindConfirmState: session.rebindConfirmState || 'idle',
rebindConfirmMessage: String(session.rebindConfirmMessage || ''),
bindConfirmState: session.bindConfirmState || 'idle',
bindConfirmMessage: String(session.bindConfirmMessage || ''),
rebindCooldownDays: Number(session.rebindCooldownDays || 0),
nextRebindAt: String(session.nextRebindAt || ''),
platformChangeBindDay: Number(session.platformChangeBindDay || 0),
@@ -1144,6 +1147,8 @@ async function updateBindingTask(
rebindUnchanged: mapped.rebindUnchanged,
rebindConfirmState: mapped.rebindConfirmState,
rebindConfirmMessage: mapped.rebindConfirmMessage,
bindConfirmState: mapped.bindConfirmState,
bindConfirmMessage: mapped.bindConfirmMessage,
rebindCooldownDays: mapped.rebindCooldownDays,
nextRebindAt: mapped.nextRebindAt,
changeBindDay: mapped.platformChangeBindDay,
@@ -1166,6 +1171,8 @@ async function updateBindingTask(
rebindUnchanged: mapped.rebindUnchanged,
rebindConfirmState: mapped.rebindConfirmState,
rebindConfirmMessage: mapped.rebindConfirmMessage,
bindConfirmState: mapped.bindConfirmState,
bindConfirmMessage: mapped.bindConfirmMessage,
rebindCooldownDays: mapped.rebindCooldownDays,
nextRebindAt: mapped.nextRebindAt,
platformChangeBindDay: mapped.platformChangeBindDay,
@@ -1341,7 +1348,11 @@ export async function pollPublicBinding(orderNoInput: unknown, taskIdInput: unkn
return { task: mapTask(updated), binding }
}
export async function confirmPublicBinding(orderNoInput: unknown, taskIdInput: unknown) {
export async function confirmPublicBinding(
orderNoInput: unknown,
taskIdInput: unknown,
options: { acceptExistingRole?: boolean } = {},
) {
const orderNo = normalizeOrderNo(orderNoInput)
const taskId = normalizeId(taskIdInput)
const task = await loadTaskForOrder(orderNo, taskId)
@@ -1360,15 +1371,27 @@ export async function confirmPublicBinding(orderNoInput: unknown, taskIdInput: u
errorCode: 'semi_auto_binding_not_ready',
})
}
const session = await getBindingForTask(task, task.connector_session_id)
if (task.platform === 'huya' && session.rebindUnchanged === true) {
throw createHttpError(session.message || '换绑未生效:平台仍返回原绑定角色,请重新扫码', {
statusCode: 409,
errorCode:
session.rebindConfirmState === 'rejected'
? 'semi_auto_binding_rebind_rejected'
: 'semi_auto_binding_rebind_unchanged',
})
// 确认绑定是纯本地动作:虎牙侧只读内存快照,不再触发角色查询或换绑提交。
const session =
task.platform === 'huya'
? await getHuyaBindingSnapshot(task.connector_session_id, task.connector_mode)
: await getBindingForTask(task, task.connector_session_id)
if (
task.platform === 'huya' &&
session.rebindUnchanged === true &&
options.acceptExistingRole !== true
) {
// 换绑被虎牙拒绝时不直接放行,要求客户二选一:重新扫码换绑 / 仍使用原角色。
const reason = String(session.rebindConfirmMessage || '').trim()
throw createHttpError(
`${
reason ? `换绑未成功:${reason}。` : '换绑未生效:平台仍返回原绑定角色。'
}请重新扫码换绑,或确认继续使用原绑定角色「${session.bindGameRole || '原角色'}」`,
{
statusCode: 409,
errorCode: 'semi_auto_binding_rebind_decision_required',
},
)
}
const comparison = compareBindingRole(task, session)
if (comparison.verdict === 'mismatch') {
@@ -1380,7 +1403,7 @@ export async function confirmPublicBinding(orderNoInput: unknown, taskIdInput: u
// 必须调用 Connector 完成确认,否则会话仍是 role_ready,数据库也会停在待确认。
const confirmedSession =
task.platform === 'huya'
? await confirmHuyaBinding(task.connector_session_id, task.connector_mode)
? await confirmHuyaBinding(task.connector_session_id, task.connector_mode, options)
: session
const binding = await updateBindingTask(task, confirmedSession, 'customer')
const updated = await loadTask(task.id)