# 站内信 v2 可配置回信引擎 —— 端到端测试流程指南
> 适用对象:开发/测试人员。覆盖消息 HTTP 推送进入、群类型创建、回传数据接收、
> 校验准则、涉及表的状态变化与特殊流程边界。
> 所有示例基于本地环境(服务 `127.0.0.1:6060`,MySQL `127.0.0.1:3307/wms`),
> 生产环境仅做只读核对,禁止写操作。
## 测试范围(重要)
- **只测 v2 链路**:`template_reply_enabled=1` 的群走 `inbox.v2.rules` 可配置引擎;
- **v1 链路不需要测试**:processor 分叉为 `else` 分支原样保留,v1 规则表
(`inbox/rules.js` 静态规则)与 AI 兜底逻辑零改动,无需回归;
- 自动化验证已覆盖:`test/inbox/v2_rules_engine.test.js`(引擎 9 用例)、
`test/inbox/v2_processor_fork.test.js`(分叉 3 用例)、
`test/inbox/v2_function_sync.test.js`(函数同步 4 用例)。
---
## 0. 总体链路
```mermaid
flowchart LR
A[外部适配器] -->|POST /warehouse inbox.push 验签| B[warehouseMethods/inbox.push]
B --> C[receiver.receive 幂等写库
wms_inbox_message inbound]
C -->|自动登记群| D[wms_inbox_group]
C -->|source_type=api 异步| E[processor.handleApiMessage]
E --> F{群校验: group_type / ai_enabled}
F -->|未通过| G[静默跳过]
F -->|通过| H{规则引擎}
H -->|v1| I[rules.handle]
H -->|template_reply_enabled=1| J[inbox.v2.rules 引擎
模块接管]|
I --> K[callFunction 代码越权校验]
K --> L[writeOutboundReply 出站回执]
L -->|POST notify.reply| M[回调 URL
wms_api_app.callback_url]
L --> N[wms_inbox_message outbound + wms_warehouse_log]
```
---
## 1. 消息 HTTP 推送进入(inbox.push)
### 1.1 入口
```
POST http://127.0.0.1:6060/warehouse?method=inbox.push&v=1.0×tamp={秒级时间戳}&app_key={appKey}&sign={sign}
Content-Type: application/json
```
- `warehouse_id` 由验签后的 `wms_api_app` 上下文注入,**禁止外部传入**;
- `ext_id` 由服务端组合:`api:{appKey}:{requestId}`,用于幂等去重。
### 1.2 签名算法(app/lib/api_sign.js)
```
bodySign = md5(stableStringify(body)) // 对象键按字母序排序后序列化
canonical = query 参数按 key 字母序拼接 "k=v&k2=v2"(排除 sign/signature)
sign = md5(canonical + self_app_secret + bodySign)
```
- `self_app_secret` 来自 `wms_api_app.self_app_secret`(按 `app_key` 查询);
- `app_key` 对应仓库的 API 应用需存在且已启用。
### 1.3 请求体字段
| 字段 | 必填 | 说明 |
|---|---|---|
| `requestId` | ✅ | 来源请求唯一 ID,与 appKey 组成 `ext_id` |
| `content` | - | 消息正文(触发规则引擎的输入) |
| `groupId` | - | 外部群 ID,用于关联群与货主路由 |
| `groupName` | - | 群名称(首次推送会自动登记群) |
| `userId` / `userName` | - | 外部用户 ID / 名称 |
| `parentId` | - | 关联消息 ID(回信时形成对话链) |
| `targetType` | - | `im` / `api` / `webhook`,默认 `im` |
| `extData` | - | 透传 JSON,WMS 不解析,回信原样带回 |
| `sendTime` | - | 消息原始发送时间(毫秒/秒/ISO),用于历史消息过滤 |
| `flags` | - | `{skipAi:true}` 显式跳过 AI;`{send_time:ms}` 等价 sendTime |
### 1.4 响应与幂等
- 成功:`{code:0, message:'ok', data:{ok:true, id, ext_id}}`;
- 相同 `ext_id` 重复推送:直接返回已存在记录,**不重复入库、不重复触发处理**。
---
## 2. 创建特定群类型
### 2.1 自动登记(首次推送即建群)
首次推送含 `groupName` 的消息时,`receiver.receive` 自动在 `wms_inbox_group`
创建群记录(按 `group_id + warehouse_id` 唯一):
- `ai_enabled=0`、`group_type/sub_type=NULL`、`store_id` 取自绑定的货主;
- 群名变化只更新名称,不重复建群。
### 2.2 配置群类型(管理接口)
```
POST http://127.0.0.1:6060/system?method=inbox.group.update&v=1.0×tamp={ts}
Authorization: Bearer {登录 token}
Content-Type: application/json
{ "id": {群记录ID}, "groupType": "store", "subType": "after_sales",
"storeId": 1000000, "aiEnabled": 1 }
```
- `groupType`:`store`(货主)/ `warehouse`(仓库)/ `express`(快递);
- `subType`(群子类型):
- store:`after_sales` / `finance` / `receiving`
- warehouse:`receiving` / `production` / `stockout` / `finance` / `all` / `customer_service` / `exception`
- express:`pickup` / `after_sales`
- `aiEnabled=1` 才会进入规则引擎(第 5 步开关);
- `inbox.group.reset`:清空群类型配置并重置 AI 开关。
### 2.3 v2 回信开关(开启即接管链路)
v2 引擎开关 `template_reply_enabled`(管理接口未上线前用 SQL 设置):
```sql
UPDATE wms_inbox_group SET template_reply_enabled = 1
WHERE group_id = '{测试群ID}' AND warehouse_id = {仓库ID};
```
- `template_reply_enabled=1` 的群在第 6 步自动走 `inbox.v2.rules.handle`(已接入);
- **模块优先语义**:`template_reply_enabled=1` 即为模块总开关,开启时不依赖 `ai_enabled`
(两个开关同开时也走 v2 不走 v1/AI;`ai_enabled` 只约束未开启模板开关的群);
- **模块接管模式**:v2 开启群的未命中消息直接静默,不走 v1 规则、不走 AI 兜底;
- 群信息每条消息实时查库(`_loadGroupInfo` 不缓存),SQL 改动对下一条消息立即生效;
- v2 配置数据(关键词/白名单/函数/取号/回复)有 300s 缓存,改动后需
`ctx.service.inbox.v2.config.invalidate(warehouseId)` 或等 TTL 过期。
---
## 3. 接收回传数据
### 3.1 出站回执方向(WMS → 外部)
规则处理完成后,`processor.writeOutboundReply` 向 `wms_api_app.callback_url`
POST 回执(`notify.reply`):
```
POST {callback_url}?app_key={k}&method=notify.reply×tamp={秒}&sign={md5(appSecret + timestamp + bodyJson)}
```
回执 body 关键字段:
- `data.type`:`ai`(规则/AI 自动回复)、`system`、`bind`、`balance`、`error`;
- `data.content`:回复内容;`data.ext_data`:入站 `extData` 原样带回;
- `data.ext_id`:出站消息记录 ID;`data.group_id` / `user_id` / `user_name`:目标群与用户。
### 3.2 测试接收方法
方式 A(推荐):临时把本地库 `wms_api_app.callback_url` 指向本地 HTTP 接收服务,
观察收到的 `notify.reply` 报文并返回 `{code:200}`:
```sql
UPDATE wms_api_app SET callback_url = 'http://127.0.0.1:9001/ack'
WHERE app_key = '{测试app_key}';
```
方式 B(不落回执服务):直接核对库表:
- `wms_inbox_message`:`direction='outbound'`、`ext_id='sys:ack:{入站ext_id}'`;
- `wms_warehouse_log`:`method='notify.reply'` 的出站通知日志(含 http_status/body/result)。
### 3.3 推送状态核对
| push_status | 含义 |
|---|---|
| 0/1 | 未推送 / 待推送 |
| 2 | 回调返回 HTTP 200 且 `code=200` → 推送成功 |
| 3 | 回调非 200 / 无回调地址 / 异常 → 推送失败(可 `inbox.message.retry` 重推) |
---
## 4. 校验准则
| # | 校验项 | 准则 |
|---|---|---|
| 1 | 幂等 | 相同 `ext_id` 只入库一次、只处理一次 |
| 2 | 群类型 | `group_type` 为空 → 跳过处理(未绑定任务类型) |
| 3 | AI 开关 | `ai_enabled != 1` → 跳过(快递群默认 0,需手动开) |
| 4 | 历史消息 | `send_time` 距今 > 10 分钟(`config.inbox.historyMessageMaxAgeMs` 可调)→ 跳过,不回复不建工单 |
| 5 | 屏蔽 | 屏蔽用户/群 → 跳过处理(`blockUser` 函数 / `wms_inbox_block`) |
| 6 | 关键词命中 | 长词优先;命中后先过防误判守卫(如"拦截" vs "查物流") |
| 7 | 函数越权 | `callFunction` 按群活跃分组校验,越权返回错误(DB 配置只做可见性,代码是最终权威) |
| 8 | 取号失败 | 子类型关联了取号规则但未提取到值 → 回复引导语(`no_number_hint` → target 专属 → 默认),**不调用函数** |
| 9 | 回复决策 | 回复完全由回复配置控制:`is_reply=1` 且模板渲染非空 → 回复;`is_reply=0` → 静默(函数仍执行);无配置/模板渲染为空 → **默认不回复**(函数已执行,仅不出回执) |
| 10 | 快递群 | express 群仅执行函数,**不回信** |
| 11 | 出站回执 | 回执 `ext_id='sys:ack:{入站ext_id}'` 唯一,重复处理不重复出站 |
| 12 | 缓存 | v2 配置缓存 `inbox:v2:cfg:{warehouseId}` TTL 300s;配置变更后必须 `invalidate`,否则 5 分钟内不生效 |
---
## 5. 涉及表的状态变化
### 5.1 消息链路表
| 表 | 变化 |
|---|---|
| `wms_inbox_message` | 入站:`direction='inbound'`、`push_status=0`;规则命中后写 `ai_thoughts`(轨迹 JSON)。出站:`direction='outbound'`、`ext_id='sys:ack:{ext_id}'`、`parent_id=入站ID`;推送后 `push_status=2/3`、`push_response`、`pushed_at` |
| `wms_inbox_group` | 首次推送自动登记(`ai_enabled=0`);`group.update` 写 `group_type/sub_type/store_id/ai_enabled`;群名变化只更新名称 |
| `wms_warehouse_log` | 每次出站 `notify.reply` 写一条(`method/url/http_status/body/result/use_time`) |
### 5.2 业务函数表(v1 与 v2 共用函数)
| 表 | 变化(以函数为准) |
|---|---|
| `wms_after_sale` | `interceptWaybill`(type=order, sub_type=intercept, status=pending)、`changeAddr`(change_address/rejected/urge)、`handleStoreFeedback`(mis_shipment/damage/extra_item/missing_item)、`weishoudao`(verify_delivery)、`requestPickup`(pickup)等创建售后工单 |
| `wms_order_express` | 拦截成功后写 `intercept_status='requested'` 与 `intercept_time`(值域见 `intercept-status-values` 约定) |
| `wms_order_delivery_{warehouseId}` | `createPostnum` 分配运单号后写 `logistics_*`/`post_status`;`changeExpress` 修改快递分配 |
### 5.3 v2 配置表(全部只读,引擎启动时一次性同步函数表)
| 表 | 变化 |
|---|---|
| `wms_after_sale_function` | 启动时 `functionSync.sync()` 幂等 upsert(只增改不删、不覆盖 `is_enabled/sort_order`) |
| `wms_after_sale_type` / `wms_after_sale_sub_type` | 系统级 + 仓库级(`warehouse_id NULL` 全局可见) |
| `wms_after_sale_keyword` | 关键词 → 子类型映射(长词优先、`sort_order` 同长时生效) |
| `wms_after_sale_sub_type_group` | 子类型 × 群类型 × 群子类型白名单(`uk(sub_type_id, group_type, sub_group)`) |
| `wms_after_sale_sub_type_function` | 子类型 → 处理函数(`function_id` + `sort_order`) |
| `wms_after_sale_sub_type_rule` + `wms_inbox_number_rule` | 子类型 → 取号规则(`target/regexp/sort_order`) |
| `wms_after_sale_reply` | 仓库级(`warehouse_id` 非空)覆盖系统级;`is_reply=0` 静默、`no_number_hint` 引导语、`create_work_order=0` 函数照常执行但内部跳过工单登记 |
---
## 6. 特殊流程边界
### 6.1 开关与分叉边界
- **AI 开关**:`ai_enabled != 1` 一律跳过(安全默认,快递群默认关闭);
例外:`template_reply_enabled=1` 的群不依赖 AI 开关(模块优先);
- **群未绑定**:`group_type` 为空跳过;`store` 群无 `store_id` 归属时主分组不激活(`resolveActiveGroups`);
- **v1/v2 分叉**(已接入):`template_reply_enabled=1` 走 `inbox.v2.rules.handle`,
否则走 `inbox.rules.handle`(v1 分支原逻辑零改动);
- **模块接管**:v2 开启群的未命中消息直接静默 return,不回落到 v1 规则与 AI 兜底。
### 6.2 v2 引擎边界(已接入 processor)
- **关键词命中**:长词优先;同长多个子类型均按序尝试;
- **白名单过滤**:`(group_type, sub_group)` 双维度;群 `sub_type` 为空时**只按主类型放行**
(随后由 `callFunction` groups 校验兜底收紧);
- **取号正则安全三件套**:保存时校验 + 长度 ≤ 500 + 每次 `new RegExp`(非法正则跳过并告警);
- **入参组装**:`waybill_no/order_no/source_order_codes/receiving_no/entry_order_no/stockout_no`
合并去重 join 逗号 → `keyword`;`express_name→express`;
子类型转译 `issue_type`(damage→damaged、change_address→addr、rejected→return、urge→urge 等);
- **多函数子类型**:按 `sort_order` 依次执行,任一失败立即返回失败文案;
- **回复优先级**:回复表(仓库级 > 系统级);模板渲染为空或无配置时**默认不回复**(函数照常执行);
`{back_text}` 占位符由 help 函数提供,业务函数无该内容时渲染为空 → 不回复;
- **缓存失效**:管理接口增删改配置后必须调用 `ctx.service.inbox.v2.config.invalidate(warehouseId)`;
启动时**不清** v2 缓存(防雪崩)。
### 6.3 消息边界
- **历史/补推消息**:`sendTime` 超阈值 → 静默跳过(不回复、不建工单);
- **屏蔽**:屏蔽用户(`wms_inbox_block`)/ 屏蔽群(`is_blocked=1`)→ 跳过处理;
- **express 群**:函数照常执行(如 `handleExpressFeedback`),但**不回信**;
- **幂等回执**:`sys:ack:{ext_id}` 保证同一入站消息只产生一条出站回执;
- **多条回复**:引擎返回数组时逐条出站,`ext_id` 追加 `:r0/:r1` 避免唯一键冲突;
- **渠道校正**:回执 `ext_data.source` 按群 ID 格式校正(`@chatroom→wx`、纯数字→qiwe),防止投递到错误渠道。
### 6.4 数据层已知状态(2026-09-17 已修复)
1. ✅ `change_carrier`(换快递)已补 `express_name` 取号规则关联(迁移 `20260917130000`),
"改快递 {单号} 圆通" 可完整组装 `keyword + express`;
2. ✅ 关键词表已补 `intercept`(拦截/退回/召回/追回/取消快递)与 `pickup`(揽收/上门取件/取件/退货取件)共 9 条;
3. ⚠️ `wrong_sku`/`quality_issue` 无群白名单关联行(预期内,引擎白名单过滤后跳过)。
---
## 7. v2 链路测试步骤(本地)
> v1 链路不需要测试(分叉 else 分支原样保留)。以下步骤专测 v2。
### 7.1 前置:准备好一个 v2 开启的测试群
```sql
-- 1) 确保群存在(可由首次推送自动登记,或手动插入)
-- 2) 配置群类型 + 开关(管理接口未上线前用 SQL)
UPDATE wms_inbox_group
SET group_type='store', sub_type='after_sales',
store_id={货主ID}, ai_enabled=1, template_reply_enabled=1
WHERE group_id='{测试群ID}' AND warehouse_id={仓库ID};
```
v2 链路只需三个条件(模板开关优先,不依赖 AI 开关):`group_type` 非空 →
`template_reply_enabled=1` → 消息内容命中 v2 关键词;`ai_enabled` 开或关都不影响 v2。
### 7.2 推送消息并核对(HTTP 入口)
```powershell
# 1) 推送入站消息:POST /warehouse?method=inbox.push(签名见 1.2)
# body: {"requestId":"v2-001","content":"破损 SF1234567890123",
# "groupId":"{测试群ID}","groupName":"{群名}",
# "userId":"u1","userName":"测试用户"}
# 2) 核对入站:
# SELECT id, direction, ai_thoughts FROM wms_inbox_message
# WHERE ext_id='api:{appKey}:v2-001';
# → direction='inbound',ai_thoughts 含 v2 轨迹(action=rule、function=handleStoreFeedback)
# 3) 核对出站回执:
# SELECT id, ext_id, direction, content, push_status FROM wms_inbox_message
# WHERE ext_id='sys:ack:api:{appKey}:v2-001';
# → direction='outbound'、push_status=2(回调可用时)/3(未配置回调)
# 4) 核对工单:
# SELECT after_sale_no, type, sub_type, status FROM wms_after_sale
# WHERE warehouse_id={仓库ID} ORDER BY id DESC LIMIT 5;
# → sub_type='damage'、status='pending'
# 5) 核对出站日志:
# SELECT method, http_status, result FROM wms_warehouse_log
# WHERE warehouse_id={仓库ID} AND method='notify.reply' ORDER BY id DESC LIMIT 5;
```
### 7.3 推荐用例集(全部走 v2 群)
| 用例 | 消息 | 预期 |
|---|---|---|
| 破损建单 | `破损 SF1234567890123` | `handleStoreFeedback(issue_type=damaged)` + damage 工单 + 回执 |
| 改地址 | `改地址 SF1234567890123` | `changeAddr(issue_type=addr)` + change_address 工单 |
| 换快递 | `改快递 SF1234567890123 圆通` | `changeExpress(keyword=..., express=圆通)` |
| 拦截 | `拦截 SF1234567890123` | `interceptWaybill` + intercept 工单(`wms_order_express.intercept_status='requested'`) |
| 揽收 | `上门取件 SF1234567890123` | `requestPickup` + pickup 工单 |
| 取号失败 | `破损` | 回复引导语,**不建工单** |
| v2 未命中 | `今天天气怎么样` | 模块接管静默:无函数调用、无回执记录 |
| 模块优先 | 同破损内容 + `ai_enabled=0`(`template_reply_enabled=1` 不变) | 仍走 v2 并回执(不依赖 AI 开关) |
| 历史消息 | 同破损内容 + `sendTime` 为 30 分钟前 | 静默跳过:无回执、无工单 |
> 所有用例的群必须 `template_reply_enabled=1`;**不测** `template_reply_enabled=0` 的 v1 场景。
### 7.4 边界补充
- 快递群(express)命中 v2:函数照常执行,但**不回信**(复用现有回执逻辑);
- 相同 `requestId` 重复推送:幂等,只处理一次;
- 回复表 `is_reply=0`:函数执行但静默(可临时插行验证,见 `wms_after_sale_reply`)。
> 补充:egg 测试环境运行 DB 相关测试必须
> `$env:DISPATCH_FACTORY_TEST_MYSQL='1'; $env:EGG_SERVER_ENV='local'; npx egg-bin test {文件}`
> (默认 unittest 环境禁用 sequelize 且 `config.default.js` 指向生产库,禁止裸跑)。