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

220 lines
5.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 收货单 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&timestamp={unix_timestamp}
Content-Type: application/json
Authorization: Bearer <token>
platform: web
project: wms
```
### 调用示例
```bash
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 请求体示例
```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` | `绑定商品失败: <error>` | 服务内部异常 |
### 失败响应示例
```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` 当前已支持:
- **绑定** 收货明细商品
- **改绑** 收货明细商品
- 自动回填商品名称、条码、重量、箱规等信息
- 自动刷新收货单统计数据
适合作为收货单明细与系统商品标准匹配接口对外说明使用。