# 消息通知事件 API 文档(独立于 system) ## 1. 文档说明 本文档描述 **WMS 对外消息通知能力** 的事件 API 约定。 特点: - **独立于 `/system` 接口** - 不走 `method=xxx` 的 system 调用方式 - 由内部业务在关键节点触发 `event` - 通过 WebHook 向外部系统推送标准 JSON 消息 当前已落地事件: - `receiving_completed`:收货完成通知 - `order_cancel_intercepted`:订单取消失败并触发拦截执行通知 - `store_warehouse_print_quantity_adjusted`:货主面单余额人工调整通知 --- ## 2. 触发方式 内部业务在以下位置触发: - 文件:`app/service/systems/storage/receiving.js` - 方法:`completeReceiving()` - 通知方法:`sendCompletionNotice()` 触发时机: 1. 收货单状态更新为 `completed` 2. 收货完成 Excel 报表上传成功或已生成完成结果 3. 调用: ```js await ctx.service.systems.notice.send({ businessName: 'receiving', event: 'receiving_completed', ... }) ``` --- ## 3. 事件命名规则 本能力中,**事件名本身就是通知方法标识**。 示例: | event | 含义 | |---|---| | `receiving_completed` | 收货单完成通知 | | `order_cancel_intercepted` | 订单取消失败并触发拦截执行通知 | | `store_warehouse_print_quantity_adjusted` | 货主面单余额人工调整通知 | > 当前正式注册的业务事件包括 `receiving_completed`、`order_cancel_intercepted`、`store_warehouse_print_quantity_adjusted`。 对于外部订阅方来说,判断消息类型时,优先看: - `event` - `businessName` - `message.type` 命名约束: - 仅允许小写字母、数字、下划线 - 首字符不能为数字 - **禁止使用 `.`** --- ## 4. 当前已落地事件:`receiving_completed` ### 4.1 业务含义 当仓库完成一张收货单时,系统会向绑定的 WebHook 推送一条 `receiving_completed` 通知。 ### 4.2 推送目标 由 `wms_notification_webhook` 决定: - 先匹配仓库 `warehouseId` 绑定的接口 - 若传了 `storeId / ownerId`,再匹配货主绑定的接口 - `events` 命中以下任一规则即可推送: - `all` - `*` - `receiving_completed` --- ## 5. 请求方式 对外固定使用: ```http POST Content-Type: application/json ``` --- ## 6. 收货完成通知 payload ### 6.1 字段说明 | 字段 | 类型 | 说明 | |---|---|---| | `traceId` | `string` | 通知追踪 ID | | `event` | `string` | 固定为 `receiving_completed` | | `businessName` | `string` | 固定为 `receiving` | | `warehouseId` | `number` | 仓库 ID | | `storeId` | `number \| null` | 货主 ID,可为空 | | `businessId` | `number` | 收货单 ID | | `occurredAt` | `string` | 发生时间,ISO 格式 | | `subject` | `object` | 当前主体(仓库) | | `store` | `object` | 货主信息 | | `sender` | `object` | 操作人信息 | | `receivers` | `array` | 接收者占位 | | `message` | `object` | 消息主体 | | `metadata` | `object` | 业务扩展信息 | ### 6.2 示例(带完成报表) ```json { "traceId": "notice_1775368780099_c6fb8643", "event": "receiving_completed", "businessName": "receiving", "warehouseId": 100000, "storeId": 200000, "businessId": 12345, "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": { "id": 10001, "name": "张三" }, "receivers": [], "message": { "type": "file", "title": "收货单RCV202604050001已完成", "content": "收货单RCV202604050001已完成,匹配商品10件,未匹配商品0件,总数量120,完成人张三。", "url": "https://cdn.example.com/收货完成_RCV202604050001.xlsx", "fileName": "收货完成_RCV202604050001.xlsx", "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "body": "收货单RCV202604050001已完成,匹配商品10件,未匹配商品0件,总数量120,完成人张三。" }, "metadata": { "receivingId": 12345, "receivingNumber": "RCV202604050001", "warehouseId": 100000, "storeId": 200000, "stats": { "total_details": 10, "matched_details": 10, "unmatched_details": 0, "total_quantity": 120 }, "completionReport": { "fileKey": "收货完成_RCV202604050001.xlsx", "url": "https://cdn.example.com/收货完成_RCV202604050001.xlsx" } } } ``` --- ## 7. 返回值约定 针对当前旧回调接口的约定: - 返回 `1` = **成功** - 返回 `0` = **失败** --- ## 8. 当前可信结论 已验证: - `GET` 调用旧接口地址可返回 `1` - `POST {}` 可返回 `1` - 手工最小 probe JSON 可返回 `1` 因此: > 若 `receiving_completed` 的统一通知实际推送触发远端错误,优先判断为 **payload 字段结构差异导致的远端解析异常**。 --- ## 9. 当前已落地事件:`store_warehouse_print_quantity_adjusted` ### 9.1 业务含义 当仓库侧对某个货主签约关系执行人工面单余额调整后,系统会向相关 WebHook 推送一条 `store_warehouse_print_quantity_adjusted` 通知。 ### 9.2 推送目标 由 `wms_notification_webhook` 决定: - 匹配签约仓库 `warehouseId` 绑定的接口 - 若签约中带有 `storeId`,同步匹配货主绑定的接口 - `events` 命中以下任一规则即可推送: - `all` - `*` - `store_warehouse_print_quantity_adjusted` ### 9.3 metadata 关键字段 | 字段 | 类型 | 说明 | |---|---|---| | `contractId` | `number` | 签约关系 ID | | `changeType` | `string` | 当前固定为 `manual_adjust` | | `businessType` | `string \| null` | 业务类型预留字段 | | `businessId` | `number \| null` | 业务关联 ID,预留给 `wms_order_express.id` | | `changeQuantity` | `number` | 本次调整值,整数,可正可负 | | `balanceBefore` | `number` | 调整前余额 | | `balanceAfter` | `number` | 调整后余额 | | `reason` | `string` | 调整缘由 | --- ## 10. 后续事件扩展建议 下一步可继续补充: - `receiving_cancelled` - `order_cancelled` - `stock_low` - `stock_changed` - `entry_order_created` - `entry_order_completed` 保持原则: > **一个业务事件 = 一个对外通知 event**