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
@@ -16,6 +16,7 @@ import {
huyaNativeConnector,
type HuyaStoredCredential,
} from './huya-native/huya-native-connector.js'
import { recordSemiAutoTrace, traceFingerprint } from './semi-auto-trace.js'
export type ConnectorLoginSession = {
sessionId: string
@@ -204,9 +205,11 @@ async function callConnector<T>(
const timeoutMs = Math.max(1000, Number(runtimeConfig.semiAuto?.connectorTimeoutMs || 15_000))
const controller = new AbortController()
const timer = setTimeout(() => controller.abort(), timeoutMs)
const method = String(options.method || 'GET').toUpperCase()
const startedAt = Date.now()
try {
const requestInit: RequestInit = {
method: options.method || 'GET',
method,
headers: {
Accept: 'application/json',
'Content-Type': 'application/json',
@@ -223,6 +226,20 @@ async function callConnector<T>(
} catch {
payload = null
}
recordSemiAutoTrace({
direction: 'outbound',
channel: 'external_connector',
action: `${method} ${path}`,
status: response.ok ? 'ok' : 'error',
httpStatus: response.status,
durationMs: Date.now() - startedAt,
requestSummary: { baseUrl: endpoint.baseUrl },
requestBody: options.body,
responseSummary: { bodyBytes: text.length },
responseBody: payload ?? text,
always: method !== 'GET',
fingerprint: method === 'GET' ? traceFingerprint(payload) : undefined,
})
if (!response.ok) {
const detail =
payload && typeof payload === 'object'
@@ -235,6 +252,19 @@ async function callConnector<T>(
}
return payload as T
} catch (error) {
if (!(error && typeof error === 'object' && 'statusCode' in error)) {
recordSemiAutoTrace({
direction: 'outbound',
channel: 'external_connector',
action: `${method} ${path}`,
status: 'error',
durationMs: Date.now() - startedAt,
requestSummary: { baseUrl: endpoint.baseUrl },
requestBody: options.body,
always: true,
errorMessage: error instanceof Error ? error.message : String(error),
})
}
if (error && typeof error === 'object' && 'statusCode' in error) throw error
if (error instanceof Error && error.name === 'AbortError') {
throw createHttpError('半自动履约 Connector 请求超时', {
@@ -2,6 +2,7 @@
import crypto from 'node:crypto'
import { recordSemiAutoTrace, traceFingerprint } from '../semi-auto-trace.js'
import { buildHuyaLoginContext, cookiePairs, cookieValue, normalizeCookiePairs } from './cookie.js'
import {
decodeWupResponse,
@@ -494,22 +495,67 @@ export class HuyaRpcClient {
gid?: number
scene?: string
}): Promise<HuyaBindResponse | null> {
const response = await this.callRpc(
'webActUI',
'checkUserBindGameAccount',
input.uid,
input.cookie,
(writer) => {
this.writeActivityUser(writer, input.uid, input.cookie)
writer.writeInt32(1, input.gid || 0)
writer.writeString(2, input.outerActId || '')
writer.writeInt32(3, 0)
writer.writeString(4, input.scene || '')
writer.writeInt32(5, input.bindActId || 0)
writer.writeInt32(6, input.isUseOuterActId ?? 1)
},
)
return response ? readWupStruct(response, parseBindResponse) : null
const startedAt = Date.now()
const request = {
servant: 'webActUI',
func: 'checkUserBindGameAccount',
uid: input.uid,
gid: input.gid || 0,
outerActId: input.outerActId || '',
bindActId: input.bindActId || 0,
isUseOuterActId: input.isUseOuterActId ?? 1,
scene: input.scene || '',
}
try {
const response = await this.callRpc(
'webActUI',
'checkUserBindGameAccount',
input.uid,
input.cookie,
(writer) => {
this.writeActivityUser(writer, input.uid, input.cookie)
writer.writeInt32(1, input.gid || 0)
writer.writeString(2, input.outerActId || '')
writer.writeInt32(3, 0)
writer.writeString(4, input.scene || '')
writer.writeInt32(5, input.bindActId || 0)
writer.writeInt32(6, input.isUseOuterActId ?? 1)
},
)
const parsed = response ? readWupStruct(response, parseBindResponse) : null
recordSemiAutoTrace({
direction: 'outbound',
channel: 'huya_wup',
action: 'webActUI.checkUserBindGameAccount',
status: parsed && parsed.status === 200 ? 'ok' : 'error',
durationMs: Date.now() - startedAt,
requestSummary: request,
responseSummary: { status: parsed?.status, msg: parsed?.msg },
responseBody: parsed,
// 绑定轮询:状态没变化就不落库。
fingerprint: traceFingerprint({
status: parsed?.status,
msg: parsed?.msg,
isBindAccount: parsed?.accountData?.isBindAccount,
isBindRole: parsed?.accountData?.isBindRole,
role: parsed?.accountData?.gameRole?.roleName,
roleId: parsed?.accountData?.gameRole?.roleId,
}),
errorMessage: parsed && parsed.status !== 200 ? String(parsed.msg || '') : '',
})
return parsed
} catch (error) {
recordSemiAutoTrace({
direction: 'outbound',
channel: 'huya_wup',
action: 'webActUI.checkUserBindGameAccount',
status: 'error',
durationMs: Date.now() - startedAt,
requestSummary: request,
errorMessage: error instanceof Error ? error.message : String(error),
})
throw error
}
}
async confirmBindActAccount(input: {
@@ -519,19 +565,55 @@ export class HuyaRpcClient {
outerActId: string
gid?: number
}): Promise<HuyaConfirmResponse | null> {
const response = await this.callRpc(
'webActUI',
'confirmBindActAccount',
input.uid,
input.cookie,
(writer) => {
this.writeActivityUser(writer, input.uid, input.cookie)
writer.writeInt32(1, input.gid || 0)
writer.writeString(2, input.outerActId || '')
writer.writeInt32(3, input.bindActId || 0)
},
)
return response ? readWupStruct(response, parseConfirmResponse) : null
const startedAt = Date.now()
const request = {
servant: 'webActUI',
func: 'confirmBindActAccount',
uid: input.uid,
gid: input.gid || 0,
outerActId: input.outerActId || '',
bindActId: input.bindActId || 0,
}
try {
const response = await this.callRpc(
'webActUI',
'confirmBindActAccount',
input.uid,
input.cookie,
(writer) => {
this.writeActivityUser(writer, input.uid, input.cookie)
writer.writeInt32(1, input.gid || 0)
writer.writeString(2, input.outerActId || '')
writer.writeInt32(3, input.bindActId || 0)
},
)
const parsed = response ? readWupStruct(response, parseConfirmResponse) : null
recordSemiAutoTrace({
direction: 'outbound',
channel: 'huya_wup',
action: 'webActUI.confirmBindActAccount',
status: parsed && parsed.status === 200 ? 'ok' : 'error',
durationMs: Date.now() - startedAt,
requestSummary: request,
responseSummary: { status: parsed?.status, msg: parsed?.msg },
responseBody: parsed,
always: true,
errorMessage: parsed && parsed.status !== 200 ? String(parsed.msg || '') : '',
})
return parsed
} catch (error) {
recordSemiAutoTrace({
direction: 'outbound',
channel: 'huya_wup',
action: 'webActUI.confirmBindActAccount',
status: 'error',
durationMs: Date.now() - startedAt,
requestSummary: request,
always: true,
errorMessage: error instanceof Error ? error.message : String(error),
})
throw error
}
}
async getLiveLinkParam(input: {
@@ -541,21 +623,57 @@ export class HuyaRpcClient {
outerActId: number
gameAuthScene?: string
}): Promise<HuyaLiveLinkResponse | null> {
const response = await this.callRpc(
'webActUI',
'getLiveLinkParam',
input.uid,
input.cookie,
(writer) => {
this.writeActivityUser(writer, input.uid, input.cookie)
writer.writeInt32(1, 0)
writer.writeInt32(2, input.outerActId || 0)
writer.writeString(3, input.gameAuthScene || '')
writer.writeString(4, '')
writer.writeInt32(5, input.bindActId || 0)
},
)
return response ? readWupStruct(response, parseLiveLinkResponse) : null
const startedAt = Date.now()
const request = {
servant: 'webActUI',
func: 'getLiveLinkParam',
uid: input.uid,
bindActId: input.bindActId || 0,
outerActId: input.outerActId || 0,
gameAuthScene: input.gameAuthScene || '',
}
try {
const response = await this.callRpc(
'webActUI',
'getLiveLinkParam',
input.uid,
input.cookie,
(writer) => {
this.writeActivityUser(writer, input.uid, input.cookie)
writer.writeInt32(1, 0)
writer.writeInt32(2, input.outerActId || 0)
writer.writeString(3, input.gameAuthScene || '')
writer.writeString(4, '')
writer.writeInt32(5, input.bindActId || 0)
},
)
const parsed = response ? readWupStruct(response, parseLiveLinkResponse) : null
recordSemiAutoTrace({
direction: 'outbound',
channel: 'huya_wup',
action: 'webActUI.getLiveLinkParam',
status: parsed && parsed.status === 200 ? 'ok' : 'error',
durationMs: Date.now() - startedAt,
requestSummary: request,
responseSummary: { status: parsed?.status, msg: parsed?.msg },
responseBody: parsed,
always: true,
errorMessage: parsed && parsed.status !== 200 ? String(parsed.msg || '') : '',
})
return parsed
} catch (error) {
recordSemiAutoTrace({
direction: 'outbound',
channel: 'huya_wup',
action: 'webActUI.getLiveLinkParam',
status: 'error',
durationMs: Date.now() - startedAt,
requestSummary: request,
always: true,
errorMessage: error instanceof Error ? error.message : String(error),
})
throw error
}
}
async getUserProfileBatch(input: {
@@ -585,17 +703,53 @@ export class HuyaRpcClient {
}): Promise<HuyaUserProfile | null> {
const targetUid = Math.trunc(input.targetUid)
if (!(targetUid > 0)) return null
const response = await this.callRpc(
'huyauserui',
'getUserProfile',
input.uid,
input.cookie,
(writer) => {
this.writeActivityUser(writer, 0, input.cookie)
writer.writeInt64(1, targetUid)
},
)
return response ? readWupStruct(response, parseProfileResponse) : null
const startedAt = Date.now()
try {
const response = await this.callRpc(
'huyauserui',
'getUserProfile',
input.uid,
input.cookie,
(writer) => {
this.writeActivityUser(writer, 0, input.cookie)
writer.writeInt64(1, targetUid)
},
)
const parsed = response ? readWupStruct(response, parseProfileResponse) : null
recordSemiAutoTrace({
direction: 'outbound',
channel: 'huya_wup',
action: 'huyauserui.getUserProfile',
status: parsed ? 'ok' : 'error',
durationMs: Date.now() - startedAt,
requestSummary: {
servant: 'huyauserui',
func: 'getUserProfile',
uid: input.uid,
targetUid,
},
responseBody: parsed,
always: true,
})
return parsed
} catch (error) {
recordSemiAutoTrace({
direction: 'outbound',
channel: 'huya_wup',
action: 'huyauserui.getUserProfile',
status: 'error',
durationMs: Date.now() - startedAt,
requestSummary: {
servant: 'huyauserui',
func: 'getUserProfile',
uid: input.uid,
targetUid,
},
always: true,
errorMessage: error instanceof Error ? error.message : String(error),
})
throw error
}
}
private async callRpc(
@@ -715,6 +869,7 @@ export async function getLiveLinkMiniQrcode(
).join('')
const sessionId = `${Math.floor(Date.now() / 1000)}_${suffix}`
const fetchImpl = options.fetchImpl || fetch
const startedAt = Date.now()
const response = await fetchImpl(`${LIVELINK_BIND_API_BASE}/api/qrcode/getMiniAppQrcode`, {
method: 'POST',
headers: {
@@ -728,14 +883,41 @@ export async function getLiveLinkMiniQrcode(
body: JSON.stringify({ queryString: `${query}&sessionId=${sessionId}` }),
signal: AbortSignal.timeout(options.timeoutMs || 15_000),
})
if (!response.ok) return null
const traceMiniQrcode = (status: 'ok' | 'error', extra: Record<string, unknown> = {}) => {
recordSemiAutoTrace({
direction: 'outbound',
channel: 'huya_http',
action: 'livelink.getMiniAppQrcode',
status,
durationMs: Date.now() - startedAt,
httpStatus: response.status,
requestSummary: { api: 'getMiniAppQrcode', queryLength: query.length },
responseSummary: extra,
always: true,
})
}
if (!response.ok) {
traceMiniQrcode('error', { httpStatus: response.status })
return null
}
const payload = (await response.json().catch(() => null)) as {
iRet?: number
jData?: { qrcode?: string; qrcodeToken?: string }
} | null
if (!payload || payload.iRet !== 0) return null
if (!payload || payload.iRet !== 0) {
traceMiniQrcode('error', { iRet: payload?.iRet ?? null })
return null
}
const image = livelinkQrcodeImageSrc(String(payload.jData?.qrcode || ''))
if (!image) return null
if (!image) {
traceMiniQrcode('error', { iRet: payload.iRet, hasImage: false })
return null
}
traceMiniQrcode('ok', {
iRet: payload.iRet,
hasImage: true,
tokenLength: String(payload.jData?.qrcodeToken || '').length,
})
return { image, token: String(payload.jData?.qrcodeToken || '') }
}
@@ -751,6 +933,7 @@ export async function getLiveLinkQrcodeStatus(
const normalized = String(token || '').trim()
if (!normalized) return null
const fetchImpl = options.fetchImpl || fetch
const startedAt = Date.now()
const response = await fetchImpl(`${LIVELINK_BIND_API_BASE}/api/qrcode/poolingQrcodeStatus`, {
method: 'POST',
headers: {
@@ -764,7 +947,24 @@ export async function getLiveLinkQrcodeStatus(
body: JSON.stringify({ qrcodeToken: normalized }),
signal: AbortSignal.timeout(options.timeoutMs || 15_000),
})
if (!response.ok) return null
const traceQrcodeStatus = (status: 'ok' | 'error', extra: Record<string, unknown> = {}) => {
recordSemiAutoTrace({
direction: 'outbound',
channel: 'huya_http',
action: 'livelink.poolingQrcodeStatus',
status,
durationMs: Date.now() - startedAt,
httpStatus: response.status,
requestSummary: { api: 'poolingQrcodeStatus', tokenLength: normalized.length },
responseSummary: extra,
// 二维码轮询:状态没变化就不落库。
fingerprint: traceFingerprint(extra),
})
}
if (!response.ok) {
traceQrcodeStatus('error', { httpStatus: response.status })
return null
}
const payload = (await response.json().catch(() => null)) as {
iRet?: number
jData?: {
@@ -774,13 +974,18 @@ export async function getLiveLinkQrcodeStatus(
isFailure?: boolean
}
} | null
if (!payload || payload.iRet !== 0) return null
return {
if (!payload || payload.iRet !== 0) {
traceQrcodeStatus('error', { iRet: payload?.iRet ?? null })
return null
}
const result = {
isScan: Boolean(payload.jData?.isScan),
isExpired: Boolean(payload.jData?.isExpired),
isCompleted: Boolean(payload.jData?.isCompleted),
isFailure: Boolean(payload.jData?.isFailure),
}
traceQrcodeStatus('ok', { iRet: payload.iRet, ...result })
return result
}
export function buildBindUrls(input: {
@@ -55,6 +55,7 @@ import {
markSemiAutoCredentialCheck,
upsertSemiAutoCredentialWithClient,
} from './semi-auto-credential-service.js'
import { querySemiAutoTraces } from './semi-auto-trace.js'
const SEMI_AUTO_PLATFORMS = new Set(['huya', 'weibo'])
type SemiAutoPlatform = 'huya' | 'weibo'
@@ -920,19 +921,22 @@ async function updateLoginTask(
credentialId,
],
)
await appendTaskEvent(client, task.id, {
eventType: 'login_status_changed',
actorType,
fromLoginStatus: task.login_status,
toLoginStatus: mapped.status,
fromExecutionStatus: task.execution_status,
toExecutionStatus: nextExecutionStatus,
detail: {
hasCredential: mapped.hasCredential,
message: mapped.message,
method: options.method || 'qr',
},
})
// 轮询会每 2 秒调用一次:状态与执行状态都没变时不写事件,避免时间线被重复项淹没。
if (mapped.status !== task.login_status || nextExecutionStatus !== task.execution_status) {
await appendTaskEvent(client, task.id, {
eventType: 'login_status_changed',
actorType,
fromLoginStatus: task.login_status,
toLoginStatus: mapped.status,
fromExecutionStatus: task.execution_status,
toExecutionStatus: nextExecutionStatus,
detail: {
hasCredential: mapped.hasCredential,
message: mapped.message,
method: options.method || 'qr',
},
})
}
})
}
@@ -1130,32 +1134,40 @@ async function updateBindingTask(
mapped.bindGameRoleId,
],
)
await appendTaskEvent(client, task.id, {
eventType: 'binding_status_changed',
actorType,
fromBindingStatus: task.binding_status,
toBindingStatus: mapped.status,
fromExecutionStatus: task.execution_status,
toExecutionStatus: executionStatus,
detail: {
gameAccount: mapped.bindGameAccount,
gameRole: mapped.bindGameRole,
gameRoleId: mapped.bindGameRoleId,
gameChannel: mapped.bindGameChannel,
verdict: comparison.verdict,
rebindRequested: mapped.rebindRequested,
rebindUnchanged: mapped.rebindUnchanged,
rebindConfirmState: mapped.rebindConfirmState,
rebindConfirmMessage: mapped.rebindConfirmMessage,
bindConfirmState: mapped.bindConfirmState,
bindConfirmMessage: mapped.bindConfirmMessage,
rebindCooldownDays: mapped.rebindCooldownDays,
nextRebindAt: mapped.nextRebindAt,
changeBindDay: mapped.platformChangeBindDay,
changeBindTime: mapped.platformChangeBindTime,
message: mapped.message,
},
})
// 轮询会每 2 秒调用一次:只有状态/执行状态变化,或换绑被拒这类关键信号才写事件。
const bindingChanged =
mapped.status !== task.binding_status ||
executionStatus !== task.execution_status ||
mapped.rebindUnchanged ||
mapped.rebindConfirmState === 'rejected'
if (bindingChanged) {
await appendTaskEvent(client, task.id, {
eventType: 'binding_status_changed',
actorType,
fromBindingStatus: task.binding_status,
toBindingStatus: mapped.status,
fromExecutionStatus: task.execution_status,
toExecutionStatus: executionStatus,
detail: {
gameAccount: mapped.bindGameAccount,
gameRole: mapped.bindGameRole,
gameRoleId: mapped.bindGameRoleId,
gameChannel: mapped.bindGameChannel,
verdict: comparison.verdict,
rebindRequested: mapped.rebindRequested,
rebindUnchanged: mapped.rebindUnchanged,
rebindConfirmState: mapped.rebindConfirmState,
rebindConfirmMessage: mapped.rebindConfirmMessage,
bindConfirmState: mapped.bindConfirmState,
bindConfirmMessage: mapped.bindConfirmMessage,
rebindCooldownDays: mapped.rebindCooldownDays,
nextRebindAt: mapped.nextRebindAt,
changeBindDay: mapped.platformChangeBindDay,
changeBindTime: mapped.platformChangeBindTime,
message: mapped.message,
},
})
}
})
return {
status: mapped.status,
@@ -1916,6 +1928,78 @@ export async function getAdminSemiAutoTask(taskIdInput: unknown) {
}
}
type SemiAutoTaskEventRow = {
id: number
event_type: string
actor_type: string
actor_id: string
from_login_status: string | null
to_login_status: string | null
from_binding_status: string | null
to_binding_status: string | null
from_execution_status: string | null
to_execution_status: string | null
detail_json: Record<string, unknown>
created_at: string
}
/**
* 运营端「历史」:任务状态流转事件 + 全链路报文(本系统入站 + 外部平台出站)。
* 报文只读,不做任何写操作;Cookie / Token 已在落库前脱敏。
*/
export async function getAdminSemiAutoTaskHistory(
taskIdInput: unknown,
input: Record<string, unknown> = {},
) {
const task = await loadTask(normalizeId(taskIdInput))
const eventCount = await query<{ total: number }>(
`SELECT COUNT(*)::int AS total FROM semi_auto_task_events WHERE task_id = $1`,
[task.id],
)
const events = await query<SemiAutoTaskEventRow>(
`SELECT * FROM (
SELECT id, event_type, actor_type, actor_id,
from_login_status, to_login_status,
from_binding_status, to_binding_status,
from_execution_status, to_execution_status,
detail_json, created_at
FROM semi_auto_task_events
WHERE task_id = $1
ORDER BY id DESC
LIMIT 500
) recent
ORDER BY id ASC`,
[task.id],
)
const traces = await querySemiAutoTraces(task.id, {
page: Number(input.page) || 1,
pageSize: Number(input.pageSize) || 50,
channel: String(input.channel || '').trim(),
status: String(input.status || '').trim(),
requestId: String(input.requestId || '').trim(),
keyword: String(input.keyword || '').trim(),
})
return {
task: mapTask(task),
events: events.rows.map((event) => ({
id: Number(event.id),
eventType: event.event_type,
actorType: event.actor_type,
actorId: event.actor_id,
fromLoginStatus: event.from_login_status,
toLoginStatus: event.to_login_status,
fromBindingStatus: event.from_binding_status,
toBindingStatus: event.to_binding_status,
fromExecutionStatus: event.from_execution_status,
toExecutionStatus: event.to_execution_status,
detail: event.detail_json || {},
createdAt: event.created_at,
})),
eventTotal: Number(eventCount.rows[0]?.total || 0),
traces,
}
}
export async function exportAdminSemiAutoCredential(taskIdInput: unknown) {
const task = await loadTask(normalizeId(taskIdInput))
if (!task.credential_id) {
@@ -0,0 +1,326 @@
import { AsyncLocalStorage } from 'node:async_hooks'
import crypto from 'node:crypto'
import { query } from '../../db/client.js'
import { logWarn } from '../../utils/logger.js'
/** 报文保留天数:180 天,由 startSemiAutoTraceCleanup 定时清理。 */
export const SEMI_AUTO_TRACE_RETENTION_DAYS = 180
const MAX_BODY_CHARS = 32_000
const MAX_REDACT_DEPTH = 6
const FINGERPRINT_LIMIT = 5_000
export type SemiAutoTraceChannel =
| 'customer_api'
| 'admin_api'
| 'huya_wup'
| 'huya_http'
| 'external_connector'
export type SemiAutoTraceContext = {
requestId: string
taskId?: number
orderNo?: string
source?: string
}
export type SemiAutoTraceEntry = {
taskId?: number
orderNo?: string
requestId?: string
direction: 'inbound' | 'outbound'
channel: SemiAutoTraceChannel | string
action: string
status?: 'ok' | 'error'
httpStatus?: number
durationMs?: number
requestSummary?: Record<string, unknown>
requestBody?: unknown
responseSummary?: Record<string, unknown>
responseBody?: unknown
errorMessage?: string
/** 写操作/关键读:无条件记录(轮询类不要传)。 */
always?: boolean
/** 轮询类请求的状态指纹:与上次相同则不记录。 */
fingerprint?: string | undefined
}
const traceStorage = new AsyncLocalStorage<SemiAutoTraceContext>()
const lastFingerprints = new Map<string, string>()
/** Cookie / Token / 密钥字段:一律不落库。 */
const SENSITIVE_KEYS = new Set([
'cookie',
'set-cookie',
'authorization',
'proxyauthorization',
'token',
'accesstoken',
'access_token',
'refreshtoken',
'refresh_token',
'biztoken',
'udb_biztoken',
'password',
'passwd',
'secret',
'apikey',
'api_key',
'x-semi-auto-key',
'sig',
'qrcodetoken',
'qrcode_token',
'qrcontent',
'qr_content',
'qrimage',
'qr_image',
'query_string',
'smscode',
'sms_code',
'sessionid',
'session_id',
'baseinfo',
'cookies',
'cookie_header',
'cookieheader',
'ticket',
'credential_payload_json',
])
export function runWithSemiAutoTrace<T>(context: SemiAutoTraceContext, fn: () => T): T {
return traceStorage.run(context, fn)
}
export function currentSemiAutoTrace(): SemiAutoTraceContext | undefined {
return traceStorage.getStore()
}
function maskValue(value: unknown): unknown {
if (value === null || value === undefined) return value
if (typeof value !== 'string') return '******'
return value.length > 0 ? '******' : ''
}
function normalizeKey(key: string): string {
return key.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase()
}
/** 深度脱敏:Cookie / Token / 密钥字段直接替换为 ******。 */
export function redactTraceValue(value: unknown, depth = 0): unknown {
if (depth > MAX_REDACT_DEPTH) return '[max-depth]'
if (value === null || value === undefined) return value
if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
return value
}
if (Array.isArray(value)) {
return value.slice(0, 50).map((item) => redactTraceValue(item, depth + 1))
}
if (typeof value === 'object') {
const source = value as Record<string, unknown>
const result: Record<string, unknown> = {}
for (const [key, current] of Object.entries(source)) {
result[key] = SENSITIVE_KEYS.has(normalizeKey(key))
? maskValue(current)
: redactTraceValue(current, depth + 1)
}
return result
}
return String(value)
}
export function stringifyTraceBody(value: unknown): string {
if (value === undefined || value === null) return ''
if (typeof value === 'string') {
return value.length > MAX_BODY_CHARS
? `${value.slice(0, MAX_BODY_CHARS)}\n...[truncated]`
: value
}
try {
const text = JSON.stringify(redactTraceValue(value), null, 2)
return text.length > MAX_BODY_CHARS ? `${text.slice(0, MAX_BODY_CHARS)}\n...[truncated]` : text
} catch {
return String(value).slice(0, MAX_BODY_CHARS)
}
}
function fingerprintKey(entry: SemiAutoTraceEntry): string {
return `${entry.taskId || 0}|${entry.channel}|${entry.action}`
}
/**
* 采样:写操作与关键读一律记录;轮询类只在状态变化或失败时记录,避免每 2 秒一条。
*/
export function shouldRecordTrace(entry: SemiAutoTraceEntry): boolean {
if (entry.always) return true
if ((entry.status || 'ok') === 'error') return true
const fingerprint = String(entry.fingerprint || '')
if (!fingerprint) return true
const key = fingerprintKey(entry)
const previous = lastFingerprints.get(key)
if (previous === fingerprint) return false
lastFingerprints.set(key, fingerprint)
if (lastFingerprints.size > FINGERPRINT_LIMIT) lastFingerprints.clear()
return true
}
/** 记录一条报文:异步落库,失败只记日志,绝不阻断主流程。 */
export function recordSemiAutoTrace(entry: SemiAutoTraceEntry): void {
const context = currentSemiAutoTrace()
const taskId = Number(entry.taskId || context?.taskId || 0)
if (!Number.isFinite(taskId) || taskId <= 0) return
if (!shouldRecordTrace(entry)) return
const orderNo = entry.orderNo || context?.orderNo || ''
const requestId = entry.requestId || context?.requestId || ''
const status = entry.status === 'error' ? 'error' : 'ok'
const requestBody = stringifyTraceBody(entry.requestBody)
const responseBody = stringifyTraceBody(entry.responseBody)
void query(
`INSERT INTO semi_auto_trace_logs (
task_id, order_no, request_id, direction, channel, action, status,
http_status, duration_ms, request_summary, request_body,
response_summary, response_body, error_message, created_at
) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10::jsonb,$11,$12::jsonb,$13,$14,NOW())`,
[
taskId,
orderNo,
requestId,
entry.direction,
entry.channel,
entry.action,
status,
entry.httpStatus ?? null,
entry.durationMs ?? null,
JSON.stringify(redactTraceValue(entry.requestSummary || {})),
requestBody,
JSON.stringify(redactTraceValue(entry.responseSummary || {})),
responseBody,
String(entry.errorMessage || ''),
],
).catch((error) => {
logWarn('semi-auto/trace', '写入报文失败', {
taskId,
action: entry.action,
error: error instanceof Error ? error.message : String(error),
})
})
}
/** 供调用方快速生成一个轮询指纹。 */
export function traceFingerprint(value: unknown): string {
if (value === null || value === undefined) return ''
let text = ''
if (typeof value === 'string') {
text = value
} else {
try {
text = JSON.stringify(value)
} catch {
text = String(value)
}
}
return crypto.createHash('sha1').update(text).digest('hex')
}
export type SemiAutoTraceQuery = {
page?: number
pageSize?: number
channel?: string
status?: string
requestId?: string
keyword?: string
}
export async function querySemiAutoTraces(taskId: number, input: SemiAutoTraceQuery = {}) {
const page = Math.max(1, Math.floor(Number(input.page) || 1))
const pageSize = Math.min(200, Math.max(1, Math.floor(Number(input.pageSize) || 50)))
const conditions = ['task_id = $1']
const params: unknown[] = [taskId]
if (input.channel) {
params.push(String(input.channel))
conditions.push(`channel = $${params.length}`)
}
if (input.status) {
params.push(String(input.status))
conditions.push(`status = $${params.length}`)
}
if (input.requestId) {
params.push(String(input.requestId))
conditions.push(`request_id = $${params.length}`)
}
if (input.keyword) {
params.push(`%${String(input.keyword).trim()}%`)
conditions.push(
`(action ILIKE $${params.length} OR request_body ILIKE $${params.length} OR response_body ILIKE $${params.length})`,
)
}
const where = conditions.join(' AND ')
const count = await query(
`SELECT COUNT(*)::int AS total FROM semi_auto_trace_logs WHERE ${where}`,
params,
)
const rows = await query(
`SELECT id, order_no, request_id, direction, channel, action, status,
http_status, duration_ms, request_summary, request_body,
response_summary, response_body, error_message, created_at
FROM semi_auto_trace_logs
WHERE ${where}
ORDER BY id DESC
LIMIT $${params.length + 1} OFFSET $${params.length + 2}`,
[...params, pageSize, (page - 1) * pageSize],
)
const summary = await query(
`SELECT channel, status, COUNT(*)::int AS total
FROM semi_auto_trace_logs
WHERE task_id = $1
GROUP BY channel, status`,
[taskId],
)
return {
pagination: { page, pageSize, total: Number(count.rows[0]?.total || 0) },
summary: summary.rows,
items: rows.rows.map((row) => ({
id: Number(row.id),
orderNo: row.order_no,
requestId: row.request_id,
direction: row.direction,
channel: row.channel,
action: row.action,
status: row.status,
httpStatus: row.http_status,
durationMs: row.duration_ms,
requestSummary: row.request_summary || {},
requestBody: row.request_body || '',
responseSummary: row.response_summary || {},
responseBody: row.response_body || '',
errorMessage: row.error_message || '',
createdAt: row.created_at,
})),
}
}
export async function cleanupSemiAutoTraces(retentionDays = SEMI_AUTO_TRACE_RETENTION_DAYS) {
const days = Math.max(1, Math.floor(Number(retentionDays) || SEMI_AUTO_TRACE_RETENTION_DAYS))
const result = await query(
`DELETE FROM semi_auto_trace_logs WHERE created_at < NOW() - ($1 || ' days')::interval`,
[String(days)],
)
return result.rowCount || 0
}
let cleanupStarted = false
/** 启动时清一次,之后每 6 小时清理超过保留期的报文。 */
export function startSemiAutoTraceCleanup(): void {
if (cleanupStarted) return
cleanupStarted = true
const run = () => {
void cleanupSemiAutoTraces().catch((error) => {
logWarn('semi-auto/trace', '清理历史报文失败', {
error: error instanceof Error ? error.message : String(error),
})
})
}
run()
const timer = setInterval(run, 6 * 60 * 60 * 1000)
timer.unref?.()
}