WMS_MAIN/INBOX_V2_TEST_GUIDE.md
liufumingren 806e739267 feat(inbox): v2 规则引擎完善(help 指令/建单开关/系统回复)并修复拦截日志误写仓库 ID
- functions.js: 拦截/取消拦截波次感知写订单日志 businessId 误用仓库 ID,改为订单 ID
  (生产订单 JY2026091813795 已发起拦截但订单详情查不到拦截日志的根因)
- rules/v2/processor/config/functionSync: 新增 help 指令、create_work_order=0 时跳过
  工单登记、系统级回复与无单号提示、白名单范围修正
- after_sale_reply 模型 + 6 个迁移: create_work_order 字段与相关配置种子
- return_unpack: 列表 count 统计修复、分页排序追加主键防重漏行、视频附加 camera_name
- methods/system.json + changes + sync 脚本: 接口文档与权限同步
2026-09-18 22:38:57 +08:00

334 lines
17 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.

# 站内信 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 幂等写库<br/>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 引擎<br/>模块接管]|
I --> K[callFunction 代码越权校验]
K --> L[writeOutboundReply 出站回执]
L -->|POST notify.reply| M[回调 URL<br/>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&timestamp={秒级时间戳}&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&timestamp={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&timestamp={秒}&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` 指向生产库,禁止裸跑)。