feat(waybill): 新增 waybill.warehouse.getTrace 运单轨迹查询

- 按运单号一次返回该运单全部物流轨迹(不分页),按 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>
This commit is contained in:
liufumingren 2026-11-11 20:05:22 +08:00
parent 89e4cd22c0
commit 1964021d50
5 changed files with 313 additions and 6 deletions

View File

@ -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<Object>} { 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;

View File

@ -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<Object>}>} 轨迹列表。
*/
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;

View File

@ -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` 变更

View File

@ -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",

View File

@ -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)"
]
}
]
},