256 lines
6.4 KiB
Markdown
256 lines
6.4 KiB
Markdown
# 消息通知事件 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**
|