WMS_MAIN/methods/inbox-callback.json
liufumingren 948f600689 feat(inbox): 回调推送、出站文档、搜索增强、日志与推送状态完善
出站回调:
- 新增 warehouse_notify.json 文档(notify.ping/notify.reply),与 warehouse.json 互跳
- 回调体统一 { method, code, data },method 放 query,body 为业务数据
- MD5 签名: sign=MD5(appSecret+timestamp+bodyJson)
- 回调响应: {code:200} 成功,非200/非code:200 视为失败
- docs 页面支持模拟推送调试

搜索增强(searchStock/searchWarehouseStock):
- 直接查 stock_warehouse,不再依赖 stock_store
- 新增字段: gross_weight/box_spec/packing_requirements/prohibited_type
- 管理标识: is_sn_mgmt/is_shelf_life_mgmt/is_batch_mgmt
- 条码关联: wms_stock_barcodes
- 图片: wms_file_reference(business_type=stock)+wms_file,返回数组
- id 修正为 stock_warehouse.id

推送状态完善:
- handleApiMessage 增加 push_status 更新(2成功/3失败)
- 未配回调地址 → push_status=3 + error 原因
- 回调异常 catch 也更新 push_status=3 + 写日志
- 出站日志写入 wms_warehouse_log 表(WN-前缀)

消息列表:
- keyword 兼容 content/keyword,支持数组
- keyword 搜索 content/group_name/user_name 三列
- 支持 where+operator 结构化查询(parseWhereConditions)
- storeId=-1 查询无货主消息; storeId=0→IS NULL
- 日期范围: startDate/endDate

其他:
- silent 动作: AI 识别无需回复时跳过回执
- ai_enabled 灰度开关(群级)
- bindCode 文档修正
- store_name 改用 StoreWarehouse.store_remask
2026-08-08 00:17:38 +08:00

261 lines
9.4 KiB
JSON
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.

