- 新增 app/service/systems/receiving_pending_notice.js:扫描「创建时间超过 min_hours 且不足 max_hours 仍未完成入库」的收货单(wms_receiving 未作废、is_deleted=0,且 status=receiving 或 storage_status<>all),
按货主聚合成一条消息;未绑定货主的单独一批
- 新增 app/schedule/notice_receiving_pending_inbound.js:每 5 分钟单 worker 检查,按各仓库配置的提醒时间(默认 08:30,宽限 10 分钟覆盖调度抖动)执行,
进程内防重入 + Redis 当日锁 receiving_pending_notice🔒{warehouseId}:{YYYYMMDD}(NX/EX 24h,执行异常释放锁允许窗口内重试),保证每仓库每天只提醒一次
- 仓库设置新增字段 wms_store.subject_config.receiving_pending_inbound_notice:
enabled(是否通知收货未入库,flag,默认 0 关闭)/ notice_time(提醒时间 HH:mm,默认 08:30)/ min_hours(超时下限,默认 24)/ max_hours(超时上限,默认 48,须大于 min_hours)
/ notice_template(仓库客服群通知短语)/ store_notice_template(货主群通知短语)
- 通知短语可配置并支持变量替换:{warehouse} {warehouse_id} {store} {store_id} {count} {min_hours} {max_hours} {date} {numbers};
未识别占位符原样保留,留空回退默认短语,最长 500 字符(超长 400)
- 消息结构统一为「短语 + 换行 + 明细(一行一条,最多 20 行,超出提示剩余单数)+ 快速查看/详情查看链接」,不再在结尾追加句号
- 新增通知事件 receiving_pending_inbound(notification_webhook 事件注册 + notice DEFAULT_REGISTERED_EVENT_CODES)与固定群订阅:
store:receiving,fallbackTargets=warehouse:customer_service —— 有货主推货主收货群,无货主或货主未配收货群时推仓库客服群(出站仍走 notify.reply,落 wms_inbox_message)
- 文档:methods/system.json 的 setting.warehouse.getSettings/saveSettings 补充该配置字段(版本 0.3.129 -> 0.3.131),
变更记录新增 2026.09.15-warehouse-pending-receiving-notice / -notice-template(system)、2026-09-15-warehouse-01 / -02(warehouse,事件注册与文案结构);
AI_METHOD_ROUTING.md 同步刷新(新服务 14 个方法)
- 单测 test/app/service/systems/receiving_pending_notice.test.js(11 用例:开关关闭/未命中提醒时间不执行、超时窗口查询条件、货主群通知、无货主回退客服群、
当日只提醒一次、推送失败不重复、扫描异常释放锁重试、行数截断、非法配置回退默认、短语变量替换与明细逐行、未识别占位符保留)全部通过;npx eslint 无告警
同时提交上一轮未提交的 camera/PTZ 改动(app/lib/ptz_client.js 新增、systems/camera.js 与 systemMethods/camera.js:PTZ 下发给打印服务时请求体统一携带 cameraId),
其文档与路由清单改动与本提交共用 methods/system.json 等文件,无法按行安全拆分,故合并为一次提交。
338 lines
17 KiB
JSON
338 lines
17 KiB
JSON
{
|
||
"module": "warehouse",
|
||
"description": "仓库开放 API 统一入口(入站方向:外部 → WMS),供仓库级外部适配器(企微/钉钉/飞书/IM 等)调用,HTTP POST /warehouse,使用 MD5 签名鉴权(interface_type_id=3)。出站通知请参阅 warehouse_notify.json。",
|
||
"version": "1.2.2",
|
||
"updatedAt": "2026-09-15",
|
||
"http": {
|
||
"path": "/warehouse",
|
||
"method": "POST"
|
||
},
|
||
"headers": [],
|
||
"methods": {
|
||
"groups": [
|
||
{
|
||
"groupName": "基础模块",
|
||
"module": "index",
|
||
"list": [
|
||
{
|
||
"method": "index.ping",
|
||
"description": "心跳接口,验证仓库 API 应用连通性,返回仓库上下文与应用信息",
|
||
"isNeedAuth": false,
|
||
"isNeedLogin": false,
|
||
"headers": [],
|
||
"params": [],
|
||
"response": [
|
||
{
|
||
"name": "warehouse_id",
|
||
"type": "number",
|
||
"required": true,
|
||
"description": "当前仓库 ID"
|
||
},
|
||
{
|
||
"name": "app_key",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "当前请求的 AppKey"
|
||
},
|
||
{
|
||
"name": "server_time",
|
||
"type": "number",
|
||
"required": true,
|
||
"description": "服务器 Unix 时间戳(秒)"
|
||
},
|
||
{
|
||
"name": "status",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "服务状态,正常时返回 ok"
|
||
}
|
||
],
|
||
"errors": [],
|
||
"notes": [
|
||
"模块:基础模块",
|
||
"方法部署位置:warehouseMethods/index.ping",
|
||
"无需 body 参数,GET query 参数满足 method/v/timestamp/app_key/sign 即可",
|
||
"timestamp 时间戳时效校验:与服务器时间差不得超过 ±10 分钟(600 秒),否则返回 400"
|
||
]
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"groupName": "货主模块",
|
||
"module": "store",
|
||
"list": [
|
||
{
|
||
"method": "store.list",
|
||
"description": "查询当前仓库下已授权的货主列表,返回货主基本信息与授权状态(需 auth_status=2 已通过 + store.status=1 启用 + warehouse_use_status=1 可用)",
|
||
"isNeedAuth": false,
|
||
"isNeedLogin": false,
|
||
"headers": [],
|
||
"params": [
|
||
{
|
||
"name": "page",
|
||
"type": "number",
|
||
"required": false,
|
||
"source": "body",
|
||
"description": "页码,默认 1",
|
||
"defaultValue": 1
|
||
},
|
||
{
|
||
"name": "pageSize",
|
||
"type": "number",
|
||
"required": false,
|
||
"source": "body",
|
||
"description": "每页数量,默认 20,最大 100",
|
||
"defaultValue": 20
|
||
}
|
||
],
|
||
"response": [
|
||
{
|
||
"name": "list",
|
||
"type": "array",
|
||
"required": true,
|
||
"description": "货主列表",
|
||
"children": [
|
||
{
|
||
"name": "store_id",
|
||
"type": "number",
|
||
"required": true,
|
||
"description": "货主 ID(wms_store.id)"
|
||
},
|
||
{
|
||
"name": "company_name",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "公司全称"
|
||
},
|
||
{
|
||
"name": "contact_person",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "联系人"
|
||
},
|
||
{
|
||
"name": "contact_phone",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "联系电话"
|
||
},
|
||
{
|
||
"name": "contract_id",
|
||
"type": "number",
|
||
"required": true,
|
||
"description": "授权关系 ID(wms_store_warehouse.id)"
|
||
},
|
||
{
|
||
"name": "auth_status",
|
||
"type": "number",
|
||
"required": true,
|
||
"description": "授权状态:2=已通过"
|
||
},
|
||
{
|
||
"name": "auth_start",
|
||
"type": "string",
|
||
"required": false,
|
||
"description": "授权开始日期"
|
||
},
|
||
{
|
||
"name": "auth_end",
|
||
"type": "string",
|
||
"required": false,
|
||
"description": "授权结束日期"
|
||
},
|
||
{
|
||
"name": "store_remask",
|
||
"type": "string",
|
||
"required": false,
|
||
"description": "商家备注"
|
||
},
|
||
{
|
||
"name": "warehouse_remask",
|
||
"type": "string",
|
||
"required": false,
|
||
"description": "仓库备注"
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"name": "pagination",
|
||
"type": "object",
|
||
"required": true,
|
||
"description": "分页信息",
|
||
"children": [
|
||
{
|
||
"name": "page",
|
||
"type": "number",
|
||
"required": true,
|
||
"description": "当前页码"
|
||
},
|
||
{
|
||
"name": "pageSize",
|
||
"type": "number",
|
||
"required": true,
|
||
"description": "每页数量"
|
||
},
|
||
{
|
||
"name": "total",
|
||
"type": "number",
|
||
"required": true,
|
||
"description": "总记录数"
|
||
},
|
||
{
|
||
"name": "totalPages",
|
||
"type": "number",
|
||
"required": true,
|
||
"description": "总页数"
|
||
}
|
||
]
|
||
}
|
||
],
|
||
"errors": [],
|
||
"notes": [
|
||
"模块:货主模块",
|
||
"方法部署位置:warehouseMethods/store.list",
|
||
"仓库隔离:自动使用当前 API 应用绑定的 warehouse_id",
|
||
"仅返回已通过授权(auth_status=2)、仓库侧可用(warehouse_use_status=1)、货主启用(store.status=1)的记录",
|
||
"分页查询:默认 20 条/页,最大 100 条/页"
|
||
]
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"groupName": "站内信模块",
|
||
"module": "inbox",
|
||
"list": [
|
||
{
|
||
"method": "inbox.push",
|
||
"description": "外部系统将消息推入仓库站内信。warehouse_id 由验签后上下文注入,禁止外部传入。ext_id 由 appKey + requestId 自动组合,幂等去重。source_type 固定为 api,禁止外部传入。",
|
||
"isNeedAuth": false,
|
||
"isNeedLogin": false,
|
||
"headers": [],
|
||
"params": [
|
||
{
|
||
"name": "requestId",
|
||
"type": "string",
|
||
"required": true,
|
||
"source": "body",
|
||
"description": "来源请求唯一 ID,与 appKey 组合为 ext_id(api:{appKey}:{requestId}),用于幂等去重"
|
||
},
|
||
{
|
||
"name": "content",
|
||
"type": "string",
|
||
"required": false,
|
||
"source": "body",
|
||
"description": "消息正文/摘要"
|
||
},
|
||
{
|
||
"name": "groupId",
|
||
"type": "string",
|
||
"required": false,
|
||
"source": "body",
|
||
"description": "外部群 ID,用于关联群及自动查询货主路由"
|
||
},
|
||
{
|
||
"name": "groupName",
|
||
"type": "string",
|
||
"required": false,
|
||
"source": "body",
|
||
"description": "群名称(展示用)"
|
||
},
|
||
{
|
||
"name": "userId",
|
||
"type": "string",
|
||
"required": false,
|
||
"source": "body",
|
||
"description": "外部用户 ID"
|
||
},
|
||
{
|
||
"name": "userName",
|
||
"type": "string",
|
||
"required": false,
|
||
"source": "body",
|
||
"description": "用户名称(展示用)"
|
||
},
|
||
{
|
||
"name": "parentId",
|
||
"type": "number",
|
||
"required": false,
|
||
"source": "body",
|
||
"description": "关联消息 ID(回信时指向原消息,形成对话链)"
|
||
},
|
||
{
|
||
"name": "targetType",
|
||
"type": "string",
|
||
"required": false,
|
||
"source": "body",
|
||
"description": "目标类型:im / api / webhook,默认 im"
|
||
},
|
||
{
|
||
"name": "extData",
|
||
"type": "object",
|
||
"required": false,
|
||
"source": "body",
|
||
"description": "外部透传数据,任意 JSON,WMS 不解析,回信时原样返回"
|
||
},
|
||
{
|
||
"name": "sendTime",
|
||
"type": "number",
|
||
"required": false,
|
||
"source": "body",
|
||
"description": "消息原始发送时间(可选):毫秒时间戳、秒时间戳或 ISO 时间字符串。WMS 据此判断历史消息:发送时间距今超过阈值(默认 10 分钟,config.inbox.historyMessageMaxAgeMs 可调)的历史/补推消息将跳过 AI 处理,不自动回复、不创建工单;不传则按实时消息处理"
|
||
},
|
||
{
|
||
"name": "flags",
|
||
"type": "object",
|
||
"required": false,
|
||
"source": "body",
|
||
"description": "处理标记。支持:skipAi=true 显式跳过 AI 处理;send_time=毫秒时间戳(消息原始发送时间,用于历史消息过滤,与 sendTime 参数等价)"
|
||
}
|
||
],
|
||
"response": [
|
||
{
|
||
"name": "ok",
|
||
"type": "boolean",
|
||
"required": true,
|
||
"description": "操作是否成功"
|
||
},
|
||
{
|
||
"name": "id",
|
||
"type": "number",
|
||
"required": true,
|
||
"description": "站内信记录 ID"
|
||
},
|
||
{
|
||
"name": "ext_id",
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "外部唯一消息主键(api:{appKey}:{requestId})"
|
||
}
|
||
],
|
||
"errors": [
|
||
{
|
||
"code": "400",
|
||
"message": "requestId 不能为空"
|
||
},
|
||
{
|
||
"code": "400",
|
||
"message": "缺少仓库信息"
|
||
},
|
||
{
|
||
"code": "400",
|
||
"message": "parent_id=XX 对应的消息不存在"
|
||
},
|
||
{
|
||
"code": "400",
|
||
"message": "消息体超过 64KB 限制"
|
||
},
|
||
{
|
||
"code": "500",
|
||
"message": "站内信入站失败"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|