WMS_MAIN/docs/notification-event-api.md

4.8 KiB
Raw Blame History

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

1. 文档说明

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

特点:

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

当前第一批落地事件:

  • receiving_completed:收货完成通知

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 收货单完成通知

当前正式注册的业务事件仅保留 receiving_completed。

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

  • 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. 后续事件扩展建议

下一步可继续补充:

  • receiving_cancelled
  • stock_low
  • stock_changed
  • entry_order_created
  • entry_order_completed

保持原则:

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