WMS_MAIN/database/designs/waybill-module-design.md

26 KiB
Raw Blame History

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

状态: ⏳ 等待审阅
设计日期: 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
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 查询

索引迁移:以下索引将通过迁移文件 YYYYMMDDHHmmss-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 的子单号

三、接口设计

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": "",
    "orderId": 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"
  }
}

参数说明

参数 类型 必填 说明
pagination object ✗ 分页参数 { page, pageSize },默认 page=1, pageSize=20
where object ✗ 筛选条件,所有字段均为可选
where.waybillCode string ✗ 运单号(模糊搜索)
where.mainWaybillCode string ✗ 主单号(精确匹配)。先通过主单号定位 order_id,再返回该订单下所有运单(主+子)。与 waybillCode 互斥,同时传入时 mainWaybillCode 优先
where.orderId number ✗ 订单ID(等值)
where.orderNo string ✗ 订单号(需要 JOIN 订单表后模糊匹配)
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号纸箱",
      "pack_status": "已打包",
      "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 包材名称
pack_status string LEFT JOIN pack_task 打包状态("未打包"/"已打包")
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(WHERE waybill_code = ? AND business_key = 1),再 WHERE order_id = ? 返回该订单下所有运单(主+子)
  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. 打包状态:LEFT JOIN pack_task ON waybill_code
  8. 性能注意:打印次数和打包状态的聚合查询在数据量大时可能成为瓶颈,建议先不做 JOIN,改为按需异步加载(在 detail 接口中返回),list 只返回 wms_order_express 原生字段 + 主单号 SELF JOIN

性能优化策略(建议):

  • 方案 A(推荐):列表仅查 wms_order_express 原生字段,不 JOIN 订单/打印/打包表。pack_status 和 print_count 通过批量异步查询补充,或仅在 detail 接口返回。
  • 方案 B:列表即 JOIN,但需确保索引覆盖良好。

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号纸箱",
    "pack_status": "已打包",
    "pack_quantity": 3,
    "pack_at": "2026-07-29 09:15:00",
    "packer_name": "张三"
  },
  "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/YYYYMMDDHHmmss-add-waybill-list-indexes.js 迁移文件:新增 idx_warehouse_id_status、idx_logistics_code、idx_logistics_interface_id、idx_warehouse_id_create_at 索引

六、安全约束

约束 说明
仓库隔离 所有查询自动注入 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,与现有模式一致
  • 列表字段是否完整(是否需要增减字段)
  • 是否需要 JOIN 订单/打印/打包表(性能 vs 信息完整性权衡)
  • 是否需要新增数据库索引
  • 与现有 index.toOrder、order.* 接口的边界是否清晰