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

6.1 KiB
Raw Blame History

消息通知事件 API 文档(独立于 system)

1. 文档说明

本文档描述 WMS 对外消息通知能力 的事件 API 约定。

特点:

  • 独立于 /system 接口
  • 不走 method=xxx 的 system 调用方式
  • 由内部业务在关键节点触发 event
  • 通过 WebHook 向外部系统推送标准 JSON 消息

当前已落地事件:

  • receiving_completed:收货完成通知
  • store_warehouse_print_quantity_adjusted:货主面单余额人工调整通知

2. 触发方式

内部业务在以下位置触发:

  • 文件:app/service/systems/storage/receiving.js
  • 方法:completeReceiving()
  • 通知方法:sendCompletionNotice()

触发时机:

  1. 收货单状态更新为 completed
  2. 收货完成 Excel 报表上传成功或已生成完成结果
  3. 调用:
await ctx.service.systems.notice.send({
  businessName: 'receiving',
  event: 'receiving_completed',
  ...
})

3. 事件命名规则

本能力中,事件名本身就是通知方法标识。

示例:

event 含义
receiving_completed 收货单完成通知
store_warehouse_print_quantity_adjusted 货主面单余额人工调整通知

当前正式注册的业务事件包括 receiving_completed、store_warehouse_print_quantity_adjusted。

对于外部订阅方来说,判断消息类型时,优先看:

  • event
  • businessName
  • message.type

命名约束:

  • 仅允许小写字母、数字、下划线
  • 首字符不能为数字
  • 禁止使用 .

4. 当前已落地事件:receiving_completed

4.1 业务含义

当仓库完成一张收货单时,系统会向绑定的 WebHook 推送一条 receiving_completed 通知。

4.2 推送目标

由 wms_notification_webhook 决定:

  • 先匹配仓库 warehouseId 绑定的接口
  • 若传了 storeId / ownerId,再匹配货主绑定的接口
  • events 命中以下任一规则即可推送:
    • all
    • *
    • receiving_completed

5. 请求方式

对外固定使用:

POST
Content-Type: application/json

6. 收货完成通知 payload

6.1 字段说明

字段 类型 说明
traceId string 通知追踪 ID
event string 固定为 receiving_completed
businessName string 固定为 receiving
warehouseId number 仓库 ID
storeId number | null 货主 ID,可为空
businessId number 收货单 ID
occurredAt string 发生时间,ISO 格式
subject object 当前主体(仓库)
store object 货主信息
sender object 操作人信息
receivers array 接收者占位
message object 消息主体
metadata object 业务扩展信息

6.2 示例(带完成报表)

{
  "traceId": "notice_1775368780099_c6fb8643",
  "event": "receiving_completed",
  "businessName": "receiving",
  "warehouseId": 100000,
  "storeId": 200000,
  "businessId": 12345,
  "occurredAt": "2026-04-05T12:00:00.000Z",
  "subject": {
    "id": 100000,
    "type": "warehouse",
    "name": "广州仓",
    "code": "",
    "config": {
      "max_notice_webhook_count": 5
    }
  },
  "store": {
    "id": 200000,
    "name": "某货主",
    "businessLicense": "9144XXXXXXXXXXXX",
    "storeRemask": "华南货主"
  },
  "sender": {
    "id": 10001,
    "name": "张三"
  },
  "receivers": [],
  "message": {
    "type": "file",
    "title": "收货单RCV202604050001已完成",
    "content": "收货单RCV202604050001已完成,匹配商品10件,未匹配商品0件,总数量120,完成人张三。",
    "url": "https://cdn.example.com/收货完成_RCV202604050001.xlsx",
    "fileName": "收货完成_RCV202604050001.xlsx",
    "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    "body": "收货单RCV202604050001已完成,匹配商品10件,未匹配商品0件,总数量120,完成人张三。"
  },
  "metadata": {
    "receivingId": 12345,
    "receivingNumber": "RCV202604050001",
    "warehouseId": 100000,
    "storeId": 200000,
    "stats": {
      "total_details": 10,
      "matched_details": 10,
      "unmatched_details": 0,
      "total_quantity": 120
    },
    "completionReport": {
      "fileKey": "收货完成_RCV202604050001.xlsx",
      "url": "https://cdn.example.com/收货完成_RCV202604050001.xlsx"
    }
  }
}

7. 返回值约定

针对当前旧回调接口的约定:

  • 返回 1 = 成功
  • 返回 0 = 失败

8. 当前可信结论

已验证:

  • GET 调用旧接口地址可返回 1
  • POST {} 可返回 1
  • 手工最小 probe JSON 可返回 1

因此:

若 receiving_completed 的统一通知实际推送触发远端错误,优先判断为 payload 字段结构差异导致的远端解析异常。


9. 当前已落地事件:store_warehouse_print_quantity_adjusted

9.1 业务含义

当仓库侧对某个货主签约关系执行人工面单余额调整后,系统会向相关 WebHook 推送一条 store_warehouse_print_quantity_adjusted 通知。

9.2 推送目标

由 wms_notification_webhook 决定:

  • 匹配签约仓库 warehouseId 绑定的接口
  • 若签约中带有 storeId,同步匹配货主绑定的接口
  • events 命中以下任一规则即可推送:
    • all
    • *
    • store_warehouse_print_quantity_adjusted

9.3 metadata 关键字段

字段 类型 说明
contractId number 签约关系 ID
changeType string 当前固定为 manual_adjust
businessType string | null 业务类型预留字段
businessId number | null 业务关联 ID,预留给 wms_order_express.id
changeQuantity number 本次调整值,整数,可正可负
balanceBefore number 调整前余额
balanceAfter number 调整后余额
reason string 调整缘由

10. 后续事件扩展建议

下一步可继续补充:

  • receiving_cancelled
  • stock_low
  • stock_changed
  • entry_order_created
  • entry_order_completed

保持原则:

一个业务事件 = 一个对外通知 event