WMS_MAIN/docs/storage-receiving-api.md
liufumingren 77435aeb79 1
2026-06-23 18:48:33 +08:00

17 KiB
Raw Blame History

收货单 API 文档(storage.receiving)

1. 文档说明

本文档补充 storage.receiving 相关 system 方法中的收货明细商品绑定接口,当前重点覆盖:

  • storage.receiving.bindDetailProduct

适用场景:

  • 新增收货单明细后,为该明细绑定系统商品
  • 已绑定商品时,改绑为另一个系统商品
  • 前端或第三方系统对接收货单明细与系统商品的匹配动作

2. 统一调用方式

该项目的 system 方法统一通过 /system 调用,方法名通过 query 参数 method 传入。

请求方式

POST /system?method=storage.receiving.bindDetailProduct&v=1.0&timestamp={unix_timestamp}
Content-Type: application/json
Authorization: Bearer <token>
platform: web
project: wms

调用示例

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 请求体示例

{
  "detail_id": 12345,
  "system_product_id": 67890
}

4. 成功返回示例

{
  "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> 服务内部异常

失败响应示例

{
  "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 步新增明细后,一般会返回:

{
  "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 请求示例

{
  "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 中包含基础标识与关键展示字段:

{
  "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 返回示例(成功)

{
  "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,用于下游系统或前端展示箱内余量与实测箱重。通知示例(结构化示例,字段以实现为准):

{
  "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 单一收货单快捷入库,功能受限 storage.inventory.matchPutaway(支持多收货单+多入库单批量匹配入库)

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:已弃用,不再写入新数据(旧方案:明细级绑定)
  • 收货单与入库单不再需要逐明细绑定,通过主表关联即可完成匹配入库