# 收货单 API 文档(`storage.receiving`) ## 1. 文档说明 本文档补充 `storage.receiving` 相关 system 方法中的收货明细商品绑定接口,当前重点覆盖: - `storage.receiving.bindDetailProduct` 适用场景: - 新增收货单明细后,为该明细绑定系统商品 - 已绑定商品时,改绑为另一个系统商品 - 前端或第三方系统对接收货单明细与系统商品的匹配动作 --- ## 2. 统一调用方式 该项目的 system 方法统一通过 `/system` 调用,方法名通过 query 参数 `method` 传入。 ### 请求方式 ```http POST /system?method=storage.receiving.bindDetailProduct&v=1.0×tamp={unix_timestamp} Content-Type: application/json Authorization: Bearer platform: web project: wms ``` ### 调用示例 ```bash curl -X POST "http://127.0.0.1:6060/system?method=storage.receiving.bindDetailProduct&v=1.0×tamp=1712400000" \ -H "Authorization: Bearer " \ -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 请求体示例 ```json { "detail_id": 12345, "system_product_id": 67890 } ``` --- ## 4. 成功返回示例 ```json { "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` | `绑定商品失败: ` | 服务内部异常 | ### 失败响应示例 ```json { "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 步新增明细后,一般会返回: ```json { "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` 当前已支持: - **绑定** 收货明细商品 - **改绑** 收货明细商品 - 自动回填商品名称、条码、重量、箱规等信息 - 自动刷新收货单统计数据 适合作为收货单明细与系统商品标准匹配接口对外说明使用。