8.6 KiB
统一消息通知能力文档(草案)
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.jsapp/service/systems/notice/drivers/generic.jsapp/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 |
default_express_code |
默认快递编码,默认 STO |
default_platform_code |
默认平台编码,默认 TB |
4. 事件能力结构建议(独立于 /system)
当前更推荐的能力组织方式是:内部业务事件 = 对外通知方法标识,而不是先对外包装成 /system method。
推荐结构:
系统内部业务事件
-> ctx.service.systems.notice.send(options)
-> payload 归一化
-> 查找匹配的 webhook
-> 按 hook_type 选择 driver
-> 推送到外部系统
当前已落地示例:
| event | 说明 |
|---|---|
receiving_completed |
收货单完成通知 |
order_cancel_intercepted |
订单取消失败并触发拦截执行的通知 |
当前正式注册的业务事件包括
receiving_completed、order_cancel_intercepted;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,
"default_express_code": "STO",
"default_platform_code": "TB"
}
},
"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 |
只接收收货完成事件 |
order_cancel_intercepted |
只接收订单取消拦截事件 |
若需新增其他事件,必须先在
app/model/notification_webhook.js完成注册,否则发送入口会直接拒绝。
当前订单取消拦截通知由 app/service/qimenMethods/order.js 在拣货状态或打印状态未结束时发送,事件码为 order_cancel_intercepted。
8. 命中与分发规则
当前 findMatchedWebhooks(payload) 逻辑:
- 先判断
warehouseId,并查询该仓库主体绑定的启用接口 - 若
storeId / ownerId非空,再查询该货主绑定的启用接口 - 过滤条件:
status = 1events命中当前消息
- 去重规则:
- 优先按
id - 无
id时按hook_url
- 优先按
- 最终按
subject_config.max_notice_webhook_count限制最大推送数量
9. 货主信息补充与缓存
若传了 storeId / ownerId,当前会补齐货主信息:
wms_store.business_licensewms_store_warehouse.store_remask
缓存键:
warehouse:{warehouseId}store:{storeId}:info
缓存 TTL:
600 秒
查询顺序:
- 优先读缓存
- 缓存未命中再查数据库
- 查到后回填缓存
- 若为空,则推送字段也保持空字符串
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 类验证:
- notice 能力测试:确认事件注册、WebHook 命中、payload 结构与失败处理符合预期
- 参考:
test/app/service/systems/notice.test.js
- 参考:
- 业务回归测试:确认业务节点确实会触发通知调用
- 参考:
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. 后续扩展建议
建议后续继续补充:
- 通知发送日志表
- 重试队列 / 死信队列
- 回调签名与鉴权
- WebHook 健康检查
- 失败告警与监控面板
- system 接口文档同步到
methods/system.json