WMS_MAIN/docs/storage-receiving-api.md
liufumingren d711ba9c21 0506更新
Co-authored-by: Copilot <copilot@github.com>
2026-05-06 17:53:54 +08:00

437 lines
14 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` 当前已支持:
- **绑定** 收货明细商品
- **改绑** 收货明细商品
- 自动回填商品名称、条码、重量、箱规等信息
- 自动刷新收货单统计数据
适合作为收货单明细与系统商品标准匹配接口对外说明使用。
---
## 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` | 否 | 箱长 |
| `box_remainder` | `number` | 否 | 箱内剩余数量/零散数量(不满箱时的件数) |
| `box_weight` | `number` | 否 | 实测箱重(单位与系统重量一致,如 kg) |
| `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,
"box_remainder": 0,
"box_weight": 0.0,
"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.box_remainder`:箱内剩余数量/零散数量(不满箱时的件数)
- `data.box_weight`:实测箱重(单位与系统重量一致)
- `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`(小于等于当前时间加最大阈值天数)。
---
## 12. 接口:storage.receiving.getReceivingDetail
## 接口:storage.receiving.get
### 用途
查询收货单完整信息(含明细 `details`、`images` 等)。
### 请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---:|---|---|
| `id` | `number` | 是 | 收货单 ID(source=body) |
### 返回字段补充
- `data.details.*.box_remainder`:number,可选,箱内剩余数量/零散数量(不满箱时的件数),默认 0。
- `data.details.*.box_weight`:number,可选,实测箱重(单位与系统重量一致,如 kg),默认 0。
兼容性:新增字段为可选,旧客户端无需变更。
### 12.1 用途
查询单张收货单详情,返回收货单头信息与明细(`details`),用于前端展示或二次处理。
### 12.2 请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---:|---|---|
| `id` | `number` | 是 | 收货单 ID |
| `pagination` | `object` | 否 | 明细分页参数,支持 `page` / `pageSize` |
### 12.3 返回示例(成功)
```json
{
"code": 200,
"message": "success",
"data": {
"receiving": {
"id": 12345,
"receiving_number": "RCV20260506001",
"details": [
{
"id": 501,
"product_name": "测试商品",
"actual_quantity": 10,
"box_quantity": 2,
"box_remainder": 0,
"box_weight": 5.2
}
],
"pagination": {
"page": 1,
"pageSize": 20,
"total": 1
}
}
}
}
```
### 12.4 返回字段说明(新增)
- `receiving.details.*.box_remainder`:number,可选,箱内剩余数量/零散数量(不满箱时的件数)。
- `receiving.details.*.box_weight`:number,可选,实测箱重(单位与系统重量一致,如 kg)。
## 13. 接口:storage.receiving.completeReceiving
### 13.1 用途
完成收货操作;完成后系统会发送内部通知/回调,通知中会包含收货单明细层面的箱规回写信息。
### 13.2 通知说明(新增字段)
完成收货时发送的通知 payload/metadata 将在每条明细中包含 `box_remainder` 与 `box_weight`,用于下游系统或前端展示箱内余量与实测箱重。通知示例(结构化示例,字段以实现为准):
```json
{
"event": "storage.receiving.completed",
"receiving_id": 12345,
"details": [
{
"id": 501,
"box_remainder": 0,
"box_weight": 5.2
}
],
"metadata": {
"completed_by": 1001,
"completed_at": "2026-05-06T12:00:00.000Z"
}
}
```
### 13.3 字段说明(通知/metadata)
- `details[*].box_remainder`:number,可选,箱内剩余数量/零散数量。
- `details[*].box_weight`:number,可选,实测箱重,单位同系统重量(例如 kg)。
兼容性:上述新增字段为可选字段,旧版消费者在未识别这些字段时可忽略。