WMS_MAIN/methods/warehouse.json
liufumingren 1571de341c feat(storage): 新增收货未入库提醒定时任务(货主/客服群通知,短语可配置)
- 新增 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 等文件,无法按行安全拆分,故合并为一次提交。
2026-09-15 23:49:34 +08:00

338 lines
17 KiB
JSON
Raw Permalink 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",
"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": "站内信入站失败"
}
]
}
]
}
]
}
}