{
"module": "inbox-callback",
"description": "站内信模块出站回调定义。WMS 处理入站消息后,通过 HTTP POST 将回复推送到仓库 ApiApp 配置的 callback_url(interface_type_id=3),供外部适配器消费并投递到实际聊天通道。回调体统一包裹:{ method, code, data }。",
"version": "1.1.0",
"updatedAt": "2026-08-07",
"http": {
"path": "{ApiApp.callback_url}",
"method": "POST"
},
"headers": [
{
"name": "Content-Type",
"type": "string",
"required": true,
"description": "application/json"
}
],
"methods": {
"groups": [
{
"groupName": "AI 自动回复",
"module": "ai_reply",
"list": [
{
"method": "inbox.callback.ai_reply",
"description": "AI 自动回复回调。用户发送消息后,DeepSeek 推理给出回复内容,WMS 推送到外部聊天通道。",
"params": [],
"response": [],
"errors": [],
"notes": [
"content 为 AI 生成的纯文本(含 \\n 换行,禁止 Markdown)",
"ext_id 与入站消息相同,外部系统可据此关联对话",
"若 AI 判定无需回复(silent),不会触发此回调",
"ai_thoughts 字段记录整个推理链(仅限出站记录查询,不入回调)"
],
"example": {
"method": "inbox.callback.ai_reply",
"code": 200,
"data": {
"source": "ai_reply",
"content": "条码6900000000016查到2款商品:\n1. 披肩-消退 可用0\n2. 披肩 可用0(总量95已锁定)\n均无可用库存,建议更换商品。",
"ext_id": "api:AK001:req-123",
"ext_data": {
"request_id": "req-123"
},
"group_id": "wrchat-xxx",
"user_id": "user-001",
"group_name": "售后沟通群",
"user_name": "张三",
"timestamp": 1786100000
}
}
}
]
},
{
"groupName": "绑群确认",
"module": "bind_confirm",
"list": [
{
"method": "inbox.callback.bind_confirm",
"description": "绑群确认回调。用户发送「授权:CODE」后,WMS 校验成功/失败/已绑定,推送绑群结果。",
"params": [],
"response": [],
"errors": [],
"notes": [
"成功 content:绑定「{货主备注名}」成功",
"失败 content:绑群码无效或已过期,请重新生成",
"已绑定 content:已在绑定状态,无需重复操作",
"绑定成功后自动追加 inbox.callback.balance 返回面单余额"
],
"example": {
"method": "inbox.callback.bind_confirm",
"code": 200,
"data": {
"source": "bind_confirm",
"content": "绑定「测试货主1111」成功",
"ext_id": "api:AK001:req-456",
"ext_data": null,
"group_id": "wrchat-xxx",
"user_id": "user-001",
"group_name": "售后沟通群",
"user_name": "张三",
"timestamp": 1786100000
}
}
}
]
},
{
"groupName": "面单余额",
"module": "balance",
"list": [
{
"method": "inbox.callback.balance",
"description": "面单余额回调。绑群成功后自动查询,或用户主动查询时推送面单余额。",
"params": [],
"response": [],
"errors": [],
"notes": [
"content 格式:面单余额:总量 {print_quantity},已锁定 {print_quantity_locked},可用 {available}",
"ext_id 为 {原ext_id}:balance 后缀,避免与绑群确认回执冲突",
"余额查询失败时 content:面单余额查询失败:{错误原因}"
],
"example": {
"method": "inbox.callback.balance",
"code": 200,
"data": {
"source": "balance",
"content": "面单余额:总量 5000,已锁定 200,可用 4800",
"ext_id": "api:AK001:req-456:balance",
"ext_data": null,
"group_id": "wrchat-xxx",
"user_id": "user-001",
"group_name": "售后沟通群",
"user_name": "张三",
"timestamp": 1786100000
}
}
}
]
},
{
"groupName": "异常兜底",
"module": "error",
"list": [
{
"method": "inbox.callback.error",
"description": "异常兜底回调。AI 5轮推理均失败或系统异常时的兜底回复。",
"params": [],
"response": [],
"errors": [],
"notes": [
"content 为固定兜底文案:抱歉,暂时无法处理您的请求,请稍后重试",
"出站前仍写入 wms_inbox_message.outbound 记录"
],
"example": {
"method": "inbox.callback.error",
"code": 200,
"data": {
"source": "error",
"content": "抱歉,暂时无法处理您的请求,请稍后重试",
"ext_id": "api:AK001:req-789",
"ext_data": null,
"group_id": "wrchat-xxx",
"user_id": "user-001",
"group_name": "售后沟通群",
"user_name": "张三",
"timestamp": 1786100000
}
}
}
]
},
{
"groupName": "通用说明",
"module": "common",
"list": [
{
"method": "inbox.callback.common",
"description": "所有回调类型共有字段说明及路由指引。外部适配器根据 method 字段路由到不同处理逻辑。",
"params": [
{
"name": "method",
"type": "string",
"required": true,
"source": "body",
"description": "回调方法名,固定格式 inbox.callback.{source},外部适配器据此路由"
},
{
"name": "code",
"type": "number",
"required": true,
"source": "body",
"description": "状态码,正常回调固定 200"
},
{
"name": "data.source",
"type": "string",
"required": true,
"source": "body",
"description": "消息来源:ai_reply / bind_confirm / balance / error"
},
{
"name": "data.content",
"type": "string",
"required": true,
"source": "body",
"description": "回复正文(纯文本,含 \\n 换行)"
},
{
"name": "data.ext_id",
"type": "string",
"required": true,
"source": "body",
"description": "原始入站消息ID,关联对话链"
},
{
"name": "data.ext_data",
"type": "object",
"required": false,
"source": "body",
"description": "入站透传数据,原路带回"
},
{
"name": "data.group_id",
"type": "string",
"required": true,
"source": "body",
"description": "外部群ID"
},
{
"name": "data.user_id",
"type": "string",
"required": true,
"source": "body",
"description": "外部用户ID"
},
{
"name": "data.group_name",
"type": "string",
"required": true,
"source": "body",
"description": "群名称"
},
{
"name": "data.user_name",
"type": "string",
"required": true,
"source": "body",
"description": "用户名称"
},
{
"name": "data.timestamp",
"type": "number",
"required": true,
"source": "body",
"description": "出站 Unix 时间戳(秒)"
}
],
"response": [
{
"name": "http_status",
"type": "number",
"required": true,
"description": "HTTP 200 表示回调成功,WMS 更新 push_status=2"
}
],
"errors": [],
"notes": [
"回调由 app/service/inbox/processor.js → writeOutboundReply() / handleApiMessage 发起",
"callback_url 配置:wms_api_app.interface_type_id=3 AND is_enabled=1",
"超时 10 秒,失败不影响消息记录写入",
"HTTP 200 → 更新出站+入站 push_status=2(已送达)"
]
}
]
}
]
}
}