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:
parent
89e4cd22c0
commit
1964021d50
@ -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;
|
||||
|
||||
@ -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;
|
||||
|
||||
@ -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` 变更
|
||||
|
||||
@ -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",
|
||||
|
||||
@ -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)"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user