328 lines
8.1 KiB
Markdown
328 lines
8.1 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. 新增功能需要通知时怎么接入
|
||
|
||
当其他功能模块需要新增通知时,建议按下面 4 步接入,避免各自重复造轮子:
|
||
|
||
### 12.1 注册事件
|
||
|
||
先在 `app/model/notification_webhook.js` 的 `AVAILABLE_EVENTS` 中登记新的事件编码。
|
||
|
||
要求:
|
||
|
||
- 事件名仅允许小写字母、数字、下划线
|
||
- 首字符不能为数字
|
||
- **禁止使用 `.`**
|
||
- 未注册的事件,`notice.send()` 会直接拒绝发送
|
||
|
||
### 12.2 在业务 service 调用统一入口
|
||
|
||
在实际业务 service 中调用:
|
||
|
||
```js
|
||
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`
|