From 1964021d50452847851ab96a811cd795a7253b65 Mon Sep 17 00:00:00 2001 From: liufumingren Date: Wed, 11 Nov 2026 20:05:22 +0800 Subject: [PATCH] =?UTF-8?q?feat(waybill):=20=E6=96=B0=E5=A2=9E=20waybill.w?= =?UTF-8?q?arehouse.getTrace=20=E8=BF=90=E5=8D=95=E8=BD=A8=E8=BF=B9?= =?UTF-8?q?=E6=9F=A5=E8=AF=A2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 按运单号一次返回该运单全部物流轨迹(不分页),按 op_time DESC, id DESC 排序 - 只读本地 wms_order_express_trace,不调外部接口、不落库 - 查询固定带 warehouse_id = ctx.user.store_id,跨仓不可见 - 无数据返回 success + total=0 + list=[];运单号必填(兼容 waybill_code 别名) - op_time 统一格式化为 YYYY-MM-DD HH:mm:ss - 文档:methods/system.json(0.3.326)、变更记录、设计文档接口清单与 3.9 节 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../systemMethods/waybill/warehouse.js | 38 ++++- app/service/systems/waybill.js | 69 ++++++++ database/designs/waybill-module-design.md | 40 ++++- methods/changes/system.json | 16 ++ methods/system.json | 156 +++++++++++++++++- 5 files changed, 313 insertions(+), 6 deletions(-) diff --git a/app/service/systemMethods/waybill/warehouse.js b/app/service/systemMethods/waybill/warehouse.js index 7794dd4..e0ed92a 100644 --- a/app/service/systemMethods/waybill/warehouse.js +++ b/app/service/systemMethods/waybill/warehouse.js @@ -29,9 +29,9 @@ class WaybillWarehouseService extends MainService { constructor(ctx) { super(ctx); const _noNeedLogin = ''; - const _noNeedRight = 'list,detail,export,exportTaskProgress,updateReceive,updateReceiveTaskProgress,updateTrace,updateTraceTaskProgress'; + const _noNeedRight = 'list,detail,export,exportTaskProgress,updateReceive,updateReceiveTaskProgress,updateTrace,updateTraceTaskProgress,getTrace'; const _noNeedLog = ''; - const _noNeedAuth = 'list,detail,export,exportTaskProgress,updateReceive,updateReceiveTaskProgress,updateTrace,updateTraceTaskProgress'; + const _noNeedAuth = 'list,detail,export,exportTaskProgress,updateReceive,updateReceiveTaskProgress,updateTrace,updateTraceTaskProgress,getTrace'; this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth); } @@ -845,6 +845,40 @@ class WaybillWarehouseService extends MainService { async getTraceTaskProgress(taskId = '') { return await this.getTaskProgress(taskId, WAYBILL_TRACE_TASK_CACHE_KEY_PREFIX); } + + /** + * 查询单个运单的全部物流轨迹(仓库侧)。 + * + * 一次返回该运单号下的所有轨迹(不分页),按操作时间倒序排列(最新的在前)。 + * 仅查当前仓库的数据(warehouse_id 隔离);运单号不存在或该仓库无轨迹时返回空列表。 + * + * @param {Object} data 请求参数。 + * @param {string} [data.waybillCode] 运单号(兼容 waybill_code)。 + * @return {Promise} { waybill_code, total, list }。 + */ + async getTrace(data = {}) { + try { + const safeData = this.isPlainObject(data) ? data : {}; + const waybillCode = String(safeData.waybillCode || safeData.waybill_code || '').trim(); + if (!waybillCode) { + return this.fail('运单号不能为空'); + } + + const warehouseId = Number(this.ctx?.user?.store_id || 0); + if (!warehouseId) { + return this.fail('无法获取当前仓库ID'); + } + + const result = await this.service.systems.waybill.listTracesByWaybill({ + waybillCode, + warehouseId, + }); + + return this.success('获取成功', result); + } catch (e) { + return this.fail(e.message); + } + } } module.exports = WaybillWarehouseService; diff --git a/app/service/systems/waybill.js b/app/service/systems/waybill.js index 203563b..cf9a4f6 100644 --- a/app/service/systems/waybill.js +++ b/app/service/systems/waybill.js @@ -1868,6 +1868,75 @@ class WaybillService extends MainService { : String(opTime || ''); return `${Number(expressId) || 0}|${time}|${String(scanType || '')}`; } + + /** + * 查询单个运单的全部物流轨迹(不分页),按操作时间倒序返回。 + * 仅查当前仓库数据(warehouse_id 隔离)。 + * + * @param {Object} options 查询参数。 + * @param {string} options.waybillCode 运单号。 + * @param {number} options.warehouseId 仓库 ID。 + * @return {Promise<{waybill_code: string, total: number, list: Array}>} 轨迹列表。 + */ + async listTracesByWaybill({ waybillCode, warehouseId } = {}) { + const { ctx } = this; + const normalizedCode = String(waybillCode || '').trim(); + const normalizedWarehouseId = Number(warehouseId) || 0; + + if (!normalizedCode) { + throw new Error('运单号不能为空'); + } + if (!normalizedWarehouseId) { + throw new Error('缺少仓库ID'); + } + + const rows = await ctx.model.OrderExpressTrace.findAll({ + attributes: [ + 'id', 'express_id', 'order_id', 'op_time', 'out_biz_code', + 'memo', 'op_org_city_name', 'weight', 'scan_type', 'raw_data', 'created_at', + ], + where: { + waybill_code: normalizedCode, + warehouse_id: normalizedWarehouseId, + }, + order: [[ 'op_time', 'DESC' ], [ 'id', 'DESC' ]], + raw: true, + }); + + const list = (rows || []).map(row => ({ + id: Number(row.id) || 0, + express_id: Number(row.express_id) || 0, + order_id: row.order_id ? Number(row.order_id) : null, + op_time: this.formatTraceTime(row.op_time), + out_biz_code: row.out_biz_code || '', + memo: row.memo || '', + op_org_city_name: row.op_org_city_name || '', + weight: Number(row.weight) || 0, + scan_type: row.scan_type || '', + raw_data: row.raw_data || null, + })); + + return { + waybill_code: normalizedCode, + total: list.length, + list, + }; + } + + /** + * 把轨迹时间格式化为 'YYYY-MM-DD HH:mm:ss'(本地时间),空值返回空字符串。 + * @param {*} value 数据库返回值。 + * @return {string} 格式化后的时间字符串。 + */ + formatTraceTime(value) { + if (!value) return ''; + const date = value instanceof Date ? value : new Date(value); + if (Number.isNaN(date.getTime())) return String(value); + + const pad = num => String(num).padStart(2, '0'); + return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ` + + `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`; + } } module.exports = WaybillService; diff --git a/database/designs/waybill-module-design.md b/database/designs/waybill-module-design.md index 9cd2b4c..1b1d3d1 100644 --- a/database/designs/waybill-module-design.md +++ b/database/designs/waybill-module-design.md @@ -237,14 +237,15 @@ POST /system { method: "waybill.warehouse.list", ... } | 6 | `waybill.warehouse.updateReceiveTaskProgress` | 揽收状态更新任务进度查询 | ✓ | ✗ | | 7 | `waybill.warehouse.updateTrace` | 批量更新运单物流轨迹(走出站回调 `waybill.getTrace`,异步任务) | ✓ | ✗ | | 8 | `waybill.warehouse.updateTraceTaskProgress` | 物流轨迹更新任务进度查询 | ✓ | ✗ | +| 9 | `waybill.warehouse.getTrace` | 查询单个运单的全部物流轨迹(不分页) | ✓ | ✗ | > **预留接口(本期不实现)**: > > | # | method | 描述 | > |---|--------|------| -> | 9 | `waybill.store.list` | 运单列表-货主侧(按 store_id 隔离) | -> | 10 | `waybill.store.detail` | 运单详情-货主侧 | -> | 11 | `waybill.store.export` | 运单导出-货主侧 | +> | 10 | `waybill.store.list` | 运单列表-货主侧(按 store_id 隔离) | +> | 11 | `waybill.store.detail` | 运单详情-货主侧 | +> | 12 | `waybill.store.export` | 运单导出-货主侧 | --- @@ -663,6 +664,39 @@ waybill.warehouse.updateTrace(入口层:参数校验 + 接口配置预检 + { "method": "waybill.warehouse.updateTraceTaskProgress", "task_id": "waybill_trace_1000028_1731190000000_ab12cd34" } ``` +#### 查询单个运单轨迹(`waybill.warehouse.getTrace`) + +只读接口:按运单号一次返回该运单下**全部**轨迹(不分页),按 `op_time DESC, id DESC` 排序;不调用外部接口、不落库。 + +```json +{ "method": "waybill.warehouse.getTrace", "waybillCode": "770358128188071" } +``` + +```json +{ + "waybill_code": "770358128188071", + "total": 1, + "list": [ + { + "id": 1, + "express_id": 123, + "order_id": 456, + "op_time": "2026-11-10 06:15:53", + "out_biz_code": "770358128188071_510180_1794262553000_210", + "memo": "【广州市】快件已发往 山东济南转运中心", + "op_org_city_name": "广州市", + "weight": 0, + "scan_type": "发件", + "raw_data": { "opTime": "2026-11-10 06:15:53" } + } + ] +} +``` + +- 仓库隔离:查询固定带 `warehouse_id = ctx.user.store_id` +- 运单号不存在或该仓库无轨迹 → `success` + `total=0` + `list=[]`(不报错) +- 同一运单号存在主单/子单多条运单记录时,按 `waybill_code` 聚合返回 + --- ## 四、`methods/system.json` 变更 diff --git a/methods/changes/system.json b/methods/changes/system.json index bfafcae..137c0db 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -1,4 +1,20 @@ [ + { + "version": "0.3.326", + "date": "2026-11-11", + "type": "added", + "summary": "新增运单轨迹查询:waybill.warehouse.getTrace 按运单号一次返回全部物流轨迹(不分页,按操作时间倒序),只读查询 wms_order_express_trace 并按仓库隔离", + "methods": [ + "waybill.warehouse.getTrace" + ], + "notes": [ + "定位:与 waybill.warehouse.updateTrace(拉取并落库)互补,本方法只读本地已落库轨迹,不触发外部接口调用。", + "入参:waybillCode(必填,兼容 waybill_code 下划线别名),单个运单精确匹配。", + "返回:{ waybill_code, total, list };list 按 op_time DESC, id DESC 排序,字段含 op_time(YYYY-MM-DD HH:mm:ss)、out_biz_code、memo、op_org_city_name、weight、scan_type、raw_data。", + "仓库隔离:查询固定带 warehouse_id = ctx.user.store_id;无数据返回 success + total=0 + list=[]。", + "代码依据:app/service/systemMethods/waybill/warehouse.js#getTrace,app/service/systems/waybill.js#listTracesByWaybill。" + ] + }, { "version": "0.3.325", "date": "2026-11-11", diff --git a/methods/system.json b/methods/system.json index 9377436..c6af33f 100644 --- a/methods/system.json +++ b/methods/system.json @@ -1,7 +1,7 @@ { "module": "system", "description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内", - "version": "0.3.325", + "version": "0.3.326", "updatedAt": "2026-11-11", "headers": [ { @@ -43534,6 +43534,160 @@ "message": "服务器内部错误:物流轨迹更新进度查询失败" } ] + }, + { + "method": "waybill.warehouse.getTrace", + "description": "查询单个运单的物流轨迹-仓库侧:按运单号一次返回该运单下的全部轨迹(不分页),按操作时间倒序排列(最新在前)。仅返回当前仓库数据(warehouse_id 隔离),运单号不存在时返回空列表。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "****** warehouseId(仓库上下文,ctx.user.store_id)" + } + ], + "params": [ + { + "name": "waybillCode", + "type": "string", + "required": true, + "source": "body", + "description": "运单号(单个精确匹配)" + }, + { + "name": "waybill_code", + "type": "string", + "required": false, + "source": "body", + "description": "waybillCode 的下划线别名,二者取其一" + } + ], + "response": [ + { + "name": "code", + "type": "number", + "required": true, + "description": "业务状态码,200 表示成功" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "业务提示信息" + }, + { + "name": "data", + "type": "object", + "required": true, + "description": "运单轨迹信息", + "children": [ + { + "name": "waybill_code", + "type": "string", + "required": true, + "description": "运单号" + }, + { + "name": "total", + "type": "number", + "required": true, + "description": "轨迹条数" + }, + { + "name": "list", + "type": "array", + "required": true, + "description": "轨迹列表(按 op_time 倒序,不分页)", + "children": [ + { + "name": "id", + "type": "number", + "required": false, + "description": "轨迹记录ID" + }, + { + "name": "express_id", + "type": "number", + "required": false, + "description": "运单ID(wms_order_express.id)" + }, + { + "name": "order_id", + "type": "number", + "required": false, + "description": "订单ID" + }, + { + "name": "op_time", + "type": "string", + "required": false, + "description": "操作时间,格式 YYYY-MM-DD HH:mm:ss" + }, + { + "name": "out_biz_code", + "type": "string", + "required": false, + "description": "外部业务码" + }, + { + "name": "memo", + "type": "string", + "required": false, + "description": "轨迹描述" + }, + { + "name": "op_org_city_name", + "type": "string", + "required": false, + "description": "操作机构所在城市" + }, + { + "name": "weight", + "type": "number", + "required": false, + "description": "重量(来源原值)" + }, + { + "name": "scan_type", + "type": "string", + "required": false, + "description": "扫描类型,如 发件/到件/派件/签收" + }, + { + "name": "raw_data", + "type": "object", + "required": false, + "description": "原始轨迹报文(未建模字段兜底)" + } + ] + } + ] + } + ], + "errors": [ + { + "code": "401", + "message": "未登录,请先登录" + }, + { + "code": "405", + "message": "参数校验失败:运单号不能为空" + }, + { + "code": "500", + "message": "服务器内部错误:运单轨迹查询失败" + } + ], + "notes": [ + "链路:systemMethods/waybill/warehouse.js#getTrace → systems/waybill.js#listTracesByWaybill → wms_order_express_trace", + "只读接口:不调用外部接口、不落库,仅查询已由 waybill.warehouse.updateTrace 落库的轨迹", + "不分页:一次返回该运单号下全部轨迹(按 op_time DESC, id DESC 排序)", + "仓库隔离:查询条件固定带 warehouse_id = 当前登录仓库,跨仓不可见", + "运单号不存在或该仓库无轨迹时返回 success + total=0 + list=[],不报错", + "同一运单号若存在主单/子单多条运单记录,轨迹按 waybill_code 聚合返回(轨迹表已冗余 waybill_code)" + ] } ] },