feat(semi-auto): 新增履约历史与全链路报文留痕

运营端历史抽屉展示状态流转与全链路报文:客户/运营接口入站 + 虎牙 WUP/livelink、外部 Connector 出站;轮询按状态变化采样,Cookie/Token/短信验证码不落库,报文保留 180 天。同步收敛登录/绑定事件,避免轮询重复写时间线。
This commit is contained in:
2026-11-16 17:26:35 +08:00
parent f371cc2c8d
commit 08e753ec94
13 changed files with 1648 additions and 101 deletions
@@ -0,0 +1,248 @@
import crypto from 'node:crypto'
import type { NextFunction, Request, Response } from 'express'
import { query } from '../db/client.js'
import {
recordSemiAutoTrace,
runWithSemiAutoTrace,
traceFingerprint,
type SemiAutoTraceChannel,
} from '../services/semi-auto/semi-auto-trace.js'
import { logWarn } from '../utils/logger.js'
/**
* 半自动履约入站报文:以 `:taskId` 路由参数为锚点。
*
* 用法:`router.param('taskId', createSemiAutoTaskTraceHandler({ channel: 'customer_api' }))`。
* 命中后整条请求链路都在 AsyncLocalStorage 上下文里,外部 Connector / 虎牙 RPC 的出站报文
* 会自动复用同一个 requestId,前端即可按 requestId 串起「一次客户操作」。
*/
export type SemiAutoTaskTraceOptions = {
channel: SemiAutoTraceChannel
/** 轮询类请求:只有失败或响应状态变化才落库。 */
isPolling?: (req: Request) => boolean
/** 不记录本次请求(例如返回 CK 的导出接口、历史查询自身)。 */
skip?: (req: Request) => boolean
}
const TASK_ORDER_CACHE_LIMIT = 800
const taskOrderCache = new Map<number, string>()
/** 响应里代表「状态」的字段:轮询指纹只取这些,时间戳/计数变化不算状态变化。 */
const TRACE_STATE_KEYS = [
'status',
'state',
'loginStatus',
'bindingStatus',
'executionStatus',
'displayStatus',
'message',
'msg',
'code',
'errorCode',
'ok',
'challenge',
'ready',
'pending',
'type',
'rebindUnchanged',
'rebindRequested',
'rebindConfirmState',
'rebindConfirmMessage',
'rebindCooldownDays',
'nextRebindAt',
'bindConfirmState',
'bindConfirmMessage',
'bindEffectDeadlineMs',
'bindGameRole',
'bindGameRoleId',
'huyaUid',
'lastError',
'isBindAccount',
'isBindRole',
]
/** 客户请求体里的凭据类字段:短信验证码等一律不落库。 */
const INBOUND_SECRET_KEYS = new Set([
'code',
'smscode',
'sms_code',
'password',
'token',
'cookie',
'qrcode',
'qrcode_token',
'qrcodetoken',
'ticket',
'sig',
])
function normalizeKey(key: string): string {
return key.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase()
}
function createTraceRequestId(): string {
return `req_${Date.now().toString(36)}_${crypto.randomBytes(4).toString('hex')}`
}
async function resolveTaskOrderNo(taskId: number): Promise<string> {
const cached = taskOrderCache.get(taskId)
if (cached !== undefined) return cached
try {
const result = await query<{ platform_order_id: string | null }>(
`SELECT o.platform_order_id
FROM semi_auto_tasks task
JOIN orders o ON o.id = task.order_id
WHERE task.id = $1
LIMIT 1`,
[taskId],
)
const orderNo = String(result.rows[0]?.platform_order_id || '')
if (taskOrderCache.size >= TASK_ORDER_CACHE_LIMIT) taskOrderCache.clear()
taskOrderCache.set(taskId, orderNo)
return orderNo
} catch (error) {
logWarn('[semi-auto/trace]', '解析任务订单号失败,报文将不带订单号', {
taskId,
error: error instanceof Error ? error.message : String(error),
})
return ''
}
}
function maskInboundRequestBody(value: unknown, depth = 0): unknown {
if (depth > 4) return '[max-depth]'
if (value === null || value === undefined) return value
if (Array.isArray(value)) {
return value.slice(0, 50).map((item) => maskInboundRequestBody(item, depth + 1))
}
if (typeof value !== 'object') return value
const source = value as Record<string, unknown>
const masked: Record<string, unknown> = {}
for (const [key, current] of Object.entries(source)) {
masked[key] = INBOUND_SECRET_KEYS.has(normalizeKey(key))
? '******'
: maskInboundRequestBody(current, depth + 1)
}
return masked
}
function pickTraceState(value: unknown, depth = 0): unknown {
if (!value || typeof value !== 'object' || depth > 3) return value
if (Array.isArray(value)) {
return value.slice(0, 20).map((item) => pickTraceState(item, depth + 1))
}
const source = value as Record<string, unknown>
const picked: Record<string, unknown> = {}
for (const key of TRACE_STATE_KEYS) {
if (key in source && source[key] !== undefined) picked[key] = source[key]
}
// 常见响应外壳:{ task, login, binding }
for (const key of ['task', 'login', 'binding', 'result']) {
const nested = source[key]
if (nested && typeof nested === 'object' && !Array.isArray(nested)) {
picked[key] = pickTraceState(nested, depth + 1)
}
}
return Object.keys(picked).length > 0 ? picked : value
}
function buildPollingFingerprint(payload: unknown): string {
const body = payload && typeof payload === 'object' ? (payload as Record<string, unknown>) : {}
return traceFingerprint({
code: body.code,
msg: body.msg,
errorCode: body.errorCode,
data: pickTraceState(body.data),
})
}
export function createSemiAutoTaskTraceHandler(options: SemiAutoTaskTraceOptions) {
return (req: Request, res: Response, next: NextFunction, taskIdInput: string): void => {
const taskId = Number(taskIdInput)
if (!Number.isInteger(taskId) || taskId <= 0) {
next()
return
}
if (options.skip?.(req)) {
next()
return
}
const pathOrderNo = String(req.params?.orderNo || '').trim()
const startedAt = Date.now()
const requestId = createTraceRequestId()
const polling = options.isPolling?.(req) === true
const actionPath = String(req.originalUrl || req.url || '').split('?')[0]
const action = `${String(req.method || 'GET').toUpperCase()} ${actionPath}`
const requestSummary = {
method: req.method,
path: actionPath,
query: req.query || {},
ip: req.ip || '',
}
const requestBody =
req.body && typeof req.body === 'object' && Object.keys(req.body as object).length > 0
? maskInboundRequestBody(req.body)
: ''
let recorded = false
const record = (payload: unknown) => {
if (recorded) return
recorded = true
try {
const body =
payload && typeof payload === 'object' ? (payload as Record<string, unknown>) : {}
const code = Number(body.code)
const httpStatus = Number(res.statusCode || 200)
const failed = Number.isFinite(code) ? code !== 0 : httpStatus >= 400
const status = failed || httpStatus >= 400 ? 'error' : 'ok'
recordSemiAutoTrace({
taskId,
orderNo: pathOrderNo,
requestId,
direction: 'inbound',
channel: options.channel,
action,
status,
httpStatus,
durationMs: Date.now() - startedAt,
requestSummary,
requestBody,
responseSummary: {
code: body.code ?? null,
msg: body.msg ?? '',
errorCode: body.errorCode ?? '',
},
responseBody: payload,
errorMessage: status === 'error' ? String(body.msg || '') : '',
always: !polling,
fingerprint: polling ? buildPollingFingerprint(payload) : undefined,
})
} catch (error) {
logWarn('[semi-auto/trace]', '记录入站报文失败,已跳过', {
taskId,
action,
error: error instanceof Error ? error.message : String(error),
})
}
}
const originalJson = res.json.bind(res)
res.json = ((payload: unknown) => {
record(payload)
return originalJson(payload as never)
}) as Response['json']
const start = (orderNo: string) => {
runWithSemiAutoTrace({ requestId, taskId, orderNo, source: options.channel }, () => next())
}
if (pathOrderNo) {
start(pathOrderNo)
return
}
void resolveTaskOrderNo(taskId).then(start, () => start(''))
}
}