WMS_MAIN/database/designs/inbox-message-module-design.md

442 lines
19 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.

# 站内信(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
> + '&timestamp=' + 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}&timestamp=${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.*` |