# 统一消息通知能力文档(草案) ## 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` | | `default_express_code` | 默认快递编码,默认 `STO` | | `default_platform_code` | 默认平台编码,默认 `TB` | --- ## 4. 事件能力结构建议(独立于 `/system`) 当前更推荐的能力组织方式是:**内部业务事件 = 对外通知方法标识**,而不是先对外包装成 `/system` method。 推荐结构: ```text 系统内部业务事件 -> 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` | 否 | 业务单据 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, "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)` 逻辑: 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`