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

328 lines
8.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 统一消息通知能力文档(草案)
## 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`