WMS_MAIN/docs/notification-webhook-capability.md

6.2 KiB
Raw Blame History

统一消息通知能力文档(草案)

1. 目标

用于沉淀 WMS 统一消息通知能力的接口结构、数据模型、事件订阅规则与对外推送格式,作为后续构建“消息通知中心 / WebHook 能力”的基础文档。


2. 能力结构

当前统一发送入口:

await ctx.service.systems.notice.send(options)

当前调用链:

业务服务
  -> ctx.service.systems.notice.send(options)
  -> normalizePayload(options)
  -> findMatchedWebhooks(payload)
  -> GenericWebhookDriver.send({ hook, payload })
  -> POST JSON 到外部 hook_url

代码位置:

  • app/service/systems/notice/index.js
  • app/service/systems/notice/drivers/generic.js
  • app/model/notification_webhook.js

3. 相关数据模型

3.1 wms_notification_webhook

用于保存主体绑定的外部 WebHook 配置。

核心字段:

字段 说明
store_id 主体 ID,可绑定到仓库主体或货主主体
hook_name WebHook 名称
hook_type WebHook 类型,当前支持 customize / wecom
hook_url 推送目标地址
events 订阅事件列表
status 状态,1=启用,0=禁用
remark 备注

3.2 wms_store.subject_config

用于保存主体级通知配置。

当前已使用字段:

字段 说明
max_notice_webhook_count 当前主体最多允许绑定 / 触达的消息推送接口数量,默认 5

4. 事件能力结构建议(独立于 /system)

当前更推荐的能力组织方式是:内部业务事件 = 对外通知方法标识,而不是先对外包装成 /system method。

推荐结构:

系统内部业务事件
  -> ctx.service.systems.notice.send(options)
    -> payload 归一化
    -> 查找匹配的 webhook
    -> 按 hook_type 选择 driver
    -> 推送到外部系统

当前已落地示例:

event 说明
receiving_completed 收货单完成通知

当前正式注册的业务事件仅保留 receiving_completed;all / * 作为通配订阅值继续保留。收货完成事件的独立 API 文档见:docs/notification-event-api.md。


5. 对内统一发送入参

notice.send(options) 推荐入参如下:

参数 类型 必填 说明
warehouseId number 是 仓库 ID
storeId number 否 货主 ID,可空
ownerId number 否 货主 ID 别名,可空
businessName string 是 业务名称,如 receiving
event string 否 具体事件,如 receiving_completed
messageType string 是 text / image / file,兼容中文
title string 否 消息标题
content string/object 否 消息正文
url string 条件必填 图片 / 文件类型时必填
businessId `number string` 否
subject object 否 主体信息
sender object 否 发送者信息
receivers array 否 接收者信息
metadata object 否 扩展元数据

5.1 入参约束

  • warehouseId 必传
  • storeId / ownerId 允许为空
  • messageType = image / file 时,url 必填
  • event 命名仅允许小写字母、数字、下划线,且首字符不能为数字;禁止使用 .

6. 对外统一推送 payload

当前对外固定为:POST + application/json

示例:

{
  "traceId": "notice_xxx",
  "event": "receiving_completed",
  "businessName": "receiving",
  "warehouseId": 100000,
  "storeId": 200000,
  "businessId": 123,
  "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": {},
  "receivers": [],
  "message": {
    "type": "text",
    "title": "收货完成",
    "content": "收货单已完成",
    "url": "",
    "fileName": "",
    "mimeType": "",
    "body": "收货单已完成"
  },
  "metadata": {
    "source": "system"
  }
}

7. 事件订阅规则

events 字段建议使用数组。

支持写法:

写法 含义
all 接收全部已注册通知
* 兼容旧配置,等价于 all
receiving_completed 只接收收货完成事件

若需新增其他事件,必须先在 app/model/notification_webhook.js 完成注册,否则发送入口会直接拒绝。


8. 命中与分发规则

当前 findMatchedWebhooks(payload) 逻辑:

  1. 先判断 warehouseId,并查询该仓库主体绑定的启用接口
  2. 若 storeId / ownerId 非空,再查询该货主绑定的启用接口
  3. 过滤条件:
    • status = 1
    • events 命中当前消息
  4. 去重规则:
    • 优先按 id
    • 无 id 时按 hook_url
  5. 最终按 subject_config.max_notice_webhook_count 限制最大推送数量

9. 货主信息补充与缓存

若传了 storeId / ownerId,当前会补齐货主信息:

  • wms_store.business_license
  • wms_store_warehouse.store_remask

缓存键:

warehouse:{warehouseId}store:{storeId}:info

缓存 TTL:

600 秒

查询顺序:

  1. 优先读缓存
  2. 缓存未命中再查数据库
  3. 查到后回填缓存
  4. 若为空,则推送字段也保持空字符串

10. 回调返回值约定

对于现有旧接口(如 notic、notic2)的可信判定约定:

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

11. 当前可信结论

已验证:

  • GET 请求可通
  • POST 请求可通
  • POST {} 可返回 1
  • 手工最小 probe payload 可返回 1

因此:

若统一 notice.send() 的实际推送触发远端报错,优先判断为 payload 字段结构差异导致的远端解析问题,而不是地址或请求方式问题。


12. 后续扩展建议

建议后续继续补充:

  1. 通知发送日志表
  2. 重试队列 / 死信队列
  3. 回调签名与鉴权
  4. WebHook 健康检查
  5. 失败告警与监控面板
  6. system 接口文档同步到 methods/system.json