WMS_MAIN/methods/warehouse_notify.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

181 lines
6.1 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": "warehouse_notify",
"description": "仓库开放通知 API 定义(出站方向:WMS → 外部系统)。WMS 处理消息后,通过 HTTP POST 主动推送到外部系统配置的 notify_url,使用 MD5 签名鉴权。method 通过 query 参数传递,body 为 { code, data }。外部系统返回 {\"code\":200} 或 HTTP 非 200 视为推送失败。",
"version": "1.0.0",
"updatedAt": "2026-08-07",
"http": {
"path": "{wms_api_app.callback_url}",
"method": "POST"
},
"auth": {
"type": "MD5",
"description": "签名算法:sign = MD5(app_secret + timestamp + body_json)。外部系统用预先分配的 AppSecret 验证。method / app_key / timestamp / sign 通过 query 参数传递。",
"params": [
{
"name": "app_key",
"type": "string",
"required": true,
"source": "query",
"description": "WMS 的 AppKey"
},
{
"name": "method",
"type": "string",
"required": true,
"source": "query",
"description": "notify.ping / notify.reply"
},
{
"name": "timestamp",
"type": "number",
"required": true,
"source": "query",
"description": "Unix 时间戳(秒),±10分钟有效"
},
{
"name": "sign",
"type": "string",
"required": true,
"source": "query",
"description": "MD5(appSecret + timestamp + bodyJson)"
}
]
},
"headers": [
{
"name": "Content-Type",
"type": "string",
"required": true,
"description": "application/json"
}
],
"methods": {
"groups": [
{
"groupName": "心跳",
"module": "ping",
"list": [
{
"method": "notify.ping",
"description": "连通性测试。WMS 配置 notify_url 后可发送 ping 通知验证外部系统可达。",
"isNeedAuth": true,
"isNeedLogin": false,
"example": {
"query": "?app_key=AK20260807001&timestamp=1786100000&sign=abc123",
"method": "notify.ping",
"code": 200,
"data": {
"content": "ping",
"timestamp": 1786100000
}
}
}
]
},
{
"groupName": "消息回复",
"module": "reply",
"list": [
{
"method": "notify.reply",
"description": "消息回复通知。WMS 处理入站消息后,将 AI 回复/绑群结果/面单余额等内容推送到外部系统。外部系统根据 data.type 区分消息类别。",
"isNeedAuth": true,
"isNeedLogin": false,
"params": [
{
"name": "data.type",
"type": "string",
"required": true,
"source": "body",
"description": "ai=AI回复 / bind=绑群结果 / balance=面单余额 / error=异常兜底"
},
{
"name": "data.content",
"type": "string",
"required": true,
"source": "body",
"description": "回复正文(纯文本)"
},
{
"name": "data.ext_id",
"type": "string",
"required": true,
"source": "body",
"description": "通知唯一 ID(wms_inbox_message.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 秒"
}
],
"notes": [
"对应入站:/warehouse inbox.push",
"type=ai:用户消息触发 AI 推理回复",
"type=bind:用户发送「授权:CODE」绑群",
"type=balance:绑群成功后自动推送面单余额",
"type=error:AI 无法处理时的兜底回复",
"AI silent(无需回复)时不推送",
"ext_id 为 wms_inbox_message.id 主键,接收方应以 ext_id 做幂等去重,网络波动可能重推"
],
"example": {
"query": "?app_key=AK001&timestamp=1786100000&sign=abc",
"method": "notify.reply",
"code": 200,
"data": {
"type": "ai",
"content": "条码6900000000016查到2款商品:\n1. 披肩-消退 可用0\n2. 披肩 可用0(总量95已锁定)",
"ext_id": "188",
"ext_data": {
"request_id": "req-123"
},
"group_id": "wrchat-xxx",
"user_id": "user-001",
"group_name": "售后沟通群",
"user_name": "张三",
"timestamp": 1786100000
}
}
}
]
}
]
}
}