diff --git a/src/api/waybill.warehouse/index.ts b/src/api/waybill.warehouse/index.ts index f9b09275..01b528d0 100644 --- a/src/api/waybill.warehouse/index.ts +++ b/src/api/waybill.warehouse/index.ts @@ -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 { + 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 { + 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 | null +} + +/** + * waybill.warehouse.getTrace:查询单个运单的全部物流轨迹-仓库侧 + * + * 只读接口:仅查 wms_order_express_trace 中 updateTrace 已落库的数据,不调外部接口。 + * 不分页,按 op_time DESC, id DESC 返回;无数据时返回空列表(不报错)。 + */ +export function waybillWarehouseGetTrace( + data: WaybillWarehouseGetTraceParams +): Promise { + 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 } diff --git a/src/views/express/waybill/config/components/TracePanel.vue b/src/views/express/waybill/config/components/TracePanel.vue new file mode 100644 index 00000000..2f5df354 --- /dev/null +++ b/src/views/express/waybill/config/components/TracePanel.vue @@ -0,0 +1,232 @@ + + + + + + diff --git a/src/views/express/waybill/config/template-config.ts b/src/views/express/waybill/config/template-config.ts index 873ece93..c257b54a 100644 --- a/src/views/express/waybill/config/template-config.ts +++ b/src/views/express/waybill/config/template-config.ts @@ -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 = { DetailPanel, - LogPanel + LogPanel, + TracePanel } // ============================================================ @@ -575,6 +583,12 @@ export interface TabPageApiConfig { updateReceive?: ApiMethod /** 揽收状态更新任务进度查询 */ updateReceiveProgress?: ApiMethod + /** 批量更新运单物流轨迹(异步任务) */ + updateTrace?: ApiMethod + /** 物流轨迹更新任务进度查询 */ + updateTraceProgress?: ApiMethod + /** 单个运单的物流轨迹查询(明细面板「轨迹」标签页) */ + trace?: ApiMethod scanBoxOptions?: Record toolbar?: Record parseListResponse?: (res: any) => { list: any[]; total: number } @@ -902,6 +916,22 @@ export const TOOLBAR_BUTTONS: Record = { { 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 { diff --git a/src/views/express/waybill/index.vue b/src/views/express/waybill/index.vue index a17b0f2a..3171249f 100644 --- a/src/views/express/waybill/index.vue +++ b/src/views/express/waybill/index.vue @@ -263,6 +263,20 @@ :error-text="receiveProgressState.error" @close="closeReceiveProgress" /> + + + @@ -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>(() => ({ const buttonLoadingMap = computed>(() => ({ loading: loading.value, exportLoading: exportLoading.value, - receiveLoading: receiveLoading.value + receiveLoading: receiveLoading.value, + traceLoading: traceLoading.value })) const buttonLabelMap = computed>(() => ({ @@ -579,7 +597,9 @@ const toolbarActionMap: Record 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 { +function parseTaskPayload(res: any): Record { if (!res || typeof res !== 'object') return {} const root = res as Record const nested = root.data @@ -776,8 +796,8 @@ function parseReceiveTaskPayload(res: any): Record { } /** 进度接口响应 → 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 = { + submitted: '已提交', + running: '处理中', + success: '已完成', + completed: '已完成', + failed: '失败', + error: '错误' + } + return map[traceProgressState.status] || traceProgressState.status || '—' +}) + +/** 提交物流轨迹更新任务(运单号 / 筛选条件 二选一) */ +async function submitTraceTask(payload: { waybillCodes?: string[]; where?: Record }) { + 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) => { const cfg = currentTabConfig.value if (!cfg) return selectedRow.value = row + // 先展示行内数据:避免明细/轨迹面板短暂停留在上一条运单 + selectedDetail.value = { ...row } try { const detailRes = await waybillWarehouseDetail({