WMS_MAIN/docs/notification-event-api.md
2026-04-17 19:21:57 +08:00

256 lines
6.4 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.

# 消息通知事件 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**