442 lines
19 KiB
Markdown
442 lines
19 KiB
Markdown
# 站内信(Inbox)模块设计方案
|
||
|
||
> **状态**: 📋 设计中
|
||
> **设计日期**: 2026-08-03
|
||
> **设计人**: wms-test-agent
|
||
> **模块**: `app/service/inbox/`,独立文件模块
|
||
> **表**: 1 张 — `wms_inbox_message`
|
||
|
||
---
|
||
|
||
## 一、概念
|
||
|
||
消息推送状态追踪表。不重复存储消息内容(消息体由 IM 回调 / API 请求各自管理),只记录**谁发来的、要推到哪、推送状态**。收件(inbound)和回信(outbound)共表,`direction` + `parent_id` 形成对话链。
|
||
|
||
```
|
||
inbound(外部 → WMS) outbound(WMS → 外部)
|
||
┌──────────────────────┐ ┌──────────────────────┐
|
||
│ IM 回调 / API push │ │ 系统回信 / 工单通知 │
|
||
└──────────┬───────────┘ └──────────┬───────────┘
|
||
│ │
|
||
▼ ▼
|
||
┌─────────────────────────────────────────┐
|
||
│ wms_inbox_message(同一张表) │
|
||
│ │
|
||
│ direction: inbound │ outbound │
|
||
│ parent_id: NULL │ parent_id: 原消息ID │
|
||
│ │
|
||
│ "IM msg_001 → API app_10 → success" │
|
||
│ "WMS 回复 → 企微 Bot → success" │
|
||
└─────────────────────────────────────────┘
|
||
│
|
||
▼ setImmediate async push
|
||
dispatch → HTTP POST / Bot API
|
||
```
|
||
|
||
---
|
||
|
||
## 二、数据库表
|
||
|
||
### `wms_inbox_message`
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| `id` | `BIGINT UNSIGNED` | ✅ | AUTO | 主键 |
|
||
| `ext_id` | `VARCHAR(128)` | ✅ | — | **外部唯一消息主键**(IM msgId / API requestId 等),唯一索引,幂等去重 |
|
||
| `warehouse_id` | `BIGINT UNSIGNED` | ✅ | — | 所属仓库 |
|
||
| `store_id` | `BIGINT UNSIGNED` | — | NULL | 关联货主 |
|
||
| `direction` | `VARCHAR(10)` | ✅ | `inbound` | `inbound`=外部→WMS 收件 / `outbound`=WMS→外部 回信 |
|
||
| `parent_id` | `BIGINT UNSIGNED` | — | NULL | 关联消息 ID(回信时指向原消息,形成对话链) |
|
||
|
||
#### 来源 / 目标
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `source_type` | `VARCHAR(20)` | ✅ | `im` / `api` |
|
||
| `source_extra` | `VARCHAR(100)` | — | 附加信息(IM 平台 / API app_id) |
|
||
| `target_type` | `VARCHAR(20)` | ✅ | `im` / `api` |
|
||
| `target_channel` | `VARCHAR(50)` | ✅ | 目标渠道:`wecom` / `dingtalk` / `feishu` / `warehouse_api` / `webhook` |
|
||
| `target_url` | `VARCHAR(500)` | ✅ | 推送目标 URL(IM Bot webhook 地址 / API 回调地址) |
|
||
|
||
> **安全设计**:
|
||
> - `target_url` 不含 secret。IM Bot URL 中 token 已内嵌,API 推送时 secret 从 `ApiApp.self_app_secret` 查。
|
||
> - **出站签名**:推送到仓库开放 API 时,使用与该仓库 ApiApp 相同的 MD5 签名算法(`canonicalQuery + self_app_secret + bodySign`),接收方用同一 `app_key` 验证。IM 通道则使用各自 Bot 的原生鉴权。
|
||
|
||
> **inbound vs outbound 的 source/target 语义**:
|
||
> ```
|
||
> inbound(外部→WMS):source=外部来源 target=WMS 内部要转发到的渠道
|
||
> outbound(WMS→外部):source=WMS 内部 target=要推送到的外部渠道
|
||
> ```
|
||
| `ref_code` | `VARCHAR(100)` | — | 外部引用编码,推送/回执时原样携带 |
|
||
| `ext_data` | `JSON` | — | **外部透传数据**,外部传入任意 JSON,WMS 不解析,回信时原样返回 |
|
||
| `flags` | `JSON` | — | **处理标记**,外部传入控制 WMS 处理行为,见下表 |
|
||
|
||
> **`flags` 支持的标记**:
|
||
> ```json
|
||
> {
|
||
> "skip_ai_parse": true, // 跳过智能解析(内部员工发信时设为 true)
|
||
> "skip_auto_reply": true, // 跳过自动回复
|
||
> "skip_forward": true // 仅存档,不转发
|
||
> }
|
||
> ```
|
||
> 外部不传 → 默认全部开启(智能解析 + 自动回复 + 转发)。内部系统调用 `inbox.push` 时按需关闭特定行为。
|
||
|
||
#### 推送状态
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| `push_status` | `TINYINT(4)` | ✅ | 0 | 0=待推送 1=推送中 2=已送达 3=失败 |
|
||
| `push_started_at` | `DATETIME` | — | NULL | 开始推送时间(僵尸检测:超 5 分钟仍为 1 → 重置为 0) |
|
||
| `retry_count` | `INT(11)` | ✅ | 0 | 已重试次数 |
|
||
| `push_response` | `JSON` | — | NULL | 目标响应(http_status, body, error) |
|
||
| `pushed_at` | `DATETIME` | — | NULL | 推送完成时间 |
|
||
|
||
> **防重机制**:`push_status` 字段本身即状态流转,不需要额外流转表。使用乐观锁 `UPDATE SET push_status=1 WHERE push_status=0` 保证单条消息不会被重复取走。`push_started_at` 用于进程崩溃后的僵尸恢复。
|
||
|
||
#### 关联(后续)
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `work_order_id` | `BIGINT UNSIGNED` | — | 🔮 关联工单 |
|
||
| `work_order_no` | `VARCHAR(50)` | — | 🔮 工单号 |
|
||
|
||
#### 时间
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| `created_at` | `DATETIME` | ✅ | CURRENT_TIMESTAMP | |
|
||
| `updated_at` | `DATETIME` | ✅ | CURRENT_TIMESTAMP ON UPDATE | |
|
||
| `deleted_at` | `DATETIME` | — | NULL | 软删除 |
|
||
|
||
### 索引
|
||
|
||
| 索引名 | 字段 | 用途 |
|
||
|--------|------|------|
|
||
| `PRIMARY` | `id` | — |
|
||
| `uk_ext_id` | `ext_id` UNIQUE | 外部幂等去重 |
|
||
| `idx_warehouse_status` | `warehouse_id, push_status` | 按仓库+状态查询 |
|
||
| `idx_warehouse_direction` | `warehouse_id, direction, created_at` | 收件/回信列表 |
|
||
| `idx_parent` | `parent_id` | 对话链查询 |
|
||
| `idx_created_at` | `created_at` | 时间范围 |
|
||
|
||
> **`ext_id` 唯一键防碰撞**:不同来源的消息 ID 可能重复(IM msgId 与 API requestId 撞车)。入库时按来源加前缀:
|
||
> ```
|
||
> IM 消息: ext_id = `im:wecom:${msg.msgId}`
|
||
> API 消息: ext_id = `api:${apiAppId}:${body.requestId}`
|
||
> 系统回信: ext_id = `sys:${uuid}`
|
||
> ```
|
||
> 前缀保证不同来源的消息不会因 ID 相同而误判为重复。
|
||
|
||
> **容量规划**:`BIGINT UNSIGNED` 主键容量无限。单表 InnoDB 建议 ≤ 5000 万行。以 100 仓 × 日均 5000 条 = 日 50 万条计,达到上限需 ~100 天。届时加 `PARTITION BY HASH(warehouse_id) PARTITIONS 16` 即可水平扩展,无需分库分表,代码零改动。
|
||
|
||
### 安全边界(强制)
|
||
|
||
| 边界 | 规则 |
|
||
|------|------|
|
||
| **warehouse_id 归属** | 禁止外部传入。IM 路径从回调解析获取,API 路径从验签后 `ctx.warehouseId` 获取 |
|
||
| **ext_id 前缀** | `im:{platform}:{msgId}` / `api:{appId}:{requestId}` / `sys:{uuid}`,receiver 入站时统一格式 |
|
||
| **target_url SSRF** | 仅允许 `https://`,禁止内网 IP(127.0.0.1/10.x/172.16-31.x/192.168.x) |
|
||
| **dispatch 超时** | HTTP 请求超时 10s,超时视为失败进入重试 |
|
||
| **setImmediate 异常** | `try/catch` 包裹,异常写入 `push_response.error`,`push_status=3` |
|
||
| **target_channel 校验** | `dispatch[channel]` 不存在时返回明确错误,不静默丢弃 |
|
||
| **僵尸恢复** | 启动时 + 每 5 分钟定时执行 `UPDATE push_status=0 WHERE push_status=1 AND push_started_at < NOW()-5MIN` |
|
||
| **推送 body 大小** | 限制 64KB,超限拒绝写入 |
|
||
|
||
---
|
||
|
||
## 三、推送流程
|
||
|
||
```
|
||
receiver.receive()
|
||
│
|
||
├─ 1. 幂等检查(ext_id 已存在 → 直接返回)
|
||
├─ 2. INSERT(push_status=0)
|
||
└─ 3. setImmediate(() => asyncPush(record))
|
||
│
|
||
├─ UPDATE push_status=1(推送中)
|
||
├─ dispatch(target_channel, target_url)
|
||
│ ├─ 成功 → UPDATE push_status=2, pushed_at=NOW()
|
||
│ └─ 失败 → retry_count++
|
||
│ ├─ < 3 次 → setTimeout(delay, asyncPush) 指数退避重试
|
||
│ └─ ≥ 3 次 → UPDATE push_status=3(终态)
|
||
└─ 返回
|
||
```
|
||
|
||
**指数退避**:30s → 60s → 120s,最多重试 3 次。
|
||
|
||
**关键**:不依赖定时任务轮询,利用 Node.js 事件循环的 `setImmediate` + `setTimeout` 在同一个进程内异步完成推送与重试。
|
||
|
||
---
|
||
|
||
## 四、两个接收入口
|
||
|
||
### IM 消息入站
|
||
|
||
```
|
||
企微/钉钉/飞书 Bot 回调 → receiver.receive({
|
||
// warehouse_id 由 IM 回调解析 / 签名验证后从上下文获取,不外部传入
|
||
source_type: 'im',
|
||
ext_id: `im:wecom:${msg.msgId}`,
|
||
source_extra: 'wecom',
|
||
|
||
target_type: 'api',
|
||
target_channel: 'warehouse_api',
|
||
target_url: 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx',
|
||
ref_code: msg.userId,
|
||
ext_data: { conversation_id: msg.conversationId },
|
||
flags: {},
|
||
|
||
warehouse_id: ctx.warehouseId, // ← 来自鉴权上下文,非外部传入
|
||
})
|
||
```
|
||
|
||
### 仓库 API 消息入站
|
||
|
||
```
|
||
POST /warehouse?method=inbox.push → receiver.receive({
|
||
// warehouse_id 由仓库 API 验签后从 ApiApp 解析,不外部传入
|
||
source_type: 'api',
|
||
ext_id: `api:${ctx.apiAppId}:${body.requestId}`,
|
||
source_extra: String(ctx.apiAppId),
|
||
|
||
target_type: 'im',
|
||
target_channel: body.targetChannel || 'wecom',
|
||
target_url: body.targetUrl,
|
||
ref_code: body.refCode,
|
||
ext_data: body.extData,
|
||
flags: body.flags || {},
|
||
|
||
warehouse_id: ctx.warehouseId, // ← 来自鉴权上下文,非外部传入
|
||
})
|
||
```
|
||
|
||
### 系统回信(outbound)
|
||
|
||
```
|
||
WMS 内部(工单通知/状态更新)→ receiver.reply({
|
||
parent_id: 1, // 原消息 ID
|
||
target_type: 'im',
|
||
target_channel: 'wecom',
|
||
target_url: 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx',
|
||
ref_code: 'TICKET-001',
|
||
ext_data: { ... }, // 继承原消息 ext_data
|
||
|
||
warehouse_id: ctx.warehouseId, // ← WMS 内部上下文
|
||
})
|
||
// 自动写入 direction=outbound, parent_id=1
|
||
// 推送成功后,可通过 inbox.thread 查完整对话链
|
||
```
|
||
|
||
---
|
||
|
||
## 五、API
|
||
|
||
### 5.1 内部管理 (`inbox.*`)
|
||
|
||
| method | 说明 |
|
||
|--------|------|
|
||
| `inbox.list` | 消息列表(`direction` 区分收件/回信) |
|
||
| `inbox.detail` | 消息详情(含 push_response) |
|
||
| `inbox.thread` | 对话链(原消息 + 所有回信) |
|
||
| `inbox.reply` | 系统回信(写入 outbound 记录 + 异步推送) |
|
||
| `inbox.retry` | 手动重推 |
|
||
| `inbox.stats` | 推送统计 |
|
||
|
||
### 5.2 仓库 API (`inbox.push`)
|
||
|
||
`POST /warehouse?method=inbox.push`
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `body.sourceType` | `string` | ✅ | 来源类型:`im` / `api` |
|
||
| `body.sourceChannel` | `string` | — | 来源渠道(IM 平台 / API 标识) |
|
||
| `body.requestId` | `string` | ✅ | 来源请求 ID(组成 ext_id) |
|
||
| `body.targetChannel` | `string` | ✅ | 目标渠道 |
|
||
| `body.targetUrl` | `string` | ✅ | 推送目标 URL |
|
||
| `body.refCode` | `string` | — | 引用编码 |
|
||
| `body.extData` | `object` | — | 透传数据 |
|
||
| `body.flags` | `object` | — | 处理标记 `{ skip_ai_parse, skip_auto_reply, skip_forward }` |
|
||
| `body.storeId` | `number` | — | 关联货主 |
|
||
|
||
---
|
||
|
||
## 六、异步推送实现
|
||
|
||
不启动独立 consumer,利用 Egg.js / Node.js 原生异步能力:
|
||
|
||
```javascript
|
||
// receiver.js
|
||
async receive(data) {
|
||
// 1. 幂等检查
|
||
const exist = await this.ctx.model.InboxMessage.findOne({
|
||
where: { ext_id: data.ext_id },
|
||
});
|
||
if (exist) return { ok: true, id: exist.id, ext_id: data.ext_id };
|
||
|
||
// 2. 写入记录
|
||
const record = await this.ctx.model.InboxMessage.create({
|
||
ext_id: data.ext_id,
|
||
warehouse_id: data.warehouse_id,
|
||
source_type: data.source_type,
|
||
source_extra: data.source_extra,
|
||
target_type: data.target_type,
|
||
target_channel: data.target_channel,
|
||
target_url: data.target_url,
|
||
ref_code: data.ref_code,
|
||
ext_data: data.ext_data,
|
||
flags: data.flags || {},
|
||
push_status: 0,
|
||
});
|
||
|
||
// 3. 异步后台推送(不阻塞响应)
|
||
setImmediate(() => this.asyncPush(record));
|
||
|
||
return { ok: true, id: record.id, ext_id: data.ext_id };
|
||
}
|
||
|
||
async asyncPush(record, attempt = 0) {
|
||
// 乐观锁:仅 push_status=0 时可取走,防重
|
||
const [ updated ] = await InboxMessage.update(
|
||
{ push_status: 1, push_started_at: new Date() },
|
||
{ where: { id: record.id, push_status: attempt === 0 ? 0 : 3 } }
|
||
);
|
||
if (!updated) return; // 已被其他进程取走
|
||
|
||
try {
|
||
// API 渠道:用仓库 ApiApp 生成 MD5 签名,接收方同密钥验证
|
||
const payload = { ref_code: record.ref_code, ext_data: record.ext_data };
|
||
const signedUrl = record.target_type === 'api'
|
||
? await this.signRequest(record, payload)
|
||
: record.target_url;
|
||
|
||
const res = await this.ctx.service.inbox.dispatch[record.target_channel].push(
|
||
signedUrl, payload
|
||
);
|
||
await record.update({
|
||
push_status: 2,
|
||
push_response: { http_status: res.status, body: res.data },
|
||
pushed_at: new Date(),
|
||
});
|
||
} catch (err) {
|
||
const next = attempt + 1;
|
||
await record.update({ push_status: 3, retry_count: next, push_response: { error: err.message } });
|
||
|
||
if (next < 3) {
|
||
const delay = 30000 * Math.pow(2, attempt); // 30s → 60s → 120s
|
||
setTimeout(() => this.asyncPush(record, next), delay);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**不需要**:定时任务、消息队列、独立 worker 进程。
|
||
|
||
> **僵尸恢复**:进程崩溃导致 `push_status=1` 的记录卡死时,启动时执行 `UPDATE SET push_status=0 WHERE push_status=1 AND push_started_at < NOW() - INTERVAL 5 MINUTE` 即可复活。
|
||
|
||
> **出站签名**:推送到 `target_type=api` 时,使用仓库 ApiApp 的 `self_app_secret` 生成 MD5 签名附加到 URL query:
|
||
> ```
|
||
> signedUrl = target_url
|
||
> + '?app_key=' + apiApp.self_app_key
|
||
> + '×tamp=' + now
|
||
> + '&sign=' + md5(queryString + self_app_secret + md5(body))
|
||
> ```
|
||
> 接收方(仓库开放侧)可用同一 `app_key` 调用 `apiSignLib.verifyRequestSign()` 验证。IM 通道(wecom/dingtalk/feishu)使用各自 Bot 原生鉴权,不走此签名。
|
||
|
||
---
|
||
|
||
## 七、模块结构
|
||
|
||
**分层原则**:API 入口只做校验与签名,统一委托 `app/service/inbox/` 处理写库与推送逻辑。`methods/` 仅放接口定义,不放业务代码。
|
||
|
||
```
|
||
入口层(校验 + 签名) 统一处理层(写库 + 推送) 数据层
|
||
────────────────────────── ────────────────────────── ──────
|
||
app/controller/ app/service/inbox/ app/model/
|
||
im.js ─────────────┐ ┌─ receiver.js inbox_message.js
|
||
warehouse.js ──────┤ │ 统一接收(幂等去重) ↑
|
||
├──调用──→ │ 写库(INSERT) │
|
||
app/service/im.js ─┘ │ 异步推送(setImmediate) │
|
||
│ │ 重试(setTimeout 指数退避) │
|
||
│ │ │
|
||
│ ├─ index.js │
|
||
│ │ 列表/详情/重推/统计 │
|
||
│ │ │
|
||
│ └─ dispatch/ │
|
||
│ base.js ← 统一出站:查 ApiApp、取密钥、签名、发 HTTP │
|
||
│ webhook.js ← 继承 base,HTTP POST │
|
||
│ wecom.js ← 继承 base,企微 Bot │
|
||
│ dingtalk.js ← 继承 base,钉钉 Bot │
|
||
│ feishu.js ← 继承 base,飞书 Bot │
|
||
│ │
|
||
methods/ (仅接口定义,不放逻辑) │
|
||
warehouse.json ← inbox.push 参数声明 │
|
||
system.json ← inbox.* 参数声明 │
|
||
```
|
||
|
||
> **关键**:`app/service/inbox/` 是独立的统一处理目录,所有写库、推送、重试逻辑集中在此。后续新增渠道只需在 `dispatch/` 下加一个文件,不影响其他层。
|
||
|
||
### 统一出站基类 `dispatch/base.js`
|
||
|
||
所有渠道 dispatch 继承此基类,统一处理查密钥、签名、发 HTTP:
|
||
|
||
```javascript
|
||
// dispatch/base.js
|
||
class OutboundBase {
|
||
constructor(ctx) { this.ctx = ctx; }
|
||
|
||
// 获取仓库 ApiApp 密钥(IM 渠道无需签名,返回 null)
|
||
async getApiApp(warehouseId) {
|
||
return await this.ctx.service.systems.apiSign.getApiAppConfigByAppKey(
|
||
/* appKey from warehouse */, WAREHOUSE_INTERFACE_TYPE_ID
|
||
);
|
||
}
|
||
|
||
// 生成 MD5 签名(复用 apiSignLib)
|
||
signRequest(url, body, secret) {
|
||
const query = { app_key: secret.appKey, timestamp: Math.floor(Date.now() / 1000) };
|
||
const { sign } = apiSignLib.signRequest({ query, body, selfAppSecret: secret.selfAppSecret });
|
||
return `${url}?app_key=${query.app_key}×tamp=${query.timestamp}&sign=${sign}`;
|
||
}
|
||
|
||
// 统一发送(子类可覆盖签名逻辑)
|
||
async post(url, body) { /* axios/post */ }
|
||
|
||
// 子类必须实现
|
||
async push(record) { throw new Error('子类实现'); }
|
||
}
|
||
```
|
||
|
||
> **调用链**:`receiver.asyncPush()` → `dispatch[channel].push(record)` → 基类 `signRequest()` + `post()` → 外部。各渠道只关注消息格式转换,签名和 HTTP 由基类统一处理。
|
||
|
||
### 与现有系统集成
|
||
|
||
```
|
||
app/controller/im.js(已有)
|
||
→ IM 回调签名校验后 → ctx.service.inbox.receiver.receive({ source_type: 'im', ... })
|
||
|
||
app/controller/warehouse.js(已有)
|
||
→ method=inbox.push → ctx.service.inbox.receiver.receive({ source_type: 'api', ... })
|
||
|
||
methods/warehouse.json(修改)
|
||
→ 新增 inbox.push 方法定义,注册到 warehouse 开放接口方法列表
|
||
```
|
||
|
||
---
|
||
|
||
## 八、文件变更清单
|
||
|
||
| 文件 | 操作 |
|
||
|------|------|
|
||
| `database/migrations/{ts}-create-inbox-message.js` | 新增 DDL |
|
||
| `app/model/inbox_message.js` | 新增 |
|
||
| `app/service/inbox/index.js` | 新增 |
|
||
| `app/service/inbox/receiver.js` | 新增(统一接收 + 写库 + 异步推送入口) |
|
||
| `app/service/inbox/dispatch/base.js` | 新增(统一出站:查密钥 + 签名 + HTTP) |
|
||
| `app/service/inbox/dispatch/webhook.js` | 新增(HTTP POST 推送) |
|
||
| `app/service/inbox/dispatch/wecom.js` | 新增(企微 Bot) |
|
||
| `app/service/inbox/dispatch/dingtalk.js` | 新增(钉钉 Bot) |
|
||
| `app/service/inbox/dispatch/feishu.js` | 新增(飞书 Bot) |
|
||
| `app/controller/inbox.js` | 新增 |
|
||
| `methods/warehouse.json` | 新增 `inbox.push` |
|
||
| `methods/system.json` | 新增 `inbox.*` |
|