- 新增 systems/waybill.js 业务层:运单列表查询/详情/导出 - 新增 systemMethods/waybill/warehouse.js 入口层 - 新增 6 个迁移脚本:面单列表索引、store_id 列、物流编码/名称回填、发货单号列、货主ID回填、发货字段回填 - 更新 waybill-module-design.md 设计文档
637 lines
29 KiB
Markdown
637 lines
29 KiB
Markdown
# 运单号模块设计方案(仓库侧)
|
||
|
||
> **状态**: 🔧 开发中(索引已就绪,快照字段待 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 | — |
|