6.2 KiB
6.2 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 |
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) 逻辑:
- 先判断
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. 后续扩展建议
建议后续继续补充:
- 通知发送日志表
- 重试队列 / 死信队列
- 回调签名与鉴权
- WebHook 健康检查
- 失败告警与监控面板
- system 接口文档同步到
methods/system.json