WMS_MAIN/docs/storage-receiving-api.md
2026-04-09 01:36:49 +08:00

5.6 KiB
Raw Blame History

收货单 API 文档(storage.receiving)

1. 文档说明

本文档补充 storage.receiving 相关 system 方法中的收货明细商品绑定接口,当前重点覆盖:

  • storage.receiving.bindDetailProduct

适用场景:

  • 新增收货单明细后,为该明细绑定系统商品
  • 已绑定商品时,改绑为另一个系统商品
  • 前端或第三方系统对接收货单明细与系统商品的匹配动作

2. 统一调用方式

该项目的 system 方法统一通过 /system 调用,方法名通过 query 参数 method 传入。

请求方式

POST /system?method=storage.receiving.bindDetailProduct&v=1.0&timestamp={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&timestamp=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_id
  • product_name
  • product_snapshot
  • barcode(有条码时)
  • 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. 业务校验规则

接口内部会执行以下校验:

  1. 当前用户必须有仓库上下文
    • 仓库 ID 取自 ctx.user.store_id
  2. 收货单明细必须存在
  3. 收货单明细必须属于当前仓库
  4. 收货单状态必须为 receiving
    • 已完成、已作废等状态不允许继续绑定或改绑
  5. 目标商品必须属于当前仓库
    • 根据 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. 推荐调用链路

典型前端操作顺序如下:

  1. storage.receiving.create:创建收货单
  2. storage.receiving.addDetail:新增空白明细,拿到 selectId
  3. storage.receiving.bindDetailProduct:绑定系统商品
  4. storage.receiving.detailChange:补充数量、箱数、备注等字段
  5. 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 当前已支持:

  • 绑定 收货明细商品
  • 改绑 收货明细商品
  • 自动回填商品名称、条码、重量、箱规等信息
  • 自动刷新收货单统计数据

适合作为收货单明细与系统商品标准匹配接口对外说明使用。