feat(express/waybill): 新增更新轨迹按钮与运单轨迹标签页

- 接入 waybill.warehouse.updateTrace / updateTraceTaskProgress:工具栏「更新轨迹」支持更新选中与更新全部(当前筛选,直接传 where,上限 5000)
- 异步任务进度弹窗轮询 updateTraceTaskProgress,完成后刷新列表
- 新增 waybill.warehouse.getTrace 接口封装,底部明细区新增「轨迹」标签页,按运单号展示已落库轨迹(时间线、最新高亮、支持刷新)
- 抽取通用的异步任务响应/进度解析(parseTaskPayload / normalizeTaskProgress),兼容 current_count 进度字段
- 选中行时先展示行数据,避免轨迹/明细短暂显示上一条运单

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
liufumingren 2026-11-11 20:22:50 +08:00
parent 6838d69788
commit b2d53e3b72
4 changed files with 566 additions and 10 deletions

View File

@ -247,6 +247,124 @@ export function waybillWarehouseUpdateReceiveTaskProgress(
} as any)
}
// ============ waybill.warehouse.updateTrace ============
/** waybill.warehouse.updateTrace 请求参数(waybillCodes 与 where 二选一,同时传入时 waybillCodes 优先) */
export type WaybillWarehouseUpdateTraceParams = {
/** 运单号列表(字符串数组),优先于 where */
waybillCodes?: string[]
/** waybillCodes 的下划线别名,二者取其一 */
waybill_codes?: string[]
/**
* 与 waybill.warehouse.list 一致的筛选条件(不含分页/排序)。
* 服务端先解析命中的运单号再执行;超过 5000 条时直接失败,不做截断。
*/
where?: WaybillWarehouseListWhere
}
/**
* waybill.warehouse.updateTrace:批量更新运单物流轨迹-仓库侧
*
* 调用外部接口 waybill.getTrace 查询轨迹(单批最多 10 单,超出自动切批),
* 结果按 (express_id, op_time, scan_type) 幂等写入 wms_order_express_trace。
* 异步任务模式:返回任务受理信息(任务 ID 前缀 waybill_trace_),进度用 updateTraceTaskProgress 查询。
* 仓库未配置承接该回调方法的 API 应用时直接失败,不创建任务。
*/
export function waybillWarehouseUpdateTrace(
data: WaybillWarehouseUpdateTraceParams
): Promise<any> {
return request({
url: '/system',
method: 'post',
params: {
method: 'waybill.warehouse.updateTrace',
v,
timestamp: Date.now()
},
data,
isSystemApi: true
} as any)
}
// ============ waybill.warehouse.updateTraceTaskProgress ============
/** waybill.warehouse.updateTraceTaskProgress 请求参数 */
export type WaybillWarehouseUpdateTraceTaskProgressParams = {
/** 异步任务ID(前缀 waybill_trace_)。与 taskId 二选一 */
task_id?: string
/** 异步任务ID(别名,优先使用)。至少传入 taskId 或 task_id 之一 */
taskId?: string
}
/** waybill.warehouse.updateTraceTaskProgress:运单物流轨迹更新进度查询-仓库侧 */
export function waybillWarehouseUpdateTraceTaskProgress(
data: WaybillWarehouseUpdateTraceTaskProgressParams
): Promise<any> {
return request({
url: '/system',
method: 'post',
params: {
method: 'waybill.warehouse.updateTraceTaskProgress',
v,
timestamp: Date.now()
},
data,
isSystemApi: true
} as any)
}
// ============ waybill.warehouse.getTrace ============
/** waybill.warehouse.getTrace 请求参数 */
export type WaybillWarehouseGetTraceParams = {
/** 运单号(必填) */
waybillCode?: string
/** waybillCode 的下划线别名 */
waybill_code?: string
}
/** 单条物流轨迹 */
export type WaybillWarehouseTraceItem = {
id?: number
express_id?: number
order_id?: number
/** 节点时间,格式 YYYY-MM-DD HH:mm:ss */
op_time?: string
/** 外部业务码(幂等键之一) */
out_biz_code?: string
/** 轨迹描述文案 */
memo?: string
/** 操作网点城市 */
op_org_city_name?: string
/** 重量(部分快递返回) */
weight?: number
/** 扫描类型 */
scan_type?: string
raw_data?: Record<string, any> | null
}
/**
* waybill.warehouse.getTrace:查询单个运单的全部物流轨迹-仓库侧
*
* 只读接口:仅查 wms_order_express_trace 中 updateTrace 已落库的数据,不调外部接口。
* 不分页,按 op_time DESC, id DESC 返回;无数据时返回空列表(不报错)。
*/
export function waybillWarehouseGetTrace(
data: WaybillWarehouseGetTraceParams
): Promise<any> {
return request({
url: '/system',
method: 'post',
params: {
method: 'waybill.warehouse.getTrace',
v,
timestamp: Date.now()
},
data,
isSystemApi: true
} as any)
}
// ============ 模块导出 ============
export const waybillWarehouseModule = {
@ -255,5 +373,8 @@ export const waybillWarehouseModule = {
export: waybillWarehouseExport,
exportTaskProgress: waybillWarehouseExportTaskProgress,
updateReceive: waybillWarehouseUpdateReceive,
updateReceiveTaskProgress: waybillWarehouseUpdateReceiveTaskProgress
updateReceiveTaskProgress: waybillWarehouseUpdateReceiveTaskProgress,
updateTrace: waybillWarehouseUpdateTrace,
updateTraceTaskProgress: waybillWarehouseUpdateTraceTaskProgress,
getTrace: waybillWarehouseGetTrace
}

View File

@ -0,0 +1,232 @@
<!--
TracePanel — 运单物流轨迹面板
数据来源:waybill.warehouse.getTrace(只读,返回已落库的全部轨迹,不分页,按操作时间倒序)。
取数入参:当前行的运单号(waybill_code / waybillCode)。
-->
<template>
<div class="trace-panel">
<div class="section-title">
<span>物流轨迹</span>
<span v-if="total > 0" class="trace-count">共 {{ total }} 条</span>
<el-button
class="trace-refresh"
size="small"
link
type="primary"
:loading="loading"
@click="refresh"
>
刷新
</el-button>
</div>
<div v-if="loading" class="empty-tip">加载中…</div>
<div v-else-if="error" class="empty-tip">{{ error }}</div>
<div v-else-if="!traceList.length" class="empty-tip">暂无轨迹数据,可先点击「更新轨迹」拉取</div>
<div v-else class="trace-timeline">
<div
v-for="(item, index) in traceList"
:key="item.id ?? `${item.op_time}-${index}`"
class="trace-item"
:class="{ 'is-latest': index === 0 }"
>
<div class="trace-dot" />
<div class="trace-content">
<div class="trace-memo">{{ item.memo || item.out_biz_code || '—' }}</div>
<div class="trace-meta">
<span v-if="item.scan_type" class="trace-tag">{{ item.scan_type }}</span>
<span v-if="item.op_org_city_name" class="trace-city">{{ item.op_org_city_name }}</span>
<span class="trace-time">{{ item.op_time || '—' }}</span>
</div>
</div>
</div>
</div>
</div>
</template>
<script setup lang="ts">
import { ref, watch } from 'vue'
import type { WaybillWarehouseTraceItem } from '@/api/waybill.warehouse'
defineOptions({ name: 'TracePanel', inheritAttrs: false })
const props = defineProps<{
/** 当前选中行数据(取其中的运单号查询轨迹) */
row: Record<string, any> | null
/** 轨迹查询接口(waybill.warehouse.getTrace) */
apiMethod?: (...args: any[]) => Promise<any>
}>()
const traceList = ref<WaybillWarehouseTraceItem[]>([])
const total = ref(0)
const loading = ref(false)
const error = ref('')
/** 请求序号:行切换较快时丢弃过期响应 */
let requestSeq = 0
function resolveWaybillCode(row: Record<string, any> | null): string {
return String(row?.waybill_code ?? row?.waybillCode ?? '').trim()
}
async function loadTraces(row: Record<string, any> | null) {
const seq = ++requestSeq
traceList.value = []
total.value = 0
error.value = ''
if (!row) return
const waybillCode = resolveWaybillCode(row)
if (!waybillCode) {
error.value = '缺少运单号,无法查询轨迹'
return
}
const apiMethod = props.apiMethod
if (!apiMethod) {
error.value = '轨迹接口未配置'
return
}
loading.value = true
try {
const res = await apiMethod({ waybillCode })
if (seq !== requestSeq) return
if (res && (res.code === 1 || res.code === 200)) {
const data = res.data ?? res
const list = Array.isArray(data?.list) ? data.list : []
traceList.value = list
total.value = Number(data?.total ?? list.length) || list.length
} else {
error.value = res?.message || '获取轨迹失败'
}
} catch (e: any) {
if (seq !== requestSeq) return
error.value = e?.message || '获取轨迹失败'
} finally {
if (seq === requestSeq) loading.value = false
}
}
watch(
() => resolveWaybillCode(props.row) || null,
() => {
void loadTraces(props.row)
},
{ immediate: true }
)
function refresh() {
void loadTraces(props.row)
}
</script>
<style lang="scss" scoped>
.trace-panel {
height: 100%;
overflow-y: auto;
padding: 6px 10px 8px;
box-sizing: border-box;
.section-title {
display: flex;
align-items: center;
gap: 8px;
margin-bottom: 10px;
padding-left: 8px;
border-left: 3px solid #409eff;
line-height: 1.4;
font-size: 14px;
font-weight: 600;
color: #303133;
}
.trace-count {
font-weight: 400;
font-size: 12px;
color: #909399;
}
.trace-refresh {
margin-left: auto;
font-size: 12px;
font-weight: 400;
}
.empty-tip {
padding: 40px 0;
text-align: center;
font-size: 13px;
color: #909399;
}
}
.trace-timeline {
position: relative;
padding-left: 6px;
.trace-item {
position: relative;
padding: 0 0 14px 18px;
border-left: 1px solid #e4e7ed;
&:last-child {
border-left-color: transparent;
padding-bottom: 0;
}
}
.trace-dot {
position: absolute;
left: -4px;
top: 4px;
width: 7px;
height: 7px;
border-radius: 50%;
background: #c0c4cc;
}
.trace-item.is-latest {
.trace-dot {
background: #409eff;
box-shadow: 0 0 0 3px rgba(64, 158, 255, 0.15);
}
.trace-memo {
color: #303133;
font-weight: 600;
}
}
.trace-memo {
font-size: 13px;
line-height: 1.5;
color: #606266;
word-break: break-all;
}
.trace-meta {
display: flex;
flex-wrap: wrap;
align-items: center;
gap: 8px;
margin-top: 4px;
font-size: 12px;
color: #909399;
}
.trace-tag {
padding: 0 6px;
border-radius: 3px;
background: #f0f2f5;
color: #606266;
line-height: 18px;
}
.trace-time {
font-variant-numeric: tabular-nums;
}
}
</style>

View File

@ -8,17 +8,24 @@
* - waybillWarehouseExport → waybill.warehouse.export 运单导出
* - waybillWarehouseUpdateReceive → waybill.warehouse.updateReceive 批量更新揽收
* - waybillWarehouseUpdateReceiveTaskProgress → waybill.warehouse.updateReceiveTaskProgress 揽收更新进度
* - waybillWarehouseUpdateTrace → waybill.warehouse.updateTrace 批量更新物流轨迹
* - waybillWarehouseUpdateTraceTaskProgress → waybill.warehouse.updateTraceTaskProgress 轨迹更新进度
* - waybillWarehouseGetTrace → waybill.warehouse.getTrace 单运单物流轨迹
*/
import type { Component } from 'vue'
import DetailPanel from './components/DetailPanel.vue'
import LogPanel from './components/LogPanel.vue'
import TracePanel from './components/TracePanel.vue'
import {
waybillWarehouseList,
waybillWarehouseExport,
waybillWarehouseExportTaskProgress,
waybillWarehouseUpdateReceive,
waybillWarehouseUpdateReceiveTaskProgress,
waybillWarehouseUpdateTrace,
waybillWarehouseUpdateTraceTaskProgress,
waybillWarehouseGetTrace,
} from '@/api/waybill.warehouse'
// ============================================================
@ -44,7 +51,8 @@ export const LIST_REQUEST_TIMEOUT = 5 * 60 * 1000
// ============================================================
export const COMPONENT_REGISTRY: Record<string, Component> = {
DetailPanel,
LogPanel
LogPanel,
TracePanel
}
// ============================================================
@ -575,6 +583,12 @@ export interface TabPageApiConfig {
updateReceive?: ApiMethod
/** 揽收状态更新任务进度查询 */
updateReceiveProgress?: ApiMethod
/** 批量更新运单物流轨迹(异步任务) */
updateTrace?: ApiMethod
/** 物流轨迹更新任务进度查询 */
updateTraceProgress?: ApiMethod
/** 单个运单的物流轨迹查询(明细面板「轨迹」标签页) */
trace?: ApiMethod
scanBoxOptions?: Record<string, ApiMethod>
toolbar?: Record<string, ApiMethod>
parseListResponse?: (res: any) => { list: any[]; total: number }
@ -902,6 +916,22 @@ export const TOOLBAR_BUTTONS: Record<string, ToolbarButtonConfig> = {
{ label: '更新全部(当前筛选)', action: 'handleUpdateReceiveAll', divided: true }
]
},
updateTrace: {
key: 'updateTrace',
label: '更新轨迹',
category: 'function',
size: 'small',
type: 'warning',
plain: true,
loadingKey: 'traceLoading',
// 两种范围:选中 / 当前筛选全部;未勾选时的提示由 handleUpdateTraceSelected 内部处理。
action: 'handleUpdateTraceSelected',
buttonType: 'dropdown',
dropdownOptions: [
{ label: '更新选中', action: 'handleUpdateTraceSelected' },
{ label: '更新全部(当前筛选)', action: 'handleUpdateTraceAll', divided: true }
]
},
}
export function getTabToolbarButtons(tabName: string): ToolbarButtonConfig[] {
@ -969,7 +999,8 @@ export const tabPages: TabPageRawConfig[] = [
showSelection: true
},
detailTabs: [
{ name: 'detail', label: '运单明细', componentKey: 'DetailPanel' }
{ name: 'detail', label: '运单明细', componentKey: 'DetailPanel' },
{ name: 'trace', label: '轨迹', componentKey: 'TracePanel' }
],
detailSections: [
{
@ -1032,6 +1063,9 @@ export const tabPages: TabPageRawConfig[] = [
exportProgress: waybillWarehouseExportTaskProgress as ApiMethod,
updateReceive: waybillWarehouseUpdateReceive as ApiMethod,
updateReceiveProgress: waybillWarehouseUpdateReceiveTaskProgress as ApiMethod,
updateTrace: waybillWarehouseUpdateTrace as ApiMethod,
updateTraceProgress: waybillWarehouseUpdateTraceTaskProgress as ApiMethod,
trace: waybillWarehouseGetTrace as ApiMethod,
parseListResponse(res: any) {
const data = res?.data ?? res
return {

View File

@ -263,6 +263,20 @@
:error-text="receiveProgressState.error"
@close="closeReceiveProgress"
/>
<!-- 批量更新物流轨迹(waybill.warehouse.updateTrace 异步任务) -->
<TaskProgressDialog
v-if="traceProgressVisible"
:visible="traceProgressVisible"
title="更新物流轨迹"
:polling="traceProgressPolling"
:task-id="traceProgressState.taskId"
:progress-percent="traceProgressState.progress"
:status-label="traceProgressStatusLabel"
:error-text="traceProgressState.error"
:result-text="traceProgressPolling ? '' : traceProgressState.message"
@close="closeTraceProgress"
/>
</div>
</template>
@ -434,6 +448,9 @@ const currentDetailTabApiMethod = computed(() => {
case 'LogPanel':
componentCfg = cfg.api.log
break
case 'TracePanel':
componentCfg = cfg.api.trace
break
default:
return undefined
}
@ -473,7 +490,8 @@ const buttonDisabledMap = computed<Record<string, boolean>>(() => ({
const buttonLoadingMap = computed<Record<string, boolean>>(() => ({
loading: loading.value,
exportLoading: exportLoading.value,
receiveLoading: receiveLoading.value
receiveLoading: receiveLoading.value,
traceLoading: traceLoading.value
}))
const buttonLabelMap = computed<Record<string, string>>(() => ({
@ -579,7 +597,9 @@ const toolbarActionMap: Record<string, () => void> = {
handleExportAll: () => { void handleExportAll() },
openTransferByWaybillsDialog: () => { openTransferByWaybillsDialog() },
handleUpdateReceiveSelected: () => { void handleUpdateReceiveSelected() },
handleUpdateReceiveAll: () => { void handleUpdateReceiveAll() }
handleUpdateReceiveAll: () => { void handleUpdateReceiveAll() },
handleUpdateTraceSelected: () => { void handleUpdateTraceSelected() },
handleUpdateTraceAll: () => { void handleUpdateTraceAll() }
}
function handleToolbarButtonClick(action: string) {
@ -758,7 +778,7 @@ const RECEIVE_ALL_MAX_PAGES = 1000
const RECEIVE_ALL_MAX_CODES = 100000
/** 解析异步任务响应体(兼容 data / data.data 嵌套) */
function parseReceiveTaskPayload(res: any): Record<string, any> {
function parseTaskPayload(res: any): Record<string, any> {
if (!res || typeof res !== 'object') return {}
const root = res as Record<string, any>
const nested = root.data
@ -776,8 +796,8 @@ function parseReceiveTaskPayload(res: any): Record<string, any> {
}
/** 进度接口响应 → useTaskProgress 期望结构(频率字段做兼容归一) */
function normalizeReceiveProgress(res: any) {
const payload = parseReceiveTaskPayload(res)
function normalizeTaskProgress(res: any) {
const payload = parseTaskPayload(res)
const rawStatus = String(payload.status || '').toLowerCase()
// 任务不存在/已过期:按失败处理,避免无意义轮询到超时
const status = rawStatus === 'not_found' ? 'failed' : rawStatus
@ -787,6 +807,8 @@ function normalizeReceiveProgress(res: any) {
payload.processed
?? payload.processed_count
?? payload.processedCount
?? payload.current_count
?? payload.currentCount
?? payload.current
?? payload.done
?? 0
@ -823,7 +845,7 @@ const {
const cfg = currentTabConfig.value
if (!cfg?.api?.updateReceiveProgress) throw new Error('揽收进度接口未配置')
const res = await cfg.api.updateReceiveProgress({ task_id: taskId })
return normalizeReceiveProgress(res)
return normalizeTaskProgress(res)
},
onSuccess: async () => {
ElMessage.success('揽收状态更新完成')
@ -856,7 +878,7 @@ async function submitReceiveTask(waybillCodes: string[]) {
}
const res = await cfg.api.updateReceive({ waybillCodes })
const payload = parseReceiveTaskPayload(res)
const payload = parseTaskPayload(res)
const taskId = String(payload.task_id || payload.taskId || '').trim()
if (!taskId) {
throw new Error(payload.message || res?.message || '揽收状态更新任务提交失败')
@ -1029,6 +1051,151 @@ async function handleUpdateReceiveAll() {
}
}
// ============================================================
// 批量更新物流轨迹(waybill.warehouse.updateTrace)
// ============================================================
/** 提交中(按钮 loading / 防重复提交) */
const traceLoading = ref(false)
/** 服务端按筛选条件解析运单号时的单次上限(超过即失败,不做截断) */
const TRACE_MAX_CODES = 5000
const {
visible: traceProgressVisible,
polling: traceProgressPolling,
state: traceProgressState,
startPolling: startTracePolling,
close: closeTraceProgress
} = useTaskProgress({
interval: 1500,
// 200 次 × 1.5s ≈ 5 分钟上限,超时后提示刷新查看结果
maxAttempts: 200,
pollFn: async (taskId: string) => {
const cfg = currentTabConfig.value
if (!cfg?.api?.updateTraceProgress) throw new Error('轨迹进度接口未配置')
const res = await cfg.api.updateTraceProgress({ task_id: taskId })
return normalizeTaskProgress(res)
},
onSuccess: async () => {
ElMessage.success('物流轨迹更新完成')
upperTableRef.value?.clearSelection?.()
selectedRows.value = []
await loadData()
},
onError: (error: string) => {
ElMessage.error(error || '物流轨迹更新失败')
}
})
const traceProgressStatusLabel = computed(() => {
const map: Record<string, string> = {
submitted: '已提交',
running: '处理中',
success: '已完成',
completed: '已完成',
failed: '失败',
error: '错误'
}
return map[traceProgressState.status] || traceProgressState.status || '—'
})
/** 提交物流轨迹更新任务(运单号 / 筛选条件 二选一) */
async function submitTraceTask(payload: { waybillCodes?: string[]; where?: Record<string, any> }) {
const cfg = currentTabConfig.value
if (!cfg?.api?.updateTrace) {
throw new Error('物流轨迹更新接口未配置')
}
const res = await cfg.api.updateTrace(payload)
const taskPayload = parseTaskPayload(res)
const taskId = String(taskPayload.task_id || taskPayload.taskId || '').trim()
if (!taskId) {
throw new Error(taskPayload.message || res?.message || '物流轨迹更新任务提交失败')
}
const countText = payload.waybillCodes?.length
? `${payload.waybillCodes.length} 个运单`
: '当前筛选条件下的运单'
ElMessage.success(`已提交${countText}的物流轨迹更新任务`)
// 异步任务:不 await,轮询由进度弹窗接管
void startTracePolling(taskId)
}
/** 勾选运单 → 提交物流轨迹更新任务 → 轮询进度 */
async function handleUpdateTraceSelected() {
if (traceLoading.value) return
if (!selectedRows.value.length) {
ElMessage.warning('请先勾选需要更新物流轨迹的运单')
return
}
const waybillCodes = selectedRows.value
.map((row: any) => String(row?.waybill_code ?? row?.waybillCode ?? '').trim())
.filter(Boolean)
if (!waybillCodes.length) {
ElMessage.warning('勾选的运单缺少运单号,无法更新物流轨迹')
return
}
traceLoading.value = true
try {
await submitTraceTask({ waybillCodes })
} catch (e: any) {
ElMessage.error(e?.message || '物流轨迹更新失败')
} finally {
traceLoading.value = false
}
}
/** 按当前筛选条件全部更新(接口直接接收 where,由服务端解析运单号) */
async function handleUpdateTraceAll() {
if (traceLoading.value) return
const conditions = scanBoxRef.value?.getConditions?.() || {}
const where = buildWhereConditions(conditions)
// 没有任何筛选条件时,避免误把整表全部更新
if (!Object.keys(where).length) {
ElMessage.warning('请先在筛选区设置条件(如创建时间)后,再使用「更新全部」')
return
}
if (pagination.total > TRACE_MAX_CODES) {
ElMessage.warning(
`当前筛选命中 ${pagination.total} 条,超过单次更新上限 ${TRACE_MAX_CODES} 条,请缩小筛选范围(如缩小创建时间)`
)
return
}
const totalText = pagination.total > 0
? `当前筛选共 ${pagination.total} 条运单`
: '当前筛选命中的全部运单'
try {
await ElMessageBox.confirm(
`将按当前筛选条件批量更新物流轨迹:${totalText}。任务在后台执行,完成后可重新查询确认。`,
'更新全部物流轨迹',
{
confirmButtonText: '开始更新',
cancelButtonText: '取消',
type: 'warning',
buttonSize: 'small'
}
)
} catch {
return
}
traceLoading.value = true
try {
await submitTraceTask({ where })
} catch (e: any) {
ElMessage.error(e?.message || '更新全部物流轨迹失败')
} finally {
traceLoading.value = false
}
}
// ============================================================
// 明细面板
// ============================================================
@ -1043,6 +1210,8 @@ const handleRowClick = async (row: Record<string, any>) => {
const cfg = currentTabConfig.value
if (!cfg) return
selectedRow.value = row
// 先展示行内数据:避免明细/轨迹面板短暂停留在上一条运单
selectedDetail.value = { ...row }
try {
const detailRes = await waybillWarehouseDetail({