WMS_MAIN/docs/storage-receiving-api.md
liufumingren 5ef99e3bed 1
2026-07-01 14:00:59 +08:00

488 lines
17 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)。
兼容性:上述新增字段为可选字段,旧版消费者在未识别这些字段时可忽略。
---
## 14. 收货→入库完整流程
### 14.1 流程概览
收货完成后,商品库存的实际入库通过以下步骤完成:
1. **创建入库单** → `storage.entry` 系列方法(list/get/cancel/completeEntry)
2. **匹配入库(写库存)** → `storage.inventory.matchPutaway`(**目前唯一的库存写入入库链路**)
> ⚠️ 注意:`storage.entry.completeEntry` 仅做入库单状态变更(PENDING → COMPLETED),**不涉及库存写入**。库存的实际写入统一由 `storage.inventory.matchPutaway` 完成。
### 14.2 完整推荐流程
```
1. storage.receiving.create → 创建收货单
2. storage.receiving.addDetail → 新增明细,拿到 selectId
3. storage.receiving.bindDetailProduct → 绑定系统商品
4. storage.receiving.detailChange → 补充数量、批次等
5. storage.receiving.completeReceiving → 完成收货
↓
6. storage.entry 入库单管理 → 入库单与收货单通过 wms_entry_order_receiving 主表级关联
7. storage.inventory.matchPutaway → 收货单与入库单匹配,完成库存写入
8. storage.entry.completeEntry → 入库单状态标记为 COMPLETED(仅状态变更)
```
### 14.3 已弃用的方法
以下方法已从代码中移除,**不再可用**:
| 已弃用方法 | 弃用原因 | 替代方案 |
|---|---|---|
| `storage.entry.bindReceivingDetails` | 入库单明细与收货明细逐行绑定(基于 `wms_entry_receiving_binding` 表),关系已改为 `wms_entry_order_receiving` 主表级关联 | 不再需要,入库单与收货单直接通过主表关联 |
| `storage.entry.unbindReceivingDetails` | 同上,逐行解绑已无必要 | 不再需要 |
| `storage.inventory.quickPutaway` | 单一收货单快捷转入库单(已重新实现):按 stock_id 合并收货明细创建入库单(SCRK,自动审批到 PENDING),写入主表级绑定 | `storage.entry.commitDirectInbound`(导入/PDA 入库完成确认) |
### 14.4 核心方法职责
| 方法 | 职责 | 备注 |
|---|---|---|
| `storage.inventory.matchPutaway` | **唯一库存写入入库链路**:接收多个收货单和多个入库单,按商品进行数量匹配,完成库存的实际写入 | 入库后根据来源(QM/API)自动触发回传 |
| `storage.entry.completeEntry` | **仅状态变更**:入库单 PENDING → COMPLETED | 不涉及任何库存写入 |
| `storage.entry.list` | 入库单列表查询 | 支持 CREATING/CREATED/PENDING/COMPLETED/CANCELLED 状态筛选 |
| `storage.entry.get` | 入库单详情查询 | 含 items 及其 bindings |
| `storage.entry.cancel` | 作废入库单(CREATED/PENDING 可作废) | COMPLETED 不可作废 |
### 14.5 关键数据库表关系
- `wms_entry_order_receiving`:入库单与收货单的**主表级关联**(当前方案)
- `wms_entry_receiving_binding`:**已弃用**,不再写入新数据(旧方案:明细级绑定)
- 收货单与入库单不再需要逐明细绑定,通过主表关联即可完成匹配入库