- functions 新增 openDoor/registerLicensePlate/enter/departure(规则表+权限分组) - 到货登记表 wms_inbox_arrival_register(含消费字段,离场闭环,货主收货群优先推送) - 回执 extend_props 持久化落库与定时补发送下发(重推兜底回读) - 车牌提取正则兼容异体字(粤/粵) - 售后类型/关键字/函数/回复 v2 模型与迁移 - INBOX V2 HTTP 测试报告与指南
16 KiB
站内信 v2 可配置回信引擎 —— 端到端测试流程指南
适用对象:开发/测试人员。覆盖消息 HTTP 推送进入、群类型创建、回传数据接收、 校验准则、涉及表的状态变化与特殊流程边界。 所有示例基于本地环境(服务
127.0.0.1:6060,MySQL127.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. 总体链路
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×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
- store:
aiEnabled=1才会进入规则引擎(第 5 步开关);inbox.group.reset:清空群类型配置并重置 AI 开关。
2.3 v2 回信开关(开启即接管链路)
v2 引擎开关 template_reply_enabled(管理接口未上线前用 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(已接入);- 模块接管模式: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}:
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 引导语 |
6. 特殊流程边界
6.1 开关与分叉边界
- AI 开关:
ai_enabled != 1一律跳过(安全默认,快递群默认关闭); - 群未绑定:
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为空时只按主类型放行 (随后由callFunctiongroups 校验兜底收紧); - 取号正则安全三件套:保存时校验 + 长度 ≤ 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依次执行,任一失败立即返回失败文案; - 回复优先级:回复表(仓库级 > 系统级)> 函数返回值(
direct_reply.messages>data.message>error); - 缓存失效:管理接口增删改配置后必须调用
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 已修复)
- ✅
change_carrier(换快递)已补express_name取号规则关联(迁移20260917130000), "改快递 {单号} 圆通" 可完整组装keyword + express; - ✅ 关键词表已补
intercept(拦截/退回/召回/追回/取消快递)与pickup(揽收/上门取件/取件/退货取件)共 9 条; - ⚠️
wrong_sku/quality_issue无群白名单关联行(预期内,引擎白名单过滤后跳过)。
7. v2 链路测试步骤(本地)
v1 链路不需要测试(分叉 else 分支原样保留)。以下步骤专测 v2。
7.1 前置:准备好一个 v2 开启的测试群
-- 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 链路的四个开关缺一不可:group_type 非空 → ai_enabled=1 → template_reply_enabled=1
→ 消息内容命中 v2 关键词。
7.2 推送消息并核对(HTTP 入口)
# 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 未命中 | 今天天气怎么样 |
模块接管静默:无函数调用、无回执记录 |
| 历史消息 | 同破损内容 + sendTime 为 30 分钟前 |
静默跳过:无回执、无工单 |
| 群开关关闭 | 同破损内容 + template_reply_enabled=0 |
走 v1(不属 v2 测试范围,仅确认分叉生效) |
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指向生产库,禁止裸跑)。