WMS_MAIN/database/designs/waybill-module-design.md
liufumingren edc164298d feat(waybill): 新增面单/运单管理模块
- 新增 systems/waybill.js 业务层:运单列表查询/详情/导出
- 新增 systemMethods/waybill/warehouse.js 入口层
- 新增 6 个迁移脚本:面单列表索引、store_id 列、物流编码/名称回填、发货单号列、货主ID回填、发货字段回填
- 更新 waybill-module-design.md 设计文档
2026-08-01 03:43:47 +08:00

637 lines
29 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 运单号模块设计方案(仓库侧)
> **状态**: 🔧 开发中(索引已就绪,快照字段待 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`)。
#### 请求参数
```json
{
"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"
}
}
```
#### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `pagination` | `object` | ✗ | 分页参数 `{ page, pageSize }`,默认 page=1, pageSize=20 |
| `where` | `object` | ✗ | 筛选条件,所有字段均为可选 |
| `where.waybillCode` | `string` | ✗ | 运单号(模糊搜索) |
| `where.mainWaybillCode` | `string` | ✗ | **主单号**(精确匹配)。先通过主单号定位 `order_id`,再返回该订单下所有运单(主+子)。与 `waybillCode` 互斥,同时传入时 `mainWaybillCode` 优先 |
| `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` |
#### 响应格式
```json
{
"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`(`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. **性能注意**:打印次数聚合查询在数据量大时可能成为瓶颈,建议仅在 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` — 运单详情(仓库侧)
**功能说明**:查看单个运单的完整信息,包含关联订单、打印记录、打包信息。
#### 请求参数
```json
{
"method": "waybill.warehouse.detail",
"id": 123456
}
```
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | `number` | ✓ | 运单记录ID(`wms_order_express.id`) |
| `waybillCode` | `string` | ✗ | 运单号(与 id 二选一,waybillCode 优先) |
#### 响应格式
```json
{
"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` 指定导出字段。
```json
{
"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:
```json
{
"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` 并存 |
> **核心原则**:新模块不修改任何现有接口,仅新增运单维度的独立查询能力。现有订单维度的运单操作全部保持不动。
---
## 八、后续扩展方向(不在本期范围)
| 扩展 | 说明 |
|------|------|
| 运单拦截/解拦截 | 批量操作运单状态 |
| 运单退回标记 | 标记运单退回并记录原因 |
| 运单打印管理 | 批量补打、重新推送电子面单 |
| 运单异常列表 | 独立展示分配失败/打印失败的运单 |
| 运单物流轨迹 | 对接物流轨迹查询接口 |
---
## 九、审阅检查点
- [ ] 接口设计是否满足业务需求(运单号独立列表 + 详情)
- [x] ~~仓库隔离策略是否正确~~ → 已核实:全系统统一使用 `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 | 精确→order_id | ✅ |
| 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 | — |