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

17 KiB
Raw Permalink Blame History

站内信 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. 总体链路

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 设置):

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}:

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 开启的测试群

-- 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 入口)

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