17 KiB
收货单 API 文档(storage.receiving)
1. 文档说明
本文档补充 storage.receiving 相关 system 方法中的收货明细商品绑定接口,当前重点覆盖:
storage.receiving.bindDetailProduct
适用场景:
- 新增收货单明细后,为该明细绑定系统商品
- 已绑定商品时,改绑为另一个系统商品
- 前端或第三方系统对接收货单明细与系统商品的匹配动作
2. 统一调用方式
该项目的 system 方法统一通过 /system 调用,方法名通过 query 参数 method 传入。
请求方式
POST /system?method=storage.receiving.bindDetailProduct&v=1.0×tamp={unix_timestamp}
Content-Type: application/json
Authorization: Bearer <token>
platform: web
project: wms
调用示例
curl -X POST "http://127.0.0.1:6060/system?method=storage.receiving.bindDetailProduct&v=1.0×tamp=1712400000" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-H "platform: web" \
-H "project: wms" \
-d '{
"detail_id": 12345,
"system_product_id": 67890
}'
说明:该接口通常要求用户已登录,并以当前仓库角色执行;实际仓库上下文来自
ctx.user.store_id。
3. 接口:storage.receiving.bindDetailProduct
3.1 接口用途
用于绑定或改绑收货单明细的系统商品。
调用成功后,系统会按当前仓库商品信息自动回填或更新以下内容:
system_product_idproduct_nameproduct_snapshotbarcode(有条码时)weight(商品存在毛重时)- 箱规尺寸字段(启用箱规时)
同时会刷新整张收货单的统计信息。
3.2 请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail_id |
number |
是 | 收货单明细 ID |
id |
number |
否 | 兼容字段,可替代 detail_id |
system_product_id |
number |
是 | 要绑定的系统商品 ID(StockWarehouse.id) |
3.3 请求体示例
{
"detail_id": 12345,
"system_product_id": 67890
}
4. 成功返回示例
{
"flag": "success",
"code": 200,
"message": "绑定商品成功",
"data": {
"detail_id": 12345,
"receiving_id": 10001,
"system_product_id": 67890,
"product_name": "测试商品A"
}
}
返回字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
flag |
string |
固定为 success |
code |
number |
业务状态码,成功为 200 |
message |
string |
返回说明 |
data.detail_id |
number |
当前绑定的收货单明细 ID |
data.receiving_id |
number |
收货单 ID |
data.system_product_id |
number |
当前绑定的系统商品 ID |
data.product_name |
string |
自动回填的商品名称 |
注意:该项目的 system 方法经常返回 HTTP
200,业务是否成功请以响应体内的code和message为准。
5. 业务校验规则
接口内部会执行以下校验:
- 当前用户必须有仓库上下文
- 仓库 ID 取自
ctx.user.store_id
- 仓库 ID 取自
- 收货单明细必须存在
- 收货单明细必须属于当前仓库
- 收货单状态必须为
receiving- 已完成、已作废等状态不允许继续绑定或改绑
- 目标商品必须属于当前仓库
- 根据
StockWarehouse.id + warehouse_id校验
- 根据
6. 失败返回示例与错误码
常见失败场景
code |
message 示例 |
含义 |
|---|---|---|
400 |
用户未绑定仓库 |
当前用户无仓库角色上下文 |
400 |
收货单明细ID不能为空 |
未传 detail_id / id |
400 |
商品ID不能为空 |
未传 system_product_id |
400 |
收货单状态不允许绑定或改绑商品 |
当前收货单状态不允许继续操作 |
404 |
收货单明细不存在 |
明细不存在或不属于当前仓库 |
404 |
商品不存在或不属于当前仓库 |
商品不存在或仓库不匹配 |
500 |
绑定商品失败: <error> |
服务内部异常 |
失败响应示例
{
"flag": "success",
"code": 404,
"message": "商品不存在或不属于当前仓库"
}
7. 推荐调用链路
典型前端操作顺序如下:
storage.receiving.create:创建收货单storage.receiving.addDetail:新增空白明细,拿到selectIdstorage.receiving.bindDetailProduct:绑定系统商品storage.receiving.detailChange:补充数量、箱数、备注等字段storage.receiving.completeReceiving:完成收货
其中第 2 步新增明细后,一般会返回:
{
"data": {
"selectId": 12345
}
}
该 selectId 即可直接作为 bindDetailProduct 的 detail_id。
8. 回归验证参考
仓库中已有接口级回归用例,可作为联调参考:
test/app/controller/system.storage.receiving.test.js
已覆盖的场景包括:
- 新建收货单后绑定商品
- 已绑定商品后再次改绑
- 绑定成功后返回
detail_id、system_product_id、product_name
9. 实现位置(源码定位)
system 方法包装层
- 文件:
app/service/systemMethods/storage/receiving.js - 方法:
bindDetailProduct(data)
实际业务实现
- 文件:
app/service/systems/storage/receiving.js - 方法:
bindDetailProduct(data)
10. 当前接口结论
storage.receiving.bindDetailProduct 当前已支持:
- 绑定 收货明细商品
- 改绑 收货明细商品
- 自动回填商品名称、条码、重量、箱规等信息
- 自动刷新收货单统计数据
适合作为收货单明细与系统商品标准匹配接口对外说明使用。
11. 接口:storage.receiving.detailChange
11.1 接口用途
用于修改收货单明细(明细行)中的数量、箱规、批次与商品信息,并触发收货单统计与相关联动(例如库存/统计刷新与操作日志)。典型场景为:前端在录入收货明细后,补录实际收货数量、箱数、托盘数、批次/生产/到期信息或回写条码与商品名称等。
注意:方法在 system 层以
POST /system?method=storage.receiving.detailChange调用,需包含Authorization: Bearer <token>,仓库上下文来源于ctx.user.store_id。
11.2 请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
id |
number |
是 | 收货明细 ID(必填) |
receiving_id |
number |
是 | 收货单 ID(必填) |
actual_quantity |
number |
否 | 实际收货数量 |
batch_number |
string |
否 | 批次号 |
production_date |
string |
否 | 生产日期(ISO 或可解析的日期字符串) |
expiry_date |
string |
否 | 到期日期(ISO 或可解析的日期字符串)。若传入的 expiry_date 小于当前日期,接口会拒绝并返回 400(见错误码) |
box_quantity |
number |
否 | 箱数 |
boxes_per_pallet |
number |
否 | 每托盘箱数 |
pallet_quantity |
number |
否 | 托盘数 |
space_id |
number |
否 | 目标库位 ID(可用于回写库位) |
remark |
string |
否 | 备注 |
system_product_id |
number |
否 | 系统商品 ID(StockWarehouse.id)。若提供,系统会回填条码、重量、箱规、商品名称与快照等;若不提供,可单独更新 barcode/product_name |
barcode |
string |
否 | 条码(当未传 system_product_id 时,可单独更新) |
product_name |
string |
否 | 商品名称(当未传 system_product_id 时,可单独更新) |
box_width |
number |
否 | 箱宽(单位按系统约定) |
box_height |
number |
否 | 箱高 |
box_length |
number |
否 | 箱长 |
box_remainder |
number |
否 | 箱内剩余数量/零散数量(不满箱时的件数) |
box_weight |
number |
否 | 实测箱重(单位与系统重量一致,如 kg) |
weight |
number |
否 | 毛重/重量 |
说明:
id与receiving_id为必须校验项,其他字段为可选—仅在传入时会写入/覆盖对应明细字段。传入system_product_id时,系统优先使用系统商品信息回填字段(前端可只传system_product_id来自动回填)。
11.3 请求示例
{
"id": 501,
"receiving_id": 123,
"actual_quantity": 10,
"batch_number": "B20260401",
"production_date": "2026-04-01",
"expiry_date": "2027-04-01",
"box_quantity": 2,
"boxes_per_pallet": 10,
"pallet_quantity": 0,
"space_id": 1001,
"remark": "样例备注",
"system_product_id": 8888
}
11.4 返回结构(成功)
成功时返回 code: 200,message 为 修改成功,data 中包含基础标识与关键展示字段:
{
"code": 200,
"message": "修改成功",
"data": {
"id": 501,
"receiving_id": 123,
"actual_quantity": 1,
"product_name": "测试商品",
"barcode": "",
"system_product_id": null,
"box_remainder": 0,
"box_weight": 0.0,
"updated_at": "2026-04-01T00:00:00.000Z"
}
}
返回字段说明:
data.id:收货明细 IDdata.receiving_id:收货单 IDdata.actual_quantity:明细当前的实际收货数量(根据实现,此处返回服务端查询到的明细值)data.product_name:商品名称(若system_product_id回填则为系统商品名称)data.barcode:条码data.system_product_id:回填或当前关联的系统商品 IDdata.box_remainder:箱内剩余数量/零散数量(不满箱时的件数)data.box_weight:实测箱重(单位与系统重量一致)data.updated_at:明细记录的更新时间
11.5 常见错误码
| code | message 示例 | 含义 |
|---|---|---|
400 |
收货明细ID不能为空 |
未传 id |
400 |
收货单ID不能为空 |
未传 receiving_id |
400 |
到期日期已过期,不能录入收货 |
expiry_date 小于当前日期时返回(禁止录入已过期批次) |
400 |
箱数不能为负数 / 托盘数不能为负数 |
非法的箱规数值 |
404 |
收货明细不存在 |
明细不存在或不属于当前仓库/收货单状态不允许操作 |
500 |
修改失败,请稍后重试 |
服务端异常 |
11.6 业务要点与实现说明
- 若传入
system_product_id,服务端尝试读取StockWarehouse(同仓库)并回填:barcode(若前端未显式传入),weight,boxes_per_pallet、box_height、box_width、box_length(若启用箱规),以及product_snapshot中的货主快照信息。 - 若未传
system_product_id,但传入barcode或product_name,服务端仍允许更新这两个字段(并把system_product_id置为null)。 - 接口会在成功写入明细后触发收货单统计刷新(
updateReceivingStats)并写操作日志(RECEIVING_UPDATE_DETAIL)。 - 系统存在一个库存效期预警定时任务,逻辑上会扫描启用保质期管理且设置了剩余天数阈值的商品,并按库存到期日筛选候选记录后进行去重通知发送;其判断条件主要依赖
wms_stock_warehouse.is_shelf_life_mgmt = 'Y'、remaining_threshold_days > 0,以及wms_storage.expiry_date(小于等于当前时间加最大阈值天数)。
12. 接口:storage.receiving.getReceivingDetail
接口:storage.receiving.get
用途
查询收货单完整信息(含明细 details、images 等)。
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
id |
number |
是 | 收货单 ID(source=body) |
返回字段补充
data.details.*.box_remainder:number,可选,箱内剩余数量/零散数量(不满箱时的件数),默认 0。data.details.*.box_weight:number,可选,实测箱重(单位与系统重量一致,如 kg),默认 0。
兼容性:新增字段为可选,旧客户端无需变更。
12.1 用途
查询单张收货单详情,返回收货单头信息与明细(details),用于前端展示或二次处理。
12.2 请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
id |
number |
是 | 收货单 ID |
pagination |
object |
否 | 明细分页参数,支持 page / pageSize |
12.3 返回示例(成功)
{
"code": 200,
"message": "success",
"data": {
"receiving": {
"id": 12345,
"receiving_number": "RCV20260506001",
"details": [
{
"id": 501,
"product_name": "测试商品",
"actual_quantity": 10,
"box_quantity": 2,
"box_remainder": 0,
"box_weight": 5.2
}
],
"pagination": {
"page": 1,
"pageSize": 20,
"total": 1
}
}
}
}
12.4 返回字段说明(新增)
receiving.details.*.box_remainder:number,可选,箱内剩余数量/零散数量(不满箱时的件数)。receiving.details.*.box_weight:number,可选,实测箱重(单位与系统重量一致,如 kg)。
13. 接口:storage.receiving.completeReceiving
13.1 用途
完成收货操作;完成后系统会发送内部通知/回调,通知中会包含收货单明细层面的箱规回写信息。
13.2 通知说明(新增字段)
完成收货时发送的通知 payload/metadata 将在每条明细中包含 box_remainder 与 box_weight,用于下游系统或前端展示箱内余量与实测箱重。通知示例(结构化示例,字段以实现为准):
{
"event": "storage.receiving.completed",
"receiving_id": 12345,
"details": [
{
"id": 501,
"box_remainder": 0,
"box_weight": 5.2
}
],
"metadata": {
"completed_by": 1001,
"completed_at": "2026-05-06T12:00:00.000Z"
}
}
13.3 字段说明(通知/metadata)
details[*].box_remainder:number,可选,箱内剩余数量/零散数量。details[*].box_weight:number,可选,实测箱重,单位同系统重量(例如 kg)。
兼容性:上述新增字段为可选字段,旧版消费者在未识别这些字段时可忽略。
14. 收货→入库完整流程
14.1 流程概览
收货完成后,商品库存的实际入库通过以下步骤完成:
- 创建入库单 →
storage.entry系列方法(list/get/cancel/completeEntry) - 匹配入库(写库存) →
storage.inventory.matchPutaway(目前唯一的库存写入入库链路)
⚠️ 注意:
storage.entry.completeEntry仅做入库单状态变更(PENDING → COMPLETED),不涉及库存写入。库存的实际写入统一由storage.inventory.matchPutaway完成。
14.2 完整推荐流程
1. storage.receiving.create → 创建收货单
2. storage.receiving.addDetail → 新增明细,拿到 selectId
3. storage.receiving.bindDetailProduct → 绑定系统商品
4. storage.receiving.detailChange → 补充数量、批次等
5. storage.receiving.completeReceiving → 完成收货
↓
6. storage.entry 入库单管理 → 入库单与收货单通过 wms_entry_order_receiving 主表级关联
7. storage.inventory.matchPutaway → 收货单与入库单匹配,完成库存写入
8. storage.entry.completeEntry → 入库单状态标记为 COMPLETED(仅状态变更)
14.3 已弃用的方法
以下方法已从代码中移除,不再可用:
| 已弃用方法 | 弃用原因 | 替代方案 |
|---|---|---|
storage.entry.bindReceivingDetails |
入库单明细与收货明细逐行绑定(基于 wms_entry_receiving_binding 表),关系已改为 wms_entry_order_receiving 主表级关联 |
不再需要,入库单与收货单直接通过主表关联 |
storage.entry.unbindReceivingDetails |
同上,逐行解绑已无必要 | 不再需要 |
storage.inventory.quickPutaway |
单一收货单快捷入库,功能受限 | storage.inventory.matchPutaway(支持多收货单+多入库单批量匹配入库) |
14.4 核心方法职责
| 方法 | 职责 | 备注 |
|---|---|---|
storage.inventory.matchPutaway |
唯一库存写入入库链路:接收多个收货单和多个入库单,按商品进行数量匹配,完成库存的实际写入 | 入库后根据来源(QM/API)自动触发回传 |
storage.entry.completeEntry |
仅状态变更:入库单 PENDING → COMPLETED | 不涉及任何库存写入 |
storage.entry.list |
入库单列表查询 | 支持 CREATING/CREATED/PENDING/COMPLETED/CANCELLED 状态筛选 |
storage.entry.get |
入库单详情查询 | 含 items 及其 bindings |
storage.entry.cancel |
作废入库单(CREATED/PENDING 可作废) | COMPLETED 不可作废 |
14.5 关键数据库表关系
wms_entry_order_receiving:入库单与收货单的主表级关联(当前方案)wms_entry_receiving_binding:已弃用,不再写入新数据(旧方案:明细级绑定)- 收货单与入库单不再需要逐明细绑定,通过主表关联即可完成匹配入库