5.6 KiB
5.6 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 当前已支持:
- 绑定 收货明细商品
- 改绑 收货明细商品
- 自动回填商品名称、条码、重量、箱规等信息
- 自动刷新收货单统计数据
适合作为收货单明细与系统商品标准匹配接口对外说明使用。