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

8.1 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. 新增功能需要通知时怎么接入

当其他功能模块需要新增通知时,建议按下面 4 步接入,避免各自重复造轮子:

12.1 注册事件

先在 app/model/notification_webhook.js 的 AVAILABLE_EVENTS 中登记新的事件编码。

要求:

  • 事件名仅允许小写字母、数字、下划线
  • 首字符不能为数字
  • 禁止使用 .
  • 未注册的事件,notice.send() 会直接拒绝发送

12.2 在业务 service 调用统一入口

在实际业务 service 中调用:

await ctx.service.systems.notice.send({
  warehouseId,
  storeId, // 可选,也可传 ownerId
  businessName: 'your_business',
  event: 'your_event_code',
  messageType: 'text',
  title: '通知标题',
  content: '通知内容',
  businessId,
  subject,
  sender,
  metadata,
});

接入原则:

  • warehouseId 必传,storeId / ownerId 可空
  • 业务侧只负责组装业务语义并调用统一入口
  • 重试、分发、失败日志由 app/service/systems/notice/index.js 统一处理
  • 如需图片 / 文件通知,补充 url、fileName、mimeType

12.3 测试验证

至少补 2 类验证:

  1. notice 能力测试:确认事件注册、WebHook 命中、payload 结构与失败处理符合预期
    • 参考:test/app/service/systems/notice.test.js
  2. 业务回归测试:确认业务节点确实会触发通知调用
    • 参考:test/app/service/systems/storage.receiving.report.test.js

若对接的是外部地址,还应额外确认:

  • 返回结果是否符合成功约定(如 1 / ok / errcode=0)
  • 对方是否能正确解析当前 JSON payload

12.4 文档同步

接入完成后,至少同步以下文档:

  • 本文档:补能力边界、接入规则或命中说明
  • docs/notification-event-api.md:新增事件说明与 payload 示例
  • 若对外暴露了新的 /system 接口或 method,再按需同步 methods/*.json

13. 后续扩展建议

建议后续继续补充:

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