328 lines
11 KiB
Markdown
328 lines
11 KiB
Markdown
# 收货单 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 <token>
|
||
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 <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` 当前已支持:
|
||
|
||
- **绑定** 收货明细商品
|
||
- **改绑** 收货明细商品
|
||
- 自动回填商品名称、条码、重量、箱规等信息
|
||
- 自动刷新收货单统计数据
|
||
|
||
适合作为收货单明细与系统商品标准匹配接口对外说明使用。
|
||
|
||
---
|
||
|
||
## 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` | 否 | 箱长 |
|
||
| `weight` | `number` | 否 | 毛重/重量 |
|
||
|
||
> 说明:`id` 与 `receiving_id` 为必须校验项,其他字段为可选—仅在传入时会写入/覆盖对应明细字段。传入 `system_product_id` 时,系统优先使用系统商品信息回填字段(前端可只传 `system_product_id` 来自动回填)。
|
||
|
||
### 11.3 请求示例
|
||
|
||
```json
|
||
{
|
||
"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` 中包含基础标识与关键展示字段:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "修改成功",
|
||
"data": {
|
||
"id": 501,
|
||
"receiving_id": 123,
|
||
"actual_quantity": 1,
|
||
"product_name": "测试商品",
|
||
"barcode": "",
|
||
"system_product_id": null,
|
||
"updated_at": "2026-04-01T00:00:00.000Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
返回字段说明:
|
||
|
||
- `data.id`:收货明细 ID
|
||
- `data.receiving_id`:收货单 ID
|
||
- `data.actual_quantity`:明细当前的实际收货数量(根据实现,此处返回服务端查询到的明细值)
|
||
- `data.product_name`:商品名称(若 `system_product_id` 回填则为系统商品名称)
|
||
- `data.barcode`:条码
|
||
- `data.system_product_id`:回填或当前关联的系统商品 ID
|
||
- `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`(小于等于当前时间加最大阈值天数)。
|
||
|
||
---
|
||
|
||
|