# 站内信 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` 指向生产库,禁止裸跑)。