- storeWarehouse.store.saveApiConfig:新增 resolveContractApiInterfaceType, interface_type_id=3(OPEN_API_WAREHOUSE 仓库开放接口)自动映射为 2(OPEN_API 货主开放接口)落库, 不再要求当前主体为仓库(货主可维护自身签约关系下的接口配置) - callback_url 不再取入参(含 callbackUrl 别名),统一写入 config.openapi.defaultCallbackUrl(新增配置项,默认空) - storeWarehouse.store.listApiConfig:interface_type_id 过滤同步映射(传 3 按 2 查询) - 文档:methods/system.json 升级 0.3.350、methods/changes/system.json 变更记录、docs/openapi-callback-events.md 回调地址来源说明 - 测试:saveApiConfig 新增 4 条用例(3→2 落库、忽略入参回调地址、默认值未配置、货主主体可保存、缺失类型 404),listApiConfig 新增 1 条过滤映射用例 同时提交工作区其余在制品改动: - waybill:移除 wms_order_express_trace 模型并新增 drop 迁移,轨迹查询/取号/打印链路调整 - order:订单 SN 编码(order_item_sn / order_item_sn_log / sn_code_rule、has_sn_item 回填迁移),pendingOrder/recheckOrder/wave/base 调整 - express_platform、order_async、order_export、order_storage_allocation、storage.report、stock_store 配套修复 - lib:新增 jd_client,调整 qimen_client、callback_functions 及配套测试 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
38 KiB
运单号模块设计方案(仓库侧)
状态: 🔧 开发中(索引已就绪,快照字段待 dev 实现写入逻辑后执行)
设计日期: 2026-07-29
设计人: wms-db-agent
说明: 本文档仅输出设计方案,不执行代码实现。审阅通过后再进入开发。
命名空间:waybill.warehouse.*(仓库侧操作);后续预留waybill.store.*(货主侧操作),本期不实现。
一、需求概述
当前系统缺少独立的运单号查询与管理界面。运单数据(wms_order_express)始终依附于订单上下文——运单信息仅通过订单详情接口(xxx.detail)的 expresses[] 字段返回,或通过 index.toOrder 做运单号→订单反查。实际业务中需要:
- 运单号列表(仓库侧):按仓库维度,独立查询所有运单号,支持多条件筛选、分页,支持主单号/子单号关联展示与查询
- 运单详情(仓库侧):查看单个运单的完整信息,包含关联订单、打印记录、打包状态、称重信息
- 运单导出(仓库侧):支持按筛选条件导出运单列表
主单号/子单号规则(沿用已有业务约定):同一
order_id下,business_key = 1的运单为主单号,business_key > 1的运单为子单号(即拆单产生的子运单)。该规则已在order_export.js导出逻辑中使用。命名空间规划:
waybill.warehouse.*本期实现(仓库侧操作);后续按需扩展waybill.store.*(货主侧操作,按store_id维度查询)。两套接口共享底层systems/waybill.js业务逻辑,仅入口鉴权与数据隔离维度不同。
二、数据模型分析
2.1 核心表:wms_order_express(运单表,已有)
当前表结构(关键字段):
| 字段 | 类型 | 说明 |
|---|---|---|
id |
BIGINT(20) UNSIGNED PK |
主键 |
waybill_code |
VARCHAR(50) |
运单号 |
order_id |
BIGINT(20) |
订单ID |
warehouse_id |
BIGINT(20) UNSIGNED |
仓库ID |
store_id |
BIGINT(20) UNSIGNED |
🆕 货主ID |
business_key |
INTEGER(3) |
拆单序号(1=主单号,>1=子单号) |
status |
TINYINT(1) DEFAULT 0 |
状态(1=已分配,0=未分配) |
logistics_interface_id |
BIGINT(20) UNSIGNED |
物流接口ID |
logistics_code |
VARCHAR(50) |
物流公司编码 |
logistics_name |
VARCHAR(50) |
物流公司名称 |
logistics_interface_id |
BIGINT(20) UNSIGNED |
物流接口ID |
logistics_interface_name |
VARCHAR(50) |
物流接口名称 |
platform_code |
VARCHAR(50) |
平台编码 |
is_galaxy_receive |
ENUM('Y','N') |
是否揽收 |
is_back |
ENUM('Y','N') |
是否退回 |
is_intercept |
ENUM('Y','N') |
是否拦截 |
weighing_weight |
INT(11) DEFAULT 0 |
称重重量(g) |
package_material_id |
BIGINT(20) UNSIGNED |
包材ID |
package_material_name_snapshot |
VARCHAR(128) |
包材名称快照 |
printinfo |
TEXT('long') |
打印信息 |
ver |
VARCHAR(50) |
打印版本号 |
retry_count |
TINYINT(3) |
重试次数 |
create_at |
DATE |
创建时间 |
delete_at |
DATE |
删除时间 |
现有索引:
| 索引名 | 字段 | 类型 |
|---|---|---|
PRIMARY |
id |
主键 |
uk_order_id_business_key |
order_id, business_key |
唯一 |
idx_waybill_code |
waybill_code |
普通 |
idx_create_at |
create_at |
普通 |
idx_wms_order_express_package_material_id |
package_material_id |
普通 |
idx_warehouse_store |
store_id, warehouse_id |
普通(货主+仓库组合过滤,迁移 20261109235000) |
2.2 关联表
| 表名 | 关联字段 | 用途 |
|---|---|---|
wms_order_delivery(current/history/dispatch) |
order_id |
订单信息(订单号、货主、波次等) |
wms_express |
logistics_code ↔ code |
物流公司名称(统一展示名) |
express_print_record |
express_no ↔ waybill_code |
打印记录(打印时间、打印机、模板) |
pack_task |
waybill_code |
打包任务(打包状态、打包人、打包时间) |
package_material |
package_material_id ↔ id |
包材详情 |
轨迹不落库(2026-11-11 调整):物流轨迹改为全部实时回源,
wms_order_express_trace表与模型已删除(迁移20261111205500-drop-wms-order-express-trace.js)。轨迹查询不再有本地表,也不再存在 1:N 关联。
2.3 索引评估
当前 wms_order_express 表的索引不足以支撑运单列表场景的高频查询:
| 缺失索引 | 原因 |
|---|---|
idx_warehouse_id_status |
运单列表按仓库+状态是最常见查询 |
idx_logistics_code |
按物流公司筛选运单 |
idx_logistics_interface_id |
按快递接口ID筛选运单 |
idx_warehouse_id_create_at |
仓库+时间范围排序分页 |
idx_order_id_business_key |
已有 uk_order_id_business_key 唯一索引,可同时覆盖主单号 SELF JOIN 查询 |
索引迁移:以下索引已通过迁移文件
20260729140000-add-waybill-list-indexes.js正式创建,见 §五 文件变更清单。
Y/N 标记列单列索引(2026-11-11 新增):is_back / is_intercept / is_galaxy_receive 三列此前无索引,而它们是列表常用筛选条件(且用于「批量更新揽收状态」的条件圈选)。迁移 20261111041500-add-yn-flag-indexes-to-order-express.js 为三列分别建立单列索引(idx_is_back / idx_is_intercept / idx_is_galaxy_receive,ALGORITHM=INPLACE, LOCK=NONE 在线创建)。不同筛选方向各自独立命中,故不建联合索引。
默认值:三列默认值均为 'N'(模型 defaultValue + 数据库 DEFAULT 'N'),存量 NULL 已由迁移 20261111033000-init-is-back-intercept-receive-to-n.js 回填为 'N'(Y 不动)。
2.4 主单号/子单号关联关系
规则(沿用系统已有约定):
- 同一
order_id下,business_key = 1→ 主单号(main waybill) - 同一
order_id下,business_key > 1→ 子单号(child waybill) - 该规则已在
app/service/systems/order_export.js第 444 行使用:business_key === 1 ? '主单号' : '子单号'
查询方式:
- 正向查(子→主):在
wms_order_express上做 SELF JOIN,t1.order_id = t2.order_id AND t2.business_key = 1获取主单号 - 反向查(主→子):通过
order_id+business_key > 1查子单号;或通过主单号waybill_code先定位order_id,再查该订单下所有运单
注意:
- 大部分运单
business_key = 1(未拆单),此时主单号 = 运单号本身 - 仅拆单场景下存在
business_key > 1的子单号
2.5 快照字段评估(待开发实现)
状态:字段和迁移已准备就绪,但创建运单号时写入快照值的逻辑尚未实现(属于 dev 任务范围)。当前快照列为空,列表仍需 JOIN 订单表。
原则:运单列表应尽量避免 JOIN wms_order_delivery(current/history/dispatch 多表)和 store 表,通过快照字段冗余订单关键信息到 wms_order_express。
现有快照字段:
| 字段 | 快照内容 | 覆盖场景 |
|---|---|---|
package_material_name_snapshot |
包材名称 | ✅ 避 JOIN package_material |
待新增快照字段(需配合 dev 改造创建运单号逻辑):
| 快照列 | 类型 | 替代的 JOIN | 写入时机 |
|---|---|---|---|
delivery_order_code |
VARCHAR(50) |
order_delivery.delivery_order_code |
运单号分配成功时(express.js) |
store_id_snapshot |
BIGINT(20) UNSIGNED |
order_delivery.store_id |
同上 |
store_name_snapshot |
VARCHAR(128) |
store.name(货主表) |
同上 |
warehouse_name_snapshot |
VARCHAR(128) |
store.name(仓库表) |
同上 |
迁移文件:
20260729130000-add-waybill-order-snapshots.js已创建但已回滚,待 dev 实现写入逻辑后再执行。
三、接口设计
3.1 模块概览
| 项目 | 说明 |
|---|---|
| 模块名 | waybill.warehouse |
| 接口路径 | POST /system,body 中 method 字段为 waybill.warehouse.{方法名} |
| 请求方式 | 全部 POST,参数放在 body 内 |
| 鉴权 | 全部接口需登录,暂不做细粒度鉴权 |
| 数据隔离 | 按 warehouse_id 隔离(仓库侧视角,见 §3.1.1 仓库隔离策略) |
| 后续扩展 | 预留 waybill.store.*(货主侧,按 store_id 隔离),本期不实现 |
3.1.1 仓库隔离策略(已核实)
核实结论:仓库隔离策略与系统现有模式一致,无需调整。
请求上下文来源(系统统一约定):
| 项目 | 值 | 说明 |
|---|---|---|
| 仓库ID来源 | ctx.user.store_id |
全系统统一:ctx.user.store_id 即为当前操作用户所属仓库的 warehouse_id |
| 后备方案 | 无(必须登录) | 未登录用户无法访问,不存在 store_id 为空的情况 |
| 注入方式 | WHERE 条件自动追加 | 在 systems/waybill.js 中 const warehouseId = Number(ctx.user.store_id),追加 warehouse_id = warehouseId 到所有查询的 WHERE 子句 |
| 注入时机 | 业务层(systems) | 不在入口层(systemMethods)注入,保持业务层职责单一 |
参考依据(系统内一致使用 ctx.user.store_id 作为 warehouse_id):
| 文件 | 行号/位置 | 用法 |
|---|---|---|
systems/waybill.js(现有 toOrder) |
第 29 行 | ctx.user && ctx.user.store_id ? ctx.user.store_id : null |
systemMethods/index.js |
第 1593 行 | ctx.user && ctx.user.store_id ? Number(ctx.user.store_id) : null |
systemMethods/print.js |
第 725 行 | ctx.user.store_id |
systemMethods/stock/transaction.js |
第 32 行 | Number(this.ctx.user && this.ctx.user.store_id) |
systemMethods/storage/management.js |
JSDoc 注释 | "仓库 ID 从用户上下文(ctx.user.store_id / ctx.user.warehouse_id)自动获取" |
注:部分文件也支持
ctx.user.warehouse_id作为备选来源(如storage/management.js),但ctx.user.store_id是全系统主要来源,且wms_order_express表中的warehouse_id字段语义上对应store_id。本期统一使用ctx.user.store_id。
3.2 文件规划
app/service/systemMethods/waybill/warehouse.js ← 入口层(鉴权、参数校验、委托)
app/service/systems/waybill.js ← 业务层(扩展:新增 list/detail/export 方法)
methods/system.json ← API 文档(新增 waybill.warehouse group)
注意:
app/service/systems/waybill.js已有toOrder()方法(运单反查),新方法将添加到同一文件中。- 目录
systemMethods/waybill/预留store.js(货主侧入口),本期仅创建warehouse.js。
3.3 调用链路
POST /system { method: "waybill.warehouse.list", ... }
→ app/router.js
→ app/service/system.js
→ app/service/systemMethods/waybill/warehouse.js ← 鉴权 + 参数校验
→ app/service/systems/waybill.js ← 业务逻辑 + DB操作
→ ctx.model.OrderExpress ← Sequelize Model
→ ctx.model.OrderDeliveryFactory ← 订单信息补充
→ ctx.model.Express ← 物流公司名称
→ ctx.model.ExpressPrintRecord ← 打印记录
3.4 接口清单
| # | method | 描述 | 需登录 | 需鉴权 |
|---|---|---|---|---|
| 1 | waybill.warehouse.list |
运单列表-仓库侧(分页+筛选) | ✓ | ✗ |
| 2 | waybill.warehouse.detail |
运单详情-仓库侧(含订单/打印/打包/称重信息) | ✓ | ✗ |
| 3 | waybill.warehouse.export |
运单导出-仓库侧(按筛选条件) | ✓ | ✗ |
| 4 | waybill.warehouse.exportTaskProgress |
运单导出任务进度查询 | ✓ | ✗ |
| 5 | waybill.warehouse.updateReceive |
批量更新运单是否揽收(走出站回调 waybill.getreceive,异步任务) |
✓ | ✗ |
| 6 | waybill.warehouse.updateReceiveTaskProgress |
揽收状态更新任务进度查询 | ✓ | ✗ |
| 7 | waybill.warehouse.getTrace |
查询单个运单的全部物流轨迹(实时回源,不分页) | ✓ | ✗ |
预留接口(本期不实现):
# method 描述 8 waybill.store.list运单列表-货主侧(按 store_id 隔离) 9 waybill.store.detail运单详情-货主侧 10 waybill.store.export运单导出-货主侧
3.5 waybill.warehouse.list — 运单列表(仓库侧)
功能说明:查询运单号列表,支持分页与多条件筛选。仓库隔离(自动注入 warehouse_id)。
请求参数
{
"method": "waybill.warehouse.list",
"pagination": {
"page": 1,
"pageSize": 20
},
"where": {
"waybillCode": "",
"mainWaybillCode": "",
"waybillType": "",
"orderId": null,
"orderNo": "",
"storeId": null,
"logisticsCode": "",
"logisticsInterfaceId": null,
"platformCode": "",
"status": null,
"isBack": null,
"isIntercept": null,
"isGalaxyReceive": null,
"packageMaterialId": null,
"hasWeighingWeight": null,
"keyword": "",
"createdAtStart": "",
"createdAtEnd": ""
},
"sort": {
"field": "create_at",
"order": "desc"
}
}
where.mainWaybillCode支持字符串或字符串数组:"SF1234567890"(单主单)或["SF1234567890", "SF0987654321"](多主单,按IN精确匹配)。上例以单值展示。
参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
pagination |
object |
✗ | 分页参数 { page, pageSize },默认 page=1, pageSize=20 |
where |
object |
✗ | 筛选条件,所有字段均为可选 |
where.waybillCode |
string |
✗ | 运单号(模糊搜索) |
where.mainWaybillCode |
string | string[] |
✗ | 主单号(精确匹配,2026-10-04 起支持数组)。单值:先通过主单号定位 order_id,再返回该订单下所有运单(主+子);数组:按 Op.in 匹配多个主单号,返回这些主单对应订单下的全部运单。与 waybillCode 同时传入时按 AND 叠加,不做互斥优先级处理。空数组/全空值不加该条件;主单号均不存在时直接返回空列表 |
where.waybillType |
string |
✗ | 🆕 运单类型:"main"/"1"=主单号(business_key=1),"child"/"2"=子单号(business_key>1) |
where.orderId |
number |
✗ | 订单ID(等值) |
where.orderNo |
string |
✗ | ⛔ 暂不可用:订单号(待快照字段 delivery_order_code 落库后启用 LIKE 模糊搜索) |
where.storeId |
number |
✗ | 货主ID(等值,直读 store_id 列) |
where.logisticsCode |
string |
✗ | 物流公司编码(等值) |
where.logisticsInterfaceId |
number |
✗ | 物流接口ID(等值),对应 wms_order_express.logistics_interface_id,用于按快递接口筛选运单列表 |
where.platformCode |
string |
✗ | 平台编码(等值),如 PDD/DY/KS/JD/CAINIAO/SPH/XHS |
where.status |
number |
✗ | 运单状态:0=未分配,1=已分配 |
where.isBack |
string |
✗ | 是否退回:Y/N |
where.isIntercept |
string |
✗ | 是否拦截:Y/N |
where.isGalaxyReceive |
string |
✗ | 是否揽收:Y/N |
where.packageMaterialId |
number |
✗ | 包材ID(等值) |
where.hasWeighingWeight |
boolean |
✗ | 是否已称重:true=weighing_weight>0,false=weighing_weight=0 |
where.keyword |
string |
✗ | 关键词:匹配运单号(waybill_code)、主单号(main_waybill_code)、订单号(需 JOIN) |
where.createdAtStart |
string |
✗ | 创建时间起始(YYYY-MM-DD) |
where.createdAtEnd |
string |
✗ | 创建时间截止(YYYY-MM-DD) |
sort |
object |
✗ | 排序 { field, order },默认 create_at desc |
sort.field |
string |
✗ | 排序字段:create_at / weighing_weight / id |
sort.order |
string |
✗ | 排序方向:asc / desc,默认 desc |
响应格式
{
"list": [
{
"id": 123456,
"waybill_code": "SF1234567890",
"main_waybill_code": "SF1234567890",
"waybill_type": "主单号",
"order_id": 78901,
"order_no": "PO202607290001",
"warehouse_id": 1,
"warehouse_name": "默认仓库",
"store_id": 10,
"store_name": "测试货主",
"business_key": 1,
"status": 1,
"status_text": "已分配",
"logistics_interface_id": 3,
"logistics_code": "SF",
"logistics_name": "顺丰速运",
"logistics_interface_name": "顺丰标准",
"platform_code": "PDD",
"platform_name": "拼多多",
"is_back": "N",
"is_intercept": "N",
"is_galaxy_receive": "N",
"weighing_weight": 1250,
"weighing_weight_display": "1.25 kg",
"package_material_id": 5,
"package_material_name": "3号纸箱",
"print_count": 2,
"last_print_at": "2026-07-29 10:30:00",
"create_at": "2026-07-29 08:00:00"
}
],
"pagination": {
"page": 1,
"pageSize": 20,
"total": 156,
"totalPages": 8
}
}
响应字段说明
| 字段 | 类型 | 来源 | 说明 |
|---|---|---|---|
id |
number |
wms_order_express.id |
运单记录ID |
waybill_code |
string |
wms_order_express.waybill_code |
运单号(当前运单的运单号) |
main_waybill_code |
string |
SELF JOIN 同 order 下 business_key=1 |
主单号。当 business_key=1 时等于 waybill_code 本身;当 business_key>1 时通过 SELF JOIN 查找同 order_id 下 business_key=1 的运单号 |
waybill_type |
string |
计算字段 | 运单类型:business_key=1 → "主单号",business_key>1 → "子单号" |
order_id |
number |
wms_order_express.order_id |
订单ID |
order_no |
string |
JOIN 订单表 | 订单号(delivery_order_code)。待快照字段 + 写入逻辑实现后可改为直读 |
warehouse_id |
number |
wms_order_express.warehouse_id |
仓库ID |
warehouse_name |
string |
JOIN store 表 |
仓库名称。待快照字段 + 写入逻辑实现后可改为直读 |
store_id |
number |
JOIN 订单表 | 货主ID。待快照字段 + 写入逻辑实现后可改为直读 |
store_name |
string |
JOIN store 表 |
货主名称。待快照字段 + 写入逻辑实现后可改为直读 |
business_key |
number |
wms_order_express.business_key |
拆单序号 |
status |
number |
wms_order_express.status |
状态:0/1 |
status_text |
string |
前端映射 | 状态文本 |
logistics_code |
string |
wms_order_express.logistics_code |
物流公司编码 |
logistics_name |
string |
wms_order_express.logistics_name |
物流公司名称 |
logistics_interface_id |
number |
wms_order_express.logistics_interface_id |
物流接口ID |
logistics_interface_name |
string |
wms_order_express.logistics_interface_name |
物流接口名称 |
platform_code |
string |
wms_order_express.platform_code |
平台编码 |
platform_name |
string |
前端映射 | 平台名称 |
is_back |
string |
wms_order_express.is_back |
是否退回 |
is_intercept |
string |
wms_order_express.is_intercept |
是否拦截 |
is_galaxy_receive |
string |
wms_order_express.is_galaxy_receive |
是否揽收 |
weighing_weight |
number |
wms_order_express.weighing_weight |
称重重量(g) |
weighing_weight_display |
string |
格式化 | 称重重量可读展示 |
package_material_id |
number |
wms_order_express.package_material_id |
包材ID |
package_material_name |
string |
wms_order_express.package_material_name_snapshot |
包材名称 |
print_count |
number |
COUNT express_print_record |
打印次数 |
last_print_at |
string |
MAX express_print_record.created_at |
最近打印时间 |
create_at |
string |
wms_order_express.create_at |
运单创建时间 |
查询逻辑要点
- 仓库隔离:自动注入
warehouse_id = ctx.user.store_id(系统统一约定,ctx.user.store_id即为当前用户所属仓库ID)。所有查询 WHERE 条件自动追加warehouse_id,不可由前端入参覆盖 - 主单号关联查询:每条运单记录通过 SELF JOIN(
t1.order_id = t2.order_id AND t2.business_key = 1)获取主单号main_waybill_code。当business_key = 1时,主单号就是自身waybill_code;当business_key > 1时,需要 JOIN 获取主单号 - 按主单号入参查询:当
where.mainWaybillCode传入时,先通过主单号waybill_code定位order_id,再返回该订单下所有运单(主+子)。支持单值 / 数组(2026-10-04):单值保持WHERE waybill_code = ? AND business_key = 1 AND warehouse_id = ?→WHERE order_id = ?(标量,向后兼容);数组按WHERE waybill_code IN (?, ?) AND business_key = 1 AND warehouse_id = ?→WHERE order_id IN (?, ?)(去重后Op.in),返回多个主单对应订单下的全部运单;元素自动 trim 并过滤空值,全部主单号不存在时直接返回空列表,空数组/全空值数组不添加该条件 - 按物流接口ID查询:直接
WHERE logistics_interface_id = ?,等值匹配 - 订单号模糊搜索:当
where.orderNo或where.keyword匹配到非纯数字运单号时,需要 JOIN 订单表(current/history/dispatch)进行delivery_order_code LIKE匹配 - 打印次数:通过子查询或 LEFT JOIN + GROUP BY
express_print_record.express_no = waybill_code聚合 - 性能注意:打印次数聚合查询在数据量大时可能成为瓶颈,建议仅在 detail 接口返回
性能优化策略(建议):
- 方案 A(推荐):列表仅查
wms_order_express原生字段,不 JOIN 订单/打印/打包表。print_count通过批量异步查询补充,或仅在 detail 接口返回。- 方案 B:列表即 JOIN,但需确保索引覆盖良好。
快照字段优化(待实现):新增快照列 + 创建运单号时写入快照值后,可彻底去掉订单表和 store 表的 JOIN。迁移文件
20260729130000-add-waybill-order-snapshots.js已就绪,待 dev 实现写入逻辑后执行。
3.6 waybill.warehouse.detail — 运单详情(仓库侧)
功能说明:查看单个运单的完整信息,包含关联订单、打印记录、打包信息。
请求参数
{
"method": "waybill.warehouse.detail",
"id": 123456
}
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id |
number |
✓ | 运单记录ID(wms_order_express.id) |
waybillCode |
string |
✗ | 运单号(与 id 二选一,waybillCode 优先) |
响应格式
{
"id": 123456,
"waybill_code": "SF1234567890",
"main_waybill_code": "SF1234567890",
"waybill_type": "主单号",
"business_key": 1,
"sibling_waybills": [
{ "waybill_code": "SF1234567890", "business_key": 1, "waybill_type": "主单号" },
{ "waybill_code": "SF1234567891", "business_key": 2, "waybill_type": "子单号" }
],
"order": {
"order_id": 78901,
"order_no": "PO202607290001",
"warehouse_id": 1,
"warehouse_name": "默认仓库",
"store_id": 10,
"store_name": "测试货主",
"wave_id": 500,
"wave_no": "W202607290001",
"order_type": "delivery"
},
"logistics": {
"logistics_code": "SF",
"logistics_name": "顺丰速运",
"logistics_interface_id": 3,
"logistics_interface_name": "顺丰标准",
"platform_code": "PDD"
},
"status_info": {
"status": 1,
"status_text": "已分配",
"is_back": "N",
"is_intercept": "N",
"is_galaxy_receive": "N"
},
"weight": {
"weighing_weight": 1250,
"weighing_weight_display": "1.25 kg"
},
"package": {
"package_material_id": 5,
"package_material_name": "3号纸箱"
},
"print_records": [
{
"id": 1001,
"printer_name": "打印机-01",
"template_id": 2,
"template_name": "顺丰标准面单",
"platform": "PDD",
"printed_at": "2026-07-29 10:30:00"
}
],
"print_count": 2,
"printinfo": "{...}",
"ver": "v2.1",
"retry_count": 0,
"create_at": "2026-07-29 08:00:00",
"delete_at": null
}
查询逻辑要点
- 查询
wms_order_express主记录 - 通过
order_id查询同订单下所有运单组成sibling_waybills(含各运单的waybill_code、business_key、waybill_type) - 通过
order_id→OrderDeliveryFactory多表遍历查找订单信息 - LEFT JOIN
wms_express获取物流公司统一名称 - LEFT JOIN
pack_taskONwaybill_code获取打包信息 - LEFT JOIN
express_print_recordONexpress_no = waybill_code获取打印记录列表 - 仓库隔离校验
3.7 waybill.warehouse.export — 运单导出(仓库侧)
功能说明:按筛选条件导出运单列表为 Excel。复用 waybill.warehouse.list 的筛选逻辑,去掉分页,全量导出。
请求参数
同 waybill.warehouse.list,不含 pagination 参数,可选增加 exportFields 指定导出字段。
{
"method": "waybill.warehouse.export",
"where": { "...": "同 waybill.warehouse.list" },
"sort": { "...": "同 waybill.warehouse.list" },
"exportFields": ["waybill_code", "order_no", "logistics_name", "weighing_weight", "create_at"]
}
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
where |
object |
✗ | 同 waybill.warehouse.list 的筛选条件 |
sort |
object |
✗ | 同 waybill.warehouse.list 的排序 |
exportFields |
string[] |
✗ | 需要导出的字段列表,不传则导出全部字段 |
3.8 waybill.warehouse.updateReceive / waybill.warehouse.updateReceiveTaskProgress — 批量更新是否揽收(仓库侧)
功能说明:wms_order_express.is_galaxy_receive 此前只有创建默认值 N,没有任何写入来源。本接口按运单号调用外部访问接口查询揽收状态并回写,链路不读取本地库的揽收标记。
调用链路
waybill.warehouse.updateReceive(入口层:参数校验 + 接口配置预检 + 建任务)
→ systems/waybill.js#queryReceiveStatus(每批 ≤10 单,逐批回写 + 回调进度)
→ openapi/callback.js#sendByAppKey(event = waybill.getreceive)
→ 回写 wms_order_express.is_galaxy_receive(waybill_code + warehouse_id 隔离)
请求参数
两种用法二选一(waybillCodes 优先):
{ "method": "waybill.warehouse.updateReceive", "waybillCodes": ["YT1234567890", "SF1234567890"] }
{
"method": "waybill.warehouse.updateReceive",
"where": { "isGalaxyReceive": "N", "logisticsCode": "YTO", "createdAt": ["2026-11-01", "2026-11-11"] }
}
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
waybillCodes |
string[] |
✗ | 运单号列表,内部按 10 单一批调用外部接口 |
waybill_codes |
string[] |
✗ | waybillCodes 的下划线别名 |
where |
object |
✗ | 与 waybill.warehouse.list 完全一致的筛选条件(不含 pagination / sort);仅传 where 时由 buildListQueryWhere 解析运单号后再走同一任务链路 |
where 支持的字段与列表一致:waybillCode / mainWaybillCode / orderId / orderNo / logisticsCode / logisticsInterfaceId / platformCode / status / isBack / isIntercept / isGalaxyReceive / waybillType / storeId / packageMaterialId / hasWeighingWeight / keyword / createdAt(含 createAt 别名、createdAtStart/createdAtEnd 旧写法)。
约束:
- 两者都不传 → 失败「运单号不能为空,或传入 where 筛选条件」
where匹配数 > 5000 → 失败「符合条件的运单超过 5000 条,请缩小筛选范围或直接传 waybillCodes」(不截断,避免误更新)where匹配 0 条 → 失败「未匹配到符合条件的运单」
外部接口约定(waybill.getreceive)
- 请求体:
{ "request": { "waybill_codes": [...] } }(由sendByAppKey统一包装,单批最多 10 单) - 签名:
sign = MD5(appSecret + timestamp + bodyJson)(仓库通知协议,signMode=simple);不使用/openapi入站的canonicalQuery口径。外部接收端(如new_wms_notify)按该协议验签,用旧口径会返回{"code":401,"msg":"签名验证失败"} - 响应:裸数组
[{ "waybill_code": "YT...", "is_galaxy_receive": 1 }],兼容{ code, data: [...] }与{ data: { waybills: [...] } } - 取值:
1/0、'Y'/'N'(大小写不敏感)、布尔;非法值计入failed,不写库 - 业务失败:HTTP 200 但
code非0/1/200时整批计入failed - 目标应用:该仓库
callback_functions勾选waybill.getreceive的首个启用应用(按id升序)
失败前置校验(不进入任务流程)
仓库下无任何应用承接 waybill.getreceive 时,updateReceive 直接返回失败(不创建任务、不写进度缓存):
如需更新运单是否揽收信息,到【设置】->【基础设置】->【API开放接口】配置相应的外部访问接口
任务进度
task_id 前缀 waybill_receive_,Redis 缓存键前缀 waybill_receive_task_(与导出的 waybill_export_ 互相隔离)。状态流转 submitted → running → success/failed,result 返回 { total, updated, unchanged, not_found, failed }。
{
"method": "waybill.warehouse.updateReceiveTaskProgress",
"task_id": "waybill_receive_1000028_1731190000000_ab12cd34"
}
3.9 waybill.warehouse.getTrace — 查询运单物流轨迹(仓库侧,实时回源)
功能说明:按运单号实时调用外部访问接口 waybill.getTrace 查询轨迹,一次返回全部轨迹(不分页),按 op_time 倒序。
- 不做本地存储:
wms_order_express_trace表与模型已删除(迁移20261111205500-drop-wms-order-express-trace.js),每次查询都回源 - 揽收联动:轨迹非空时把该运单
wms_order_express.is_galaxy_receive置为Y(只升不降,失败只记日志不阻断查询) - 失败口径:未配置承接应用或外部接口异常时直接返回失败(无本地兜底);
trace: []属于正常结果(success+total=0)
调用链路
waybill.warehouse.getTrace(入口层:参数校验 + 接口配置预检)
→ systems/waybill.js#fetchTracesByWaybill(单运单实时查询 + 归一排序)
→ openapi/callback.js#sendByAppKey(event = waybill.getTrace,signMode=simple)
→ systems/waybill.js#markReceiveByTraces(命中轨迹则置 is_galaxy_receive=Y)
请求 / 响应
{ "method": "waybill.warehouse.getTrace", "waybillCode": "770358128188071" }
{
"waybill_code": "770358128188071",
"total": 2,
"received_updated": 1,
"list": [
{
"op_time": "2026-11-11 10:43:00",
"out_biz_code": "770358128188071_510902_1794255999000_120",
"memo": "【广州市】快件已发往 山东济南转运中心",
"op_org_city_name": "广州市",
"weight": 0.99,
"scan_type": "收件",
"raw_data": { "opTime": "2026-11-11 10:43:00" }
}
]
}
外部接口约定(waybill.getTrace)
- 请求体:
{ "request": { "waybill_codes": ["770358128188071"] } }(单运单);签名同waybill.getreceive(MD5(appSecret + timestamp + bodyJson)) - 响应:
[{ "waybillNo": "...", "trace": [ { "opTime", "outBizCode", "memo", "opOrgCityName", "weight", "scanType" } ] }],trace可为对象或数组,另兼容{ code, data: [...] }与单个对象返回 trace: []表示暂无轨迹;weight支持字符串小数("0.99")- 目标应用:该仓库
callback_functions勾选waybill.getTrace的首个启用应用(按id升序)
四、methods/system.json 变更
在 methods.groups[] 中新增 waybill.warehouse group:
{
"name": "waybill.warehouse",
"description": "运单号管理(仓库侧)",
"methods": [
{
"method": "waybill.warehouse.list",
"description": "运单列表(分页+筛选)。仓库隔离。",
"isNeedAuth": false,
"isNeedLogin": true,
"params": [ "... 参数定义 ..." ],
"response": [ "... 返回值定义 ..." ]
},
{
"method": "waybill.warehouse.detail",
"description": "运单详情(含订单/打印/打包信息)。仓库隔离。",
"isNeedAuth": false,
"isNeedLogin": true,
"params": [ "... 参数定义 ..." ],
"response": [ "... 返回值定义 ..." ]
},
{
"method": "waybill.warehouse.export",
"description": "运单导出。仓库隔离。",
"isNeedAuth": false,
"isNeedLogin": true,
"params": [ "... 参数定义 ..." ],
"response": [ "... 返回值定义 ..." ]
}
]
}
预留 group(本期不实现):
waybill.store— 运单号管理(货主侧),按store_id隔离。完整的
methods/system.jsonmethod 定义(含 params/response 的 children 详情)在代码实现阶段由wms-doc-agent补齐。
五、文件变更清单
| 操作 | 文件路径 | 说明 |
|---|---|---|
| 新增 | app/service/systemMethods/waybill/warehouse.js |
入口层(仓库侧):继承 MainService,systemInit 声明免鉴权方法,参数校验,委托 systems/waybill.js |
| 预留 | app/service/systemMethods/waybill/store.js |
入口层(货主侧):本期不创建,后续按需新增 |
| 修改 | app/service/systems/waybill.js |
业务层:在现有 toOrder() 方法基础上新增 list()、detail()、export() 方法 |
| 修改 | methods/system.json |
新增 waybill.warehouse group,注册 3 个 method 定义 |
| 新增 | database/migrations/20260729140000-add-waybill-list-indexes.js |
迁移文件:新增 4 个索引(✅ 已执行) |
| 新增 | database/migrations/20260730000000-add-store-id-to-wms-order-express.js |
迁移文件:新增 store_id 货主ID列(✅ 已执行) |
| 新增 | database/migrations/20261109235000-add-warehouse-store-index-to-wms-order-express.js |
迁移文件:新增 idx_warehouse_store (store_id, warehouse_id) 索引(生产已手工创建,待按流程执行记录) |
六、安全约束
| 约束 | 说明 |
|---|---|
| 仓库隔离 | 所有查询自动注入 warehouse_id = ctx.user.store_id(系统统一约定),仅返回当前用户所属仓库数据,不可由入参覆盖 |
| 只读 | 本模块一期仅提供只读查询,不涉及运单创建/修改/删除 |
| 鉴权 | 全部接口仅需登录,暂不做细粒度权限校验(与订单列表保持一致) |
七、与现有功能的边界划分
| 现有功能 | 所属 method | 与新模块关系 |
|---|---|---|
| 运单号反查订单 | index.toOrder |
保留,独立于新模块。用于 PDA 扫运单号快速定位订单 |
| 订单详情中的运单信息 | order.detail → expresses[] |
保留,不变。新模块提供运单维度的独立视图 |
| 运单包材绑定 | order.bindExpressPackageMaterial* |
保留,不变。仍按订单维度操作 |
| 运单称重更新 | order.updateExpressWeighingWeight |
保留,不变。仍按订单维度操作 |
| 快递号分配 | order.pendingOrder.allocateExpressCode |
保留,不变。仍按订单维度操作 |
| 订单导出(运单模式) | order.export (export_mode=waybill) |
保留,不变。与新模块 waybill.warehouse.export 并存 |
核心原则:新模块不修改任何现有接口,仅新增运单维度的独立查询能力。现有订单维度的运单操作全部保持不动。
八、后续扩展方向(不在本期范围)
| 扩展 | 说明 |
|---|---|
| 运单拦截/解拦截 | 批量操作运单状态 |
| 运单退回标记 | 标记运单退回并记录原因 |
| 运单打印管理 | 批量补打、重新推送电子面单 |
| 运单异常列表 | 独立展示分配失败/打印失败的运单 |
| 运单物流轨迹 | 对接物流轨迹查询接口 |
九、审阅检查点
- 接口设计是否满足业务需求(运单号独立列表 + 详情)
仓库隔离策略是否正确→ 已核实:全系统统一使用ctx.user.store_id作为 warehouse_id,与现有模式一致- 列表字段是否完整(是否需要增减字段)
- 快照字段写入逻辑:需在创建运单号(express.js)时同步写入快照列值(dev 任务)
- 是否需要新增数据库索引(已明确需要,
20260729140000已执行) - 与现有
index.toOrder、order.*接口的边界是否清晰
当前筛选条件(共 18 项,16 可用 + 2 待快照)
| # | 参数 | 类型 | 匹配 | 状态 |
|---|---|---|---|---|
| — | warehouse_id |
— | = | ✅ 自动注入 |
| 1 | waybillCode |
string | LIKE | ✅ |
| 2 | mainWaybillCode |
string | string[] | 精确→order_id(数组 Op.in) | ✅ 🆕 |
| 3 | waybillType |
string | main/1→bk=1, child/2→bk>1 |
✅ 🆕 |
| 4 | orderId |
number | = | ✅ |
| 5 | orderNo |
string | LIKE | ⛔ 待快照 |
| 6 | storeId |
number | = | ✅ 直读 store_id |
| 7 | logisticsCode |
string | = | ✅ |
| 8 | logisticsInterfaceId |
number | = | ✅ |
| 9 | platformCode |
string | = | ✅ |
| 10 | status |
number | = | ✅ |
| 11 | isBack |
string | = | ✅ |
| 12 | isIntercept |
string | = | ✅ |
| 13 | isGalaxyReceive |
string | = | ✅ |
| 14 | packageMaterialId |
number | = | ✅ |
| 15 | hasWeighingWeight |
boolean | true→>0, false→=0 | ✅ |
| 16 | keyword |
string | LIKE waybill_code | ✅ |
| 17 | createdAtStart |
string YYYY-MM-DD | >= | ✅ |
| 18 | createdAtEnd |
string YYYY-MM-DD | <= | ✅ |
排序
| field | order | 默认 |
|---|---|---|
create_at |
asc/desc | desc |
weighing_weight |
asc/desc | — |
id |
asc/desc | — |