264 lines
6.2 KiB
Markdown
264 lines
6.2 KiB
Markdown
# 统一消息通知能力文档(草案)
|
||
|
||
## 1. 目标
|
||
|
||
用于沉淀 WMS 统一消息通知能力的接口结构、数据模型、事件订阅规则与对外推送格式,作为后续构建“消息通知中心 / WebHook 能力”的基础文档。
|
||
|
||
---
|
||
|
||
## 2. 能力结构
|
||
|
||
当前统一发送入口:
|
||
|
||
```js
|
||
await ctx.service.systems.notice.send(options)
|
||
```
|
||
|
||
当前调用链:
|
||
|
||
```text
|
||
业务服务
|
||
-> 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。
|
||
|
||
推荐结构:
|
||
|
||
```text
|
||
系统内部业务事件
|
||
-> 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` | 否 | 业务单据 ID |
|
||
| `subject` | `object` | 否 | 主体信息 |
|
||
| `sender` | `object` | 否 | 发送者信息 |
|
||
| `receivers` | `array` | 否 | 接收者信息 |
|
||
| `metadata` | `object` | 否 | 扩展元数据 |
|
||
|
||
### 5.1 入参约束
|
||
|
||
- `warehouseId` **必传**
|
||
- `storeId / ownerId` **允许为空**
|
||
- `messageType = image / file` 时,`url` **必填**
|
||
- `event` 命名仅允许小写字母、数字、下划线,且首字符不能为数字;**禁止使用 `.`**
|
||
|
||
---
|
||
|
||
## 6. 对外统一推送 payload
|
||
|
||
当前对外固定为:`POST + application/json`
|
||
|
||
示例:
|
||
|
||
```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`
|
||
|
||
缓存键:
|
||
|
||
```text
|
||
warehouse:{warehouseId}store:{storeId}:info
|
||
```
|
||
|
||
缓存 TTL:
|
||
|
||
```text
|
||
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`
|