WMS_MAIN/database/designs/waybill-module-design.md
liufumingren 0717640eff feat(waybill): waybill.warehouse.list/export 支持 mainWaybillCode 数组(0.3.243)
- systems/waybill.js 新增 resolveMainWaybillOrderIds:主单号单值/数组统一解析为 order_id 集合
  - 数组按 Op.in 精确匹配多个主单号,返回这些订单下的全部运单(主+子)
  - 单值仍写标量 order_id(向后兼容);主单号均不存在时直接返回空结果;空数组/全空值数组不加该筛选条件
- 新增回归测试 test/app/service/systems/waybill.warehouse.mainWaybillCode.in.test.js(13 用例,含 list/export 与仓库隔离)
- 接口文档:where.mainWaybillCode 类型改为 string|string[],并修正原「与 waybillCode 互斥、mainWaybillCode 优先」的错误描述(实际为 AND 叠加);根版本 0.3.242 → 0.3.243
- 设计文档 database/designs/waybill-module-design.md 同步(请求示例、参数表、查询逻辑、筛选条件清单)

注:methods/system.json 与 methods/changes/system.json 中同时包含上一批盘点(stock.check)的未提交文档改动(JSON 无法按 hunk 拆分)。
2026-10-04 18:50:03 +08:00

30 KiB
Raw Blame History

运单号模块设计方案(仓库侧)

状态: 🔧 开发中(索引已就绪,快照字段待 dev 实现写入逻辑后执行)
设计日期: 2026-07-29
设计人: wms-db-agent
说明: 本文档仅输出设计方案,不执行代码实现。审阅通过后再进入开发。
命名空间: waybill.warehouse.*(仓库侧操作);后续预留 waybill.store.*(货主侧操作),本期不实现。


一、需求概述

当前系统缺少独立的运单号查询与管理界面。运单数据(wms_order_express)始终依附于订单上下文——运单信息仅通过订单详情接口(xxx.detail)的 expresses[] 字段返回,或通过 index.toOrder 做运单号→订单反查。实际业务中需要:

  1. 运单号列表(仓库侧):按仓库维度,独立查询所有运单号,支持多条件筛选、分页,支持主单号/子单号关联展示与查询
  2. 运单详情(仓库侧):查看单个运单的完整信息,包含关联订单、打印记录、打包状态、称重信息
  3. 运单导出(仓库侧):支持按筛选条件导出运单列表

主单号/子单号规则(沿用已有业务约定):同一 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 普通

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 包材详情

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 正式创建,见 §五 文件变更清单。

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 运单导出-仓库侧(按筛选条件) ✓ ✗

预留接口(本期不实现):

# method 描述
4 waybill.store.list 运单列表-货主侧(按 store_id 隔离)
5 waybill.store.detail 运单详情-货主侧
6 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 运单创建时间

查询逻辑要点

  1. 仓库隔离:自动注入 warehouse_id = ctx.user.store_id(系统统一约定,ctx.user.store_id 即为当前用户所属仓库ID)。所有查询 WHERE 条件自动追加 warehouse_id,不可由前端入参覆盖
  2. 主单号关联查询:每条运单记录通过 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 获取主单号
  3. 按主单号入参查询:当 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 并过滤空值,全部主单号不存在时直接返回空列表,空数组/全空值数组不添加该条件
  4. 按物流接口ID查询:直接 WHERE logistics_interface_id = ?,等值匹配
  5. 订单号模糊搜索:当 where.orderNo 或 where.keyword 匹配到非纯数字运单号时,需要 JOIN 订单表(current/history/dispatch)进行 delivery_order_code LIKE 匹配
  6. 打印次数:通过子查询或 LEFT JOIN + GROUP BY express_print_record.express_no = waybill_code 聚合
  7. 性能注意:打印次数聚合查询在数据量大时可能成为瓶颈,建议仅在 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
}

查询逻辑要点

  1. 查询 wms_order_express 主记录
  2. 通过 order_id 查询同订单下所有运单组成 sibling_waybills(含各运单的 waybill_code、business_key、waybill_type)
  3. 通过 order_id → OrderDeliveryFactory 多表遍历查找订单信息
  4. LEFT JOIN wms_express 获取物流公司统一名称
  5. LEFT JOIN pack_task ON waybill_code 获取打包信息
  6. LEFT JOIN express_print_record ON express_no = waybill_code 获取打印记录列表
  7. 仓库隔离校验

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[] ✗ 需要导出的字段列表,不传则导出全部字段

四、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.json method 定义(含 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列(✅ 已执行)

六、安全约束

约束 说明
仓库隔离 所有查询自动注入 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 —