feat(binding): verify 4G relations before Banban unbind
This commit is contained in:
stu2not
@@ -3,6 +3,7 @@ export default defineAppConfig({
|
||||
"pages/device/index",
|
||||
"pages/login/index",
|
||||
"pages/bind/index",
|
||||
"pages/traffic-binding/index",
|
||||
"pages/notification/index",
|
||||
"pages/chat/index",
|
||||
"pages/chat/detail/index",
|
||||
@@ -12,6 +13,7 @@ export default defineAppConfig({
|
||||
"pages/family-invite/index",
|
||||
"pages/webview/index",
|
||||
],
|
||||
navigateToMiniProgramAppIdList: ['wx56e1cfc52aab630f'],
|
||||
window: {
|
||||
backgroundTextStyle: "light",
|
||||
navigationBarBackgroundColor: "#FFF9EA",
|
||||
|
||||
@@ -1,7 +1,10 @@
|
||||
import './app.scss'
|
||||
import { PropsWithChildren } from 'react'
|
||||
import { useDidShow } from '@tarojs/taro'
|
||||
import { captureTrafficReturn } from './services/traffic-binding'
|
||||
|
||||
function App(props: PropsWithChildren) {
|
||||
useDidShow((options) => { captureTrafficReturn(options) })
|
||||
return props.children
|
||||
}
|
||||
|
||||
|
||||
@@ -26,6 +26,7 @@ import {
|
||||
validateChildNameInput,
|
||||
} from '@/services/child'
|
||||
import { useSystemBanner } from '@/components/system-banner/use-system-banner'
|
||||
import { trafficPageUrl } from '@/services/traffic-binding'
|
||||
|
||||
import './index.scss'
|
||||
|
||||
@@ -678,6 +679,10 @@ export default function Bind() {
|
||||
<Button className='bind-result-button primary' onClick={() => Taro.reLaunch({ url: bindResultDestination })}>
|
||||
{bindResultDestination.includes('/sleep/') ? '去关联宝贝' : '返回首页'}
|
||||
</Button>
|
||||
{!isAddingCard && <Button className='bind-result-button primary' onClick={() => Taro.navigateTo({ url: trafficPageUrl(boundDeviceId) })}>
|
||||
关联流量服务
|
||||
</Button>}
|
||||
{!isAddingCard && <Text className='bind-result-description'>设备已绑定。流量查询和充值需另外关联，可稍后在管理页完成。</Text>}
|
||||
</>
|
||||
) : (
|
||||
<>
|
||||
|
||||
@@ -10,6 +10,7 @@ import Taro, { useDidHide, useDidShow, useShareAppMessage } from '@tarojs/taro'
|
||||
import { authorizeParentPhone, clearToken, getParent, getToken, Parent } from '@/services/auth'
|
||||
import { DEVICE_UNAVAILABLE_MESSAGE } from '@/services/api'
|
||||
import { getCurrentUserId } from '@/services/session'
|
||||
import { TrafficOverview, getTrafficOverview, trafficLinked, openTrafficPage, openTrafficPortal, flushTrafficReceipt } from '@/services/traffic-binding'
|
||||
import {
|
||||
BindingListItem,
|
||||
BindingCardItem,
|
||||
@@ -19,7 +20,6 @@ import {
|
||||
loadCurrentChildBindingContext,
|
||||
setSelectedBindingDeviceId,
|
||||
updateBindingCardName,
|
||||
unbindDevice,
|
||||
} from '@/services/binding'
|
||||
import {
|
||||
Child,
|
||||
@@ -77,6 +77,20 @@ export default function Sleep() {
|
||||
const [children, setChildren] = useState<Child[]>([])
|
||||
const [bindings, setBindings] = useState<BindingListItem[]>([])
|
||||
const [binding, setBinding] = useState<BindingListItem | null>(null)
|
||||
const [trafficOverview, setTrafficOverview] = useState<TrafficOverview | null>(null)
|
||||
const [trafficBusy, setTrafficBusy] = useState(false)
|
||||
const trafficLock = useRef(false)
|
||||
useEffect(() => {
|
||||
let cancelled = false
|
||||
setTrafficOverview(null)
|
||||
if (binding?.device_id) {
|
||||
void flushTrafficReceipt().catch(() => null)
|
||||
.then(() => getTrafficOverview(binding.device_id))
|
||||
.then((value) => { if (!cancelled) setTrafficOverview(value) })
|
||||
.catch(() => { /* Core device management remains available. */ })
|
||||
}
|
||||
return () => { cancelled = true }
|
||||
}, [binding])
|
||||
const [currentChild, setCurrentChild] = useState<Child | null>(null)
|
||||
const [firmwareStatus, setFirmwareStatus] = useState<DeviceFirmwareStatus | null>(null)
|
||||
const [showFirmwareProgress, setShowFirmwareProgress] = useState(false)
|
||||
@@ -651,12 +665,7 @@ export default function Sleep() {
|
||||
if (!result.confirm) return
|
||||
|
||||
try {
|
||||
await unbindDevice(targetBinding.device_id)
|
||||
if (binding?.device_id === targetBinding.device_id) {
|
||||
clearSelectedBindingDeviceId()
|
||||
}
|
||||
Taro.showToast({ title: '已删除设备', icon: 'success' })
|
||||
await loadData()
|
||||
await openTrafficPage(targetBinding.device_id, 'unbind')
|
||||
} catch (error: any) {
|
||||
Taro.showToast({
|
||||
title: error?.message || '删除设备失败，请重试',
|
||||
@@ -834,10 +843,7 @@ export default function Sleep() {
|
||||
if (!result.confirm) return
|
||||
|
||||
try {
|
||||
await unbindDevice(binding.device_id)
|
||||
clearSelectedBindingDeviceId()
|
||||
Taro.showToast({ title: '已解绑', icon: 'success' })
|
||||
await loadData()
|
||||
await openTrafficPage(binding.device_id, 'unbind')
|
||||
} catch (error: any) {
|
||||
Taro.showToast({
|
||||
title: error?.message || '解绑失败，请重试',
|
||||
@@ -956,6 +962,18 @@ export default function Sleep() {
|
||||
return
|
||||
}
|
||||
|
||||
if (['关联流量服务', '继续确认流量服务', '继续解绑', '流量查询', '套餐充值'].includes(item.name)) {
|
||||
if (!binding || trafficLock.current) return
|
||||
trafficLock.current = true
|
||||
setTrafficBusy(true)
|
||||
const operation = item.name === '流量查询' || item.name === '套餐充值'
|
||||
? openTrafficPortal(binding.device_id, item.name === '套餐充值' ? 'recharge' : 'device')
|
||||
: openTrafficPage(binding.device_id, item.name === '继续解绑' ? 'unbind' : 'bind')
|
||||
void operation.catch((error: any) => Taro.showToast({ title: error.message || error.errMsg || '操作未完成，请重试', icon: 'none' }))
|
||||
.finally(() => { trafficLock.current = false; setTrafficBusy(false) })
|
||||
return
|
||||
}
|
||||
|
||||
if (item.name === '我的卡片') {
|
||||
setShowCardsModal(true)
|
||||
return
|
||||
@@ -1129,6 +1147,14 @@ export default function Sleep() {
|
||||
value: binding?.device_id ? `当前: ${binding.device_id}` : '未绑定',
|
||||
arrow: true,
|
||||
},
|
||||
...(binding ? (trafficLinked(trafficOverview) && trafficOverview?.device_id === binding.device_id
|
||||
? [
|
||||
{ icon: require('../../assets/ui/menu-binding.png'), iconBgClass: 'green', name: '流量查询', value: '', arrow: true, disabled: !isFamilyOwner || trafficBusy },
|
||||
{ icon: require('../../assets/ui/menu-binding.png'), iconBgClass: 'green', name: '套餐充值', value: '', arrow: true, disabled: !isFamilyOwner || trafficBusy },
|
||||
]
|
||||
: [{ icon: require('../../assets/ui/menu-binding.png'), iconBgClass: 'green',
|
||||
name: trafficOverview?.unbind ? '继续解绑' : trafficOverview?.bind ? '继续确认流量服务' : '关联流量服务',
|
||||
value: isFamilyOwner ? '不影响伴伴使用' : '仅设备归属账号可操作', arrow: true, disabled: !isFamilyOwner || trafficBusy }]) : []),
|
||||
{
|
||||
icon: require('../../assets/ui/menu-cards.png'),
|
||||
iconBgClass: 'green',
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
export default definePageConfig({ navigationBarTitleText: '流量服务关联' })
|
||||
@@ -0,0 +1,7 @@
|
||||
.traffic-binding-page {
|
||||
min-height: 100vh; box-sizing: border-box; padding: 72rpx 40rpx;
|
||||
.title { display: block; font-size: 38rpx; font-weight: bold; margin-bottom: 30rpx; }
|
||||
.description { display: block; font-size: 28rpx; line-height: 1.7; margin-bottom: 30rpx; }
|
||||
.error { display: block; color: #a52a2a; margin-bottom: 24rpx; }
|
||||
button { margin-top: 24rpx; }
|
||||
}
|
||||
@@ -0,0 +1,69 @@
|
||||
import { View, Text, Button } from '@tarojs/components'
|
||||
import Taro, { useDidShow, useRouter } from '@tarojs/taro'
|
||||
import { useRef, useState } from 'react'
|
||||
import { getToken } from '@/services/auth'
|
||||
import { clearSelectedBindingDeviceId } from '@/services/binding'
|
||||
import { getPageStyle } from '@/utils/page-style'
|
||||
import { TrafficOperation, getTrafficOperation, resumeTrafficOperation,
|
||||
flushTrafficReceipt, finishTrafficUnbind, jumpTraffic } from '@/services/traffic-binding'
|
||||
import './index.scss'
|
||||
|
||||
export default function TrafficBindingPage() {
|
||||
const { params } = useRouter()
|
||||
const deviceId = String(params.device_id || '')
|
||||
const action = params.action === 'unbind' ? 'unbind' : 'bind'
|
||||
const [operation, setOperation] = useState<TrafficOperation | null>(null)
|
||||
const [busy, setBusy] = useState(false)
|
||||
const [error, setError] = useState('')
|
||||
const lock = useRef(false)
|
||||
|
||||
const recover = async () => {
|
||||
if (lock.current) return
|
||||
if (!getToken()) { Taro.navigateTo({ url: '/pages/login/index' }); return }
|
||||
lock.current = true
|
||||
setBusy(true)
|
||||
try {
|
||||
const current = await resumeTrafficOperation(deviceId, action)
|
||||
setOperation(current)
|
||||
if (action === 'unbind' && current.status === 'completed') clearSelectedBindingDeviceId()
|
||||
setError('')
|
||||
} catch (e: any) { setError(e.message || '暂时无法确认，请重试') }
|
||||
finally { lock.current = false; setBusy(false) }
|
||||
}
|
||||
useDidShow(() => { void recover() })
|
||||
|
||||
const proceed = async () => {
|
||||
if (!operation) { await recover(); return }
|
||||
if (lock.current) return
|
||||
lock.current = true
|
||||
setBusy(true)
|
||||
setError('')
|
||||
try {
|
||||
await flushTrafficReceipt()
|
||||
let current = await getTrafficOperation(operation.operation_id)
|
||||
if (current.status !== 'completed') {
|
||||
const result = await jumpTraffic(current)
|
||||
if (!result) return
|
||||
current = result
|
||||
if (action === 'unbind') current = await finishTrafficUnbind(current)
|
||||
}
|
||||
setOperation(current)
|
||||
if (action === 'unbind' && current.status === 'completed') clearSelectedBindingDeviceId()
|
||||
} catch (e: any) { setError(e.message || e.errMsg || '操作未完成，请继续重试') }
|
||||
finally { lock.current = false; setBusy(false) }
|
||||
}
|
||||
const completed = operation?.status === 'completed'
|
||||
const finalUnbind = action === 'unbind' && operation?.traffic_status === 'server_confirmed'
|
||||
return <View className='traffic-binding-page' style={getPageStyle(true)}>
|
||||
<Text className='title'>{action === 'bind' ? completed ? '流量服务已关联' : '设备已绑定，流量服务待关联' : completed ? '设备已解除绑定' : '解除设备与流量服务绑定'}</Text>
|
||||
<Text className='description'>{action === 'bind'
|
||||
? completed ? '可以查询流量和购买套餐了。' : '伴伴设备可以正常使用。继续前往流量管理小程序登录并关联，也可以稍后完成。'
|
||||
: completed ? '设备已解绑，流量侧已确认没有本次有效绑定。' : finalUnbind ? '流量后端已确认可以解绑，点击完成伴伴解绑。' : '先确认流量侧原绑定已解除，再解除伴伴绑定；套餐和充值记录保留。继续处理会停止本次流量关联，暂不支持取消恢复。'}</Text>
|
||||
{operation?.last_error === 'HANDOFF_RELATION_UNKNOWN' && <Text className='error'>流量后端无法确认原绑定记录，伴伴绑定仍保留，请联系服务人员核查。</Text>}
|
||||
{operation?.last_error === 'TRAFFIC_UNBIND_REQUIRED' && <Text className='description'>原流量绑定仍有效，请继续前往流量管理小程序解绑。</Text>}
|
||||
{operation?.status === 'partial_failed' && <Text className='description'>上次流量操作未完成，可以继续重试。</Text>}
|
||||
{error && <Text className='error'>{error}</Text>}
|
||||
{!completed && <Button disabled={busy} onClick={proceed}>{busy ? '处理中…' : finalUnbind ? '完成伴伴解绑' : '继续处理'}</Button>}
|
||||
<Button disabled={busy} onClick={() => Taro.switchTab({ url: '/pages/sleep/index' })}>{completed ? '返回管理' : '稍后处理'}</Button>
|
||||
</View>
|
||||
}
|
||||
@@ -12,7 +12,7 @@ const ERROR_DETAIL_MAP: Record<string, string> = {
|
||||
}
|
||||
|
||||
class ApiError extends Error {
|
||||
constructor(public status: number, message: string) {
|
||||
constructor(public status: number, message: string, public code?: string) {
|
||||
super(message)
|
||||
}
|
||||
}
|
||||
@@ -21,6 +21,7 @@ function getErrorDetail(data: any): string {
|
||||
if (!data) return ERROR_DETAIL_MAP['Request failed']
|
||||
if (typeof data.errMsg === 'string') return data.errMsg
|
||||
if (typeof data.detail === 'string') return ERROR_DETAIL_MAP[data.detail] || data.detail
|
||||
if (typeof data.detail?.message === 'string') return data.detail.message
|
||||
if (Array.isArray(data.detail)) {
|
||||
return data.detail.map((item: any) => String(item?.msg || item)).join('; ')
|
||||
}
|
||||
@@ -48,25 +49,33 @@ async function request<T>(
|
||||
}
|
||||
|
||||
let response
|
||||
let timer: ReturnType<typeof setTimeout> | undefined
|
||||
try {
|
||||
response = await Taro.request({
|
||||
const task = Taro.request({
|
||||
url: requestUrl,
|
||||
method: requestMethod,
|
||||
data: options.data,
|
||||
header: headers,
|
||||
timeout: REQUEST_TIMEOUT_MS,
|
||||
})
|
||||
response = await Promise.race([task, new Promise<never>((_, reject) => {
|
||||
timer = setTimeout(() => {
|
||||
reject(new Error('请求超时，请重试'))
|
||||
task.abort?.()
|
||||
}, REQUEST_TIMEOUT_MS)
|
||||
})])
|
||||
} catch (error: any) {
|
||||
const message = String(error?.errMsg || error?.message || 'request:fail')
|
||||
throw new ApiError(0, message)
|
||||
}
|
||||
} finally { if (timer) clearTimeout(timer) }
|
||||
|
||||
if (response.statusCode === 401) {
|
||||
handleUnauthorized({ redirect: !url.startsWith('/banban/auth/') })
|
||||
}
|
||||
|
||||
if (response.statusCode >= 400) {
|
||||
throw new ApiError(response.statusCode, getErrorDetail(response.data))
|
||||
const body = response.data as any
|
||||
throw new ApiError(response.statusCode, getErrorDetail(body), body?.detail?.code || body?.code)
|
||||
}
|
||||
|
||||
return response.data as T
|
||||
|
||||
@@ -0,0 +1,157 @@
|
||||
import Taro from '@tarojs/taro'
|
||||
import { request } from './api'
|
||||
import { getCurrentUserId } from './session'
|
||||
|
||||
export const TRAFFIC_APP_ID = 'wx56e1cfc52aab630f'
|
||||
export type TrafficAction = 'bind' | 'unbind'
|
||||
export interface TrafficOperation {
|
||||
operation_id: string
|
||||
device_id: string
|
||||
action: TrafficAction
|
||||
status: 'pending' | 'partial_failed' | 'completed'
|
||||
traffic_status: 'pending' | 'client_confirmed' | 'server_confirmed'
|
||||
last_error?: string | null
|
||||
}
|
||||
export interface TrafficOverview {
|
||||
device_id: string
|
||||
binding_instance_id: string
|
||||
bind: TrafficOperation | null
|
||||
unbind: TrafficOperation | null
|
||||
}
|
||||
const key = () => `trafficBinding:${getCurrentUserId()}`
|
||||
type Pending = { operation: TrafficOperation; receipt?: any }
|
||||
|
||||
export function getPendingTraffic(): Pending | null {
|
||||
if (!getCurrentUserId()) return null
|
||||
const value = Taro.getStorageSync(key())
|
||||
return value?.operation?.operation_id ? value : null
|
||||
}
|
||||
export function rememberOperation(operation: TrafficOperation) {
|
||||
if (!getCurrentUserId()) return
|
||||
const previous = getPendingTraffic()
|
||||
Taro.setStorageSync(key(), { operation, receipt: previous?.operation.operation_id === operation.operation_id ? previous.receipt : undefined })
|
||||
}
|
||||
export function captureTrafficReturn(options: any): boolean {
|
||||
if (options?.referrerInfo?.appId !== TRAFFIC_APP_ID) return false
|
||||
const data = options.referrerInfo.extraData
|
||||
const pending = getPendingTraffic()
|
||||
if (!pending || !data || data.operationId !== pending.operation.operation_id
|
||||
|| data.action !== pending.operation.action || data.requestId !== `joint-${data.operationId}`
|
||||
|| typeof data.success !== 'boolean' || !/^[A-Za-z0-9_]{1,64}$/.test(data.code || '')) return false
|
||||
if (data.success && (data.code !== 'OK' || !/^[A-Z0-9]{18,22}$/.test(data.iccid || ''))) return false
|
||||
// Only store the bounded receipt, never another app's tokens or arbitrary extraData.
|
||||
Taro.setStorageSync(key(), { operation: pending.operation, receipt: {
|
||||
action: data.action, request_id: data.requestId, success: data.success, code: data.code,
|
||||
iccid: data.success ? data.iccid : null,
|
||||
} })
|
||||
return true
|
||||
}
|
||||
export function trafficLinked(overview: TrafficOverview | null): boolean {
|
||||
return Boolean(overview?.bind?.status === 'completed' && overview.bind.traffic_status === 'server_confirmed' && !overview?.unbind)
|
||||
}
|
||||
export async function getTrafficOverview(deviceId: string) {
|
||||
const user = getCurrentUserId()
|
||||
const overview = await request<TrafficOverview>(`/banban/joint-bindings/devices/${encodeURIComponent(deviceId)}`)
|
||||
assertSameUser(user)
|
||||
if (overview.bind && !overview.unbind) overview.bind = await checkTrafficOperation(overview.bind.operation_id)
|
||||
return overview
|
||||
}
|
||||
export function getTrafficOperation(operationId: string) {
|
||||
return request<TrafficOperation>(`/banban/joint-bindings/${encodeURIComponent(operationId)}`)
|
||||
}
|
||||
export async function checkTrafficOperation(operationId: string) {
|
||||
const user = getCurrentUserId()
|
||||
const operation = await request<TrafficOperation>(`/banban/joint-bindings/${encodeURIComponent(operationId)}/check`, { method: 'POST' })
|
||||
assertSameUser(user)
|
||||
return operation
|
||||
}
|
||||
export async function startTrafficOperation(deviceId: string, action: TrafficAction) {
|
||||
const user = getCurrentUserId()
|
||||
const operation = await request<TrafficOperation>('/banban/joint-bindings', { method: 'POST', data: { device_id: deviceId, action } })
|
||||
assertSameUser(user)
|
||||
rememberOperation(operation)
|
||||
return operation
|
||||
}
|
||||
export async function flushTrafficReceipt(): Promise<TrafficOperation | null> {
|
||||
const pending = getPendingTraffic()
|
||||
if (!pending?.receipt) return null
|
||||
const user = getCurrentUserId()
|
||||
let result: TrafficOperation
|
||||
try {
|
||||
result = await request<TrafficOperation>(`/banban/joint-bindings/${pending.operation.operation_id}/result`, {
|
||||
method: 'POST', data: pending.receipt,
|
||||
})
|
||||
} catch (error: any) {
|
||||
assertSameUser(user)
|
||||
if (!['STALE_OPERATION', 'OPERATION_NOT_FOUND'].includes(error.code)) throw error
|
||||
// A previous binding instance must not prevent this device from being bound again.
|
||||
if (getPendingTraffic()?.operation.operation_id === pending.operation.operation_id) Taro.setStorageSync(key(), null)
|
||||
return null
|
||||
}
|
||||
assertSameUser(user)
|
||||
if (getPendingTraffic()?.operation.operation_id === result.operation_id) Taro.setStorageSync(key(), { operation: result })
|
||||
return result
|
||||
}
|
||||
export async function resumeTrafficOperation(deviceId: string, action: TrafficAction) {
|
||||
await flushTrafficReceipt()
|
||||
const pending = getPendingTraffic()
|
||||
if (pending?.operation.device_id === deviceId && pending.operation.action === action) {
|
||||
try { return await checkTrafficOperation(pending.operation.operation_id) }
|
||||
catch (error: any) {
|
||||
if (!['STALE_OPERATION', 'OPERATION_NOT_FOUND'].includes(error.code)) throw error
|
||||
}
|
||||
}
|
||||
return startTrafficOperation(deviceId, action)
|
||||
}
|
||||
export async function finishTrafficUnbind(operation: TrafficOperation) {
|
||||
const user = getCurrentUserId()
|
||||
const result = await request<TrafficOperation>(`/banban/joint-bindings/${operation.operation_id}/finish-unbind`, { method: 'POST' })
|
||||
assertSameUser(user)
|
||||
rememberOperation(result)
|
||||
return result
|
||||
}
|
||||
function targetVersion(): 'trial' | 'release' {
|
||||
return Taro.getAccountInfoSync().miniProgram.envVersion === 'release' ? 'release' : 'trial'
|
||||
}
|
||||
function assertSameUser(user: number) {
|
||||
if (!user || getCurrentUserId() !== user) throw new Error('账号已变化，请重新进入')
|
||||
}
|
||||
async function navigate(options: any, withinApp = false) {
|
||||
let timer: ReturnType<typeof setTimeout> | undefined
|
||||
try {
|
||||
return await Promise.race([withinApp ? Taro.navigateTo(options) : Taro.navigateToMiniProgram(options), new Promise((_, reject) => {
|
||||
timer = setTimeout(() => reject(new Error('跳转等待已结束，请重新进入确认')), 15000)
|
||||
})])
|
||||
} finally { if (timer) clearTimeout(timer) }
|
||||
}
|
||||
export async function jumpTraffic(operation: TrafficOperation) {
|
||||
const user = getCurrentUserId()
|
||||
const data = await request<any>(`/banban/joint-bindings/${operation.operation_id}/prepare`, { method: 'POST' })
|
||||
assertSameUser(user)
|
||||
rememberOperation(data.operation)
|
||||
if (data.operation.status === 'completed' || data.operation.traffic_status === 'server_confirmed') return data.operation as TrafficOperation
|
||||
if (data.target_app_id !== TRAFFIC_APP_ID) throw new Error('目标小程序配置不一致')
|
||||
await navigate({
|
||||
appId: TRAFFIC_APP_ID, path: 'pages/handoff/index', envVersion: targetVersion(),
|
||||
extraData: { operationId: operation.operation_id, action: operation.action,
|
||||
requestId: data.request_id, sourceBindingId: data.source_binding_id,
|
||||
handoffToken: data.handoff_token, iccid: data.iccid, deviceId: operation.device_id,
|
||||
recoveryOnly: data.recovery_only === true },
|
||||
})
|
||||
return null
|
||||
}
|
||||
export async function openTrafficPortal(deviceId: string, destination: 'device' | 'recharge') {
|
||||
const user = getCurrentUserId()
|
||||
const data = await request<any>(`/banban/joint-bindings/devices/${encodeURIComponent(deviceId)}/portal`)
|
||||
assertSameUser(user)
|
||||
if (data.target_app_id !== TRAFFIC_APP_ID) throw new Error('目标小程序配置不一致')
|
||||
await navigate({ appId: TRAFFIC_APP_ID, path: 'pages/handoff/index', envVersion: targetVersion(),
|
||||
extraData: { action: 'view', destination, iccid: data.iccid, deviceId,
|
||||
sourceBindingId: data.source_binding_id } })
|
||||
}
|
||||
export function trafficPageUrl(deviceId: string, action: TrafficAction = 'bind') {
|
||||
return `/pages/traffic-binding/index?device_id=${encodeURIComponent(deviceId)}&action=${action}`
|
||||
}
|
||||
export function openTrafficPage(deviceId: string, action: TrafficAction = 'bind') {
|
||||
return navigate({ url: trafficPageUrl(deviceId, action) }, true)
|
||||
}
|
||||
@@ -0,0 +1,31 @@
|
||||
const assert = require('node:assert/strict')
|
||||
const { test } = require('node:test')
|
||||
const fs = require('node:fs')
|
||||
const path = require('node:path')
|
||||
const ts = require('typescript')
|
||||
|
||||
test('request with no platform callback ends at 10 seconds and aborts without retrying', async () => {
|
||||
const timers = new Map()
|
||||
let calls = 0
|
||||
let aborted = 0
|
||||
let resolve
|
||||
const task = new Promise(r => { resolve = r })
|
||||
task.abort = () => { aborted++ }
|
||||
const module = { exports: {} }
|
||||
const source = fs.readFileSync(path.join(__dirname, '../src/services/api.ts'), 'utf8')
|
||||
const js = ts.transpileModule(source, { compilerOptions: { module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2019, esModuleInterop: true } }).outputText
|
||||
new Function('require', 'module', 'exports', 'setTimeout', 'clearTimeout', js)(name => {
|
||||
if (name === '@tarojs/taro') return { request: () => { calls++; return task } }
|
||||
if (name === '@/config/env') return { API_BASE_URL: 'https://example.invalid' }
|
||||
return { getToken: () => 'test', getCurrentUserId: () => 7, handleUnauthorized: () => {} }
|
||||
}, module, module.exports, (fn, ms) => { timers.set(fn, ms); return fn }, fn => timers.delete(fn))
|
||||
const pending = module.exports.request('/test')
|
||||
const [timer, duration] = [...timers][0]
|
||||
assert.equal(duration, 10000)
|
||||
timer()
|
||||
await assert.rejects(pending, /请求超时/)
|
||||
assert.equal(aborted, 1)
|
||||
assert.equal(calls, 1)
|
||||
assert.equal(timers.size, 0)
|
||||
resolve({ statusCode: 200, data: {} })
|
||||
})
|
||||
@@ -0,0 +1,152 @@
|
||||
const assert = require('node:assert/strict')
|
||||
const fs = require('node:fs')
|
||||
const path = require('node:path')
|
||||
const { test } = require('node:test')
|
||||
const ts = require('typescript')
|
||||
const operation = { operation_id: '12345678-1234-1234-1234-123456789abc', device_id: 'test-device', action: 'bind', status: 'pending', traffic_status: 'pending' }
|
||||
const iccid = '898604E91123D1334901'
|
||||
|
||||
function load() {
|
||||
const storage = new Map()
|
||||
let user = 7
|
||||
let version = 'trial'
|
||||
const calls = []
|
||||
const jumps = []
|
||||
const timers = new Map()
|
||||
let request = async (url, options) => { calls.push({ url, options }); return { ...operation, status: 'completed' } }
|
||||
const Taro = { getStorageSync: k => storage.get(k), setStorageSync: (k, v) => storage.set(k, v),
|
||||
navigateTo: () => new Promise(() => {}),
|
||||
getAccountInfoSync: () => ({ miniProgram: { envVersion: version } }),
|
||||
navigateToMiniProgram: async options => { jumps.push(options) } }
|
||||
const source = fs.readFileSync(path.join(__dirname, '../src/services/traffic-binding.ts'), 'utf8')
|
||||
const js = ts.transpileModule(source, { compilerOptions: { module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2019, esModuleInterop: true } }).outputText
|
||||
const module = { exports: {} }
|
||||
new Function('require', 'module', 'exports', 'setTimeout', 'clearTimeout', js)(id => {
|
||||
if (id === '@tarojs/taro') return Taro
|
||||
if (id === './session') return { getCurrentUserId: () => user }
|
||||
if (id === './api') return { request: (...args) => request(...args) }
|
||||
throw Error(id)
|
||||
}, module, module.exports, (fn, ms) => { timers.set(fn, ms); return fn }, fn => timers.delete(fn))
|
||||
return { api: module.exports, storage, calls, jumps, timers,
|
||||
user: value => { user = value }, version: value => { version = value }, request: fn => { request = fn } }
|
||||
}
|
||||
function returned(data = {}, appId = 'wx56e1cfc52aab630f') {
|
||||
return { referrerInfo: { appId, extraData: { operationId: operation.operation_id, action: 'bind',
|
||||
requestId: `joint-${operation.operation_id}`, code: 'OK', success: true, iccid, ...data } } }
|
||||
}
|
||||
test('only matching source, operation, action and business request can confirm', () => {
|
||||
const { api } = load()
|
||||
api.rememberOperation(operation)
|
||||
assert.equal(api.captureTrafficReturn(returned({}, 'wrong')), false)
|
||||
for (const invalid of [{ operationId: 'old' }, { action: 'unbind' }, { requestId: 'wrong' }, { success: 'true' }, { iccid: 'short' }]) {
|
||||
assert.equal(api.captureTrafficReturn(returned(invalid)), false)
|
||||
}
|
||||
assert.equal(api.captureTrafficReturn(returned()), true)
|
||||
})
|
||||
test('receipt survives network failure and account switch cannot consume it', async () => {
|
||||
const context = load()
|
||||
context.api.rememberOperation(operation)
|
||||
context.api.captureTrafficReturn(returned())
|
||||
context.request(async () => { throw new Error('network') })
|
||||
await assert.rejects(context.api.flushTrafficReceipt(), /network/)
|
||||
assert.ok(context.api.getPendingTraffic().receipt)
|
||||
context.user(8)
|
||||
assert.equal(context.api.getPendingTraffic(), null)
|
||||
assert.equal(context.api.captureTrafficReturn(returned()), false)
|
||||
context.user(7)
|
||||
context.request(async () => ({ ...operation, status: 'completed' }))
|
||||
await context.api.flushTrafficReceipt()
|
||||
assert.equal(context.api.getPendingTraffic().receipt, undefined)
|
||||
})
|
||||
test('only confirmed association opens query and recharge, unbinding closes them', () => {
|
||||
const { api } = load()
|
||||
assert.equal(api.trafficLinked(null), false)
|
||||
assert.equal(api.trafficLinked({ bind: operation }), false)
|
||||
assert.equal(api.trafficLinked({ bind: { ...operation, status: 'completed', traffic_status: 'client_confirmed' }, unbind: null }), false)
|
||||
assert.equal(api.trafficLinked({ bind: { ...operation, status: 'completed', traffic_status: 'server_confirmed' }, unbind: null }), true)
|
||||
assert.equal(api.trafficLinked({ bind: { ...operation, status: 'completed' }, unbind: { status: 'pending' } }), false)
|
||||
})
|
||||
test('jump uses trial for testing and release in production and never treats navigation as binding', async () => {
|
||||
const context = load()
|
||||
context.request(async () => ({ operation, target_app_id: 'wx56e1cfc52aab630f', handoff_token: 'secret', request_id: `joint-${operation.operation_id}`, source_binding_id: 'banban:test' }))
|
||||
assert.equal(await context.api.jumpTraffic(operation), null)
|
||||
assert.equal(context.jumps[0].envVersion, 'trial')
|
||||
assert.equal(context.api.getPendingTraffic().operation.status, 'pending')
|
||||
assert.ok(!JSON.stringify([...context.storage.values()]).includes('secret'))
|
||||
context.version('release')
|
||||
await context.api.jumpTraffic(operation)
|
||||
assert.equal(context.jumps[1].envVersion, 'release')
|
||||
assert.equal(context.timers.size, 0)
|
||||
})
|
||||
test('a late response after account change cannot start a jump or overwrite state', async () => {
|
||||
const context = load()
|
||||
context.request(async () => { context.user(8); return { operation } })
|
||||
await assert.rejects(context.api.jumpTraffic(operation), /账号已变化/)
|
||||
assert.equal(context.jumps.length, 0)
|
||||
assert.equal(context.api.getPendingTraffic(), null)
|
||||
})
|
||||
test('rebind discards a stale receipt and starts a current operation once', async () => {
|
||||
const context = load()
|
||||
context.api.rememberOperation(operation)
|
||||
context.api.captureTrafficReturn(returned())
|
||||
const urls = []
|
||||
context.request(async url => {
|
||||
urls.push(url)
|
||||
if (url.endsWith('/result')) throw Object.assign(new Error('stale'), { code: 'STALE_OPERATION' })
|
||||
return { ...operation, operation_id: 'new-instance' }
|
||||
})
|
||||
const resumed = await context.api.resumeTrafficOperation(operation.device_id, 'bind')
|
||||
assert.equal(resumed.operation_id, 'new-instance')
|
||||
assert.equal(urls.length, 2)
|
||||
assert.equal(context.api.getPendingTraffic().receipt, undefined)
|
||||
})
|
||||
test('stale cached operation recovers once; network failure keeps its receipt for retry', async () => {
|
||||
const context = load()
|
||||
context.api.rememberOperation(operation)
|
||||
context.request(async url => {
|
||||
if (url.endsWith(`${operation.operation_id}/check`)) throw Object.assign(new Error('stale'), { code: 'STALE_OPERATION' })
|
||||
return { ...operation, operation_id: 'new-instance' }
|
||||
})
|
||||
assert.equal((await context.api.resumeTrafficOperation(operation.device_id, 'bind')).operation_id, 'new-instance')
|
||||
context.api.rememberOperation(operation)
|
||||
context.api.captureTrafficReturn(returned())
|
||||
context.request(async () => { throw new Error('network') })
|
||||
await assert.rejects(context.api.resumeTrafficOperation(operation.device_id, 'bind'), /network/)
|
||||
assert.ok(context.api.getPendingTraffic().receipt)
|
||||
})
|
||||
test('missing navigation callback cannot keep the management button locked forever', async () => {
|
||||
const context = load()
|
||||
const pending = context.api.openTrafficPage(operation.device_id, 'unbind')
|
||||
const [timer, duration] = [...context.timers][0]
|
||||
assert.equal(duration, 15000)
|
||||
timer()
|
||||
await assert.rejects(pending, /跳转等待已结束/)
|
||||
assert.equal(context.timers.size, 0)
|
||||
})
|
||||
test('server-confirmed release proceeds locally without a redundant 4G jump', async () => {
|
||||
const context = load()
|
||||
const released = { ...operation, action: 'unbind', traffic_status: 'server_confirmed' }
|
||||
context.request(async () => ({ operation: released }))
|
||||
assert.deepEqual(await context.api.jumpTraffic(released), released)
|
||||
assert.equal(context.jumps.length, 0)
|
||||
})
|
||||
test('a legacy client receipt alone cannot skip the 4G result check', async () => {
|
||||
const context = load()
|
||||
const pending = { ...operation, action: 'unbind', traffic_status: 'client_confirmed' }
|
||||
context.request(async () => ({ operation: pending, target_app_id: 'wx56e1cfc52aab630f', iccid,
|
||||
request_id: `joint-${operation.operation_id}`, source_binding_id: 'banban:test' }))
|
||||
assert.equal(await context.api.jumpTraffic(pending), null)
|
||||
assert.equal(context.jumps.length, 1)
|
||||
})
|
||||
test('management refresh checks the original relation before showing traffic entrances', async () => {
|
||||
const context = load()
|
||||
const calls = []
|
||||
context.request(async url => {
|
||||
calls.push(url)
|
||||
return url.endsWith('/check') ? { ...operation, status: 'pending', traffic_status: 'pending' }
|
||||
: { device_id: operation.device_id, bind: { ...operation, status: 'completed', traffic_status: 'server_confirmed' }, unbind: null }
|
||||
})
|
||||
const overview = await context.api.getTrafficOverview(operation.device_id)
|
||||
assert.equal(calls.length, 2)
|
||||
assert.equal(context.api.trafficLinked(overview), false)
|
||||
})
|
||||
@@ -0,0 +1,166 @@
|
||||
# Banban 与 4G 小程序流量关联、联合解绑联调说明
|
||||
|
||||
当前契约以 [4G 后端接口文档 (2)](./设备直接绑定接口联调文档(2).md) 为准。本文描述 Banban 后端、Banban 小程序及 `/Users/stu2not/4g-miniprogram` 的本地实现；第 10 节为此前版本的线上操作记录，不表示新版关系查询/关闭流程已部署。
|
||||
|
||||
## 1. 业务规则
|
||||
|
||||
- Banban NFC 绑定成功即可正常使用设备；4G 关联允许失败、取消或稍后处理。
|
||||
- 管理页查询原 4G 关系，只有后端确认关联有效才显示查询、充值入口。
|
||||
- 用户确认联合解绑后，持久化解绑操作，阻止此绑定实例继续申请 handoff。
|
||||
- Banban 必须调用 4G 关系关闭接口，并取得 `canUnbind=true` 才能解除本地设备绑定。
|
||||
- 4G 已在其他入口解绑时，可直接确认后完成 Banban 解绑，不必再次跳转小程序。
|
||||
- `unknown`、403、404、网络失败和不存在记录均不能作为已解绑依据。
|
||||
- 不把客户端回报或当前用户设备列表中存在同一 ICCID 当作原关系有效的证明。
|
||||
|
||||
## 2. 身份与绑定实例
|
||||
|
||||
| 小程序 | AppID |
|
||||
| --- | --- |
|
||||
| Banban | `wx29ce99ce96b56cd9` |
|
||||
| 4G 设备管理 | `wx56e1cfc52aab630f` |
|
||||
|
||||
两个小程序分别登录。服务密钥仅供后端使用，不进入小程序、页面参数或日志。开发版/体验版跳转目标体验版，正式版跳转目标正式版，两侧需协调发布。
|
||||
|
||||
设备每次重新建立 Banban 绑定时生成新的 `device_bindings.binding_instance_id`。加卡、关联宝贝保持原实例。原有 `sourceBindingId=banban:{binding_instance_id}` 保持稳定，查询/关闭路径对整个 ID 做 URL 编码，包括冒号；不能为旧关系换 ID 绕过关闭状态。
|
||||
|
||||
## 3. ICCID 来源与保存
|
||||
|
||||
设备成功的 `006` 回复：
|
||||
|
||||
```json
|
||||
{
|
||||
"msg_id": "006",
|
||||
"status": "success",
|
||||
"data": {
|
||||
"uuid": "53D22B6DA20001",
|
||||
"iccid": "898604E91123D1334901"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
ICCID 为 18～22 位字母或数字，归一化为大写，持久化到 `device_settings.iccid`。准备操作时保存到操作表作为快照。不能从 IMEI 推导；设备换卡或其他设备占用同一 ICCID 时不覆盖原记录。
|
||||
|
||||
保存最多等待 2 秒；缺失、非法或保存失败不影响 NFC 绑定。日志记录 `006 ICCID present=..., valid=...`，保存成功记录 `006 ICCID persisted`，不打印完整 ICCID。当前仅接入 `006`，没有替固件实现上报或为历史设备自动回填。
|
||||
|
||||
## 4. Banban 接口与状态
|
||||
|
||||
所有接口使用 Banban 用户登录态，并校验设备归属账号。家庭成员不能执行关联、确认或解绑。
|
||||
|
||||
| 方法与路径 | 用途 |
|
||||
| --- | --- |
|
||||
| `GET /banban/joint-bindings/devices/{device_id}` | 本地当前绑定实例的操作概况 |
|
||||
| `POST /banban/joint-bindings` | 创建/复用 `{device_id,action:bind/unbind}` 操作 |
|
||||
| `GET /banban/joint-bindings/{operation_id}` | 读取本地操作 |
|
||||
| `POST /banban/joint-bindings/{operation_id}/check` | 向 4G 查询原关系并更新本地确认状态 |
|
||||
| `POST /banban/joint-bindings/{operation_id}/prepare` | 绑定申请 handoff；解绑先关闭关系，必要时返回 4G 跳转信息 |
|
||||
| `POST /banban/joint-bindings/{operation_id}/result` | 接收客户端结果；成功仍需服务端查询确认 |
|
||||
| `POST /banban/joint-bindings/{operation_id}/finish-unbind` | 重新确认关闭结果后，事务性完成 Banban 解绑 |
|
||||
| `GET /banban/joint-bindings/devices/{device_id}/portal` | 查询原关系后返回查询/充值入口 |
|
||||
|
||||
原 `DELETE /banban/bindings/{device_id}` 返回 409，引导联合解绑。旧客户端需要更新才能使用新解绑流程。
|
||||
|
||||
操作的 `status=pending/partial_failed/completed` 不代表 Banban 是否已绑定。新增 `traffic_status=server_confirmed` 表示 4G 服务端关系查询/关闭已确认；旧的 `client_confirmed` 只代表客户端回报，不能授权解绑。字段已为 VARCHAR，无需为本次新增状态再加列。
|
||||
|
||||
绑定确认要求原关系为 `bound + open`。解绑确认要求 4G 明确返回 `canUnbind=true`，同时校验 `closing`、无待处理凭证、不再接受 handoff、状态为 `unbound/never_bound`。响应必须 HTTP 200、业务码 OK、sourceBindingId 匹配，布尔字段必须是布尔值，checkedAt 必须是合法 UTC 时间。
|
||||
|
||||
## 5. 流量关联流程
|
||||
|
||||
1. Banban NFC 绑定独立完成，用户自愿继续关联。
|
||||
2. 后端使用服务凭证向 `POST /internal/v1/handoff-tokens` 申请凭证；sourceBindingId 始终对应同一 ICCID。
|
||||
3. 4G 小程序使用自身登录态调用 `POST /api/v1/program/bindings/handoff`；原消费请求重试必须沿用 token 与业务 requestId。
|
||||
4. 客户端返回经过字段匹配的结果，Banban 再使用 GET 关系接口确认原绑定，确认后显示查询/充值入口。
|
||||
5. 申请返回 `HANDOFF_TOKEN_USED` 时，Banban 直接查询原关系；只有原绑定仍有效才恢复成功，不再跳转后按当前 ICCID 设备列表猜测。
|
||||
6. 4G 小程序即使保存过成功结果，再次提交也让 4G 后端校验原 token，防止旧回执关联到后来的其他绑定。旧 recoveryOnly 入口提示返回 Banban 确认。
|
||||
|
||||
关联失败不回滚 Banban 绑定。管理页刷新和打开查询/充值入口都会检查原关系，4G 侧独立解绑后不会继续把旧缓存当作有效关联。
|
||||
|
||||
## 6. 联合解绑流程
|
||||
|
||||
1. 用户确认后创建持久化 `action=unbind` 操作；此记录阻止同实例再申请 handoff。
|
||||
2. 用户点击继续，调用 `POST /internal/v1/binding-relations/{sourceBindingId}/close`，业务请求号为 `bb-close-{operation_id}`。
|
||||
3. 返回 `canUnbind=true`：无需跳转，直接执行本地解绑。此判断仅依赖原关系，ICCID 缺失也不会挡住已经得到的服务端确认。
|
||||
4. 返回 `bound`：保留 Banban 绑定，携带原 ICCID 跳转 4G 小程序，用户用自己的 4G 登录态调用现有 unbind 接口。
|
||||
5. 用户返回、重新打开页面或在 4G 其他入口完成解绑后，可以主动查询/继续处理；最终提交前再次调用幂等 close，只有确认放行才执行本地事务。
|
||||
6. 本地设备解绑、家庭关联停用、操作完成在同一事务内提交。失败保留已确认状态，重试仍检查原关系；已完成操作可幂等返回。
|
||||
7. 未知关系、鉴权错误、限流、网络异常均保留绑定，不执行自动猜测或无限重试。
|
||||
|
||||
| 4G 状态 | 处理 |
|
||||
| --- | --- |
|
||||
| 原绑定仍有效 | 保留 Banban，前往 4G 解绑 |
|
||||
| 原绑定已解除 | 关闭后确认 canUnbind=true，再解绑 Banban |
|
||||
| 有记录证明从未完成绑定 | 撤销待消费凭证并确认放行 |
|
||||
| 没有关系记录或历史不明确 | unknown，不自动放行，需核查 |
|
||||
|
||||
关闭不会自动解除 4G 用户绑定或删除套餐。它会持续禁止该 sourceBindingId 签发/消费 handoff，文档没有取消关闭接口。页面明确提示继续后不能恢复本次关联；“稍后处理”只是离开页面，不恢复已关闭关系。
|
||||
|
||||
4G 设备详情页对本机留有 Banban 标记的设备引导回 Banban；清缓存/换手机无法依靠该本地标记拦截所有独立解绑，服务端关系查询负责后续确认。
|
||||
|
||||
## 7. 有限等待与并发
|
||||
|
||||
| 环节 | 上限 |
|
||||
| --- | --- |
|
||||
| 006 保存 ICCID | 2 秒，失败继续 NFC 绑定 |
|
||||
| Banban 新业务接口 | 8 秒总期限 |
|
||||
| Banban 调用 4G | 默认 6 秒网络超时，外层受 8 秒期限约束 |
|
||||
| Banban 小程序 HTTP | 10 秒，平台超时及独立计时器 |
|
||||
| 4G 微信登录 | 10 秒 |
|
||||
| 4G 每次 HTTP | 15 秒，超时终止请求 |
|
||||
| 4G 单次操作 | 45 秒 |
|
||||
| 页面及跨小程序跳转 | 15 秒 |
|
||||
|
||||
无自动无限循环或长期轮询，失败后用户主动重试。关闭按 sourceBindingId 幂等；超时不换绑定实例或业务请求号。
|
||||
|
||||
Banban 不跨网络持有数据库行锁：先读取、关闭事务，再请求 4G，返回后重新校验当前设备所有者和绑定实例。最终事务再次校验操作。4G 端关闭与签发/消费的互斥依赖新版后端的关系锁；本地模拟测试不能替代这部分 MySQL 并发验收。
|
||||
|
||||
## 8. 配置与数据库
|
||||
|
||||
```dotenv
|
||||
TRAFFIC_4G_API_BASE_URL=https://role.api.talkingq.com/traffic-4g
|
||||
BANBAN_HANDOFF_SERVICE_TOKEN=<两侧一致的服务端密钥>
|
||||
TRAFFIC_4G_TARGET_APP_ID=wx56e1cfc52aab630f
|
||||
TRAFFIC_4G_TIMEOUT_SECONDS=6
|
||||
```
|
||||
|
||||
查询和关闭沿用现有密钥。必须先部署 4G 新 JAR、V13 迁移及 Nginx 新路由；仅替换 JAR 不保证公网接口可用。历史关系无法准确回填时保持 unknown。
|
||||
|
||||
Banban 首次安装本功能：已有库执行一次 `talkingq-url/mysql/migrations/20260923_joint_binding.sql`；新库使用 `mysql/init/02-init.sql` 与 `03-joint-binding.sql`。已执行迁移的生产库不要重跑 ADD COLUMN。本次查询/关闭接入不需要新增 Banban 数据库迁移。
|
||||
|
||||
## 9. 本地验证与发布
|
||||
|
||||
```bash
|
||||
# talkingq-url（既有告警测试断言此测试地址，不需要真实 .env）
|
||||
SERVER_HOST=192.168.101.78 .venv/bin/python -m pytest tests -q
|
||||
# banban-mini
|
||||
npm run test:ui
|
||||
npm run build:weapp
|
||||
# 4g-miniprogram
|
||||
node --test tests/*.test.cjs
|
||||
```
|
||||
|
||||
覆盖：原关系解绑、从未绑定、未知关系、旧客户端成功回执、原关系与后来 ICCID 绑定区别、关闭失败重试、事务回滚、重绑后的旧响应、格式/鉴权/限流/超时、页面恢复及跳转计时。
|
||||
|
||||
状态事务测试使用 SQLite 适配，HTTP 使用模拟传输；没有访问生产 4G 接口或验证真实 MySQL 锁竞争。微信登录、真机跨小程序返回、V13 历史回填和真实关闭/消费并发需部署到联调环境后验收。伴伴构建可执行，全量 TypeScript 检查有既有类型错误，不将构建通过等同于全量类型检查通过。
|
||||
|
||||
2026-09-23 本次提交内容在独立目录验证：后端 142 项通过，Banban 小程序 30 项通过且微信小程序构建成功，4G 小程序 16 项通过且全部页面脚本/JSON 校验通过。全量 TypeScript 检查的 6 项错误与修改前 HEAD 一致。本次只做本地实施、测试与 Git 交付，不部署新版服务或上传小程序。
|
||||
|
||||
## 10. 2026-09-23 服务器更新记录
|
||||
|
||||
按用户授权，于北京时间 14:21 完成 Banban 后端更新，范围为本功能相关的 8 个 Python 文件和已有库迁移脚本。未上传两个小程序，未配置 4G 服务密钥。
|
||||
|
||||
服务器：`101.35.224.118`，应用目录：`/home/ubuntu/banban-backend`。
|
||||
|
||||
备份目录：`/home/ubuntu/banban-backups/joint-binding-20260923-1411`，仅 root 可读：
|
||||
|
||||
- `code-and-config.tar.gz`：更新前代码与配置，排除虚拟环境、资源、运行数据和日志。
|
||||
- `binding-tables.sql.gz`：`device_settings`、`device_bindings`、`device_family_members`、`device_bind_history` 的一致性快照。
|
||||
- `replaced-files/`、`manifest-before.json`、`manifest-after.json`：被替换文件和更新前后 SHA-256 清单。
|
||||
|
||||
迁移后四表记录数仍为 63、22、33、144；22 条绑定均生成互不重复的绑定实例 UUID。新操作表为空，未为了验证而创建或解除真实绑定。
|
||||
|
||||
更新后验证：进程 `511137` 启动成功，MQTT 重新连接；7 个新接口路径已注册；设备所有者状态查询与原绑定查询均为 HTTP 200；未关联设备的查询/充值跳转接口返回预期 409；未登录访问返回 401；公网 HTTPS OpenAPI 和绑定提示音均为 200。
|
||||
|
||||
截至 14:22，`TalkingQ_ZHWK00003111` 的 ICCID 仍为空，尚无更新后的 `006 ICCID` 检测日志，需要设备重新上报。`BANBAN_HANDOFF_SERVICE_TOKEN` 仍未配置，申请 4G 凭证暂不可用。
|
||||
|
||||
14:25 按用户提供的密钥配置 `BANBAN_HANDOFF_SERVICE_TOKEN`。更新前 `.env` 备份于 `/home/ubuntu/banban-backups/handoff-token-20260923-1424/env.before`；其他配置项保持原值，现有 `.env` 权限收紧为 600。独立进程校验有效配置与提供值一致，重启后进程为 `512483`，HTTPS OpenAPI 为 200，MQTT 连接正常。密钥值不记录到文档或仓库。
|
||||
|
||||
4G 申请接口空请求分别在无密钥、有密钥时均返回 400 `INVALID_REQUEST`，说明该检查无法证明密钥鉴权成功；未提交有效 ICCID 或创建交接凭证，实际关联仍待正常业务请求验证。
|
||||
@@ -0,0 +1,564 @@
|
||||
# 设备直接绑定接口联调文档
|
||||
|
||||
## 1. 适用范围
|
||||
|
||||
本文档用于 Banban 小程序与 4G 管理后端之间的“设备无法获取绑定码时直接绑定”联调。
|
||||
|
||||
2026-09-23 更新：新增按 `sourceBindingId` 查询原绑定关系、关闭 handoff 关联的服务端接口，见第 11、12 节。伴伴解绑必须以 `canUnbind=true` 为放行条件，不能只看 ICCID 当前状态或把查不到当成已经解绑。
|
||||
|
||||
生产环境推荐使用 `handoffToken` 两段式流程：
|
||||
|
||||
1. Banban 后端使用服务凭证，向 4G 管理后端申请一次性 `handoffToken`。
|
||||
2. 4G 小程序用户完成微信登录后，携带程序用户 Token 和 `handoffToken` 完成设备绑定。
|
||||
|
||||
该流程仍然复用普通绑定码绑定的事务逻辑，成功后会：
|
||||
|
||||
- 创建当前 4G 小程序用户与设备的有效绑定关系；
|
||||
- 将 `sim_card.binding_status` 更新为 `bound`；
|
||||
- 作废该设备尚未使用的绑定验证码；
|
||||
- 清理绑定验证码缓存；
|
||||
- 写入绑定审计记录。
|
||||
|
||||
handoff 申请接口会在服务 Token 校验通过后，按 ICCID 幂等创建或复用 4G 后端的 `sim_card` 档案。新建档案初始状态为 `active`、`unbound`、`sync_status=pending`；消费 handoffToken 后才会创建用户绑定并将绑定状态更新为 `bound`。因此 Banban 不需要提前调用 4G 后端的设备注册接口。
|
||||
|
||||
该自动建档能力只对已认证的 Banban 服务接口开放，不代表可以通过公开接口任意写入 ICCID。ICCID 格式仍必须合法；如果已有档案状态为非 `active`，申请会被拒绝。
|
||||
|
||||
## 2. 联调环境与配置
|
||||
|
||||
当前生产环境通过 Nginx 的 `/traffic-4g` 前缀访问，以下 `BASE_URL` 必须包含此前缀：
|
||||
|
||||
```text
|
||||
BASE_URL=https://role.api.talkingq.com/traffic-4g
|
||||
```
|
||||
|
||||
4G 后端需要配置并重启后才会生效：
|
||||
|
||||
```bash
|
||||
HANDOFF_ENABLED=true
|
||||
HANDOFF_TOKEN_TTL=5m
|
||||
HANDOFF_TOKEN_PEPPER=<独立的高强度随机值>
|
||||
BANBAN_HANDOFF_SERVICE_TOKEN=<独立的高强度随机值>
|
||||
WECHAT_APP_ID=<4G 小程序 AppID>
|
||||
DIRECT_ICCID_BINDING_ENABLED=false
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `BANBAN_HANDOFF_SERVICE_TOKEN` 只允许保存在 Banban 后端服务端，不能下发到小程序或前端页面。
|
||||
- `HANDOFF_TOKEN_PEPPER` 只允许保存在 4G 后端服务端，不能与服务 Token 共用。
|
||||
- `HANDOFF_TOKEN_TTL=5m` 表示凭证默认有效 5 分钟，具体有效期以申请接口返回的 `expiresIn` 为准。
|
||||
- 当前环境的 `BINDING_ALLOWED_ORIGINS` 可以继续保留 `https://banban.api.talkingq.com,http://192.168.101.151`，但 handoff 流程不依赖 Origin 证明设备归属。
|
||||
- 新增关系查询、关闭接口继续使用 `BANBAN_HANDOFF_SERVICE_TOKEN`，不需要新增密钥或修改 `.env`。即使 `HANDOFF_ENABLED=false`，仍可使用正确服务凭证查询、关闭已有关系。
|
||||
|
||||
## 3. 完整调用时序
|
||||
|
||||
```text
|
||||
Banban 后端 4G 管理后端 4G 小程序
|
||||
| | |
|
||||
|-- X-Service-Token + ICCID -------->| |
|
||||
|<--------- handoffToken ------------| |
|
||||
| | |
|
||||
| |<-- wx.login code --------|
|
||||
| |---- accessToken -------->|
|
||||
| | |
|
||||
| |<-- accessToken + token --|
|
||||
| |---- 完成设备绑定 -------->|
|
||||
```
|
||||
|
||||
Banban 后端申请凭证的接口只能由服务端调用；4G 小程序消费凭证的接口只能由登录后的 `PROGRAM_USER` 调用。
|
||||
|
||||
## 4. 接口一：Banban 后端申请一次性 handoffToken
|
||||
|
||||
### 4.1 请求地址
|
||||
|
||||
```http
|
||||
POST /internal/v1/handoff-tokens
|
||||
```
|
||||
|
||||
完整地址：
|
||||
|
||||
```text
|
||||
https://role.api.talkingq.com/traffic-4g/internal/v1/handoff-tokens
|
||||
```
|
||||
|
||||
必须使用 HTTPS。该接口不使用小程序 JWT，而是使用服务间 Token。
|
||||
|
||||
### 4.2 请求头
|
||||
|
||||
```http
|
||||
X-Service-Token: <BANBAN_HANDOFF_SERVICE_TOKEN>
|
||||
Content-Type: application/json
|
||||
X-Request-Id: banban-handoff-20260922-0001
|
||||
```
|
||||
|
||||
`X-Service-Token` 的值必须与 4G 后端环境变量 `BANBAN_HANDOFF_SERVICE_TOKEN` 完全一致。
|
||||
|
||||
`X-Request-Id` 仅用于 HTTP 请求追踪，建议使用 8 至 64 位的字母、数字、点、下划线或短横线。真正的业务幂等键是请求体中的 `requestId`。
|
||||
|
||||
### 4.3 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"iccid": "898604E91123D1334901",
|
||||
"sourceBindingId": "banban-binding-100001",
|
||||
"requestId": "banban-handoff-20260922-0001"
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必填 | 约束与说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `iccid` | string | 是 | 18 至 22 位字母或数字，后端会统一转为大写；已登记的 active 档案会复用，未登记时由 4G 后端自动建档 |
|
||||
| `sourceBindingId` | string | 是 | Banban 侧绑定关系的稳定唯一 ID，最长 128 个字符；同一绑定关系保持不变，且必须始终对应同一 ICCID。新接入使用 UUID 或字母、数字、短横线、下划线，便于作为查询路径参数 |
|
||||
| `requestId` | string | 是 | 本次申请的幂等请求号，最长 64 个字符；网络超时重试必须保持不变 |
|
||||
|
||||
`sourceBindingId` 不要使用每次随机生成的值，否则无法实现申请接口幂等。`requestId` 建议由 Banban 后端生成，例如 `banban-handoff-20260922-0001`。
|
||||
|
||||
即使换了 `requestId`，同一 `sourceBindingId` 也不能切换 ICCID，否则返回 `IDEMPOTENCY_CONFLICT`。伴伴关系进入 `closing` 后不得再申请或消费 handoff；完成解绑并重新建立伴伴绑定时，必须使用新关系的唯一 ID，不能复用旧 ID 绕过关闭状态。
|
||||
|
||||
### 4.4 curl 示例
|
||||
|
||||
以下命令只能在 Banban 后端服务器或安全的服务端环境执行：
|
||||
|
||||
```bash
|
||||
export BASE_URL="https://role.api.talkingq.com/traffic-4g"
|
||||
export BANBAN_HANDOFF_SERVICE_TOKEN="<服务端密钥>"
|
||||
|
||||
curl -i -sS -X POST "$BASE_URL/internal/v1/handoff-tokens" \
|
||||
-H "X-Service-Token: $BANBAN_HANDOFF_SERVICE_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-Request-Id: banban-handoff-20260922-0001" \
|
||||
--data '{
|
||||
"iccid": "898604E91123D1334901",
|
||||
"sourceBindingId": "banban-binding-100001",
|
||||
"requestId": "banban-handoff-20260922-0001"
|
||||
}'
|
||||
```
|
||||
|
||||
### 4.5 成功响应
|
||||
|
||||
HTTP 状态码为 `200`：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "OK",
|
||||
"message": "success",
|
||||
"data": {
|
||||
"targetAppId": "<4G 小程序 AppID>",
|
||||
"handoffToken": "<一次性凭证>",
|
||||
"expiresIn": 300
|
||||
},
|
||||
"requestId": "banban-handoff-20260922-0001",
|
||||
"timestamp": "2026-09-22T03:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 说明 |
|
||||
| --- | --- |
|
||||
| `data.targetAppId` | 允许消费该凭证的目标小程序 AppID，必须与 4G 小程序登录身份一致 |
|
||||
| `data.handoffToken` | 一次性绑定凭证，只能传给 4G 小程序的绑定接口，不要写入日志或返回给不可信客户端 |
|
||||
| `data.expiresIn` | 剩余有效秒数，消费时以服务端校验结果为准 |
|
||||
|
||||
相同的 `sourceBindingId + requestId` 重试时：
|
||||
|
||||
- 凭证仍为 `active` 且未过期：返回同一凭证，不会重复创建；
|
||||
- 对应 ICCID 发生变化：返回 `IDEMPOTENCY_CONFLICT`；
|
||||
- 凭证已消费：返回 `HANDOFF_TOKEN_USED`；
|
||||
- 凭证已过期：返回 `HANDOFF_TOKEN_EXPIRED`。
|
||||
|
||||
## 5. 接口二：4G 小程序消费 handoffToken 完成绑定
|
||||
|
||||
### 5.1 先获取 4G 小程序 accessToken
|
||||
|
||||
4G 小程序先调用微信 `wx.login()`，再把返回的临时 `code` 交给 4G 后端：
|
||||
|
||||
```http
|
||||
POST /api/v1/program/auth/login
|
||||
```
|
||||
|
||||
请求：
|
||||
|
||||
```http
|
||||
Content-Type: application/json
|
||||
X-Request-Id: program-login-20260922-0001
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "<4G 小程序 wx.login 返回的 code>"
|
||||
}
|
||||
```
|
||||
|
||||
curl 示例：
|
||||
|
||||
```bash
|
||||
curl -i -sS -X POST "$BASE_URL/api/v1/program/auth/login" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-Request-Id: program-login-20260922-0001" \
|
||||
--data '{"code":"<4G 小程序 wx.login 返回的 code>"}'
|
||||
```
|
||||
|
||||
成功响应中的 `data.accessToken` 是后续绑定接口需要的程序用户 Token：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "OK",
|
||||
"message": "success",
|
||||
"data": {
|
||||
"accessToken": "<PROGRAM_USER_ACCESS_TOKEN>",
|
||||
"expiresAt": "2026-09-22T15:30:00Z",
|
||||
"user": {
|
||||
"userId": 10001,
|
||||
"status": "active"
|
||||
}
|
||||
},
|
||||
"requestId": "program-login-20260922-0001",
|
||||
"timestamp": "2026-09-22T03:31:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
必须使用 4G 小程序自己的 `wx.login()` code，不能使用 Banban 小程序的登录 code，也不能使用 `SUPER_ADMIN`、`FACTORY_PROVISIONER` 或设备 Token。
|
||||
|
||||
### 5.2 请求地址
|
||||
|
||||
```http
|
||||
POST /api/v1/program/bindings/handoff
|
||||
```
|
||||
|
||||
完整地址：
|
||||
|
||||
```text
|
||||
https://role.api.talkingq.com/traffic-4g/api/v1/program/bindings/handoff
|
||||
```
|
||||
|
||||
### 5.3 请求头
|
||||
|
||||
```http
|
||||
Authorization: Bearer <PROGRAM_USER_ACCESS_TOKEN>
|
||||
Content-Type: application/json
|
||||
X-Request-Id: program-handoff-20260922-0001
|
||||
```
|
||||
|
||||
该接口不要求 `Origin` 白名单。权限来自程序用户 JWT、目标小程序 AppID 校验和一次性 `handoffToken`。
|
||||
|
||||
### 5.4 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"handoffToken": "<接口一返回的一次性凭证>",
|
||||
"requestId": "program-handoff-20260922-0001"
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必填 | 约束与说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `handoffToken` | string | 是 | 接口一返回的一次性凭证，最长 256 个字符；不要自行修改或解码 |
|
||||
| `requestId` | string | 是 | 本次绑定的幂等请求号，最长 64 个字符；网络超时重试时保持不变 |
|
||||
|
||||
### 5.5 curl 示例
|
||||
|
||||
```bash
|
||||
export PROGRAM_ACCESS_TOKEN="<4G 小程序登录返回的 accessToken>"
|
||||
export HANDOFF_TOKEN="<接口一返回的 handoffToken>"
|
||||
|
||||
curl -i -sS -X POST "$BASE_URL/api/v1/program/bindings/handoff" \
|
||||
-H "Authorization: Bearer $PROGRAM_ACCESS_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-Request-Id: program-handoff-20260922-0001" \
|
||||
--data "{\"handoffToken\":\"$HANDOFF_TOKEN\",\"requestId\":\"program-handoff-20260922-0001\"}"
|
||||
```
|
||||
|
||||
### 5.6 成功响应
|
||||
|
||||
HTTP 状态码为 `200`：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "OK",
|
||||
"message": "success",
|
||||
"data": {
|
||||
"iccid": "898604E91123D1334901",
|
||||
"alreadyBound": false
|
||||
},
|
||||
"requestId": "program-handoff-20260922-0001",
|
||||
"timestamp": "2026-09-22T03:32:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 说明 |
|
||||
| --- | --- |
|
||||
| `data.iccid` | 实际绑定成功的设备 ICCID |
|
||||
| `data.alreadyBound` | `false` 表示本次新建绑定；`true` 表示重复请求返回已有绑定结果 |
|
||||
|
||||
绑定、作废旧验证码、更新 SIM 绑定状态、记录 handoff 对应的具体绑定记录、消费凭证和审计记录在同一个数据库事务中完成。即使设备原本已绑定当前用户，也会记录复用的绑定记录 ID。接口成功后，可以调用 `GET /api/v1/program/devices` 验证当前用户的设备列表。
|
||||
|
||||
## 6. 幂等与重试规则
|
||||
|
||||
### 6.1 申请凭证重试
|
||||
|
||||
Banban 后端申请接口超时或未收到响应时，使用相同的 `sourceBindingId` 和 `requestId` 重试，不要重新生成请求号。这样可以复用原有有效凭证，避免创建多条 handoff 记录。
|
||||
|
||||
### 6.2 消费凭证重试
|
||||
|
||||
4G 小程序消费接口超时或网络断开时，使用相同的 `handoffToken` 和 `requestId` 重试：
|
||||
|
||||
- 如果事务已经成功提交，原绑定仍有效且伴伴关系未关闭，原消费用户重试返回 `alreadyBound=true`；
|
||||
- 如果凭证已被其他用户消费，或对应的原绑定已解绑，返回 `HANDOFF_TOKEN_USED`；设备后来重新绑定给同一用户，也不能复用旧凭证；
|
||||
- 如果伴伴已关闭此关系，返回 `HANDOFF_RELATION_CLOSED`；
|
||||
- 不要因为超时就重新向 Banban 申请新的 `sourceBindingId`，应先使用原请求参数重试或查询绑定结果。
|
||||
|
||||
### 6.3 凭证安全规则
|
||||
|
||||
- `handoffToken` 只能在服务端申请、在 4G 小程序绑定流程中消费一次；
|
||||
- 不要把 `BANBAN_HANDOFF_SERVICE_TOKEN` 放在小程序、浏览器代码、页面参数或日志中；
|
||||
- 不要把完整 `handoffToken` 写入业务日志、埋点或群聊；
|
||||
- `handoffToken` 过期、篡改或消费后不可恢复，需按原绑定关系重新申请。
|
||||
|
||||
## 7. 错误码与处理建议
|
||||
|
||||
统一错误响应结构如下，`data` 为 `null`：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "HANDOFF_TOKEN_EXPIRED",
|
||||
"message": "跨系统绑定凭证已过期",
|
||||
"data": null,
|
||||
"requestId": "program-handoff-20260922-0001",
|
||||
"timestamp": "2026-09-22T03:40:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### 7.1 申请凭证接口
|
||||
|
||||
| HTTP 状态 | `code` | 含义与处理 |
|
||||
| --- | --- | --- |
|
||||
| 400 | `INVALID_REQUEST` | ICCID、`sourceBindingId` 或 `requestId` 格式不符合约束 |
|
||||
| 401 | `HANDOFF_SERVICE_UNAUTHORIZED` | 缺少或错误的 `X-Service-Token`；确认服务端密钥配置一致 |
|
||||
| 403 | `DEVICE_DISABLED` | 设备状态不是 `active`；先恢复设备状态 |
|
||||
| 409 | `IDEMPOTENCY_CONFLICT` | 相同幂等键对应了不同 ICCID；检查 `sourceBindingId` 和 `requestId` |
|
||||
| 409 | `HANDOFF_TOKEN_USED` | 原凭证已经消费；按当前绑定结果处理或重新发起新业务请求 |
|
||||
| 409 | `HANDOFF_RELATION_CLOSED` | 此伴伴关系已停止新关联；不能重新申请凭证 |
|
||||
| 409 | `HANDOFF_RELATION_UNKNOWN` | 历史记录无法准确关联，需要核查，不能绕过检查重新申请 |
|
||||
| 410 | `HANDOFF_TOKEN_EXPIRED` | 原凭证已过期；使用相同业务关系重新申请凭证 |
|
||||
| 429 | `RATE_LIMITED` | 触发申请频率限制；降低重试频率 |
|
||||
| 503 | `HANDOFF_DISABLED` | 后端未启用 handoff 流程；检查 `HANDOFF_ENABLED` |
|
||||
| 503 | `CONFIGURATION_ERROR` | handoff 密钥、4G AppID 或 TTL 配置缺失/不合法 |
|
||||
| 500 | `INTERNAL_ERROR` | 自动建档后无法读取 SIM 档案；需要联系后端排查数据库或事务状态 |
|
||||
|
||||
### 7.2 消费凭证接口
|
||||
|
||||
| HTTP 状态 | `code` | 含义与处理 |
|
||||
| --- | --- | --- |
|
||||
| 400 | `INVALID_REQUEST` | 请求体字段缺失或超过长度限制 |
|
||||
| 400 | `HANDOFF_TOKEN_INVALID` | 凭证不存在、被篡改或已失效 |
|
||||
| 401 | `UNAUTHORIZED` | 未登录、Token 过期或 Token 不是程序用户 Token |
|
||||
| 403 | `HANDOFF_TARGET_APP_MISMATCH` | 当前登录的小程序不是接口一返回的 `targetAppId` |
|
||||
| 403 | `DEVICE_DISABLED` | 设备当前被禁用 |
|
||||
| 409 | `HANDOFF_TOKEN_USED` | 凭证已使用且无法匹配当前用户的重试 |
|
||||
| 409 | `DEVICE_ALREADY_BOUND` | 设备已经绑定其他程序用户 |
|
||||
| 409 | `IDEMPOTENCY_CONFLICT` | 相同 `requestId` 对应了不同设备或不同绑定操作 |
|
||||
| 409 | `HANDOFF_RELATION_CLOSED` | 伴伴关系已关闭；已有未消费凭证不能再绑定 |
|
||||
| 409 | `HANDOFF_RELATION_UNKNOWN` | 无法确认此凭证对应的原关系，需联系后端核查 |
|
||||
| 410 | `HANDOFF_TOKEN_EXPIRED` | 凭证已经过期 |
|
||||
| 429 | `RATE_LIMITED` | 用户、IP 或凭证消费频率过高 |
|
||||
| 503 | `HANDOFF_DISABLED` | 后端未启用 handoff 流程 |
|
||||
|
||||
## 8. 兼容接口：裸 ICCID 直接绑定（逐步下线）
|
||||
|
||||
旧接口地址：
|
||||
|
||||
```http
|
||||
POST /api/v1/program/bindings/by-iccid
|
||||
```
|
||||
|
||||
该接口要求：
|
||||
|
||||
- 使用 `PROGRAM_USER` 的 `Authorization: Bearer` Token；
|
||||
- 携带与页面完全一致的 `Origin`；
|
||||
- `Origin` 必须存在于 `BINDING_ALLOWED_ORIGINS`；
|
||||
- 后端配置 `DIRECT_ICCID_BINDING_ENABLED=true`。
|
||||
|
||||
当前环境已配置：
|
||||
|
||||
```bash
|
||||
DIRECT_ICCID_BINDING_ENABLED=false
|
||||
```
|
||||
|
||||
因此当前调用该接口会返回 HTTP `410` 和 `DIRECT_BINDING_DISABLED`。只有临时兼容旧版本联调时，才允许在服务端显式开启：
|
||||
|
||||
```bash
|
||||
DIRECT_ICCID_BINDING_ENABLED=true
|
||||
BINDING_ALLOWED_ORIGINS=https://banban.api.talkingq.com,http://192.168.101.151
|
||||
```
|
||||
|
||||
旧接口请求示例：
|
||||
|
||||
```http
|
||||
POST /api/v1/program/bindings/by-iccid
|
||||
Origin: https://banban.api.talkingq.com
|
||||
Authorization: Bearer <PROGRAM_USER_ACCESS_TOKEN>
|
||||
Content-Type: application/json
|
||||
X-Request-Id: direct-bind-20260922-0001
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"iccid": "898604E91123D1334901",
|
||||
"requestId": "direct-bind-20260922-0001"
|
||||
}
|
||||
```
|
||||
|
||||
该接口无法证明 Banban 后端实际拥有该 ICCID，不应作为新的跨系统正式方案。新接入方必须使用本文档第 4、5 节的 handoffToken 流程。
|
||||
|
||||
## 9. 联调验收清单
|
||||
|
||||
建议按以下顺序验收：
|
||||
|
||||
1. 使用尚未登记的测试 ICCID，申请接口返回 `code=OK`、`targetAppId`、`handoffToken` 和正数 `expiresIn`。
|
||||
2. 查询数据库，确认该 ICCID 已自动写入 `sim_card`，初始为 `status=active`、`binding_status=unbound`、`sync_status=pending`。
|
||||
3. 使用 4G 小程序的 `wx.login()` code 登录，确认返回 `PROGRAM_USER` 的 `accessToken`。
|
||||
4. 使用该 `accessToken` 消费 handoffToken，返回 `code=OK`、正确 ICCID、`alreadyBound=false`。
|
||||
5. 查询 `GET /api/v1/program/devices`，确认设备出现在当前 4G 小程序用户列表中。
|
||||
6. 使用相同 `sourceBindingId + requestId` 重试申请接口，确认不会重复创建 SIM 档案或凭证。
|
||||
7. 使用相同用户、相同 handoffToken 和相同绑定 `requestId` 重试消费接口，确认返回幂等结果或可确认已绑定。
|
||||
8. 绑定成功后调用流量详情接口，确认设备可以进入 `pending` 或同步后的流量状态，而不是 `DEVICE_NOT_FOUND`。
|
||||
9. 使用其他小程序身份消费，确认返回 `HANDOFF_TARGET_APP_MISMATCH`。
|
||||
10. 使用过期或篡改后的凭证，确认分别返回 `HANDOFF_TOKEN_EXPIRED` 或 `HANDOFF_TOKEN_INVALID`。
|
||||
11. 使用已绑定到其他用户的设备，确认返回 `DEVICE_ALREADY_BOUND`，不会覆盖原绑定关系。
|
||||
12. 确认数据库中该设备的 `sim_card.binding_status` 为 `bound`，且 `user_device_binding.status` 为 `active`。
|
||||
13. 确认旧 `/bindings/by-iccid` 接口在 `DIRECT_ICCID_BINDING_ENABLED=false` 时返回 `DIRECT_BINDING_DISABLED`。
|
||||
|
||||
## 10. 联调排查信息
|
||||
|
||||
请保留以下信息用于后端排查，但不要提交 Token 或完整 ICCID：
|
||||
|
||||
- 请求路径和 HTTP 状态码；
|
||||
- 响应中的 `code`、`message`、`requestId`；
|
||||
- 请求头中的 `X-Request-Id`；
|
||||
- Banban 的 `sourceBindingId` 和脱敏后的 ICCID；
|
||||
- 调用时间（含时区）；
|
||||
- 是否使用了相同幂等参数重试。
|
||||
|
||||
不要在工单、群聊、代码仓库或日志中粘贴 `X-Service-Token`、`PROGRAM_USER_ACCESS_TOKEN` 或完整 `handoffToken`。
|
||||
|
||||
## 11. 接口三：查询这次伴伴绑定对应的 4G 关系
|
||||
|
||||
```http
|
||||
GET /internal/v1/binding-relations/{sourceBindingId}
|
||||
X-Service-Token: <BANBAN_HANDOFF_SERVICE_TOKEN>
|
||||
```
|
||||
|
||||
查询的是 `sourceBindingId` 实际关联的具体 4G 绑定记录。原绑定解绑后，即使同一 ICCID 后来被其他用户或原用户通过其他流程重新绑定，原关系仍返回 `unbound`。若未关闭的同一伴伴关系又成功消费了新 handoff，则查询追踪这次新关联。
|
||||
|
||||
```bash
|
||||
export BASE_URL="https://role.api.talkingq.com/traffic-4g"
|
||||
export SOURCE_BINDING_ID="banban-binding-100001"
|
||||
|
||||
curl -i -sS "$BASE_URL/internal/v1/binding-relations/$SOURCE_BINDING_ID" \
|
||||
-H "X-Service-Token: $BANBAN_HANDOFF_SERVICE_TOKEN" \
|
||||
-H "X-Request-Id: relation-query-20260923-0001"
|
||||
```
|
||||
|
||||
成功响应示例（四种业务状态均返回 HTTP 200）：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "OK",
|
||||
"message": "success",
|
||||
"data": {
|
||||
"sourceBindingId": "banban-binding-100001",
|
||||
"status": "never_bound",
|
||||
"pendingHandoff": true,
|
||||
"acceptingHandoff": true,
|
||||
"relationState": "open",
|
||||
"canUnbind": false,
|
||||
"reason": "NO_COMPLETED_BINDING",
|
||||
"checkedAt": "2026-09-23T08:00:00Z"
|
||||
},
|
||||
"requestId": "relation-query-20260923-0001",
|
||||
"timestamp": "2026-09-23T08:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
| `status` | 含义 | 伴伴处理 |
|
||||
| --- | --- | --- |
|
||||
| `bound` | 本次伴伴关系关联的 4G 绑定仍有效 | 提示先完成 4G 解绑 |
|
||||
| `unbound` | 关联的原 4G 绑定已由用户或管理员解除 | 完成关闭后，仅 `canUnbind=true` 才能解绑伴伴 |
|
||||
| `never_bound` | 有关系记录，且能证明尚未完成过 handoff 绑定 | 完成关闭后，仅 `canUnbind=true` 才能解绑伴伴 |
|
||||
| `unknown` | 无记录、历史无法准确关联或数据不一致 | 提示未确认，保留伴伴绑定并核查 |
|
||||
|
||||
| 字段 | 说明 |
|
||||
| --- | --- |
|
||||
| `pendingHandoff` | 是否存在 `active` 且未过期的凭证；数据库状态尚未改为 `expired` 的过期凭证不计入 |
|
||||
| `acceptingHandoff` | 此关系是否仍允许申请或消费新 handoff；还需满足功能开关、身份、设备状态等原有检查 |
|
||||
| `relationState` | `open` 允许关联；`closing` 已停止关联；`unknown` 表示没有关系记录 |
|
||||
| `canUnbind` | 仅当关系已 `closing`、无待处理凭证，且 `status` 为 `unbound/never_bound` 时为 `true` |
|
||||
| `reason` | 状态原因，例如 `NO_RELATION`、`AMBIGUOUS_HISTORY`、`ORIGINAL_BINDING_ACTIVE`、`ORIGINAL_BINDING_RELEASED`、`NO_COMPLETED_BINDING` |
|
||||
| `checkedAt` | 查询时间，UTC、带 `Z` 时区；只是本次快照时间，不是后续请求的锁或授权凭据 |
|
||||
|
||||
该 GET 不会撤销凭证或关闭关系，响应禁止缓存。即使查到 `never_bound + pendingHandoff=false`，只要仍为 `open`，`canUnbind` 就是 `false`。伴伴不能根据一次普通 GET 直接删除绑定，必须进入下一节关闭流程。
|
||||
|
||||
## 12. 接口四：关闭关联并确认是否可以解绑伴伴
|
||||
|
||||
```http
|
||||
POST /internal/v1/binding-relations/{sourceBindingId}/close
|
||||
X-Service-Token: <BANBAN_HANDOFF_SERVICE_TOKEN>
|
||||
Content-Type: application/json
|
||||
|
||||
{"requestId":"banban-close-20260923-0001"}
|
||||
```
|
||||
|
||||
`requestId` 必填，最长 64 字符，用于审计及重试追踪；关闭操作按 `sourceBindingId` 幂等，重复调用不会恢复关系，也不会重复解绑设备。返回结构与第 11 节一致。
|
||||
|
||||
```bash
|
||||
curl -i -sS -X POST "$BASE_URL/internal/v1/binding-relations/$SOURCE_BINDING_ID/close" \
|
||||
-H "X-Service-Token: $BANBAN_HANDOFF_SERVICE_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-Request-Id: banban-close-20260923-0001" \
|
||||
--data '{"requestId":"banban-close-20260923-0001"}'
|
||||
```
|
||||
|
||||
此操作会锁定关系，将其设置为 `closing`，撤销所有尚未消费的凭证，再判断原绑定是否有效。不会自动解除 4G 用户绑定，也不会删除 SIM 档案或影响已有流量、充值记录。
|
||||
|
||||
如果 `sourceBindingId` 完全没有记录，关闭操作会创建一条拒绝后续关联的记录，但仍返回 `unknown + canUnbind=false`，不会把“没有记录”变成“证明从未绑定”。
|
||||
|
||||
伴伴后端的解绑顺序：
|
||||
|
||||
1. 用户确认解绑后，先将本地伴伴关系标记为解绑中；该状态必须持久化，并阻止所有入口发起新的 handoff。
|
||||
2. 调用上述 `close`；超时、网络失败时保持解绑中并重试，不删除本地绑定。
|
||||
3. 返回 `bound`：提示用户先到 4G 小程序解绑。此时 handoff 已被关闭，但原 4G 绑定继续有效，流量查询和充值仍按原权限工作。
|
||||
4. 用户完成 4G 解绑后，再调用 GET 或重试 `close`；只有 `canUnbind=true` 时才能删除伴伴绑定。
|
||||
5. 返回 `unknown`，或 HTTP 401/429/5xx：保留伴伴绑定，提示未确认或稍后重试。不能把异常兜底成 `unbound`。
|
||||
|
||||
并发结果：消费事务先获得关系锁并完成绑定时，`close` 等待后返回 `bound`；`close` 先获得锁时，正在途中的签发、消费请求等待后返回 `HANDOFF_RELATION_CLOSED`。`pendingHandoff` 是已提交凭证的快照；正在进行的消费由 `close` 的事务锁处理。
|
||||
|
||||
`closing` 是持续生效的关闭状态，本版本没有恢复/取消关闭接口。即使用户取消了伴伴解绑，也不会自动恢复此 ID 的 handoff 能力；已有 4G 绑定可以继续使用。只有伴伴真正建立新的绑定关系时才使用新的 `sourceBindingId`。
|
||||
|
||||
查询、关闭接口错误码：
|
||||
|
||||
| HTTP 状态 | `code` | 处理 |
|
||||
| --- | --- | --- |
|
||||
| 400 | `INVALID_REQUEST` | 路径 ID 为空/超长，或关闭请求缺少合法 `requestId` |
|
||||
| 401 | `HANDOFF_SERVICE_UNAUTHORIZED` | 缺失或错误的服务凭证 |
|
||||
| 429 | `RATE_LIMITED` | 同一关系查询和关闭合计超过每分钟 60 次；降低频率 |
|
||||
| 500 | `INTERNAL_ERROR` | 数据库、事务或其他内部失败；保留伴伴关系并重试/排查 |
|
||||
|
||||
## 13. 本次升级部署及验收
|
||||
|
||||
本次新增 Flyway `V13__add_handoff_binding_relations.sql`，启动时自动建表、关联凭证并回填可明确识别的历史绑定，不修改已有 V12 迁移文件。历史凭证能通过消费用户、SIM、消费请求号唯一关联原绑定时会回填；同用户复用旧绑定但请求号不同等无法确认的情况保留为 `unknown`，由后端核查。
|
||||
|
||||
发布时同步更新 JAR 与 `nginx/locations.conf`，让新增 `/traffic-4g/internal/v1/binding-relations/` 路径生效；在实际承载域名的 Nginx 进程/容器中检查配置并重载。只替换 JAR 不会使 Nginx 自动开放新路径。迁移期间停止旧后端实例写入，完成迁移后再由新实例提供 handoff 服务。
|
||||
|
||||
新增验收场景：
|
||||
|
||||
1. 不带或带错误 `X-Service-Token` 调用查询、关闭，均返回 HTTP 401。
|
||||
2. 查询未出现过的 `sourceBindingId`，返回 HTTP 200、`unknown`、`canUnbind=false`。
|
||||
3. 申请未消费凭证后，查询返回 `never_bound`、`pendingHandoff=true`、`canUnbind=false`。
|
||||
4. 同一关系申请多张凭证后关闭，全部不能再消费，返回 `never_bound`、`pendingHandoff=false`、`canUnbind=true`。
|
||||
5. 成功消费后关闭，返回 `bound`、`canUnbind=false`；用户或管理员完成 4G 解绑后，查询返回 `unbound`、`canUnbind=true`。
|
||||
6. 原绑定解绑后，同一 ICCID 被其他用户或原用户通过其他流程绑定，旧关系查询仍为 `unbound`；旧已消费凭证不能变成新绑定的重试凭证。
|
||||
7. 同一 `sourceBindingId` 使用不同 `requestId` 换 ICCID，返回 `IDEMPOTENCY_CONFLICT`。
|
||||
8. 并发执行关闭与签发/消费，结果只能是“先绑定成功，关闭返回 bound”或“关闭成功，后续关联失败”。
|
||||
9. 重复关闭结果保持关闭状态；没有历史的关系关闭后仍为 `unknown`。
|
||||
10. 历史不明确的数据保持 `unknown`，不得通过换申请请求号绕过。
|
||||
|
||||
自动化验证：普通单元和接口测试执行 `mvn test`；真实 MySQL 事务测试为 `HandoffBindingRelationIntegrationTest`，需要显式配置 `HANDOFF_TEST_JDBC_URL`、`HANDOFF_TEST_DB_PASSWORD`（可选 `HANDOFF_TEST_DB_USERNAME`，默认 root），指向全新的空测试库后执行 `mvn -Dtest=HandoffBindingRelationIntegrationTest test`。该测试只使用指定测试库，不读取生产 `.env`；数据库非空时会拒绝执行。
|
||||
@@ -108,7 +108,7 @@ class BindingDAO(BaseDAO):
|
||||
async def _bind_device(self, device_id: str, user_id: int, child_id: Optional[int]) -> None:
|
||||
existing_by_device = (
|
||||
await self.execute(
|
||||
"SELECT id, status FROM device_bindings WHERE device_id = :device_id",
|
||||
"SELECT id, status, owner_user_id, binding_instance_id FROM device_bindings WHERE device_id = :device_id FOR UPDATE",
|
||||
{"device_id": device_id},
|
||||
)
|
||||
).mappings().first()
|
||||
@@ -122,18 +122,20 @@ class BindingDAO(BaseDAO):
|
||||
child_id = NULL,
|
||||
status = 1,
|
||||
unbound_at = NULL,
|
||||
binding_instance_id = :binding_instance_id,
|
||||
updated_at = CURRENT_TIMESTAMP
|
||||
WHERE device_id = :device_id
|
||||
""",
|
||||
{"owner_user_id": user_id, "device_id": device_id},
|
||||
{"owner_user_id": user_id, "device_id": device_id,
|
||||
"binding_instance_id": self._binding_instance(existing_by_device, user_id)},
|
||||
)
|
||||
else:
|
||||
await self.execute(
|
||||
"""
|
||||
INSERT INTO device_bindings (device_id, owner_user_id, child_id, status, bound_at)
|
||||
VALUES (:device_id, :owner_user_id, NULL, 1, CURRENT_TIMESTAMP)
|
||||
INSERT INTO device_bindings (device_id, owner_user_id, child_id, status, bound_at, binding_instance_id)
|
||||
VALUES (:device_id, :owner_user_id, NULL, 1, CURRENT_TIMESTAMP, :binding_instance_id)
|
||||
""",
|
||||
{"device_id": device_id, "owner_user_id": user_id},
|
||||
{"device_id": device_id, "owner_user_id": user_id, "binding_instance_id": str(uuid.uuid4())},
|
||||
)
|
||||
return
|
||||
|
||||
@@ -156,10 +158,12 @@ class BindingDAO(BaseDAO):
|
||||
child_id = :child_id,
|
||||
status = 1,
|
||||
unbound_at = NULL,
|
||||
binding_instance_id = :binding_instance_id,
|
||||
updated_at = CURRENT_TIMESTAMP
|
||||
WHERE device_id = :device_id
|
||||
""",
|
||||
{"owner_user_id": user_id, "child_id": child_id, "device_id": device_id},
|
||||
{"owner_user_id": user_id, "child_id": child_id, "device_id": device_id,
|
||||
"binding_instance_id": self._binding_instance(existing_by_device, user_id)},
|
||||
)
|
||||
return
|
||||
|
||||
@@ -168,12 +172,18 @@ class BindingDAO(BaseDAO):
|
||||
|
||||
await self.execute(
|
||||
"""
|
||||
INSERT INTO device_bindings (device_id, owner_user_id, child_id, status, bound_at)
|
||||
VALUES (:device_id, :owner_user_id, :child_id, 1, CURRENT_TIMESTAMP)
|
||||
INSERT INTO device_bindings (device_id, owner_user_id, child_id, status, bound_at, binding_instance_id)
|
||||
VALUES (:device_id, :owner_user_id, :child_id, 1, CURRENT_TIMESTAMP, :binding_instance_id)
|
||||
""",
|
||||
{"device_id": device_id, "owner_user_id": user_id, "child_id": child_id},
|
||||
{"device_id": device_id, "owner_user_id": user_id, "child_id": child_id, "binding_instance_id": str(uuid.uuid4())},
|
||||
)
|
||||
|
||||
@staticmethod
|
||||
def _binding_instance(row, user_id):
|
||||
if int(row["status"]) == 1 and int(row["owner_user_id"]) == user_id and row.get("binding_instance_id"):
|
||||
return row["binding_instance_id"]
|
||||
return str(uuid.uuid4())
|
||||
|
||||
async def _ensure_owner_family_member(self, device_id: str, user_id: int) -> None:
|
||||
await self.execute(
|
||||
"""
|
||||
@@ -607,7 +617,7 @@ class BindingDAO(BaseDAO):
|
||||
await self.commit()
|
||||
return True
|
||||
|
||||
async def unbind(self, device_id: str, user_id: int) -> bool:
|
||||
async def unbind(self, device_id: str, user_id: int, *, commit: bool = True) -> bool:
|
||||
row = (
|
||||
await self.execute(
|
||||
"""
|
||||
@@ -667,7 +677,8 @@ class BindingDAO(BaseDAO):
|
||||
""",
|
||||
{"device_id": device_id, "user_id": user_id},
|
||||
)
|
||||
await self.commit()
|
||||
if commit:
|
||||
await self.commit()
|
||||
return True
|
||||
|
||||
async def list_history(self, device_id: str, limit: int = 20, cursor: datetime = None) -> list[Mapping]:
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
from fastapi import APIRouter
|
||||
|
||||
from banban.routers.bindings import router as bindings_router
|
||||
from banban.routers.joint_binding import router as joint_binding_router
|
||||
from banban.routers.children import router as children_router
|
||||
from banban.routers.device_im import router as device_im_router
|
||||
from banban.routers.device_location import router as device_location_router
|
||||
@@ -20,6 +21,7 @@ banban_router = APIRouter(prefix="/banban")
|
||||
banban_router.include_router(wechat_auth_router, tags=["banban-auth"])
|
||||
banban_router.include_router(wechat_mp_router, tags=["banban-wechat-mp"])
|
||||
banban_router.include_router(bindings_router, tags=["banban-bindings"])
|
||||
banban_router.include_router(joint_binding_router)
|
||||
banban_router.include_router(children_router, tags=["banban-children"])
|
||||
banban_router.include_router(devices_router, tags=["banban-devices"])
|
||||
banban_router.include_router(family_router, tags=["banban-family"])
|
||||
|
||||
@@ -375,8 +375,7 @@ async def unbind_device(
|
||||
current_user_id: int = Depends(get_current_user_id),
|
||||
) -> None:
|
||||
del request
|
||||
if not await binding_service.unbind(device_id, current_user_id):
|
||||
raise HTTPException(status_code=404, detail="binding not found")
|
||||
raise HTTPException(status_code=409, detail="请使用联合解绑流程，完成流量侧解绑后再解除设备绑定")
|
||||
|
||||
|
||||
@router.get("/history/{device_id}", response_model=BindHistoryResponse)
|
||||
|
||||
@@ -0,0 +1,74 @@
|
||||
import asyncio
|
||||
from typing import Literal
|
||||
from uuid import UUID
|
||||
|
||||
from fastapi import APIRouter, Depends, HTTPException
|
||||
from pydantic import BaseModel, Field, StrictBool
|
||||
|
||||
from banban.security import get_current_user_id
|
||||
from banban.service.joint_binding import joint_binding_service
|
||||
from banban.service.traffic_handoff import TrafficError
|
||||
|
||||
router = APIRouter(prefix="/joint-bindings", tags=["joint-bindings"])
|
||||
|
||||
|
||||
class StartRequest(BaseModel):
|
||||
device_id: str = Field(min_length=1, max_length=64)
|
||||
action: Literal["bind", "unbind"]
|
||||
|
||||
|
||||
class ResultRequest(BaseModel):
|
||||
action: Literal["bind", "unbind"]
|
||||
request_id: str = Field(min_length=1, max_length=64)
|
||||
success: StrictBool
|
||||
code: str = Field(min_length=1, max_length=64, pattern=r"^[A-Za-z0-9_]+$")
|
||||
iccid: str | None = Field(default=None, max_length=22)
|
||||
|
||||
|
||||
async def call(coro):
|
||||
try:
|
||||
return await asyncio.wait_for(coro, timeout=8)
|
||||
except asyncio.TimeoutError:
|
||||
raise HTTPException(503, detail={"code": "OPERATION_TIMEOUT", "message": "操作暂时无法确认，请重试"}) from None
|
||||
except TrafficError as exc:
|
||||
raise HTTPException(exc.status_code, detail={"code": exc.code, "message": str(exc)}) from None
|
||||
|
||||
|
||||
@router.post("")
|
||||
async def start(payload: StartRequest, user: int = Depends(get_current_user_id)):
|
||||
return await call(joint_binding_service.start(payload.device_id, user, payload.action))
|
||||
|
||||
|
||||
@router.get("/devices/{device_id}")
|
||||
async def overview(device_id: str, user: int = Depends(get_current_user_id)):
|
||||
return await call(joint_binding_service.overview(device_id, user))
|
||||
|
||||
|
||||
@router.get("/devices/{device_id}/portal")
|
||||
async def portal(device_id: str, user: int = Depends(get_current_user_id)):
|
||||
return await call(joint_binding_service.portal(device_id, user))
|
||||
|
||||
|
||||
@router.get("/{operation_id}")
|
||||
async def get(operation_id: UUID, user: int = Depends(get_current_user_id)):
|
||||
return await call(joint_binding_service.get(str(operation_id), user))
|
||||
|
||||
|
||||
@router.post("/{operation_id}/prepare")
|
||||
async def prepare(operation_id: UUID, user: int = Depends(get_current_user_id)):
|
||||
return await call(joint_binding_service.prepare(str(operation_id), user))
|
||||
|
||||
|
||||
@router.post("/{operation_id}/check")
|
||||
async def check(operation_id: UUID, user: int = Depends(get_current_user_id)):
|
||||
return await call(joint_binding_service.check(str(operation_id), user))
|
||||
|
||||
|
||||
@router.post("/{operation_id}/result")
|
||||
async def report(operation_id: UUID, payload: ResultRequest, user: int = Depends(get_current_user_id)):
|
||||
return await call(joint_binding_service.report(str(operation_id), user, **payload.model_dump()))
|
||||
|
||||
|
||||
@router.post("/{operation_id}/finish-unbind")
|
||||
async def finish_unbind(operation_id: UUID, user: int = Depends(get_current_user_id)):
|
||||
return await call(joint_binding_service.finish_unbind(str(operation_id), user))
|
||||
@@ -0,0 +1,297 @@
|
||||
"""Durable orchestration for the two mini-programs.
|
||||
|
||||
Only server_confirmed represents the 4G relation service's decision.
|
||||
Client receipts never authorize local unbinding.
|
||||
"""
|
||||
from uuid import uuid4
|
||||
|
||||
from sqlalchemy import text
|
||||
|
||||
from banban.dao.binding import BindingDAO
|
||||
from banban.service.traffic_handoff import TrafficError, binding_relation, create_handoff, normalize_iccid
|
||||
from config import settings
|
||||
from services.database_service_base import DatabaseServiceBase
|
||||
|
||||
|
||||
class JointBindingService(DatabaseServiceBase):
|
||||
async def overview(self, device_id, user_id):
|
||||
db = await self.get_session()
|
||||
try:
|
||||
binding = await self._binding(db, device_id, user_id)
|
||||
if int(binding["status"]) != 1:
|
||||
raise TrafficError("NOT_BOUND", "设备当前未绑定")
|
||||
rows = (await db.execute(text("SELECT * FROM device_binding_operations WHERE binding_instance_id=:instance"),
|
||||
{"instance": binding["binding_instance_id"]})).mappings().all()
|
||||
operations = {r["action"]: self.public(r) for r in rows}
|
||||
return {"device_id": device_id, "binding_instance_id": binding["binding_instance_id"],
|
||||
"bind": operations.get("bind"), "unbind": operations.get("unbind")}
|
||||
finally:
|
||||
await db.close()
|
||||
|
||||
async def portal(self, device_id, user_id):
|
||||
overview = await self.overview(device_id, user_id)
|
||||
if overview["bind"] and not overview["unbind"]:
|
||||
await self.check(overview["bind"]["operation_id"], user_id)
|
||||
db = await self.get_session()
|
||||
try:
|
||||
binding = await self._binding(db, device_id, user_id)
|
||||
rows = (await db.execute(text("SELECT * FROM device_binding_operations WHERE binding_instance_id=:instance"),
|
||||
{"instance": binding["binding_instance_id"]})).mappings().all()
|
||||
operations = {r["action"]: r for r in rows}
|
||||
linked = operations.get("bind")
|
||||
if (int(binding["status"]) != 1 or "unbind" in operations or not linked
|
||||
or linked["status"] != "completed" or linked["traffic_status"] != "server_confirmed"):
|
||||
raise TrafficError("TRAFFIC_BIND_REQUIRED", "请先完成流量服务关联")
|
||||
return {"target_app_id": settings.traffic_4g_target_app_id, "iccid": linked["iccid"],
|
||||
"source_binding_id": f"banban:{binding['binding_instance_id']}"}
|
||||
finally:
|
||||
await db.close()
|
||||
|
||||
async def record_iccid(self, device_id: str, value) -> None:
|
||||
iccid = normalize_iccid(value)
|
||||
if iccid is None:
|
||||
raise TrafficError("ICCID_INVALID", "设备尚未上报有效流量卡信息")
|
||||
db = await self.get_session()
|
||||
try:
|
||||
# Do not silently replace a SIM participating in a binding operation.
|
||||
current = (await db.execute(text("SELECT iccid FROM device_settings WHERE device_id=:device_id FOR UPDATE"),
|
||||
{"device_id": device_id})).mappings().first()
|
||||
if current and current["iccid"] and current["iccid"] != iccid:
|
||||
raise TrafficError("ICCID_CONFLICT", "设备流量卡信息发生变化，需要核实")
|
||||
if current:
|
||||
await db.execute(text("UPDATE device_settings SET iccid=:iccid WHERE device_id=:device_id"),
|
||||
{"device_id": device_id, "iccid": iccid})
|
||||
else:
|
||||
await db.execute(text("INSERT INTO device_settings (device_id, iccid) VALUES (:device_id, :iccid)"),
|
||||
{"device_id": device_id, "iccid": iccid})
|
||||
await db.commit()
|
||||
finally:
|
||||
await db.close()
|
||||
|
||||
async def _binding(self, db, device_id, user_id):
|
||||
row = (await db.execute(text("SELECT * FROM device_bindings WHERE device_id=:device_id FOR UPDATE"),
|
||||
{"device_id": device_id})).mappings().first()
|
||||
if not row or int(row["owner_user_id"]) != user_id:
|
||||
raise TrafficError("NOT_DEVICE_OWNER", "仅设备归属账号可操作", 403)
|
||||
return row
|
||||
|
||||
def _check_current(self, binding, operation):
|
||||
if (binding["binding_instance_id"] != operation["binding_instance_id"]
|
||||
or (int(binding["status"]) != 1 and not (operation["action"] == "unbind" and operation["status"] == "completed"))):
|
||||
raise TrafficError("STALE_OPERATION", "设备绑定关系已变化，请重新进入")
|
||||
|
||||
async def _operation(self, db, operation_id, user_id):
|
||||
# Consistent lock order: binding first, operation second.
|
||||
row = (await db.execute(text("SELECT * FROM device_binding_operations WHERE operation_id=:id AND owner_user_id=:user"),
|
||||
{"id": operation_id, "user": user_id})).mappings().first()
|
||||
if not row:
|
||||
raise TrafficError("OPERATION_NOT_FOUND", "未找到该操作", 404)
|
||||
binding = await self._binding(db, row["device_id"], user_id)
|
||||
row = (await db.execute(text("SELECT * FROM device_binding_operations WHERE operation_id=:id FOR UPDATE"),
|
||||
{"id": operation_id})).mappings().one()
|
||||
self._check_current(binding, row)
|
||||
return dict(row)
|
||||
|
||||
@staticmethod
|
||||
def public(row):
|
||||
return {key: row[key] for key in ("operation_id", "device_id", "action", "status", "traffic_status", "last_error")}
|
||||
|
||||
async def start(self, device_id, user_id, action):
|
||||
if action not in {"bind", "unbind"}:
|
||||
raise TrafficError("INVALID_ACTION", "操作类型无效", 400)
|
||||
db = await self.get_session()
|
||||
try:
|
||||
binding = await self._binding(db, device_id, user_id)
|
||||
if int(binding["status"]) != 1:
|
||||
raise TrafficError("NOT_BOUND", "设备当前未绑定")
|
||||
instance = binding["binding_instance_id"]
|
||||
other = (await db.execute(text("SELECT * FROM device_binding_operations WHERE binding_instance_id=:instance AND action='unbind'"),
|
||||
{"instance": instance})).mappings().first()
|
||||
if action == "bind" and other:
|
||||
raise TrafficError("UNBIND_PENDING", "设备正在解绑，请先完成解绑")
|
||||
row = (await db.execute(text("SELECT * FROM device_binding_operations WHERE binding_instance_id=:instance AND action=:action"),
|
||||
{"instance": instance, "action": action})).mappings().first()
|
||||
if row is None:
|
||||
row = {"operation_id": str(uuid4()), "binding_instance_id": instance,
|
||||
"device_id": device_id, "owner_user_id": user_id, "action": action,
|
||||
"traffic_status": "pending", "status": "pending", "last_error": None}
|
||||
await db.execute(text("""INSERT INTO device_binding_operations
|
||||
(operation_id, binding_instance_id, device_id, owner_user_id, action)
|
||||
VALUES (:operation_id, :binding_instance_id, :device_id, :owner_user_id, :action)"""), row)
|
||||
await db.commit()
|
||||
return self.public(row)
|
||||
finally:
|
||||
await db.close()
|
||||
|
||||
async def get(self, operation_id, user_id):
|
||||
db = await self.get_session()
|
||||
try:
|
||||
return self.public(await self._operation(db, operation_id, user_id))
|
||||
finally:
|
||||
await db.close()
|
||||
|
||||
async def check(self, operation_id, user_id, *, close=False):
|
||||
db = await self.get_session()
|
||||
try:
|
||||
row = await self._operation(db, operation_id, user_id)
|
||||
if row["action"] == "unbind" and row["status"] == "completed":
|
||||
return self.public(row)
|
||||
if close and row["action"] != "unbind":
|
||||
raise TrafficError("INVALID_ACTION", "仅解绑操作可关闭流量关联")
|
||||
finally:
|
||||
await db.close()
|
||||
relation = await binding_relation(f"banban:{row['binding_instance_id']}",
|
||||
f"bb-{'close' if close else 'query'}-{operation_id}", close=close)
|
||||
db = await self.get_session()
|
||||
try:
|
||||
# Revalidate after the network call; an old result cannot affect a rebind.
|
||||
row = await self._operation(db, operation_id, user_id)
|
||||
if row["status"] == "completed" and row["action"] == "unbind":
|
||||
return self.public(row)
|
||||
if row["action"] == "bind":
|
||||
other = (await db.execute(text("SELECT operation_id FROM device_binding_operations WHERE binding_instance_id=:instance AND action='unbind'"),
|
||||
{"instance": row["binding_instance_id"]})).first()
|
||||
if other:
|
||||
raise TrafficError("UNBIND_PENDING", "设备正在解绑，请先完成解绑")
|
||||
confirmed = relation["status"] == "bound" and relation["relationState"] == "open"
|
||||
if confirmed and not row["iccid"]:
|
||||
setting = (await db.execute(text("SELECT iccid FROM device_settings WHERE device_id=:device_id"),
|
||||
{"device_id": row["device_id"]})).mappings().first()
|
||||
row["iccid"] = normalize_iccid(setting["iccid"] if setting else None)
|
||||
if not row["iccid"]:
|
||||
raise TrafficError("ICCID_NOT_AVAILABLE", "设备尚未上报流量卡信息，请设备联网后重试")
|
||||
else:
|
||||
confirmed = relation["canUnbind"]
|
||||
error = None if confirmed else (
|
||||
"HANDOFF_RELATION_UNKNOWN" if relation["status"] == "unknown" else
|
||||
"TRAFFIC_UNBIND_REQUIRED" if row["action"] == "unbind" and relation["status"] == "bound" else
|
||||
"HANDOFF_RELATION_CLOSED" if row["action"] == "bind" and relation["relationState"] == "closing" else
|
||||
"TRAFFIC_RESULT_UNCONFIRMED")
|
||||
row.update(traffic_status="server_confirmed" if confirmed else "pending",
|
||||
status="completed" if confirmed and row["action"] == "bind" else "pending",
|
||||
last_error=error)
|
||||
await db.execute(text("UPDATE device_binding_operations SET iccid=:iccid,traffic_status=:traffic_status,status=:status,last_error=:last_error WHERE operation_id=:operation_id"), row)
|
||||
await db.commit()
|
||||
return self.public(row)
|
||||
finally:
|
||||
await db.close()
|
||||
|
||||
async def prepare(self, operation_id, user_id):
|
||||
initial = await self.get(operation_id, user_id)
|
||||
if initial["action"] == "unbind":
|
||||
checked = await self.check(operation_id, user_id, close=True)
|
||||
if checked["status"] == "completed" or checked["traffic_status"] == "server_confirmed":
|
||||
return {"operation": checked}
|
||||
if checked["last_error"] != "TRAFFIC_UNBIND_REQUIRED":
|
||||
raise TrafficError(checked["last_error"] or "TRAFFIC_RESULT_UNCONFIRMED",
|
||||
"流量关系尚未确认，伴伴绑定保留；请重试或联系服务人员")
|
||||
elif initial["status"] == "completed":
|
||||
checked = await self.check(operation_id, user_id)
|
||||
if checked["status"] == "completed":
|
||||
return {"operation": checked}
|
||||
db = await self.get_session()
|
||||
try:
|
||||
row = await self._operation(db, operation_id, user_id)
|
||||
if row["action"] == "bind":
|
||||
unbinding = (await db.execute(text("SELECT operation_id FROM device_binding_operations WHERE binding_instance_id=:instance AND action='unbind'"),
|
||||
{"instance": row["binding_instance_id"]})).first()
|
||||
if unbinding:
|
||||
raise TrafficError("UNBIND_PENDING", "设备正在解绑，请先完成解绑")
|
||||
if row["status"] == "completed" or row["traffic_status"] == "server_confirmed":
|
||||
return {"operation": self.public(row)}
|
||||
setting = (await db.execute(text("SELECT iccid FROM device_settings WHERE device_id=:device_id"),
|
||||
{"device_id": row["device_id"]})).mappings().first()
|
||||
iccid = normalize_iccid(setting["iccid"] if setting else None)
|
||||
if not iccid:
|
||||
raise TrafficError("ICCID_NOT_AVAILABLE", "设备尚未上报流量卡信息，请设备联网后重试")
|
||||
if row["iccid"] and row["iccid"] != iccid:
|
||||
raise TrafficError("ICCID_CONFLICT", "设备流量卡信息发生变化，需要核实")
|
||||
await db.execute(text("UPDATE device_binding_operations SET iccid=:iccid, handoff_started=1 WHERE operation_id=:id"),
|
||||
{"id": operation_id, "iccid": iccid})
|
||||
await db.commit()
|
||||
finally:
|
||||
await db.close()
|
||||
# Never hold a DB transaction across a network call or mini-program jump.
|
||||
result = {"operation": self.public(row), "target_app_id": settings.traffic_4g_target_app_id,
|
||||
"request_id": f"joint-{operation_id}", "handoff_token": None,
|
||||
"source_binding_id": f"banban:{row['binding_instance_id']}"}
|
||||
if row["action"] == "unbind":
|
||||
# ICCID identifies the resource; only the 4G user's JWT authorizes unbind.
|
||||
result["iccid"] = iccid
|
||||
return result
|
||||
request_id = f"bb-{operation_id}-{row['handoff_attempt']}"
|
||||
try:
|
||||
data = await create_handoff(iccid, result["source_binding_id"], request_id)
|
||||
except TrafficError as exc:
|
||||
if exc.code == "HANDOFF_TOKEN_USED":
|
||||
checked = await self.check(operation_id, user_id)
|
||||
if checked["status"] == "completed":
|
||||
return {"operation": checked}
|
||||
raise TrafficError(checked["last_error"] or "TRAFFIC_RESULT_UNCONFIRMED",
|
||||
"原流量绑定结果尚未确认，请重试或联系服务人员") from None
|
||||
if exc.code == "HANDOFF_TOKEN_EXPIRED":
|
||||
db = await self.get_session()
|
||||
try:
|
||||
await self._operation(db, operation_id, user_id)
|
||||
await db.execute(text("""UPDATE device_binding_operations
|
||||
SET handoff_attempt=handoff_attempt+1 WHERE operation_id=:id AND handoff_attempt=:attempt"""),
|
||||
{"id": operation_id, "attempt": row["handoff_attempt"]})
|
||||
await db.commit()
|
||||
finally:
|
||||
await db.close()
|
||||
raise TrafficError(exc.code, "交接凭证已过期，请点击继续重新申请") from None
|
||||
raise
|
||||
result.update(handoff_token=data["handoffToken"], expires_in=data["expiresIn"])
|
||||
return result
|
||||
|
||||
async def report(self, operation_id, user_id, action, request_id, iccid, code, success):
|
||||
db = await self.get_session()
|
||||
try:
|
||||
row = await self._operation(db, operation_id, user_id)
|
||||
if row["action"] != action or request_id != f"joint-{operation_id}":
|
||||
raise TrafficError("RESULT_MISMATCH", "返回结果与当前操作不匹配")
|
||||
if row["status"] == "completed" or row["traffic_status"] == "server_confirmed":
|
||||
return self.public(row)
|
||||
if success:
|
||||
if code != "OK" or not row["iccid"] or normalize_iccid(iccid) != row["iccid"]:
|
||||
raise TrafficError("RESULT_MISMATCH", "返回设备与当前操作不匹配")
|
||||
row.update(traffic_status="client_confirmed", status="pending", last_error=None)
|
||||
else:
|
||||
row.update(status="partial_failed", last_error=code)
|
||||
await db.execute(text("""UPDATE device_binding_operations SET traffic_status=:traffic_status,
|
||||
status=:status, last_error=:last_error WHERE operation_id=:operation_id"""), row)
|
||||
await db.commit()
|
||||
finally:
|
||||
await db.close()
|
||||
# Even a success receipt must be checked against the original server relation.
|
||||
return await self.check(operation_id, user_id) if success else self.public(row)
|
||||
|
||||
async def finish_unbind(self, operation_id, user_id):
|
||||
initial = await self.get(operation_id, user_id)
|
||||
if initial["action"] != "unbind":
|
||||
raise TrafficError("INVALID_ACTION", "仅解绑操作可完成解绑")
|
||||
if initial["status"] == "completed":
|
||||
return initial
|
||||
checked = await self.check(operation_id, user_id, close=True)
|
||||
if checked["traffic_status"] != "server_confirmed":
|
||||
raise TrafficError(checked["last_error"] or "TRAFFIC_UNBIND_REQUIRED",
|
||||
"流量侧尚未确认可解绑，伴伴绑定保留")
|
||||
db = await self.get_session()
|
||||
try:
|
||||
row = await self._operation(db, operation_id, user_id)
|
||||
if row["action"] != "unbind" or row["traffic_status"] != "server_confirmed":
|
||||
raise TrafficError("TRAFFIC_UNBIND_REQUIRED", "请先完成流量管理侧解绑")
|
||||
if row["status"] == "completed":
|
||||
return self.public(row)
|
||||
if not await BindingDAO(db).unbind(row["device_id"], user_id, commit=False):
|
||||
raise TrafficError("NOT_BOUND", "设备绑定关系已变化")
|
||||
await db.execute(text("UPDATE device_binding_operations SET status='completed', last_error=NULL WHERE operation_id=:id"),
|
||||
{"id": operation_id})
|
||||
await db.commit()
|
||||
row.update(status="completed", last_error=None)
|
||||
return self.public(row)
|
||||
finally:
|
||||
await db.close()
|
||||
|
||||
|
||||
joint_binding_service = JointBindingService("joint_binding")
|
||||
@@ -0,0 +1,89 @@
|
||||
"""4G contract adapter. No user JWT or remote response body is logged."""
|
||||
import re
|
||||
from datetime import datetime
|
||||
from urllib.parse import quote
|
||||
|
||||
import httpx
|
||||
|
||||
from config import settings
|
||||
|
||||
|
||||
class TrafficError(ValueError):
|
||||
def __init__(self, code: str, message: str, status_code: int = 409):
|
||||
super().__init__(message)
|
||||
self.code = code
|
||||
self.status_code = status_code
|
||||
|
||||
|
||||
def normalize_iccid(value) -> str | None:
|
||||
if not isinstance(value, str):
|
||||
return None
|
||||
value = value.strip().upper()
|
||||
return value if re.fullmatch(r"[A-Z0-9]{18,22}", value) else None
|
||||
|
||||
|
||||
async def _request(method: str, path: str, request_id: str, payload=None) -> dict:
|
||||
base = settings.traffic_4g_api_base_url.rstrip("/")
|
||||
if not base.startswith("https://") or not settings.banban_handoff_service_token:
|
||||
raise TrafficError("CONFIGURATION_ERROR", "流量服务尚未配置，请稍后继续绑定", 503)
|
||||
try:
|
||||
async with httpx.AsyncClient(timeout=settings.traffic_4g_timeout_seconds) as client:
|
||||
response = await client.request(
|
||||
method, base + path,
|
||||
headers={"X-Service-Token": settings.banban_handoff_service_token,
|
||||
"X-Request-Id": request_id, "Cache-Control": "no-cache"},
|
||||
**({"json": payload} if payload is not None else {}),
|
||||
)
|
||||
body = response.json()
|
||||
except (httpx.HTTPError, ValueError):
|
||||
raise TrafficError("TRAFFIC_UNAVAILABLE", "流量服务暂时无法确认结果，请重试", 503) from None
|
||||
if not isinstance(body, dict):
|
||||
raise TrafficError("INVALID_RESPONSE", "流量服务返回异常，请重试", 502)
|
||||
if response.status_code != 200 or body.get("code") != "OK":
|
||||
code = str(body.get("code") or "TRAFFIC_UNAVAILABLE")
|
||||
allowed = {"HANDOFF_TOKEN_USED", "HANDOFF_TOKEN_EXPIRED", "DEVICE_DISABLED",
|
||||
"IDEMPOTENCY_CONFLICT", "HANDOFF_DISABLED", "RATE_LIMITED",
|
||||
"HANDOFF_SERVICE_UNAUTHORIZED", "INVALID_REQUEST", "CONFIGURATION_ERROR",
|
||||
"HANDOFF_RELATION_CLOSED", "HANDOFF_RELATION_UNKNOWN"}
|
||||
raise TrafficError(code if code in allowed else "TRAFFIC_UNAVAILABLE",
|
||||
"流量绑定尚未完成，请重试或联系服务人员", 503 if response.status_code >= 500 else 409)
|
||||
data = body.get("data")
|
||||
if not isinstance(data, dict):
|
||||
raise TrafficError("INVALID_RESPONSE", "流量服务返回异常，请重试", 502)
|
||||
return data
|
||||
|
||||
|
||||
async def create_handoff(iccid: str, source_binding_id: str, request_id: str) -> dict:
|
||||
data = await _request("POST", "/internal/v1/handoff-tokens", request_id,
|
||||
{"iccid": iccid, "sourceBindingId": source_binding_id, "requestId": request_id})
|
||||
if (not isinstance(data, dict) or data.get("targetAppId") != settings.traffic_4g_target_app_id
|
||||
or not isinstance(data.get("handoffToken"), str) or not 1 <= len(data["handoffToken"]) <= 256
|
||||
or type(data.get("expiresIn")) is not int or data["expiresIn"] <= 0):
|
||||
raise TrafficError("INVALID_RESPONSE", "流量服务返回异常，请重试", 502)
|
||||
return data
|
||||
|
||||
|
||||
async def binding_relation(source_binding_id: str, request_id: str, *, close=False) -> dict:
|
||||
path = "/internal/v1/binding-relations/" + quote(source_binding_id, safe="")
|
||||
data = await _request("POST" if close else "GET", path + ("/close" if close else ""),
|
||||
request_id, {"requestId": request_id} if close else None)
|
||||
valid = (data.get("sourceBindingId") == source_binding_id
|
||||
and isinstance(data.get("status"), str) and data["status"] in {"bound", "unbound", "never_bound", "unknown"}
|
||||
and isinstance(data.get("relationState"), str) and data["relationState"] in {"open", "closing", "unknown"}
|
||||
and all(type(data.get(key)) is bool for key in ("pendingHandoff", "acceptingHandoff", "canUnbind")))
|
||||
expected = (data.get("relationState") == "closing" and data.get("pendingHandoff") is False
|
||||
and data.get("acceptingHandoff") is False and data.get("status") in ("unbound", "never_bound"))
|
||||
valid = valid and data.get("canUnbind") == expected
|
||||
if data.get("relationState") == "closing":
|
||||
valid = valid and not data.get("pendingHandoff") and not data.get("acceptingHandoff")
|
||||
if data.get("relationState") == "unknown":
|
||||
valid = valid and data.get("status") == "unknown" and not data.get("acceptingHandoff")
|
||||
try:
|
||||
checked = data.get("checkedAt")
|
||||
valid = valid and isinstance(checked, str) and checked.endswith("Z")
|
||||
datetime.fromisoformat(checked.replace("Z", "+00:00"))
|
||||
except (AttributeError, TypeError, ValueError):
|
||||
valid = False
|
||||
if not valid:
|
||||
raise TrafficError("INVALID_RESPONSE", "流量关系返回不完整或不一致，请重试", 502)
|
||||
return data
|
||||
@@ -24,6 +24,11 @@ class Settings(BaseSettings):
|
||||
server_host: str = Field(default="0.0.0.0", validation_alias="SERVER_HOST")
|
||||
server_port: int = Field(default=8080, validation_alias="SERVER_PORT")
|
||||
|
||||
traffic_4g_api_base_url: str = Field(default="https://role.api.talkingq.com/traffic-4g", validation_alias="TRAFFIC_4G_API_BASE_URL")
|
||||
banban_handoff_service_token: str = Field(default="", validation_alias="BANBAN_HANDOFF_SERVICE_TOKEN")
|
||||
traffic_4g_target_app_id: str = Field(default="wx56e1cfc52aab630f", validation_alias="TRAFFIC_4G_TARGET_APP_ID")
|
||||
traffic_4g_timeout_seconds: float = Field(default=6.0, gt=0, le=15, validation_alias="TRAFFIC_4G_TIMEOUT_SECONDS")
|
||||
|
||||
asr_provider: str = Field(default="Aliyun", validation_alias="ASR_PROVIDER")
|
||||
llm_provider: str = Field(default="Volcano", validation_alias="LLM_PROVIDER")
|
||||
tts_provider: str = Field(default="MiniMax", validation_alias="TTS_PROVIDER")
|
||||
|
||||
@@ -399,8 +399,24 @@ class TalkingQMQTTService:
|
||||
params = payload
|
||||
status = params.get("status")
|
||||
logger.info(device_id, "", f"[NFC绑定] 设备 {device_id} 请求绑定卡片返回状态: {status}")
|
||||
data = params.get("data", {})
|
||||
if status != "success":
|
||||
return
|
||||
data = params.get("data")
|
||||
if not isinstance(data, dict) or not isinstance(data.get("uuid"), str) or not data["uuid"].strip():
|
||||
logger.warning(device_id, "", "[NFC bind] invalid card response")
|
||||
return
|
||||
nfc_uuid = data.get("uuid")
|
||||
from banban.service.traffic_handoff import normalize_iccid
|
||||
logger.info(device_id, "", f"[NFC bind] 006 ICCID present={'iccid' in data}, valid={normalize_iccid(data.get('iccid')) is not None}")
|
||||
if data.get("iccid") is not None:
|
||||
from banban.service.joint_binding import joint_binding_service
|
||||
try:
|
||||
await asyncio.wait_for(joint_binding_service.record_iccid(device_id, data["iccid"]), timeout=2)
|
||||
logger.info(device_id, "", "[NFC bind] 006 ICCID persisted")
|
||||
except Exception:
|
||||
# A SIM persistence failure must not lose the NFC receipt. The
|
||||
# combined operation remains pending until ICCID is available.
|
||||
logger.warning(device_id, "", "[NFC bind] ICCID persistence failed; traffic binding pending")
|
||||
# 卡片与设备绑定
|
||||
# await card_service.activate_card(device_id=device_id, card_uuid=nfc_uuid)
|
||||
result = await binding_service.finalize_nfc_bind(device_id=device_id, card_uuid=nfc_uuid)
|
||||
|
||||
@@ -312,6 +312,7 @@ CREATE TABLE IF NOT EXISTS `device_bindings` (
|
||||
`id` BIGINT NOT NULL AUTO_INCREMENT,
|
||||
`device_id` VARCHAR(64) NOT NULL,
|
||||
`owner_user_id` BIGINT NOT NULL,
|
||||
`binding_instance_id` CHAR(36) NULL,
|
||||
`child_id` BIGINT NULL,
|
||||
`status` TINYINT NOT NULL DEFAULT 1,
|
||||
`bound_at` DATETIME NOT NULL,
|
||||
@@ -320,6 +321,7 @@ CREATE TABLE IF NOT EXISTS `device_bindings` (
|
||||
`updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||||
PRIMARY KEY (`id`),
|
||||
CONSTRAINT `uq_device_binding_device` UNIQUE (`device_id`),
|
||||
UNIQUE KEY `uk_binding_instance` (`binding_instance_id`),
|
||||
CONSTRAINT `uq_device_binding_child` UNIQUE (`child_id`),
|
||||
KEY `idx_device_bindings_owner_user_id` (`owner_user_id`),
|
||||
CONSTRAINT `fk_device_bindings_device`
|
||||
@@ -498,6 +500,7 @@ CREATE TABLE IF NOT EXISTS `device_settings` (
|
||||
`signal` TINYINT UNSIGNED NULL,
|
||||
`version` VARCHAR(64) NULL,
|
||||
`imei` VARCHAR(64) NULL,
|
||||
`iccid` VARCHAR(22) NULL,
|
||||
`device_type` TINYINT NULL,
|
||||
`ota_channel` VARCHAR(32) NULL,
|
||||
`disable_weekdays` VARCHAR(32) NULL,
|
||||
@@ -505,6 +508,7 @@ CREATE TABLE IF NOT EXISTS `device_settings` (
|
||||
`updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||||
PRIMARY KEY (`setting_id`),
|
||||
UNIQUE KEY `uq_device_settings_device_id` (`device_id`),
|
||||
UNIQUE KEY `uk_device_settings_iccid` (`iccid`),
|
||||
CONSTRAINT `fk_device_settings_device`
|
||||
FOREIGN KEY (`device_id`)
|
||||
REFERENCES `device_auth` (`device_id`)
|
||||
|
||||
@@ -0,0 +1,17 @@
|
||||
CREATE TABLE IF NOT EXISTS device_binding_operations (
|
||||
operation_id CHAR(36) NOT NULL PRIMARY KEY,
|
||||
binding_instance_id CHAR(36) NOT NULL,
|
||||
device_id VARCHAR(64) NOT NULL,
|
||||
owner_user_id BIGINT NOT NULL,
|
||||
action VARCHAR(8) NOT NULL,
|
||||
iccid VARCHAR(22) NULL,
|
||||
traffic_status VARCHAR(24) NOT NULL DEFAULT 'pending',
|
||||
status VARCHAR(24) NOT NULL DEFAULT 'pending',
|
||||
handoff_attempt INT NOT NULL DEFAULT 0,
|
||||
handoff_started TINYINT NOT NULL DEFAULT 0,
|
||||
last_error VARCHAR(64) NULL,
|
||||
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||||
UNIQUE KEY uk_binding_operation (binding_instance_id, action),
|
||||
KEY idx_binding_operation_owner (owner_user_id, device_id)
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
|
||||
@@ -0,0 +1,24 @@
|
||||
-- Run once on an existing database before deploying the application.
|
||||
ALTER TABLE device_settings ADD COLUMN iccid VARCHAR(22) NULL,
|
||||
ADD UNIQUE KEY uk_device_settings_iccid (iccid);
|
||||
ALTER TABLE device_bindings ADD COLUMN binding_instance_id CHAR(36) NULL;
|
||||
UPDATE device_bindings SET binding_instance_id = UUID() WHERE binding_instance_id IS NULL;
|
||||
ALTER TABLE device_bindings ADD UNIQUE KEY uk_binding_instance (binding_instance_id);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS device_binding_operations (
|
||||
operation_id CHAR(36) NOT NULL PRIMARY KEY,
|
||||
binding_instance_id CHAR(36) NOT NULL,
|
||||
device_id VARCHAR(64) NOT NULL,
|
||||
owner_user_id BIGINT NOT NULL,
|
||||
action VARCHAR(8) NOT NULL,
|
||||
iccid VARCHAR(22) NULL,
|
||||
traffic_status VARCHAR(24) NOT NULL DEFAULT 'pending',
|
||||
status VARCHAR(24) NOT NULL DEFAULT 'pending',
|
||||
handoff_attempt INT NOT NULL DEFAULT 0,
|
||||
handoff_started TINYINT NOT NULL DEFAULT 0,
|
||||
last_error VARCHAR(64) NULL,
|
||||
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||||
UNIQUE KEY uk_binding_operation (binding_instance_id, action),
|
||||
KEY idx_binding_operation_owner (owner_user_id, device_id)
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
|
||||
@@ -0,0 +1,347 @@
|
||||
"""Local SQL/state-machine checks; SQLite does not validate MySQL row locks."""
|
||||
import asyncio
|
||||
import sqlite3
|
||||
from uuid import uuid4
|
||||
|
||||
import httpx
|
||||
import pytest
|
||||
|
||||
from banban.dao.binding import BindingDAO
|
||||
from banban.service.joint_binding import JointBindingService
|
||||
from banban.service.traffic_handoff import TrafficError, normalize_iccid
|
||||
from banban.service import traffic_handoff
|
||||
|
||||
DEVICE = "TalkingQ_test_joint"
|
||||
ICCID = "898604E91123D1334901"
|
||||
|
||||
|
||||
class Result:
|
||||
def __init__(self, cursor):
|
||||
self.rows = [dict(row) for row in cursor.fetchall()] if cursor.description else []
|
||||
def mappings(self): return self
|
||||
def first(self): return self.rows[0] if self.rows else None
|
||||
def one(self):
|
||||
assert len(self.rows) == 1
|
||||
return self.rows[0]
|
||||
def all(self): return self.rows
|
||||
|
||||
|
||||
class Session:
|
||||
def __init__(self, connection): self.connection = connection
|
||||
async def execute(self, statement, params=None):
|
||||
return Result(self.connection.execute(str(statement).replace(" FOR UPDATE", ""), params or {}))
|
||||
async def commit(self): self.connection.commit()
|
||||
async def rollback(self): self.connection.rollback()
|
||||
async def close(self): self.connection.rollback()
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def state(monkeypatch):
|
||||
conn = sqlite3.connect(":memory:")
|
||||
conn.row_factory = sqlite3.Row
|
||||
conn.executescript("""
|
||||
CREATE TABLE device_bindings (id INTEGER PRIMARY KEY, device_id TEXT UNIQUE, owner_user_id INTEGER,
|
||||
child_id INTEGER, status INTEGER, binding_instance_id TEXT, unbound_at TEXT, updated_at TEXT);
|
||||
CREATE TABLE device_settings (device_id TEXT PRIMARY KEY, iccid TEXT UNIQUE);
|
||||
CREATE TABLE device_binding_operations (operation_id TEXT PRIMARY KEY, binding_instance_id TEXT,
|
||||
device_id TEXT, owner_user_id INTEGER, action TEXT, iccid TEXT,
|
||||
traffic_status TEXT DEFAULT 'pending', status TEXT DEFAULT 'pending',
|
||||
handoff_attempt INTEGER DEFAULT 0, handoff_started INTEGER DEFAULT 0, last_error TEXT,
|
||||
UNIQUE(binding_instance_id, action));
|
||||
CREATE TABLE device_family_members (device_id TEXT, status INTEGER, removed_at TEXT, updated_at TEXT);
|
||||
CREATE TABLE device_bind_history (device_id TEXT, child_id INTEGER, bound_by_user_id INTEGER,
|
||||
unbound_by_user_id INTEGER, bind_source INTEGER, bound_at TEXT, unbound_at TEXT, unbind_reason TEXT);
|
||||
""")
|
||||
conn.execute("INSERT INTO device_bindings VALUES (1, ?, 7, NULL, 1, ?, NULL, NULL)", (DEVICE, str(uuid4())))
|
||||
conn.execute("INSERT INTO device_settings VALUES (?, ?)", (DEVICE, ICCID))
|
||||
conn.execute("INSERT INTO device_family_members VALUES (?, 1, NULL, NULL)", (DEVICE,))
|
||||
conn.commit()
|
||||
service = JointBindingService()
|
||||
service.test_relation = {"status": "bound", "relationState": "open"}
|
||||
service.test_relation_calls = []
|
||||
async def relation(source, request_id, *, close=False):
|
||||
service.test_relation_calls.append((source, request_id, close))
|
||||
if close: service.test_relation["relationState"] = "closing"
|
||||
return {**service.test_relation, "sourceBindingId": source, "pendingHandoff": False,
|
||||
"acceptingHandoff": service.test_relation["relationState"] == "open",
|
||||
"canUnbind": service.test_relation["relationState"] == "closing" and service.test_relation["status"] in {"unbound", "never_bound"}}
|
||||
monkeypatch.setattr("banban.service.joint_binding.binding_relation", relation)
|
||||
async def session(): return Session(conn)
|
||||
monkeypatch.setattr(service, "get_session", session)
|
||||
yield service, conn
|
||||
conn.close()
|
||||
|
||||
|
||||
async def confirm(service, op, iccid=ICCID, success=True, code="OK"):
|
||||
return await service.report(op["operation_id"], 7, op["action"], f"joint-{op['operation_id']}", iccid, code, success)
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_bind_failure_preserves_banban_and_request_identity(state, monkeypatch):
|
||||
service, conn = state
|
||||
calls = []
|
||||
async def unavailable(*args):
|
||||
calls.append(args)
|
||||
raise TrafficError("TRAFFIC_UNAVAILABLE", "timeout", 503)
|
||||
monkeypatch.setattr("banban.service.joint_binding.create_handoff", unavailable)
|
||||
op = await service.start(DEVICE, 7, "bind")
|
||||
for _ in range(2):
|
||||
assert (await service.start(DEVICE, 7, "bind"))["operation_id"] == op["operation_id"]
|
||||
with pytest.raises(TrafficError): await service.prepare(op["operation_id"], 7)
|
||||
assert calls[0] == calls[1]
|
||||
assert conn.execute("SELECT status FROM device_bindings").fetchone()[0] == 1
|
||||
assert (await service.overview(DEVICE, 7))["bind"]["status"] == "pending"
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_missing_iccid_never_removes_binding_or_completes_unbind(state):
|
||||
service, conn = state
|
||||
conn.execute("UPDATE device_settings SET iccid=NULL")
|
||||
conn.commit()
|
||||
op = await service.start(DEVICE, 7, "unbind")
|
||||
with pytest.raises(TrafficError, match="流量卡信息"): await service.prepare(op["operation_id"], 7)
|
||||
with pytest.raises(TrafficError): await service.finish_unbind(op["operation_id"], 7)
|
||||
assert conn.execute("SELECT status FROM device_bindings").fetchone()[0] == 1
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_successful_unbind_is_atomic_and_idempotent(state):
|
||||
service, conn = state
|
||||
op = await service.start(DEVICE, 7, "unbind")
|
||||
await service.prepare(op["operation_id"], 7)
|
||||
with pytest.raises(TrafficError): await service.finish_unbind(op["operation_id"], 7)
|
||||
result = await confirm(service, op, success=False, code="NETWORK_ERROR")
|
||||
assert result["status"] == "partial_failed"
|
||||
with pytest.raises(TrafficError): await service.finish_unbind(op["operation_id"], 7)
|
||||
service.test_relation["status"] = "unbound"
|
||||
await confirm(service, op)
|
||||
for _ in range(2):
|
||||
result = await service.finish_unbind(op["operation_id"], 7)
|
||||
assert result["status"] == "completed"
|
||||
assert conn.execute("SELECT status FROM device_bindings").fetchone()[0] == 0
|
||||
assert conn.execute("SELECT status FROM device_family_members").fetchone()[0] == 0
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_local_unbind_failure_rolls_back_and_keeps_4g_receipt(state, monkeypatch):
|
||||
service, conn = state
|
||||
op = await service.start(DEVICE, 7, "unbind")
|
||||
await service.prepare(op["operation_id"], 7)
|
||||
service.test_relation["status"] = "unbound"
|
||||
await confirm(service, op)
|
||||
original = BindingDAO.unbind
|
||||
async def fail_after_update(self, *args, **kwargs):
|
||||
await original(self, *args, **kwargs)
|
||||
raise RuntimeError("local transaction failure")
|
||||
monkeypatch.setattr(BindingDAO, "unbind", fail_after_update)
|
||||
with pytest.raises(RuntimeError): await service.finish_unbind(op["operation_id"], 7)
|
||||
assert conn.execute("SELECT status FROM device_bindings").fetchone()[0] == 1
|
||||
assert (await service.get(op["operation_id"], 7))["traffic_status"] == "server_confirmed"
|
||||
monkeypatch.setattr(BindingDAO, "unbind", original)
|
||||
assert (await service.finish_unbind(op["operation_id"], 7))["status"] == "completed"
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_owner_device_action_and_lifecycle_guards(state):
|
||||
service, conn = state
|
||||
with pytest.raises(TrafficError): await service.start(DEVICE, 8, "bind")
|
||||
op = await service.start(DEVICE, 7, "unbind")
|
||||
await service.prepare(op["operation_id"], 7)
|
||||
with pytest.raises(TrafficError): await service.get(op["operation_id"], 8)
|
||||
with pytest.raises(TrafficError): await confirm(service, op, iccid="898604E91123D1334999")
|
||||
with pytest.raises(TrafficError): await service.report(op["operation_id"], 7, "bind", f"joint-{op['operation_id']}", ICCID, "OK", True)
|
||||
with pytest.raises(TrafficError): await service.report(op["operation_id"], 7, "unbind", "other-request", ICCID, "OK", True)
|
||||
conn.execute("UPDATE device_bindings SET binding_instance_id=?", (str(uuid4()),))
|
||||
conn.commit()
|
||||
with pytest.raises(TrafficError): await confirm(service, op)
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_consumed_token_recovers_only_the_original_server_relation(state, monkeypatch):
|
||||
service, _ = state
|
||||
async def consumed(*args): raise TrafficError("HANDOFF_TOKEN_USED", "used")
|
||||
monkeypatch.setattr("banban.service.joint_binding.create_handoff", consumed)
|
||||
op = await service.start(DEVICE, 7, "bind")
|
||||
result = await service.prepare(op["operation_id"], 7)
|
||||
assert result["operation"]["status"] == "completed"
|
||||
assert result["operation"]["traffic_status"] == "server_confirmed"
|
||||
assert "recovery_only" not in result
|
||||
assert (await service.portal(DEVICE, 7))["iccid"] == ICCID
|
||||
await service.start(DEVICE, 7, "unbind")
|
||||
with pytest.raises(TrafficError): await service.portal(DEVICE, 7)
|
||||
with pytest.raises(TrafficError): await service.prepare(op["operation_id"], 7)
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
@pytest.mark.parametrize("status", ["unbound", "never_bound"])
|
||||
async def test_already_released_relation_finishes_without_client_receipt_or_iccid(state, status):
|
||||
service, conn = state
|
||||
conn.execute("UPDATE device_settings SET iccid=NULL")
|
||||
conn.commit()
|
||||
service.test_relation["status"] = status
|
||||
op = await service.start(DEVICE, 7, "unbind")
|
||||
checked = await service.check(op["operation_id"], 7)
|
||||
assert checked["traffic_status"] == "pending" # A plain GET on an open relation cannot authorize unbinding.
|
||||
prepared = await service.prepare(op["operation_id"], 7)
|
||||
assert prepared["operation"]["traffic_status"] == "server_confirmed"
|
||||
assert "target_app_id" not in prepared # No redundant jump to the 4G mini-program.
|
||||
assert (await service.finish_unbind(op["operation_id"], 7))["status"] == "completed"
|
||||
assert conn.execute("SELECT status FROM device_bindings").fetchone()[0] == 0
|
||||
close_calls = [call for call in service.test_relation_calls if call[2]]
|
||||
assert len(set(close_calls)) == 1
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_unknown_relation_and_legacy_success_receipt_never_unbind(state):
|
||||
service, conn = state
|
||||
service.test_relation["status"] = "unknown"
|
||||
op = await service.start(DEVICE, 7, "unbind")
|
||||
conn.execute("UPDATE device_binding_operations SET traffic_status='client_confirmed'")
|
||||
conn.commit()
|
||||
with pytest.raises(TrafficError) as failure: await service.finish_unbind(op["operation_id"], 7)
|
||||
assert failure.value.code == "HANDOFF_RELATION_UNKNOWN"
|
||||
assert conn.execute("SELECT status FROM device_bindings").fetchone()[0] == 1
|
||||
with pytest.raises(TrafficError) as failure: await service.start(DEVICE, 7, "bind")
|
||||
assert failure.value.code == "UNBIND_PENDING"
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_close_network_failure_is_bounded_and_preserves_local_unbinding_marker(state, monkeypatch):
|
||||
service, conn = state
|
||||
calls = []
|
||||
async def unavailable(source, request_id, *, close=False):
|
||||
calls.append((source, request_id, close))
|
||||
raise TrafficError("TRAFFIC_UNAVAILABLE", "timeout", 503)
|
||||
monkeypatch.setattr("banban.service.joint_binding.binding_relation", unavailable)
|
||||
op = await service.start(DEVICE, 7, "unbind")
|
||||
for _ in range(2):
|
||||
with pytest.raises(TrafficError): await service.prepare(op["operation_id"], 7)
|
||||
assert calls[0] == calls[1]
|
||||
assert conn.execute("SELECT status FROM device_bindings").fetchone()[0] == 1
|
||||
assert (await service.overview(DEVICE, 7))["unbind"]["operation_id"] == op["operation_id"]
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_late_close_response_cannot_unbind_a_new_binding_instance(state, monkeypatch):
|
||||
service, conn = state
|
||||
async def changed(source, request_id, *, close=False):
|
||||
conn.execute("UPDATE device_bindings SET binding_instance_id=?", (str(uuid4()),))
|
||||
conn.commit()
|
||||
return {"status": "unbound", "canUnbind": True, "relationState": "closing"}
|
||||
monkeypatch.setattr("banban.service.joint_binding.binding_relation", changed)
|
||||
op = await service.start(DEVICE, 7, "unbind")
|
||||
with pytest.raises(TrafficError) as failure: await service.finish_unbind(op["operation_id"], 7)
|
||||
assert failure.value.code == "STALE_OPERATION"
|
||||
assert conn.execute("SELECT status FROM device_bindings").fetchone()[0] == 1
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_consumed_token_unknown_or_released_relation_is_not_success(state, monkeypatch):
|
||||
service, _ = state
|
||||
async def consumed(*args): raise TrafficError("HANDOFF_TOKEN_USED", "used")
|
||||
monkeypatch.setattr("banban.service.joint_binding.create_handoff", consumed)
|
||||
op = await service.start(DEVICE, 7, "bind")
|
||||
for status in ["unknown", "unbound", "never_bound"]:
|
||||
service.test_relation["status"] = status
|
||||
with pytest.raises(TrafficError): await service.prepare(op["operation_id"], 7)
|
||||
assert (await service.get(op["operation_id"], 7))["status"] != "completed"
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_successful_client_receipt_cannot_override_active_original_binding(state):
|
||||
service, conn = state
|
||||
op = await service.start(DEVICE, 7, "unbind")
|
||||
await service.prepare(op["operation_id"], 7)
|
||||
result = await confirm(service, op)
|
||||
assert result["traffic_status"] == "pending"
|
||||
with pytest.raises(TrafficError): await service.finish_unbind(op["operation_id"], 7)
|
||||
assert conn.execute("SELECT status FROM device_bindings").fetchone()[0] == 1
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_expired_token_rotates_only_application_key(state, monkeypatch):
|
||||
service, _ = state
|
||||
calls = []
|
||||
async def expired(*args):
|
||||
calls.append(args)
|
||||
raise TrafficError("HANDOFF_TOKEN_EXPIRED", "expired")
|
||||
monkeypatch.setattr("banban.service.joint_binding.create_handoff", expired)
|
||||
op = await service.start(DEVICE, 7, "bind")
|
||||
for _ in range(2):
|
||||
with pytest.raises(TrafficError): await service.prepare(op["operation_id"], 7)
|
||||
assert calls[0][:2] == calls[1][:2]
|
||||
assert calls[0][2] != calls[1][2]
|
||||
assert (await service.start(DEVICE, 7, "bind"))["operation_id"] == op["operation_id"]
|
||||
|
||||
|
||||
def test_binding_generation_changes_only_for_new_ownership():
|
||||
row = {"status": 1, "owner_user_id": 7, "binding_instance_id": str(uuid4())}
|
||||
assert BindingDAO._binding_instance(row, 7) == row["binding_instance_id"]
|
||||
assert BindingDAO._binding_instance(row, 8) != row["binding_instance_id"]
|
||||
row["status"] = 0
|
||||
assert BindingDAO._binding_instance(row, 7) != row["binding_instance_id"]
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_iccid_normalization_and_conflict(state):
|
||||
service, conn = state
|
||||
assert normalize_iccid(ICCID.lower()) == ICCID
|
||||
for invalid in [None, 1234, "123456789012345", "x" * 23, "#" * 20]: assert normalize_iccid(invalid) is None
|
||||
await service.record_iccid(DEVICE, ICCID.lower())
|
||||
with pytest.raises(TrafficError): await service.record_iccid(DEVICE, "898604E91123D1334999")
|
||||
assert conn.execute("SELECT iccid FROM device_settings").fetchone()[0] == ICCID
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_mqtt_006_failure_and_iccid_failure(monkeypatch):
|
||||
from handlers.mqtt_handler import TalkingQMQTTService
|
||||
calls = []
|
||||
logs = []
|
||||
monkeypatch.setattr("handlers.mqtt_handler.logger.info", lambda *args: logs.append(args[-1]))
|
||||
async def broken_iccid(*args): raise RuntimeError("database unavailable")
|
||||
async def finalize(**kwargs):
|
||||
calls.append(kwargs)
|
||||
return None
|
||||
monkeypatch.setattr("banban.service.joint_binding.joint_binding_service.record_iccid", broken_iccid)
|
||||
monkeypatch.setattr("handlers.mqtt_handler.binding_service.finalize_nfc_bind", finalize)
|
||||
mqtt = TalkingQMQTTService({"broker": "localhost"})
|
||||
await mqtt._handle_bind_response(DEVICE, {"status": "failed", "data": {"uuid": "CARD"}})
|
||||
await mqtt._handle_bind_response(DEVICE, {"status": "success", "data": None})
|
||||
assert not calls
|
||||
await mqtt._handle_bind_response(DEVICE, {"status": "success", "data": {"uuid": "CARD", "iccid": ICCID}})
|
||||
await mqtt._handle_bind_response(DEVICE, {"status": "success", "data": {"uuid": "CARD"}})
|
||||
assert len(calls) == 2
|
||||
assert any("ICCID present=True, valid=True" in line for line in logs)
|
||||
assert any("ICCID present=False, valid=False" in line for line in logs)
|
||||
assert not any("ICCID persisted" in line for line in logs)
|
||||
async def saved_iccid(*args): return None
|
||||
monkeypatch.setattr("banban.service.joint_binding.joint_binding_service.record_iccid", saved_iccid)
|
||||
await mqtt._handle_bind_response(DEVICE, {"status": "success", "data": {"uuid": "CARD", "iccid": ICCID}})
|
||||
assert any("ICCID persisted" in line for line in logs)
|
||||
assert not any(ICCID in line for line in logs)
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
@pytest.mark.parametrize("body", [None, {"code": "OK", "data": {}},
|
||||
{"code": "OK", "data": {"targetAppId": "wrong", "handoffToken": "secret", "expiresIn": 300}},
|
||||
{"code": "OK", "data": {"targetAppId": "wx56e1cfc52aab630f", "handoffToken": "secret", "expiresIn": True}}])
|
||||
async def test_upstream_malformed_reply_is_not_success(monkeypatch, body):
|
||||
real_client = httpx.AsyncClient
|
||||
transport = httpx.MockTransport(lambda req: httpx.Response(200, json=body))
|
||||
monkeypatch.setattr(traffic_handoff.settings, "banban_handoff_service_token", "test-service-token")
|
||||
monkeypatch.setattr(traffic_handoff.httpx, "AsyncClient", lambda **kwargs: real_client(transport=transport, **kwargs))
|
||||
with pytest.raises(TrafficError): await traffic_handoff.create_handoff(ICCID, "banban:test", "test-request")
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_router_timeout_returns_retryable_error(monkeypatch):
|
||||
from banban.routers.joint_binding import call
|
||||
from fastapi import HTTPException
|
||||
real_wait_for = asyncio.wait_for
|
||||
async def short_wait(coro, timeout):
|
||||
assert timeout == 8
|
||||
return await real_wait_for(coro, timeout=0.001)
|
||||
monkeypatch.setattr(asyncio, "wait_for", short_wait)
|
||||
with pytest.raises(HTTPException) as failure: await call(asyncio.sleep(10))
|
||||
assert failure.value.status_code == 503
|
||||
assert failure.value.detail["code"] == "OPERATION_TIMEOUT"
|
||||
@@ -0,0 +1,79 @@
|
||||
import json
|
||||
|
||||
import httpx
|
||||
import pytest
|
||||
|
||||
from banban.service import traffic_handoff as adapter
|
||||
|
||||
SOURCE = "banban:12345678-1234-1234-1234-123456789abc"
|
||||
RELEASED = {"sourceBindingId": SOURCE, "status": "unbound", "relationState": "closing",
|
||||
"pendingHandoff": False, "acceptingHandoff": False, "canUnbind": True,
|
||||
"reason": "ORIGINAL_BINDING_RELEASED", "checkedAt": "2026-09-23T08:00:00Z"}
|
||||
|
||||
|
||||
def transport(monkeypatch, callback):
|
||||
client = httpx.AsyncClient
|
||||
monkeypatch.setattr(adapter.settings, "banban_handoff_service_token", "test-only")
|
||||
monkeypatch.setattr(adapter.httpx, "AsyncClient", lambda **kwargs: client(transport=httpx.MockTransport(callback), **kwargs))
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_query_and_close_encode_existing_ids_and_use_service_auth(monkeypatch):
|
||||
requests = []
|
||||
def reply(request):
|
||||
requests.append(request)
|
||||
return httpx.Response(200, json={"code": "OK", "data": RELEASED})
|
||||
transport(monkeypatch, reply)
|
||||
await adapter.binding_relation(SOURCE, "query-1")
|
||||
for _ in range(2): await adapter.binding_relation(SOURCE, "close-1", close=True)
|
||||
assert requests[0].method == "GET" and requests[0].content == b""
|
||||
assert b"banban%3A" in requests[0].url.raw_path
|
||||
assert all(request.headers["X-Service-Token"] == "test-only" for request in requests)
|
||||
assert all("Authorization" not in request.headers for request in requests)
|
||||
assert requests[0].headers["Cache-Control"] == "no-cache"
|
||||
assert requests[1].url.path.endswith("/close") and requests[1].method == "POST"
|
||||
assert json.loads(requests[1].content) == {"requestId": "close-1"}
|
||||
assert requests[1].content == requests[2].content
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
@pytest.mark.parametrize("changes", [
|
||||
{"sourceBindingId": "another"}, {"canUnbind": "true"}, {"pendingHandoff": 0},
|
||||
{"pendingHandoff": True}, {"acceptingHandoff": True}, {"relationState": "open"},
|
||||
{"status": "bound"}, {"status": "unknown"}, {"status": {}},
|
||||
{"relationState": []}, {"checkedAt": None}, {"checkedAt": "badZ"},
|
||||
{"checkedAt": "2026-09-23T08:00:00"}, {"canUnbind": False},
|
||||
])
|
||||
async def test_inconsistent_or_malformed_relation_never_authorizes_unbind(monkeypatch, changes):
|
||||
transport(monkeypatch, lambda request: httpx.Response(200, json={"code": "OK", "data": {**RELEASED, **changes}}))
|
||||
with pytest.raises(adapter.TrafficError) as failure: await adapter.binding_relation(SOURCE, "query")
|
||||
assert failure.value.code == "INVALID_RESPONSE"
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
@pytest.mark.parametrize("status,code", [(401, "HANDOFF_SERVICE_UNAUTHORIZED"), (429, "RATE_LIMITED"),
|
||||
(500, "INTERNAL_ERROR"), (404, "NOT_FOUND"), (200, "HANDOFF_RELATION_UNKNOWN")])
|
||||
async def test_http_or_business_errors_never_become_unbound(monkeypatch, status, code):
|
||||
transport(monkeypatch, lambda request: httpx.Response(status, json={"code": code, "data": RELEASED}))
|
||||
with pytest.raises(adapter.TrafficError): await adapter.binding_relation(SOURCE, "close", close=True)
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
@pytest.mark.parametrize("state", [
|
||||
{**RELEASED, "status": "never_bound"},
|
||||
{**RELEASED, "status": "bound", "canUnbind": False},
|
||||
{**RELEASED, "status": "unknown", "canUnbind": False},
|
||||
{**RELEASED, "status": "unknown", "relationState": "unknown", "canUnbind": False},
|
||||
{**RELEASED, "status": "never_bound", "relationState": "open", "acceptingHandoff": True, "pendingHandoff": True, "canUnbind": False},
|
||||
])
|
||||
async def test_valid_non_success_business_states_are_preserved(monkeypatch, state):
|
||||
transport(monkeypatch, lambda request: httpx.Response(200, json={"code": "OK", "data": state}))
|
||||
assert await adapter.binding_relation(SOURCE, "query") == state
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_relation_network_timeout_is_explicit(monkeypatch):
|
||||
def timeout(request): raise httpx.ReadTimeout("test timeout")
|
||||
transport(monkeypatch, timeout)
|
||||
with pytest.raises(adapter.TrafficError) as failure: await adapter.binding_relation(SOURCE, "query")
|
||||
assert failure.value.code == "TRAFFIC_UNAVAILABLE"
|
||||
Reference in New Issue
Block a user