feat(semi-auto): 报文列表展示接口用途说明

This commit is contained in:
2026-11-17 11:16:44 +08:00
parent 136c392f8f
commit 72cca72ae5
3 changed files with 289 additions and 1 deletions
@@ -27,6 +27,7 @@ import type { CSSProperties } from 'react'
import { fetchAdminSemiAutoTaskHistory } from '@/services/admin/semi-auto'
import type { SemiAutoTaskHistoryEvent, SemiAutoTraceItem } from '@/types/admin/semi-auto'
import { formatAdminDateTime } from '@/utils/admin-time'
import { describeSemiAutoTraceAction } from '@/utils/semi-auto-trace-action'
import { useIsMobile } from '@/utils/use-is-mobile'
const { Text } = Typography
@@ -584,6 +585,10 @@ function EventItem({
}
function TraceLabel({ item }: { item: SemiAutoTraceItem }) {
const actionLabel = describeSemiAutoTraceAction({
channel: item.channel,
action: item.action,
})
return (
<Space direction="vertical" size={2} style={{ width: '100%' }}>
<Space size={6} wrap>
@@ -602,6 +607,7 @@ function TraceLabel({ item }: { item: SemiAutoTraceItem }) {
) : null}
<Text type="secondary">{formatAdminDateTime(item.createdAt)}</Text>
</Space>
{actionLabel ? <Text strong>{actionLabel}</Text> : null}
<Text code style={{ whiteSpace: 'break-all' }}>
{item.action}
</Text>
@@ -621,6 +627,10 @@ function TracePayload({
onCopy: (text: string, label: string) => void
onFilterRequest: (requestId: string) => void
}) {
const actionLabel = describeSemiAutoTraceAction({
channel: item.channel,
action: item.action,
})
return (
<Space direction="vertical" size={10} style={{ width: '100%' }}>
<Row gutter={[12, 12]}>
@@ -644,7 +654,7 @@ function TracePayload({
onClick={() =>
onCopy(
[
`动作:${item.action}`,
`动作:${actionLabel ? `${actionLabel} · ` : ''}${item.action}`,
`requestId:${item.requestId}`,
'',
'# 请求',
@@ -0,0 +1,157 @@
/**
* 半自动履约报文动作说明。
*
* trace 的 action 是原始格式:入站为「METHOD 路径」,虎牙出站为 WUP 方法名,
* 外部 Connector 为「METHOD 内部路径」。这里只做展示层映射,不写库、不改变报文内容。
*/
export type SemiAutoTraceActionInput = {
channel: string
action: string
}
/** 虎牙 WUP / livelink 出站动作。 */
const HUYA_RPC_ACTIONS: Record<string, string> = {
'webActUI.checkUserBindGameAccount': '查询虎牙账号已绑定角色',
'webActUI.confirmBindActAccount': '向虎牙提交绑定/换绑',
'webActUI.getLiveLinkParam': '获取绑定二维码参数',
'huyauserui.getUserProfile': '获取虎牙账号资料',
'livelink.getMiniAppQrcode': '生成登录二维码',
'livelink.poolingQrcodeStatus': '轮询扫码状态',
}
/** 旧版 Mock Connector 写入的历史动作,保留中文说明避免露出英文。 */
const LEGACY_ACTIONS: Record<string, string> = {
'mock.sms.send': '发送登录验证码(Mock Connector)',
'mock.sms.login': '验证码登录(Mock Connector)',
}
/** 客户接口尾路径 → 用途。 */
const CUSTOMER_ACTIONS: Record<string, string> = {
open: '客户打开履约页',
profile: '提交客户游戏资料',
'login/start': '发起平台登录',
'login/status': '查询登录状态',
'huya/sms/send': '发送虎牙登录验证码',
'huya/sms/login': '虎牙验证码登录',
'huya/sms/verify': '完成虎牙安全验证',
'binding/start': '开始绑定(查询已绑角色)',
'binding/status': '查询绑定状态',
'binding/rebind': '发起扫码换绑',
'binding/confirm': '确认绑定角色(含换绑)',
'weibo/config': '读取微博登录配置',
'weibo/sms/send': '发送微博登录验证码',
'weibo/sms/login': '微博验证码登录',
'weibo/qrcode': '获取微博登录二维码',
'weibo/qrcode/status': '查询微博扫码状态',
}
/** 运营接口尾路径 → 用途。 */
const ADMIN_ACTIONS: Record<string, string> = {
claim: '客服领取任务',
sync: '手动同步平台状态',
reauthorize: '重新发起客户授权',
'browser-session': '生成浏览器登录票据',
complete: '客服完成履约',
cancel: '取消履约任务',
'credential/export': '导出账号 CK',
history: '读取履约历史',
}
const CUSTOMER_PREFIX = '/api/v1/customer-fulfillment'
const ADMIN_PREFIX = '/api/v1/admin/semi-auto'
const CONNECTOR_PREFIX = '/api/internal/huya-semi-auto'
export function describeSemiAutoTraceAction(input: SemiAutoTraceActionInput): string {
const action = String(input?.action || '').trim()
if (!action) return ''
const channel = String(input?.channel || '').trim()
const named = HUYA_RPC_ACTIONS[action] || LEGACY_ACTIONS[action]
if (named) return named
const { method, path } = splitHttpAction(action)
if (!path) return ''
if (path.startsWith(CUSTOMER_PREFIX) || channel === 'customer_api') {
return describeCustomerAction(path)
}
if (path.startsWith(ADMIN_PREFIX) || channel === 'admin_api') {
return describeAdminAction(method, path)
}
if (path.startsWith(CONNECTOR_PREFIX) || channel === 'external_connector') {
return describeConnectorAction(method, path)
}
return ''
}
function splitHttpAction(action: string): { method: string; path: string } {
const match = /^(GET|POST|PUT|PATCH|DELETE)\s+(\S+)/i.exec(action)
if (!match) return { method: '', path: '' }
return {
method: match[1].toUpperCase(),
path: match[2].split('?')[0].split('#')[0],
}
}
function describeCustomerAction(path: string): string {
const match = /^\/api\/v1\/customer-fulfillment\/[^/]+(?:\/tasks\/[^/]+)?(?:\/(.*))?$/.exec(path)
if (!match) return ''
const tail = (match[1] || '').replace(/\/+$/, '')
if (!tail) return '读取履约任务'
return CUSTOMER_ACTIONS[tail] || ''
}
function describeAdminAction(method: string, path: string): string {
if (path === ADMIN_PREFIX + '/tasks') return '读取履约任务列表'
const taskMatch = /^\/api\/v1\/admin\/semi-auto\/tasks\/[^/]+(?:\/(.*))?$/.exec(path)
if (taskMatch) {
const tail = (taskMatch[1] || '').replace(/\/+$/, '')
if (!tail) {
return method === 'POST' || method === 'PUT' || method === 'PATCH'
? '更新履约任务'
: '读取履约任务详情'
}
return ADMIN_ACTIONS[tail] || ''
}
if (/^\/api\/v1\/admin\/semi-auto\/injections\/[^/]+$/.test(path)) {
return '校验浏览器注入票据'
}
return ''
}
function describeConnectorAction(method: string, path: string): string {
if (!path.startsWith(CONNECTOR_PREFIX)) return ''
const rest = path.slice(CONNECTOR_PREFIX.length).split('/').filter(Boolean)
if (rest.length === 0) return ''
if (rest[0] === 'sessions') {
if (rest.length === 1) return method === 'POST' ? '创建平台登录会话' : ''
if (rest.length === 2) {
if (method === 'DELETE') return '释放平台登录会话'
if (method === 'GET') return '查询登录会话'
return ''
}
if (rest.length === 3) {
if (rest[2] === 'binding') {
return method === 'POST' ? '开始绑定(含换绑)' : '查询绑定状态/快照'
}
if (rest[2] === 'browser-ticket') {
return method === 'DELETE' ? '释放浏览器票据' : '生成浏览器票据'
}
if (rest[2] === 'credential') return '读取平台账号 CK'
return ''
}
if (rest.length === 4 && rest[2] === 'binding' && rest[3] === 'confirm') {
return '确认绑定/换绑'
}
return ''
}
if (rest[0] === 'browser-tickets' && rest.length === 2) return '校验浏览器票据'
if (rest[0] === 'sms') {
if (rest[1] === 'send') return '发送平台登录验证码'
if (rest[1] === 'verify') return '完成平台安全验证'
if (rest[1] === 'login') return '平台验证码登录'
}
return ''
}
@@ -0,0 +1,121 @@
import assert from 'node:assert/strict'
import test from 'node:test'
import { describeSemiAutoTraceAction } from '../src/utils/semi-auto-trace-action.ts'
const label = (channel: string, action: string) => describeSemiAutoTraceAction({ channel, action })
test('客户接口:绑定与登录动作都有中文说明', () => {
assert.equal(
label('customer_api', 'POST /api/v1/customer-fulfillment/MOCKSA1/tasks/51/binding/confirm'),
'确认绑定角色(含换绑)',
)
assert.equal(
label('customer_api', 'GET /api/v1/customer-fulfillment/MOCKSA1/tasks/51/binding/status?x=1'),
'查询绑定状态',
)
assert.equal(
label('customer_api', 'POST /api/v1/customer-fulfillment/MOCKSA1/tasks/51/binding/start'),
'开始绑定(查询已绑角色)',
)
assert.equal(
label('customer_api', 'POST /api/v1/customer-fulfillment/MOCKSA1/tasks/51/profile'),
'提交客户游戏资料',
)
assert.equal(
label('customer_api', 'POST /api/v1/customer-fulfillment/MOCKSA1/tasks/51/open'),
'客户打开履约页',
)
assert.equal(
label('customer_api', 'GET /api/v1/customer-fulfillment/MOCKSA1/tasks/51/login/status'),
'查询登录状态',
)
assert.equal(label('customer_api', 'GET /api/v1/customer-fulfillment/MOCKSA1'), '读取履约任务')
})
test('客户接口:短信与微博动作', () => {
assert.equal(
label('customer_api', 'POST /api/v1/customer-fulfillment/MOCKSA1/tasks/51/huya/sms/send'),
'发送虎牙登录验证码',
)
assert.equal(
label('customer_api', 'POST /api/v1/customer-fulfillment/MOCKSA1/tasks/51/huya/sms/verify'),
'完成虎牙安全验证',
)
assert.equal(
label('customer_api', 'GET /api/v1/customer-fulfillment/MOCKSA1/tasks/51/weibo/qrcode/status'),
'查询微博扫码状态',
)
})
test('运营接口:领取、同步、完成与详情', () => {
assert.equal(label('admin_api', 'POST /api/v1/admin/semi-auto/tasks/39/claim'), '客服领取任务')
assert.equal(label('admin_api', 'POST /api/v1/admin/semi-auto/tasks/39/sync'), '手动同步平台状态')
assert.equal(label('admin_api', 'GET /api/v1/admin/semi-auto/tasks/39'), '读取履约任务详情')
assert.equal(label('admin_api', 'POST /api/v1/admin/semi-auto/tasks/39'), '更新履约任务')
assert.equal(
label('admin_api', 'GET /api/v1/admin/semi-auto/injections/ticket-1'),
'校验浏览器注入票据',
)
})
test('虎牙 WUP 与 livelink 动作', () => {
assert.equal(label('huya_wup', 'webActUI.checkUserBindGameAccount'), '查询虎牙账号已绑定角色')
assert.equal(label('huya_wup', 'webActUI.confirmBindActAccount'), '向虎牙提交绑定/换绑')
assert.equal(label('huya_wup', 'huyauserui.getUserProfile'), '获取虎牙账号资料')
assert.equal(label('huya_http', 'livelink.getMiniAppQrcode'), '生成登录二维码')
assert.equal(label('huya_http', 'livelink.poolingQrcodeStatus'), '轮询扫码状态')
})
test('外部 Connector:会话、绑定与票据', () => {
const sessionId = '32aabcb6-27af-420b-b223-a47db63861bf'
assert.equal(
label('external_connector', 'POST /api/internal/huya-semi-auto/sessions'),
'创建平台登录会话',
)
assert.equal(
label('external_connector', `POST /api/internal/huya-semi-auto/sessions/${sessionId}/binding`),
'开始绑定(含换绑)',
)
assert.equal(
label('external_connector', `GET /api/internal/huya-semi-auto/sessions/${sessionId}/binding`),
'查询绑定状态/快照',
)
assert.equal(
label(
'external_connector',
`POST /api/internal/huya-semi-auto/sessions/${sessionId}/binding/confirm`,
),
'确认绑定/换绑',
)
assert.equal(
label('external_connector', 'GET /api/internal/huya-semi-auto/browser-tickets/ticket-1'),
'校验浏览器票据',
)
assert.equal(
label('external_connector', 'POST /api/internal/huya-semi-auto/sms/login'),
'平台验证码登录',
)
})
test('未知动作与空值不展示噪音', () => {
assert.equal(label('customer_api', 'POST /api/v1/customer-fulfillment/X/tasks/1/unknown'), '')
assert.equal(label('huya_wup', 'some.unknown.method'), '')
assert.equal(label('external_connector', 'GET /api/internal/huya-semi-auto/unknown'), '')
assert.equal(label('', ''), '')
assert.equal(label('customer_api', 'POST /api/v1/other/endpoint'), '')
})
test('渠道缺失时按路径兜底识别', () => {
assert.equal(
label('', 'POST /api/v1/customer-fulfillment/MOCKSA1/tasks/51/binding/rebind'),
'发起扫码换绑',
)
assert.equal(label('', 'POST /api/v1/admin/semi-auto/tasks/39/cancel'), '取消履约任务')
assert.equal(label('', 'DELETE /api/internal/huya-semi-auto/sessions/abc'), '释放平台登录会话')
})
test('历史 Mock 动作保留中文说明', () => {
assert.equal(label('external_connector', 'mock.sms.send'), '发送登录验证码(Mock Connector)')
assert.equal(label('external_connector', 'mock.sms.login'), '验证码登录(Mock Connector)')
})