{ "module": "system", "description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内", "version": "0.3.258", "updatedAt": "2026-10-09", "headers": [ { "name": "platform", "type": "string", "required": true, "description": "客户端平台标识,如 web/pda/app/miniprogram/tv", "list": [ { "value": "web", "name": "网页端" }, { "value": "pda", "name": "PDA端" }, { "value": "app", "name": "APP端" }, { "value": "miniprogram", "name": "微信端" }, { "value": "tv", "name": "TV端" }, { "value": "other", "name": "其他" }, { "value": "workerstation", "name": "工作台" } ] }, { "type": "string", "required": true, "name": "project", "description": "项目标识,如 all/warehouse/store/tms/wms/scm/other", "list": [ { "value": "all", "name": "全部" }, { "value": "warehouse", "name": "仓库" }, { "value": "store", "name": "货主" }, { "value": "tms", "name": "物流" }, { "value": "wms", "name": "WMS" }, { "value": "scm", "name": "SCM" }, { "value": "other", "name": "其他" } ] } ], "methods": { "groups": [ { "groupName": "配置模块", "module": "config", "list": [ { "method": "config.list", "description": "config.list 接口", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "array", "required": true, "source": "body", "description": "要批量修改的仓库商品记录 ID 数组(stock_warehouse.id)", "children": [ { "name": "id", "type": "number", "description": "单个记录 ID" } ] }, { "name": "method", "type": "string", "required": true, "source": "body", "description": "要修改的字段名,可选值:brand_name、prohibited_id、gross_weight、packing_requirements、managementFlags、stock_unit" }, { "name": "value", "type": "string|number|object", "required": true, "source": "body", "description": "修改值,类型依 method 而定:brand_name/packing_requirements/stock_unit 为 string(<=255 字符);prohibited_id 为 number(整数);gross_weight 为 number(正整数,单位 g);managementFlags 为 object,必须包含 is_sn_mgmt/is_shelf_life_mgmt/is_batch_mgmt,值为 'Y' 或 'N'" }, { "name": "values", "type": "any", "required": false, "source": "body", "description": "兼容字段:当前实现以 `value` 为准,不使用 `values`。若客户端历史使用 `values`,请切换为 `value`。" } ], "response": [ { "name": "code", "type": "number", "description": "业务状态码,200 表示成功;405 表示参数/权限校验不通过;500 表示服务器错误" }, { "name": "message", "type": "string", "description": "业务提示信息" }, { "name": "data", "type": "object", "description": "成功时返回的结果对象", "children": [ { "name": "affectedRows", "type": "number", "description": "被更新的记录数" }, { "name": "ids", "type": "array", "description": "请求中传入的 ids 数组" } ] } ], "errors": [ { "code": "405", "description": "请选择要修改的商品(缺少 ids 或 ids 为空)" }, { "code": "405", "description": "不支持修改的字段: {method}" }, { "code": "405", "description": "修改值不能为空" }, { "code": "405", "description": "违禁品类型必须是数字" }, { "code": "405", "description": "毛重必须是有效的正数" }, { "code": "405", "description": "管理标识必须是对象格式 / 管理标识缺少字段 / 管理标识字段值必须是 'Y' 或 'N'" }, { "code": "405", "description": "部分商品不存在或无权修改: " }, { "code": "405", "description": "缺少仓库信息" }, { "code": "500", "description": "内部错误:批量修改失败" } ] } ] }, { "groupName": "看板模块", "module": "dashboard", "list": [ { "method": "dashboard.storeStats", "description": "仓库/货主看板-仓库发货统计:统计待处理、今日新增、发货进度、出库率及拦截、异常、复核、打包订单数量;货主端自动跨已签约仓库汇总。无业务入参,依据登录用户上下文区分仓库端与货主端。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记,成功为 success" }, { "name": "code", "type": "number", "required": true, "description": "业务码,成功为 200" }, { "name": "message", "type": "string", "required": true, "description": "提示信息,成功为 成功" }, { "name": "data.todayOrders", "type": "number", "required": true, "description": "今日订单数(待处理 + 今日已出库)" }, { "name": "data.orderTrend", "type": "number", "required": true, "description": "今日新增较昨日增长率(%),昨日为 0 时按 100 或 0 计算" }, { "name": "data.unassignedOrders", "type": "number", "required": true, "description": "未分配快递号订单数" }, { "name": "data.unprintedOrders", "type": "number", "required": true, "description": "未打印订单数" }, { "name": "data.unpickedOrders", "type": "number", "required": true, "description": "未拣货订单数" }, { "name": "data.pendingShipments", "type": "number", "required": true, "description": "待发货订单数" }, { "name": "data.shipmentProgress", "type": "number", "required": true, "description": "发货进度(%),(待处理-待发货)/待处理" }, { "name": "data.todayOutbound", "type": "number", "required": true, "description": "今日已出库订单数" }, { "name": "data.outboundRate", "type": "number", "required": true, "description": "出库完成率(%),今日出库/(待发货+今日出库)" }, { "name": "data.interceptedOrders", "type": "number", "required": true, "description": "拦截订单数" }, { "name": "data.exceptionOrders", "type": "number", "required": true, "description": "异常订单数(step=3)" }, { "name": "data.recheckedOrders", "type": "number", "required": true, "description": "已复核订单数" }, { "name": "data.packedOrders", "type": "number", "required": true, "description": "已打包订单数" }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": "0", "message": "缺少仓库上下文(仓库端未绑定仓库)或缺少货主上下文(货主端未绑定货主),返回 flag=failure" }, { "code": "401", "message": "未登录或 token 无效" }, { "code": "500", "message": "订单数据查询失败" } ] }, { "method": "dashboard.warehouseStats", "description": "仓库发货统计(演示数据):返回固定的演示统计值,非实时查询结果,仅供前端展示与调试使用。无业务入参。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记,成功为 success" }, { "name": "code", "type": "number", "required": true, "description": "业务码,成功为 200" }, { "name": "message", "type": "string", "required": true, "description": "提示信息,成功为 成功" }, { "name": "data.todayOrders", "type": "number", "required": true, "description": "今日订单数(演示值 153023)" }, { "name": "data.orderTrend", "type": "number", "required": true, "description": "较昨日增长率(%,演示值 3)" }, { "name": "data.unassignedOrders", "type": "number", "required": true, "description": "未分配快递号订单数(演示值 3060)" }, { "name": "data.unprintedOrders", "type": "number", "required": true, "description": "未打印订单数(演示值 4591)" }, { "name": "data.unpickedOrders", "type": "number", "required": true, "description": "未拣货订单数(演示值 7651)" }, { "name": "data.pendingShipments", "type": "number", "required": true, "description": "待发货订单数(演示值 45907)" }, { "name": "data.shipmentProgress", "type": "number", "required": true, "description": "发货进度(%,演示值 70)" }, { "name": "data.todayOutbound", "type": "number", "required": true, "description": "今日已出库订单数(演示值 107116)" }, { "name": "data.outboundRate", "type": "number", "required": true, "description": "出库完成率(%,演示值 70)" }, { "name": "data.interceptedOrders", "type": "number", "required": true, "description": "拦截订单数(演示值 306)" }, { "name": "data.exceptionOrders", "type": "number", "required": true, "description": "异常订单数(演示值 1530)" }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": "401", "message": "未登录或 token 无效" }, { "code": "500", "message": "服务器内部错误" } ] }, { "method": "dashboard.hot_order_rank", "description": "热销商品排行:统计今日(00:00 至当前时刻)销量 Top10 商品及环比昨日趋势。仓库端按当前仓库统计,货主端跨全部签约仓库聚合。数据来源于真实数据库查询(订单明细/配送分表)。data[].sku 为库存商品ID(stock_warehouse.id),data[].name 已做脱敏处理(前2字符+***+后2字符)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记,成功为 success" }, { "name": "code", "type": "number", "required": true, "description": "业务码,成功为 200" }, { "name": "message", "type": "string", "required": true, "description": "提示信息,成功为 成功" }, { "name": "data", "type": "array", "required": true, "description": "热销商品排行列表(按今日销量降序,最多 10 条,无数据时为空数组)" }, { "name": "data[].id", "type": "number", "required": true, "description": "排行序号(从 1 开始)" }, { "name": "data[].name", "type": "string", "required": true, "description": "脱敏后的商品名称:保留前两个字符与后两个字符,中间以三个星号替代;长度不足 4 个字符时返回 ***;无名称时回退商品编码/商品+库存ID 后同样脱敏" }, { "name": "data[].sku", "type": "number", "required": true, "description": "库存商品ID(stock_warehouse.id);极端情况下订单明细无库存商品ID时回退商品编码字符串" }, { "name": "data[].value", "type": "number", "required": true, "description": "今日销量(件数)" }, { "name": "data[].trend", "type": "number", "required": true, "description": "环比昨日百分比(保留 1 位小数,昨日为 0 且今日 >0 时为 100)" }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": "0", "message": "缺少仓库上下文(仓库端未绑定仓库)或缺少货主上下文(货主端未绑定货主),返回 flag=failure" }, { "code": "401", "message": "未登录或 token 无效" }, { "code": "500", "message": "订单数据查询失败" } ] }, { "method": "dashboard.express_ratio", "description": "快递占比统计(饼图):按快递公司统计待处理订单数量及占比,按订单数降序返回;货主端自动跨已签约仓库汇总。无业务入参,依据登录用户上下文区分仓库端与货主端。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记,成功为 success" }, { "name": "code", "type": "number", "required": true, "description": "业务码,成功为 200" }, { "name": "message", "type": "string", "required": true, "description": "提示信息,成功为 成功" }, { "name": "data", "type": "array", "required": true, "description": "快递占比列表(按订单数降序,无数据时为空数组)" }, { "name": "data[].name", "type": "string", "required": true, "description": "快递公司名称(未填写时为 未指定快递)" }, { "name": "data[].value", "type": "number", "required": true, "description": "该快递公司的待处理订单数" }, { "name": "data[].itemStyle.color", "type": "string", "required": true, "description": "图表配色(十六进制色值)" }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": "0", "message": "缺少仓库上下文(仓库端未绑定仓库)或缺少货主上下文(货主端未绑定货主),返回 flag=failure" }, { "code": "401", "message": "未登录或 token 无效" }, { "code": "500", "message": "订单数据查询失败" } ] }, { "method": "dashboard.platform_distribution", "description": "平台分布统计(饼图):按系统平台统计待处理订单数量及占比,按订单数降序返回;货主端自动跨已签约仓库汇总。无业务入参,依据登录用户上下文区分仓库端与货主端。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记,成功为 success" }, { "name": "code", "type": "number", "required": true, "description": "业务码,成功为 200" }, { "name": "message", "type": "string", "required": true, "description": "提示信息,成功为 成功" }, { "name": "data", "type": "array", "required": true, "description": "平台占比列表(按订单数降序,无数据时为空数组)" }, { "name": "data[].name", "type": "string", "required": true, "description": "平台名称(未填写时为 未指定平台)" }, { "name": "data[].value", "type": "number", "required": true, "description": "该平台的待处理订单数" }, { "name": "data[].itemStyle.color", "type": "string", "required": true, "description": "图表配色(十六进制色值)" }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": "0", "message": "缺少仓库上下文(仓库端未绑定仓库)或缺少货主上下文(货主端未绑定货主),返回 flag=failure" }, { "code": "401", "message": "未登录或 token 无效" }, { "code": "500", "message": "订单数据查询失败" } ] }, { "method": "dashboard.order_trend", "description": "订单趋势统计:按小时统计当日 08:00 至当前小时的订单数与发货数,并返回发货率、峰值时段等汇总指标;依据当前用户绑定仓库统计。无业务入参。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记,成功为 success" }, { "name": "code", "type": "number", "required": true, "description": "业务码,成功为 200" }, { "name": "message", "type": "string", "required": true, "description": "提示信息,成功为 成功" }, { "name": "data.range", "type": "string", "required": true, "description": "统计范围,固定为 day" }, { "name": "data.date", "type": "string", "required": true, "description": "统计日期(YYYY-MM-DD)" }, { "name": "data.summary.total_orders", "type": "number", "required": true, "description": "当日订单总数" }, { "name": "data.summary.total_shipments", "type": "number", "required": true, "description": "当日发货总数" }, { "name": "data.summary.shipment_rate", "type": "number", "required": true, "description": "发货率(%,1 位小数)" }, { "name": "data.summary.peak_hour", "type": "string", "required": true, "description": "订单峰值时段(如 08:00)" }, { "name": "data.summary.peak_orders", "type": "number", "required": true, "description": "峰值时段订单数" }, { "name": "data.categories", "type": "array", "required": true, "description": "时段列表(08:00 至当前小时,如 ['08:00','09:00'])" }, { "name": "data.orders", "type": "array", "required": true, "description": "各时段订单数(与 categories 一一对应)" }, { "name": "data.shipments", "type": "array", "required": true, "description": "各时段发货数(与 categories 一一对应)" }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": "0", "message": "缺少仓库上下文(当前用户未绑定仓库),返回 flag=failure" }, { "code": "401", "message": "未登录或 token 无效" }, { "code": "500", "message": "订单数据查询失败" } ] } ] }, { "groupName": "基础模块", "module": "index", "list": [ { "method": "index.fastWhereTree", "description": "index.fastWhereTree 接口", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "type", "type": "string", "required": false, "source": "body", "description": "type 参数" } ], "response": [], "errors": [] }, { "method": "index.loadStores", "description": "index.loadStores 接口", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "index.loadWarehouses", "description": "index.loadWarehouses 接口", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "index.loadExpressInterfaces", "description": "index.loadExpressInterfaces 接口", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "systemExpressCode", "type": "string", "required": false, "source": "body", "description": "系统快递编码(wms_express.code),传入时仅返回该编码对应的快递接口" } ], "response": [ { "name": "code", "type": "number", "description": "业务状态码,200 表示成功" }, { "name": "message", "type": "string", "description": "业务提示信息" }, { "name": "expressInterfaces", "type": "array", "description": "当前仓库下的快递接口下拉列表", "children": [ { "name": "value", "type": "number", "description": "快递接口ID(wms_express_interface.id)" }, { "name": "label", "type": "string", "description": "快递接口名称(wms_express_interface.name)" } ] } ], "errors": [] }, { "method": "index.getCOSUploadConfig", "description": "index.getCOSUploadConfig 接口", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "data", "type": "object", "required": false, "source": "body", "description": "data 参数" } ], "response": [], "errors": [] }, { "method": "index.getImages", "description": "index.getImages 接口", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "index.uploadSuccessNotify", "description": "index.uploadSuccessNotify 接口", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "index.ReferenceFile", "description": "index.ReferenceFile 接口", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "index.getMessageDetail", "description": "index.getMessageDetail 接口", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "index.test", "description": "后台专用的拼多多开放平台测试接口,用于传入请求参数并发起真实请求,返回签名后的请求体和接口响应", "isNeedAuth": false, "isNeedLogin": false, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "type", "type": "string", "required": true, "source": "body", "description": "拼多多接口名,例如 pdd.order.number.list.get" }, { "name": "bizParams", "type": "object", "required": false, "source": "body", "description": "业务参数对象,会参与签名和请求" }, { "name": "request", "type": "object", "required": false, "source": "body", "description": "bizParams 兼容字段" }, { "name": "accessToken", "type": "string", "required": false, "source": "body", "description": "用户授权令牌" }, { "name": "access_token", "type": "string", "required": false, "source": "body", "description": "accessToken 的下划线命名兼容字段" }, { "name": "dataType", "type": "string", "required": false, "source": "body", "description": "返回格式,默认 JSON" }, { "name": "version", "type": "string", "required": false, "source": "body", "description": "API 版本" }, { "name": "timestamp", "type": "string|number", "required": false, "source": "body", "description": "时间戳,不传则使用当前秒级时间戳" }, { "name": "clientId", "type": "string", "required": false, "source": "body", "description": "覆盖配置中的 client_id" }, { "name": "clientSecret", "type": "string", "required": false, "source": "body", "description": "覆盖配置中的 client_secret" }, { "name": "baseUrl", "type": "string", "required": false, "source": "body", "description": "请求地址,默认拼多多开放平台网关" }, { "name": "headers", "type": "object", "required": false, "source": "body", "description": "额外请求头" }, { "name": "timeout", "type": "number", "required": false, "source": "body", "description": "请求超时时间(毫秒)" } ], "response": [ { "name": "requestBody", "type": "object", "description": "实际发送到 PDD 网关的请求体,已包含 sign" }, { "name": "response", "type": "any", "description": "拼多多接口返回内容" }, { "name": "baseUrl", "type": "string", "description": "实际请求地址" } ], "errors": [ { "code": "400", "description": "type 不能为空" }, { "code": "500", "description": "PDD 接口调用失败" } ] }, { "method": "index.recognizeLicensePlate", "description": "识别车牌号码(通过 base64 图片)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "base64", "type": "string", "required": true, "source": "body", "description": "base64 图片,支持 data URL 前缀(data:image/...;base64,)或纯 base64 字符串" }, { "name": "imageBase64", "type": "string", "required": false, "source": "body", "description": "兼容字段(同 base64)" }, { "name": "image_base64", "type": "string", "required": false, "source": "body", "description": "兼容字段(同 base64)" } ], "response": [ { "name": "licensePlate", "type": "string", "description": "识别到的车牌号(对外契约,仅返回该字段)" } ], "errors": [ { "code": "400", "description": "base64 图片不能为空 / base64 图片格式不正确 / 图片大小不能超过 7MB" }, { "code": "500", "description": "第三方 OCR 服务调用失败或腾讯云配置未设置" } ] }, { "method": "index.getI18nMessage", "description": "index.getI18nMessage 接口", "isNeedAuth": false, "isNeedLogin": false, "headers": [], "params": [ { "name": "language", "type": "string", "required": false, "source": "body|query", "description": "language 参数" } ], "response": [], "errors": [] }, { "method": "index.putI18nCollect", "description": "index.putI18nCollect 接口", "isNeedAuth": false, "isNeedLogin": false, "headers": [], "params": [ { "name": "keys", "type": "array", "required": false, "source": "body", "description": "keys 参数" }, { "name": "locale", "type": "string", "required": false, "source": "body", "description": "locale 参数" }, { "name": "project", "type": "string", "required": false, "source": "body", "description": "project 参数" }, { "name": "source", "type": "string", "required": false, "source": "body", "description": "source 参数" } ], "response": [], "errors": [] }, { "method": "index.tryAutoTranslateNewKeys", "description": "index.putI18nCollect 的内部辅助方法:目标语言非 zh-CN 时,为该项目在 zh-CN 已有翻译的键批量创建目标语言的翻译占位记录(translation=null、translation_status=0、auto_generated=1、translator=auto-translate),不调用翻译 API;无对外返回值,异常仅记日志,不建议作为 HTTP API 直接调用", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "project", "type": "string", "required": false, "source": "body", "description": "项目标识(如 wms);该方法为 putI18nCollect 的内部辅助函数,project 由 putI18nCollect 内部传入,不建议直接调用本接口传参" }, { "name": "targetLanguage", "type": "string", "required": false, "source": "body", "description": "目标语言代码(如 en-US);为 zh-CN 时方法直接返回,不生成任何翻译占位记录" } ], "response": [], "errors": [] }, { "method": "index.searchSpace", "description": "按当前仓库上下文搜索库位(使用 ctx.user.store_id;仅在 location_space 表中按 space_code/custom_barcode 搜索)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "keyword", "type": "string", "required": false, "source": "body", "description": "搜索关键字,对 space_code 和 custom_barcode 做模糊匹配(%keyword%);为空时返回当前仓库下前 50 条" } ], "response": [ { "name": "flag", "type": "string", "description": "全局调用结果标识,成功时为 success" }, { "name": "code", "type": "number", "description": "业务状态码,200 表示成功" }, { "name": "message", "type": "string", "description": "返回信息" }, { "name": "data", "type": "array", "description": "库位数组(最多 50 条),每项包含以下字段", "children": [ { "name": "id", "type": "number", "description": "库位 ID" }, { "name": "space_code", "type": "string", "description": "库位编码" }, { "name": "custom_barcode", "type": "string", "description": "库位自定义条码" }, { "name": "custom_name", "type": "string", "description": "库位自定义名称" } ] }, { "name": "total", "type": "number", "description": "本次返回的记录条数(等于 data.length,≤50)" } ], "errors": [] }, { "method": "index.searchSpaces", "description": "按当前仓库上下文批量搜索库位(使用 ctx.user.store_id;对每个关键字在 location_space 表中按 space_code/custom_barcode/custom_name 做模糊匹配,结果按传入顺序返回)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "keywords", "type": "array", "required": true, "source": "body", "description": "搜索关键字数组,每项对 space_code、custom_barcode、custom_name 做模糊匹配(%keyword%);非数组视为空数组" } ], "response": [ { "name": "flag", "type": "string", "description": "全局调用结果标识,成功时为 success" }, { "name": "code", "type": "number", "description": "业务状态码,200 表示成功" }, { "name": "message", "type": "string", "description": "返回信息" }, { "name": "data", "type": "array", "description": "库位列表的数组,与 keywords 一一对应;每项为库位数组(最多 50 条),无记录时对应项为空数组 []", "children": [ { "name": "id", "type": "number", "description": "库位 ID" }, { "name": "space_code", "type": "string", "description": "库位编码" }, { "name": "custom_barcode", "type": "string", "description": "库位自定义条码" }, { "name": "custom_name", "type": "string", "description": "库位自定义名称" } ] }, { "name": "total", "type": "number", "description": "返回的分组数量(等于 keywords.length)" } ], "errors": [] }, { "method": "index.listInterfaceTypes", "description": "查询可用的接口类型列表(如奇门仓储、开放接口等)", "isNeedAuth": false, "isNeedLogin": true, "params": [] }, { "method": "index.getLocationTypeList", "description": "查询库位类型基础列表,优先返回当前仓库下启用的库位类型,同时合并系统公共类型;结果带 300 秒缓存", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [ { "name": "list", "type": "array", "description": "库位类型列表", "children": [ { "name": "id", "type": "number", "description": "库位类型 ID" }, { "name": "type_code", "type": "string", "description": "库位类型编码" }, { "name": "type_name", "type": "string", "description": "库位类型名称" }, { "name": "temperature_zone", "type": "string", "description": "温区" }, { "name": "allow_allocation", "type": "boolean", "description": "是否允许分配储位" }, { "name": "allow_transfer_out", "type": "boolean", "description": "是否允许移出" }, { "name": "description", "type": "string", "description": "描述" }, { "name": "warehouse_id", "type": "number", "description": "所属仓库 ID,null 表示系统公共类型" } ] }, { "name": "total", "type": "number", "description": "返回总数" } ], "errors": [] }, { "method": "index.getPlatformOauthLink", "description": "获取平台授权链接。入参支持 code / platform_code / platformCode,服务端按首个非空值标准化为大写平台编码;会从当前登录上下文读取仓库 ID(ctx.user.store_id),再从 wms_platform.auth_base_url 读取授权基础地址。接口会优先复用当前仓库与平台下 status=0 的未授权记录;若历史 auth_random_code 带有当前配置前缀,则会先去前缀后以裸码回写,当前数据库最终保存的 auth_random_code 为裸码。若无可复用记录则生成新的裸码并写入 wms_shops。返回的 oauth_link 会从配置 platformOauthReservationCodePrefix 读取前缀(本地示例为 xxxxx_),按“前缀 + 平台编码 + '_' + 裸码”生成 state,并将 URL 编码后的 state 直接拼接到平台基础授权链接后,例如 xxxxx_PDD_。当前仅支持已按上述模式配置好的基础授权链接。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "code", "type": "string", "required": false, "source": "body", "description": "平台编码主字段;与 platform_code / platformCode 三选一即可,服务端按 code -> platform_code -> platformCode 顺序取首个非空值并转为大写" }, { "name": "platform_code", "type": "string", "required": false, "source": "body", "description": "平台编码下划线别名" }, { "name": "platformCode", "type": "string", "required": false, "source": "body", "description": "平台编码驼峰别名" } ], "response": [ { "name": "code", "type": "number", "required": true, "description": "业务状态码,成功时返回 200" }, { "name": "data.platform_code", "type": "string", "required": true, "description": "标准化后的平台编码" }, { "name": "data.oauth_link", "type": "string", "required": true, "description": "基于 wms_platform.auth_base_url 构造的授权链接;实际拼接值为 encodeURIComponent(prefix + platform_code + '_' + rawCode),其中 prefix 来自 platformOauthReservationCodePrefix,rawCode 为数据库 auth_random_code 中保存的裸码。基础授权链接需预先配置为可直接追加 state 值的模式。" } ], "errors": [ { "code": 400, "message": "平台编码不能为空" }, { "code": 400, "message": "未识别到当前仓库" }, { "code": 400, "message": "平台不存在" }, { "code": 400, "message": "平台授权基础地址未配置" }, { "code": 500, "message": "创建平台授权预占记录失败" }, { "code": 500, "message": "生成唯一授权码失败,请稍后重试" } ] }, { "method": "index.getShopList", "description": "获取当前登录仓库下的已授权店铺列表,支持按平台编码可选过滤。仓库上下文来自 ctx.user.store_id;服务端兼容读取 body.platform_code 与 body.platformCode,按该顺序取首个 trim 后非空值作为平台过滤条件。未传平台参数时返回当前登录仓库下全部已授权店铺;传入非空平台编码时仅返回该平台的已授权店铺。结果按 status DESC、updated_at DESC、id DESC 排序,并对敏感字段完成脱敏后返回 data.list。", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "platform_code", "type": "string", "required": false, "source": "body", "description": "平台编码过滤条件;兼容 platformCode。服务端按 platform_code、platformCode 的顺序读取首个值,trim 后非空时仅返回该平台的已授权店铺;未传或为空时返回当前登录仓库下全部已授权店铺。" } ], "response": [ { "name": "code", "type": "number", "required": true, "description": "业务状态码,成功时返回 200" }, { "name": "message", "type": "string", "required": true, "description": "业务提示信息,成功时返回 ok" }, { "name": "data.list", "type": "array", "required": true, "description": "当前登录仓库下按条件过滤后的已授权店铺列表数组;未传平台参数时返回当前仓库全部已授权店铺,传入非空 platform_code/platformCode 时仅返回对应平台店铺。结果按 status DESC、updated_at DESC、id DESC 排序,且 owner_id、access_token、refresh_token、auth_random_code 已按实现规则脱敏。", "children": [ { "name": "id", "type": "number", "description": "店铺主键 ID" }, { "name": "warehouse_id", "type": "number", "description": "所属仓库 ID(来自当前登录仓库上下文)" }, { "name": "platform_code", "type": "string", "description": "平台编码" }, { "name": "shop_name", "type": "string", "description": "店铺名称" }, { "name": "custom_name", "type": "string|null", "description": "店铺自定义名称;wms_shops 当前真实字段,未设置时返回 null" }, { "name": "status", "type": "number", "description": "授权状态:0=未授权,1=已授权" }, { "name": "auth_expire_at", "type": "string|null", "description": "授权到期时间,未设置时返回 null" }, { "name": "token_expires_at", "type": "string|null", "description": "访问令牌过期时间,未设置时返回 null" }, { "name": "refresh_token_expires_at", "type": "string|null", "description": "刷新令牌过期时间,未设置时返回 null" }, { "name": "scope", "type": "object|array|null", "description": "授权范围;直接返回数据库 JSON 字段内容,可能为对象、数组或 null" }, { "name": "created_at", "type": "string", "description": "创建时间" }, { "name": "updated_at", "type": "string", "description": "更新时间" }, { "name": "owner_id", "type": "string|null", "description": "平台店铺/主体 ID;非空且长度大于 5 时返回前 3 位 + *** + 后 2 位,长度小于等于 5 时返回 ***,空值返回 null" }, { "name": "access_token", "type": "string|null", "description": "访问令牌;非空固定返回 ***,空值返回 null" }, { "name": "refresh_token", "type": "string|null", "description": "刷新令牌;非空固定返回 ***,空值返回 null" }, { "name": "auth_random_code", "type": "string|null", "description": "授权随机码;非空固定返回 ***,空值返回 null" } ] } ], "errors": [ { "code": 400, "message": "未识别到当前仓库" } ] }, { "method": "index.getShopExpressList", "description": "获取指定店铺的快递签约/电子面单可用列表。接口依赖当前登录仓库上下文 ctx.user.store_id 校验店铺归属;服务端会按店铺所属平台拉取并收敛可用快递列表,统一返回前端消费结构;未接入的平台当前返回空列表。", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "shop_id", "type": "string|number", "required": false, "source": "body", "description": "店铺 ID;与 shopId 兼容,二选一至少传一个。服务端按 shop_id、shopId 的顺序读取首个非空值。" }, { "name": "shopId", "type": "string|number", "required": false, "source": "body", "description": "店铺 ID 的驼峰兼容字段;当 shop_id 为空时读取该值。" } ], "response": [ { "name": "code", "type": "number", "required": true, "description": "业务状态码,成功时返回 200。" }, { "name": "message", "type": "string", "required": true, "description": "业务提示信息,成功时返回 ok。" }, { "name": "data.shop_id", "type": "number", "required": true, "description": "当前店铺 ID。" }, { "name": "data.platform_code", "type": "string", "required": true, "description": "店铺所属平台编码,返回值按服务端实现转为大写。" }, { "name": "data.list", "type": "array", "required": true, "description": "服务端按店铺所属平台拉取并统一收敛后的快递签约/电子面单可用列表;未接入的平台返回空数组。", "children": [ { "name": "wp_code", "type": "string", "required": true, "description": "快递/面单服务编码。" }, { "name": "wp_name", "type": "string", "required": true, "description": "系统快递名称;由系统快递基础表根据平台快递编码 wp_code 映射得到,未匹配到时返回空字符串。" }, { "name": "sys_express_code", "type": "string", "required": true, "description": "系统快递编码;由平台快递编码 wp_code 映射得到,未匹配到时返回空字符串。" }, { "name": "wp_type", "type": "string", "required": true, "description": "快递/面单类型标识。" }, { "name": "accounts", "type": "array", "required": true, "description": "当前快递服务下的签约账号列表;无签约账号时返回空数组。", "children": [ { "name": "branch_code", "type": "string", "required": true, "description": "网点/签约账号编码。" }, { "name": "branch_name", "type": "string", "required": true, "description": "网点/签约账号名称。" }, { "name": "quantity", "type": "number", "required": true, "description": "当前可用单量。" }, { "name": "cancel_quantity", "type": "number", "required": true, "description": "已取消单量。" }, { "name": "recycled_quantity", "type": "number", "required": true, "description": "已回收单量。" }, { "name": "allocated_quantity", "type": "number", "required": true, "description": "已分配单量。" }, { "name": "ship_addresses", "type": "array", "required": true, "description": "发货地址列表;无可用地址时返回空数组。", "children": [ { "name": "country", "type": "string", "required": true, "description": "国家。" }, { "name": "province", "type": "string", "required": true, "description": "省。" }, { "name": "city", "type": "string", "required": true, "description": "市。" }, { "name": "district", "type": "string", "required": true, "description": "区/县。" }, { "name": "detail", "type": "string", "required": true, "description": "详细地址。" }, { "name": "full_address", "type": "string", "required": true, "description": "完整地址。" } ] }, { "name": "services", "type": "array", "required": true, "description": "当前签约账号可用的附加服务列表;无可用服务时返回空数组。", "children": [ { "name": "service_code", "type": "string", "required": true, "description": "服务编码。" }, { "name": "service_name", "type": "string", "required": true, "description": "服务名称。" }, { "name": "service_desc", "type": "string", "required": true, "description": "服务说明。" }, { "name": "required", "type": "boolean", "required": true, "description": "是否为必选服务。" }, { "name": "attributes", "type": "array", "required": true, "description": "服务属性列表;无属性时返回空数组。", "children": [ { "name": "attribute_code", "type": "string", "required": true, "description": "属性编码。" }, { "name": "attribute_name", "type": "string", "required": true, "description": "属性名称。" }, { "name": "attribute_type", "type": "string", "required": true, "description": "属性类型编码。" }, { "name": "type_desc", "type": "string", "required": true, "description": "属性类型说明。" } ] } ] } ] } ] } ], "errors": [ { "code": 400, "message": "shop_id 不能为空" }, { "code": 400, "message": "未识别到当前仓库" }, { "code": 404, "message": "店铺不存在" }, { "code": 400, "message": "店铺未授权" } ] }, { "method": "index.getCainiaoStfTemplates", "description": "公共无参查询淘宝菜鸟标准模板列表;服务端调用淘宝开放平台 cainiao.cloudprint.stdtemplates.get,请求地址为 https://eco.taobao.com/router/rest,使用 TOP 公共签名参数。不需要用户授权,不下发 session,不依赖登录态、当前仓库或店铺授权。成功返回 data.platform_code='TB' 与标准模板数组,模板项统一字段为 template_id/template_name/template_url/cp_code/wp_code。", "isNeedAuth": false, "isNeedLogin": false, "headers": [], "params": [], "response": [ { "name": "code", "type": "number", "required": true, "description": "业务状态码,成功时返回 200。" }, { "name": "message", "type": "string", "required": true, "description": "业务提示信息,成功时返回 ok。" }, { "name": "data.platform_code", "type": "string", "required": true, "description": "平台编码,固定返回 TB。" }, { "name": "data.list", "type": "array", "required": true, "description": "菜鸟标准模板列表;来源于 cainiao_cloudprint_stdtemplates_get_response.result.datas[*].standard_templates[*] 的宽松兼容解析结果,按统一字段 template_id/template_name/template_url/cp_code/wp_code 返回。", "children": [ { "name": "template_id", "type": "string", "required": true, "description": "模板唯一标识;缺失时返回空字符串。" }, { "name": "template_name", "type": "string", "required": true, "description": "模板名称;缺失时返回空字符串。" }, { "name": "template_url", "type": "string", "required": true, "description": "模板预览或打印地址;缺失时返回空字符串。" }, { "name": "cp_code", "type": "string", "required": true, "description": "快递公司编码;结合 datas 节点与模板项宽松提取,缺失时返回空字符串。" }, { "name": "wp_code", "type": "string", "required": true, "description": "快递面单服务编码;结合 datas 节点的 brand_code/cp_code 与模板项宽松提取,缺失时返回空字符串。" } ] } ], "errors": [ { "code": 500, "message": "淘宝菜鸟标准模板查询失败" } ] }, { "method": "index.getPrintPlatformTemplateList", "description": "按打印平台与快递编码查询模板列表。express_code 为必填;接口会先按 platform_code(默认 CAINIAO)定位 wms_express 对应打印平台字段,再以 express_code 过滤可用模板后返回。", "isNeedAuth": false, "isNeedLogin": false, "headers": [], "params": [ { "name": "platform_code", "type": "string", "required": false, "source": "body", "description": "打印平台编码(如 CAINIAO);不传默认 CAINIAO,服务端会转为大写。" }, { "name": "express_code", "type": "string", "required": true, "source": "body", "description": "快递编码(必填);服务端会转为大写,并用于按 wms_express 中对应打印平台字段筛选模板。" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "全局结果标识;成功为 success,失败为 failure。" }, { "name": "code", "type": "number", "required": true, "description": "业务状态码;成功时为 200。" }, { "name": "message", "type": "string", "required": true, "description": "提示信息;成功时为 ok。" }, { "name": "data", "type": "object", "required": true, "description": "返回数据对象。", "children": [ { "name": "platform_code", "type": "string", "required": true, "description": "规范化后的平台编码(大写);未传时默认 CAINIAO。" }, { "name": "express_code", "type": "string", "required": true, "description": "规范化后的快递编码(大写)。" }, { "name": "responseData", "type": "object", "required": true, "description": "平台模板响应数据;CAINIAO 场景下会按 platform_code 对应字段 + express_code 过滤 cainiao_cloudprint_stdtemplates_get_response.result.datas 后返回,未实现平台返回空对象。" } ] } ], "errors": [ { "code": 400, "message": "express_code 不能为空" }, { "code": 500, "message": "获取打印平台模板列表失败" } ] }, { "method": "index.polyapiAuthorizeUrl", "description": "生成菠萝派授权链接。该接口不接收请求参数,服务端会固定调用 Differ.JH.BuildeAuthorizeUrl,并以内置配置 this.app.config.poloApi.appKey / this.app.config.poloApi.secret 以及当前代码中写死的 callbackUrl=http://39.100.57.68/、state=123456、itemcode=test001 作为上游请求参数,最终将菠萝派接口原始响应包裹后返回。", "isNeedAuth": false, "isNeedLogin": false, "headers": [], "params": [], "response": [ { "name": "code", "type": "number", "required": true, "description": "业务状态码,成功时返回 200。" }, { "name": "message", "type": "string", "required": true, "description": "业务提示信息,成功时返回 ok。" }, { "name": "data.respone", "type": "object", "required": true, "description": "菠萝派接口 Differ.JH.BuildeAuthorizeUrl 的原始响应对象。字段名按当前实现保持为 respone。" } ], "errors": [] }, { "method": "index.toOrder", "description": "根据运单号快速查询订单ID及其所属波次下所有订单ID列表。查询流程:1) 通过运单号查询 wms_order_express 表(status=1)获取 order_id 和 warehouse_id;2) 遍历多表(current/history/dispatch)获取 wave_id 和 wave_no;3) 若有有效波次则再遍历多表查询该波次下所有订单的 ID 列表。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "waybill_code", "type": "string", "required": true, "source": "body", "description": "运单号" } ], "response": [ { "name": "order_id", "type": "number", "required": true, "description": "订单ID" }, { "name": "waves", "type": "array", "required": true, "description": "波次列表,无波次时为空数组。每项含 wave_id(波次ID,number)、wave_no(波次号,string)、order_ids(波次下所有订单ID列表,number[])" }, { "name": "waves[].wave_id", "type": "number", "required": true, "description": "波次ID" }, { "name": "waves[].wave_no", "type": "string", "required": true, "description": "波次号" }, { "name": "waves[].order_ids", "type": "array", "required": true, "description": "该波次下所有订单的 ID 列表" } ], "errors": [ { "code": 405, "message": "运单号不能为空" }, { "code": 405, "message": "未找到该运单号对应的订单" } ] }, { "method": "index.getWorkbenchBindCode", "description": "获取工作台绑定码(免登录、免鉴权,参考 user.getLoginWechatCode):返回 client_code 并在缓存生成绑定码;不传 client_code 时分配新客户端编码并立即返回绑定码;传入 client_code 时进入长轮询等待 workbench.bind 完成,绑定成功后返回 token,等待超时/缓存失效时重新生成绑定码后才返回数据", "isNeedAuth": false, "isNeedLogin": false, "headers": [], "params": [ { "name": "clientCode", "type": "string", "required": false, "source": "body", "description": "客户端编码(6 位大写字母+数字);首次可不传,后续轮询建议透传已有值" } ], "response": [ { "name": "client_code", "type": "string", "required": true, "description": "客户端编码(6 位大写字母+数字)" }, { "name": "code", "type": "string", "required": true, "description": "缓存生成的绑定码(6 位大写字母+数字,供 workbench.bind 使用)" }, { "name": "status", "type": "string", "required": true, "description": "会话状态:pending 等待绑定 / bound 已绑定" }, { "name": "workbench_id", "type": "number", "required": false, "description": "已绑定的工作台ID(仅 bound 状态返回)" }, { "name": "token", "type": "string", "required": false, "description": "绑定成功后返回的工作台 token(64 位,仅 bound 状态返回)" }, { "name": "updated_at", "type": "string", "required": true, "description": "状态更新时间" }, { "name": "expires_at", "type": "string", "required": false, "description": "会话过期时间(ISO 字符串,可能为 null)" }, { "name": "expire_after_ms", "type": "number", "required": true, "description": "距离过期的剩余毫秒数" } ], "errors": [ { "code": "400", "message": "无效的客户端编码格式" } ] }, { "method": "index.LoginWorkbenchByCode", "description": "通过工作台登录码登录获取 token(免登录、免鉴权):以 wms_workbench.login_code 为入参查询工作台,命中则返回其 token(工作台尚无 token 时自动生成并持久化,等价补绑定),并将 token 信息写入 workbench:token:{token} 缓存;无匹配工作台返回失败(flag=failure、code=403)", "isNeedAuth": false, "isNeedLogin": false, "headers": [], "params": [ { "name": "loginCode", "type": "string", "required": true, "source": "body", "description": "工作台登录码(前缀 wblc + 随机段共 64 位,兼容 login_code 驼峰/下划线两种入参名)" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "工作台ID" }, { "name": "workbench_id", "type": "number", "required": true, "description": "工作台ID(同 id)" }, { "name": "name", "type": "string", "required": true, "description": "工作台名称" }, { "name": "token", "type": "string", "required": true, "description": "工作台 token(64 位)" } ], "errors": [ { "code": "400", "message": "login_code 不能为空" }, { "code": "403", "message": "工作台不存在或登录码无效(返回 flag=failure、code=403)" } ] }, { "method": "index.queryUserByToken", "description": "按 token(ye4s 登录临时码)查询用户信息(免登录、免鉴权):以 ye4s 库 ye4s_user 表 tmp_code 字段为入参查询用户,命中返回 flag=success、code=200 与 real_name(用户真实姓名)、wms_account_id(WMS 账号 ID);未命中返回 flag=failure、code=404(用户不存在);数据库异常返回 code=500", "isNeedAuth": false, "isNeedLogin": false, "headers": [], "params": [ { "name": "token", "type": "string", "required": true, "source": "body", "description": "ye4s 登录临时码(对应 ye4s 库 ye4s_user 表 tmp_code 字段);为空返回 code 400「token 不能为空」" } ], "response": [ { "name": "real_name", "type": "string", "required": true, "description": "用户真实姓名(无值时为空字符串)" }, { "name": "wms_account_id", "type": "number", "required": false, "description": "WMS 账号 ID(未绑定时为 null)" } ], "errors": [ { "code": "400", "message": "token 不能为空" }, { "code": "404", "message": "用户不存在(返回 flag=failure、code=404)" }, { "code": "500", "message": "查询失败(数据库异常,message 为具体错误信息)" } ] }, { "method": "index.uploadClientErrorLog", "description": "上报客户端错误日志(免登录、免权限、免鉴权,保留系统日志):设备端将运行时错误日志批量上报到服务端暂存表 wms_client_error_log。入参支持三种形态——单条对象、数组、{ logs: [...] },单次最多 50 条;字段命名兼容 snake_case 与 camelCase 别名。error_message 与 error_stack 至少一项有值(超长分别截断 5000 / 65535 字符),extra 超长截断 65535;report_uuid 幂等去重(重复上报静默成功,duplicated +1、不产生重复行;缺失时服务端生成 srv-{uuid} 且不保证幂等);client_time 仅参考(毫秒/秒时间戳或日期字符串,非法值存 null)。成功返回 flag=success、code=200 与 total/accepted/duplicated/rejected/rejected_reasons 统计;方法级错误按 /system 惯例为 HTTP 200 + flag=failure(code=400/500)。", "isNeedAuth": false, "isNeedLogin": false, "headers": [], "params": [ { "name": "client_type", "type": "string", "required": false, "source": "body", "description": "客户端类型:android/ios/web 等;表宽 STRING(32),超出截断;兼容 camelCase 别名 clientType" }, { "name": "app_version", "type": "string", "required": false, "source": "body", "description": "客户端版本号;表宽 STRING(64),超出截断;别名 appVersion" }, { "name": "device_id", "type": "string", "required": false, "source": "body", "description": "设备唯一标识;表宽 STRING(128),超出截断;别名 deviceId" }, { "name": "os_version", "type": "string", "required": false, "source": "body", "description": "操作系统版本;表宽 STRING(64),超出截断;别名 osVersion" }, { "name": "device_model", "type": "string", "required": false, "source": "body", "description": "设备型号;表宽 STRING(128),超出截断;别名 deviceModel" }, { "name": "error_type", "type": "string", "required": false, "source": "body", "description": "错误类型/等级;表宽 STRING(64),超出截断;别名 errorType" }, { "name": "error_message", "type": "string", "required": false, "source": "body", "description": "错误信息;与 error_stack 至少一项有值,超长截断至 5000 字符;别名 errorMessage" }, { "name": "error_stack", "type": "string", "required": false, "source": "body", "description": "错误堆栈;与 error_message 至少一项有值,超长截断至 65535 字符;别名 errorStack" }, { "name": "extra", "type": "string", "required": false, "source": "body", "description": "附加上下文;字符串或对象(对象序列化为 JSON 字符串),超长截断至 65535 字符" }, { "name": "report_uuid", "type": "string", "required": false, "source": "body", "description": "客户端上报幂等ID(唯一索引 uk_report_uuid);表宽 STRING(64),超出截断;重复上报静默成功(duplicated +1,不产生重复行);缺失时服务端生成 srv-{uuid},此时不保证幂等;别名 reportUuid" }, { "name": "client_time", "type": "string", "required": false, "source": "body", "description": "客户端错误发生时间(仅参考,不作为记录时间):毫秒/秒时间戳或日期字符串,非法值存 null;别名 clientTime" }, { "name": "logs", "type": "array", "required": false, "source": "body", "description": "包裹形态 { logs: [...] } 的上报条目数组,单次最多 50 条;与「单条对象」「数组」三种形态三选一" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "结果标记:success" }, { "name": "code", "type": "number", "required": true, "description": "业务码:200 成功;400 入参形状错误/空数据/超 50 条/全部条目无效;500 查询或写入失败(方法级错误仍为 HTTP 200)" }, { "name": "message", "type": "string", "required": true, "description": "提示文案:成功为「上报成功」" }, { "name": "success", "type": "boolean", "required": true, "description": "服务处理结果标记:true 表示成功(400/500 失败响应无此字段)" }, { "name": "total", "type": "number", "required": true, "description": "本次上报条数" }, { "name": "accepted", "type": "number", "required": true, "description": "新入库条数" }, { "name": "duplicated", "type": "number", "required": true, "description": "幂等去重条数(report_uuid 已存在,静默成功、不产生重复行)" }, { "name": "rejected", "type": "number", "required": true, "description": "校验失败条数" }, { "name": "rejected_reasons", "type": "array", "required": false, "description": "拒绝明细(最多返回 10 条),每条含 index(0 起条目下标)与 reason(原因文案)" }, { "name": "timestamp", "type": "number", "required": true, "description": "服务端响应时间戳(秒)" } ], "errors": [ { "code": 400, "message": "入参形状错误(非对象/数组且无 logs 键)、缺少上报日志数据(空数组)、单次超过 50 条、全部条目无效(error_message 与 error_stack 均无值);HTTP 200 + flag=failure,body 仅含 flag/code/message/timestamp" }, { "code": 500, "message": "查询已有 report_uuid 失败或批量写入失败(HTTP 200 + flag=failure,body 仅含 flag/code/message/timestamp)" } ] }, { "method": "index.getWarehousePanelData", "description": "仓库面板数据接口:按仓库做增量变更检测,is_change=false 时返回空 data(节约流量),data 已填充有数据源的字段(无数据源的字段暂不输出)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "last_change_at", "type": "number", "required": false, "source": "body", "description": "最后一次更改的时间戳(Unix 秒);常规调用(force=false)必填,小于缓存最后更改时间戳时返回 is_change=true;force=true 时可选,缺省视为 0" }, { "name": "force", "type": "boolean", "required": false, "source": "body", "description": "首次拉取兼容入参(true/1/'true'),当前仅影响 last_change_at 是否可缺省" } ], "response": [ { "name": "is_change", "type": "boolean", "required": true, "description": "是否已改变:传入时间戳小于缓存最后更改时间戳时为 true,否则为 false(缓存无最后时间时恒为 true)" }, { "name": "last_change_at", "type": "number", "required": true, "description": "缓存最后更改时间戳(Unix 秒,一般由外部业务驱动;缓存无最后时间时为本接口拉取数据时刻);前端保存后作为下次轮询的 last_change_at 入参回传" }, { "name": "data", "type": "object", "required": true, "description": "面板数据对象;is_change=false 时为空对象(节约流量),is_change=true 时输出。已输出字段:title(仓库名)、fulfillment(订单履约链路 6 环节未/已 + total)、stageOverview(totalOrders/interceptOrders/stages 5 卡:receiving/shelf/pick/recheck/pack)、b2b(orders/goods/sku)、groupPicking、scatterPicking(orders/goods/sku/wave/top5)、packingRank(personal:orders/goods/sku/wave/top5)、trend(max/points 08:00-18:00 共 11 点)、weeklyEfficiency(days 7 天 intercept)" } ], "errors": [], "notes": [ "缓存键 index:warehousePanel:lastChangeAt:{warehouseId},值为 { last_change_at, data },TTL 300 秒。拉取逻辑:缓存有最后更新时间且传入时间戳未过期 → is_change=false + 空 data 不查库;时间戳过期且缓存有数据 → 直接输出缓存数据;时间戳过期但缓存无数据(外部只驱动了时间戳)→ 查库拉数据补入缓存并保留外部时间戳;缓存无最后更新时间(未命中/过期)→ 查库拉数据并设置最后更新时间", "最后更新时间一般由外部驱动:业务数据变化时由外部写入缓存键的 last_change_at(只写时间戳即可,数据由本接口下次拉取时补入)", "未输出字段(数据源或口径未定):履约链路第 7 环节退件签收、stageOverview 质检卡、收货/上架卡的 today/abnormal、weeklyEfficiency 的 throughput/max、packingRank 的 group(组别口径未定)", "口径:fulfillment 各环节按订单分表状态字段(post_status/print_status/pick_status/recheck_status/pack_status/outbound_status)未/已;groupPicking=wave_pick_task pick_mode 1,5,scatterPicking=2,3,4(今日创建任务,orders/wave 取任务快照,goods/sku 经任务订单关联表 join 订单分表 items_total/items_count);packingRank.personal 按 pack_task_packer.account_name 聚合(今日创建且非异常任务);trend 固定 08:00-18:00 按小时补零;weeklyEfficiency.days 时间锚点=COALESCE(intercept_time, create_at)" ] } ] }, { "groupName": "订单工作台入口模块", "module": "order.index", "list": [ { "method": "order.list", "description": "订单工作台总列表入口,查询当前登录用户仓库上下文下的订单总列表,支持 pagination / where / sort。;列表运单号回填强制同仓校验:wms_order_express 按「订单ID + 订单所属仓库ID」隔离读取,禁止仅凭订单ID跨仓串读运单号", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page / pageSize,兼容 currentPage / page_size / size" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "统一 where 条件对象;推荐使用 { operator, value, type } 标准结构,历史简写会自动标准化;禁止传入 warehouse_id / warehouseId。支持虚拟字段:buyer_message_has(覆盖 buyer_message/seller_message/remark 三个字段,任一有值即为有留言,value=true/false),express_numbers / waybill_codes(运单号筛选),wave_index(波次内序号筛选,联查 wms_order_wave_index,支持 eq/in/gt/lt/ge/le/between/notbetween,between 要求 value 为长度 2 的数组,如 {\"wave_index\":{\"operator\":\"between\",\"value\":[1,50]}}),wave_scope(波次范围筛选,直接按订单表 wave_scope 字段过滤,支持单个值、数组多选或 { operator, value } 结构;取值:0=未分配波次,1=大团购,2=散单,3=小团购,4=单品单件;示例 {\"wave_scope\":{\"operator\":\"in\",\"value\":[1,3]}} 筛选大团购+小团购,{\"wave_scope\":0} 筛选未分配波次订单)。create_channel(订单来源渠道筛选,按订单表 create_channel 列过滤;枚举:MANUAL=手工单、API=接口、QM=奇门、STOCKOUT=出库转单)。支持简写与标准结构:{\"create_channel\":\"MANUAL\"} 单值精确、{\"create_channel\":[\"QM\",\"API\"]} 裸数组按 in 多选、{\"create_channel\":{\"operator\":\"in\",\"value\":[\"QM\",\"API\"]}} 标准结构多选、{\"create_channel\":{\"operator\":\"ne\",\"value\":\"MANUAL\"}} 排除指定渠道。注意:列表响应中的 create_channel 已格式化为中文标签(手工单/接口/奇门/出库转单),查询条件请传英文枚举值。" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数,支持 sortField / sortOrder" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "订单列表(raw 行数据,字段字典见 docs/order-workbench-list-api.md 中的“订单列表 raw 字段字典”章节),本次新增 store_remark(货主备注)字段;wave_index(波次内序号,联查 wms_order_wave_index,无记录时为 0)。" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)" }, { "name": "recheck_status", "type": "string", "required": false, "description": "复核状态:none=未复核,fin=已复核" } ], "errors": [ { "code": "400", "message": "缺少仓库上下文或 where 参数格式错误" }, { "code": "500", "message": "查询失败" } ] }, { "method": "order.detail", "description": "查询单个订单详情,返回订单头、商品明细和运单信息;运单信息强制同仓校验:wms_order_express 按「订单ID + 订单所属仓库ID」隔离读取,禁止仅凭订单ID跨仓串读运单号", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids / id / order_id / orderId", "type": "array|string|number", "required": true, "source": "body", "description": "订单ID;支持 ids 数组、逗号分隔字符串或单个 id/order_id,至少提供一项" }, { "name": "tableType / tablePosition / type / moduleName", "type": "string", "required": false, "source": "body", "description": "可选,指定订单表类型,支持 current/history/dispatch/outsourced/order/revieworder/pendingorder 等" } ], "response": [ { "name": "order", "type": "object", "required": true, "description": "订单头对象(raw 行数据)" }, { "name": "detail", "type": "object", "required": true, "description": "等同于 order" }, { "name": "orderItems / items", "type": "array", "required": true, "description": "商品明细数组" }, { "name": "expresses", "type": "array", "required": true, "description": "运单信息数组,每个元素包含以下字段:waybill_code(运单号,string)、weighing_weight(称重重量,number|null)、sys_logistics_code(系统物流公司编码,string)、sys_logistics_name(系统物流公司名称,string)、logistics_code(实际物流公司编码,string)、logistics_name(实际物流公司名称,string)、logistics_interface_id(物流接口ID,number|null)、business_key(业务标识,string)、created_at(创建时间戳毫秒,number|null)、package_material_id(包材ID,number|null)、package_material_name_snapshot(包材名称快照,string|null)" }, { "name": "waybill_codes", "type": "array", "required": true, "description": "去重后的运单号字符串数组" } ], "errors": [ { "code": "400", "message": "订单ID 为空或格式错误" }, { "code": "404", "message": "订单不存在或不属于当前仓库" }, { "code": "500", "message": "内部错误" } ] }, { "method": "order.manualOutboundOrder", "description": "手动触发出库迁移,将当前仓库内已出库订单同步到配送表。请求体直接透传给 orderDeliveryMigration.syncOutboundOrdersToDelivery。迁移写入配送表(wms_order_delivery_{仓库}_dispatch)的订单行会记录 dispath_time(订单迁移进配送表的时间,由 orderDeliveryMigration.buildDispatchRow 写入 new Date(),仅配送表独有)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "warehouseId", "type": "number", "required": false, "source": "body", "description": "单仓库ID,兼容 warehouse_id" }, { "name": "warehouseIds", "type": "array", "required": false, "source": "body", "description": "仓库ID 数组" }, { "name": "queryTimeoutMs", "type": "number", "required": false, "source": "body", "description": "查询超时时间(毫秒)" }, { "name": "executionTimeoutMs", "type": "number", "required": false, "source": "body", "description": "执行超时时间(毫秒)" } ], "response": [ { "name": "warehouseIds", "type": "array", "required": true, "description": "参与迁移的仓库ID列表" }, { "name": "batchSize", "type": "number", "required": true, "description": "单批处理上限,当前固定为 1000" }, { "name": "outboundStatuses", "type": "array", "required": true, "description": "本次迁移匹配的出库状态" }, { "name": "totalSelected", "type": "number", "required": true, "description": "命中的源订单数量" }, { "name": "totalCreated", "type": "number", "required": true, "description": "实际创建到配送表的订单数量" }, { "name": "totalSkipped", "type": "number", "required": true, "description": "本次跳过的源订单数量" }, { "name": "totalTimeout", "type": "number", "required": true, "description": "被标记为出库超时的订单数量" }, { "name": "results", "type": "array", "required": true, "description": "按仓库维度返回的批次结果数组,元素包含 selectedCount、createdCount、skippedCount、timeoutCount、retryableFailure 等字段" } ], "errors": [ { "code": "400", "message": "仓库ID为空或请求参数格式错误" }, { "code": "500", "message": "迁移失败或数据库错误" } ] }, { "method": "order.badgeCount", "description": "订单工作台各标签页角标计数,基于当前仓库上下文返回。配送、配送异常与归档标签固定返回 99+。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [ { "name": "reviewOrder", "type": "number|string", "required": true, "description": "待审核角标" }, { "name": "pendingOrder", "type": "number|string", "required": true, "description": "待处理角标" }, { "name": "outboundOrder", "type": "number|string", "required": true, "description": "待出库角标" }, { "name": "expectionOrder", "type": "number|string", "required": true, "description": "待处理异常角标" }, { "name": "entrustOrder", "type": "number|string", "required": true, "description": "委托外仓角标" }, { "name": "deliveryOrder", "type": "string", "required": true, "description": "配送角标,固定返回 99+" }, { "name": "deliveryExpectionOrder", "type": "string", "required": true, "description": "配送异常角标,固定返回 99+" }, { "name": "archiveOrder", "type": "string", "required": true, "description": "归档角标,固定返回 99+" } ], "errors": [ { "code": "400", "description": "缺少当前仓库上下文 store_id" } ] }, { "method": "order.queryOrderLogs", "description": "查询当前仓库下订单操作日志,底层复用通用日志查询分页结构,按订单ID筛选。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "string", "required": true, "source": "body", "description": "订单ID" }, { "name": "page", "type": "number", "required": false, "source": "body", "description": "页码" }, { "name": "pageSize", "type": "number", "required": false, "source": "body", "description": "每页数量" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "日志列表,字段与 stock.warehouse.queryStockLogs 保持一致" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息,包含 page、pageSize、total、totalPages" } ], "errors": [ { "code": "400", "description": "订单ID为空或仓库上下文缺失" }, { "code": "500", "description": "查询失败" } ] }, { "method": "order.queryOrderLogList", "description": "按 order_id 查询订单操作日志,返回全量日志(不分页)。接口按当前登录用户的仓库上下文过滤(method 层从 ctx.user.store_id 获取 warehouse_id),以防跨仓越界。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "order_id / id / orderId", "type": "string|number", "required": true, "source": "body", "description": "订单ID;支持别名 id 与 orderId,接口会兼容解析。" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "日志列表(全量返回,无分页)。每项字段与 stock.warehouse.queryStockLogs 保持一致,典型字段包括 id、action、message、actor、created_at、warehouse_id 等。" } ], "errors": [ { "code": "400", "description": "order_id 为空或格式不合法" }, { "code": "500", "description": "内部错误" } ] }, { "method": "order.updateExpressWeighingWeight", "description": "更新订单运单称重重量。支持两种模式:1) 订单模式(order_id>0):规则:订单仅一个运单时,直接写入该运单重量;多运单时,必须传 waybill_code 并按运单写入;团购波次批量设置同一重量到波次下所有订单运单,并返回拆单汇总信息(total_weight/split_count/splits/store_name/sys_logistics_name)。2) 运单号模式(order_id=0):从运单号反查订单与波次,散单/非团购波次仅更新单个运单重量,团购波次按 wave_no+business_key 批量设置并返回拆单汇总信息。;散单称重前置打包校验:开启仓库配置 single_weigh_require_pack 后,散单路径(订单模式与运单号模式的散单/非团购波次)写入重量前校验订单波次范围与打包状态,wave_scope 非 1(大团购)/3(小团购)且 pack_status 非 fin 时拒绝称重(400);团购波次批量称重不校验;配置缺失/读取异常按关闭处理", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "order_id", "type": "number|string", "required": true, "source": "body", "description": "订单ID,必填且必须为数字。订单模式下为正整数,设为0时切换为运单号模式(需配合 waybill_code 使用)。" }, { "name": "waybill_code", "type": "string", "required": false, "source": "body", "description": "运单号。订单模式下:订单仅一个运单时可不传且会被忽略,多运单时必填并需匹配订单下运单。运单号模式(order_id=0)下必填。" }, { "name": "weighing_weight", "type": "number|string", "required": true, "source": "body", "description": "称重重量(g),必填,必须大于 0,必须为正整数。" } ], "response": [ { "name": "order_id", "type": "number", "required": false, "description": "订单ID。订单模式及运单号散单模式返回。" }, { "name": "waybill_code", "type": "string", "required": false, "description": "写入重量的运单号。订单模式及运单号散单模式返回。" }, { "name": "weighing_weight", "type": "number", "required": true, "description": "已写入的称重重量(g)。" }, { "name": "wave_no", "type": "string", "required": false, "description": "波次号。团购批量模式返回。" }, { "name": "business_key", "type": "string", "required": false, "description": "业务键。运单号团购批量模式返回。" }, { "name": "wave_id", "type": "number", "required": false, "description": "波次ID。团购批量模式返回。" }, { "name": "total_weight", "type": "number", "required": false, "description": "所有拆单重量累加(g)。团购批量模式返回。" }, { "name": "split_count", "type": "number", "required": false, "description": "waybill_code 非空的 business_key 数量。团购批量模式返回。" }, { "name": "splits", "type": "array", "required": false, "description": "按 business_key 分组的拆单明细。每项含 business_key(业务键)、weighing_weight(该拆单累加重量)、waybill_code(代表运单号)。团购批量模式返回。" }, { "name": "store_name", "type": "string", "required": false, "description": "货主名称(订单 shop_nick)。团购批量模式返回。" }, { "name": "sys_logistics_name", "type": "string", "required": false, "description": "系统快递名称。团购批量模式返回。" } ], "errors": [ { "code": 400, "message": "order_id 必填且必须为数字(订单模式下为正整数;设为 0 时为运单号模式)" }, { "code": 400, "message": "weighing_weight 必填" }, { "code": 400, "message": "weighing_weight 格式非法,必须为正整数(单位 g)" }, { "code": 400, "message": "weighing_weight 必须大于 0" }, { "code": 400, "message": "多运单订单必须传入 waybill_code" }, { "code": 400, "message": "订单未打包(pack_status=padding 打包中时返回「订单打包中」)——开启仓库配置 single_weigh_require_pack 后,散单/非团购波次(wave_scope 非 1 大团购/3 小团购)订单 pack_status 未达 fin 时拒绝称重" }, { "code": 404, "message": "未找到有效的订单运单记录" }, { "code": 404, "message": "waybill_code 未匹配到该订单下的运单记录" }, { "code": 404, "message": "运单号不存在(运单号模式)" }, { "code": 404, "message": "运单号对应的订单不存在(运单号模式)" }, { "code": 404, "message": "波次下未找到订单(团购批量模式)" }, { "code": 500, "message": "运单模型未初始化" }, { "code": 500, "message": "订单模型未初始化" }, { "code": 500, "message": "波次模型未初始化" }, { "code": 500, "message": "更新称重重量失败" }, { "code": 500, "message": "批量更新称重重量失败,波次下无有效运单记录(团购批量模式)" } ] }, { "method": "order.bindExpressPackageMaterial", "description": "按订单ID+运单号匹配 wms_order_express,按包材编码匹配包材,并将 package_material_id 与 package_material_name_snapshot 绑定到订单运单记录。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "order_id", "type": "number|string", "required": true, "source": "body", "description": "订单ID,必填。" }, { "name": "waybill_code", "type": "string", "required": true, "source": "body", "description": "运单号,必填。" }, { "name": "package_material_code", "type": "string", "required": true, "source": "body", "description": "包材编码,必填。" } ], "response": [ { "name": "order_id", "type": "number", "required": true, "description": "订单ID(成功时返回于 data 对象中)。" }, { "name": "waybill_code", "type": "string", "required": true, "description": "运单号(成功时返回于 data 对象中)。" }, { "name": "package_material_id", "type": "number", "required": true, "description": "绑定后的包材ID(成功时返回于 data 对象中)。" }, { "name": "package_material_name_snapshot", "type": "string", "required": true, "description": "绑定时写入的包材名称快照(成功时返回于 data 对象中)。" }, { "name": "package_material_code", "type": "string", "required": true, "description": "绑定成功的包材编码(成功时返回于 data 对象中)。" } ], "errors": [ { "code": 400, "message": "参数错误" }, { "code": 404, "message": "包材编码不存在" }, { "code": 404, "message": "订单运单记录不存在" }, { "code": 500, "message": "绑定包材失败" } ] }, { "method": "order.export", "description": "提交订单导出任务(异步)。入参支持 table_type/tableType、module/module_name、export_mode/exportMode;where 与 sort 语义与 order.list 一致。提交后立即返回 task_id,后台异步执行,导出进度/下载请通过 order.exportTaskProgress 查询。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "table_type / tableType", "type": "string", "required": false, "source": "body", "description": "导出表类型,枚举:current/history/dispatch/outsourced;兼容订单模块别名(order/reviewOrder/pendingOrder 等);支持 table_type 与 tableType 两种写法" }, { "name": "module / module_name", "type": "string", "required": false, "source": "body", "description": "订单模块名,兼容 module(驼峰)与 module_name(下划线)两种写法" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "查询条件,语义与 order.list 的 where 一致(推荐使用 { operator, value, type } 标准结构);禁止传入 warehouse_id/warehouseId" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数,语义与 order.list 的 sort 一致" }, { "name": "export_mode / exportMode", "type": "string", "required": false, "source": "body", "description": "导出模式:waybill(默认,按运单展开,items_detail 列汇总商品)或 item(按商品明细展开,每商品一行);支持 export_mode 与 exportMode 两种写法" }, { "name": "export_columns / exportColumns", "type": "array", "required": false, "source": "body", "description": "导出表头字段白名单(中文表头字符串数组,如 [\"系统订单号\",\"外部订单号\"]);不传或空数组时输出全部列。枚举(共 52 个,校验不区分导出模式):系统订单号、外部订单号、平台单号、订单ID、订单号、外部单号、订单状态、抓取波次号、波次号、波次序号、货主、平台、来源、店铺昵称、收件人、收件人电话、省、市、区、镇、详细地址、商品明细、仓库商品名称、商品条码、商品图片、数量、物流公司、运单号、业务类型、运单接口、包材ID、包材编码、包材名称、分配时间、订单商品总类数、订单商品总数、商品重量、称重重量(g)、订单金额、实收金额、创建时间、支付时间、发货时间、出库状态、复核状态、复核完成状态、配货状态、打包状态、备注、买家留言、卖家留言、归档时间。其中仅 waybill 模式输出:系统订单号、外部订单号、平台单号、抓取波次号、商品明细;仅 item 模式输出:订单ID、订单号、外部单号、波次号、仓库商品名称、商品条码、商品图片、数量;其余为两种模式通用(选了当前模式不存在的表头时该列自动忽略)。来源列(字段 create_channel,中文取值:手工单/接口/奇门/出库转单)位于平台列之后,waybill/item 两种模式均输出。传入非法表头会报错(错误信息列出非法值);支持 export_columns 与 exportColumns 两种写法" } ], "response": [ { "name": "task_id", "type": "string", "description": "任务 ID(后端生成)", "required": true }, { "name": "status", "type": "string", "description": "任务状态,枚举:submitted/running/success/failed/not_found", "required": true }, { "name": "progress", "type": "number", "description": "当前进度百分比(0-100)", "required": true }, { "name": "current_count", "type": "number", "description": "当前已处理记录数", "required": true }, { "name": "total_count", "type": "number", "description": "总记录数(若有)", "required": true }, { "name": "message", "type": "string", "description": "任务提示信息", "required": true }, { "name": "result", "type": "object", "description": "任务执行结果(可选,可能包含文件 url/fileKey 等)", "required": true }, { "name": "error", "type": "string", "description": "失败时的错误信息(可选)", "required": true }, { "name": "update_time", "type": "string", "description": "任务更新时间(Unix ms 或 ISO 字符串)", "required": true } ], "errors": [ { "code": 400, "message": "参数格式不正确或 where 条件非法" }, { "code": 500, "message": "导出任务提交失败" } ] }, { "method": "order.exportTaskProgress", "description": "按 task_id 查询订单导出任务进度,返回 task_id、status、progress、current_count、total_count、message、error、download_url、update_time;上传完成后 download_url 返回下载链接;未找到时 status=not_found。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id / taskId", "type": "string", "required": true, "source": "body|query", "description": "任务 ID,兼容 taskId" } ], "response": [ { "name": "task_id", "type": "string", "description": "任务 ID", "required": true }, { "name": "status", "type": "string", "description": "任务状态:submitted/running/success/failed/not_found", "required": true }, { "name": "progress", "type": "number", "description": "进度百分比(0-100)", "required": true }, { "name": "current_count", "type": "number", "description": "当前已处理记录数", "required": true }, { "name": "total_count", "type": "number", "description": "总记录数", "required": true }, { "name": "message", "type": "string", "description": "额外提示信息", "required": true }, { "name": "error", "type": "string", "description": "失败信息(可选)", "required": true }, { "name": "download_url", "type": "string", "description": "任务完成后下载链接(若有)", "required": true }, { "name": "update_time", "type": "string", "description": "最近一次状态更新时间(Unix ms 或 ISO 字符串)", "required": true } ], "errors": [ { "code": 400, "message": "task_id 参数不能为空" }, { "code": 500, "message": "查询失败或内部错误" } ] } ] }, { "groupName": "订单待审核模块", "module": "order.reviewOrder", "list": [ { "method": "order.reviewOrder.list", "description": "待审核订单列表,默认仅查询 step=0 的订单。;列表运单号回填强制同仓校验:wms_order_express 按「订单ID + 订单所属仓库ID」隔离读取,禁止仅凭订单ID跨仓串读运单号", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page / pageSize" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "统一 where 条件对象;禁止传入 warehouse_id / warehouseId。create_channel(订单来源渠道筛选,按订单表 create_channel 列过滤;枚举:MANUAL=手工单、API=接口、QM=奇门、STOCKOUT=出库转单)。支持简写与标准结构:{\"create_channel\":\"MANUAL\"} 单值精确、{\"create_channel\":[\"QM\",\"API\"]} 裸数组按 in 多选、{\"create_channel\":{\"operator\":\"in\",\"value\":[\"QM\",\"API\"]}} 标准结构多选、{\"create_channel\":{\"operator\":\"ne\",\"value\":\"MANUAL\"}} 排除指定渠道。注意:列表响应中的 create_channel 已格式化为中文标签(手工单/接口/奇门/出库转单),查询条件请传英文枚举值。" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数,支持 sortField / sortOrder" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "订单列表(raw 行数据,字段字典见 docs/order-workbench-list-api.md 中的“订单列表 raw 字段字典”章节),本次新增 store_remark(货主备注)字段;wave_index(波次内序号,联查 wms_order_wave_index,无记录时为 0)。" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息" }, { "name": "recheck_status", "type": "string", "required": false, "description": "复核状态:none=未复核,fin=已复核" } ], "errors": [ { "code": "400", "message": "参数格式错误或缺少仓库上下文" }, { "code": "500", "message": "查询失败" } ] }, { "method": "order.reviewOrder.detail", "description": "查询单个订单详情,返回订单头、商品明细和运单信息", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids / id / order_id / orderId", "type": "array|string|number", "required": true, "source": "body", "description": "订单ID;支持 ids 数组、逗号分隔字符串或单个 id/order_id,至少提供一项" }, { "name": "tableType / tablePosition / type / moduleName", "type": "string", "required": false, "source": "body", "description": "可选,指定订单表类型,支持 current/history/dispatch/outsourced/order/revieworder/pendingorder 等" } ], "response": [ { "name": "order", "type": "object", "description": "订单头对象(raw 行数据)" }, { "name": "detail", "type": "object", "description": "等同于 order" }, { "name": "orderItems / items", "type": "array", "description": "商品明细数组" }, { "name": "expresses", "type": "array", "description": "运单信息数组" }, { "name": "waybill_codes", "type": "array", "description": "去重后的运单号字符串数组" } ], "errors": [ { "code": "400", "description": "订单ID 为空或格式错误" }, { "code": "404", "description": "订单不存在或不属于当前仓库" }, { "code": "500", "description": "内部错误" } ] }, { "method": "order.reviewOrder.reviewOrder", "description": "批量审核通过订单并进入待处理。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "array", "required": true, "source": "body", "description": "订单 ID 数组;仅允许 ids 字段,建议传数组,也兼容逗号字符串或单值" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "首条更新记录 ID" }, { "name": "inspection_status", "type": "string", "required": true, "description": "新的审核状态" }, { "name": "step", "type": "number", "required": true, "description": "新的流程步骤" }, { "name": "updated_at", "type": "string", "required": true, "description": "更新时间" }, { "name": "updated_count", "type": "number", "required": true, "description": "受影响行数" }, { "name": "ids", "type": "array", "required": true, "description": "实际更新的订单 ID 列表" } ], "errors": [ { "code": "400", "description": "ids 不能为空或格式错误" }, { "code": "404", "description": "订单不存在或不属于当前仓库" } ] }, { "method": "reviewOrder.detail", "description": "查询单个订单详情,返回订单头、商品明细和运单信息", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids / id / order_id / orderId", "type": "array|string|number", "required": true, "source": "body", "description": "订单ID;支持 ids 数组、逗号分隔字符串或单个 id/order_id,至少提供一项" }, { "name": "tableType / tablePosition / type / moduleName", "type": "string", "required": false, "source": "body", "description": "可选,指定订单表类型,支持 current/history/dispatch/outsourced/order/revieworder/pendingorder 等" } ], "response": [ { "name": "order", "type": "object", "required": true, "description": "订单头对象(raw 行数据)" }, { "name": "detail", "type": "object", "required": true, "description": "等同于 order" }, { "name": "orderItems / items", "type": "array", "required": true, "description": "商品明细数组" }, { "name": "expresses", "type": "array", "required": true, "description": "运单信息数组" }, { "name": "waybill_codes", "type": "array", "required": true, "description": "去重后的运单号字符串数组" } ], "errors": [ { "code": "400", "message": "订单ID 为空或格式错误" }, { "code": "404", "message": "订单不存在或不属于当前仓库" }, { "code": "500", "message": "内部错误" } ] } ] }, { "groupName": "待处理订单", "module": "order.pendingOrder", "list": [ { "method": "order.pendingOrder.list", "description": "待处理订单列表,默认筛选 outbound_status != padding 且 step in [1,2,3]。;列表运单号回填强制同仓校验:wms_order_express 按「订单ID + 订单所属仓库ID」隔离读取,禁止仅凭订单ID跨仓串读运单号", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page / pageSize" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "统一 where 条件对象;禁止传入 warehouse_id / warehouseId。where 无字段白名单,可直接传订单表列名。lock_status 锁定状态筛选(筛选值用数据库原始枚举 none/warehouse/store,不是响应中的 Y/N;ne 表示不等于;条件值为空自动忽略):未锁定 {\"lock_status\":\"none\"};已锁定(所有非 none){\"lock_status\":{\"operator\":\"ne\",\"value\":\"none\"}}。create_channel(订单来源渠道筛选,按订单表 create_channel 列过滤;枚举:MANUAL=手工单、API=接口、QM=奇门、STOCKOUT=出库转单)。支持简写与标准结构:{\"create_channel\":\"MANUAL\"} 单值精确、{\"create_channel\":[\"QM\",\"API\"]} 裸数组按 in 多选、{\"create_channel\":{\"operator\":\"in\",\"value\":[\"QM\",\"API\"]}} 标准结构多选、{\"create_channel\":{\"operator\":\"ne\",\"value\":\"MANUAL\"}} 排除指定渠道。注意:列表响应中的 create_channel 已格式化为中文标签(手工单/接口/奇门/出库转单),查询条件请传英文枚举值。confirm_print_status(确认打印状态筛选,按订单表列过滤;枚举:none=未确认打印、fin=已确认打印)。支持简写与标准结构(同 create_channel 示例),如 {\"confirm_print_status\":\"fin\"} 只查已确认打印订单。claim_status(领料状态筛选,按订单表列过滤;枚举:none=未领料、padding=领料中、fin=已领料、error=异常)。支持简写与标准结构(同 create_channel 示例),如 {\"claim_status\":{\"operator\":\"ne\",\"value\":\"fin\"}} 查未完成领料的订单。" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数,支持 sortField / sortOrder" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "订单列表(raw 行数据,字段字典见 docs/order-workbench-list-api.md 中的“订单列表 raw 字段字典”章节),本次新增 store_remark(货主备注)字段;raw 行数据包含 confirm_print_status(确认打印状态,none/fin)与 claim_status(领料状态,none/padding/fin/error)字段;wave_index(波次内序号,联查 wms_order_wave_index,无记录时为 0)。lock_status 字段统一输出为 Y/N:none(含空值)→ 'N',其余值(如 warehouse/store)→ 'Y'。" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息" }, { "name": "recheck_status", "type": "string", "required": false, "description": "复核状态:none=未复核,fin=已复核" } ], "errors": [ { "code": "400", "message": "参数格式错误或缺少仓库上下文" }, { "code": "500", "message": "查询失败" } ] }, { "method": "order.pendingOrder.detail", "description": "查询单个订单详情,返回订单头、商品明细和运单信息;忽略传入的表位参数,固定先查配送表(dispatch),查不到再兜底查询待处理表(current);运单信息强制同仓校验:wms_order_express 按「订单ID + 订单所属仓库ID」隔离读取,禁止仅凭订单ID跨仓串读运单号", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids / id / order_id / orderId", "type": "array|string|number", "required": true, "source": "body", "description": "订单ID;支持 ids 数组、逗号分隔字符串或单个 id/order_id,至少提供一项" }, { "name": "tableType / tablePosition / type / moduleName", "type": "string", "required": false, "source": "body", "description": "已忽略:本接口固定先查配送表(dispatch),查不到再兜底待处理表(current),传入该参数不生效" } ], "response": [ { "name": "detail", "type": "object", "description": "订单头对象(raw 行数据,来自配送表或兜底的待处理表)", "required": true }, { "name": "orderItems / items", "type": "array", "description": "商品明细数组(以库存标准格式为主,附 plan_qty / order_line_no / stock_id / order_item_id / order_id 及拣货库位 picking_locations)", "required": true }, { "name": "expresses", "type": "array", "description": "运单信息数组", "required": true }, { "name": "storage_items", "type": "array", "description": "按库位平铺的储位分配明细(附商品编码、名称、规格、单位等库存信息)", "required": true } ], "errors": [ { "code": "400", "message": "订单ID 为空或格式错误" }, { "code": "404", "message": "订单不存在或不属于当前仓库" }, { "code": "500", "message": "内部错误" } ] }, { "method": "order.pendingOrder.reverseReviewOrder", "description": "将待处理订单反审回待审核状态。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "array", "required": false, "source": "body", "description": "订单 ID 列表;兼容 ids / id / order_id,建议传 ids" }, { "name": "id", "type": "number", "required": false, "source": "body", "description": "兼容单个订单 ID" }, { "name": "order_id", "type": "number", "required": false, "source": "body", "description": "兼容单个订单 ID" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "首条更新记录 ID" }, { "name": "inspection_status", "type": "string", "required": true, "description": "新的审核状态" }, { "name": "step", "type": "number", "required": true, "description": "新的流程步骤" }, { "name": "updated_at", "type": "string", "required": true, "description": "更新时间" }, { "name": "updated_count", "type": "number", "required": true, "description": "受影响行数" }, { "name": "ids", "type": "array", "required": true, "description": "实际更新的订单 ID 列表" } ], "errors": [ { "code": "400", "description": "订单ID 不能为空或格式错误" }, { "code": "404", "description": "订单不存在或不属于当前仓库" } ] }, { "method": "order.pendingOrder.markPendingOutboundOrder", "description": "将待处理订单批量标记为待出库。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "array", "required": true, "source": "body", "description": "订单 ID 正整数数组;不支持 id、order_id 或逗号字符串" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "首条更新记录 ID" }, { "name": "outbound_status", "type": "string", "required": true, "description": "新的出库状态" }, { "name": "updated_at", "type": "string", "required": true, "description": "更新时间" }, { "name": "updated_count", "type": "number", "required": true, "description": "受影响行数" }, { "name": "ids", "type": "array", "required": true, "description": "实际更新的订单 ID 列表" } ], "errors": [ { "code": "400", "description": "ids 必须为正整数数组" }, { "code": "404", "description": "订单不存在或不属于当前仓库" } ] }, { "method": "order.pendingOrder.cancelOrder", "description": "将待处理订单批量取消,仅允许当前状态可取消的订单。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "array", "required": true, "source": "body", "description": "订单 ID 正整数数组;不支持 id、order_id 或逗号字符串" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "首条更新记录 ID" }, { "name": "status", "type": "string", "required": true, "description": "新的订单状态" }, { "name": "step", "type": "number", "required": true, "description": "新的流程步骤" }, { "name": "updated_at", "type": "string", "required": true, "description": "更新时间" }, { "name": "updated_count", "type": "number", "required": true, "description": "受影响行数" }, { "name": "ids", "type": "array", "required": true, "description": "实际更新的订单 ID 列表" } ], "errors": [ { "code": "400", "description": "ids 必填或当前状态不允许取消" }, { "code": "404", "description": "订单不存在或不属于当前仓库" } ] }, { "method": "order.pendingOrder.allocateExpressCode", "description": "批量分配待处理订单的首单快递号(异步接口)。调用后立即返回 task_id,后台异步执行运单创建;可通过 order.pendingOrder.allocateExpressCodeTaskProgress 查询进度。拆单场景请使用 order.pendingOrder.allocateSubOrderNumber。已锁定订单(lock_status 非 none)与拦截订单同样在流水线中被跳过、不参与分配,任务结果(allocateExpressCodeTaskProgress)中包含 skipped_locked_order_ids 等跳过明细。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "array", "required": true, "source": "body", "description": "订单 ID 数组,例如 [123456, 789012]。sys_platform_code、logistics_code 等字段由后端直接从数据库读取,前端无需传参。" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "全局调用结果标识,成功时为 success" }, { "name": "code", "type": "number", "required": true, "description": "业务状态码,200 表示成功" }, { "name": "message", "type": "string", "required": false, "description": "返回信息" }, { "name": "data", "type": "object", "required": false, "description": "异步受理结果。包含 task_id(任务 ID,用于查询进度)、status(submitted)、message、update_time 等字段。实际运单分配结果需通过 allocateExpressCodeTaskProgress 接口查询。" } ], "errors": [ { "code": "400", "message": "入参格式错误或必填字段缺失" }, { "code": "500", "message": "运单创建链路或第三方快递接口调用失败" } ] }, { "method": "order.pendingOrder.allocateStorage", "description": "按订单批量分配储位(迁移自 order.storageAllocation.allocateStorage)。这是一个异步提交接口:调用后接口立即返回受理信息(包含 request_id),后端异步执行实际的储位分配与锁定操作;仓库上下文由当前登录用户提供(ctx.user.store_id)。接口不会在同步响应中返回分配明细(如 requested_order_ids、allocated_order_ids 等),客户端可通过请求 ID 或事件/查询链路获取最终结果。已锁定订单(lock_status 非 none)会在分配流水线中被跳过(底层分配结果 skipped_orders 中记录 skipped_reason='locked')。默认仅从库位类型允许分配且启用的储位中分配;传入 allow_storage_location=true 时直接分配储位,无视库位类型的 allow_allocation/is_active 限制。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "allow_storage_location / allowStorageLocation / is_allow_storage / isAllowStorage", "type": "boolean", "required": false, "source": "body", "description": "是否允许使用存储储位,支持多种字段别名。为 true 时直接分配储位,无视库位类型的 allow_allocation/is_active 限制;缺省时仅校验可分配储位。" }, { "name": "order_ids / orderIds / ids / order_id / orderId / id", "type": "array|string|number", "required": true, "source": "body", "description": "订单 ID 列表,支持数组、逗号分隔字符串或单个 ID(兼容多种别名)。" } ], "response": [ { "name": "request_id", "type": "string", "required": true, "description": "请求 ID(后端生成的唯一标识),用于查询任务状态或结果" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "生效的仓库 ID(来自当前用户 store_id)" }, { "name": "message", "type": "string", "required": true, "description": "受理提示信息,通常为 '请求已受理,后端异步处理中' 或错误说明" } ], "errors": [ { "code": 400, "message": "缺少仓库上下文(用户登录上下文无 store_id)" }, { "code": 400, "message": "订单ID 不能为空(请求中未包含有效 order_ids)" }, { "code": 409, "message": "存在并发锁定或数据库约束导致的冲突(场景少见,视底层实现抛出)" }, { "code": 500, "message": "内部错误:模型不可用或数据库/锁定操作失败" } ] }, { "method": "order.pendingOrder.allocateStorageProgress", "description": "按 request_id 查询储位分配异步任务状态/结果(由 allocateStorage 提交)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "request_id / requestId", "type": "string", "required": true, "source": "body|query", "description": "任务请求 ID,兼容字段 requestId" } ], "response": [ { "name": "request_id", "type": "string", "required": true, "description": "请求 ID(后端生成的唯一标识)" }, { "name": "status", "type": "string", "required": true, "description": "任务状态枚举:submitted(已受理)/ running(进行中)/ success(成功)/ failed(失败)/ not_found(未找到)" }, { "name": "result", "type": "object", "required": false, "description": "成功时返回底层分配结果,结构视实现而定" }, { "name": "error", "type": "string", "required": false, "description": "失败时返回的错误信息" }, { "name": "warehouse_id", "type": "number", "required": false, "description": "关联仓库 ID(若任务关联仓库时返回)" }, { "name": "update_time", "type": "string", "required": false, "description": "最近一次状态更新时间,ISO8601 字符串" }, { "name": "message", "type": "string", "required": false, "description": "额外提示信息" } ], "errors": [ { "code": 400, "message": "request_id 为空或格式不合法" }, { "code": 500, "message": "内部错误" } ] }, { "method": "order.pendingOrder.syncOrderIds", "description": "同步待处理订单(异步模式)。提交后立即返回 request_id,后台异步执行同步流程。调用方需通过 syncOrderIdsProgress 接口轮询任务进度与最终结果。后台会按 create_channel 分组并行派发同步任务(QM/MANUAL/API);单订单失败写入错误状态(sync_status='error')并标记待处理异常,不影响整批结果;已同步完成(sync_status='fin')的订单会被自动跳过防重复。SN管理订单和快递未分配订单在同步前即被标记为 error 并跳过派发。API 渠道订单逐单先回传 deliveryorder.confirm,回调成功后才扣减库存并更新 sync_status='fin'(回调失败/异常置 error、不扣减库存,可重新派发);QM/MANUAL 渠道派发成功后更新 sync_status='fin',防止重复同步。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "order_ids / orderIds / ids / order_id / orderId / id", "type": "array|string|number", "required": true, "source": "body", "description": "订单 ID 列表,支持数组、逗号分隔字符串或单个 ID。服务端会校验订单状态并执行批量同步拦截规则(含 SN 订单限制)。" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "全局调用结果标识,成功为 success" }, { "name": "code", "type": "number", "required": true, "description": "业务状态码,200 表示已受理" }, { "name": "message", "type": "string", "required": true, "description": "受理提示信息" }, { "name": "request_id", "type": "string", "required": true, "description": "异步任务唯一标识,用于 syncOrderIdsProgress 查询进度" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "生效的仓库 ID" } ], "errors": [ { "code": 400, "message": "order_ids 不能为空或格式错误" } ] }, { "method": "order.pendingOrder.syncOrderIdsProgress", "description": "查询 syncOrderIds 异步任务的进度与结果。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "request_id / requestId", "type": "string", "required": true, "source": "body", "description": "syncOrderIds 返回的 request_id" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "全局调用结果标识,成功为 success" }, { "name": "code", "type": "number", "required": true, "description": "业务状态码,200 表示成功" }, { "name": "message", "type": "string", "required": true, "description": "返回信息" }, { "name": "request_id", "type": "string", "required": true, "description": "请求 ID(原样回传)" }, { "name": "status", "type": "string", "required": true, "description": "任务状态:submitted(已受理)/ running(处理中)/ success(完成)/ failed(失败)/ not_found(未找到)" }, { "name": "progress", "type": "number", "required": true, "description": "进度百分比(0-100)" }, { "name": "total_count", "type": "number", "required": false, "description": "总订单数" }, { "name": "processed_count", "type": "number", "required": false, "description": "已处理订单数" }, { "name": "warehouse_id", "type": "number", "required": false, "description": "仓库 ID" }, { "name": "result", "type": "object", "required": false, "description": "完成时的同步结果(success 状态时存在),含 success_count / failed_count / dispatch_results 等" }, { "name": "error", "type": "string", "required": false, "description": "失败时的错误信息(failed 状态时存在)" }, { "name": "update_time", "type": "number", "required": false, "description": "最后更新时间戳" } ], "errors": [ { "code": 400, "message": "request_id 参数不能为空" } ] }, { "method": "order.pendingOrder.cancelAllocateStorage", "description": "待处理模块的取消分配储位入口,直接对接 system service 的 cancelAllocateStorage。仅接受订单ID(order_ids)作为入参,不接受 allow_storage_location 或 warehouse_id/warehouseId;仓库上下文来自当前登录用户的 store_id。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "order_ids / orderIds / ids / order_id / orderId / id", "type": "array|string|number", "required": true, "source": "body", "description": "订单 ID 列表;支持数组、逗号字符串或单个 ID(兼容多种别名)。" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "全局调用结果标识,成功为 success" }, { "name": "code", "type": "number", "required": true, "description": "业务状态码,200 表示成功" }, { "name": "message", "type": "string", "required": true, "description": "返回信息,成功或部分成功时给出摘要" }, { "name": "data", "type": "object", "required": false, "description": "取消分配汇总结果,包含下列字段", "children": [ { "name": "warehouse_id", "type": "number", "required": true, "description": "生效的仓库 ID(来自当前用户 store_id)" }, { "name": "requested_order_ids", "type": "array", "required": true, "description": "请求中传入的订单 ID 列表(规范化后)" }, { "name": "cancellable_order_ids", "type": "array", "required": true, "description": "实际可以取消分配的订单 ID 列表" }, { "name": "skipped_orders", "type": "array", "required": true, "description": "被跳过的订单数组,每项至少包含 order_id 与 skipped_reason(如 not_found / not_allocated / no_allocation)" }, { "name": "orders", "type": "array", "required": true, "description": "每个订单的取消分配结果数组,包含成功与跳过记录(合并 skipped_orders 与成功结果)" }, { "name": "picking_count", "type": "number", "required": true, "description": "本次被取消的 picking 行数" }, { "name": "storage_unlock_summary", "type": "array", "required": true, "description": "按 storage_id 汇总的解锁数量数组({storage_id, unlocked_quantity})" }, { "name": "stock_unlock_summary", "type": "array", "required": true, "description": "按 stock_id 汇总的解锁数量数组({stock_id, unlocked_quantity})" } ] } ], "errors": [ { "code": 400, "message": "缺少仓库上下文" }, { "code": 400, "message": "订单ID不能为空" }, { "code": 500, "message": "内部错误:模型不可用或数据库/回滚失败" } ] }, { "method": "order.pendingOrder.updateOrderPlatform", "description": "批量修改待处理订单的平台信息。用 code 查找 wms_platform 表,若平台存在则将订单的 sys_platform_code 和 sys_platform_name 更新为该平台的 code/name;若平台不存在则返回错误。只操作当前仓库的当前订单表,不处理其他订单表。正在分配快递(wms_order_express 存在 status=0 取号中占位记录)的订单跳过处理,不影响其余订单,跳过明细通过 skipped_order_ids 透出。", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "order_ids", "type": "number[]", "required": true, "source": "body", "description": "订单ID 正整数数组,不能为空" }, { "name": "code", "type": "string", "required": true, "source": "body", "description": "平台编码,对应 wms_platform.code" } ], "response": [ { "name": "updated_count", "type": "number", "required": true, "description": "实际更新行数" }, { "name": "skipped_order_ids", "type": "number[]", "required": false, "description": "因正在分配快递(取号中)而跳过的订单 ID 列表" }, { "name": "sys_platform_code", "type": "string", "required": true, "description": "更新后的平台编码" }, { "name": "sys_platform_name", "type": "string", "required": true, "description": "更新后的平台名称" } ], "errors": [ { "code": 400, "message": "order_ids 不能为空" }, { "code": 400, "message": "code 不能为空" }, { "code": 404, "message": "平台不存在:" }, { "code": 400, "message": "缺少仓库上下文" } ] }, { "method": "order.pendingOrder.updateOrderExpress", "description": "批量修改待处理订单的快递信息。用 express_code 从当前仓库快递列表(带缓存)中查找对应项:若为自定义映射(is_system_setting=true),sys_logistics_code/name 写系统快递编码和名称,logistics_code/name 写自定义编码和名称;若为系统快递(is_system_setting=false),四个字段均写系统快递的 code/name;未找到则报错。只操作当前仓库的当前订单表,不处理其他订单表。正在分配快递(wms_order_express 存在 status=0 取号中占位记录)的订单跳过处理,不影响其余订单,跳过明细通过 skipped_order_ids 透出。", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "order_ids", "type": "number[]", "required": true, "source": "body", "description": "订单ID 正整数数组,不能为空" }, { "name": "express_code", "type": "string", "required": true, "source": "body", "description": "快递编码,可为系统编码或仓库自定义编码" } ], "response": [ { "name": "updated_count", "type": "number", "required": true, "description": "实际更新行数" }, { "name": "skipped_order_ids", "type": "number[]", "required": false, "description": "因正在分配快递(取号中)而跳过的订单 ID 列表" }, { "name": "sys_logistics_code", "type": "string", "required": true, "description": "写入的系统快递编码" }, { "name": "sys_logistics_name", "type": "string", "required": true, "description": "写入的系统快递名称" }, { "name": "logistics_code", "type": "string", "required": true, "description": "写入的快递编码(自定义或系统)" }, { "name": "logistics_name", "type": "string", "required": true, "description": "写入的快递名称(自定义或系统)" } ], "errors": [ { "code": 400, "message": "order_ids 不能为空" }, { "code": 400, "message": "order_ids 仅支持正整数数组" }, { "code": 400, "message": "express_code 不能为空" }, { "code": 404, "message": "快递编码 不存在" } ] }, { "method": "order.pendingOrder.cloneOrder", "description": "克隆待处理订单(含已同步 sync_status=fin 订单)。完整流程:1. 查找原订单,校验可取消状态(step 0/1/2/3);2. 若原订单已分配储位(storage_status='fin'),先清除已分配库存,释放失败不阻断克隆(残留占用保留在原订单名下);3. 取消原订单(step→9, status→cancel),记录克隆日志;4. 以原订单业务数据创建新订单,所有流程状态字段重置为初始落库状态,发货单号重新生成为 SYS 前缀新单号(受唯一索引 delivery_order_code+store_id+warehouse_id 约束,不可复制原单号),原单号写入 pre_delivery_order_code 保留克隆追溯链,同步状态继承原订单(原订单已同步 sync_status=fin 则新订单直接置 fin 避免重复回传,否则重置 padding 重新同步);5. 克隆订单明细(含 stock_id),重置 order_id 为新订单 ID;6. 对新订单记录克隆创建日志。克隆新订单不重新占用库存(storage_status=none,不触发储位分配与库存锁定)。", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "order_id", "type": "number", "required": true, "source": "body", "description": "原订单ID,正整数" } ], "response": [ { "name": "source_order_id", "type": "number", "required": true, "description": "原订单ID(已取消)" }, { "name": "new_order_id", "type": "number", "required": true, "description": "新订单ID(克隆生成)" } ], "errors": [ { "code": 400, "message": "order_id 不能为空" }, { "code": 400, "message": "order_id 仅支持正整数" }, { "code": 404, "message": "订单不存在" }, { "code": 400, "message": "订单状态不允许克隆(仅支持 step 0/1/2/3)" } ] }, { "method": "order.pendingOrder.createOrder", "description": "手动创建待处理订单。根据货主策略(need_order_approval)决定初始步骤:need_order_approval=1 进待审核(step=0),need_order_approval=0 直接进待处理(step=1)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "store_id", "type": "number", "required": true, "source": "body", "description": "货主ID(正整数)" }, { "name": "name", "type": "string", "required": true, "source": "body", "description": "收件人姓名" }, { "name": "mobile", "type": "string", "required": false, "source": "body", "description": "收件人手机号,mobile 与 tel 至少填一项" }, { "name": "tel", "type": "string", "required": false, "source": "body", "description": "收件人电话,mobile 与 tel 至少填一项" }, { "name": "detail_address", "type": "string", "required": true, "source": "body", "description": "详细地址" }, { "name": "province", "type": "string", "required": true, "source": "body", "description": "省份(必填,空值返回 400)" }, { "name": "city", "type": "string", "required": true, "source": "body", "description": "城市(必填,空值返回 400)" }, { "name": "area", "type": "string", "required": true, "source": "body", "description": "区/县(必填,空值返回 400)" }, { "name": "town", "type": "string", "required": false, "source": "body", "description": "镇/街道" }, { "name": "zip_code", "type": "string", "required": false, "source": "body", "description": "邮编" }, { "name": "items", "type": "array", "required": true, "source": "body", "description": "订单明细数组,每项含 item_id(商品主键,必填,正整数)和 plan_qty(计划数量,正整数);item_name(优先外部传入,其次从 StockStore 缓存获取,最后兜底'商品')、order_line_no、actual_price 为可选" }, { "name": "delivery_order_code", "type": "string", "required": false, "source": "body", "description": "订单号,不填则自动生成(SYS + 时间戳 + 随机4位)" }, { "name": "logistics_code", "type": "string", "required": false, "source": "body", "description": "快递编码,不填则读货主默认快递策略(policy_config.default_express_code)" }, { "name": "logistics_name", "type": "string", "required": false, "source": "body", "description": "快递名称" }, { "name": "sys_platform_code", "type": "string", "required": false, "source": "body", "description": "系统平台编码,不填则读货主默认平台策略(policy_config.default_platform_code)" }, { "name": "source_platform_code", "type": "string", "required": false, "source": "body", "description": "来源平台编码" }, { "name": "source_order_codes", "type": "string", "required": false, "source": "body", "description": "来源订单号" }, { "name": "shop_nick", "type": "string", "required": false, "source": "body", "description": "店铺名称(自定义),最大长度 200" }, { "name": "order_type", "type": "string", "required": false, "source": "body", "description": "订单类型" }, { "name": "is_urgency", "type": "string", "required": false, "source": "body", "description": "是否紧急:Y/N,默认 N" }, { "name": "invoice_flag", "type": "string", "required": false, "source": "body", "description": "是否需要发票:Y/N,默认 N" } ], "response": [ { "name": "order_id", "type": "number", "required": true, "description": "新创建的订单 ID" }, { "name": "delivery_order_code", "type": "string", "required": true, "description": "订单号(传入值或自动生成值)" }, { "name": "step", "type": "number", "required": true, "description": "初始步骤:0=待审核,1=待处理" }, { "name": "step_label", "type": "string", "required": true, "description": "步骤说明:待审核 / 待处理" }, { "name": "items_count", "type": "number", "required": true, "description": "商品种类数" }, { "name": "items_total", "type": "number", "required": true, "description": "商品总件数" } ], "errors": [ { "code": 400, "message": "必填字段缺失(含 province/city/area)、items 格式错误(item_id 须为正整数)或 delivery_order_code 重复" }, { "code": 404, "message": "货主与仓库无有效合约关系(getContractConfig 返回 null 时降级为需审核)" } ], "notes": [ "使用 item_id 直接匹配商品主键,不依赖外部系统商品同步;item_id 可通过 singleitem.synchronize 返回的 itemId 获取", "手工单 item_id 即仓库 stock_id(wms_stock_warehouse.id),系统会校验该库存记录归属货主与 store_id 一致,跨货主传库存将被拒绝(商品《xxx》库存归属货主与当前货主不一致)", "province/city/area 为必填项,空值返回 400" ] }, { "method": "order.pendingOrder.importOrdersFromExcel", "description": "通过 Excel 文件批量创建订单。接受 base64 编码的 xlsx 内容,按订单号分组,每组创建一个订单(step 由货主策略决定)。每行代表一条商品明细;同一订单号的多行组成一个完整订单,头信息取每组第一行。(已作废)", "status": "deprecated", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "file_base64", "type": "string", "required": true, "source": "body", "description": "base64 编码的 .xlsx 文件内容" } ], "response": [ { "name": "total", "type": "number", "required": true, "description": "解析到的订单总数" }, { "name": "success_count", "type": "number", "required": true, "description": "创建成功的订单数" }, { "name": "fail_count", "type": "number", "required": true, "description": "创建失败的订单数" }, { "name": "success_orders", "type": "array", "required": true, "description": "成功订单列表,每项含 delivery_order_code、order_id、step、step_label" }, { "name": "fail_orders", "type": "array", "required": true, "description": "失败订单列表,每项含 delivery_order_code、error(失败原因)" } ], "errors": [ { "code": "400", "message": "file_base64 为空、Excel 格式无效或无有效数据行" } ] }, { "method": "order.pendingOrder.parseAddress", "description": "智能地址解析:使用内置省市区地址字典遍历方式将非结构化地址字符串解析为省/市/区/详细地址/手机号(不调用 AI)。支持单条解析与数组批量解析:address 传字符串时返回单条结果,addresses(或 address)传字符串数组时批量解析,响应 data.list 按输入顺序返回每条地址的解析结果(失败条目 flag=failure 不影响其他条目)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "address", "type": "string", "required": true, "source": "body", "description": "原始地址字符串(必填),如\"张三 13800138000 广东省广州市天河区体育西路100号\"。也支持传字符串数组批量解析(与 addresses 二选一)" }, { "name": "addresses", "type": "string[]", "required": false, "source": "body", "description": "批量地址字符串数组,单次最多 50 条,按数组顺序返回解析结果" } ], "requestBody": [], "response": [ { "name": "code", "type": "number", "required": true, "description": "1=成功,0=失败" }, { "name": "message", "type": "string", "required": true, "description": "提示消息" }, { "name": "data", "type": "object", "required": false, "description": "解析成功时返回 province/city/area/detailAddress/name/mobile" }, { "name": "data.province", "type": "string", "required": false, "description": "省份,如 广东省" }, { "name": "data.city", "type": "string", "required": false, "description": "城市,如 广州市" }, { "name": "data.area", "type": "string", "required": false, "description": "区/县,如 天河区" }, { "name": "data.town", "type": "string", "required": false, "description": "乡镇/街道,如 员村街道" }, { "name": "data.detailAddress", "type": "string", "required": false, "description": "详细地址,如 体育西路100号" }, { "name": "data.name", "type": "string", "required": false, "description": "收件人姓名,如 张三" }, { "name": "data.mobile", "type": "string", "required": false, "description": "收件人手机号,如 13800138000" }, { "name": "data.list", "type": "array", "required": false, "description": "批量解析时返回的结果数组,按输入顺序排列;每条含 address/flag/message/province/city/area/town/detailAddress/name/mobile,失败条目 flag=failure 且解析字段为空字符串" }, { "name": "data.list[].address", "type": "string", "required": false, "description": "原始地址字符串(原样返回)" }, { "name": "data.list[].flag", "type": "string", "required": false, "description": "该条解析状态:success=成功,failure=失败" }, { "name": "data.list[].message", "type": "string", "required": false, "description": "该条解析提示:成功为 ok,失败为具体错误原因" }, { "name": "data.list[].province", "type": "string", "required": false, "description": "省份,如 广东省" }, { "name": "data.list[].city", "type": "string", "required": false, "description": "城市,如 广州市" }, { "name": "data.list[].area", "type": "string", "required": false, "description": "区/县,如 天河区" }, { "name": "data.list[].town", "type": "string", "required": false, "description": "乡镇/街道,如 员村街道" }, { "name": "data.list[].detailAddress", "type": "string", "required": false, "description": "详细地址,如 体育西路100号" }, { "name": "data.list[].name", "type": "string", "required": false, "description": "收件人姓名,如 张三" }, { "name": "data.list[].mobile", "type": "string", "required": false, "description": "收件人手机号,如 13800138000" } ], "errors": [ { "code": 400, "message": "地址字符串不能为空" }, { "code": 400, "message": "地址数组不能为空" }, { "code": 400, "message": "单次批量解析最多支持 50 条地址" }, { "code": 500, "message": "地址解析失败(AI服务异常或密钥未配置)" } ], "notes": [ "方法部署位置:systemMethods/order/pendingOrder/parseAddress", "使用本地省市区地址字典遍历识别(原 DeepSeek AI 方式已弃用)", "解析结果可直接回填到 createOrder 的收件人信息字段", "未识别到的字段返回空字符串", "批量解析:addresses 或 address 传字符串数组,按输入顺序逐条遍历识别并聚合返回,单条失败不影响其他条目" ] }, { "method": "order.pendingOrder.parseAddressLocal", "description": "本地地址解析接口:不调用 AI,接口内置省市区地址字典数据,对地址字符串遍历匹配识别省/市/区(含直辖市、省直辖县级市、不设区地级市、地级市代管县级市)。与 parseAddress 使用同一套本地字典遍历解析逻辑,两者解析结果等价。支持单条与批量:address 传字符串时返回单条结果,addresses(或 address)传字符串数组时批量解析返回 data.list;address 与 addresses 均不传时,使用接口内置的示例地址数据遍历识别并返回 data.list(data.source=sample)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "address", "type": "string", "required": false, "source": "body", "description": "原始地址字符串(选填),如\"张三 13800138000 广东省广州市天河区体育西路100号\"。也支持传字符串数组批量解析(与 addresses 二选一);两者均不传时使用内置示例地址数据" }, { "name": "addresses", "type": "string[]", "required": false, "source": "body", "description": "批量地址字符串数组,单次最多 50 条,按数组顺序返回解析结果;不传 address 与 addresses 时返回内置示例地址数据的遍历识别结果" } ], "requestBody": [], "response": [ { "name": "code", "type": "number", "required": true, "description": "1=成功,0=失败" }, { "name": "message", "type": "string", "required": true, "description": "提示消息" }, { "name": "data", "type": "object", "required": false, "description": "解析成功时返回 province/city/area/town/detailAddress/mobile" }, { "name": "data.province", "type": "string", "required": false, "description": "省份,如 广东省" }, { "name": "data.city", "type": "string", "required": false, "description": "城市,如 广州市" }, { "name": "data.area", "type": "string", "required": false, "description": "区/县,如 天河区" }, { "name": "data.town", "type": "string", "required": false, "description": "乡镇/街道,如 员村街道" }, { "name": "data.detailAddress", "type": "string", "required": false, "description": "详细地址,如 体育西路100号" }, { "name": "data.mobile", "type": "string", "required": false, "description": "收件人手机号,如 13800138000" }, { "name": "data.list", "type": "array", "required": false, "description": "批量解析或内置示例数据遍历识别时返回的结果数组,按输入顺序排列;每条含 address/flag/message/province/city/area/town/detailAddress/name/mobile,失败条目 flag=failure 且解析字段为空字符串" }, { "name": "data.list[].address", "type": "string", "required": false, "description": "原始地址字符串(原样返回)" }, { "name": "data.list[].flag", "type": "string", "required": false, "description": "该条解析状态:success=成功,failure=失败" }, { "name": "data.list[].message", "type": "string", "required": false, "description": "该条解析提示:成功为 ok,失败为具体错误原因" }, { "name": "data.list[].province", "type": "string", "required": false, "description": "省份,如 广东省" }, { "name": "data.list[].city", "type": "string", "required": false, "description": "城市,如 广州市" }, { "name": "data.list[].area", "type": "string", "required": false, "description": "区/县,如 天河区" }, { "name": "data.list[].town", "type": "string", "required": false, "description": "乡镇/街道,如 员村街道" }, { "name": "data.list[].detailAddress", "type": "string", "required": false, "description": "详细地址,如 体育西路100号" }, { "name": "data.list[].name", "type": "string", "required": false, "description": "收件人姓名(本地遍历不识别,固定返回空字符串)" }, { "name": "data.list[].mobile", "type": "string", "required": false, "description": "收件人手机号,如 13800138000" }, { "name": "data.source", "type": "string", "required": false, "description": "未传 address/addresses 时为 sample,表示结果来自内置示例地址数据" } ], "errors": [ { "code": 400, "message": "地址字符串不能为空" }, { "code": 400, "message": "地址数组不能为空" }, { "code": 400, "message": "单次批量解析最多支持 50 条地址" }, { "code": 500, "message": "地址解析失败(省市区均无法识别)" } ], "notes": [ "方法部署位置:systemMethods/order/pendingOrder/parseAddressLocal", "不调用 AI 接口,本地遍历内置省市区地址字典(LOCAL_CITY_DICT,约 340 个地级市/自治州/地区/盟)识别省市区", "辅助识别:CHINA_ADMIN_DIVISION_MAP(省直辖县级市/不设区地级市/代管县级市)、PROVINCE_LIST(省份全称与简称)", "与 parseAddress 使用同一套本地字典遍历解析逻辑,两者解析结果等价", "本地遍历不识别收件人姓名,name 固定返回空字符串" ] }, { "method": "order.pendingOrder.updateAddress", "description": "批量修改待处理订单的收件地址信息。地址字段修改仅允许 post_status='none'(未分配快递)的订单;至少需要提供一个地址字段(name/mobile/tel/zip_code/province/city/area/town/detail_address),空值和纯空白会被忽略。更新成功后写入操作日志。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "number[]", "required": true, "source": "body", "description": "订单ID 正整数数组,不能为空" }, { "name": "name", "type": "string", "required": false, "source": "body", "description": "收件人姓名" }, { "name": "mobile", "type": "string", "required": false, "source": "body", "description": "收件人手机号" }, { "name": "tel", "type": "string", "required": false, "source": "body", "description": "收件人电话" }, { "name": "zip_code", "type": "string", "required": false, "source": "body", "description": "邮编" }, { "name": "province", "type": "string", "required": false, "source": "body", "description": "省份" }, { "name": "city", "type": "string", "required": false, "source": "body", "description": "城市" }, { "name": "area", "type": "string", "required": false, "source": "body", "description": "区/县" }, { "name": "town", "type": "string", "required": false, "source": "body", "description": "镇/街道" }, { "name": "detail_address", "type": "string", "required": false, "source": "body", "description": "详细地址" } ], "response": [ { "name": "updated_count", "type": "number", "required": true, "description": "实际更新的订单行数(地址更新行数)。仅统计 post_status='none' 的订单地址更新成功数。" }, { "name": "ids", "type": "number[]", "required": true, "description": "请求的订单ID数组(原样返回)" } ], "errors": [ { "code": 400, "message": "ids 不能为空" }, { "code": 400, "message": "至少需要提供一个地址字段进行修改" }, { "code": 400, "message": "仅允许修改 post_status='none'(未分配快递)的订单;若订单已分配快递则地址更新行数为 0,不会报错但实际无更新。" } ] }, { "method": "order.pendingOrder.updateRemark", "description": "批量修改待处理订单的备注(remark)。不受 post_status 限制,可对所有状态的订单生效。更新成功后写入操作日志。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "number[]", "required": true, "source": "body", "description": "订单ID 正整数数组,不能为空" }, { "name": "remark", "type": "string", "required": true, "source": "body", "description": "订单备注/留言,最大500字符,必填" } ], "response": [ { "name": "updated_count", "type": "number", "required": true, "description": "实际更新的订单行数" }, { "name": "ids", "type": "number[]", "required": true, "description": "请求的订单ID数组(原样返回)" } ], "errors": [ { "code": 400, "message": "ids 不能为空" }, { "code": 400, "message": "ids 仅支持正整数数组" }, { "code": 400, "message": "remark 不能为空" } ] }, { "method": "order.pendingOrder.batchIntercept", "description": "批量提交订单拦截请求(异步任务模式)。接收订单ID数组,提交后立即返回 task_id 和受理信息,后端异步将每个订单的 intercept_status 更新为 'requested' 并写入操作日志(ORDER_INTERCEPT_REQUEST)。拦截时间 intercept_time 仅在订单首次发起拦截时写入(当时刻),重复发起不覆盖已有值;取消/解除拦截(order.pendingOrder.batchUnintercept)会清空该字段,故其恒为「最近一次发起拦截的通知时刻」,库内确定拦截时刻改用配送表 dispath_time。相同 task_id 幂等提交会返回已存在任务的信息。仓库ID统一使用当前上下文(ctx.user.store_id)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "order_ids / orderIds / ids", "type": "number[]", "required": true, "source": "body", "description": "订单ID数组;优先级 order_ids > orderIds > ids" }, { "name": "task_id / taskId", "type": "string", "required": false, "source": "body", "description": "外部指定任务ID(用于幂等提交,不传则自动生成)" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务ID,格式 recheck_intercept_{warehouseId}_{timestamp}_{rand}(幂等提交时返回已有任务的 task_id)" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "仓库ID(取自当前上下文)" }, { "name": "message", "type": "string", "required": true, "description": "任务提交状态说明:'批量拦截任务已提交。' 或 '批量拦截任务已存在,请勿重复提交。'" }, { "name": "accepted_at", "type": "string", "required": true, "description": "任务受理时间(ISO 字符串)" }, { "name": "status", "type": "string", "required": false, "description": "提交状态(固定为 'success')" }, { "name": "state", "type": "string", "required": false, "description": "幂等提交时返回已有任务的状态:submitted / running / success / failed" } ], "errors": [ { "code": 400, "message": "未识别到当前仓库上下文" }, { "code": 400, "message": "order_ids 参数不能为空或格式错误" } ] }, { "method": "order.pendingOrder.batchInterceptTaskProgress", "description": "查询批量拦截任务进度。根据 task_id 返回任务的当前状态、进度百分比、已处理/已拦截订单数等信息。任务状态 state 包含 submitted(已提交)、running(执行中)、success(已完成)、failed(失败)、not_found(未找到)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id / taskId", "type": "string", "required": true, "source": "body|query", "description": "任务ID" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务ID" }, { "name": "state", "type": "string", "required": true, "description": "任务状态:submitted / running / success / failed / not_found" }, { "name": "warehouse_id", "type": "number", "required": false, "description": "仓库ID(not_found 时不返回)" }, { "name": "submitted_at", "type": "number|null", "required": false, "description": "任务提交时间戳(毫秒)" }, { "name": "start_time", "type": "number|null", "required": false, "description": "任务开始执行时间戳(毫秒,running/success/failed 时返回)" }, { "name": "end_time", "type": "number|null", "required": false, "description": "任务结束时间戳(毫秒,success/failed 时返回)" }, { "name": "progress_percent", "type": "number", "required": false, "description": "进度百分比 0-100(submitted/running/success/failed 时返回)" }, { "name": "total_order_count", "type": "number", "required": false, "description": "总订单数(submitted/running/success/failed 时返回)" }, { "name": "processed_order_count", "type": "number", "required": false, "description": "已处理订单数(仅 submitted/running 时返回)" }, { "name": "intercepted_order_count", "type": "number", "required": false, "description": "已拦截订单数(submitted/running/success/failed 时返回)" }, { "name": "intercepted_order_ids", "type": "number[]", "required": false, "description": "已拦截订单ID列表(仅 success 时返回)" }, { "name": "duration_ms", "type": "number", "required": false, "description": "任务耗时(毫秒,success/failed 时返回)" }, { "name": "error_message", "type": "string", "required": false, "description": "错误信息(仅 failed 时返回)" }, { "name": "error_code", "type": "string", "required": false, "description": "错误码(仅 failed 时返回,默认 'BATCH_INTERCEPT_FAILED')" } ], "errors": [ { "code": 400, "message": "task_id 参数不能为空" } ] }, { "method": "order.pendingOrder.batchLock", "description": "批量提交订单锁定请求(异步任务模式)。接收订单ID数组,提交后立即返回 task_id 和受理信息,后端异步将每个订单的 lock_status 更新为 'warehouse' 并写入操作日志(ORDER_LOCK)。相同 task_id 幂等提交会返回已存在任务的信息。仓库ID统一使用当前上下文(ctx.user.store_id)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "order_ids / orderIds / ids", "type": "number[]", "required": true, "source": "body", "description": "订单ID数组;优先级 order_ids > orderIds > ids" }, { "name": "task_id / taskId", "type": "string", "required": false, "source": "body", "description": "外部指定任务ID(用于幂等提交,不传则自动生成)" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务ID,格式 order_lock_{warehouseId}_{timestamp}_{rand}(幂等提交时返回已有任务的 task_id)" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "仓库ID(取自当前上下文)" }, { "name": "message", "type": "string", "required": true, "description": "任务提交状态说明:'批量锁定任务已提交。' 或 '批量锁定任务已存在,请勿重复提交。'" }, { "name": "accepted_at", "type": "string", "required": true, "description": "任务受理时间(ISO 字符串)" }, { "name": "status", "type": "string", "required": false, "description": "提交状态(固定为 'success')" }, { "name": "state", "type": "string", "required": false, "description": "幂等提交时返回已有任务的状态:submitted / running / success / failed" } ], "errors": [ { "code": 400, "message": "未识别到当前仓库上下文" }, { "code": 400, "message": "order_ids 参数不能为空或格式错误" } ] }, { "method": "order.pendingOrder.batchLockTaskProgress", "description": "查询批量锁定任务进度。根据 task_id 返回任务的当前状态、进度百分比、已处理/已锁定订单数等信息。任务状态 state 包含 submitted(已提交)、running(执行中)、success(已完成)、failed(失败)、not_found(未找到)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id / taskId", "type": "string", "required": true, "source": "body|query", "description": "任务ID" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务ID" }, { "name": "state", "type": "string", "required": true, "description": "任务状态:submitted / running / success / failed / not_found" }, { "name": "warehouse_id", "type": "number", "required": false, "description": "仓库ID(not_found 时不返回)" }, { "name": "submitted_at", "type": "number|null", "required": false, "description": "任务提交时间戳(毫秒)" }, { "name": "start_time", "type": "number|null", "required": false, "description": "任务开始执行时间戳(毫秒,running/success/failed 时返回)" }, { "name": "end_time", "type": "number|null", "required": false, "description": "任务结束时间戳(毫秒,success/failed 时返回)" }, { "name": "progress_percent", "type": "number", "required": false, "description": "进度百分比 0-100(submitted/running/success/failed 时返回)" }, { "name": "total_order_count", "type": "number", "required": false, "description": "总订单数(submitted/running/success/failed 时返回)" }, { "name": "processed_order_count", "type": "number", "required": false, "description": "已处理订单数(仅 submitted/running 时返回)" }, { "name": "locked_order_count", "type": "number", "required": false, "description": "已锁定订单数(submitted/running/success/failed 时返回)" }, { "name": "locked_order_ids", "type": "number[]", "required": false, "description": "已锁定订单ID列表(仅 success 时返回)" }, { "name": "duration_ms", "type": "number", "required": false, "description": "任务耗时(毫秒,success/failed 时返回)" }, { "name": "error_message", "type": "string", "required": false, "description": "错误信息(仅 failed 时返回)" }, { "name": "error_code", "type": "string", "required": false, "description": "错误码(仅 failed 时返回,默认 'BATCH_LOCK_FAILED')" } ], "errors": [ { "code": 400, "message": "task_id 参数不能为空" } ] }, { "method": "order.pendingOrder.batchUnlock", "description": "批量提交订单解锁请求(异步任务模式)。接收订单ID数组,提交后立即返回 task_id 和受理信息,后端异步将每个订单的 lock_status 更新为 'none' 并写入操作日志(ORDER_UNLOCK)。相同 task_id 幂等提交会返回已存在任务的信息。仓库ID统一使用当前上下文(ctx.user.store_id)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "order_ids / orderIds / ids", "type": "number[]", "required": true, "source": "body", "description": "订单ID数组;优先级 order_ids > orderIds > ids" }, { "name": "task_id / taskId", "type": "string", "required": false, "source": "body", "description": "外部指定任务ID(用于幂等提交,不传则自动生成)" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务ID,格式 order_unlock_{warehouseId}_{timestamp}_{rand}(幂等提交时返回已有任务的 task_id)" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "仓库ID(取自当前上下文)" }, { "name": "message", "type": "string", "required": true, "description": "任务提交状态说明:'批量解锁任务已提交。' 或 '批量解锁任务已存在,请勿重复提交。'" }, { "name": "accepted_at", "type": "string", "required": true, "description": "任务受理时间(ISO 字符串)" }, { "name": "status", "type": "string", "required": false, "description": "提交状态(固定为 'success')" }, { "name": "state", "type": "string", "required": false, "description": "幂等提交时返回已有任务的状态:submitted / running / success / failed" } ], "errors": [ { "code": 400, "message": "未识别到当前仓库上下文" }, { "code": 400, "message": "order_ids 参数不能为空或格式错误" } ] }, { "method": "order.pendingOrder.batchUnlockTaskProgress", "description": "查询批量解锁任务进度。根据 task_id 返回任务的当前状态、进度百分比、已处理/已解锁订单数等信息。任务状态 state 包含 submitted(已提交)、running(执行中)、success(已完成)、failed(失败)、not_found(未找到)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id / taskId", "type": "string", "required": true, "source": "body|query", "description": "任务ID" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务ID" }, { "name": "state", "type": "string", "required": true, "description": "任务状态:submitted / running / success / failed / not_found" }, { "name": "warehouse_id", "type": "number", "required": false, "description": "仓库ID(not_found 时不返回)" }, { "name": "submitted_at", "type": "number|null", "required": false, "description": "任务提交时间戳(毫秒)" }, { "name": "start_time", "type": "number|null", "required": false, "description": "任务开始执行时间戳(毫秒,running/success/failed 时返回)" }, { "name": "end_time", "type": "number|null", "required": false, "description": "任务结束时间戳(毫秒,success/failed 时返回)" }, { "name": "progress_percent", "type": "number", "required": false, "description": "进度百分比 0-100(submitted/running/success/failed 时返回)" }, { "name": "total_order_count", "type": "number", "required": false, "description": "总订单数(submitted/running/success/failed 时返回)" }, { "name": "processed_order_count", "type": "number", "required": false, "description": "已处理订单数(仅 submitted/running 时返回)" }, { "name": "unlocked_order_count", "type": "number", "required": false, "description": "已解锁订单数(submitted/running/success/failed 时返回)" }, { "name": "unlocked_order_ids", "type": "number[]", "required": false, "description": "已解锁订单ID列表(仅 success 时返回)" }, { "name": "duration_ms", "type": "number", "required": false, "description": "任务耗时(毫秒,success/failed 时返回)" }, { "name": "error_message", "type": "string", "required": false, "description": "错误信息(仅 failed 时返回)" }, { "name": "error_code", "type": "string", "required": false, "description": "错误码(仅 failed 时返回,默认 'BATCH_UNLOCK_FAILED')" } ], "errors": [ { "code": 400, "message": "task_id 参数不能为空" } ] }, { "method": "order.pendingOrder.batchUnintercept", "description": "批量提交解除拦截请求(异步任务模式)。接收订单ID数组,提交后立即返回 task_id 和受理信息,后端异步将每个订单的 intercept_status 更新为 'none' 并写入操作日志(ORDER_INTERCEPT_CANCEL)。解除拦截同时将拦截时间 intercept_time 清空(置为 null,避免残留旧的发起拦截时刻)。不操作库存拦截锁定数量字段。相同 task_id 幂等提交会返回已存在任务的信息。仓库ID统一使用当前上下文(ctx.user.store_id)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "order_ids / orderIds / ids", "type": "number[]", "required": true, "source": "body", "description": "订单ID数组;优先级 order_ids > orderIds > ids" }, { "name": "task_id / taskId", "type": "string", "required": false, "source": "body", "description": "外部指定任务ID(用于幂等提交,不传则自动生成)" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务ID,格式 order_unintercept_{warehouseId}_{timestamp}_{rand}(幂等提交时返回已有任务的 task_id)" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "仓库ID(取自当前上下文)" }, { "name": "message", "type": "string", "required": true, "description": "任务提交状态说明:'批量解除拦截任务已提交。' 或 '批量解除拦截任务已存在,请勿重复提交。'" }, { "name": "accepted_at", "type": "string", "required": true, "description": "任务受理时间(ISO 字符串)" }, { "name": "status", "type": "string", "required": false, "description": "提交状态(固定为 'success')" }, { "name": "state", "type": "string", "required": false, "description": "幂等提交时返回已有任务的状态:submitted / running / success / failed" } ], "errors": [ { "code": 400, "message": "未识别到当前仓库上下文" }, { "code": 400, "message": "order_ids 参数不能为空或格式错误" } ] }, { "method": "order.pendingOrder.batchUninterceptTaskProgress", "description": "查询批量解除拦截任务进度。根据 task_id 返回任务的当前状态、进度百分比、已处理/已解除拦截订单数等信息。任务状态 state 包含 submitted(已提交)、running(执行中)、success(已完成)、failed(失败)、not_found(未找到)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id / taskId", "type": "string", "required": true, "source": "body|query", "description": "任务ID" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务ID" }, { "name": "state", "type": "string", "required": true, "description": "任务状态:submitted / running / success / failed / not_found" }, { "name": "warehouse_id", "type": "number", "required": false, "description": "仓库ID(not_found 时不返回)" }, { "name": "submitted_at", "type": "number|null", "required": false, "description": "任务提交时间戳(毫秒)" }, { "name": "start_time", "type": "number|null", "required": false, "description": "任务开始执行时间戳(毫秒,running/success/failed 时返回)" }, { "name": "end_time", "type": "number|null", "required": false, "description": "任务结束时间戳(毫秒,success/failed 时返回)" }, { "name": "progress_percent", "type": "number", "required": false, "description": "进度百分比 0-100(submitted/running/success/failed 时返回)" }, { "name": "total_order_count", "type": "number", "required": false, "description": "总订单数(submitted/running/success/failed 时返回)" }, { "name": "processed_order_count", "type": "number", "required": false, "description": "已处理订单数(仅 submitted/running 时返回)" }, { "name": "unintercepted_order_count", "type": "number", "required": false, "description": "已解除拦截订单数(submitted/running/success/failed 时返回)" }, { "name": "unintercepted_order_ids", "type": "number[]", "required": false, "description": "已解除拦截订单ID列表(仅 success 时返回)" }, { "name": "duration_ms", "type": "number", "required": false, "description": "任务耗时(毫秒,success/failed 时返回)" }, { "name": "error_message", "type": "string", "required": false, "description": "错误信息(仅 failed 时返回)" }, { "name": "error_code", "type": "string", "required": false, "description": "错误码(仅 failed 时返回,默认 'BATCH_UNINTERCEPT_FAILED')" } ], "errors": [ { "code": 400, "message": "task_id 参数不能为空" } ] } ] }, { "groupName": "订单复核模块", "module": "order.recheckOrder", "list": [ { "method": "order.recheckOrder.scanOrder", "description": "扫描关键词并返回以波次为单位的复核视图。支持运单号、波次号、车号三种匹配模式。运单号/波次号命中(散单)返回扁平化订单列表 list_type='single',车号命中(团单)返回嵌套波次结构 list_type='group'。运单号命中但订单无波次信息时,退回单订单详情模式(list 每项含 detail/items/expresses/logs)。所有模式的 list[] 每项均附带 items_weight(订单商品总重量)与 suggested_package_material(推荐包材信息,无推荐时为 null)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "keyword / value / waybill_no / waybillCode / waybill_code / wave_no / waveNo / cart_code / cartCode", "type": "string", "required": true, "source": "body|query", "description": "扫描关键词;匹配优先级:运单号 → 波次号 → 车号。支持别名 waybillCode/waybill_code(运单号)、waveNo(波次号)、cartCode(车号)" } ], "response": [ { "name": "match_type", "type": "string", "required": true, "description": "命中类型:waybill(运单号命中)/ wave(波次号命中)/ cart(车号命中)" }, { "name": "list_type", "type": "string", "required": true, "description": "列表模式:single(散单扁平列表)/ group(团购嵌套波次列表)" }, { "name": "waybill_no", "type": "string", "required": false, "description": "仅 waybill 命中时返回,匹配到的运单号" }, { "name": "task_id", "type": "number|null", "required": false, "description": "散单有波次信息时返回(来自拣货任务表 wms_wave_pick_task.id),团单车号命中时返回 cartMatchContext 中的任务 ID" }, { "name": "picker_id", "type": "number|null", "required": false, "description": "仅散单模式(有波次信息时)返回,拣货人ID(来自 wms_wave_pick_task.pick_user_id)" }, { "name": "picker_name", "type": "string", "required": false, "description": "仅散单模式(有波次信息时)返回,拣货人名称(来自 wms_wave_pick_task.pick_user_name)" }, { "name": "wave_id", "type": "number", "required": false, "description": "仅散单模式(有波次信息时)返回,波次ID" }, { "name": "wave_no", "type": "string", "required": false, "description": "仅散单模式(有波次信息时)返回,波次号" }, { "name": "wave_type", "type": "number", "required": false, "description": "仅散单模式(有波次信息时)返回,波次类型编码(来自 wms_wave_batch.wave_type)" }, { "name": "pick_mode", "type": "number", "required": false, "description": "拣货模式:1-团购小波次 2-散单单品单件 3-散单先拣后分 4-边拣边分 5-团购大波次。散单模式在顶层返回,团购模式在每个波次视图项内返回" }, { "name": "strategy_id", "type": "number|null", "required": false, "description": "仅散单模式返回,波次策略ID" }, { "name": "strategy_name", "type": "string", "required": false, "description": "仅散单模式返回,波次策略名称" }, { "name": "total_orders", "type": "number", "required": false, "description": "仅散单模式返回,波次内订单总数" }, { "name": "reviewed_count", "type": "number", "required": false, "description": "仅散单模式返回,已复核订单数" }, { "name": "unreviewed_count", "type": "number", "required": false, "description": "仅散单模式返回,未复核订单数" }, { "name": "list", "type": "array", "required": true, "description": "统一列表输出。散单模式(list_type=single)有波次信息时:扁平订单数组;无波次信息时退回单订单详情模式(每项含 detail、items、expresses、logs)。团购模式(list_type=group):波次视图数组(每项含 wave_id、wave_no、wave_type、wave_status、total_orders、processed_orders、creator、create_time、update_time、order_count、pick_mode、box_no、order_ids、orders_detail、stocks[])。所有模式的 list[] 每项均附带 items_weight(订单商品总重量,单位 g)与 suggested_package_material(推荐包材信息,无推荐时为 null)。", "children": [ { "name": "order_id", "type": "number", "description": "[散单有波次] 订单ID" }, { "name": "delivery_order_code", "type": "string", "description": "[散单有波次] 发货单号(优先 delivery_order_code,其次 pre_delivery_order_code)" }, { "name": "waybill_no", "type": "string", "description": "[散单有波次] 运单号(从 order_express 关联表查询)" }, { "name": "pick_status", "type": "string", "description": "[散单有波次] 拣货状态" }, { "name": "is_printed", "type": "boolean", "description": "[散单有波次] 是否已打印(print_status === 'fin')" }, { "name": "is_reviewed", "type": "boolean", "description": "[散单有波次] 是否已复核(recheck_status === 'fin')" }, { "name": "shop_nick", "type": "string", "description": "[散单有波次] 店铺昵称" }, { "name": "items_count", "type": "number", "description": "[散单有波次] 商品种类数" }, { "name": "wave_index", "type": "number", "description": "[散单有波次] 波次内序号(优先从 wms_order_wave_index 读取真实 wave_index,若无则降级为数组临时序号)" }, { "name": "recheck_status", "type": "string", "description": "[散单有波次] 复核状态" }, { "name": "wave_id", "type": "number", "description": "[散单有波次] 波次ID" }, { "name": "wave_no", "type": "string", "description": "[散单有波次] 波次号" }, { "name": "order_type", "type": "string", "description": "[散单有波次] 订单类型" }, { "name": "status", "type": "number", "description": "[散单有波次] 订单状态码" }, { "name": "logistics_name", "type": "string", "description": "[散单有波次] 物流名称" }, { "name": "store_remark", "type": "string", "description": "[散单有波次] 货主备注(来自 wms_store_warehouse.store_remask)" }, { "name": "intercept_status", "type": "string", "description": "[散单有波次] 拦截状态(requested / requesting / intercepting / intercepted_in_transit / intercepted_at_warehouse / 历史值 intercepted / 空字符串)。已拦截订单保留在 list 中按单提示,不阻断整个扫描视图,且不计入 reviewed_count / unreviewed_count / printed_count / unprinted_count 统计" }, { "name": "stock", "type": "array", "description": "[散单有波次] 订单商品库存明细", "children": [ { "name": "stock_id", "type": "number", "description": "库存商品ID" }, { "name": "item_code", "type": "string", "description": "商品编码" }, { "name": "item_name", "type": "string", "description": "商品名称" }, { "name": "sku_property", "type": "string", "description": "SKU属性(来自 wms_stock_warehouse.sku_property)" }, { "name": "packing_requirements", "type": "string", "description": "包装要求(来自 wms_stock_warehouse.packing_requirements)" }, { "name": "barcodes", "type": "array", "description": "条码列表(来自 wms_stock_barcodes,若无则回退为 [item_code])" }, { "name": "images", "type": "array", "description": "商品图片URL列表(来自 file_reference 关联查询)" }, { "name": "plan_qty", "type": "number", "description": "计划数量" }, { "name": "has_shared_barcode", "type": "boolean", "description": "是否存在共享条码(同一条码出现在多个不同 stock_id 中)" } ] }, { "name": "detail", "type": "object", "description": "[散单无波次回退] 订单详情对象(来自 order.detail 方法返回)" }, { "name": "items", "type": "array", "description": "[散单无波次回退] 订单商品明细数组" }, { "name": "expresses", "type": "array", "description": "[散单无波次回退] 订单快递信息数组" }, { "name": "logs", "type": "array", "description": "[散单无波次回退] 订单操作日志数组" }, { "name": "wave_id", "type": "number", "description": "[团购波次项] 波次ID" }, { "name": "wave_no", "type": "string", "description": "[团购波次项] 波次号" }, { "name": "wave_type", "type": "number", "description": "[团购波次项] 波次类型编码" }, { "name": "wave_status", "type": "number", "description": "[团购波次项] 波次状态码" }, { "name": "total_orders", "type": "number", "description": "[团购波次项] 波次内订单总数(来自 wms_wave_batch)" }, { "name": "processed_orders", "type": "number", "description": "[团购波次项] 已处理订单数(来自 wms_wave_batch)" }, { "name": "creator", "type": "string", "description": "[团购波次项] 波次创建人" }, { "name": "create_time", "type": "string", "description": "[团购波次项] 波次创建时间" }, { "name": "update_time", "type": "string", "description": "[团购波次项] 波次更新时间" }, { "name": "order_count", "type": "number", "description": "[团购波次项] 波次下实际订单数(COUNT 查询)" }, { "name": "pick_mode", "type": "number", "description": "[团购波次项] 拣货模式(以拣货任务级别为准)" }, { "name": "box_no", "type": "number", "description": "[团购波次项] 箱号(来自 wms_wave_pick_task_wave.box_no)" }, { "name": "order_ids", "type": "array", "description": "[团购波次项] 非拦截订单 ID 数组,仅 list_type='group' 时返回" }, { "name": "orders_detail", "type": "array", "description": "[团购波次项] 非拦截订单详细列表,每项含 order_id、delivery_order_code、waybill_no、pick_status、is_printed、is_reviewed、recheck_status、shop_nick、items_count、wave_index、intercept_status,仅 list_type='group' 时返回", "children": [ { "name": "order_id", "type": "number", "description": "订单ID" }, { "name": "delivery_order_code", "type": "string", "description": "发货单号" }, { "name": "waybill_no", "type": "string", "description": "运单号" }, { "name": "pick_status", "type": "string", "description": "拣货状态" }, { "name": "is_printed", "type": "boolean", "description": "是否已打印(print_status === 'fin')" }, { "name": "is_reviewed", "type": "boolean", "description": "是否已复核(recheck_status === 'fin')" }, { "name": "recheck_status", "type": "string", "description": "复核状态" }, { "name": "shop_nick", "type": "string", "description": "店铺昵称" }, { "name": "items_count", "type": "number", "description": "商品种类数" }, { "name": "wave_index", "type": "number", "description": "波次内序号" }, { "name": "intercept_status", "type": "string", "description": "拦截状态(requested / intercepted_at_warehouse / 空字符串)" } ] }, { "name": "orders", "type": "array", "description": "[团购波次项] 波次下订单列表(结构与散单有波次模式订单项一致,含 order_id/delivery_order_code/waybill_no/pick_status/is_printed/is_reviewed/shop_nick/items_count/wave_index/recheck_status/order_type/status/logistics_name/store_remark/intercept_status/stock[])", "children": [ { "name": "order_id", "type": "number", "description": "订单ID" }, { "name": "delivery_order_code", "type": "string", "description": "发货单号" }, { "name": "waybill_no", "type": "string", "description": "运单号" }, { "name": "pick_status", "type": "string", "description": "拣货状态" }, { "name": "is_printed", "type": "boolean", "description": "是否已打印" }, { "name": "is_reviewed", "type": "boolean", "description": "是否已复核" }, { "name": "shop_nick", "type": "string", "description": "店铺昵称" }, { "name": "items_count", "type": "number", "description": "商品种类数" }, { "name": "wave_index", "type": "number", "description": "波次内序号" }, { "name": "recheck_status", "type": "string", "description": "复核状态" }, { "name": "order_type", "type": "string", "description": "订单类型" }, { "name": "status", "type": "number", "description": "订单状态码" }, { "name": "logistics_name", "type": "string", "description": "物流名称" }, { "name": "store_remark", "type": "string", "description": "货主备注" }, { "name": "intercept_status", "type": "string", "description": "拦截状态" }, { "name": "stock", "type": "array", "description": "商品库存明细(结构同散单模式)" } ] }, { "name": "intercepted", "type": "array", "description": "[团购波次项] 拦截订单列表,仅当波次内存在已进入拦截流程的订单时返回(intercept_status 为 requested / requesting / intercepting / intercepted_in_transit / intercepted_at_warehouse,以及历史遗留值 intercepted)。每项含 wave_index(波次内序号)、order_id、delivery_order_code、waybill_no、intercept_status", "children": [ { "name": "wave_index", "type": "number", "description": "波次内序号(优先从 wms_order_wave_index 读取真实 wave_index,若无则降级为数组临时序号)" }, { "name": "order_id", "type": "number", "description": "订单ID" }, { "name": "delivery_order_code", "type": "string", "description": "发货单号" }, { "name": "waybill_no", "type": "string", "description": "运单号" }, { "name": "intercept_status", "type": "string", "description": "拦截状态(requested / requesting / intercepting / intercepted_in_transit / intercepted_at_warehouse / intercepted)" } ] }, { "name": "items_weight", "type": "number|null", "description": "[全模式] 订单商品总重量(g),来源于 wms_order_delivery.items_weight。散单模式每个订单对象包含,团购模式每个波次对象包含(取波次内首个正常订单的重量)" }, { "name": "suggested_package_material", "type": "object|null", "description": "[全模式] 推荐包材信息。根据订单商品结构(items_hash + items_crc)匹配 wms_package_material_item_relation 历史绑定记录,按 bind_count 降序取最优匹配。若 items_hash 为空或无匹配记录则为 null。散单模式每个订单对象包含,团购模式每个波次对象包含;团购模式以波次内首个正常订单的商品指纹匹配包材推荐", "children": [ { "name": "id", "type": "number", "description": "包材ID(wms_package_material.id)" }, { "name": "code", "type": "string", "description": "包材编码" }, { "name": "name", "type": "string", "description": "包材名称" }, { "name": "spec", "type": "string", "description": "包材规格" }, { "name": "type", "type": "string", "description": "包材类型" }, { "name": "weight", "type": "number", "description": "包材自身重量(g)" }, { "name": "length", "type": "number", "description": "长(cm)" }, { "name": "width", "type": "number", "description": "宽(cm)" }, { "name": "height", "type": "number", "description": "高(cm)" }, { "name": "bind_count", "type": "number", "description": "历史绑定次数(推荐排序依据)" } ] } ] } ], "errors": [ { "code": 400, "message": "扫描关键词不能为空" }, { "code": 404, "message": "未找到对应订单" }, { "code": 400, "message": "订单未拣货,不允许复核。" } ] }, { "method": "order.recheckOrder.confirmRecheck", "description": "按订单 ID 确认复核并记录复核任务到 wms_recheck_task(入参兼容 id/orderId)。确认复核后,若该订单所属波次拣货任务下所有订单均已复核完成,则自动解绑车任务:清空 wms_wave_pick_task 的车绑定信息(current_cart_id、current_cart_code_snapshot)、停用 wms_pick_task_cart_binding 绑定记录(is_active=0 并记录解绑人和时间)并释放 wms_pick_cart(清空 current_task_id、bind_user_id)。解绑失败仅记录 warn 日志,不影响复核主流程。复核状态更新后,会先自动清理波次内「已拦截且未打印」的订单(wave_id 清零回池、删除波次索引与任务订单关联、回写波次统计、写 ORDER_WAVE_REMOVE 日志并触发波次策略快扫),避免拦截订单卡住波次完成判定;已打印的拦截订单保持不动。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "order_id / id / orderId", "type": "string|number", "required": true, "source": "body|query", "description": "订单 ID;优先使用 order_id,兼容别名 id 与 orderId" } ], "response": [ { "name": "order_id", "type": "number", "required": true, "description": "订单 ID" }, { "name": "waybill_no", "type": "string", "required": true, "description": "运单号" }, { "name": "recheck_status", "type": "string", "required": true, "description": "复核结果状态(固定为 'fin')" }, { "name": "recheck_time", "type": "string", "required": true, "description": "复核时间(ISO 字符串)" }, { "name": "review_no", "type": "string", "required": true, "description": "复核任务编号" } ], "errors": [ { "code": 400, "message": "订单ID不能为空" }, { "code": 404, "message": "未找到对应订单" }, { "code": 400, "message": "订单未拣货,不允许复核。" } ] }, { "method": "order.recheckOrder.confirmIntercept", "description": "确认拦截:通过订单 ID 列表批量匹配订单,将拦截状态更新为 intercepted_at_warehouse(仓库已拦截,step=4、outbound_status=fin),同步标记运单退回与拦截(is_back='Y', is_intercept='Y'),并释放储位分配(cancelAllocateStorage 拦截模式 interceptMode=true:库存不归还可用,移入拦截锁定字段 intercept_locked_quantity)与订单锁(lock_status=none)。仅拦截当前指定订单,不波及波次内其他订单。前置条件:订单必须处于拦截发起中状态(requested/requesting/intercepting,历史值 intercepted 兼容),未发起拦截(none/空)的订单直接静默跳过不参与处理,已确认拦截(intercepted_at_warehouse)及其它非可确认状态(intercepted_in_transit/returning/returned/delivered_by_mistake/timeout/cancelled/failed/exception)一律跳过并记录失败原因;更新 SQL 的 where 同时限定拦截状态白名单,防止并发修改导致误更新。支持部分失败:未找到的订单与处理失败的订单记录在 failed 列表并返回失败原因,其余订单继续处理。全部订单处理完后按成功订单 ID 汇总批量创建售后工单 + 通知快递群。每个订单操作成功后写入操作日志(ORDER_INTERCEPT_CONFIRM)。运单标记、储位释放、锁释放、工单创建、日志写入失败均不影响主流程。库内拦截确认**不写** intercept_time(该字段恒为「最近一次发起拦截的通知时刻」,确认时不覆盖),库内确定拦截时刻以配送表 dispath_time(订单迁移进配送表的时间)为准。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "array|string", "required": true, "source": "body", "description": "订单 ID 列表,支持数组或以逗号分隔的字符串。兼容 id / order_id / orderId 单值写法" } ], "response": [ { "name": "success", "type": "array", "required": true, "description": "拦截成功的订单列表", "children": [ { "name": "order_id", "type": "number", "description": "订单 ID" }, { "name": "order_no", "type": "string", "description": "订单号(优先 delivery_order_code,其次 pre_delivery_order_code)" }, { "name": "intercept_status", "type": "string", "description": "拦截状态(固定为 'intercepted_at_warehouse')" }, { "name": "updated_at", "type": "string", "description": "更新时间(ISO 字符串)" } ] }, { "name": "failed", "type": "array", "required": true, "description": "拦截失败的订单列表", "children": [ { "name": "order_id", "type": "number", "description": "订单 ID" }, { "name": "delivery_order_code", "type": "string", "description": "发货单号(订单存在时返回)" }, { "name": "reason", "type": "string", "description": "失败原因(未找到对应订单 / 订单已确认拦截 / 订单拦截状态不允许确认拦截: xxx / 确认拦截失败: xxx);拦截状态为 none 的订单静默跳过,不进入 failed" } ] }, { "name": "success_count", "type": "number", "required": true, "description": "成功数量" }, { "name": "failed_count", "type": "number", "required": true, "description": "失败数量" } ], "errors": [ { "code": 400, "message": "订单ID列表不能为空", "description": "ids 为空或全部无效(非正整数)时返回" } ] }, { "method": "order.recheckOrder.interceptScan", "description": "拦截扫描:通过运单号查找运单记录。非拦截订单会被拒绝并提示「非拦截订单」:运单记录不存在,或运单 is_intercept≠'Y' 且关联订单 intercept_status 不在 requested/intercepting。校验通过后标记退回与拦截(is_back='Y', is_intercept='Y'),处理关联的未完结售后工单(写入「库内拦截成功」步骤并置为 completed)。若运单关联到订单,则将订单拦截状态更新为 intercepted_at_warehouse(step=4、outbound_status=fin)并释放储位分配(拦截模式:库存不归还可用,移入拦截锁定字段 intercept_locked_quantity)与订单锁(仅订单级状态更新,不标记订单下其他面单)。该状态更新**不写** intercept_time(该字段恒为「最近一次发起拦截的通知时刻」),库内确定拦截时刻以配送表 dispath_time 为准。工单处理失败不阻断主流程。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "waybill_code", "type": "string", "required": true, "source": "body", "description": "运单号" } ], "response": [ { "name": "waybill_code", "type": "string", "required": true, "description": "运单号" }, { "name": "is_back", "type": "string", "required": true, "description": "退回标记(固定为 'Y')" }, { "name": "is_intercept", "type": "string", "required": true, "description": "拦截标记(固定为 'Y')" }, { "name": "after_sale", "type": "object|null", "required": false, "description": "关联的售后工单处理结果(仅当存在未完结工单时返回);工单处理失败时为 null" }, { "name": "order", "type": "object|null", "required": false, "description": "订单拦截结果(仅当运单关联到订单时返回),包含 order_id、order_no、intercept_status;无法关联订单时为 null" } ], "errors": [ { "code": 400, "message": "运单号不能为空" }, { "code": 400, "message": "非拦截订单" } ] }, { "method": "order.recheckOrder.recheckOrderList", "description": "复核订单列表查询,通过入参 list_type 区分散单模式与团购模式。散单模式(single,默认)返回待复核订单列表(每项为一个订单,排除 pick_status='none' 和 recheck_status='fin'),团购模式(group)返回波次维度的复核汇总列表(每项为一个波次及其订单复核统计,含 review_assignment_status 计算字段)。统一使用 list 字段名输出,均支持分页与筛选。;散单模式运单号回读与运单号关键词搜索强制同仓校验(order_express.warehouse_id 必须等于订单 warehouse_id),禁止跨仓串读", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "list_type", "type": "string", "required": false, "source": "body", "description": "列表模式:single(散单模式,默认)/ group(团购模式)" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "筛选条件。散单模式支持 keyword(运单号/订单号模糊搜索)、wave_no(精确匹配)、recheck_status、pick_status、wave_index(波次内序号范围筛选,如 {\"operator\":\"between\",\"value\":[起,止]},或 wave_index_min / wave_index_max);团购模式支持 wave_no(模糊搜索)、wave_type、wave_status" }, { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page / pageSize(默认 page=1, pageSize=20)" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "散单模式(list_type=single):订单数组,每项含 order_id、delivery_order_code、order_type、wave_id、wave_no、pick_status、recheck_status、shop_nick、logistics_name、items_count、items_total、wave_index、status、create_at、pick_time、recheck_time。团购模式(list_type=group):波次汇总数组,每项含 wave_id、wave_no、wave_type、wave_status、total_orders、processed_orders、creator、create_time、update_time、order_count、reviewed_count、unreviewed_count、review_assignment_status(unreviewed/partially_reviewed/reviewed)" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息,含 page、pageSize、total、totalPages、hasPrevious、hasNext" } ], "errors": [] }, { "method": "order.recheckOrder.scanTask", "description": "按拣货任务 ID 拉取复核扫描视图。根据任务的 pick_mode 区分散单/团单模式,返回与 scanOrder 一致的数据结构,用于前端刷新数据。散单模式(pick_mode 2/3/4)扁平化任务下所有波次的订单列表(按 order_id 去重,未复核优先、wave_index 升序),顶层携带拣货人/任务等汇总信息(包括 picker_id、picker_name、pick_mode、total_orders、reviewed_count、unreviewed_count);团购模式(pick_mode 1/5)返回任务下所有团购波次及订单的分组列表(list_type='group')。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id", "type": "number", "required": true, "source": "body", "description": "拣货任务 ID(对应 wms_wave_pick_task.id)" } ], "response": [ { "name": "match_type", "type": "string", "required": true, "description": "固定为 'task',表示通过任务 ID 匹配" }, { "name": "list_type", "type": "string", "required": true, "description": "列表模式:single(散单扁平列表)/ group(团购嵌套波次列表),由拣货任务的 pick_mode 决定" }, { "name": "task_id", "type": "number", "required": true, "description": "拣货任务 ID" }, { "name": "picker_id", "type": "number|null", "required": false, "description": "拣货人 ID(来自 wms_wave_pick_task.pick_user_id),散单模式返回" }, { "name": "picker_name", "type": "string", "required": false, "description": "拣货人名称(来自 wms_wave_pick_task.pick_user_name),散单模式返回" }, { "name": "pick_mode", "type": "number", "required": false, "description": "拣货模式:1-团购小波次 2-散单单品单件 3-散单先拣后分 4-边拣边分 5-团购大波次" }, { "name": "wave_id", "type": "number", "required": false, "description": "散单模式固定为 0,团购模式不返回" }, { "name": "wave_no", "type": "string", "required": false, "description": "散单模式固定为空字符串,团购模式不返回" }, { "name": "wave_type", "type": "number", "required": false, "description": "波次类型编码(取任务下第一个有效波次的 wave_type),散单模式返回" }, { "name": "strategy_id", "type": "number|null", "required": false, "description": "散单模式固定为 null(任务级别不绑定单一策略)" }, { "name": "strategy_name", "type": "string", "required": false, "description": "散单模式固定为空字符串(任务级别不绑定单一策略)" }, { "name": "total_orders", "type": "number", "required": false, "description": "任务下订单总数(去重后),散单模式返回" }, { "name": "reviewed_count", "type": "number", "required": false, "description": "已复核订单数,散单模式返回" }, { "name": "unreviewed_count", "type": "number", "required": false, "description": "未复核订单数,散单模式返回" }, { "name": "list", "type": "array", "required": true, "description": "统一列表输出。散单模式(list_type=single):扁平订单数组(每项结构与 scanOrder 散单有波次模式一致,含 order_id/delivery_order_code/waybill_no/pick_status/is_printed/is_reviewed/shop_nick/items_count/wave_index/recheck_status/order_type/status/logistics_name/store_remark/intercept_status/stock[])。团购模式(list_type=group):波次视图数组(结构与 scanOrder 团购模式一致,每项含 wave_id/wave_no/wave_type/wave_status/total_orders/processed_orders/creator/create_time/update_time/order_count/pick_mode/box_no/orders[])", "children": [ { "name": "order_id", "type": "number", "description": "[散单] 订单 ID" }, { "name": "delivery_order_code", "type": "string", "description": "[散单] 发货单号" }, { "name": "waybill_no", "type": "string", "description": "[散单] 运单号" }, { "name": "pick_status", "type": "string", "description": "[散单] 拣货状态" }, { "name": "is_printed", "type": "boolean", "description": "[散单] 是否已打印" }, { "name": "is_reviewed", "type": "boolean", "description": "[散单] 是否已复核" }, { "name": "shop_nick", "type": "string", "description": "[散单] 店铺昵称" }, { "name": "items_count", "type": "number", "description": "[散单] 商品种类数" }, { "name": "wave_index", "type": "number", "description": "[散单] 波次内序号" }, { "name": "recheck_status", "type": "string", "description": "[散单] 复核状态" }, { "name": "wave_id", "type": "number", "description": "[散单] 波次 ID" }, { "name": "wave_no", "type": "string", "description": "[散单] 波次号" }, { "name": "order_type", "type": "string", "description": "[散单] 订单类型" }, { "name": "status", "type": "number", "description": "[散单] 订单状态码" }, { "name": "logistics_name", "type": "string", "description": "[散单] 物流名称" }, { "name": "store_remark", "type": "string", "description": "[散单] 货主备注" }, { "name": "intercept_status", "type": "string", "description": "[散单] 拦截状态" }, { "name": "stock", "type": "array", "description": "[散单] 订单商品库存明细(含 stock_id/item_code/item_name/sku_property/packing_requirements/barcodes/images/plan_qty/has_shared_barcode)" }, { "name": "wave_id", "type": "number", "description": "[团购波次项] 波次 ID" }, { "name": "wave_no", "type": "string", "description": "[团购波次项] 波次号" }, { "name": "wave_type", "type": "number", "description": "[团购波次项] 波次类型编码" }, { "name": "wave_status", "type": "number", "description": "[团购波次项] 波次状态码" }, { "name": "total_orders", "type": "number", "description": "[团购波次项] 波次内订单总数" }, { "name": "processed_orders", "type": "number", "description": "[团购波次项] 已处理订单数" }, { "name": "creator", "type": "string", "description": "[团购波次项] 波次创建人" }, { "name": "create_time", "type": "string", "description": "[团购波次项] 波次创建时间" }, { "name": "update_time", "type": "string", "description": "[团购波次项] 波次更新时间" }, { "name": "order_count", "type": "number", "description": "[团购波次项] 波次下实际订单数" }, { "name": "pick_mode", "type": "number", "description": "[团购波次项] 拣货模式" }, { "name": "box_no", "type": "number", "description": "[团购波次项] 箱号" }, { "name": "orders", "type": "array", "description": "[团购波次项] 波次下订单列表(结构与散单模式订单项一致)" } ] } ], "errors": [ { "code": 400, "message": "task_id 无效", "description": "task_id 为空或非正整数" }, { "code": 404, "message": "未找到对应拣货任务" } ] }, { "method": "order.recheckOrder.batchQuickRecheck", "description": "批量快捷复核:传入订单 IDs 列表,对每个有效订单执行前置检查(已分配储位、已分配快递、已同步且未被拦截),必要时自动完成拣货(含库存锁定校验与扣减、库存流水写入、拣货任务状态同步)后标记复核(含复核任务记录、任务复核状态更新、车任务解绑、操作日志)。每个订单在独立事务中执行,支持部分失败,不满足条件的订单跳过并返回原因。复核状态更新后,会先自动清理波次内「已拦截且未打印」的订单(wave_id 清零回池、删除波次索引与任务订单关联、回写波次统计、写 ORDER_WAVE_REMOVE 日志并触发波次策略快扫),避免拦截订单卡住波次完成判定;已打印的拦截订单保持不动。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "array|string", "required": true, "source": "body|query", "description": "订单 ID 列表,支持数组或以逗号分隔的字符串" } ], "response": [ { "name": "success", "type": "array", "required": true, "description": "复核成功的订单列表", "children": [ { "name": "order_id", "type": "number", "description": "订单ID" }, { "name": "delivery_order_code", "type": "string", "description": "发货单号" } ] }, { "name": "failed", "type": "array", "required": true, "description": "复核失败的订单列表", "children": [ { "name": "order_id", "type": "number", "description": "订单ID" }, { "name": "delivery_order_code", "type": "string", "description": "发货单号" }, { "name": "reason", "type": "string", "description": "失败原因(未分配储位 / 没有分配快递 / 没有同步 / 已拦截 / 未找到对应订单 / 复核失败: xxx)" } ] }, { "name": "success_count", "type": "number", "required": true, "description": "成功数量" }, { "name": "failed_count", "type": "number", "required": true, "description": "失败数量" } ], "errors": [ { "code": 400, "message": "订单ID列表不能为空" } ] }, { "method": "order.recheckOrder.batchQuickRecheckByWave", "description": "按波次批量快捷复核:传入波次 IDs 列表,对每个波次下所有有效订单执行前置检查(已分配储位、已分配快递、已同步且未被拦截),必要时自动完成拣货(含库存锁定校验与扣减、库存流水写入、拣货任务状态同步)后标记复核(含复核任务记录、任务复核状态更新、车任务解绑、操作日志)。每个订单在独立事务中执行,支持部分失败,不满足条件的订单跳过并返回原因。复核状态更新后,会先自动清理波次内「已拦截且未打印」的订单(wave_id 清零回池、删除波次索引与任务订单关联、回写波次统计、写 ORDER_WAVE_REMOVE 日志并触发波次策略快扫),避免拦截订单卡住波次完成判定;已打印的拦截订单保持不动。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "wave_ids", "type": "array|string", "required": true, "source": "body|query", "description": "波次 ID 列表,支持数组或以逗号分隔的字符串。兼容 waveIds(驼峰)、wave_id(单值)" } ], "response": [ { "name": "success", "type": "array", "required": true, "description": "复核成功的订单列表", "children": [ { "name": "order_id", "type": "number", "description": "订单ID" }, { "name": "wave_id", "type": "number", "description": "所属波次ID" }, { "name": "delivery_order_code", "type": "string", "description": "发货单号" } ] }, { "name": "failed", "type": "array", "required": true, "description": "复核失败的订单列表", "children": [ { "name": "order_id", "type": "number", "description": "订单ID(波次无订单时为 null)" }, { "name": "wave_id", "type": "number", "description": "所属波次ID" }, { "name": "delivery_order_code", "type": "string", "description": "发货单号(波次无订单时为 null)" }, { "name": "reason", "type": "string", "description": "失败原因(未分配储位 / 没有分配快递 / 没有同步 / 已拦截 / 波次下无订单 / 复核失败: xxx)" } ] }, { "name": "success_count", "type": "number", "required": true, "description": "成功数量" }, { "name": "failed_count", "type": "number", "required": true, "description": "失败数量" } ], "errors": [ { "code": 400, "message": "波次ID列表不能为空" } ] }, { "method": "order.recheckOrder.queryRecheckOrderSingleList", "description": "散单模式复核列表查询,按订单维度返回待复核订单(排除 pick_status='none' 和 recheck_status='fin'),支持分页与关键词/波次号/复核状态筛选。与 recheckOrderList 不同:本方法仅处理散单模式,不包含团购分支。;散单模式运单号回读与运单号关键词搜索强制同仓校验(order_express.warehouse_id 必须等于订单 warehouse_id),禁止跨仓串读", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "where", "type": "object", "required": false, "source": "body", "description": "筛选条件。支持 keyword(运单号/订单号模糊搜索)、wave_no(精确匹配)、recheck_status、pick_status、wave_index(波次内序号范围筛选,如 {\"operator\":\"between\",\"value\":[起,止]},或 wave_index_min / wave_index_max)" }, { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page / pageSize(默认 page=1, pageSize=20)" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "散单复核订单列表,每项含 order_id、delivery_order_code、order_type、wave_id、wave_no、pick_status、recheck_status、shop_nick、logistics_name、items_count、items_total、items_weight、weight_type、waybill_code、wave_index、status、create_at、recheck_time" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息,含 page、pageSize、total、totalPages、hasPrevious、hasNext" } ], "errors": [] } ] }, { "groupName": "订单打包模块", "module": "order.packing", "list": [ { "method": "order.packing.list", "description": "打包任务列表查询。按仓库维度查询打包任务,支持分页、筛选、排序。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "description": "分页参数 { page, pageSize },默认 page=1, pageSize=20", "children": [ { "name": "page", "type": "number", "required": false, "description": "页码" }, { "name": "pageSize", "type": "number", "required": false, "description": "每页条数" } ] }, { "name": "sort", "type": "object", "required": false, "description": "排序参数 { sortField, sortOrder }", "children": [ { "name": "sortField", "type": "string", "required": false, "description": "排序字段,支持:id、order_id、workbench_id、wave_id、pack_quantity、pack_mode、status、start_time、end_time、create_time、update_time" }, { "name": "sortOrder", "type": "string", "required": false, "description": "排序方向:ASC / DESC,默认 DESC" } ] }, { "name": "where", "type": "object", "required": false, "description": "筛选条件", "children": [ { "name": "status", "type": "number", "required": false, "description": "任务状态:0=待处理 1=打包中 2=已完成 3=异常" }, { "name": "pack_mode", "type": "number", "required": false, "description": "打包模式:1=散单 2=团购" }, { "name": "waybill_code", "type": "string", "required": false, "description": "运单号。通过 wms_order_express 表解析 order_id 后按订单过滤(wms_pack_task.waybill_code 通常为空)。支持 {operator,value} 标准结构,value 支持字符串或字符串数组(多单号取并集):operator=contains/like 时按 LIKE '%单号%' 模糊匹配(通配符已转义,可命中 '主体-1-1-' 等分段单号);缺省或 operator=eq 时按①完整单号等值匹配;②剥离一单多件包裹序号分段后缀(如 -1-1-)后的主体单号等值匹配;③主体单号前缀匹配(LIKE '主体-%',同主体不同分段序号,通配符已转义)。无任何匹配时返回空列表" }, { "name": "wave_no", "type": "string", "required": false, "description": "波次号。支持 {operator,value} 标准结构,value 支持字符串或字符串数组(多值取并集):operator=eq/in 精确匹配(单值等值、多值 IN),operator=ne 不等于,operator=contains/like 与缺省(不传 operator)为模糊匹配(LIKE '%值%',通配符已转义)" }, { "name": "order_id", "type": "number", "required": false, "description": "订单ID(精确匹配)" }, { "name": "workbench_id", "type": "number", "required": false, "description": "工作台ID(精确匹配)" }, { "name": "operator_text", "type": "string", "required": false, "description": "打包员(作业人员)筛选:目标列 wms_pack_task.operator_text(TEXT,多人姓名逗号拼接快照,如 '小吴哥,阿猫')。支持 {operator,value,type} 标准结构,value 支持字符串或字符串数组(多值取并集):operator=contains/like 与缺省(不传 operator)→ 模糊匹配 LIKE '%值%'(通配符 %/_ 已转义);operator=eq/in → 精确匹配(单值等值、多值 IN);operator=ne → 不等于(多值取首值);operator=notlike → 不包含 NOT LIKE '%值%'(多值逐个 AND 排除);值为 ''/null/空数组时忽略该条件(不过滤)" }, { "name": "quickWhere", "type": "string", "required": false, "description": "快捷搜索:波次号模糊匹配(LIKE '%kw%',逻辑不变)+ 运单号经 express→order→wave 链路解析(团购按波次号查、散单按订单ID查)。运单号匹配优先级:先按「完整单号等值 + 剥离一单多件分段后缀(如 -1-1-)后的主体单号等值 + 主体前缀 LIKE '主体-%'」精确匹配;精确未命中且关键词 trim 后长度 ≥ 4(QUICK_WHERE_WAYBILL_FUZZY_MIN_LENGTH)时才降级为 LIKE '%kw%' 模糊查询(兼容输入部分单号的场景);trim 后长度 < 4 的短词(含单字符如 \"7\")禁止降级模糊,运单号解析直接返回空结果(避免 %短词% 误命中海量历史单号);波次号模糊逻辑不变" }, { "name": "start_time", "type": "object", "required": false, "description": "开始打包时间范围:{operator:\"between\", value:[起始时间, 结束时间]},value 为 ISO 8601 或 \"YYYY-MM-DD HH:mm:ss\" 字符串数组" }, { "name": "start_time_start", "type": "string", "required": false, "description": "开始打包时间范围起始(ISO 8601,兼容旧写法)" }, { "name": "start_time_end", "type": "string", "required": false, "description": "开始打包时间范围结束(ISO 8601,兼容旧写法)" }, { "name": "end_time", "type": "object", "required": false, "description": "结束打包时间范围:{operator:\"between\", value:[起始时间, 结束时间]},value 为 ISO 8601 或 \"YYYY-MM-DD HH:mm:ss\" 字符串数组" }, { "name": "create_time", "type": "object", "required": false, "description": "创建时间范围:{operator:\"between\", value:[起始时间, 结束时间]},value 为 ISO 8601 或 \"YYYY-MM-DD HH:mm:ss\" 字符串数组" }, { "name": "has_video", "type": "number", "required": false, "description": "是否包含录像:1=有录像 2=无录像" }, { "name": "video_enable", "type": "number", "required": false, "description": "录像是否可用:1=可用(存在 video_url 非空且 status!=failed 的记录) 2=不可用" } ] } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "打包任务列表,每项含 id、order_id、warehouse_id、workbench_id、wave_id、wave_no、waybill_code、pack_quantity、item_quantity、sku_count、pack_mode、status、start_time、end_time、operator_text、device_ids、remark、meta、create_time、update_time、workbench_name、workbench_type、has_video、video_enable、videos[]、expresses[]" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息,含 page、pageSize、total、totalPages、hasPrevious、hasNext" } ], "errors": [] }, { "method": "order.packing.export", "description": "提交打包任务导出任务(异步)。入参 where/sort 语义与 order.packing.list 一致;warehouse_id 由服务端从 ctx.user.store_id 注入,禁止前端传入。提交后立即返回 task_id,后台异步生成单 Sheet Excel(Sheet1「打包任务列表」)并上传,导出进度/下载请通过 order.packing.exportTaskProgress 查询。数据来源 wms_pack_task 主表 + wms_pack_task_video 视频副表 + wms_workbench 工作台 + wms_order_express 运单表;Excel 列含任务ID/订单ID/波次号/运单号/关联运单号/打包模式/任务状态/打包数量/商品总数量/商品种类数/工作台/作业人员/开始打包时间/结束打包时间/创建时间/视频状态/录像可用/备注;全量分页拉取,无行数上限。任务缓存 Redis TTL 30 分钟;状态口径 submitted → running → 数据拉取(10~30) → 关联拉取(30~55) → Excel(55~90) → 上传(92) → success(100),失败 failed + error。免权限免日志免鉴权口径与 order.export 一致。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "where", "type": "object", "required": false, "source": "body", "description": "查询条件,语义与 order.packing.list 的 where 一致(支持 {operator,value,type} 标准结构或直接值;字段含 status/pack_mode/waybill_code/wave_no/order_id/workbench_id/operator_text/quickWhere/has_video/video_enable/start_time/end_time/create_time 等);禁止传入 warehouse_id/warehouseId(服务端注入)" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数,语义与 order.packing.list 的 sort 一致:sortField 白名单 id/order_id/warehouse_id/workbench_id/wave_id/pack_quantity/pack_mode/status/start_time/end_time/create_time/update_time,sortOrder asc/desc,默认 create_time desc" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID(后端生成,格式 packing_export_{warehouseId}_{timestamp}_{random})" }, { "name": "status", "type": "string", "required": true, "description": "任务状态,枚举:submitted/running/success/failed/not_found(提交成功时为 submitted)" }, { "name": "progress", "type": "number", "required": true, "description": "当前进度百分比(0-100),提交时返回 0" }, { "name": "current_count", "type": "number", "required": true, "description": "当前已处理记录数(打包任务条数)" }, { "name": "total_count", "type": "number", "required": true, "description": "总记录数(若有)" }, { "name": "message", "type": "string", "required": true, "description": "任务提示信息" }, { "name": "result", "type": "object", "required": true, "description": "任务执行结果(提交时为 null;后台完成后为上传信息对象,含 filename/url/fileKey/cdnUrl/cosUrl/current_count/total_count/sheet_count)" }, { "name": "error", "type": "string", "required": true, "description": "失败时的错误信息(可选,非失败时为空字符串)" }, { "name": "update_time", "type": "number", "required": true, "description": "任务更新时间(Unix 毫秒时间戳)" } ], "errors": [ { "code": "400", "message": "参数格式不正确或 where 条件非法" }, { "code": "500", "message": "导出任务提交失败" } ] }, { "method": "order.packing.exportTaskProgress", "description": "按 task_id 查询打包任务导出任务进度,返回 task_id、status、progress、current_count、total_count、message、result、error、download_url、update_time;上传完成后 download_url 返回下载链接(从 result.url/cdnUrl/cosUrl/fileKey 兜底取);任务缓存 Redis TTL 30 分钟,task_id 缺失或缓存未命中时 status=not_found(正常响应,非报错)。状态口径 submitted → running → 数据拉取(10~30) → 关联拉取(30~55) → Excel(55~90) → 上传(92) → success(100),失败 failed + error。免权限免日志口径与 order.exportTaskProgress 一致。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "task_id / taskId", "type": "string", "required": true, "source": "body|query", "description": "任务 ID,兼容 task_id(下划线)与 taskId(驼峰)两种写法" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID(task_id 缺失时为回显的空字符串,status=not_found)" }, { "name": "status", "type": "string", "required": true, "description": "任务状态:submitted/running/success/failed/not_found" }, { "name": "progress", "type": "number", "required": true, "description": "进度百分比(0-100)" }, { "name": "current_count", "type": "number", "required": true, "description": "当前已处理记录数(打包任务条数)" }, { "name": "total_count", "type": "number", "required": true, "description": "总记录数" }, { "name": "message", "type": "string", "required": true, "description": "任务提示信息" }, { "name": "result", "type": "object", "required": true, "description": "任务执行结果对象(完成后含 filename/url/fileKey/cdnUrl/cosUrl 等;未完成或 not_found 时为 null)" }, { "name": "error", "type": "string", "required": true, "description": "失败时的错误信息(可选,非失败时为空字符串)" }, { "name": "download_url", "type": "string", "required": true, "description": "任务完成后下载链接(从 result.url/cdnUrl/cosUrl/fileKey 兜底取);未完成或不存在时为空字符串" }, { "name": "update_time", "type": "number", "required": true, "description": "最近一次状态更新时间(Unix 毫秒时间戳)" } ], "errors": [] }, { "method": "order.packing.get", "description": "打包任务详情查询。按 id + warehouse_id 查询单条打包任务记录,含工作台、视频和运单关联信息。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "description": "打包任务ID" } ], "response": [ { "name": "data", "type": "object", "required": true, "description": "打包任务详情,含 id、order_id、warehouse_id、workbench_id、wave_id、wave_no、waybill_code、pack_quantity、item_quantity、sku_count、pack_mode、status、start_time、end_time、operator_text、device_ids、remark、meta、create_time、update_time、workbench_name、workbench_type、has_video、video_enable、videos[]、expresses[]" } ], "errors": [ { "code": 400, "description": "参数校验失败(如缺少 id)" }, { "code": 404, "description": "打包任务不存在或无权访问" } ] }, { "method": "order.packing.setEndTime", "description": "设置打包任务结束时间。若任务状态不是已完成(2),则同步更新状态为已完成。前端默认值:若任务已有结束时间则默认为当前时间,否则默认为开始时间+5分钟。结束时间超过仓库配置的打包最大时长上限时自动截断为 开始时间+上限时长(散单 single_order_pack_max_minutes 默认 3 分钟 / 团购 group_order_pack_max_minutes 默认 40 分钟)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "description": "打包任务ID" }, { "name": "end_time", "type": "string", "required": true, "description": "结束时间(ISO 8601 格式,如 2026-07-27T11:00:00.000Z)。前端默认值:若任务已有结束时间→当前时间;无结束时间→开始时间+5分钟。若超过仓库配置的打包最大时长上限(开始时间+配置分钟数),将自动截断为上限时间" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "打包任务ID" }, { "name": "end_time", "type": "string", "required": true, "description": "更新后的结束时间(已按仓库配置上限截断,最多为开始时间+配置分钟数)" }, { "name": "status", "type": "number", "required": true, "description": "更新后的任务状态" } ], "errors": [ { "code": 400, "description": "参数校验失败(如缺少 id 或 end_time、用户未绑定仓库)" }, { "code": 404, "description": "打包任务不存在或无权访问" } ] }, { "method": "order.packing.forceRecord", "description": "强制重新录制打包任务视频。将任务推送到录制电脑,通过打印服务触发重新录制。内部会重置视频状态为 created 并清空 video_url。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "description": "打包任务ID" } ], "response": [ { "name": "pack_task_id", "type": "number", "required": true, "description": "打包任务ID" }, { "name": "computer_id", "type": "number", "required": true, "description": "录制电脑ID" } ], "errors": [ { "code": 400, "description": "参数校验失败(如缺少 id、用户未绑定仓库、无录制电脑、录制电脑不在线)" }, { "code": 404, "description": "打包任务不存在或无权访问" }, { "code": 500, "description": "通知打印服务失败" } ] } ] }, { "groupName": "订单波次模块", "module": "order.wave", "list": [ { "method": "order.wave.waveStrategyList", "description": "查询当前仓库波次策略列表。仅查询当前登录仓库在 wms_wave_strategy 中的数据,返回标准 list/pagination 结构。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page / pageSize" }, { "name": "strategy_type", "type": "number", "required": false, "source": "body", "description": "仅支持 1=散单、2=团购;与 where.strategy_type 同时存在时以顶层 strategy_type 为准。" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "当前仅支持 where.strategy_type(1/2);其余 where 字段暂不支持。" }, { "name": "calculate_next_fetch_order_count / calculateNextFetchOrderCount", "type": "number", "required": false, "source": "body", "description": "0-不计算(默认),1-计算并返回每条策略的 next_fetch_order_count;支持别名 calculateNextFetchOrderCount" }, { "name": "debug", "type": "number", "required": false, "source": "body", "description": "0-不启用(默认),1-启用调试输出,返回每条策略的 next_fetch_order_list(含结构/快递/货主ID等指标明细)" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "策略列表,每项为波次策略记录", "children": [ { "name": "id", "type": "number", "description": "策略ID" }, { "name": "strategy_name", "type": "string", "description": "策略名称" }, { "name": "warehouse_id", "type": "number", "description": "仓库ID" }, { "name": "strategy_type", "type": "number", "description": "策略类型:1-散单 2-团购" }, { "name": "status", "type": "number", "description": "状态:1-启用 0-停用" }, { "name": "order_min_sku", "type": "number", "description": "订单最小 SKU 种类数(可为空)" }, { "name": "order_max_sku", "type": "number", "description": "订单最大 SKU 种类数(可为空)" }, { "name": "order_min_qty", "type": "number", "description": "订单最小商品总数(可为空)" }, { "name": "order_max_qty", "type": "number", "description": "订单最大商品总数(可为空)" }, { "name": "min_same_structure", "type": "number", "description": "最小相同结构订单数(可为空)" }, { "name": "max_same_structure", "type": "number", "description": "最大相同结构订单数(可为空)" }, { "name": "require_same_express", "type": "boolean", "description": "是否要求相同快递" }, { "name": "allow_cross_owner", "type": "boolean", "description": "是否允许跨货主" }, { "name": "batch_mode", "type": "number", "description": "拣货模式" }, { "name": "batch_max_orders", "type": "number", "description": "批次最大订单数(可为空)" }, { "name": "batch_max_skus", "type": "number", "description": "批次最大 SKU 总数(可为空)" }, { "name": "group_batch_max_orders", "type": "number", "description": "团购批次最大订单数(可为空)" }, { "name": "allowed_owners", "type": "array", "description": "允许的货主 ID 列表(数组或 null)" }, { "name": "allowed_expresses", "type": "array", "description": "允许的快递编码列表(数组或 null)" }, { "name": "allowed_provinces", "type": "array", "description": "允许的省份列表(数组或 null)" }, { "name": "allowed_platforms", "type": "array", "description": "允许的平台列表(数组或 null)" }, { "name": "description", "type": "string", "description": "策略描述" }, { "name": "creator_name", "type": "string", "description": "创建人" }, { "name": "create_time", "type": "string", "description": "创建时间(ISO 字符串)" }, { "name": "update_time", "type": "string", "description": "更新时间(ISO 字符串)" }, { "name": "matched_order_count_filtered", "type": "number", "description": "按当前仓库且仅统计未在波次(step!=0)并满足同结构区间后的命中订单数;口径与抓取候选一致:require_same_express=1 时按「结构+快递」分组计数,否则仅按结构分组计数" }, { "name": "next_fetch_order_count", "type": "number", "description": "按当前策略口径预演一次自动抓取时,预计会选中的订单数量;未开启计算时返回 0" }, { "name": "next_fetch_order_list", "type": "object", "description": "调试字段,仅 debug=1 时返回。包含候选订单明细及指标(结构、快递、货主ID 等)", "children": [ { "name": "candidate_count", "type": "number", "description": "当前策略匹配的候选订单总数" }, { "name": "candidates", "type": "array", "description": "候选订单明细列表(最多 500 条)", "children": [ { "name": "order_id", "type": "number", "description": "订单ID" }, { "name": "structure", "type": "object", "description": "商品结构(items_hash / items)" }, { "name": "express", "type": "object", "description": "快递信息(sys_logistics_code / logistics_code / logistics_name)" }, { "name": "store_id", "type": "string", "description": "货主ID" }, { "name": "items_count", "type": "number", "description": "SKU 种类数" }, { "name": "items_total", "type": "number", "description": "商品总件数" }, { "name": "wave_id", "type": "number", "description": "当前波次ID(0=未入波次)" }, { "name": "status", "type": "string", "description": "订单状态" }, { "name": "outbound_status", "type": "string", "description": "出库状态" }, { "name": "post_status", "type": "string", "description": "快递分配状态" }, { "name": "storage_status", "type": "string", "description": "储位分配状态" } ] } ] } ] }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)" }, { "name": "info", "type": "object", "required": true, "description": "查询汇总信息对象(成功路径恒存在;错误/失败路径响应结构不变,不含本字段)。包含当前查询条件下全部波次策略命中的去重订单总数。", "children": [ { "name": "order_count", "type": "number", "description": "当前查询条件下(当前仓库 + strategy_type 过滤)所有策略命中的订单总数,按订单去重(COUNT DISTINCT order_id)统计,不受分页影响;口径与 list[*].matched_order_count_filtered 的抓取候选一致(require_same_express=1 与 =0 两类候选口径合并去重);仅当当前仓库存在波次策略时执行统计,统计失败时安全降级为 0,不影响列表主流程。" } ] } ], "errors": [ { "code": "400", "message": "缺少仓库上下文或分页参数不合法" }, { "code": "400", "message": "strategy_type 非法(仅支持 1/2)" }, { "code": "500", "message": "查询失败" } ] }, { "method": "order.wave.waveStrategyCreate", "description": "新增波次策略。warehouse_id 与 creator_name 强制使用当前上下文,不接受外部覆盖。创建成功后会推进仓库的 wave_strategy_version 并失效相关缓存。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "strategy_name", "type": "string", "required": true, "source": "body", "description": "策略名称(必填)" }, { "name": "strategy_type", "type": "number", "required": true, "source": "body", "description": "策略类型(必填,正整数):1-散单 2-团购" }, { "name": "batch_mode", "type": "number", "required": true, "source": "body", "description": "拣货模式(必填,正整数)" }, { "name": "status", "type": "number", "required": false, "source": "body", "description": "状态:1-启用 0-停用(可选)" }, { "name": "order_min_sku", "type": "number", "required": false, "source": "body", "description": "订单最小 SKU 种类数(可选,正整数或 null)" }, { "name": "order_max_sku", "type": "number", "required": false, "source": "body", "description": "订单最大 SKU 种类数(可选,正整数或 null)" }, { "name": "order_min_qty", "type": "number", "required": false, "source": "body", "description": "订单最小商品总数(可选,正整数或 null)" }, { "name": "order_max_qty", "type": "number", "required": false, "source": "body", "description": "订单最大商品总数(可选,正整数或 null)" }, { "name": "min_same_structure", "type": "number", "required": false, "source": "body", "description": "最小相同结构订单数(可选,正整数或 null)" }, { "name": "max_same_structure", "type": "number", "required": false, "source": "body", "description": "最大相同结构订单数(可选,正整数或 null)。注意:若传入值 >= 仓库配置的 min_group_order_fetch_quantity,则会被下调为 min_group_order_fetch_quantity - 1,最小为 1。" }, { "name": "batch_max_orders", "type": "number", "required": false, "source": "body", "description": "批次最大订单数(可选)" }, { "name": "batch_max_skus", "type": "number", "required": false, "source": "body", "description": "批次最大 SKU 总数(可选)" }, { "name": "group_batch_max_orders", "type": "number", "required": false, "source": "body", "description": "团购批次最大订单数(可选)" }, { "name": "require_same_express", "type": "boolean", "required": false, "source": "body", "description": "是否要求相同快递(可选,布尔)" }, { "name": "allow_cross_owner", "type": "boolean", "required": false, "source": "body", "description": "是否允许跨货主(可选,布尔)" }, { "name": "description", "type": "string", "required": false, "source": "body", "description": "策略描述(可选)" }, { "name": "allowed_provinces", "type": "array|string", "required": false, "source": "body", "description": "允许的省份列表(可选,支持数组、JSON 字符串或逗号分隔字符串)" }, { "name": "allowed_platforms", "type": "array|string", "required": false, "source": "body", "description": "允许的平台列表(可选,支持数组、JSON 字符串或逗号分隔字符串)" }, { "name": "allowed_owners", "type": "array|string", "required": false, "source": "body", "description": "允许的货主列表(可选,支持数组/JSON/逗号分隔);系统会校验所传货主是否在仓库可用货主范围内,非法值将导致 400 错误。" }, { "name": "allowed_expresses", "type": "array|string", "required": false, "source": "body", "description": "允许的快递编码列表(可选,支持数组/JSON/逗号分隔);系统会校验所传编码是否在可用快递列表内,非法值将导致 400 错误。" }, { "name": "wave_prefix", "type": "string", "required": false, "source": "body", "description": "波次编号前缀(可选),最多 5 个字符,如 D、B、A;不传则保持原值" } ], "response": [ { "name": "data", "type": "object", "required": true, "description": "创建的策略对象,字段同 order.wave.waveStrategyList.list[*] 所示" }, { "name": "code", "type": "number", "required": true, "description": "HTTP-like 状态码,成功时返回 200" } ], "errors": [ { "code": "400", "message": "缺少必填参数或参数校验失败(包括 allowed_owners/allowed_expresses 非法)" }, { "code": "500", "message": "创建失败或内部错误" } ] }, { "method": "order.wave.waveStrategyUpdate", "description": "修改波次策略。warehouse_id 与 creator_name 强制使用当前上下文,不接受外部覆盖。id(或 strategy_id/strategyId)为必填主键,其他字段为可选更新;更新成功后会推进仓库的 wave_strategy_version 并失效相关缓存。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id / strategy_id / strategyId", "type": "number", "required": true, "source": "body", "description": "策略主键,兼容 id / strategy_id / strategyId(必填)" }, { "name": "strategy_name", "type": "string", "required": false, "source": "body", "description": "策略名称(可选)" }, { "name": "strategy_type", "type": "number", "required": false, "source": "body", "description": "策略类型(可选,正整数)" }, { "name": "batch_mode", "type": "number", "required": false, "source": "body", "description": "拣货模式(可选,正整数)" }, { "name": "status", "type": "number", "required": false, "source": "body", "description": "状态:1-启用 0-停用(可选)" }, { "name": "order_min_sku", "type": "number", "required": false, "source": "body", "description": "订单最小 SKU 种类数(可选,正整数或 null)" }, { "name": "order_max_sku", "type": "number", "required": false, "source": "body", "description": "订单最大 SKU 种类数(可选,正整数或 null)" }, { "name": "order_min_qty", "type": "number", "required": false, "source": "body", "description": "订单最小商品总数(可选,正整数或 null)" }, { "name": "order_max_qty", "type": "number", "required": false, "source": "body", "description": "订单最大商品总数(可选,正整数或 null)" }, { "name": "min_same_structure", "type": "number", "required": false, "source": "body", "description": "最小相同结构订单数(可选,正整数或 null)" }, { "name": "max_same_structure", "type": "number", "required": false, "source": "body", "description": "最大相同结构订单数(可选,正整数或 null)。会受仓库 min_group_order_fetch_quantity 约束,接口会自动调整。" }, { "name": "batch_max_orders", "type": "number", "required": false, "source": "body", "description": "批次最大订单数(可选)" }, { "name": "batch_max_skus", "type": "number", "required": false, "source": "body", "description": "批次最大 SKU 总数(可选)" }, { "name": "group_batch_max_orders", "type": "number", "required": false, "source": "body", "description": "团购批次最大订单数(可选)" }, { "name": "require_same_express", "type": "boolean", "required": false, "source": "body", "description": "是否要求相同快递(可选,布尔)" }, { "name": "allow_cross_owner", "type": "boolean", "required": false, "source": "body", "description": "是否允许跨货主(可选,布尔)" }, { "name": "description", "type": "string", "required": false, "source": "body", "description": "策略描述(可选)" }, { "name": "allowed_provinces", "type": "array|string", "required": false, "source": "body", "description": "允许的省份列表(可选,支持数组/JSON/逗号分隔)" }, { "name": "allowed_platforms", "type": "array|string", "required": false, "source": "body", "description": "允许的平台列表(可选,支持数组/JSON/逗号分隔)" }, { "name": "allowed_owners", "type": "array|string", "required": false, "source": "body", "description": "允许的货主列表(可选,支持数组/JSON/逗号分隔);系统会校验所传货主是否在仓库可用货主范围内,非法值将导致 400 错误。" }, { "name": "allowed_expresses", "type": "array|string", "required": false, "source": "body", "description": "允许的快递编码列表(可选,支持数组/JSON/逗号分隔);系统会校验所传编码是否在可用快递列表内,非法值将导致 400 错误。" }, { "name": "wave_prefix", "type": "string", "required": false, "source": "body", "description": "波次编号前缀(可选),最多 5 个字符,如 D、B、A;不传则保持原值" } ], "response": [ { "name": "data", "type": "object", "required": true, "description": "更新后的策略对象,字段同 order.wave.waveStrategyList.list[*] 所示" }, { "name": "code", "type": "number", "required": true, "description": "HTTP-like 状态码,成功时返回 200" } ], "errors": [ { "code": "400", "message": "缺少 id 或无可更新字段或参数校验失败" }, { "code": "404", "message": "波次策略不存在" }, { "code": "500", "message": "更新失败或内部错误" } ] }, { "method": "order.wave.waveStrategyQuickScan", "description": "提交波次策略快速扫描异步任务。无外部参数,使用当前仓库上下文;同一仓库同一时刻仅允许一个任务运行,若已有运行任务直接返回已有 task_id。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [ { "name": "status", "type": "string", "required": true, "description": "提交状态,固定 success" }, { "name": "task_id", "type": "string", "required": true, "description": "任务 ID(用于后续查询进度)" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "仓库 ID(来自当前上下文)" }, { "name": "state", "type": "string", "required": true, "description": "任务状态(一般为 submitted 或 running)" }, { "name": "message", "type": "string", "required": false, "description": "可选提示信息" }, { "name": "accepted_at", "type": "string", "required": false, "description": "任务受理时间(ISO 字符串)" } ], "errors": [ { "code": "400", "description": "未识别到当前仓库上下文" }, { "code": "500", "description": "任务提交失败或内部错误" } ] }, { "method": "order.wave.waveStrategyFetchPda", "description": "按策略提交并创建抓取主流程任务(PDA)。当前为最小主流程:进行入参校验并创建任务记录,返回创建结果与计划预览;后续扫描/执行阶段将扩展为完整执行流。 注意:当存在未完成任务时,接口返回 fetch_state=3 且同时返回 existing task_id/task_no,前端可直接进入拣货流程。 小团购跨池同结构合并规则:候选订单按创建时间分割为第一池(今日 0 点前)与第二池(今日订单),只有第一池抓取完毕才抓取第二池;小团购(pickMode=1)第一池抓取时,按第一池候选分组出现过的结构 key(require_same_express=1 时为「结构+快递」组合)将同结构全池订单(不限策略匹配、不含池边界)并入候选,随后复用既有分组建波流程,修复同结构订单被两池分割后单独成波(1 单 1 波次)的问题。合并触发条件:小团购 pickMode=1、第一池非空(candidate_pool_stage=first)、策略 max_same_structure 为正整数且≠999;max_same_structure 为 null/999 的团购策略跳过合并维持现状,大团购 pickMode=5 与后台抓取入口(order.wave.waveStrategyFetchAdmin)不覆盖;同结构全池查询无新增订单时亦不合并。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "strategy_id / strategyId", "type": "number", "required": true, "source": "body", "description": "策略ID(正整数,支持下划线/驼峰)" }, { "name": "cart_id / cartId", "type": "string|number", "required": false, "source": "body", "description": "可选,关联拣货车/作业车ID,支持字符串或数字,用于记录作业上下文" }, { "name": "source / operation_source", "type": "string", "required": false, "source": "body", "description": "可选,操作来源标识(例如 pda/admin/manual/auto),用于审计与分流策略" }, { "name": "strategy_params / strategyParams", "type": "object", "required": false, "source": "body", "description": "可选,策略参数透传对象(如 order_min_qty/order_max_qty/allow_cross_owner 等),在创建任务时作为策略覆盖或附加参数使用" } ], "response": [ { "name": "state", "type": "string", "required": true, "description": "任务状态:created(已创建主流程任务),后续可能为 running/success/failed" }, { "name": "task_id", "type": "string", "required": true, "description": "任务唯一 ID(用于后续查询或关联)" }, { "name": "task_no", "type": "string", "required": true, "description": "任务业务编号(便于展示与关联)" }, { "name": "warehouse_id", "type": "number", "required": false, "description": "生效的仓库 ID(来自当前上下文,如可用则返回)" }, { "name": "strategy_id", "type": "number", "required": false, "description": "生效的策略 ID(与入参保持一致,兼容回传)" }, { "name": "plan", "type": "object", "required": true, "description": "任务计划/执行预览对象,描述本次任务预估的执行计划", "children": [ { "name": "estimated_wave_count", "type": "number", "description": "预估将创建的波次数量(若适用)" }, { "name": "estimated_order_count", "type": "number", "description": "预估涉及的订单数量" }, { "name": "estimated_items_total", "type": "number", "description": "预估涉及的商品总件数" }, { "name": "preview_orders", "type": "array", "description": "可选:示例性订单 ID 列表或摘要(仅为预览,实际执行结果以最终任务为准)" } ] }, { "name": "plan_summary", "type": "string", "required": true, "description": "计划摘要字符串,便于前端在受理后快速展示(例如:'创建 3 个波次,涉及 120 单,约 450 件')" }, { "name": "validation_errors", "type": "array", "required": false, "description": "当入参校验失败时返回的数组,每项为 { field, message } 对象,供前端展示或定位问题" }, { "name": "message", "type": "string", "required": false, "description": "可选提示信息或错误说明(创建失败时返回简短说明)" }, { "name": "fetch_state", "type": "number", "required": true, "description": "抓取结果三态:1=成功创建任务(返回 task_id/task_no),2=普通失败(task_id=null),3=存在未完成任务(返回 existing task_id/task_no,前端可进入拣货流程)" }, { "name": "tip", "type": "string", "required": false, "description": "简短提示,用于向前端展示简要原因或下一步建议" }, { "name": "can_enter_pick_flow", "type": "boolean", "required": false, "description": "仅当 fetch_state=3 时为 true,表示前端可直接进入拣货流程" }, { "name": "merged_order_count", "type": "number", "required": false, "description": "小团购(pickMode=1)第一池抓取时,同结构全池订单并入候选的新增订单数量(合并进候选的跨池订单数量,仅统计新增并入、不含第一池原候选);未触发合并或合并无新增订单时为 0。统计口径:本字段不包含在原 candidate_count(合并前候选订单数,位于抓取主流程自动分流执行结果 result 内)之中,合并生效后实际参与分组建波的候选订单总量 = candidate_count + merged_order_count(最终以 selected_order_ids 为准)。触发条件:团购策略(strategy_type=2)且 pickMode=1、第一池非空、策略 max_same_structure 为正整数且≠999;require_same_express=1 时按「结构+快递」组合合并。跳过条件:pickMode=5(大团购)、max_same_structure 为 null/999、第一池为空、同结构全池无新增订单;后台抓取入口(order.wave.waveStrategyFetchAdmin)不经过该合并。该字段来自抓取主流程自动分流执行结果 result(任务创建链路内部返回并写入审计日志)。" } ], "errors": [ { "code": "400", "message": "参数校验失败(详见 validation_errors)" }, { "code": "400", "message": "未识别到当前仓库上下文" }, { "code": "500", "message": "创建任务失败或内部错误,message 字段含简短说明" } ] }, { "method": "order.wave.waveStrategyFetchAdmin", "description": "按策略提交并创建抓取主流程任务(后台管理)。当前为最小主流程:执行入参校验并创建任务记录,返回创建结果与计划预览;后续将扩展完整扫描/执行链路。 注意:当存在未完成任务时,接口返回 fetch_state=3 且同时返回 existing task_id/task_no,前端可直接进入拣货流程。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "strategy_id / strategyId", "type": "number", "required": true, "source": "body", "description": "策略ID(正整数,支持下划线/驼峰)" }, { "name": "cart_id / cartId", "type": "string|number", "required": false, "source": "body", "description": "可选,关联拣货车/作业车ID,用于记录作业上下文或幂等识别" }, { "name": "source / operation_source", "type": "string", "required": false, "source": "body", "description": "可选,操作来源标识(例如 admin/pda/manual/auto),用于审计与分流策略" }, { "name": "strategy_params / strategyParams", "type": "object", "required": false, "source": "body", "description": "可选,策略参数透传对象(如 order_min_qty/order_max_qty/allow_cross_owner 等),在创建任务时作为策略覆盖或附加参数使用" } ], "response": [ { "name": "state", "type": "string", "required": true, "description": "任务状态:created(已创建主流程任务),后续可能为 running/success/failed" }, { "name": "task_id", "type": "string", "required": true, "description": "任务唯一 ID(用于后续查询或关联)" }, { "name": "task_no", "type": "string", "required": true, "description": "任务业务编号(便于展示与关联)" }, { "name": "warehouse_id", "type": "number", "required": false, "description": "生效的仓库 ID(来自当前上下文,如可用则返回)" }, { "name": "strategy_id", "type": "number", "required": false, "description": "生效的策略 ID(与入参保持一致,兼容回传)" }, { "name": "plan", "type": "object", "required": true, "description": "任务计划/执行预览对象,描述本次任务预估的执行计划", "children": [ { "name": "estimated_wave_count", "type": "number", "description": "预估将创建的波次数量(若适用)" }, { "name": "estimated_order_count", "type": "number", "description": "预估涉及的订单数量" }, { "name": "estimated_items_total", "type": "number", "description": "预估涉及的商品总件数" }, { "name": "preview_orders", "type": "array", "description": "可选:示例性订单 ID 列表或摘要(仅为预览,实际执行结果以最终任务为准)" } ] }, { "name": "plan_summary", "type": "string", "required": true, "description": "计划摘要字符串,便于前端在受理后快速展示(例如:'创建 3 个波次,涉及 120 单,约 450 件')" }, { "name": "validation_errors", "type": "array", "required": false, "description": "当入参校验失败时返回的数组,每项为 { field, message } 对象,供前端展示或定位问题" }, { "name": "message", "type": "string", "required": false, "description": "可选提示信息或错误说明(创建失败时返回简短说明)" }, { "name": "fetch_state", "type": "number", "required": true, "description": "抓取结果三态:1=成功创建任务(返回 task_id/task_no),2=普通失败(task_id=null),3=存在未完成任务(返回 existing task_id/task_no,前端可进入拣货流程)" }, { "name": "tip", "type": "string", "required": false, "description": "简短提示,用于向前端展示简要原因或下一步建议" }, { "name": "can_enter_pick_flow", "type": "boolean", "required": false, "description": "仅当 fetch_state=3 时为 true,表示前端可直接进入拣货流程" } ], "errors": [ { "code": "400", "description": "参数校验失败(详见 validation_errors)" }, { "code": "400", "description": "未识别到当前仓库上下文" }, { "code": "500", "description": "创建任务失败或内部错误,message 字段含简短说明" } ] }, { "method": "order.wave.waveStrategyQuickScanTaskProgress", "description": "查询波次策略快速扫描任务进度。接受 task_id / taskId,若未找到返回 state='not_found'。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id / taskId", "type": "string", "required": true, "source": "body", "description": "任务 ID(下划线或驼峰兼容,必填)" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID" }, { "name": "state", "type": "string", "required": true, "description": "任务状态:submitted/running/success/failed/not_found" }, { "name": "warehouse_id", "type": "number", "required": false, "description": "仓库 ID" }, { "name": "total_order_count", "type": "number", "required": false, "description": "扫描订单总数" }, { "name": "processed_order_count", "type": "number", "required": false, "description": "已处理订单数" }, { "name": "matched_order_count", "type": "number", "required": false, "description": "命中策略的订单数" }, { "name": "unmatched_order_count", "type": "number", "required": false, "description": "未命中策略的订单数" }, { "name": "progress_percent", "type": "number", "required": false, "description": "进度百分比(0-100)" }, { "name": "submitted_at", "type": "string", "required": false, "description": "提交时间(timestamp 或 ISO)" }, { "name": "start_time", "type": "string", "required": false, "description": "实际开始时间(ISO)" }, { "name": "end_time", "type": "string", "required": false, "description": "结束时间(ISO)" }, { "name": "error_message", "type": "string", "required": false, "description": "错误信息(若失败)" }, { "name": "error_code", "type": "string", "required": false, "description": "错误码(若失败)" }, { "name": "duration_ms", "type": "number", "required": false, "description": "耗时,毫秒" } ], "errors": [ { "code": "400", "description": "task_id 参数不能为空" }, { "code": "500", "description": "查询失败或内部错误" } ] }, { "method": "order.wave.groupOrderFetchList", "description": "按机器结构分组的可抓取列表。仅处理待处理订单(排除待审核),且排除已在波次中的订单。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page / pageSize" }, { "name": "distinguish_express", "type": "boolean", "required": false, "source": "body", "description": "是否区分快递(影响分组粒度)" }, { "name": "store_id", "type": "number", "required": false, "source": "body", "description": "货主ID(仅作为筛选条件)" }, { "name": "same_order_quantity", "type": "number", "required": false, "source": "body", "description": "最小同组订单数量阈值(>=)。若显式传入有效数值则按传入值使用;未传入时使用仓库配置 min_group_order_fetch_quantity(默认 13)。" }, { "name": "shop_name", "type": "string", "required": false, "source": "body", "description": "店铺名称(模糊匹配)" }, { "name": "include_sku", "type": "string", "required": false, "source": "body", "description": "仅保留包含该 SKU 的分组(页内过滤)" }, { "name": "return_order_ids", "type": "boolean", "required": false, "source": "body", "description": "是否在结果中返回组内订单ID列表" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "分组列表,每项包含 item_detail、item_detail_machine、item_detail_machine_snapshot、item_snapshot、group、group_count、items_total、items_weight(总重量g,取组内首单 items_weight)、store_id、store_ids、logistics_name、distinguish_express、first_order_time、last_order_time、status_summary 等字段;若指定 return_order_ids=true 则额外包含 order_ids" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)" } ], "errors": [ { "code": "400", "message": "缺少仓库上下文或参数格式错误" }, { "code": "500", "message": "查询失败" } ] }, { "method": "order.wave.singleFetchByIds", "description": "按订单 ID 列表抓取到一个散单波次。仅处理当前仓库的待处理订单(step in [1,2,3]),排除已在波次中的订单(wave_id>0),不区分快递;成功抓取后批量写入订单操作日志;当无可抓取订单时返回 wave_id=0。已锁定订单(lock_status 非 none)不允许抓取波次,返回 excluded_locked_order_ids。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids / order_ids / orderIds", "type": "array|string|number", "required": true, "source": "body", "description": "订单 ID 列表;支持数组、逗号分隔字符串或单个 ID。入参会被去重并转换为正整数。字段解析优先顺序:ids -> order_ids -> orderIds。" } ], "response": [ { "name": "ids", "type": "array", "required": true, "description": "请求归一化后的 ids 列表(去重且为正整数)" }, { "name": "wave_id", "type": "number", "required": true, "description": "创建的波次 ID;若无可抓取订单返回 0" }, { "name": "wave_no", "type": "string", "required": true, "description": "创建的波次号;无可抓取时为空字符串" }, { "name": "fetched_order_ids", "type": "array", "required": true, "description": "实际被抓取并成功分配到波次的订单 ID 列表(为归一化后的 ids 的子集)" }, { "name": "fetched_order_count", "type": "number", "required": true, "description": "实际被抓取的订单数量(等于 fetched_order_ids.length)" }, { "name": "excluded_existing_wave_order_ids", "type": "array", "required": false, "description": "原始入参中已在其它波次中的订单 ID(被排除,不会被抓取)" }, { "name": "excluded_locked_order_ids", "type": "array", "required": false, "description": "因已锁定(lock_status 非 none)被排除、不会被抓取波次的订单 ID 列表(成功与无可抓取订单两个返回分支均返回)" }, { "name": "skipped_order_ids", "type": "array", "required": false, "description": "因订单状态不符、正在出库或其他业务原因被跳过的订单 ID(不会被抓取)" }, { "name": "not_found_order_ids", "type": "array", "required": false, "description": "入参中未在数据库中找到的订单 ID" } ], "errors": [ { "code": "400", "message": "未识别到当前仓库上下文或 ids 参数不能为空或格式错误;当入参包含非法字段或别名冲突时也会返回 400" }, { "code": "500", "message": "抓取失败或内部错误" } ] }, { "method": "order.wave.waveStrategyFallbackOrderList", "description": "基于波次策略的回退候选订单列表。该接口内置固定筛选条件:step != 0、wave_id = 0,且满足以下任一条件:wave_scan_result = 2(未匹配任何波次策略)、print_status = 'fin'(已完全打印)、lock_status != 'none'(订单已锁定)、intercept_status != 'none'(订单已拦截)。用于展示策略未命中或需回退处理的订单候选。;列表运单号回填强制同仓校验:wms_order_express 按「订单ID + 订单所属仓库ID」隔离读取,禁止仅凭订单ID跨仓串读运单号", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page / pageSize" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "筛选白名单字段(object)。仅支持下列字段,且禁止传入 warehouse_id / warehouseId:\n- id(等值)\n- delivery_no / deliveryNo(模糊)\n- tracking_no / trackingNo(模糊)\n- items_count_min / items_count_max(范围)\n- items_total_min / items_total_max(范围)\n- sys_logistics_name(模糊)\n- store_name(模糊)\n- owner_name(等值)\n- province(模糊)\n- sys_platform_name(模糊)\n- buyer_message_has(虚拟字段,覆盖 buyer_message/seller_message/remark 三个字段,任一有值即为有留言,value=true/false)\n说明:若传入未列出的字段或禁止字段(如 warehouse_id)接口会返回 400。" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "回退候选订单简要列表。数组内对象字段说明见 children;每行含 excluded_reason 中文标记:已锁定(lock_status 非 none)、已拦截、已打印、未匹配策略。", "children": [ { "name": "id", "type": "number", "description": "订单 ID" }, { "name": "delivery_no", "type": "string", "description": "配送单号" }, { "name": "tracking_no", "type": "string", "description": "运单号" }, { "name": "items_count", "type": "number", "description": "SKU 种类数" }, { "name": "items_total", "type": "number", "description": "总件数" }, { "name": "items_weight", "type": "number", "description": "订单总重量(g),来自 wms_order.items_weight,为 null 时返回 null" }, { "name": "weight_type", "type": "string", "description": "重量类型中文标签,取值:常规/轻货/重货/冷链(对应 DB 值 0/1/2/3)" }, { "name": "sys_logistics_name", "type": "string", "description": "系统快递名称" }, { "name": "store_name", "type": "string", "description": "货主名称" }, { "name": "province", "type": "string", "description": "省/直辖市" }, { "name": "sys_platform_name", "type": "string", "description": "平台名称" }, { "name": "item_snapshot", "type": "string", "description": "商品快照,格式示例:苹果*2|香蕉*3" }, { "name": "wave_index", "type": "number", "description": "波次内序号(联查 wms_order_wave_index,无记录时为 0)" }, { "name": "excluded_reason", "type": "string", "description": "订单进入回退列表的原因(中文标签):已锁定(lock_status 非 none)/ 已拦截 / 已打印 / 未匹配策略" } ] }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)" } ], "errors": [ { "code": "400", "message": "未识别到当前仓库上下文或 where 中包含非法/禁止字段(如 warehouse_id)或存在别名冲突" }, { "code": "500", "message": "查询失败或内部错误" } ] }, { "method": "order.wave.singleOrderFetchList", "description": "按机器结构分组的散单候选列表。仅处理待处理订单(排除待审核),且排除已在波次中的订单。与 order.wave.groupOrderFetchList 不同:groupOrderFetchList 返回满足同组订单数量 >= same_order_quantity(或仓库配置 min_group_order_fetch_quantity)的团购命中分组;singleOrderFetchList 则排除这些团购命中分组,仅返回同组订单数量小于该阈值的散单候选分组(即 < same_order_quantity)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page / pageSize" }, { "name": "distinguish_express", "type": "boolean", "required": false, "source": "body", "description": "是否区分快递(影响分组粒度)" }, { "name": "store_id", "type": "number", "required": false, "source": "body", "description": "货主ID(仅作为筛选条件)" }, { "name": "same_order_quantity", "type": "number", "required": false, "source": "body", "description": "最小同组订单数量阈值(用于判定团购命中);本接口返回同组订单数量小于该阈值的分组。若显式传入有效数值则按传入值使用;未传入时使用仓库配置 min_group_order_fetch_quantity(默认 13)。" }, { "name": "shop_name", "type": "string", "required": false, "source": "body", "description": "店铺名称(模糊匹配)" }, { "name": "include_sku", "type": "string", "required": false, "source": "body", "description": "仅保留包含该 SKU 的分组(页内过滤)" }, { "name": "return_order_ids", "type": "boolean", "required": false, "source": "body", "description": "是否在结果中返回组内订单ID列表" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "散单候选分组列表,每项包含 item_detail、item_detail_machine、item_detail_machine_snapshot、item_snapshot、group、group_count、items_total、items_weight(总重量g,取组内首单 items_weight)、store_id、store_ids、logistics_name、distinguish_express、first_order_time、last_order_time、status_summary 等字段;返回的 group_count 均小于 same_order_quantity(或仓库配置的 min_group_order_fetch_quantity);若指定 return_order_ids=true 则额外包含 order_ids" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)" } ], "errors": [ { "code": "400", "message": "缺少仓库上下文或参数格式错误" }, { "code": "500", "message": "查询失败" } ] }, { "method": "order.wave.wavePickTaskList", "description": "按当前仓库分页查询拣货任务列表。支持顶层分页参数 `page_no`/`page_size`(兼容 `pagination` 对象与 `current/size`),支持 `status` 单值或数组;兼容历史 `where` 结构,顶层参数优先。默认按 create_time desc 排序。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "warehouse_id", "type": "number", "required": true, "source": "body", "description": "仓库ID(必填)" }, { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page / pageSize,兼容 current / size(兼容旧客户端)" }, { "name": "page_no", "type": "number", "required": false, "source": "body", "description": "页码(优先于 pagination.page/current)" }, { "name": "page_size", "type": "number", "required": false, "source": "body", "description": "每页大小(优先于 pagination.pageSize/size)" }, { "name": "status", "type": "array", "required": false, "source": "body", "description": "拣货任务状态过滤;建议传数组,也兼容单值或逗号分隔字符串,兼容 where.status;顶层参数优先" }, { "name": "review_status", "type": "number", "required": false, "source": "body", "description": "复核状态过滤" }, { "name": "pick_mode", "type": "number", "required": false, "source": "body", "description": "拣货模式(如批量/逐单等)" }, { "name": "source", "type": "string", "required": false, "source": "body", "description": "任务来源标识(业务端语义)" }, { "name": "pick_user_id", "type": "number", "required": false, "source": "body", "description": "拣货执行人ID(兼容旧字段)" }, { "name": "pick_user_name", "type": "string", "required": false, "source": "body", "description": "拣货人姓名;支持模糊匹配,也支持操作符对象 { operator: 'like'|'notlike'|'eq', value }(默认 like)" }, { "name": "review_user_id", "type": "number", "required": false, "source": "body", "description": "复核人ID" }, { "name": "review_user_name", "type": "string", "required": false, "source": "body", "description": "复核人姓名;支持模糊匹配,也支持操作符对象 { operator: 'like'|'notlike'|'eq', value }(默认 like)" }, { "name": "claim_operator", "type": "string", "required": false, "source": "body", "description": "领料人姓名;支持模糊匹配,也支持操作符对象 { operator: 'like'|'notlike'|'eq', value }(默认 like)" }, { "name": "task_no", "type": "string", "required": false, "source": "body", "description": "任务编号(支持模糊匹配)" }, { "name": "wave_no", "type": "string", "required": false, "source": "body", "description": "波次号(模糊匹配任务主表 batch_no_array,如 \"B2026081500040\");也支持操作符对象 { operator: 'like'|'notlike'|'eq', value }(默认 like)" }, { "name": "cart_id", "type": "number", "required": false, "source": "body", "description": "拣货车/作业车ID" }, { "name": "cart_code", "type": "string", "required": false, "source": "body", "description": "拣货车编码;匹配拣货任务主表绑定快照 current_cart_code_snapshot,支持模糊匹配,也支持操作符对象 { operator: 'like'|'notlike'|'eq', value }(默认 like,如 { operator: 'eq', value: 'car08' })" }, { "name": "keyword", "type": "string", "required": false, "source": "body", "description": "关键字搜索:支持 task_no / batch_no / current_cart_code_snapshot 等字段的模糊匹配" }, { "name": "start_time_start", "type": "string", "required": false, "source": "body", "description": "开始时间(ISO 字符串),与 start_time_end 一起用于时间范围过滤" }, { "name": "start_time_end", "type": "string", "required": false, "source": "body", "description": "结束时间(ISO 字符串),与 start_time_start 一起用于时间范围过滤" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "兼容历史 where 结构(可包含 status 等字段);当存在顶层同名参数时,顶层参数优先" }, { "name": "strategy_id", "type": "number", "required": false, "source": "body", "description": "策略ID(当前主表未存,该接口会忽略此过滤,建议勿使用)" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "拣货任务列表(数组),每项字段如下", "children": [ { "name": "task_id", "type": "number", "description": "任务ID" }, { "name": "task_no", "type": "string", "description": "任务编号" }, { "name": "status", "type": "number", "description": "任务状态" }, { "name": "source", "type": "string", "description": "来源" }, { "name": "pick_mode", "type": "number", "description": "拣货模式" }, { "name": "wave_count", "type": "number", "description": "关联波次数" }, { "name": "order_count", "type": "number", "description": "订单数量" }, { "name": "box_count", "type": "number", "description": "箱数" }, { "name": "operator_id", "type": "number", "description": "操作人ID(兼容旧字段 pick_user_id)" }, { "name": "operator_name", "type": "string", "description": "操作人名称(兼容旧字段 pick_user_name)" }, { "name": "pick_user_id", "type": "number", "description": "拣货人ID(兼容字段,旧客户端可能使用)" }, { "name": "pick_user_name", "type": "string", "description": "拣货人名称(兼容字段,旧客户端可能使用)" }, { "name": "cart_name", "type": "string", "description": "拣货车名称(通过 current_cart_id 关联 wms_pick_cart 表获取,未绑定拣货车时为空字符串)" }, { "name": "claim_operator_id", "type": "number", "description": "领料人工号ID(任务创建时从订单冗余,未领料时为 null)" }, { "name": "claim_operator", "type": "string", "description": "领料人姓名(任务创建时从订单冗余,未领料时为 null)" }, { "name": "start_at", "type": "string", "description": "开始时间(ISO 字符串,兼容 start_time)" }, { "name": "finish_at", "type": "string", "description": "完成时间(ISO 字符串,兼容 finish_time)" }, { "name": "start_time", "type": "string", "description": "开始时间(ISO 字符串,兼容字段)" }, { "name": "finish_time", "type": "string", "description": "完成时间(ISO 字符串,兼容字段)" }, { "name": "created_at", "type": "string", "description": "创建时间(ISO 字符串,兼容 create_time)" }, { "name": "create_time", "type": "string", "description": "创建时间(ISO 字符串,兼容字段)" }, { "name": "wave_list", "type": "array", "description": "关联波次列表(通过 wms_wave_pick_task_wave 关联查询,按 id 升序排列)", "children": [ { "name": "wave_id", "type": "number", "description": "波次ID" }, { "name": "wave_no", "type": "string", "description": "波次号" }, { "name": "box_no", "type": "number", "description": "框号" }, { "name": "status", "type": "number", "description": "波次关联状态:0-待拣 1-已拣 2-异常" }, { "name": "bind_time", "type": "string", "description": "绑定时间(ISO 字符串)" }, { "name": "pick_time", "type": "string", "description": "拣货完成时间(ISO 字符串)" } ] } ] }, { "name": "total", "type": "number", "required": true, "description": "总记录数" }, { "name": "page", "type": "number", "required": true, "description": "当前页码" }, { "name": "page_size", "type": "number", "required": true, "description": "每页大小" } ], "errors": [ { "code": "400", "message": "缺少仓库上下文或参数格式错误" }, { "code": "500", "message": "查询失败" } ] }, { "method": "order.wave.wavePickTaskCancel", "description": "取消拣货任务(批量)。可取消的状态:0=待开始、1=拣货中、2=待复核(拣货完成)、3=已完成,状态9(已取消)或其他状态不允许取消。同时释放关联波次(物理删除波次记录,订单回池)、解绑拣货车、写操作日志。对于status=2或3的任务,取消时会自动回退订单拣货状态:wms_wave_pick_task_order.pick_status(1→0)、order_delivery.pick_status(fin→padding)。入参仅支持 task_ids(数组,必填),不再支持单个 task_id。操作人与仓库从请求上下文获取(例如当前登录用户上下文 ctx.user),若上下文缺失接口将返回错误。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_ids", "type": "array", "required": true, "source": "body", "description": "任务ID数组,例如 [123,124];仅支持批量处理,不再支持单个 task_id。" } ], "response": [ { "name": "cancelled_count", "type": "number", "required": false, "description": "成功取消的任务数量" }, { "name": "task_ids", "type": "array", "required": false, "description": "处理的任务ID数组(若后端返回)" }, { "name": "task_nos", "type": "array", "required": false, "description": "处理的任务编号数组(若后端返回)" }, { "name": "task_id", "type": "number", "required": false, "description": "任务ID(历史兼容,若后端仍返回)" }, { "name": "task_no", "type": "string", "required": false, "description": "任务编号(历史兼容,若后端仍返回)" } ], "errors": [ { "code": "400", "message": "任务状态不允许取消(仅允许status=0/1/2/3)或入参缺失" }, { "code": "403", "message": "仅允许取消本人创建的任务(wavePickTaskCancelSelf 接口)" }, { "code": "404", "message": "任务不存在" }, { "code": "500", "message": "内部错误或事务回滚失败" } ] }, { "method": "order.wave.wavePickTaskCancelSelf", "description": "取消单个拣货任务(仅允许取消当前操作人本人创建的任务;仅支持单个 task_id,明确不支持 task_ids)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id", "type": "number", "required": true, "source": "body", "description": "要取消的单个任务 ID(仅支持单个,不支持 task_ids)" } ], "response": [ { "name": "cancelled_count", "type": "number", "description": "成功取消的任务数量(0 或 1)" }, { "name": "task_id", "type": "number", "description": "被处理的任务ID" }, { "name": "task_no", "type": "string", "description": "被处理的任务编号(若后端返回)" } ], "errors": [ { "code": "400", "description": "参数不合法(task_id 缺失或同时传入 task_ids)" }, { "code": "400", "description": "仅允许取消本人创建任务" }, { "code": "500", "description": "取消失败" } ] }, { "method": "order.wave.batchCancel", "description": "提交批量解除波次异步任务。该接口为异步任务提交接口,立即返回 task_id,后端异步按当前仓库 + wave_ids 拉取待处理波次并执行解除操作;可通过 order.wave.batchCancelTaskProgress 查询进度与结果。新增业务校验:波次内存在拣货中或拣货完成(pick_status 为 padding/fin)的订单,或波次状态已进入拣货及后续环节(wms_wave_batch.wave_status >= 3)时,禁止取消波次并返回 400;异步任务执行时命中上述条件的波次将被跳过,跳过明细见任务进度 result 的 skipped_waves。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "wave_ids / waveIds / ids", "type": "array|string|number", "required": true, "source": "body", "description": "波次ID列表;支持数组、逗号分隔字符串或单个ID" }, { "name": "task_id / taskId", "type": "string", "required": false, "source": "body", "description": "可选外部任务ID,用于幂等提交" } ], "response": [ { "name": "status", "type": "string", "required": true, "description": "提交状态,固定 success" }, { "name": "task_id", "type": "string", "required": true, "description": "任务 ID(用于查询任务进度)" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "当前仓库ID" }, { "name": "accepted_at", "type": "string", "required": true, "description": "任务受理时间(ISO8601)" }, { "name": "message", "type": "string", "required": false, "description": "受理提示信息" } ], "errors": [ { "code": "400", "message": "未识别到当前仓库上下文" }, { "code": "400", "message": "wave_ids 参数不能为空或格式错误" }, { "code": "400", "message": "波次内存在已拣货完成或拣货中的订单,禁止取消波次(订单 pick_status 为 padding/fin;响应附带命中波次 wave_ids 与订单 order_ids)" }, { "code": "400", "message": "波次已进入拣货或后续环节,禁止取消波次(wms_wave_batch.wave_status >= 3;响应附带命中波次 wave_ids)" }, { "code": "500", "message": "任务提交失败或内部错误" } ] }, { "method": "order.wave.batchCancelTaskProgress", "description": "查询批量解除波次任务进度:按 task_id 查询任务状态与统计信息;兼容 taskId 参数名。响应包含 state、progress_percent、processed_wave_count、total_wave_count;当 state 为 success/failed 时返回额外字段说明。成功/失败终态的任务结果 result 中包含 skipped_wave_ids、skipped_wave_count、skipped_waves:因波次内存在已拣货完成或拣货中的订单(pick_status 为 padding/fin)或波次已进入拣货及后续环节(wave_status >= 3)被跳过取消的波次明细。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id / taskId", "type": "string", "required": true, "source": "body|query", "description": "任务 ID(后端生成或提交时传入)" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID" }, { "name": "state", "type": "string", "required": true, "description": "任务状态枚举:submitted(已受理)/ running(进行中)/ success(成功)/ failed(失败)/ not_found(未找到)" }, { "name": "progress_percent", "type": "number", "required": false, "description": "进度百分比(0-100)" }, { "name": "processed_wave_count", "type": "number", "required": false, "description": "已处理的波次数量" }, { "name": "total_wave_count", "type": "number", "required": false, "description": "总波次数量" }, { "name": "duration_ms", "type": "number", "required": false, "description": "任务耗时(毫秒)" }, { "name": "error_message", "type": "string", "required": false, "description": "失败时的错误信息(仅在 state=failed 时返回)" }, { "name": "error_code", "type": "string", "required": false, "description": "失败时的错误码(仅在 state=failed 时返回)" }, { "name": "result", "type": "object", "required": false, "description": "成功时返回的汇总结果(仅在 state=success 时返回),包含 ids、affected_wave_ids、affected_order_count、canceled_wave_count、skipped_wave_ids、skipped_wave_count、skipped_waves、duration_ms 等字段" }, { "name": "skipped_wave_ids", "type": "array", "required": false, "description": "因业务校验被跳过取消的波次 ID 列表(成功/失败终态的任务结果 result 中返回,数组元素为 number)" }, { "name": "skipped_wave_count", "type": "number", "required": false, "description": "被跳过取消的波次数量(等于 skipped_wave_ids 长度)" }, { "name": "skipped_waves", "type": "array", "required": false, "description": "被跳过取消的波次明细(成功/失败终态的任务结果 result 中返回)。跳过原因两类:波次已进入拣货及后续环节(wave_status >= 3)、波次内存在已拣货完成或拣货中的订单(pick_status 为 padding/fin)", "children": [ { "name": "wave_id", "type": "number", "description": "被跳过取消的波次 ID" }, { "name": "wave_no", "type": "string", "description": "波次号" }, { "name": "reason", "type": "string", "description": "跳过原因枚举:wave_status_blocked(波次已进入拣货或后续环节,wave_status >= 3)/ picked_orders_exist(波次内存在已拣货完成或拣货中的订单)" }, { "name": "wave_status", "type": "number", "description": "波次当前状态(仅 reason=wave_status_blocked 时返回)" }, { "name": "picked_order_count", "type": "number", "description": "命中已拣货完成或拣货中状态的订单数量(仅 reason=picked_orders_exist 时返回)" } ] } ], "errors": [ { "code": "400", "message": "task_id 参数不能为空" }, { "code": "500", "message": "查询失败或内部错误" } ] }, { "method": "order.wave.batchAllocateExpress", "description": "提交批次分配快递号任务。该接口为异步任务提交接口,立即返回 task_id,后端异步按当前仓库 + wave_ids 拉取待处理订单并提交到快递号分配流水线。已锁定订单(lock_status 非 none)与拦截订单在任务中被跳过、不参与分配,跳过明细见任务进度(batchAllocateExpressTaskProgress)的 skipped_locked_order_ids。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "wave_ids / waveIds / ids", "type": "array|string|number", "required": true, "source": "body", "description": "波次ID列表;支持数组、逗号分隔字符串或单个ID" }, { "name": "task_id / taskId", "type": "string", "required": false, "source": "body", "description": "可选外部任务ID,用于幂等提交" } ], "response": [ { "name": "status", "type": "string", "required": true, "description": "提交状态,固定 success" }, { "name": "task_id", "type": "string", "required": true, "description": "任务 ID(用于查询任务进度)" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "当前仓库ID" }, { "name": "accepted_at", "type": "string", "required": true, "description": "任务受理时间(ISO8601)" }, { "name": "message", "type": "string", "required": false, "description": "受理提示信息" } ], "errors": [ { "code": "400", "message": "未识别到当前仓库上下文" }, { "code": "400", "message": "wave_ids 参数不能为空或格式错误" }, { "code": "500", "message": "任务提交失败或内部错误" } ] }, { "method": "order.wave.batchAllocateExpressTaskProgress", "description": "查询批次分配快递号任务进度:按 task_id 查询任务状态与统计信息;兼容 taskId 参数名。已锁定订单(lock_status 非 none)被跳过,任务进度与 result 中包含 skipped_locked_order_ids(因已锁定被跳过的订单 ID)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id / taskId", "type": "string", "required": true, "source": "body|query", "description": "任务 ID(后端生成或提交时传入)" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID" }, { "name": "state", "type": "string", "required": true, "description": "任务状态枚举:submitted(已受理)/ running(进行中)/ success(成功)/ failed(失败)/ not_found(未找到)" }, { "name": "warehouse_id", "type": "number", "required": false, "description": "任务关联仓库ID" }, { "name": "total_wave_count", "type": "number", "required": false, "description": "波次数量" }, { "name": "total_order_count", "type": "number", "required": false, "description": "参与分配的订单数量" }, { "name": "processed_order_count", "type": "number", "required": false, "description": "已处理订单数量" }, { "name": "success_order_count", "type": "number", "required": false, "description": "成功提交分配的订单数量" }, { "name": "failed_order_count", "type": "number", "required": false, "description": "提交分配失败的订单数量" }, { "name": "skipped_locked_order_ids", "type": "array", "required": false, "description": "因已锁定(lock_status 非 none)被跳过、未参与快递号分配的订单 ID 列表(任务进度与 result 中均返回)" }, { "name": "progress_percent", "type": "number", "required": false, "description": "进度百分比(0-100)" }, { "name": "duration_ms", "type": "number", "required": false, "description": "任务耗时(毫秒)" }, { "name": "error_message", "type": "string", "required": false, "description": "失败时的错误信息" }, { "name": "error_code", "type": "string", "required": false, "description": "失败时的错误码" } ], "errors": [ { "code": "400", "message": "task_id 参数不能为空" }, { "code": "500", "message": "查询失败或内部错误" } ] }, { "method": "order.wave.batchRemoveExceptionOrders", "description": "提交批次移除异常订单任务。该接口为异步任务提交接口,立即返回 task_id,后端异步按当前仓库 + wave_ids 拉取异常订单并移出波次。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "wave_ids / waveIds / ids", "type": "array|string|number", "required": true, "source": "body", "description": "波次ID列表;支持数组、逗号分隔字符串或单个ID" }, { "name": "task_id / taskId", "type": "string", "required": false, "source": "body", "description": "可选外部任务ID,用于幂等提交" } ], "response": [ { "name": "status", "type": "string", "required": true, "description": "提交状态,固定 success" }, { "name": "task_id", "type": "string", "required": true, "description": "任务 ID(用于查询任务进度)" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "当前仓库ID" }, { "name": "accepted_at", "type": "string", "required": true, "description": "任务受理时间(ISO8601)" }, { "name": "message", "type": "string", "required": false, "description": "受理提示信息" } ], "errors": [ { "code": "400", "description": "未识别到当前仓库上下文" }, { "code": "400", "description": "wave_ids 参数不能为空或格式错误" }, { "code": "500", "description": "任务提交失败或内部错误" } ] }, { "method": "order.wave.batchRemoveExceptionOrdersTaskProgress", "description": "查询批次移除异常订单任务进度:按 task_id 查询任务状态与统计信息;兼容 taskId 参数名。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id / taskId", "type": "string", "required": true, "source": "body|query", "description": "任务 ID(后端生成或提交时传入)" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID" }, { "name": "state", "type": "string", "required": true, "description": "任务状态枚举:submitted(已受理)/ running(进行中)/ success(成功)/ failed(失败)/ not_found(未找到)" }, { "name": "warehouse_id", "type": "number", "required": false, "description": "任务关联仓库ID" }, { "name": "total_wave_count", "type": "number", "required": false, "description": "波次数量" }, { "name": "total_order_count", "type": "number", "required": false, "description": "参与处理的订单数量" }, { "name": "processed_order_count", "type": "number", "required": false, "description": "已处理订单数量" }, { "name": "removed_order_count", "type": "number", "required": false, "description": "已成功移出波次的订单数量" }, { "name": "failed_order_count", "type": "number", "required": false, "description": "处理失败的订单数量" }, { "name": "progress_percent", "type": "number", "required": false, "description": "进度百分比(0-100)" }, { "name": "duration_ms", "type": "number", "required": false, "description": "任务耗时(毫秒)" }, { "name": "error_message", "type": "string", "required": false, "description": "失败时的错误信息" }, { "name": "error_code", "type": "string", "required": false, "description": "失败时的错误码" } ], "errors": [ { "code": "400", "description": "task_id 参数不能为空" }, { "code": "500", "description": "查询失败或内部错误" } ] }, { "method": "order.wave.batchAllocateStorage", "description": "提交批次分配储位任务。该接口为异步任务提交接口,立即返回 task_id,后端异步按当前仓库 + wave_ids 拉取待处理订单并提交到储位分配流水线。已锁定订单(lock_status 非 none)在任务中被直接跳过、不参与储位分配。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "wave_ids / waveIds / ids", "type": "array|string|number", "required": true, "source": "body", "description": "波次ID列表;支持数组、逗号分隔字符串或单个ID" }, { "name": "task_id / taskId", "type": "string", "required": false, "source": "body", "description": "可选外部任务ID,用于幂等提交" } ], "response": [ { "name": "status", "type": "string", "required": true, "description": "提交状态,固定 success" }, { "name": "task_id", "type": "string", "required": true, "description": "任务 ID(用于查询任务进度)" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "当前仓库ID" }, { "name": "accepted_at", "type": "string", "required": true, "description": "任务受理时间(ISO8601)" }, { "name": "message", "type": "string", "required": false, "description": "受理提示信息" } ], "errors": [ { "code": "400", "message": "未识别到当前仓库上下文" }, { "code": "400", "message": "wave_ids 参数不能为空或格式错误" }, { "code": "500", "message": "任务提交失败或内部错误" } ] }, { "method": "order.wave.batchAllocateStorageTaskProgress", "description": "查询批次分配储位任务进度:按 task_id 查询任务状态与统计信息;兼容 taskId 参数名。已锁定订单(lock_status 非 none)被直接跳过,不计入 total_order_count 等统计。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id / taskId", "type": "string", "required": true, "source": "body|query", "description": "任务 ID(后端生成或提交时传入)" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID" }, { "name": "state", "type": "string", "required": true, "description": "任务状态枚举:submitted(已受理)/ running(进行中)/ success(成功)/ failed(失败)/ not_found(未找到)" }, { "name": "warehouse_id", "type": "number", "required": false, "description": "任务关联仓库ID" }, { "name": "total_wave_count", "type": "number", "required": false, "description": "波次数量" }, { "name": "total_order_count", "type": "number", "required": false, "description": "参与分配的订单数量" }, { "name": "processed_order_count", "type": "number", "required": false, "description": "已处理订单数量" }, { "name": "success_order_count", "type": "number", "required": false, "description": "成功提交分配的订单数量" }, { "name": "failed_order_count", "type": "number", "required": false, "description": "提交分配失败的订单数量" }, { "name": "progress_percent", "type": "number", "required": false, "description": "进度百分比(0-100)" }, { "name": "duration_ms", "type": "number", "required": false, "description": "任务耗时(毫秒)" }, { "name": "error_message", "type": "string", "required": false, "description": "失败时的错误信息" }, { "name": "error_code", "type": "string", "required": false, "description": "失败时的错误码" } ], "errors": [ { "code": "400", "message": "task_id 参数不能为空" }, { "code": "500", "message": "查询失败或内部错误" } ] }, { "method": "order.wave.groupFetch", "description": "抓取团购接口(异步任务提交)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "structure_list", "type": "array", "required": true, "source": "body", "description": "结构请求数组;每项必须包含 item_detail_machine(由 buildMachineStructureToken 生成的结构标识),可选 quantity(未传入时使用仓库默认或全局默认)" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID(后端生成的唯一标识,用于查询任务状态或结果)" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "生效的仓库 ID" }, { "name": "structure_count", "type": "number", "required": true, "description": "本次入参的结构数量(structure_list 长度)" }, { "name": "default_quantity", "type": "number", "required": true, "description": "仓库默认抓取数量或全局默认值" }, { "name": "fetch_mode", "type": "string", "required": false, "description": "抓取模式,值为 'group'(团购)或 'single'(散单)" }, { "name": "message", "type": "string", "required": false, "description": "受理信息提示,通常为 '任务已提交,后端异步处理中' 或失败/错误说明" } ], "errors": [ { "code": 400, "message": "structure_list 必须是非空数组或结构项参数不合法" }, { "code": 500, "message": "任务提交失败或内部错误" } ] }, { "method": "order.wave.singleFetch", "description": "抓取散单接口(异步任务提交)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "structure_list", "type": "array", "required": true, "source": "body", "description": "结构请求数组;每项必须包含 item_detail_machine(由 buildMachineStructureToken 生成的结构标识)并包含必填字段 max_fetch_quantity(最大抓取上限,订单数,正整数);可选 quantity(未传入时使用仓库默认或全局默认)" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID(后端生成的唯一标识,用于查询任务状态或结果)" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "生效的仓库 ID" }, { "name": "structure_count", "type": "number", "required": true, "description": "本次入参的结构数量(structure_list 长度)" }, { "name": "default_quantity", "type": "number", "required": true, "description": "仓库默认抓取数量或全局默认值" }, { "name": "fetch_mode", "type": "string", "required": false, "description": "抓取模式,值为 'group'(团购)或 'single'(散单)" }, { "name": "max_fetch_quantity", "type": "number", "required": false, "description": "提交时生效的最大抓取上限(订单数,正整数)" }, { "name": "message", "type": "string", "required": false, "description": "受理信息提示,通常为 '任务已提交,后端异步处理中' 或失败/错误说明" } ], "errors": [ { "code": 400, "message": "structure_list 必须是非空数组或结构项参数不合法;max_fetch_quantity 必填且为正整数" }, { "code": 500, "message": "任务提交失败或内部错误" } ] }, { "method": "order.wave.fetch", "description": "兼容别名(等同 groupFetch)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "structure_list", "type": "array", "required": true, "source": "body", "description": "结构请求数组;每项必须包含 item_detail_machine(由 buildMachineStructureToken 生成的结构标识),可选 quantity(未传入时使用仓库默认或全局默认)" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID(后端生成的唯一标识,用于查询任务状态或结果)" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "生效的仓库 ID" }, { "name": "structure_count", "type": "number", "required": true, "description": "本次入参的结构数量(structure_list 长度)" }, { "name": "default_quantity", "type": "number", "required": true, "description": "仓库默认抓取数量或全局默认值" }, { "name": "fetch_mode", "type": "string", "required": false, "description": "抓取模式,值为 'group'(团购)或 'single'(散单)" }, { "name": "message", "type": "string", "required": false, "description": "受理信息提示,通常为 '任务已提交,后端异步处理中' 或失败/错误说明" } ], "errors": [ { "code": 400, "message": "structure_list 必须是非空数组或结构项参数不合法" }, { "code": 500, "message": "任务提交失败或内部错误" } ] }, { "method": "order.wave.fetchTaskProgress", "description": "查询波次抓取任务进度:按 task_id 查询任务状态与进度;兼容 taskId 参数名。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id / taskId", "type": "string", "required": true, "source": "body|query", "description": "任务 ID(后端生成的唯一标识),兼容旧参数名 taskId,可从 order.wave.fetch 的返回值中获取" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID" }, { "name": "status", "type": "string", "required": true, "description": "任务状态枚举:submitted(已受理)/ running(进行中)/ success(成功)/ failed(失败)/ not_found(未找到)" }, { "name": "warehouse_id", "type": "number", "required": false, "description": "生效的仓库 ID(若任务关联仓库时返回)" }, { "name": "structure_count", "type": "number", "required": false, "description": "本次任务的结构数量(structure_list 长度)" }, { "name": "finished_structure_count", "type": "number", "required": false, "description": "已完成抓取的结构数量" }, { "name": "progress_percent", "type": "number", "required": false, "description": "进度百分比(0-100,可能为小数)" }, { "name": "total_fetched_quantity", "type": "number", "required": false, "description": "已抓取的总件数" }, { "name": "duration_ms", "type": "number", "required": false, "description": "任务已运行时长,毫秒级" }, { "name": "error", "type": "string", "required": false, "description": "错误信息,仅当 status=failed 时返回" }, { "name": "fetch_mode", "type": "string", "required": false, "description": "抓取模式,值为 'group'(团购)或 'single'(散单);single 模式时可能返回下列额外字段" }, { "name": "max_fetch_quantity", "type": "number", "required": false, "description": "当 fetch_mode=single 时返回的最大抓取上限(订单数,正整数)" }, { "name": "limit_reached", "type": "boolean", "required": false, "description": "当 fetch_mode=single 时指示是否已达到 max_fetch_quantity 限制" }, { "name": "stop_reason", "type": "string", "required": false, "description": "任务停止原因(如达到上限、人工停止或其他失败原因)" }, { "name": "update_time", "type": "string", "required": false, "description": "最近一次状态更新时间,ISO8601 字符串" }, { "name": "message", "type": "string", "required": false, "description": "额外提示信息" } ], "errors": [ { "code": 400, "message": "task_id 为空或格式不合法" }, { "code": 500, "message": "内部错误" } ] }, { "method": "order.wave.batchAutoGrouping", "description": "批量将波次状态修改为 0(自动加团中),仅作用当前登录仓库命中的波次。限制条件:\n- 跳过已打印及之后状态的波次(wave_status >= 2);\n- 跳过 total_orders >= 仓库配置 max_wave_quantity 的波次。被跳过的波次不会被修改为自动加团中。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "array|string|number", "required": true, "source": "body", "description": "波次ID 列表;支持数组、逗号分隔字符串或单个ID" } ], "response": [ { "name": "ids", "type": "array", "description": "归一化后的请求ID" }, { "name": "affected_wave_ids", "type": "array", "description": "实际命中的波次ID" }, { "name": "updated_wave_count", "type": "number", "description": "实际更新数量" }, { "name": "skipped_wave_ids", "type": "array", "description": "被跳过的波次ID数组(不修改状态)" }, { "name": "skipped_wave_count", "type": "number", "description": "被跳过的波次数量" }, { "name": "skipped_details", "type": "array", "description": "被跳过的波次明细數組,元素包含 wave_id 与 reason,reason 枚举 printed_or_after_printed / reach_max_wave_quantity", "children": [ { "name": "wave_id", "type": "number", "description": "波次 ID" }, { "name": "reason", "type": "string", "description": "跳过原因,枚举: printed_or_after_printed / reach_max_wave_quantity" } ] } ], "errors": [ { "code": "400", "description": "未识别到当前仓库上下文" }, { "code": "400", "description": "ids 参数不能为空或格式错误" }, { "code": "500", "description": "批量修改波次状态失败或内部错误" } ] }, { "method": "order.wave.batchFinishAutoGrouping", "description": "批量结束自动加团,将当前仓库命中且 wave_status=0 的波次改为 1(已就绪)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "array|string|number", "required": true, "source": "body", "description": "波次ID 列表;支持数组、逗号分隔字符串或单个ID" } ], "response": [ { "name": "ids", "type": "array", "description": "归一化后的请求ID" }, { "name": "affected_wave_ids", "type": "array", "description": "实际命中的波次ID" }, { "name": "updated_wave_ids", "type": "array", "description": "实际更新为已就绪的波次ID" }, { "name": "updated_wave_count", "type": "number", "description": "实际更新数量" } ], "errors": [ { "code": "400", "description": "未识别到当前仓库上下文" }, { "code": "400", "description": "ids 参数不能为空或格式错误" }, { "code": "500", "description": "批量结束自动加团失败或内部错误" } ] }, { "method": "order.wave.batchRemoveOrders", "description": "按订单ID批量移出波次;仅处理当前仓库的待处理订单表中非待审核订单(step in [1,2,3])。操作会清空订单的 wave_id/wave_no,并在同一事务内回写 wms_wave_batch 表:重算 total_orders,若波次被清空则将 wave_status 置为 -1。仓库上下文来自当前登录用户(ctx.user.store_id)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids / order_ids / orderIds / order_id / orderId / id", "type": "array|string|number", "required": true, "source": "body", "description": "订单 ID 列表;支持数组、逗号分隔字符串或单个 ID,以上别名均可用(ids、order_ids、orderIds、order_id、orderId、id)" } ], "response": [ { "name": "ids", "type": "array", "required": true, "description": "归一化后的请求 ID 列表" }, { "name": "removed_order_ids", "type": "array", "required": true, "description": "实际被移出波次的订单 ID 列表" }, { "name": "removed_order_count", "type": "number", "required": true, "description": "被移出波次的订单数量" }, { "name": "affected_wave_ids", "type": "array", "required": true, "description": "本次操作涉及的波次 ID 列表" }, { "name": "updated_wave_ids", "type": "array", "required": true, "description": "实际更新了 total_orders 的波次 ID 列表" }, { "name": "emptied_wave_ids", "type": "array", "required": true, "description": "被清空且已置为 wave_status=-1 的波次 ID 列表" } ], "errors": [ { "code": "400", "message": "缺少仓库上下文(用户登录信息无 store_id)或 ids 参数为空/格式错误" }, { "code": "500", "message": "内部错误" } ] }, { "method": "order.wave.fetchableOrderCount", "description": "统计当前仓库团购可抓取订单数。口径与 order.wave.groupOrderFetchList 完全一致(同一候选条件 + items_hash 粗分组 + 团购阈值过滤),但不分页、不查订单明细,仅返回达到团购阈值分组的数量与组内订单数合计。注意与 groupOrderFetchList 的口径差异:其 pagination.total 是分组数,本方法 order_count 是命中分组的订单数合计。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "distinguish_express", "type": "boolean", "required": false, "source": "body", "description": "是否区分快递(影响分组粒度):开启后按「结构(items_hash) + 快递编码」分组,关闭(默认)仅按结构分组。" }, { "name": "store_id", "type": "number", "required": false, "source": "body", "description": "货主ID(仅作为筛选条件,需为非负整数)。" }, { "name": "same_order_quantity", "type": "number", "required": false, "source": "body", "description": "最小同组订单数量阈值(>=)。显式传入有效非负整数且大于 0 时按传入值使用;未传入或为 0 时使用仓库配置 min_group_order_fetch_quantity(默认 13)。" }, { "name": "shop_name", "type": "string", "required": false, "source": "body", "description": "店铺名称(shop_nick 模糊匹配)。" }, { "name": "stock_query", "type": "string", "required": false, "source": "body", "description": "商品模糊筛选:经 stock_warehouse / stock_barcodes → order_items 限定候选订单范围;未匹配到任何商品时直接返回 group_count=0 / order_count=0。" } ], "response": [ { "name": "group_count", "type": "number", "required": true, "description": "达到团购阈值的分组数(同组订单数 >= same_order_quantity)。" }, { "name": "order_count", "type": "number", "required": true, "description": "可抓取订单数合计(命中分组内订单数之和;不含未达阈值分组的订单,也不含 items_hash/items 均为空无法分组的订单)。" }, { "name": "same_order_quantity", "type": "number", "required": true, "description": "本次统计实际使用的团购阈值(入参值或仓库配置值)。" }, { "name": "raw_order_count", "type": "number", "required": true, "description": "参与分组统计的候选订单总数(过滤团购阈值之前,便于核对口径)。" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "当前仓库ID(取自登录上下文 ctx.user.store_id)。" }, { "name": "distinguish_express", "type": "boolean", "required": true, "description": "是否区分快递(回显本次分组粒度)。" } ], "errors": [ { "code": "400", "message": "未识别到当前仓库上下文" }, { "code": "400", "message": "参数格式错误(如 store_id / same_order_quantity 非非负整数)" }, { "code": "500", "message": "查询失败" } ] } ] }, { "groupName": "订单待出库模块", "module": "order.outboundOrder", "list": [ { "method": "order.outboundOrder.list", "description": "待出库订单列表,默认筛选 outbound_status in [fin,padding] 且 step in [4,9]。;列表运单号回填强制同仓校验:wms_order_express 按「订单ID + 订单所属仓库ID」隔离读取,禁止仅凭订单ID跨仓串读运单号", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page / pageSize" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "统一 where 条件对象;禁止传入 warehouse_id / warehouseId。create_channel(订单来源渠道筛选,按订单表 create_channel 列过滤;枚举:MANUAL=手工单、API=接口、QM=奇门、STOCKOUT=出库转单)。支持简写与标准结构:{\"create_channel\":\"MANUAL\"} 单值精确、{\"create_channel\":[\"QM\",\"API\"]} 裸数组按 in 多选、{\"create_channel\":{\"operator\":\"in\",\"value\":[\"QM\",\"API\"]}} 标准结构多选、{\"create_channel\":{\"operator\":\"ne\",\"value\":\"MANUAL\"}} 排除指定渠道。注意:列表响应中的 create_channel 已格式化为中文标签(手工单/接口/奇门/出库转单),查询条件请传英文枚举值。" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数,支持 sortField / sortOrder" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "订单列表(raw 行数据,字段字典见 docs/order-workbench-list-api.md 中的“订单列表 raw 字段字典”章节);本次新增 wave_index(波次内序号,联查 wms_order_wave_index,无记录时为 0)。" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息" }, { "name": "recheck_status", "type": "string", "required": false, "description": "复核状态:none=未复核,fin=已复核" } ], "errors": [ { "code": "400", "message": "参数格式错误或缺少仓库上下文" }, { "code": "500", "message": "查询失败" } ] }, { "method": "order.outboundOrder.detail", "description": "查询单个订单详情,返回订单头、商品明细和运单信息", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids / id / order_id / orderId", "type": "array|string|number", "required": true, "source": "body", "description": "订单ID;支持 ids 数组、逗号分隔字符串或单个 id/order_id,至少提供一项" }, { "name": "tableType / tablePosition / type / moduleName", "type": "string", "required": false, "source": "body", "description": "可选,指定订单表类型,支持 current/history/dispatch/outsourced/order/revieworder/pendingorder 等" } ], "response": [ { "name": "order", "type": "object", "description": "订单头对象(raw 行数据)" }, { "name": "detail", "type": "object", "description": "等同于 order" }, { "name": "orderItems / items", "type": "array", "description": "商品明细数组" }, { "name": "expresses", "type": "array", "description": "运单信息数组" }, { "name": "waybill_codes", "type": "array", "description": "去重后的运单号字符串数组" } ], "errors": [ { "code": "400", "description": "订单ID 为空或格式错误" }, { "code": "404", "description": "订单不存在或不属于当前仓库" }, { "code": "500", "description": "内部错误" } ] }, { "method": "order.outboundOrder.manualOutboundOrder", "description": "待出库模块的手动出库入口,行为与 order.manualOutboundOrder 一致。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "warehouseId", "type": "number", "required": false, "source": "body", "description": "单仓库ID,兼容 warehouse_id" }, { "name": "warehouseIds", "type": "array", "required": false, "source": "body", "description": "仓库ID 数组" }, { "name": "queryTimeoutMs", "type": "number", "required": false, "source": "body", "description": "查询超时时间(毫秒)" }, { "name": "executionTimeoutMs", "type": "number", "required": false, "source": "body", "description": "执行超时时间(毫秒)" } ], "response": [ { "name": "warehouseIds", "type": "array", "required": true, "description": "参与迁移的仓库ID列表" }, { "name": "batchSize", "type": "number", "required": true, "description": "单批处理上限,当前固定为 1000" }, { "name": "outboundStatuses", "type": "array", "required": true, "description": "本次迁移匹配的出库状态" }, { "name": "totalSelected", "type": "number", "required": true, "description": "命中的源订单数量" }, { "name": "totalCreated", "type": "number", "required": true, "description": "实际创建到配送表的订单数量" }, { "name": "totalSkipped", "type": "number", "required": true, "description": "本次跳过的源订单数量" }, { "name": "totalTimeout", "type": "number", "required": true, "description": "被标记为出库超时的订单数量" }, { "name": "results", "type": "array", "required": true, "description": "按仓库维度返回的批次结果数组,元素包含 selectedCount、createdCount、skippedCount、timeoutCount、retryableFailure 等字段" } ], "errors": [ { "code": "400", "description": "仓库ID为空或请求参数格式错误" }, { "code": "500", "description": "迁移失败或数据库错误" } ] } ] }, { "groupName": "订单异常模块", "module": "order.expectionOrder", "list": [ { "method": "order.expectionOrder.list", "description": "待处理异常订单列表,默认仅查询 step=3 的订单。;列表运单号回填强制同仓校验:wms_order_express 按「订单ID + 订单所属仓库ID」隔离读取,禁止仅凭订单ID跨仓串读运单号", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page / pageSize" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "统一 where 条件对象;禁止传入 warehouse_id / warehouseId。create_channel(订单来源渠道筛选,按订单表 create_channel 列过滤;枚举:MANUAL=手工单、API=接口、QM=奇门、STOCKOUT=出库转单)。支持简写与标准结构:{\"create_channel\":\"MANUAL\"} 单值精确、{\"create_channel\":[\"QM\",\"API\"]} 裸数组按 in 多选、{\"create_channel\":{\"operator\":\"in\",\"value\":[\"QM\",\"API\"]}} 标准结构多选、{\"create_channel\":{\"operator\":\"ne\",\"value\":\"MANUAL\"}} 排除指定渠道。注意:列表响应中的 create_channel 已格式化为中文标签(手工单/接口/奇门/出库转单),查询条件请传英文枚举值。" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数,支持 sortField / sortOrder" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "订单列表(raw 行数据,字段字典见 docs/order-workbench-list-api.md 中的“订单列表 raw 字段字典”章节),本次新增 store_remark(货主备注)字段;wave_index(波次内序号,联查 wms_order_wave_index,无记录时为 0)。" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息" } ], "errors": [ { "code": "400", "message": "参数格式错误或缺少仓库上下文" }, { "code": "500", "message": "查询失败" } ] }, { "method": "order.expectionOrder.detail", "description": "查询单个订单详情,返回订单头、商品明细和运单信息", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids / id / order_id / orderId", "type": "array|string|number", "required": true, "source": "body", "description": "订单ID;支持 ids 数组、逗号分隔字符串或单个 id/order_id,至少提供一项" }, { "name": "tableType / tablePosition / type / moduleName", "type": "string", "required": false, "source": "body", "description": "可选,指定订单表类型,支持 current/history/dispatch/outsourced/order/revieworder/pendingorder 等" } ], "response": [ { "name": "order", "type": "object", "description": "订单头对象(raw 行数据)" }, { "name": "detail", "type": "object", "description": "等同于 order" }, { "name": "orderItems / items", "type": "array", "description": "商品明细数组" }, { "name": "expresses", "type": "array", "description": "运单信息数组" }, { "name": "waybill_codes", "type": "array", "description": "去重后的运单号字符串数组" } ], "errors": [ { "code": "400", "description": "订单ID 为空或格式错误" }, { "code": "404", "description": "订单不存在或不属于当前仓库" }, { "code": "500", "description": "内部错误" } ] }, { "method": "order.expectionOrder.resolveException", "description": "将待处理异常订单转回正常待处理状态(step 3 → 2)。只操作当前仓库的当前订单表,且仅对 step=3 的订单生效。", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "number[]", "required": true, "source": "body", "description": "订单ID 正整数数组,不能为空" } ], "response": [ { "name": "updated_count", "type": "number", "required": true, "description": "实际更新行数" }, { "name": "ids", "type": "number[]", "required": true, "description": "本次操作的订单ID 列表" } ], "errors": [ { "code": "400", "message": "ids 为空或格式非法" }, { "code": "500", "message": "更新失败" } ] } ] }, { "groupName": "订单委托外仓模块", "module": "order.entrustOrder", "list": [ { "method": "order.entrustOrder.list", "description": "委托外仓订单列表,使用 outsourced 模型。;列表运单号回填强制同仓校验:wms_order_express 按「订单ID + 订单所属仓库ID」隔离读取,禁止仅凭订单ID跨仓串读运单号", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page / pageSize" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "统一 where 条件对象;禁止传入 warehouse_id / warehouseId。create_channel(订单来源渠道筛选,按订单表 create_channel 列过滤;枚举:MANUAL=手工单、API=接口、QM=奇门、STOCKOUT=出库转单)。支持简写与标准结构:{\"create_channel\":\"MANUAL\"} 单值精确、{\"create_channel\":[\"QM\",\"API\"]} 裸数组按 in 多选、{\"create_channel\":{\"operator\":\"in\",\"value\":[\"QM\",\"API\"]}} 标准结构多选、{\"create_channel\":{\"operator\":\"ne\",\"value\":\"MANUAL\"}} 排除指定渠道。注意:列表响应中的 create_channel 已格式化为中文标签(手工单/接口/奇门/出库转单),查询条件请传英文枚举值。" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数,支持 sortField / sortOrder" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "订单列表(raw 行数据,字段字典见 docs/order-workbench-list-api.md 中的“订单列表 raw 字段字典”章节),本次新增 store_remark(货主备注)字段;wave_index(波次内序号,联查 wms_order_wave_index,无记录时为 0)。" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息" } ], "errors": [ { "code": "400", "message": "参数格式错误或缺少仓库上下文" }, { "code": "500", "message": "查询失败" } ] }, { "method": "order.entrustOrder.detail", "description": "查询单个订单详情,返回订单头、商品明细和运单信息", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids / id / order_id / orderId", "type": "array|string|number", "required": true, "source": "body", "description": "订单ID;支持 ids 数组、逗号分隔字符串或单个 id/order_id,至少提供一项" }, { "name": "tableType / tablePosition / type / moduleName", "type": "string", "required": false, "source": "body", "description": "可选,指定订单表类型,支持 current/history/dispatch/outsourced/order/revieworder/pendingorder 等" } ], "response": [ { "name": "order", "type": "object", "description": "订单头对象(raw 行数据)" }, { "name": "detail", "type": "object", "description": "等同于 order" }, { "name": "orderItems / items", "type": "array", "description": "商品明细数组" }, { "name": "expresses", "type": "array", "description": "运单信息数组" }, { "name": "waybill_codes", "type": "array", "description": "去重后的运单号字符串数组" } ], "errors": [ { "code": "400", "description": "订单ID 为空或格式错误" }, { "code": "404", "description": "订单不存在或不属于当前仓库" }, { "code": "500", "description": "内部错误" } ] } ] }, { "groupName": "订单配送模块", "module": "order.deliveryOrder", "list": [ { "method": "order.deliveryOrder.list", "description": "配送订单列表,使用 dispatch 模型,默认筛选 dispatch_lane=m4。;列表运单号回填强制同仓校验:wms_order_express 按「订单ID + 订单所属仓库ID」隔离读取,禁止仅凭订单ID跨仓串读运单号", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page / pageSize" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "统一 where 条件对象;禁止传入 warehouse_id / warehouseId。create_channel(订单来源渠道筛选,按订单表 create_channel 列过滤;枚举:MANUAL=手工单、API=接口、QM=奇门、STOCKOUT=出库转单)。支持简写与标准结构:{\"create_channel\":\"MANUAL\"} 单值精确、{\"create_channel\":[\"QM\",\"API\"]} 裸数组按 in 多选、{\"create_channel\":{\"operator\":\"in\",\"value\":[\"QM\",\"API\"]}} 标准结构多选、{\"create_channel\":{\"operator\":\"ne\",\"value\":\"MANUAL\"}} 排除指定渠道。注意:列表响应中的 create_channel 已格式化为中文标签(手工单/接口/奇门/出库转单),查询条件请传英文枚举值。" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数,支持 sortField / sortOrder" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "订单列表(raw 行数据,字段字典见 docs/order-workbench-list-api.md 中的“订单列表 raw 字段字典”章节),本次新增 store_remark(货主备注)字段;wave_index(波次内序号,联查 wms_order_wave_index,无记录时为 0)。" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息" }, { "name": "recheck_status", "type": "string", "required": false, "description": "复核状态:none=未复核,fin=已复核" } ], "errors": [ { "code": "400", "message": "参数格式错误或缺少仓库上下文" }, { "code": "500", "message": "查询失败" } ] }, { "method": "order.deliveryOrder.detail", "description": "查询单个订单详情,返回订单头、商品明细和运单信息", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids / id / order_id / orderId", "type": "array|string|number", "required": true, "source": "body", "description": "订单ID;支持 ids 数组、逗号分隔字符串或单个 id/order_id,至少提供一项" }, { "name": "tableType / tablePosition / type / moduleName", "type": "string", "required": false, "source": "body", "description": "可选,指定订单表类型,支持 current/history/dispatch/outsourced/order/revieworder/pendingorder 等" } ], "response": [ { "name": "order", "type": "object", "required": true, "description": "订单头对象(raw 行数据)" }, { "name": "detail", "type": "object", "required": true, "description": "等同于 order" }, { "name": "orderItems / items", "type": "array", "required": true, "description": "商品明细数组" }, { "name": "expresses", "type": "array", "required": true, "description": "运单信息数组,每个元素包含以下字段:waybill_code(运单号,string)、weighing_weight(称重重量,number|null)、sys_logistics_code(系统物流公司编码,string)、sys_logistics_name(系统物流公司名称,string)、logistics_code(实际物流公司编码,string)、logistics_name(实际物流公司名称,string)、logistics_interface_id(物流接口ID,number|null)、business_key(业务标识,string)、created_at(创建时间戳毫秒,number|null)、package_material_id(包材ID,number|null)、package_material_name_snapshot(包材名称快照,string|null)" }, { "name": "waybill_codes", "type": "array", "required": true, "description": "去重后的运单号字符串数组" } ], "errors": [ { "code": "400", "message": "订单ID 为空或格式错误" }, { "code": "404", "message": "订单不存在或不属于当前仓库" }, { "code": "500", "message": "内部错误" } ] }, { "method": "order.deliveryOrder.quickSearch", "description": "订单快速搜索。跨表联合搜索:运单号(wms_order_express,支持完整单号等值、剥离一单多件包裹序号分段后缀(如 -1-1-)后的主体单号等值、主体前缀 LIKE '主体-%' 匹配,不再做部分单号模糊匹配)、发货单号 delivery_order_code / 原始平台订单号 source_order_codes(express 表快照字段,模糊匹配)。返回匹配的订单列表(最多20条),包含关键字段及关联运单号;平台交易单号 pay_no 仅作为结果字段回显,不参与搜索匹配。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "keyword", "type": "string", "required": true, "source": "body", "description": "搜索关键词。运单号按「完整单号等值 + 剥离一单多件分段后缀(如 -1-1-)后的主体单号等值 + 主体前缀 LIKE '主体-%'」匹配(不做部分单号模糊);发货单号 delivery_order_code、原始平台订单号 source_order_codes 为模糊匹配(LIKE '%kw%');平台交易单号 pay_no 仅回显、不参与匹配" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "匹配的订单列表", "children": [ { "name": "order_id", "type": "number", "required": true, "description": "订单ID" }, { "name": "waybill_id", "type": "number", "required": true, "description": "运单记录ID(wms_order_express.id),0=无关联运单" }, { "name": "waybill_code", "type": "string", "required": true, "description": "运单号" }, { "name": "logistics_code", "type": "string", "required": true, "description": "快递公司编码" }, { "name": "logistics_name", "type": "string", "required": true, "description": "快递公司名称" }, { "name": "logistics_interface_id", "type": "number", "required": true, "description": "快递接口ID" }, { "name": "logistics_interface_name", "type": "string", "required": true, "description": "快递接口名称" }, { "name": "platform_code", "type": "string", "required": true, "description": "平台编码" }, { "name": "waybill_status", "type": "number", "required": true, "description": "运单状态 0/1" }, { "name": "waybill_status_text", "type": "string", "required": true, "description": "运单状态文本" }, { "name": "weighing_weight", "type": "number", "required": true, "description": "称重重量(g)" }, { "name": "delivery_order_code", "type": "string", "required": true, "description": "发货单号" }, { "name": "source_order_codes", "type": "string", "required": true, "description": "原始平台订单号" }, { "name": "pay_no", "type": "string", "required": true, "description": "平台交易单号" }, { "name": "store_id", "type": "number", "required": true, "description": "货主ID" }, { "name": "store_name", "type": "string", "required": true, "description": "货主名称" }, { "name": "status", "type": "string", "required": true, "description": "订单状态" }, { "name": "name", "type": "string", "required": true, "description": "收件人" }, { "name": "mobile", "type": "string", "required": true, "description": "手机号" }, { "name": "province", "type": "string", "required": true, "description": "省" }, { "name": "city", "type": "string", "required": true, "description": "市" }, { "name": "area", "type": "string", "required": true, "description": "区" }, { "name": "detail_address", "type": "string", "required": true, "description": "详细地址" }, { "name": "buyer_nick", "type": "string", "required": true, "description": "买家昵称" }, { "name": "seller_nick", "type": "string", "required": true, "description": "卖家昵称" }, { "name": "shop_nick", "type": "string", "required": true, "description": "店铺名称" }, { "name": "total_amount", "type": "number", "required": true, "description": "订单总金额" }, { "name": "item_amount", "type": "number", "required": true, "description": "商品金额" }, { "name": "freight", "type": "number", "required": true, "description": "运费" }, { "name": "items_count", "type": "number", "required": true, "description": "商品件数" }, { "name": "items_weight", "type": "number", "required": true, "description": "商品总重量(g)" }, { "name": "wave_no", "type": "string", "required": true, "description": "波次号" }, { "name": "delivery_time", "type": "string", "required": true, "description": "发货时间" }, { "name": "create_at", "type": "string", "required": true, "description": "创建时间" } ] }, { "name": "keyword", "type": "string", "required": true, "description": "回显搜索关键词" } ], "errors": [ { "code": 400, "message": "缺少 keyword 参数或仓库上下文" }, { "code": 500, "message": "搜索失败" } ] } ] }, { "groupName": "订单配送异常模块", "module": "order.deliveryExpectionOrder", "list": [ { "method": "order.deliveryExpectionOrder.list", "description": "配送异常订单列表,使用 dispatch 模型,默认筛选 dispatch_lane=m5。;列表运单号回填强制同仓校验:wms_order_express 按「订单ID + 订单所属仓库ID」隔离读取,禁止仅凭订单ID跨仓串读运单号", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page / pageSize" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "统一 where 条件对象;禁止传入 warehouse_id / warehouseId。create_channel(订单来源渠道筛选,按订单表 create_channel 列过滤;枚举:MANUAL=手工单、API=接口、QM=奇门、STOCKOUT=出库转单)。支持简写与标准结构:{\"create_channel\":\"MANUAL\"} 单值精确、{\"create_channel\":[\"QM\",\"API\"]} 裸数组按 in 多选、{\"create_channel\":{\"operator\":\"in\",\"value\":[\"QM\",\"API\"]}} 标准结构多选、{\"create_channel\":{\"operator\":\"ne\",\"value\":\"MANUAL\"}} 排除指定渠道。注意:列表响应中的 create_channel 已格式化为中文标签(手工单/接口/奇门/出库转单),查询条件请传英文枚举值。" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数,支持 sortField / sortOrder" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "订单列表(raw 行数据,字段字典见 docs/order-workbench-list-api.md 中的“订单列表 raw 字段字典”章节),本次新增 store_remark(货主备注)字段;wave_index(波次内序号,联查 wms_order_wave_index,无记录时为 0)。" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息" }, { "name": "recheck_status", "type": "string", "required": false, "description": "复核状态:none=未复核,fin=已复核" } ], "errors": [ { "code": "400", "message": "参数格式错误或缺少仓库上下文" }, { "code": "500", "message": "查询失败" } ] }, { "method": "order.deliveryExpectionOrder.detail", "description": "查询单个订单详情,返回订单头、商品明细和运单信息", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids / id / order_id / orderId", "type": "array|string|number", "required": true, "source": "body", "description": "订单ID;支持 ids 数组、逗号分隔字符串或单个 id/order_id,至少提供一项" }, { "name": "tableType / tablePosition / type / moduleName", "type": "string", "required": false, "source": "body", "description": "可选,指定订单表类型,支持 current/history/dispatch/outsourced/order/revieworder/pendingorder 等" } ], "response": [ { "name": "order", "type": "object", "description": "订单头对象(raw 行数据)" }, { "name": "detail", "type": "object", "description": "等同于 order" }, { "name": "orderItems / items", "type": "array", "description": "商品明细数组" }, { "name": "expresses", "type": "array", "description": "运单信息数组" }, { "name": "waybill_codes", "type": "array", "description": "去重后的运单号字符串数组" } ], "errors": [ { "code": "400", "description": "订单ID 为空或格式错误" }, { "code": "404", "description": "订单不存在或不属于当前仓库" }, { "code": "500", "description": "内部错误" } ] } ] }, { "groupName": "订单归档模块", "module": "order.archiveOrder", "list": [ { "method": "order.archiveOrder.list", "description": "归档订单列表,使用 history 模型。;列表运单号回填强制同仓校验:wms_order_express 按「订单ID + 订单所属仓库ID」隔离读取,禁止仅凭订单ID跨仓串读运单号", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page / pageSize" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "统一 where 条件对象;禁止传入 warehouse_id / warehouseId。create_channel(订单来源渠道筛选,按订单表 create_channel 列过滤;枚举:MANUAL=手工单、API=接口、QM=奇门、STOCKOUT=出库转单)。支持简写与标准结构:{\"create_channel\":\"MANUAL\"} 单值精确、{\"create_channel\":[\"QM\",\"API\"]} 裸数组按 in 多选、{\"create_channel\":{\"operator\":\"in\",\"value\":[\"QM\",\"API\"]}} 标准结构多选、{\"create_channel\":{\"operator\":\"ne\",\"value\":\"MANUAL\"}} 排除指定渠道。注意:列表响应中的 create_channel 已格式化为中文标签(手工单/接口/奇门/出库转单),查询条件请传英文枚举值。" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数,支持 sortField / sortOrder" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "订单列表(raw 行数据,字段字典见 docs/order-workbench-list-api.md 中的“订单列表 raw 字段字典”章节),本次新增 store_remark(货主备注)字段;wave_index(波次内序号,联查 wms_order_wave_index,无记录时为 0)。" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息" }, { "name": "recheck_status", "type": "string", "required": false, "description": "复核状态:none=未复核,fin=已复核" } ], "errors": [ { "code": "400", "message": "参数格式错误或缺少仓库上下文" }, { "code": "500", "message": "查询失败" } ] }, { "method": "order.archiveOrder.detail", "description": "查询单个订单详情,返回订单头、商品明细和运单信息", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids / id / order_id / orderId", "type": "array|string|number", "required": true, "source": "body", "description": "订单ID;支持 ids 数组、逗号分隔字符串或单个 id/order_id,至少提供一项" }, { "name": "tableType / tablePosition / type / moduleName", "type": "string", "required": false, "source": "body", "description": "可选,指定订单表类型,支持 current/history/dispatch/outsourced/order/revieworder/pendingorder 等" } ], "response": [ { "name": "order", "type": "object", "description": "订单头对象(raw 行数据)" }, { "name": "detail", "type": "object", "description": "等同于 order" }, { "name": "orderItems / items", "type": "array", "description": "商品明细数组" }, { "name": "expresses", "type": "array", "description": "运单信息数组" }, { "name": "waybill_codes", "type": "array", "description": "去重后的运单号字符串数组" } ], "errors": [ { "code": "400", "description": "订单ID 为空或格式错误" }, { "code": "404", "description": "订单不存在或不属于当前仓库" }, { "code": "500", "description": "内部错误" } ] } ] }, { "groupName": "打印模块", "module": "order.print", "list": [ { "method": "order.print.getWavePlatformPrintData", "description": "按波次 IDs 获取平台打印中间态数据,自动过滤快递未完全分配的波次,返回 waveGroups(波次 -> 平台 -> 订单)结构。自定义区首行在快递渠道名后追加「商品总数【n】」(n 优先取订单级商品总数 items_total,其次商品明细数量累加,最后商品种类数 items_count 兜底);当波次 source=0 且 wave_type=1 时,商品明细行尾追加「波次总单数×该行商品数量」。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "warehouse_id", "type": "number", "required": true, "source": "body", "description": "仓库ID(必须与当前用户上下文 store_id 一致)" }, { "name": "wave_ids", "type": "array", "required": true, "source": "body", "description": "波次ID列表(支持数字或字符串,内部自动去重与归一化)" } ], "response": [ { "name": "summary", "type": "object", "description": "汇总信息", "children": [ { "name": "total_waves", "type": "number", "description": "通过过滤的波次总数" }, { "name": "total_orders", "type": "number", "description": "所有平台下订单总数" }, { "name": "total_platforms", "type": "number", "description": "所有波次内平台分组总数(累加)" } ] }, { "name": "wave_ids", "type": "array", "description": "通过过滤的波次ID数组" }, { "name": "waveGroups", "type": "array", "description": "主返回结构:按波次分组(波次 -> 平台 -> 订单)", "children": [ { "name": "wave_id", "type": "number", "description": "波次ID" }, { "name": "wave_no", "type": "string", "description": "波次号" }, { "name": "order_count", "type": "number", "description": "该波次下订单总数" }, { "name": "platforms", "type": "array", "description": "按平台和系统快递分组后的订单列表", "children": [ { "name": "platform", "type": "string", "description": "平台编码" }, { "name": "platform_name", "type": "string", "description": "平台名称" }, { "name": "order_count", "type": "number", "description": "该平台+系统快递分组的订单数" }, { "name": "sys_logistics_code", "type": "string", "description": "系统快递编码" }, { "name": "sys_logistics_name", "type": "string", "description": "系统快递名称" }, { "name": "orders", "type": "array", "description": "该分组内的订单列表(逐单中间态,字段同平台层 orders 中元素)", "children": [ { "name": "wave_id", "type": "number", "description": "波次ID" }, { "name": "wave_no", "type": "string", "description": "波次号" }, { "name": "order_id", "type": "number", "description": "订单ID" }, { "name": "order_no", "type": "string", "description": "订单号(delivery_order_code 或 source_order_codes)" }, { "name": "store_id", "type": "number", "description": "货主ID" }, { "name": "warehouse_id", "type": "number", "description": "仓库ID" }, { "name": "platform", "type": "string", "description": "平台编码" }, { "name": "platform_name", "type": "string", "description": "平台名称" }, { "name": "waybill_code", "type": "string", "description": "运单号" }, { "name": "print_data", "type": "object", "description": "打印中间态(详见 printer_data_builder.buildPlatformRequestSkeleton 输出)" } ] } ] } ] }, { "name": "platform_groups", "type": "array", "description": "兼容字段:按平台分组结果(保留以兼容旧客户端)", "children": [ { "name": "platform", "type": "string", "description": "平台编码" }, { "name": "platform_name", "type": "string", "description": "平台名称" }, { "name": "order_count", "type": "number", "description": "该平台订单数" }, { "name": "orders", "type": "array", "description": "逐单中间态(字段同 order_list 元素)" } ] }, { "name": "order_list", "type": "array", "description": "兼容字段:逐单平台打印中间态明细(保留以兼容旧客户端)", "children": [ { "name": "wave_id", "type": "number", "description": "波次ID" }, { "name": "wave_no", "type": "string", "description": "波次号" }, { "name": "order_id", "type": "number", "description": "订单ID" }, { "name": "order_no", "type": "string", "description": "订单号(delivery_order_code 或 source_order_codes)" }, { "name": "store_id", "type": "number", "description": "货主ID" }, { "name": "warehouse_id", "type": "number", "description": "仓库ID" }, { "name": "platform", "type": "string", "description": "平台编码" }, { "name": "platform_name", "type": "string", "description": "平台名称" }, { "name": "waybill_code", "type": "string", "description": "运单号" }, { "name": "print_data", "type": "object", "description": "打印中间态(详见 printer_data_builder.buildPlatformRequestSkeleton 输出)" } ] }, { "name": "ext", "type": "object", "description": "扩展字段", "children": [ { "name": "missing_wave_ids", "type": "array", "description": "传入但不存在的 wave_id 列表" }, { "name": "filtered_wave_ids", "type": "array", "description": "被过滤掉的波次,每项含 wave_id、reason" } ] } ], "errors": [ { "code": "400", "description": "warehouse_id 或 wave_ids 缺失或格式错误" }, { "code": "500", "description": "查询失败" } ] }, { "method": "order.print.unlockWavePlatformPrintDataByGroup", "description": "按分组解锁波次平台打印锁:按传入的 groups 条件匹配已锁定订单并将其 print_lock_status 置为 none,返回解锁统计与解锁订单列表。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "warehouse_id", "type": "number", "required": true, "source": "body", "description": "仓库ID(必须与当前用户上下文 store_id 一致)" }, { "name": "wave_ids", "type": "array", "required": true, "source": "body", "description": "波次ID列表(支持数字或字符串,内部自动去重与归一化)" }, { "name": "group_type", "type": "string", "required": false, "source": "body", "description": "分组类型,支持 platform、platform_express、order;默认 platform_express" }, { "name": "unlock_scope", "type": "string", "required": false, "source": "body", "description": "解锁范围,支持 group、wave;默认 group" }, { "name": "groups", "type": "array", "required": true, "source": "body", "description": "分组条件列表。元素为对象,可包含字段:wave_id(必填)、platform(平台编码)、sys_logistics_code(系统快递编码)、order_ids(订单ID数组)", "children": [ { "name": "wave_id", "type": "number", "description": "波次ID(单个规则指定的波次)" }, { "name": "platform", "type": "string", "description": "平台编码(当 group_type 为 platform/platform_express 时可能必需)" }, { "name": "sys_logistics_code", "type": "string", "description": "系统快递编码(当 group_type 为 platform_express 时可能必需)" }, { "name": "order_ids", "type": "array", "description": "订单ID列表(当 group_type 为 order 时必需)" } ] } ], "response": [ { "name": "summary", "type": "object", "required": true, "description": "解锁操作的汇总统计", "children": [ { "name": "total_waves", "type": "number", "description": "有效波次数(通过过滤的波次数)" }, { "name": "total_locked_orders", "type": "number", "description": "有效波次中原本被锁定的订单总数" }, { "name": "matched_group_orders", "type": "number", "description": "匹配到分组规则的被锁定订单数" }, { "name": "unlocked_count", "type": "number", "description": "实际已更新为 unlocked 的订单数量(update 影响数)" } ] }, { "name": "wave_ids", "type": "array", "required": true, "description": "通过过滤的波次ID数组" }, { "name": "unlocked_order_ids", "type": "array", "required": true, "description": "被解锁的订单ID数组" }, { "name": "unlocked_orders", "type": "array", "required": true, "description": "被解锁订单简要信息列表", "children": [ { "name": "order_id", "type": "number", "description": "订单ID" }, { "name": "wave_id", "type": "number", "description": "波次ID" }, { "name": "wave_no", "type": "string", "description": "波次号" }, { "name": "order_no", "type": "string", "description": "订单号(delivery_order_code 或 source_order_codes)" } ] }, { "name": "ext", "type": "object", "required": false, "description": "扩展字段", "children": [ { "name": "missing_wave_ids", "type": "array", "description": "传入但不存在的 wave_id 列表" }, { "name": "filtered_wave_ids", "type": "array", "description": "被过滤掉的波次(快递未完全分配),每项含 wave_id、wave_no、reason" } ] } ], "errors": [ { "code": "400", "message": "wave_ids 必填,且必须为非空数组", "description": "wave_ids 必填,且必须为非空数组" }, { "code": "400", "message": "warehouse_id 必填且必须为正整数", "description": "warehouse_id 必填且必须为正整数" }, { "code": "400", "message": "warehouse_id 必须与当前用户上下文 store_id 保持一致", "description": "warehouse_id 必须与当前用户上下文 store_id 保持一致" }, { "code": "400", "message": "group_type 仅支持 platform、platform_express、order", "description": "group_type 仅支持 platform、platform_express、order" }, { "code": "400", "message": "unlock_scope 仅支持 group、wave", "description": "unlock_scope 仅支持 group、wave" }, { "code": "400", "message": "groups 必填,且必须为非空数组", "description": "groups 必填,且必须为非空数组" }, { "code": "400", "message": "groups 未匹配到有效的分组解锁条件", "description": "groups 未匹配到有效的分组解锁条件" }, { "code": "500", "message": "内部错误", "description": "内部错误" } ] }, { "method": "order.print.getOrderPrintData", "description": "按订单ID拉取平台打印中间态数据,与 getWavePlatformPrintData 返回结构一致。不限制打印锁定状态,所有订单(包括已锁定)统一返回。仓库ID统一从当前上下文获取,无需调用方传入。自动过滤快递未完全分配的订单(post_status !== 'fin'),返回 waveGroups(波次 -> 平台 -> 订单)结构。自定义区首行在快递渠道名后追加「商品总数【n】」(n 优先取订单级商品总数 items_total,其次商品明细数量累加,最后商品种类数 items_count 兜底);当波次 source=0 且 wave_type=1 时,商品明细行尾追加「波次总单数×该行商品数量」。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "order_ids", "type": "array", "required": true, "source": "body", "description": "订单ID列表(支持数字或字符串,内部自动去重与归一化,必须为非空数组)" } ], "response": [ { "name": "summary", "type": "object", "required": true, "description": "汇总信息", "children": [ { "name": "total_waves", "type": "number", "required": true, "description": "通过过滤的波次总数" }, { "name": "total_orders", "type": "number", "required": true, "description": "所有平台下订单总数" }, { "name": "total_platforms", "type": "number", "required": true, "description": "所有波次内平台分组总数(累加)" } ] }, { "name": "wave_ids", "type": "array", "required": true, "description": "通过过滤的波次ID数组" }, { "name": "waveGroups", "type": "array", "required": true, "description": "主返回结构:按波次分组(波次 -> 平台 -> 订单)", "children": [ { "name": "wave_id", "type": "number", "required": true, "description": "波次ID" }, { "name": "wave_no", "type": "string", "required": true, "description": "波次号" }, { "name": "order_count", "type": "number", "required": true, "description": "该波次下订单总数" }, { "name": "platforms", "type": "array", "required": true, "description": "按平台和系统快递分组后的订单列表", "children": [ { "name": "platform", "type": "string", "required": true, "description": "平台编码" }, { "name": "platform_name", "type": "string", "required": true, "description": "平台名称" }, { "name": "order_count", "type": "number", "required": true, "description": "该平台+系统快递分组的订单数" }, { "name": "sys_logistics_code", "type": "string", "required": true, "description": "系统快递编码" }, { "name": "sys_logistics_name", "type": "string", "required": true, "description": "系统快递名称" }, { "name": "orders", "type": "array", "required": true, "description": "该分组内的订单列表(逐单中间态)", "children": [ { "name": "wave_id", "type": "number", "required": true, "description": "波次ID" }, { "name": "wave_no", "type": "string", "required": true, "description": "波次号" }, { "name": "order_id", "type": "number", "required": true, "description": "订单ID" }, { "name": "order_no", "type": "string", "required": true, "description": "订单号(delivery_order_code 或 source_order_codes)" }, { "name": "store_id", "type": "number", "required": true, "description": "货主ID" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "仓库ID" }, { "name": "platform", "type": "string", "required": true, "description": "平台编码" }, { "name": "platform_name", "type": "string", "required": true, "description": "平台名称" }, { "name": "waybill_code", "type": "string", "required": true, "description": "运单号" }, { "name": "print_data", "type": "object", "required": true, "description": "打印中间态(详见 printer_data_builder.buildPlatformRequestSkeleton 输出)" } ] } ] } ] }, { "name": "ext", "type": "object", "required": true, "description": "扩展字段", "children": [ { "name": "missing_order_ids", "type": "array", "required": true, "description": "传入但数据库中不存在的 order_id 列表" }, { "name": "filtered_order_ids", "type": "array", "required": true, "description": "被过滤掉的订单(快递未完全分配),每项含 order_id、reason" } ] } ], "errors": [ { "code": "400", "message": "order_ids 必填,且必须为非空数组", "description": "order_ids 必填,且必须为非空数组" }, { "code": "500", "message": "查询失败", "description": "查询失败" } ] }, { "method": "order.print.getPrintDataByWaybillCodes", "description": "按运单号数组拉取平台打印中间态数据,与 getOrderPrintData 返回结构一致。支持子单号(business_key>1):主面单与现有逻辑一致,子面单使用主订单数据构建打印数据并在自定义区追加「子单号【{business_key}】-{主单号}」行。仓库ID统一从当前上下文获取。自动过滤快递未完全分配的订单(post_status !== 'fin'),返回 waveGroups(波次 -> 平台 -> 订单)结构。自定义区首行在快递渠道名后追加「商品总数【n】」(n 优先取订单级商品总数 items_total,其次商品明细数量累加,最后商品种类数 items_count 兜底);当波次 source=0 且 wave_type=1 时,商品明细行尾追加「波次总单数×该行商品数量」。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "waybill_codes", "type": "array", "required": true, "source": "body", "description": "运单号数组(字符串数组,内部自动去重与归一化,必须为非空数组)" } ], "response": [ { "name": "summary", "type": "object", "required": true, "description": "汇总信息", "children": [ { "name": "total_waves", "type": "number", "required": true, "description": "通过过滤的波次总数" }, { "name": "total_orders", "type": "number", "required": true, "description": "所有平台下打印条目总数(每个运单一条)" }, { "name": "total_platforms", "type": "number", "required": true, "description": "所有波次内平台分组总数(累加)" } ] }, { "name": "wave_ids", "type": "array", "required": true, "description": "通过过滤的波次ID数组" }, { "name": "waveGroups", "type": "array", "required": true, "description": "波次分组(波次 -> 平台 -> 订单),结构与 getOrderPrintData 一致", "children": [ { "name": "wave_id", "type": "number", "required": true, "description": "波次ID" }, { "name": "wave_no", "type": "string", "required": true, "description": "波次号" }, { "name": "order_count", "type": "number", "required": true, "description": "该波次下打印条目数" }, { "name": "platforms", "type": "array", "required": true, "description": "平台分组列表", "children": [ { "name": "platform", "type": "string", "required": true, "description": "平台编码" }, { "name": "platform_name", "type": "string", "required": true, "description": "平台名称" }, { "name": "order_count", "type": "number", "required": true, "description": "该平台下打印条目数" }, { "name": "order_ids", "type": "array", "required": true, "description": "订单ID数组(去重)" }, { "name": "orders", "type": "array", "required": true, "description": "打印数据文档数组(print_data)" } ] } ] }, { "name": "ext", "type": "object", "required": true, "description": "扩展信息", "children": [ { "name": "missing_waybill_codes", "type": "array", "required": true, "description": "未匹配到的运单号" }, { "name": "filtered_waybill_codes", "type": "array", "required": true, "description": "被过滤掉的运单号及其原因,每项含 waybill_code、reason" } ] } ], "errors": [ { "code": "400", "message": "waybill_codes 必填,且必须为非空数组", "description": "waybill_codes 必填,且必须为非空数组" }, { "code": "500", "message": "查询失败", "description": "查询失败" } ] } ] }, { "groupName": "打印模块", "module": "print", "list": [ { "method": "print.send", "description": "发送打印任务到打印电脑,并记录打印单。说明:当 type=express 时,接口按 data.waveGroups(来源于 order.print.getWavePlatformPrintData 返回的 data.waveGroups)进行处理,按 waveGroups -> platforms 串行处理,每个平台+快递 组分别发送;返回沿用现有简要风格,不返回明细。接口在记录打印单的同时,也会写入订单操作日志(记录打印相关操作)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "computerId", "type": "string", "required": false, "source": "body", "description": "打印电脑 ID;历史/customize 分支可能使用。注意:type=express 场景下不适用(该字段不再作为 express 路径的必填或传输约束)。" }, { "name": "count", "type": "number", "required": false, "source": "body", "description": "打印份数;对 type=customize 有效。type=express 场景下不保留,相应字段会被忽略。" }, { "name": "data", "type": "object", "required": true, "source": "body", "description": "打印业务数据对象。对于 type=express:必须提供 data.waveGroups(来源于 order.print.getWavePlatformPrintData 的返回值 data.waveGroups),接口按 waveGroups->platforms 串行处理,每个 平台+快递 组分别发送;对于 type=customize,data 的具体字段由模板决定。" }, { "name": "printer", "type": "string", "required": false, "source": "body", "description": "打印机名称;type=customize 使用。type=express 下忽略(由快递平台/站点决定打印目标)。" }, { "name": "template", "type": "object", "required": false, "source": "body", "description": "打印模板对象;仅 type=customize 时必填且应包含 page_width、page_height、template_content。type=express 场景下忽略 template 字段。", "children": [ { "name": "page_width", "type": "number", "required": true, "description": "页面宽度(mm)" }, { "name": "page_height", "type": "number", "required": true, "description": "页面高度(mm)" }, { "name": "template_content", "type": "array", "required": false, "description": "模板内容数组" } ] }, { "name": "timestamp", "type": "string", "required": false, "source": "body", "description": "业务时间戳;历史字段。type=express 场景下不适用。" }, { "name": "type", "type": "string", "required": true, "source": "body", "description": "打印类型;支持 customize、express。对于 express 场景,必须遵守下列额外约束:提供 printStationId、requestCode,并在 data.waveGroups 中传入来自 order.print.getWavePlatformPrintData 的 waveGroups 数据。" }, { "name": "printStationId", "type": "string", "required": true, "source": "body", "description": "打印站点/工作站标识(必填,type=express 时必须提供),用于指示目标打印站或分发单元。" }, { "name": "requestCode", "type": "string", "required": true, "source": "body", "description": "请求去重/防重放 ID(必填,type=express 时必须提供)。接口约束:requestCode 在约定周期内不得变更(例如一次批次/会话期间),系统在同一次请求处理范围内保证对重复 requestCode 进行防重放处理;此保护仅保证同一次请求内的去重/防重放,不等同于跨请求的强幂等保证。" } ], "response": [ { "name": "flag", "type": "string", "required": false, "description": "全局调用结果标识,成功时为 success,失败时为 failure" }, { "name": "code", "type": "number", "required": false, "description": "业务状态码;成功时为 200,失败时通常为 1001 或 504" }, { "name": "message", "type": "string", "required": false, "description": "返回信息" }, { "name": "printId", "type": "number", "required": false, "description": "打印记录 ID;任务入库成功后返回,失败时若已生成记录也会返回。接口在 express 场景下不返回明细结果,只给出调用结果摘要。" } ], "errors": [ { "code": 1001, "message": "不支持的打印类型" }, { "code": 504, "message": "打印任务发送失败(如打印机不存在、打印机脱机、打印服务通讯失败)" } ] }, { "method": "print.getPrintResult", "description": "print.getPrintResult 接口", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "printId", "type": "string", "required": true, "source": "body", "description": "printId 参数" } ], "response": [], "errors": [] }, { "method": "print.getPrintRecordItem", "description": "print.getPrintRecordItem 接口", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "id 参数" } ], "response": [], "errors": [] }, { "method": "print.getList", "description": "查询当前仓库下的打印台列表,支持分页与 where 条件筛选(支持字段:id、name、computer_id、custom_barcode)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "page", "type": "number", "required": false, "source": "body", "description": "页码,默认 1" }, { "name": "pageSize", "type": "number", "required": false, "source": "body", "description": "每页数量,默认 20" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "筛选条件对象;支持字段:id(等值)、name、computer_id、custom_barcode;推荐使用 { operator, value, type } 标准结构" } ], "response": [ { "name": "data", "type": "object", "required": true, "description": "返回数据对象,包含 list 与 pagination", "children": [ { "name": "list", "type": "array", "required": true, "description": "打印台列表", "children": [ { "name": "id", "type": "number", "description": "打印台 ID" }, { "name": "name", "type": "string", "description": "打印台名称" }, { "name": "computer_id", "type": "number", "description": "关联打印电脑 ID" }, { "name": "custom_barcode", "type": "string", "description": "自定义条码" }, { "name": "default_printer_name", "type": "string", "description": "默认打印机名称" }, { "name": "subject_config", "type": "object", "description": "打印台的 subject_config 配置" }, { "name": "is_online", "type": "number", "description": "打印电脑在线状态,1=在线,0=离线" }, { "name": "components", "type": "array", "description": "电脑组件在线信息,数组项包含 name/is_online", "children": [ { "name": "name", "type": "string", "description": "组件名称" }, { "name": "is_online", "type": "number", "description": "组件是否在线,1/0" } ] } ] }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息,包含 page、pageSize、total、totalPages、hasPrevious、hasNext" } ] } ], "errors": [ { "code": "400", "description": "参数格式错误或 where 中包含非法字段" }, { "code": "500", "description": "查询失败或内部错误" } ] }, { "method": "print.getItem", "description": "查询单个打印台详情,返回打印台对象(raw 行记录,含 subject_config)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "打印台 ID,必填" } ], "response": [ { "name": "data", "type": "object", "required": true, "description": "打印台原始记录(PrintStation raw),字段示例", "children": [ { "name": "id", "type": "number", "description": "打印台 ID" }, { "name": "name", "type": "string", "description": "打印台名称" }, { "name": "computer_id", "type": "number", "description": "关联打印电脑 ID" }, { "name": "custom_barcode", "type": "string", "description": "自定义条码" }, { "name": "default_printer_name", "type": "string", "description": "默认打印机名称" }, { "name": "subject_config", "type": "object", "description": "打印台 subject_config 配置(见下文)" }, { "name": "create_at", "type": "string", "description": "创建时间" }, { "name": "update_at", "type": "string", "description": "更新时间" }, { "name": "deleted", "type": "number", "description": "软删除标识,1=已删除" } ] } ], "errors": [ { "code": "400", "description": "参数错误:缺少 id 或 id 格式不正确" }, { "code": "404", "description": "打印台不存在" }, { "code": "500", "description": "内部错误" } ] }, { "method": "print.add", "description": "新增打印台:关联打印电脑并可保存 subject_config(会由模型 normalizeSubjectConfig 校验)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "computer_id", "type": "number", "required": true, "source": "body", "description": "关联的打印电脑 ID(必填)" }, { "name": "name", "type": "string", "required": true, "source": "body", "description": "打印台名称(必填)" }, { "name": "custom_barcode", "type": "string", "required": false, "source": "body", "description": "自定义条码" }, { "name": "default_printer_name", "type": "string", "required": false, "source": "body", "description": "默认打印机名称" }, { "name": "subject_config", "type": "object", "required": false, "source": "body", "description": "打印台的主题/业务配置(可选,若存在将调用模型 normalizeSubjectConfig 进行校验)", "children": [ { "name": "express_bind_printer", "type": "array", "description": "快递与打印机绑定数组,数组项仅包含 { express_code, printer_name }", "children": [ { "name": "express_code", "type": "string", "required": true, "description": "快递编码,必填" }, { "name": "printer_name", "type": "string", "required": true, "description": "打印机名称,必填" } ] } ] } ], "response": [ { "name": "data", "type": "object", "required": true, "description": "新建的打印台对象(raw)" } ], "errors": [ { "code": "400", "description": "参数错误:缺少必填字段(computer_id/name)或 subject_config 格式不合法" }, { "code": "500", "description": "创建失败或内部错误" } ] }, { "method": "print.hasName", "description": "print.hasName 接口", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "name", "type": "string", "required": true, "source": "body", "description": "name 参数" }, { "name": "id", "type": "number", "required": false, "source": "body", "description": "id 参数" } ], "response": [], "errors": [] }, { "method": "print.updateItem", "description": "更新打印台信息:支持更新 name、computer_id、custom_barcode、default_printer_name 以及 subject_config(会走 normalizeSubjectConfig)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "打印台 ID(必填)" }, { "name": "computer_id", "type": "number", "required": false, "source": "body", "description": "要更新的打印电脑 ID" }, { "name": "custom_barcode", "type": "string", "required": false, "source": "body", "description": "自定义条码" }, { "name": "name", "type": "string", "required": false, "source": "body", "description": "打印台名称" }, { "name": "default_printer_name", "type": "string", "required": false, "source": "body", "description": "默认打印机名称" }, { "name": "subject_config", "type": "object", "required": false, "source": "body", "description": "subject_config(可选),传入将替换/规范化配置", "children": [ { "name": "express_bind_printer", "type": "array", "description": "快递-打印机绑定数组,数组项仅包含 { express_code, printer_name }", "children": [ { "name": "express_code", "type": "string", "required": true, "description": "快递编码,必填" }, { "name": "printer_name", "type": "string", "required": true, "description": "打印机名称,必填" } ] } ] } ], "response": [ { "name": "data", "type": "object", "required": false, "description": "更新结果,通常返回 null" } ], "errors": [ { "code": "400", "description": "参数错误(缺少 id 或 subject_config 格式不合法)" }, { "code": "404", "description": "打印台不存在" }, { "code": "500", "description": "更新失败或内部错误" } ] }, { "method": "print.del", "description": "批量删除(软删除)打印台:将指定 ids 的记录标记为 deleted=1。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "array", "required": true, "source": "body", "description": "要删除的打印台 ID 数组,必须为非空数组(示例: [1,2,3])" } ], "response": [ { "name": "data", "type": "object", "required": false, "description": "返回空数据结构,表示操作成功" } ], "errors": [ { "code": "400", "description": "参数错误:ids 必须为非空数组" }, { "code": "500", "description": "删除失败或内部错误" } ] }, { "method": "print.getComputer", "description": "查询当前仓库下状态为 1 的打印电脑列表(raw 列表)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [ { "name": "data", "type": "array", "required": true, "description": "打印电脑数组,每项为打印电脑的原始记录", "children": [ { "name": "id", "type": "number", "description": "打印电脑 ID" }, { "name": "name", "type": "string", "description": "打印电脑名称或标识" }, { "name": "status", "type": "number", "description": "状态,1=启用" }, { "name": "warehouse_id", "type": "number", "description": "所属仓库 ID" } ] } ], "errors": [ { "code": "400", "description": "未识别到当前仓库上下文" }, { "code": "500", "description": "查询失败或内部错误" } ] }, { "method": "print.getComputerPrinter", "description": "获取指定打印电脑的打印机列表(从 redis: printer:{id}:printerList 读取并返回 data 数组,通常为打印机名称数组或对象数组)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "打印电脑 ID,必填" } ], "response": [ { "name": "data", "type": "array", "required": true, "description": "打印机数组,通常为字符串名称数组或打印机对象数组(取决于 redis 存储格式)" } ], "errors": [ { "code": "400", "description": "参数错误:缺少 id" }, { "code": "500", "description": "读取 Redis 或解析数据失败" } ] }, { "method": "print.savePrinters", "description": "保存 default_printer_name 与 subject_config.express_bind_printer。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "defaultPrinter", "type": "string", "required": true, "source": "body", "description": "默认打印机名称(必填),会写入打印台的 `default_printer_name` 字段" }, { "name": "express", "type": "array", "required": true, "source": "body", "description": "快递与打印机绑定数组(必填)。每项应包含首选字段 `express_code`(string)和 `printer_name`(string)。为兼容历史字段,也接受 `express_id`(可映射为 `express_code`)和 `name`(可映射为 `printer_name`)。接口实现会将结果序列化后写入打印台的 `subject_config.express_bind_printer`。", "children": [ { "name": "express_code", "type": "string", "required": false, "description": "首选:快递编码(string),实现中优先使用该字段" }, { "name": "printer_name", "type": "string", "required": false, "description": "首选:打印机名称(string),实现中优先使用该字段" }, { "name": "express_id", "type": "number|string", "required": false, "description": "兼容字段:历史的 express_id,可映射为 express_code 使用" }, { "name": "name", "type": "string", "required": false, "description": "兼容字段:历史的 name,可映射为 printer_name 使用" } ] }, { "name": "print_station_id", "type": "number", "required": true, "source": "body", "description": "目标打印台 ID(必填)。接口会根据此 ID 更新对应打印台记录的 default_printer_name 与 subject_config.express_bind_printer" } ], "response": [ { "name": "data", "type": "object", "required": false, "description": "成功不返回业务数据,语义为成功(实现中返回 { data: null, code: 0 })" } ], "errors": [ { "code": "400", "description": "参数错误:defaultPrinter/express/print_station_id 格式或缺失" }, { "code": "404", "description": "打印台不存在:未找到对应 print_station_id 的打印台记录" }, { "code": "500", "description": "保存失败或内部错误" } ] }, { "method": "print.notifyLock", "description": "仅执行订单锁定流程,不发送打印任务;记录打印任务日志并写入订单操作日志。兼容别名:print.notify_lock(等价转调)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "order_ids", "type": "array", "required": false, "source": "body", "description": "订单 ID 数组(与 orderIds 互为别名)。至少需提供 order_ids/orderIds/waveGroups/data.waveGroups 中的一类以提取订单 ID。", "children": [ { "name": "id", "type": "number", "description": "订单 ID" } ] }, { "name": "orderIds", "type": "array", "required": false, "source": "body", "description": "订单 ID 数组(驼峰兼容,等同于 order_ids)。", "children": [ { "name": "id", "type": "number", "description": "订单 ID" } ] }, { "name": "waveGroups", "type": "array", "required": false, "source": "body", "description": "波次分组结构(可从中提取订单 ID,参考 order.print.getWavePlatformPrintData 返回的 waveGroups)。", "children": [ { "name": "wave_id", "type": "number", "description": "波次 ID" } ] }, { "name": "data", "type": "object", "required": false, "source": "body", "description": "兼容包装对象;若传入 data.waveGroups,可从中提取订单 ID。", "children": [ { "name": "waveGroups", "type": "array", "required": false, "description": "同上,来自 order.print.getWavePlatformPrintData 的 data.waveGroups 结构。" } ] } ], "response": [ { "name": "locked_count", "type": "number", "required": false, "description": "成功锁定的订单数量" }, { "name": "order_ids_count", "type": "number", "required": false, "description": "请求中识别出的订单 ID 数量" }, { "name": "order_ids", "type": "array", "required": false, "description": "本次尝试锁定的订单 ID 列表" }, { "name": "source", "type": "string", "required": false, "description": "操作来源标识(可选,若后端返回则提供具体来源)" } ], "errors": [ { "code": 400, "message": "无有效订单ID(order_ids/orderIds/waveGroups/data.waveGroups 均未提供或均无有效订单)" }, { "code": 500, "message": "订单锁定失败" } ] }, { "method": "print.notify_lock", "description": "兼容别名(等价转调到 print.notifyLock);建议使用 print.notifyLock。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "print.markWavePrintStatus", "description": "标记/取消标记整个波次订单的打印状态。仓库隔离:从登录上下文获取仓库ID。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "wave_id", "type": "number", "required": true, "source": "body", "description": "波次ID(必填,正整数)" }, { "name": "status", "type": "string", "required": false, "source": "body", "description": "目标状态:printed=标记已打印,unprinted=取消已打印标记。默认 printed。" } ], "response": [ { "name": "wave_id", "type": "number", "description": "波次ID" }, { "name": "status", "type": "string", "description": "目标状态" }, { "name": "print_status", "type": "string", "description": "订单表 print_status 字段值(fin / none)" }, { "name": "total_orders", "type": "number", "description": "波次下总订单数" }, { "name": "affected_orders", "type": "number", "description": "实际更新的订单数" }, { "name": "order_ids", "type": "array", "description": "波次下所有订单ID" } ], "errors": [ { "code": 400, "message": "wave_id 参数必填,且必须为正整数" }, { "code": 400, "message": "status 参数不合法,仅支持 printed / unprinted" }, { "code": 400, "message": "无法获取当前仓库ID,请确认已登录" }, { "code": 404, "message": "波次在当前仓库下没有可操作的订单" }, { "code": 500, "message": "内部错误(OrderDeliveryFactory/OrderDeliveryModel 不可用或更新失败)" } ] }, { "method": "print.confirmWavePrint", "description": "波次确认打印:扫描波次内任一订单的面单号,将波次下全部已打印(print_status='fin')且非拦截的订单批量标记 confirm_print_status='fin',记录打印完成后真实扫描面单确认。拦截订单跳过(不确认、不阻断);波次下存在未打印订单(print_status != 'fin')时阻断;全部已确认时重复扫描返回 already_confirmed,不重复写日志。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "waybill_no", "type": "string", "required": true, "source": "body", "description": "面单号/运单号(必填,用于定位订单及所属波次)" } ], "response": [ { "name": "waybill_no", "type": "string", "required": false, "description": "扫描的面单号" }, { "name": "matched_order_id", "type": "number", "required": false, "description": "面单号匹配到的订单ID" }, { "name": "wave_id", "type": "number", "required": false, "description": "波次ID" }, { "name": "wave_no", "type": "string", "required": false, "description": "波次编码" }, { "name": "total_order_count", "type": "number", "required": false, "description": "波次下总订单数" }, { "name": "intercepted_order_count", "type": "number", "required": false, "description": "波次下拦截订单数(跳过确认)" }, { "name": "confirmed_order_count", "type": "number", "required": false, "description": "已确认打印订单数(confirm_print_status='fin')" }, { "name": "newly_confirmed_order_count", "type": "number", "required": false, "description": "本次新增确认订单数(仅 status=confirmed 时返回)" }, { "name": "status", "type": "string", "required": false, "description": "确认结果:confirmed=本次完成确认 / already_confirmed=已全部确认" } ], "errors": [ { "code": 400, "message": "waybill_no 必填(面单号/运单号)" }, { "code": 400, "message": "缺少当前用户仓库上下文 store_id" }, { "code": 400, "message": "运单对应订单未分配波次" }, { "code": 400, "message": "波次存在未打印订单,禁止确认打印(返回 unprinted_order_count)" }, { "code": 404, "message": "未查询到该面单号对应的订单,无记录" }, { "code": 500, "message": "内部错误(OrderDeliveryFactory/订单模型不可用或更新失败)" } ] } ] }, { "groupName": "打印机站点模块", "module": "printer.station", "list": [ { "method": "printer.station.list", "description": "获取打印站点列表", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] } ] }, { "groupName": "打印模板模块", "module": "setting.printTemplate", "list": [ { "method": "setting.printTemplate.list", "description": "获取打印模板树", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "setting.printTemplate.save", "description": "保存打印模板", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "setting.printTemplate.create", "description": "创建打印模板(platform 固定为 default,template_type 固定为 CUSTOM,template_url 固定为空字符串)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "template_name", "type": "string", "required": true, "source": "body", "description": "模板名称" }, { "name": "business_type", "type": "string", "required": true, "source": "body", "description": "业务类型" }, { "name": "page_width", "type": "number", "required": true, "source": "body", "description": "页面宽度(mm)" }, { "name": "page_height", "type": "number", "required": true, "source": "body", "description": "页面高度(mm)" }, { "name": "template_content", "type": "array", "required": false, "source": "body", "description": "模板内容,可省略;省略时默认创建空模板内容" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "新建模板ID" } ], "errors": [ { "code": "400", "description": "参数错误(缺少 template_name、business_type、page_width 或 page_height)" }, { "code": "409", "description": "同一业务类型和平台下已存在自定义模板" } ] }, { "method": "setting.printTemplate.delete", "description": "删除打印模板(软删除)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "模板ID" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "删除的模板ID" } ], "errors": [ { "code": "400", "description": "参数错误(缺少 id)" }, { "code": "404", "description": "模板不存在或无权限" } ] }, { "method": "setting.printTemplate.listTemplatesByType", "description": "按业务类型查询模板", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "businessType", "type": "string", "required": true, "source": "body", "description": "businessType 参数" } ], "response": [], "errors": [] } ] }, { "groupName": "仓库设置模块", "module": "setting.warehouse", "list": [ { "method": "setting.warehouse.getSettings", "description": "获取当前登录仓库的 subject_config;subject_config 新增大团购打包系数 big_group_pack_coefficient(数字,默认 3,单位秒/单,必须大于 0,用于 workbench 大团购波次打包时长闸门与倒计时);新增散单称重是否需要打包 single_weigh_require_pack(flag 布尔,默认 false 关闭;开启后散单称重(订单波次范围 wave_scope 非 1 大团购/3 小团购)前必须已打包完成 pack_status=fin,未打包时拒绝称重并返回错误)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [ { "name": "warehouse_id", "type": "number", "required": true, "description": "仓库 ID" }, { "name": "subject_config", "type": "object", "required": true, "description": "仓库的 subject_config 配置对象" }, { "name": "subject_config.enable_external_express_code", "type": "boolean", "required": true, "description": "是否启用外部快递编码;默认 false(关闭)。开启后允许按外部系统传入的快递编码进行处理(如无匹配仍以业务校验为准)" }, { "name": "subject_config.auto_outbound_rules", "type": "object", "required": true, "description": "自动出库规则配置。全部条件满足时自动标记待出库" }, { "name": "subject_config.auto_outbound_rules.enabled", "type": "boolean", "required": true, "description": "是否启用自动出库,默认 false" }, { "name": "subject_config.auto_outbound_rules.require_recheck", "type": "boolean", "required": true, "description": "是否要求已复核(recheck_status=fin),默认 true" }, { "name": "subject_config.auto_outbound_rules.require_pack", "type": "boolean", "required": true, "description": "是否要求已打包(pack_status=fin),默认 true" }, { "name": "subject_config.auto_outbound_rules.require_weigh", "type": "boolean", "required": true, "description": "是否要求已称重(weighing_weight>0),默认 true" }, { "name": "subject_config.auto_outbound_rules.require_sync", "type": "boolean", "required": true, "description": "是否要求已同步(sync_status=fin),默认 true" }, { "name": "subject_config.auto_outbound_rules.require_print", "type": "boolean", "required": true, "description": "是否要求已打印(print_status=fin),默认 true" }, { "name": "subject_config.auto_outbound_rules.require_pick", "type": "boolean", "required": true, "description": "是否要求已拣货(pick_status=fin),默认 true" }, { "name": "subject_config.sender_name", "type": "string", "required": false, "description": "仓库默认发件人姓名,默认空字符串" }, { "name": "subject_config.sender_tel", "type": "string", "required": false, "description": "仓库默认发件人联系电话,默认空字符串" }, { "name": "subject_config.province_name", "type": "string", "required": false, "description": "仓库默认发件省份,默认空字符串" }, { "name": "subject_config.city_name", "type": "string", "required": false, "description": "仓库默认发件城市,默认空字符串" }, { "name": "subject_config.district_name", "type": "string", "required": false, "description": "仓库默认发件区/县,默认空字符串" }, { "name": "subject_config.town_name", "type": "string", "required": false, "description": "仓库默认发件镇/街道,默认空字符串" }, { "name": "subject_config.address", "type": "string", "required": false, "description": "仓库默认发件详细地址,默认空字符串" }, { "name": "subject_config.receiver_address", "type": "string", "required": false, "description": "仓库收货地址(退货/退件收件地址),一行文本,默认空字符串" }, { "name": "subject_config.single_order_pack_max_minutes", "type": "number", "required": false, "description": "散单打包最大时长,单位:分钟,默认 3" }, { "name": "subject_config.group_order_pack_max_minutes", "type": "number", "required": false, "description": "团购打包最大时长,单位:分钟,默认 40" }, { "name": "subject_config.big_group_pack_coefficient", "type": "number", "required": false, "description": "大团购波次(wave_scope=1)打包中,扫描其他波次订单至少需等待「当前波次打包数 × 系数」秒,单位:秒/单,默认 3,必须大于 0" }, { "name": "subject_config.single_weigh_require_pack", "type": "boolean", "required": false, "description": "散单称重是否需要打包(flag,默认 false 关闭):开启后散单称重(订单波次范围 wave_scope 非 1 大团购/3 小团购)前必须已打包完成(pack_status=fin),未打包时拒绝称重并返回错误" }, { "name": "subject_config.return_unpack_max_record_minutes", "type": "number", "required": false, "description": "拆包最大录制时长,单位:分钟,默认 5,min 1;超过上限时拆包提交的结束时间自动截断为开始时间+上限" }, { "name": "subject_config.default_location_id", "type": "number", "required": false, "description": "默认库位(库位ID,未配置时为 null)" }, { "name": "subject_config.cutoff_order_enabled", "type": "number", "required": false, "description": "启用截单(flag:0=关闭,1=开启;默认 1)。启用后订单创建时间早于开始自动分配时间或超过截单时间(开始时间晚于截单时间时截单时间视为次日),不再自动分配快递和储位、不再自动加团" }, { "name": "subject_config.allocate_start_time", "type": "string", "required": false, "description": "开始自动分配时间,格式 HH:mm,默认 08:00,范围 00:00-23:59;作为自动分配初始时间,当前时间早于该时间与超过截单时间行为一致(不自动分配快递和储位、不自动加团)" }, { "name": "subject_config.cutoff_order_time", "type": "string", "required": false, "description": "截单时间,格式 HH:mm,默认 18:00,范围 00:00-23:59;作为最后允许自动分配的时间,开始时间晚于截单时间时截单时间视为次日(跨天窗口)" }, { "name": "subject_config.receiving_pending_inbound_notice", "type": "object", "required": false, "description": "收货未入库提醒配置。开启后每天按提醒时间(notice_time)扫描「创建时间超过 min_hours 且不足 max_hours 仍未完成入库」的收货单:绑定货主的通知货主收货群(未配群回退仓库客服群),未绑定货主的通知仓库客服群" }, { "name": "subject_config.receiving_pending_inbound_notice.enabled", "type": "boolean", "required": false, "description": "是否通知收货未入库(flag:0=关闭,1=开启;默认 0 关闭)。开启后收货未入库提醒定时任务才会在提醒时间执行" }, { "name": "subject_config.receiving_pending_inbound_notice.notice_time", "type": "string", "required": false, "description": "提醒时间,格式 HH:mm,默认 08:30,范围 00:00-23:59;定时任务按此时间(含 10 分钟宽限)每天提醒一次" }, { "name": "subject_config.receiving_pending_inbound_notice.min_hours", "type": "number", "required": false, "description": "超时下限(小时):收货单创建时间距今超过该值才提醒,默认 24,须为大于 0 的整数" }, { "name": "subject_config.receiving_pending_inbound_notice.max_hours", "type": "number", "required": false, "description": "超时上限(小时):收货单创建时间距今小于该值才提醒(超过则不再提醒),默认 48,须为大于 min_hours 的整数" }, { "name": "subject_config.receiving_pending_inbound_notice.notice_template", "type": "string", "required": false, "description": "通知短语(消息第一行,仓库/客服群)。支持变量:{warehouse} 仓库名 / {warehouse_id} 仓库ID / {store} 货主名(未绑定为「未绑定货主」)/ {store_id} 货主ID / {count} 本批单数 / {min_hours} 超时下限 / {max_hours} 超时上限 / {date} 提醒日期(YYYY-MM-DD)/ {numbers} 本批收货单号。未识别的占位符原样保留;短语后换行逐行列出明细(一行一条,最多 20 行),留空使用默认短语" }, { "name": "subject_config.receiving_pending_inbound_notice.store_notice_template", "type": "string", "required": false, "description": "通知短语(消息第一行,货主群)。变量同 notice_template,留空使用默认短语" }, { "name": "subject_config.inbox_push_retry", "type": "object", "required": false, "description": "站内信推送失败自动重发配置(同「收货未入库提醒」的嵌套结构):开启后站内信回信/系统通知推送失败(如桥接离线返回 wx offline / qiwe offline)由定时任务每 3 分钟自动重发一次" }, { "name": "subject_config.inbox_push_retry.enabled", "type": "number", "required": false, "description": "是否开启站内信推送失败自动重发(flag:0=关闭,1=开启;默认 0=关闭,需显式开启)" }, { "name": "subject_config.inbox_push_retry.window_minutes", "type": "number", "required": false, "description": "重发时间范围(分钟,1-1440,默认 30):仅自动重发「失败时间在该范围内」的消息,超出范围不再补发;仅在 enabled 开启时生效" } ], "errors": [ { "code": "400", "message": "未识别到当前仓库" }, { "code": "404", "message": "仓库不存在" }, { "code": "500", "message": "获取失败" } ] }, { "method": "setting.warehouse.getFieldMeta", "description": "获取仓库设置字段元信息;本次 list 新增「大团购打包系数」(key=big_group_pack_coefficient,type=number,default=3,min=0.1,单位秒/单,用于大团购波次打包时长闸门与倒计时);本次新增「散单称重是否需要打包」(key=single_weigh_require_pack,type=flag,default=false,required=false,开启后散单称重(wave_scope 非 1 大团购/3 小团购)前必须已打包完成 pack_status=fin)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [ { "name": "list", "type": "array", "description": "字段元信息数组", "children": [ { "name": "key", "type": "string", "description": "字段 key" }, { "name": "name", "type": "string", "description": "字段名称" }, { "name": "type", "type": "string", "description": "字段类型" }, { "name": "default", "type": "any", "description": "默认值(按字段类型返回)" }, { "name": "required", "type": "boolean", "description": "是否必填" }, { "name": "description", "type": "string", "description": "字段描述" }, { "name": "options", "type": "array", "description": "可选项(仅当 type 为 select/enum 时返回)" }, { "name": "min", "type": "number", "description": "数值型最小值(可选)" }, { "name": "max", "type": "number", "description": "数值型最大值(可选)" }, { "name": "maxLength", "type": "number", "description": "字符串最大长度(可选)" } ], "required": true } ], "errors": [ { "code": "400", "message": "未识别到当前仓库,无法操作仓库设置" }, { "code": "500", "message": "获取仓库设置字段信息失败" } ] }, { "method": "setting.warehouse.saveSettings", "description": "修改仓库设置并清理指定仓库缓存(subject_config 支持部分字段更新,本次新增 subject_config.single_weigh_require_pack);本次文档补漏 subject_config.big_group_pack_coefficient 入参说明(对齐 getSettings/getFieldMeta 与代码实现)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "subject_config", "type": "object", "required": true, "source": "body", "description": "仓库的 subject_config 对象" }, { "name": "cache_warehouse_id", "type": "number", "required": false, "source": "body", "description": "需清理缓存的仓库 ID(下划线命名兼容)" }, { "name": "cacheWarehouseId", "type": "number", "required": false, "source": "body", "description": "需清理缓存的仓库 ID(驼峰命名兼容)" }, { "name": "subject_config.enable_external_express_code", "type": "boolean", "required": false, "source": "body.subject_config", "description": "是否启用外部快递编码;默认 false(关闭)。开启后允许按外部系统传入的快递编码进行处理(如无匹配仍以业务校验为准)" }, { "name": "subject_config.auto_outbound_rules", "type": "object", "required": false, "source": "body.subject_config", "description": "自动出库规则配置。全部条件满足时自动标记待出库" }, { "name": "subject_config.auto_outbound_rules.enabled", "type": "boolean", "required": false, "source": "body.subject_config.auto_outbound_rules", "description": "是否启用自动出库,默认 false" }, { "name": "subject_config.auto_outbound_rules.require_recheck", "type": "boolean", "required": false, "source": "body.subject_config.auto_outbound_rules", "description": "是否要求已复核(recheck_status=fin),默认 true" }, { "name": "subject_config.auto_outbound_rules.require_pack", "type": "boolean", "required": false, "source": "body.subject_config.auto_outbound_rules", "description": "是否要求已打包(pack_status=fin),默认 true" }, { "name": "subject_config.auto_outbound_rules.require_weigh", "type": "boolean", "required": false, "source": "body.subject_config.auto_outbound_rules", "description": "是否要求已称重(weighing_weight>0),默认 true" }, { "name": "subject_config.auto_outbound_rules.require_sync", "type": "boolean", "required": false, "source": "body.subject_config.auto_outbound_rules", "description": "是否要求已同步(sync_status=fin),默认 true" }, { "name": "subject_config.auto_outbound_rules.require_print", "type": "boolean", "required": false, "source": "body.subject_config.auto_outbound_rules", "description": "是否要求已打印(print_status=fin),默认 true" }, { "name": "subject_config.auto_outbound_rules.require_pick", "type": "boolean", "required": false, "source": "body.subject_config.auto_outbound_rules", "description": "是否要求已拣货(pick_status=fin),默认 true" }, { "name": "subject_config.sender_name", "type": "string", "required": false, "source": "body.subject_config", "description": "仓库默认发件人姓名,默认空字符串,最大长度 50" }, { "name": "subject_config.sender_tel", "type": "string", "required": false, "source": "body.subject_config", "description": "仓库默认发件人联系电话,默认空字符串,最大长度 20" }, { "name": "subject_config.province_name", "type": "string", "required": false, "source": "body.subject_config", "description": "仓库默认发件省份,默认空字符串,最大长度 50" }, { "name": "subject_config.city_name", "type": "string", "required": false, "source": "body.subject_config", "description": "仓库默认发件城市,默认空字符串,最大长度 50" }, { "name": "subject_config.district_name", "type": "string", "required": false, "source": "body.subject_config", "description": "仓库默认发件区/县,默认空字符串,最大长度 50" }, { "name": "subject_config.town_name", "type": "string", "required": false, "source": "body.subject_config", "description": "仓库默认发件镇/街道,默认空字符串,最大长度 50" }, { "name": "subject_config.address", "type": "string", "required": false, "source": "body.subject_config", "description": "仓库默认发件详细地址,默认空字符串,最大长度 200" }, { "name": "subject_config.receiver_address", "type": "string", "required": false, "source": "body.subject_config", "description": "仓库收货地址(退货/退件收件地址),一行文本,默认空字符串,最大长度 500" }, { "name": "subject_config.single_order_pack_max_minutes", "type": "number", "required": false, "source": "body.subject_config", "description": "散单打包最大时长,单位:分钟,默认 3,须为大于 0 的整数" }, { "name": "subject_config.group_order_pack_max_minutes", "type": "number", "required": false, "source": "body.subject_config", "description": "团购打包最大时长,单位:分钟,默认 40,须为大于 0 的整数" }, { "name": "subject_config.big_group_pack_coefficient", "type": "number", "required": false, "source": "body.subject_config", "description": "大团购波次(wave_scope=1)打包中,扫描其他波次订单至少需等待「当前波次打包数 × 系数」秒,单位:秒/单,默认 3,必须大于 0;非法值报 400:subject_config.big_group_pack_coefficient 必须是大于 0 的数字" }, { "name": "subject_config.single_weigh_require_pack", "type": "boolean", "required": false, "source": "body.subject_config", "description": "散单称重是否需要打包(flag,默认 false 关闭):开启后散单称重(wave_scope 非 1 大团购/3 小团购)前必须已打包完成(pack_status=fin)。仅接受布尔/like-flag(true/1/'1'/'true' → true;false/0/'0'/'false' → false),非法值报 400:subject_config.single_weigh_require_pack 必须是布尔值" }, { "name": "subject_config.return_unpack_max_record_minutes", "type": "number", "required": false, "source": "body.subject_config", "description": "拆包最大录制时长,单位:分钟,默认 5,min 1,须为大于 0 的整数(非法值报 400:subject_config.return_unpack_max_record_minutes 必须是大于 0 的整数);超过上限时拆包提交的结束时间自动截断为开始时间+上限" }, { "name": "subject_config.default_location_id", "type": "number", "required": false, "source": "body.subject_config", "description": "默认库位(库位ID,须属于当前仓库且未删除、已启用,否则报 400;传 null 清空)" }, { "name": "subject_config.cutoff_order_enabled", "type": "number", "required": false, "source": "body.subject_config", "description": "启用截单(flag:0=关闭,1=开启;默认 1)。启用后订单创建时间早于开始自动分配时间或超过截单时间(开始时间晚于截单时间时截单时间视为次日),不再自动分配快递和储位、不再自动加团" }, { "name": "subject_config.allocate_start_time", "type": "string", "required": false, "source": "body.subject_config", "description": "开始自动分配时间,格式 HH:mm,默认 08:00,范围 00:00-23:59;作为自动分配初始时间,当前时间早于该时间与超过截单时间行为一致(不自动分配快递和储位、不自动加团)。与截单时间相同(自动分配窗口为空)时报 400" }, { "name": "subject_config.cutoff_order_time", "type": "string", "required": false, "source": "body.subject_config", "description": "截单时间,格式 HH:mm,默认 18:00,范围 00:00-23:59;作为最后允许自动分配的时间,开始时间晚于截单时间时截单时间视为次日(跨天窗口)" }, { "name": "subject_config.receiving_pending_inbound_notice", "type": "object", "required": false, "source": "body.subject_config", "description": "收货未入库提醒配置。开启后每天按提醒时间(notice_time)扫描「创建时间超过 min_hours 且不足 max_hours 仍未完成入库」的收货单:绑定货主的通知货主收货群(未配群回退仓库客服群),未绑定货主的通知仓库客服群" }, { "name": "subject_config.receiving_pending_inbound_notice.enabled", "type": "boolean", "required": false, "source": "body.subject_config", "description": "是否通知收货未入库(flag:0=关闭,1=开启;默认 0 关闭)。开启后收货未入库提醒定时任务才会在提醒时间执行;非法值报 400(字段级校验口径与其它 subject_config 字段一致)" }, { "name": "subject_config.receiving_pending_inbound_notice.notice_time", "type": "string", "required": false, "source": "body.subject_config", "description": "提醒时间,格式 HH:mm,默认 08:30,范围 00:00-23:59;定时任务按此时间(含 10 分钟宽限)每天提醒一次;非法值报 400(字段级校验口径与其它 subject_config 字段一致)" }, { "name": "subject_config.receiving_pending_inbound_notice.min_hours", "type": "number", "required": false, "source": "body.subject_config", "description": "超时下限(小时):收货单创建时间距今超过该值才提醒,默认 24,须为大于 0 的整数;非法值报 400(字段级校验口径与其它 subject_config 字段一致)" }, { "name": "subject_config.receiving_pending_inbound_notice.max_hours", "type": "number", "required": false, "source": "body.subject_config", "description": "超时上限(小时):收货单创建时间距今小于该值才提醒(超过则不再提醒),默认 48,须为大于 min_hours 的整数;非法值报 400(字段级校验口径与其它 subject_config 字段一致)" }, { "name": "subject_config.receiving_pending_inbound_notice.notice_template", "type": "string", "required": false, "source": "body.subject_config", "description": "通知短语(消息第一行,仓库/客服群)。支持变量:{warehouse} 仓库名 / {warehouse_id} 仓库ID / {store} 货主名(未绑定为「未绑定货主」)/ {store_id} 货主ID / {count} 本批单数 / {min_hours} 超时下限 / {max_hours} 超时上限 / {date} 提醒日期(YYYY-MM-DD)/ {numbers} 本批收货单号。未识别的占位符原样保留;短语后换行逐行列出明细(一行一条,最多 20 行),留空使用默认短语;最长 500 字符,超长报 400" }, { "name": "subject_config.receiving_pending_inbound_notice.store_notice_template", "type": "string", "required": false, "source": "body.subject_config", "description": "通知短语(消息第一行,货主群)。变量同 notice_template,留空使用默认短语;最长 500 字符,超长报 400" }, { "name": "subject_config.inbox_push_retry", "type": "object", "required": false, "description": "站内信推送失败自动重发配置(同「收货未入库提醒」的嵌套结构):开启后站内信回信/系统通知推送失败(如桥接离线返回 wx offline / qiwe offline)由定时任务每 3 分钟自动重发一次", "source": "body.subject_config" }, { "name": "subject_config.inbox_push_retry.enabled", "type": "number", "required": false, "description": "是否开启站内信推送失败自动重发(flag:0=关闭,1=开启;默认 0=关闭,需显式开启)", "source": "body.subject_config" }, { "name": "subject_config.inbox_push_retry.window_minutes", "type": "number", "required": false, "description": "重发时间范围(分钟,1-1440,默认 30):仅自动重发「失败时间在该范围内」的消息,超出范围不再补发;仅在 enabled 开启时生效", "source": "body.subject_config" } ], "response": [ { "name": "warehouse_id", "type": "number", "required": true, "description": "生效的仓库 ID" }, { "name": "subject_config", "type": "object", "required": true, "description": "保存后的 subject_config" }, { "name": "cache_cleared_warehouse_id", "type": "number", "required": true, "description": "被清理缓存的仓库 ID(若未清理则为 null)" }, { "name": "subject_config.enable_external_express_code", "type": "boolean", "required": true, "description": "保存后的 subject_config.enable_external_express_code 值" } ], "errors": [ { "code": "400", "message": "未识别到当前仓库/参数不合法" }, { "code": "400", "message": "subject_config.single_weigh_require_pack 必须是布尔值(仅接受 true/false/1/0 及其字符串)" }, { "code": "400", "message": "subject_config.big_group_pack_coefficient 必须是大于 0 的数字(非有限数字或小于等于 0 视为非法)" }, { "code": "404", "message": "仓库不存在" }, { "code": "500", "message": "保存失败" } ] }, { "method": "setting.warehouse.saveFrontConfig", "description": "保存当前仓库前端独立部署品牌配置(upsert,一仓一行,仅仓库主体可操作,仅品牌字段部分更新)。仅受理 title(≤100 字符)、logo_url/login_bg_url/favicon_url(≤255 字符)、theme(合法 JSON 对象或 JSON 字符串),空值清空。domain 与证书相关字段(domain/cert_pem/key_pem/cert_path/key_path/cert_expire_at)不再受理:方法层白名单静默忽略前端传值,domain 变更必须走 setting.warehouse.saveFrontCert(重新校验证书)。保存即重置同步状态(sync_status=0、sync_attempts=0、清空 last_sync_error/last_synced_at),写库成功后清理当前 domain 的公共拉取缓存(先写库后清缓存,清缓存失败仅记日志)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "title", "type": "string", "required": false, "source": "body", "description": "站点标题(可选,≤100 字符,超长报 400,空值清空)" }, { "name": "logo_url", "type": "string", "required": false, "source": "body", "description": "Logo 地址(可选,≤255 字符,超长报 400,空值清空)" }, { "name": "favicon_url", "type": "string", "required": false, "source": "body", "description": "站点 favicon 图标地址(可选,≤255 字符,超长报 400,空值清空)" }, { "name": "login_bg_url", "type": "string", "required": false, "source": "body", "description": "登录页背景图地址(可选,≤255 字符,超长报 400,空值清空)" }, { "name": "theme", "type": "object|string", "required": false, "source": "body", "description": "主题配置(可选,合法 JSON 对象或 JSON 字符串,否则报 400「theme 必须是合法的 JSON 对象」;空值清空)" } ], "response": [ { "name": "warehouse_id", "type": "number", "required": true, "description": "当前仓库 ID" }, { "name": "domain", "type": "string", "required": true, "description": "仓库自持域名(未配置为空字符串)" }, { "name": "title", "type": "string", "required": true, "description": "站点标题(未配置为空字符串)" }, { "name": "logo_url", "type": "string", "required": true, "description": "Logo 地址(未配置为空字符串)" }, { "name": "favicon_url", "type": "string", "required": true, "description": "站点 favicon 图标地址(未配置为空字符串)" }, { "name": "login_bg_url", "type": "string", "required": true, "description": "登录页背景图地址(未配置为空字符串)" }, { "name": "theme", "type": "object", "required": true, "description": "主题配置对象(未配置为 null)" }, { "name": "cert_pem", "type": "string", "required": true, "description": "证书 PEM 原文(读 cert_pem 列;未配置为空字符串;仅登录仓库主体 settings 页接口回显,公共无鉴权接口 frontConfig.getByDomain 不返回)" }, { "name": "key_pem", "type": "string", "required": true, "description": "私钥 PEM 原文(读 cert_key 列;未配置为空字符串;仅登录仓库主体 settings 页接口回显,公共无鉴权接口 frontConfig.getByDomain 不返回)" }, { "name": "cert_expire_at", "type": "string", "required": true, "description": "证书到期时间(由 saveFrontCert 上传证书后权威写入;未上传为 null)" }, { "name": "sync_status", "type": "number", "required": true, "description": "同步状态(0-待同步/1-同步成功/2-同步失败;本次保存后重置为 0)" }, { "name": "sync_attempts", "type": "number", "required": true, "description": "同步尝试次数(本次保存后重置为 0)" }, { "name": "last_sync_error", "type": "string", "required": true, "description": "最近一次同步失败原因(本次保存后清空)" }, { "name": "last_synced_at", "type": "string", "required": true, "description": "最近一次同步成功时间(本次保存后清空,可为 null)" }, { "name": "updated_at", "type": "string", "required": true, "description": "配置更新时间" } ], "errors": [ { "code": "400", "message": "未识别到当前仓库,无法操作仓库设置" }, { "code": "400", "message": "title/logo_url/login_bg_url/favicon_url 超长(title 长度不能超过 100 字符、其余不能超过 255 字符)/theme 非合法 JSON 对象" }, { "code": "403", "message": "仅仓库主体可配置前端独立部署(业务层 isWarehouse 判定)" }, { "code": "409", "message": "并发写入兜底:仓库前端配置保存冲突,请稍后重试" }, { "code": "500", "message": "签约关系服务不可用/WarehouseFrontConfig model 不可用/保存仓库前端配置失败" } ] }, { "method": "setting.warehouse.getFrontConfig", "description": "查询当前仓库前端独立部署配置(settings 页回显,仅登录仓库主体可调用)。无入参;按当前登录仓库 store_id 查询 wms_warehouse_front_config(一仓一行),无记录时返回默认空配置(warehouse_id 为当前仓库 ID,其余字段为空值/null)。响应 15 字段,含证书 PEM 原文(cert_pem,读 cert_pem 列)与私钥 PEM 原文(key_pem,读 cert_key 列)回显、未配置均为空字符串;公共无鉴权接口 frontConfig.getByDomain 仍仅返回 6 个公开字段白名单(domain/title/logo_url/login_bg_url/favicon_url/theme),不暴露证书/私钥内容。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [ { "name": "warehouse_id", "type": "number", "required": true, "description": "当前仓库 ID" }, { "name": "domain", "type": "string", "required": true, "description": "仓库自持域名(未配置为空字符串)" }, { "name": "title", "type": "string", "required": true, "description": "站点标题(未配置为空字符串)" }, { "name": "logo_url", "type": "string", "required": true, "description": "Logo 地址(未配置为空字符串)" }, { "name": "favicon_url", "type": "string", "required": true, "description": "站点 favicon 图标地址(未配置为空字符串)" }, { "name": "login_bg_url", "type": "string", "required": true, "description": "登录页背景图地址(未配置为空字符串)" }, { "name": "theme", "type": "object", "required": true, "description": "主题配置对象(未配置为 null)" }, { "name": "cert_pem", "type": "string", "required": true, "description": "证书 PEM 原文(读 cert_pem 列;未配置为空字符串;仅登录仓库主体 settings 页接口回显,公共无鉴权接口 frontConfig.getByDomain 不返回)" }, { "name": "key_pem", "type": "string", "required": true, "description": "私钥 PEM 原文(读 cert_key 列;未配置为空字符串;仅登录仓库主体 settings 页接口回显,公共无鉴权接口 frontConfig.getByDomain 不返回)" }, { "name": "cert_expire_at", "type": "string", "required": true, "description": "证书到期时间(由 saveFrontCert 上传证书后权威写入;未上传为 null)" }, { "name": "sync_status", "type": "number", "required": true, "description": "同步状态(0-待同步/1-同步成功/2-同步失败,无记录为 0)" }, { "name": "sync_attempts", "type": "number", "required": true, "description": "同步尝试次数(无记录为 0)" }, { "name": "last_sync_error", "type": "string", "required": true, "description": "最近一次同步失败原因(无记录为空字符串)" }, { "name": "last_synced_at", "type": "string", "required": true, "description": "最近一次同步成功时间(无记录为 null)" }, { "name": "updated_at", "type": "string", "required": true, "description": "配置更新时间(无记录为 null)" } ], "errors": [ { "code": "400", "message": "未识别到当前仓库,无法操作仓库设置" }, { "code": "500", "message": "WarehouseFrontConfig model 不可用/获取仓库前端配置失败" } ] }, { "method": "setting.warehouse.saveFrontCert", "description": "上传当前仓库前端独立部署证书(upsert,一仓一行,需登录、仅仓库主体可操作)。入参 domain + pem/key 成对必填:校验链为证书可解析 → 未生效/已过期拒绝 → 私钥与证书成对(SPKI 公钥指纹比对)→ 证书 SAN DNS/CN 覆盖 domain(支持精确匹配与 *.example.com 通配,不覆盖报 400),任一证书校验失败均返回统一文案「证书不合法」(400,不返回细节)。通过后自动写入 cert_expire_at(证书 validTo 权威值,不接受前端传值),证书/私钥 PEM 内容直接写入 cert_pem/cert_key 列入库(不再写暂存文件,内容供定时任务读取、禁止写入日志),cert_path/key_path 保存时置空、等待未来定时任务部署证书后回填真实路径,domain 全局唯一(非空,已被其他仓库使用报 409)。保存即重置同步状态(sync_status=0、sync_attempts=0、清空 last_sync_error/last_synced_at),写库成功后清理旧 domain 与新 domain 的公共拉取缓存(先写库后清缓存,清缓存失败仅记日志)。响应 15 字段含证书 PEM 原文(cert_pem)与私钥 PEM 原文(key_pem)回显,仅登录仓库主体 settings 页接口回显;公共无鉴权接口 frontConfig.getByDomain 不返回证书内容。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "domain", "type": "string", "required": true, "source": "body", "description": "仓库自持域名(必填,trim 后非空,≤100 字符;全局唯一,已被其他仓库使用报 409)" }, { "name": "pem", "type": "string", "required": true, "source": "body", "description": "证书 PEM 文本(必填,≤65536 字符,超长报 400「pem 内容长度不能超过 65536 字符」;须能解析为 X.509 证书、未过期且 SAN/CN 覆盖 domain)" }, { "name": "key", "type": "string", "required": true, "source": "body", "description": "私钥 PEM 文本(必填,≤65536 字符,超长报 400「key 内容长度不能超过 65536 字符」;须与 pem 成对,按 SPKI 公钥指纹比对不匹配报 400)" } ], "response": [ { "name": "warehouse_id", "type": "number", "required": true, "description": "当前仓库 ID" }, { "name": "domain", "type": "string", "required": true, "description": "保存后的域名(本次上传生效)" }, { "name": "title", "type": "string", "required": true, "description": "站点标题(未配置为空字符串)" }, { "name": "logo_url", "type": "string", "required": true, "description": "Logo 地址(未配置为空字符串)" }, { "name": "favicon_url", "type": "string", "required": true, "description": "站点 favicon 图标地址(未配置为空字符串)" }, { "name": "login_bg_url", "type": "string", "required": true, "description": "登录页背景图地址(未配置为空字符串)" }, { "name": "theme", "type": "object", "required": true, "description": "主题配置对象(未配置为 null)" }, { "name": "cert_pem", "type": "string", "required": true, "description": "证书 PEM 原文(读 cert_pem 列,本次上传后即回显;仅登录仓库主体 settings 页接口回显,公共无鉴权接口 frontConfig.getByDomain 不返回)" }, { "name": "key_pem", "type": "string", "required": true, "description": "私钥 PEM 原文(读 cert_key 列,本次上传后即回显;仅登录仓库主体 settings 页接口回显,公共无鉴权接口 frontConfig.getByDomain 不返回)" }, { "name": "cert_expire_at", "type": "string", "required": true, "description": "证书到期时间(后端按证书 validTo 权威写入,非入参)" }, { "name": "sync_status", "type": "number", "required": true, "description": "同步状态(0-待同步/1-同步成功/2-同步失败;本次上传后重置为 0)" }, { "name": "sync_attempts", "type": "number", "required": true, "description": "同步尝试次数(本次上传后重置为 0)" }, { "name": "last_sync_error", "type": "string", "required": true, "description": "最近一次同步失败原因(本次上传后清空)" }, { "name": "last_synced_at", "type": "string", "required": true, "description": "最近一次同步成功时间(本次上传后清空,可为 null)" }, { "name": "updated_at", "type": "string", "required": true, "description": "配置更新时间" } ], "errors": [ { "code": "400", "message": "domain 不能为空/domain 长度不能超过 100 字符/pem 不能为空/key 不能为空/pem|key 内容长度不能超过 65536 字符" }, { "code": "400", "message": "证书校验失败统一文案「证书不合法」:无法解析为 X.509 PEM 证书/证书未生效/证书已过期/私钥无法解析/私钥与证书不匹配/SAN-CN 不覆盖 domain" }, { "code": "400", "message": "未识别到当前仓库,无法操作仓库设置" }, { "code": "403", "message": "仅仓库主体可配置前端独立部署(业务层 isWarehouse 判定)" }, { "code": "409", "message": "域名 {domain} 已被其他仓库使用(含并发唯一索引冲突兜底:仓库前端配置保存冲突,请稍后重试)" }, { "code": "500", "message": "签约关系服务不可用/WarehouseFrontConfig model 不可用" } ] } ] }, { "groupName": "平台编码管理模块", "module": "setting.platform", "list": [ { "method": "index.getPlatformList", "description": "获取平台列表。默认返回系统基础平台与当前登录仓库自定义平台设置的合并结果:系统平台在前,仓库自定义编码在后,同一 `code` 仅保留首条(系统同码优先保留系统记录)。当 `systemOnly` 为真值(支持 `true`、`1`、`'1'`、`'true'`)时,仅返回系统基础平台列表。`full` 为真值时返回全量字段(包含 wms_platform 全部表字段、route_platform_code、platid 等)。仓库范围来自当前登录用户 `ctx.user.store_id`;未识别到仓库时,自定义设置列表为空。接口优先读取缓存,未命中时回源 `wms_platform` 与 `wms_platfrom_setting`。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "systemOnly", "type": "boolean|number|string", "required": false, "source": "body", "description": "是否仅返回系统基础平台列表;仅 `true`、`1`、`'1'`、`'true'` 会被识别为 true,其余值按 false 处理。也支持 `is_system` 别名(若请求体中同时存在 `is_system` 和 `systemOnly`,优先使用 `is_system`)" }, { "name": "full", "type": "boolean|number|string", "required": false, "source": "body", "description": "是否返回全量字段;仅 `true`、`1`、`'1'`、`'true'` 会被识别为 true,其余值按 false 处理。为 true 时返回 wms_platform 全部表字段、route_platform_code、platid 等扩展信息" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "全局调用结果标识,成功时为 `success`" }, { "name": "code", "type": "number", "required": true, "description": "业务状态码,成功时返回 200" }, { "name": "message", "type": "string", "required": true, "description": "返回消息,成功时通常为 `ok`" }, { "name": "data", "type": "array", "required": true, "description": "平台列表数组。默认模式下先返回系统基础平台,再追加当前仓库自定义设置;`systemOnly=true` 时仅返回系统基础平台。每项字段如下:", "children": [ { "name": "code", "type": "string", "description": "平台编码。系统平台项为 `wms_platform.code`;仓库自定义项为 `wms_platfrom_setting.code`" }, { "name": "name", "type": "string", "description": "展示名称。系统平台项为 `wms_platform.name`;仓库自定义项格式为 `<自定义编码> (<系统平台名>)`,若未匹配到系统平台名则退化为自定义编码" }, { "name": "value", "type": "string", "description": "与 `code` 相同,供前端选项组件直接使用" }, { "name": "label", "type": "string", "description": "与 `name` 相同,供前端选项组件直接使用" }, { "name": "platform_code", "type": "string", "description": "系统平台编码。系统平台项与 `code` 相同;仓库自定义项为 `wms_platfrom_setting.platform_code`(即该自定义编码所关联的系统平台编码)" }, { "name": "platform_name", "type": "string", "description": "系统平台名称。系统平台项与 `name` 相同;仓库自定义项为关联的系统平台名称" }, { "name": "default_express_interface", "type": "string", "description": "默认快递接口编码。由 `wms_platform.print_platform_id` → `wms_print_platform.platform_code` 解析得到;未配置时为空字符串" }, { "name": "is_system_setting", "type": "boolean", "description": "是否为仓库自定义平台设置。`false` 表示系统基础平台,`true` 表示来自当前仓库 `wms_platfrom_setting` 的自定义编码" }, { "name": "id", "type": "number|null", "description": "仅仓库自定义平台设置项返回,为 `wms_platfrom_setting.id` 记录主键;系统平台项不返回该字段" }, { "name": "alias", "type": "string", "description": "仅仓库自定义平台设置项返回,当前固定为空字符串(设计预留字段);系统平台项不返回该字段" }, { "name": "(full 模式扩展字段)", "type": "object", "description": "当 `full=true` 时,每项额外包含:系统平台项追加 `interface_url`、`appkey`、`app_secret`、`token`、`version`、`shoptype`、`ordersource`、`component`、`print_platform_id`(以上均为 wms_platform 原始表字段)、`route_platform_code`(平台后处理路由编码)、`platid`(打印平台 platid,仅当 print_platform_id 可映射时);仓库自定义项追加 `warehouse_id`、`route_platform_code` 及 wms_platfrom_setting 全部原始字段" } ] } ], "errors": [ { "code": 500, "message": "获取平台列表失败(数据库或缓存访问异常)" } ] }, { "method": "setting.platform.list", "description": "查询当前仓库范围的平台设置列表", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "setting.platform.create", "description": "创建当前仓库范围的平台设置", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "setting.platform.update", "description": "更新当前仓库范围的平台设置", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "setting.platform.delete", "description": "删除当前仓库范围的平台设置", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] } ] }, { "groupName": "快递编码管理模块", "module": "setting.express", "list": [ { "method": "index.getExpressList", "description": "获取快递列表。默认返回系统基础快递与当前登录仓库自定义快递编码的合并结果:系统快递在前,仓库自定义编码在后,同一 `code` 仅保留首条(系统同码优先保留系统记录)。当 `systemOnly` 为真值(支持 `true`、`1`、`'1'`、`'true'`)时,仅返回系统基础快递列表。仅接受 `express_code` 入参,服务端会先 trim 再转为大写:`systemOnly=true` 时按系统快递编码过滤系统基础快递列表;`systemOnly=false` 时按自定义编码映射记录中的系统快递编码字段 `express_code` 过滤,仅返回当前登录仓库下匹配该系统快递编码的自定义编码列表,不再回传系统基础项。仓库范围来自当前登录用户 `ctx.user.store_id`;未识别到仓库时,自定义编码列表为空。接口优先读取缓存,未命中时回源 `wms_express` 与 `wms_express_setting`。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "systemOnly", "type": "boolean|number|string", "required": false, "source": "body", "description": "是否仅返回系统基础快递列表;仅 `true`、`1`、`'1'`、`'true'` 会被识别为 true,其余值按 false 处理" }, { "name": "express_code", "type": "string", "required": false, "source": "body", "description": "系统快递编码;服务端会去首尾空格并转为大写。`systemOnly=true` 时按该系统快递编码过滤系统基础快递列表;`systemOnly=false` 时按自定义映射记录中的系统快递编码字段 `express_code` 过滤当前仓库的自定义编码列表,而不是按自定义 `code` 过滤" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "全局调用结果标识,成功时为 `success`" }, { "name": "code", "type": "number", "required": true, "description": "业务状态码,成功时返回 200" }, { "name": "message", "type": "string", "required": true, "description": "返回消息,成功时通常为 `ok`" }, { "name": "data", "type": "array", "required": true, "description": "快递列表数组。默认模式下先返回系统基础快递,再追加当前仓库自定义编码;当传入 `express_code` 且 `systemOnly=false` 时,仅返回当前仓库下系统快递编码等于该 `express_code` 的自定义映射记录,不返回系统基础项。每项字段如下:", "children": [ { "name": "code", "type": "string", "description": "返回项编码。系统项为系统快递编码;仓库自定义项为自定义快递编码" }, { "name": "name", "type": "string", "description": "展示名称。系统项为快递名称;仓库自定义项格式通常为 `<自定义编码> (<系统快递名>)`,若未匹配到系统快递名则退化为自定义编码" }, { "name": "value", "type": "string", "description": "与 `code` 相同,供前端选项组件直接使用" }, { "name": "label", "type": "string", "description": "与 `name` 相同,供前端选项组件直接使用" }, { "name": "is_system_setting", "type": "boolean", "description": "是否为仓库自定义快递编码;`false` 表示系统基础快递,`true` 表示来自当前仓库 `wms_express_setting` 的自定义编码" }, { "name": "id", "type": "number|null", "description": "仓库自定义快递设置记录 ID;系统基础快递固定为 `null`" }, { "name": "alias", "type": "string|null", "description": "仓库自定义快递设置表中的原始名称(`wms_express_setting.name`);系统基础快递固定为 `null`" }, { "name": "express_code", "type": "string", "description": "仅仓库自定义快递编码项返回其关联的系统快递编码;当 `systemOnly=false` 且传入筛选值时,即按该字段匹配自定义映射记录。系统基础快递项通常不返回该字段" } ] } ], "errors": [ { "code": 500, "message": "获取快递列表失败(数据库或缓存访问异常)" } ] }, { "method": "setting.express.list", "description": "查询当前仓库范围的快递映射列表,支持 where + pagination", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page / pageSize,兼容 currentPage / page_size / size" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "统一 where 条件对象;推荐使用 { operator, value, type } 标准结构" } ], "response": [], "errors": [] }, { "method": "setting.express.listBase", "description": "返回系统快递基础列表(系统级别基础快递,不含仓库自定义)", "isNeedAuth": false, "isNeedLogin": true, "params": [], "response": [], "errors": [] }, { "method": "setting.express.create", "description": "创建快递映射,仅写入已实现字段(code、name、express_code 等)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "code", "type": "string", "required": true, "source": "body", "description": "快递映射编码;接口会转为大写" }, { "name": "name", "type": "string", "required": true, "source": "body", "description": "快递名称(最大 50 字符)" }, { "name": "express_code", "type": "string", "required": true, "source": "body", "description": "系统快递编码;同时支持驼峰写法 expressCode" } ], "response": [], "errors": [] }, { "method": "setting.express.checkCodeUnique", "description": "校验快递编码在当前仓库/主体维度唯一性,仅支持 code 与可选 id 排除自身", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "code", "type": "string", "required": true, "source": "body", "description": "待校验的快递编码" }, { "name": "id", "type": "number", "required": false, "source": "body", "description": "排除自身 id(更新时使用)" } ], "response": [], "errors": [] }, { "method": "setting.express.update", "description": "更新快递映射。必须提供 `id`(必填),且至少提供 `code`、`name` 或 `express_code` 中的一个用于更新;同时支持 `expressCode` 驼峰写法。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "快递记录ID;也兼容别名 `setting_id` / `settingId`" }, { "name": "code", "type": "string", "required": false, "source": "body", "description": "快递映射编码(最大 50 字符,接口会大写化并校验在当前仓库的唯一性)" }, { "name": "name", "type": "string", "required": false, "source": "body", "description": "快递名称(最大 50 字符)" }, { "name": "express_code", "type": "string", "required": false, "source": "body", "description": "系统快递编码(必须为系统已存在的编码);支持 `expressCode` 驼峰写法" } ], "response": [ { "name": "data", "type": "object", "required": true, "description": "更新后的快递映射对象(规范化字段)", "children": [ { "name": "id", "type": "number", "description": "记录ID" }, { "name": "warehouse_id", "type": "number", "description": "所属仓库ID" }, { "name": "code", "type": "string", "description": "快递映射编码" }, { "name": "name", "type": "string", "description": "快递名称" }, { "name": "express_code", "type": "string", "description": "系统快递编码" }, { "name": "express_name", "type": "string", "description": "系统快递名称(从系统快递表映射)" } ] } ], "errors": [ { "code": "400", "message": "id 参数不能为空" }, { "code": "400", "message": "至少需要提供一个可更新字段" }, { "code": "400", "message": "code 参数不能为空" }, { "code": "400", "message": "express_code 参数不能为空" }, { "code": "400", "message": "系统快递编码不存在" }, { "code": "404", "message": "快递映射不存在或无权限操作" }, { "code": "409", "message": "快递编码已被当前仓库使用" } ] }, { "method": "setting.express.delete", "description": "批量软删除快递映射;接受 ids 参数,已删除记录会在结果中标记。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "array", "required": true, "source": "body", "description": "待删除的映射ID数组;支持数组、逗号字符串或单个ID。" } ], "response": [ { "name": "ids", "type": "array", "required": true, "description": "请求中的所有 id 列表(原样返回)" }, { "name": "deleted_ids", "type": "array", "required": true, "description": "本次实际被软删除的 ID 列表(即原本未被删除的 ID)" }, { "name": "already_deleted_ids", "type": "array", "required": true, "description": "请求中已处于已删除状态的 ID 列表" }, { "name": "status", "type": "string", "required": true, "description": "固定返回 'deleted'" } ], "errors": [ { "code": "400", "message": "ids 参数不能为空或格式错误" }, { "code": "404", "message": "快递映射不存在或无权限操作" }, { "code": "409", "message": "存在快递接口引用的快递编码,无法删除" } ] } ] }, { "groupName": "快递接口管理", "module": "setting.expressInterface", "list": [ { "method": "setting.expressInterface.list", "description": "查询当前仓库范围的快递接口列表,支持 where + pagination;返回 data:{ list, total, page, page_size }。按 weight 升序、id 降序排序,优先按权重排序。每条记录新增 quantity/recycled_quantity/cancel_quantity/allocated_quantity 扁平字段,数据源为 index.getShopExpressList,按 sys_express_code/site_code/shipperno 三层匹配汇总。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,含 page、pageSize" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "筛选条件,支持 id/name/express_code/platform_code/sender_name/sender_tel/viewer/client_id/share_id/site_code/product_type/shop_name/is_enabled/quickWhere" } ], "response": [ { "name": "list", "type": "array", "required": true, "children": [ { "name": "id", "type": "number", "required": true, "description": "主键ID" }, { "name": "name", "type": "string", "required": true, "description": "接口名称" }, { "name": "express_code", "type": "string", "required": true, "description": "快递编码" }, { "name": "sys_express_code", "type": "string", "required": true, "description": "系统快递编码" }, { "name": "warehouse_id", "type": "number", "required": false, "description": "仓库ID" }, { "name": "shop_id", "type": "number", "required": false, "description": "店铺ID,未绑定时为 null" }, { "name": "platform_shop_id", "type": "number", "required": false, "description": "平台店铺ID" }, { "name": "template_id", "type": "string", "required": false, "description": "模板ID" }, { "name": "paymode", "type": "number", "required": false, "description": "付款方式" }, { "name": "brandno", "type": "string", "required": false, "description": "品牌编码" }, { "name": "providertype", "type": "string", "required": false, "description": "服务商类型编码" }, { "name": "providerid", "type": "number", "required": false, "description": "服务商ID" }, { "name": "platform_code", "type": "string", "required": true, "description": "平台编码(PDD/CAINIAO/DY/KS/SPH/XHS/JD/QT)" }, { "name": "sender_name", "type": "string", "required": false, "description": "寄件人" }, { "name": "sender_tel", "type": "string", "required": false, "description": "寄件电话" }, { "name": "weight", "type": "number", "required": false, "description": "排序权重" }, { "name": "weight_type", "type": "number", "required": false, "description": "重量类型" }, { "name": "viewer", "type": "string", "required": false, "description": "查看者/备注" }, { "name": "client_id", "type": "string", "required": false, "description": "客户ID" }, { "name": "is_enabled", "type": "number", "required": false, "description": "是否启用(1启用 0禁用)" }, { "name": "is_share", "type": "number", "required": false, "description": "是否共享" }, { "name": "ispickup", "type": "number", "required": false, "description": "是否上门取件" }, { "name": "shipperno", "type": "string", "required": false, "description": "发货编号/客户代码" }, { "name": "template_url", "type": "string", "required": false, "description": "模板URL" }, { "name": "ext_data", "type": "object", "required": false, "description": "扩展数据(JSON对象)" }, { "name": "province_name", "type": "string", "required": false, "description": "省份" }, { "name": "city_name", "type": "string", "required": false, "description": "城市" }, { "name": "district_name", "type": "string", "required": false, "description": "区县" }, { "name": "address", "type": "string", "required": false, "description": "详细地址" }, { "name": "town_name", "type": "string", "required": false, "description": "镇/街道" }, { "name": "site_code", "type": "string", "required": false, "description": "网点编码" }, { "name": "product_type", "type": "string", "required": false, "description": "产品类型" }, { "name": "shop_name", "type": "string", "required": false, "description": "店铺名称" }, { "name": "express", "type": "object", "required": false, "description": "关联的系统快递对象", "children": [ { "name": "code", "type": "string", "required": false, "description": "系统快递编码" }, { "name": "name", "type": "string", "required": false, "description": "快递名称" }, { "name": "polyapi_code", "type": "string", "required": false, "description": "PolyAPI编码" }, { "name": "polyapi_extra_info", "type": "string", "required": false, "description": "PolyAPI扩展信息" }, { "name": "pdd_code", "type": "string", "required": false, "description": "拼多多快递编码" }, { "name": "ks_code", "type": "string", "required": false, "description": "快手快递编码" }, { "name": "dyxd_code", "type": "string", "required": false, "description": "抖音快递编码" } ] }, { "name": "express_name", "type": "string", "required": false, "description": "快递名称(扁平字段)" }, { "name": "express_polyapi_extra_info", "type": "string", "required": false, "description": "PolyAPI扩展信息(扁平字段)" }, { "name": "express_pdd_code", "type": "string", "required": false, "description": "拼多多快递编码(扁平字段)" }, { "name": "is_system_express_code", "type": "number", "required": true, "description": "是否为系统快递编码(1是 0否)" }, { "name": "quantity", "type": "number", "required": true, "description": "可用面单数量(从店铺快递签约数据汇总),无店铺或无数据时为 0" }, { "name": "recycled_quantity", "type": "number", "required": true, "description": "已回收面单数量" }, { "name": "cancel_quantity", "type": "number", "required": true, "description": "已取消面单数量" }, { "name": "allocated_quantity", "type": "number", "required": true, "description": "已分配面单数量" } ], "description": "list,按 weight 升序、id 降序排序;优先按权重排序,权重相同再按 id 倒序" }, { "name": "total", "type": "number", "required": true, "description": "总记录数" }, { "name": "page", "type": "number", "required": true, "description": "当前页码" }, { "name": "page_size", "type": "number", "required": true, "description": "每页条数" } ], "errors": [] }, { "method": "setting.expressInterface.listByWarehousePlatformCode", "description": "按 warehouse_id + platform_code 查询快递接口全字段数组,支持缓存;返回结果按 weight 升序、必要时按 id 升序排序,每条记录显式包含 express_code 以及关联的 express 对象(如 express.id/express.code/express.name/express.platform)。该接口不分页,按 warehouse_id + platform_code 全量返回匹配记录。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "warehouse_id / warehouseId", "type": "number", "required": false, "source": "body", "description": "仓库ID;默认使用当前登录主体/仓库上下文(ctx.user.store_id),也支持显式传入以查询指定仓库,文档兼容 warehouse_id 与 warehouseId 两种写法。" }, { "name": "platform_code / platformCode", "type": "string", "required": true, "source": "body", "description": "平台代码;作为缓存键的一部分,建议使用大写形式(服务端会标准化处理)。" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "快递接口记录数组(按 warehouse_id + platform_code 全量返回,不分页),每项包含以下字段:", "children": [ { "name": "id", "type": "number", "description": "记录ID" }, { "name": "name", "type": "string", "description": "接口名称" }, { "name": "express_code", "type": "string", "description": "快递编码" }, { "name": "warehouse_id", "type": "number", "description": "所属仓库ID(文档中的仓库范围由系统强制校验)" }, { "name": "platform_code", "type": "string", "description": "平台代码" }, { "name": "express_platform_id", "type": "number", "description": "平台接口ID" }, { "name": "sender_name", "type": "string", "description": "发件人姓名" }, { "name": "sender_tel", "type": "string", "description": "发件人电话" }, { "name": "weight", "type": "number", "description": "默认重量" }, { "name": "token", "type": "string", "description": "接口密钥或 token(部分记录可能为空)" }, { "name": "viewer", "type": "string", "description": "查看者标识" }, { "name": "client_id", "type": "string", "description": "客户端 ID" }, { "name": "is_share", "type": "number", "description": "是否共享(0/1)" }, { "name": "share_id", "type": "number", "description": "共享记录ID" }, { "name": "can_use_count", "type": "number", "description": "可用次数或配额" }, { "name": "province_name", "type": "string", "description": "省" }, { "name": "city_name", "type": "string", "description": "市" }, { "name": "district_name", "type": "string", "description": "区/县" }, { "name": "site_code", "type": "string", "description": "站点编码" }, { "name": "product_type", "type": "string", "description": "快递产品类型" }, { "name": "shop_name", "type": "string", "description": "店铺名称/分组标识" }, { "name": "ext_data", "type": "object", "description": "扩展信息 JSON(支持任意键值对象)" }, { "name": "express", "type": "object", "description": "关联的快递对象(若存在),包含基础快递信息,便于前端展示与回源校验", "children": [ { "name": "id", "type": "number", "description": "快递主表 ID" }, { "name": "code", "type": "string", "description": "快递编码" }, { "name": "name", "type": "string", "description": "快递名称" }, { "name": "platform", "type": "string", "description": "所属平台标识" } ] } ] } ], "errors": [ { "code": "400", "description": "缺少 platform_code 或仓库上下文错误" }, { "code": "500", "description": "查询失败" } ] }, { "method": "setting.expressInterface.create", "description": "在当前仓库范围内创建快递接口,支持 shop_id/shopId 入参。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "name", "type": "string", "required": true, "source": "body", "description": "name" }, { "name": "express_code", "type": "string", "required": true, "source": "body", "description": "express_code" }, { "name": "platform_code", "type": "string", "required": true, "source": "body", "description": "platform_code" }, { "name": "shop_id", "type": "number", "required": false, "source": "body", "description": "店铺 ID(支持 shopId),正整数,可空;未传或空值按 null 处理" }, { "name": "address", "type": "string", "required": false, "source": "body", "description": "发件人详细地址(可选),使用 index.getShopExpressList 返回的 detail 字段值,非 full_address" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "新建记录 ID" } ], "errors": [] }, { "method": "setting.expressInterface.update", "description": "更新快递接口。至少传入一个可更新字段,仅更新传入的字段;id 兼容 interface_id / interfaceId 入参;shop_id 可空,传入时会同步刷新接口 token;name/express_code/platform_code/sys_express_code 变更会触发系统快递编码重新解析。更新成功后返回该记录的完整字段。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "快递接口ID,兼容 interface_id / interfaceId" }, { "name": "name", "type": "string", "required": false, "source": "body", "description": "接口名称" }, { "name": "express_code", "type": "string", "required": false, "source": "body", "description": "快递编码(存大写);与 platform_code / sys_express_code 任一变更时重新解析系统快递编码" }, { "name": "platform_code", "type": "string", "required": false, "source": "body", "description": "平台编码(PDD/CAINIAO/DY/KS/SPH/XHS/JD/QT)" }, { "name": "sys_express_code", "type": "string", "required": false, "source": "body", "description": "系统快递编码(支持 sysExpressCode);未传时按 express_code + platform_code 自动匹配" }, { "name": "shop_id", "type": "number", "required": false, "source": "body", "description": "店铺ID(支持 shopId),正整数可空;传入该字段会同步刷新接口 token" }, { "name": "platform_shop_id", "type": "number", "required": false, "source": "body", "description": "平台店铺ID(支持 platformShopId),正整数可空" }, { "name": "template_id", "type": "string", "required": false, "source": "body", "description": "模板ID(支持 templateId),空字符串按 null 处理" }, { "name": "paymode", "type": "number", "required": false, "source": "body", "description": "付款方式(支持 payMode)" }, { "name": "brandno", "type": "string", "required": false, "source": "body", "description": "品牌编码(支持 brandNo),空字符串按 null 处理" }, { "name": "providertype", "type": "string", "required": false, "source": "body", "description": "服务商类型编码(支持 providerType),空字符串按 null 处理" }, { "name": "providerid", "type": "number", "required": false, "source": "body", "description": "服务商ID(支持 providerId)" }, { "name": "sender_name", "type": "string", "required": false, "source": "body", "description": "寄件人(支持 senderName)" }, { "name": "sender_tel", "type": "string", "required": false, "source": "body", "description": "寄件电话(支持 senderTel)" }, { "name": "weight", "type": "number", "required": false, "source": "body", "description": "排序权重,可空" }, { "name": "weight_type", "type": "number", "required": false, "source": "body", "description": "重量类型(支持 weightType),可空" }, { "name": "viewer", "type": "string", "required": false, "source": "body", "description": "验视员/查看者" }, { "name": "client_id", "type": "string", "required": false, "source": "body", "description": "客户ID(支持 clientId)" }, { "name": "ispickup", "type": "number", "required": false, "source": "body", "description": "是否上门取件(支持 isPickup),1是 0否" }, { "name": "shipperno", "type": "string", "required": false, "source": "body", "description": "发货编号/寄件网点编码(支持 shipperNo)" }, { "name": "template_url", "type": "string", "required": false, "source": "body", "description": "打印模板URL(支持 templateUrl)" }, { "name": "province_name", "type": "string", "required": false, "source": "body", "description": "寄件人省份(支持 provinceName)" }, { "name": "city_name", "type": "string", "required": false, "source": "body", "description": "寄件人城市(支持 cityName)" }, { "name": "district_name", "type": "string", "required": false, "source": "body", "description": "寄件人区县(支持 districtName)" }, { "name": "address", "type": "string", "required": false, "source": "body", "description": "发件人详细地址,使用 index.getShopExpressList 返回的 detail 字段值,非 full_address" }, { "name": "town_name", "type": "string", "required": false, "source": "body", "description": "寄件人镇/街道(支持 townName)" }, { "name": "site_code", "type": "string", "required": false, "source": "body", "description": "网点编码(支持 siteCode)" }, { "name": "product_type", "type": "string", "required": false, "source": "body", "description": "产品类型/编码(支持 productType)" }, { "name": "shop_name", "type": "string", "required": false, "source": "body", "description": "平台店铺名称(支持 shopName)" }, { "name": "ext_data", "type": "object", "required": false, "source": "body", "description": "扩展数据 JSON 对象(支持 extData)" }, { "name": "is_enabled", "type": "number", "required": false, "source": "body", "description": "是否启用(支持 isEnabled),1启用 0停用" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "主键ID" }, { "name": "name", "type": "string", "required": true, "description": "接口名称" }, { "name": "express_code", "type": "string", "required": true, "description": "快递编码" }, { "name": "sys_express_code", "type": "string", "required": true, "description": "系统快递编码" }, { "name": "warehouse_id", "type": "number", "required": false, "description": "仓库ID" }, { "name": "shop_id", "type": "number", "required": false, "description": "店铺ID,未绑定时为 null" }, { "name": "platform_shop_id", "type": "number", "required": false, "description": "平台店铺ID" }, { "name": "template_id", "type": "string", "required": false, "description": "模板ID" }, { "name": "paymode", "type": "number", "required": false, "description": "付款方式" }, { "name": "brandno", "type": "string", "required": false, "description": "品牌编码" }, { "name": "providertype", "type": "string", "required": false, "description": "服务商类型编码" }, { "name": "providerid", "type": "number", "required": false, "description": "服务商ID" }, { "name": "platform_code", "type": "string", "required": true, "description": "平台编码(PDD/CAINIAO/DY/KS/SPH/XHS/JD/QT)" }, { "name": "sender_name", "type": "string", "required": false, "description": "寄件人" }, { "name": "sender_tel", "type": "string", "required": false, "description": "寄件电话" }, { "name": "weight", "type": "number", "required": false, "description": "排序权重" }, { "name": "weight_type", "type": "number", "required": false, "description": "重量类型" }, { "name": "viewer", "type": "string", "required": false, "description": "验视员/查看者" }, { "name": "client_id", "type": "string", "required": false, "description": "客户ID" }, { "name": "is_enabled", "type": "number", "required": false, "description": "是否启用(1启用 0禁用)" }, { "name": "is_share", "type": "number", "required": false, "description": "是否共享" }, { "name": "ispickup", "type": "number", "required": false, "description": "是否上门取件" }, { "name": "shipperno", "type": "string", "required": false, "description": "发货编号/寄件网点编码" }, { "name": "template_url", "type": "string", "required": false, "description": "打印模板URL" }, { "name": "ext_data", "type": "object", "required": false, "description": "扩展数据(JSON对象)" }, { "name": "province_name", "type": "string", "required": false, "description": "寄件人省份" }, { "name": "city_name", "type": "string", "required": false, "description": "寄件人城市" }, { "name": "district_name", "type": "string", "required": false, "description": "寄件人区县" }, { "name": "address", "type": "string", "required": false, "description": "发件人详细地址" }, { "name": "town_name", "type": "string", "required": false, "description": "寄件人镇/街道" }, { "name": "site_code", "type": "string", "required": false, "description": "网点编码" }, { "name": "product_type", "type": "string", "required": false, "description": "产品类型/编码" }, { "name": "shop_name", "type": "string", "required": false, "description": "店铺名称" }, { "name": "express", "type": "object", "required": false, "description": "关联的系统快递对象(未关联时为 null)" }, { "name": "express_name", "type": "string", "required": false, "description": "快递名称(扁平字段)" }, { "name": "express_polyapi_extra_info", "type": "string", "required": false, "description": "PolyAPI扩展信息(扁平字段)" }, { "name": "express_pdd_code", "type": "string", "required": false, "description": "拼多多快递编码(扁平字段)" } ], "errors": [ { "code": "400", "message": "id 参数不能为空" }, { "code": "400", "message": "至少需要提供一个可更新字段" }, { "code": "400", "message": "name 参数不能为空" }, { "code": "400", "message": "express_code 参数不能为空" }, { "code": "400", "message": "platform_code 参数不能为空" }, { "code": "400", "message": "字段校验失败(字段为空、长度超限或数值/JSON 格式非法)" }, { "code": "400", "message": "express_code 未匹配到系统快递编码" }, { "code": "400", "message": "platform_code 未匹配到打印平台编码" }, { "code": "404", "message": "快递接口不存在或无权限操作" }, { "code": "404", "message": "当前仓库下未找到对应店铺,无法同步快递接口 token" } ] }, { "method": "setting.expressInterface.delete", "description": "删除快递接口,支持 id 别名 interface_id / interfaceId;返回被删除记录 id 与所属 warehouse_id。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "快递接口ID;兼容 interface_id / interfaceId" } ], "response": [ { "name": "id", "type": "number", "description": "已删除记录 ID" }, { "name": "warehouse_id", "type": "number", "description": "记录所属仓库 ID" }, { "name": "deleted", "type": "boolean", "description": "是否已删除,成功时为 true" } ], "errors": [ { "code": "400", "description": "id 为空或格式错误" }, { "code": "404", "description": "快递接口不存在或无权限操作" } ] }, { "method": "index.getPrintPlatformList", "description": "获取打印平台全量列表。供前端新增、修改快递接口时下拉选择使用;仅返回未删除且状态为 `ACTIVE` 的打印平台,不分页,按 `platform_name` 升序、`id` 升序返回。接口不校验额外鉴权或权限点,但需要登录态。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [], "response": [ { "name": "flag", "type": "string", "required": true, "description": "全局调用结果标识,成功时为 `success`" }, { "name": "code", "type": "number", "required": true, "description": "业务状态码,成功时返回 200" }, { "name": "message", "type": "string", "required": true, "description": "返回消息,成功时通常为 `ok`" }, { "name": "data", "type": "array", "required": true, "description": "打印平台列表数组,不分页,仅包含未删除且状态为 `ACTIVE` 的平台;按 `platform_name` 升序、`id` 升序返回。每项字段如下:", "children": [ { "name": "id", "type": "number|null", "description": "打印平台主键 ID;原始值为空时返回 `null`" }, { "name": "code", "type": "string", "description": "打印平台编码,等同于 `platform_code`,服务端会标准化为大写" }, { "name": "name", "type": "string", "description": "打印平台展示名称;若原始 `platform_name` 为空,则回退为 `platform_code`" }, { "name": "value", "type": "string", "description": "与 `code` 相同,供前端选项组件直接使用" }, { "name": "label", "type": "string", "description": "与 `name` 相同,供前端选项组件直接使用" }, { "name": "platform_code", "type": "string", "description": "打印平台编码,大写返回" }, { "name": "platform_name", "type": "string|null", "description": "打印平台名称;为空时前端可使用 `name` 或 `label` 展示" }, { "name": "status", "type": "string", "description": "平台状态;当前接口仅返回 `ACTIVE`,若原始值缺失会兜底为 `ACTIVE`" }, { "name": "remark", "type": "string|null", "description": "打印平台备注;无备注时返回 `null`" } ] } ], "errors": [ { "code": 500, "message": "获取打印平台列表失败" } ] } ] }, { "groupName": "账号管理模块", "module": "setting.account", "list": [ { "method": "setting.account.list", "description": "查询当前主体下的工号基础信息列表", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "status", "type": "number", "required": false, "source": "body", "description": "状态筛选,默认 1,仅查有效工号" }, { "name": "includeDisabled", "type": "boolean", "required": false, "source": "body", "description": "是否包含已删除工号" } ], "response": [ { "name": "data[]", "type": "object", "required": true, "description": "工号列表项" }, { "name": "data[].employee_id", "type": "number", "required": true, "description": "工号ID" }, { "name": "data[].account_id", "type": "number", "required": true, "description": "账号ID" }, { "name": "data[].store_id", "type": "number", "required": true, "description": "主体ID" }, { "name": "data[].real_name", "type": "string", "required": true, "description": "工号姓名" }, { "name": "data[].status", "type": "number", "required": true, "description": "工号状态:1=启用,0=停用" }, { "name": "data[].username", "type": "string", "required": true, "description": "账号用户名" }, { "name": "data[].phone", "type": "string", "required": true, "description": "账号手机号" }, { "name": "data[].email", "type": "string", "required": true, "description": "账号邮箱" }, { "name": "data[].avatar_file_id", "type": "number", "required": false, "description": "头像文件ID,为空表示未设置" }, { "name": "data[].avatar_url", "type": "string", "required": true, "description": "头像访问地址" } ], "errors": [ { "code": "400", "description": "当前登录态缺少主体上下文(store_id)" }, { "code": "500", "description": "查询失败" } ] }, { "method": "setting.account.add", "description": "新增工号,按手机号复用或创建账号后绑定到当前主体", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "phone", "type": "string", "required": true, "source": "body", "description": "手机号,作为账号复用/创建依据" }, { "name": "real_name", "type": "string", "required": true, "source": "body", "description": "工号姓名,新增时禁止直接使用保留名称" }, { "name": "username", "type": "string", "required": false, "source": "body", "description": "新账号用户名,不传时系统自动生成" }, { "name": "password", "type": "string", "required": false, "source": "body", "description": "新账号密码,不传默认 111111" }, { "name": "role_id", "type": "number", "required": false, "source": "body", "description": "工号角色,不传时继承当前操作人工号角色" }, { "name": "email", "type": "string", "required": false, "source": "body", "description": "新账号邮箱,不传时按 username 自动生成" } ], "response": [ { "name": "employee_id", "type": "number", "required": true, "description": "新增或复用后的工号ID" }, { "name": "account_id", "type": "number", "required": true, "description": "绑定账号ID" }, { "name": "role_id", "type": "number", "required": true, "description": "绑定后的角色ID" }, { "name": "is_new_account", "type": "boolean", "required": true, "description": "是否为本次新建账号" }, { "name": "phone", "type": "string", "required": true, "description": "绑定账号手机号" }, { "name": "username", "type": "string", "required": true, "description": "绑定账号用户名" } ], "errors": [ { "code": "400", "description": "参数错误、手机号格式错误、或直接使用保留名称" }, { "code": "409", "description": "手机号对应账号已禁用、手机号已绑定当前主体工号、或用户名重复" }, { "code": "500", "description": "新增失败" } ] }, { "method": "setting.account.delete", "description": "删除工号绑定关系,仅停用工号,不删除账号", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "employee_id", "type": "number", "required": true, "source": "body", "description": "要删除的工号ID" } ], "response": [ { "name": "employee_id", "type": "number", "required": true, "description": "被停用的工号ID" }, { "name": "account_id", "type": "number", "required": true, "description": "关联账号ID" }, { "name": "status", "type": "string", "required": true, "description": "固定返回 deleted" }, { "name": "already_deleted", "type": "boolean", "required": false, "description": "可选,true 表示该工号原本已停用" } ], "errors": [ { "code": "400", "description": "参数错误或尝试删除当前登录工号" }, { "code": "404", "description": "工号不存在或无权限删除" }, { "code": "500", "description": "删除失败" } ] }, { "method": "setting.account.update", "description": "更新工号姓名和头像引用", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "employee_id", "type": "number", "required": true, "source": "body", "description": "要更新的工号ID" }, { "name": "real_name", "type": "string", "required": false, "source": "body", "description": "更新后的工号姓名" }, { "name": "file_id", "type": "number", "required": false, "source": "body", "description": "已有文件ID,作为头像引用" } ], "response": [ { "name": "employee_id", "type": "number", "required": true, "description": "更新后的工号ID" }, { "name": "real_name", "type": "string", "required": true, "description": "更新后的工号姓名" }, { "name": "avatar_file_id", "type": "number", "required": false, "description": "更新后的头像文件ID" }, { "name": "avatar_url", "type": "string", "required": true, "description": "更新后的头像地址" } ], "errors": [ { "code": "400", "description": "参数错误,未提供更新项" }, { "code": "404", "description": "工号或头像文件不存在" }, { "code": "500", "description": "更新失败" } ] }, { "method": "setting.account.getBindWechatCode", "description": "为指定工号账号获取微信绑定码", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "account_id", "type": "number", "required": true, "source": "body", "description": "目标账号ID,兼容 user_id / id" }, { "name": "longPoll", "type": "boolean", "required": false, "source": "body", "description": "是否开启长轮询等待状态变化,最长60秒" }, { "name": "waitTimeoutMs", "type": "number", "required": false, "source": "body", "description": "等待超时毫秒数,后端自动封顶60000" } ], "response": [], "errors": [] }, { "method": "setting.account.unbindWechat", "description": "为指定工号账号解绑微信", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "account_id", "type": "number", "required": true, "source": "body", "description": "目标账号ID,兼容 user_id / id" } ], "response": [], "errors": [] } ] }, { "groupName": "权限管理模块", "module": "setting.permission", "list": [ { "method": "setting.permission.list", "description": "查询权限树/权限列表,可附带指定角色的选中状态", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "role_id", "type": "number", "required": false, "source": "body", "description": "角色ID;传入后返回 selected 标记" }, { "name": "type", "type": "string", "required": false, "source": "body", "description": "权限类型筛选:web_pages/pda_pages/btns/api/miniprogram_pages/block" }, { "name": "keyword", "type": "string", "required": false, "source": "body", "description": "关键字模糊搜索 path/name/meta_title" }, { "name": "includeDisabled", "type": "boolean", "required": false, "source": "body", "description": "是否包含已停用权限" } ], "response": [], "errors": [] }, { "method": "setting.permission.add", "description": "新增权限节点", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "path", "type": "string", "required": true, "source": "body", "description": "权限路径" }, { "name": "type", "type": "string", "required": true, "source": "body", "description": "权限类型" }, { "name": "name", "type": "string", "required": false, "source": "body", "description": "权限名称" }, { "name": "parent_id", "type": "number", "required": false, "source": "body", "description": "父级权限ID" } ], "response": [], "errors": [] }, { "method": "setting.permission.update", "description": "更新权限节点信息", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "permission_id", "type": "number", "required": true, "source": "body", "description": "权限ID" } ], "response": [], "errors": [] }, { "method": "setting.permission.delete", "description": "批量停用权限节点", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "array", "required": true, "source": "body", "description": "待停用的权限ID数组" } ], "response": [], "errors": [] } ] }, { "groupName": "角色管理模块", "module": "setting.role", "list": [ { "method": "setting.role.list", "description": "获取当前主体可管理的角色树", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "includeDisabled", "type": "boolean", "required": false, "source": "body", "description": "是否包含已停用角色" }, { "name": "includeSystem", "type": "boolean", "required": false, "source": "body", "description": "是否包含系统角色域" } ], "response": [], "errors": [] }, { "method": "setting.role.permission", "description": "获取角色权限树(兼容旧入口,等同于 setting.permission.list)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "role_id", "type": "number", "required": false, "source": "body", "description": "角色ID" } ], "response": [], "errors": [] }, { "method": "setting.role.add", "description": "新增角色并绑定权限集合", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "role_code", "type": "string", "required": true, "source": "body", "description": "角色编码" }, { "name": "role_name", "type": "string", "required": true, "source": "body", "description": "角色名称" }, { "name": "permission_ids", "type": "array", "required": true, "source": "body", "description": "权限ID数组,支持 [\"*\"]" }, { "name": "pid", "type": "number", "required": false, "source": "body", "description": "父角色ID" } ], "response": [], "errors": [] }, { "method": "setting.role.update", "description": "更新角色信息并重设权限集合", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "role_id", "type": "number", "required": true, "source": "body", "description": "角色ID" }, { "name": "permission_ids", "type": "array", "required": true, "source": "body", "description": "权限ID数组,角色权限需一次性提交" } ], "response": [], "errors": [] }, { "method": "setting.role.delete", "description": "批量停用角色", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "array", "required": true, "source": "body", "description": "待停用的角色ID数组" } ], "response": [], "errors": [] } ] }, { "groupName": "商品模块", "module": "stock", "list": [ { "method": "stock.warehouse.list", "description": "仓库商品列表查询(支持 where 条件与分页)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "pagination 参数" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "统一 where 条件对象;推荐使用 { operator, value, type } 标准结构,历史简写会在 main 中自动标准化;支持 quickWhere、barcode、prohibited_type、has_bound_item 等商品筛选字段。示例:where.barcode={operator:like,value:69}; where.prohibited_type={operator:eq,value:liquid}; where.has_bound_item={operator:eq,value:true}(已绑定外部商品)/ where.has_bound_item={operator:eq,value:false}(未绑定外部商品)。" } ], "response": [], "errors": [] }, { "method": "stock.warehouse.externalList", "description": "外仓商品列表查询。传入 warehouse_id 按仓库维度查,不传则按当前货主维度查(store_id);where/分页语义与 stock.warehouse.list 一致;where.keyword 支持模糊搜索(item_code/item_name/goods_code)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "warehouse_id", "type": "number", "required": false, "source": "body", "description": "仓库ID(可选,不传则取当前用户上下文)" }, { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,与 stock.warehouse.list 一致" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "统一 where 条件对象,与 stock.warehouse.list 语义一致。支持 keyword 快捷搜索:where.keyword={operator:like,value:'关键字'}" } ], "response": [], "errors": [] }, { "method": "stock.warehouse.export", "description": "提交导出任务,返回 task_id/status/progress/message/result/error/update_time", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "where", "type": "object", "required": false, "source": "body", "description": "查询条件对象,与 stock.warehouse.list 的 where 语义一致;推荐使用 { operator, value, type } 标准结构,历史简写会在 main 中自动标准化。" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数对象,支持 sortField/sortOrder 与 sort_field/sort_order 下划线别名兼容。" }, { "name": "sort.sortField", "type": "string", "required": false, "source": "body.sort", "description": "排序字段(兼容 sort.sortField)。" }, { "name": "sort.sort_field", "type": "string", "required": false, "source": "body.sort", "description": "排序字段下划线别名(兼容 sort.sort_field)。" }, { "name": "sort.sortOrder", "type": "string", "required": false, "source": "body.sort", "description": "排序方向(ASC/DESC,大小写不敏感)。" }, { "name": "sort.sort_order", "type": "string", "required": false, "source": "body.sort", "description": "排序方向下划线别名(兼容 sort.sort_order)。" } ], "response": [ { "name": "task_id", "type": "string", "description": "任务 ID(后端生成的唯一标识)" }, { "name": "status", "type": "string", "description": "任务状态,枚举:submitted/running/success/failed/not_found" }, { "name": "progress", "type": "number", "description": "进度百分比(0-100)" }, { "name": "message", "type": "string", "description": "额外提示信息或受理消息" }, { "name": "result", "type": "object", "description": "任务成功时返回的结果对象(可选)" }, { "name": "error", "type": "string", "description": "失败时的错误信息(可选)" }, { "name": "update_time", "type": "string", "description": "最近一次状态更新时间,ISO8601 字符串(可选)" } ], "errors": [ { "code": 400, "message": "参数格式不正确或 where 条件非法" }, { "code": 500, "message": "导出任务提交失败" } ] }, { "method": "stock.warehouse.exportTaskProgress", "description": "按 task_id 查询导出任务进度,未找到时 status=not_found", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id / taskId", "type": "string", "required": true, "source": "body|query", "description": "任务 ID,兼容 taskId" } ], "response": [ { "name": "task_id", "type": "string", "description": "任务 ID" }, { "name": "status", "type": "string", "description": "任务状态:submitted/running/success/failed/not_found" }, { "name": "progress", "type": "number", "description": "进度百分比(0-100)" }, { "name": "message", "type": "string", "description": "额外提示信息" }, { "name": "result", "type": "object", "description": "任务成功时返回的结果对象(可选)" }, { "name": "error", "type": "string", "description": "失败时的错误信息(可选)" }, { "name": "download_url", "type": "string", "description": "任务完成后可直接下载的文件地址(若有)" }, { "name": "update_time", "type": "string", "description": "最近一次状态更新时间,ISO8601 字符串(可选)" } ], "errors": [ { "code": 400, "message": "task_id 参数不能为空" }, { "code": 500, "message": "查询失败或内部错误" } ] }, { "method": "stock.warehouse.getProhibitedType", "description": "查询违禁品类型列表(系统预设+仓库自定义)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "stock.warehouse.getInfo", "description": "查询仓库商品详情", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [ { "name": "need_recheck", "type": "string", "required": true, "description": "是否需要复核:Y=需要复核,N=不需要复核" } ], "errors": [] }, { "method": "stock.warehouse.getStockDetail", "description": "按库位/批次维度查询商品库存分布", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "stock_id", "type": "number", "required": true, "source": "body", "description": "商品库存ID(stock_warehouse.id)" }, { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,包含 page/pageSize" }, { "name": "group_by_batch", "type": "boolean", "required": false, "source": "body", "default": false, "description": "是否按批次返回明细;true 返回每条明细,false 按库位合并" } ], "response": [ { "name": "stockItem", "type": "object", "description": "商品概要,包含 id、item_code、item_name、sku_property、stock_unit、quantity、locked_quantity 等", "required": true }, { "name": "storageList", "type": "array", "description": "库存明细数组;group_by_batch=true 返回 wms_storage 明细(含 batch_no、production_date、expiry_date、inbound_time、inbound_order_no、supplier_batch_no 等),group_by_batch=false 时按库位合并(批次相关字段为 null),合并明细含 intercept_locked_quantity(拦截锁定数量,默认 0),available_quantity 统一口径 = quantity - locked_quantity - intercept_locked_quantity", "required": true }, { "name": "pagination", "type": "object", "description": "分页信息,包含 page、pageSize、total", "required": true } ], "errors": [] }, { "method": "stock.warehouse.saveWarehouseStock", "description": "更新仓库商品资料", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "need_recheck", "type": "string", "required": false, "source": "body", "description": "是否需要复核:Y=需要复核,N=不需要复核(非 Y/N 值会报错)" } ], "response": [], "errors": [] }, { "method": "stock.warehouse.createWarehouseStock", "description": "新建仓库商品资料", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "need_recheck", "type": "string", "required": false, "source": "body", "description": "是否需要复核:Y=需要复核,N=不需要复核;缺省默认 Y(需要复核)" } ], "response": [], "errors": [] }, { "method": "stock.warehouse.import", "description": "批量导入或更新仓库商品。请求体优先直接传入商品数据数组 JSON(主方式为数组);也兼容以 rows/items/list/data 包装。每项仅需包含商品相关字段;当 SKU 为空时创建新商品,SKU 非空时为更新操作;更新会写操作日志以便审计。未传 store_id 时默认使用当前上下文仓库/主体(ctx.user.store_id)。支持导入条码(barcode),新建和更新均生效,条码写入 wms_stock_barcodes 表。", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "items / rows / list / data", "type": "array", "required": true, "source": "body", "description": "商品数组(主方式为直接传数组 []),也兼容对象包装:{ rows: [...] } / { items: [...] } / { list: [...] } / { data: [...] }。每项可使用下列字段别名:", "children": [ { "name": "SKU / sku / id / item_id / itemId", "type": "string|number", "description": "SKU 或商品 ID(编辑/更新使用;为空时创建)" }, { "name": "商品编码 / item_code / itemCode", "type": "string", "description": "商品编码" }, { "name": "货物编码 / goods_code / goodsCode", "type": "string", "description": "货物编码(支持导入)" }, { "name": "SKU规格 / sku_property / skuProperty", "type": "string", "description": "规格信息" }, { "name": "库存单位 / stock_unit / stockUnit", "type": "string", "description": "库存单位" }, { "name": "品牌 / brand_name / brandName", "type": "string", "description": "品牌" }, { "name": "毛重 / gross_weight / grossWeight", "type": "number", "description": "毛重(数值,单位与系统一致)" }, { "name": "标价 / tag_price / tagPrice", "type": "number", "description": "标价" }, { "name": "零售价 / retail_price / retailPrice", "type": "number", "description": "零售价" }, { "name": "是否需要复核 / need_recheck / needRecheck", "type": "string", "required": false, "description": "是否需要复核,支持中文 需要/不需要 或 Y/N;缺省时新建按需要复核(Y)处理,更新保留原值" }, { "name": "条码 / bar_code / barCode / barcodeList / barcode_list / barcode", "type": "string", "required": false, "description": "条码列表,逗号分隔字符串,如 \"6901234567890,6901234567891\"。与导出格式一致。新建和更新均支持,条码存储在 wms_stock_barcodes 表。" }, { "name": "store_id / storeId", "type": "number", "required": false, "source": "body", "description": "可选,货主/仓库 ID;未传入时使用当前上下文(ctx.user.store_id)" } ] } ], "response": [ { "name": "total_count", "type": "number", "required": true, "description": "解析到的总条目数" }, { "name": "created_count", "type": "number", "required": true, "description": "成功创建的新商品数" }, { "name": "updated_count", "type": "number", "required": true, "description": "成功更新的商品数" }, { "name": "fail_count", "type": "number", "required": true, "description": "导入失败数" }, { "name": "created_ids", "type": "array", "required": true, "description": "创建成功的商品 ID 列表" }, { "name": "updated_ids", "type": "array", "required": true, "description": "更新成功的商品 ID 列表" }, { "name": "fail_items", "type": "array", "required": true, "description": "失败项明细数组,每项包含原始输入与错误信息" } ], "errors": [ { "code": "400", "message": "导入数据不能为空" }, { "code": "400", "message": "缺少仓库上下文" }, { "code": "400", "message": "导入行数据无效" }, { "code": "500", "message": "导入失败" } ] }, { "method": "stock.warehouse.getBarcodes", "description": "查询商品条码列表", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "stock.warehouse.saveWarehouseStockBarcode", "description": "保存商品条码信息", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "stock.warehouse.getStoreStocks", "description": "查询仓库商品与货主关联列表", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "stock.warehouse.bindItem", "description": "绑定货主商品关系", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "stock.warehouse.unbindItem", "description": "解绑货主商品关系", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "stock.warehouse.checkItemCodeUnique", "description": "检测商品编码唯一性。在同一仓库和货主下,排除商品自身后,判断商品编码是否已存在于未删除商品中。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "warehouse_id", "type": "number", "required": true, "source": "body", "description": "仓库ID;默认使用当前登录主体/仓库上下文(ctx.user.store_id)" }, { "name": "item_code", "type": "string", "required": true, "source": "body", "description": "要检测的商品编码" }, { "name": "item_id", "type": "number", "required": false, "source": "body", "description": "当前商品ID(编辑场景用,排除自身);兼容字段名 id" }, { "name": "id", "type": "number", "required": false, "source": "body", "description": "兼容字段 id" }, { "name": "owner_id", "type": "number", "required": true, "source": "body", "description": "货主ID(对应表字段 store_id);兼容字段名 store_id" }, { "name": "store_id", "type": "number", "required": true, "source": "body", "description": "兼容字段 store_id" } ], "response": [ { "name": "unique", "type": "boolean", "description": "true 表示编码唯一,false 表示已存在重复" }, { "name": "isUnique", "type": "boolean", "description": "同 unique(兼容旧字段名)" }, { "name": "message", "type": "string", "description": "重复时返回 '商品编码已存在',唯一时不返回该字段", "required": false } ], "errors": [] }, { "method": "stock.warehouse.queryStockLogs", "description": "查询库存操作日志", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "warehouseId", "type": "string", "required": false, "source": "body", "description": "warehouseId 参数" } ], "response": [], "errors": [] }, { "method": "stock.warehouse.handleBatchDelete", "description": "批量删除仓库商品资料", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "stock.warehouse.deleteUnit", "description": "删除库存单位", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "stock.warehouse.deleteProhibited", "description": "删除违禁品类型", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "stock.warehouse.handleBatchChange", "description": "批量修改仓库商品字段", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "array", "required": true, "source": "body", "description": "要批量修改的仓库商品记录 ID 数组(stock_warehouse.id)", "children": [ { "name": "id", "type": "number", "description": "单个记录 ID" } ] }, { "name": "method", "type": "string", "required": true, "source": "body", "description": "要修改的字段名,可选值:brand_name、prohibited_id、gross_weight、packing_requirements、managementFlags、stock_unit、need_recheck" }, { "name": "value", "type": "string|number|object", "required": true, "source": "body", "description": "修改值,类型依 method 而定:brand_name/packing_requirements/stock_unit 为 string(<=255 字符);prohibited_id 为 number(整数);gross_weight 为 number(正整数,单位 g);managementFlags 为 object,必须包含 is_sn_mgmt/is_shelf_life_mgmt/is_batch_mgmt,值为 'Y' 或 'N';need_recheck 为 string,仅支持 'Y'(需要复核)/ 'N'(不需要复核)" }, { "name": "values", "type": "any", "required": false, "source": "body", "description": "兼容字段:当前实现以 `value` 为准,不使用 `values`。若客户端历史使用 `values`,请切换为 `value`。" } ], "response": [ { "name": "code", "type": "number", "description": "业务状态码,200 表示成功;405 表示参数/权限校验不通过;500 表示服务器错误" }, { "name": "message", "type": "string", "description": "业务提示信息" }, { "name": "data", "type": "object", "description": "成功时返回的结果对象", "children": [ { "name": "affectedRows", "type": "number", "description": "被更新的记录数" }, { "name": "ids", "type": "array", "description": "请求中传入的 ids 数组" } ] } ], "errors": [ { "code": "405", "description": "请选择要修改的商品(缺少 ids 或 ids 为空)" }, { "code": "405", "description": "不支持修改的字段: {method}" }, { "code": "405", "description": "修改值不能为空" }, { "code": "405", "description": "违禁品类型必须是数字" }, { "code": "405", "description": "毛重必须是有效的正数" }, { "code": "405", "description": "管理标识必须是对象格式 / 管理标识缺少字段 / 管理标识字段值必须是 'Y' 或 'N'" }, { "code": "405", "description": "部分商品不存在或无权修改: " }, { "code": "405", "description": "缺少仓库信息" }, { "code": "500", "description": "内部错误:批量修改失败" } ] }, { "method": "stock.warehouse.getStockUnits", "description": "查询可用库存单位(系统+仓库)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "stock.warehouse.getUnitList", "description": "查询当前仓库自定义单位列表", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "stock.warehouse.createProhibited", "description": "新增违禁品类型", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "name", "type": "string", "required": true, "source": "body", "description": "name 参数" } ], "response": [], "errors": [] }, { "method": "stock.warehouse.createUnit", "description": "新增库存单位", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "name", "type": "string", "required": true, "source": "body", "description": "name 参数" } ], "response": [], "errors": [] }, { "method": "stock.warehouse.search", "description": "仓库商品关键字搜索,按 item_code / item_name / goods_code / 条形码模糊匹配,最多返回 50 条。新增 mode=\"combo\" 时切换为组合商品搜索模式。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "keyword", "type": "string", "required": false, "source": "body", "description": "搜索关键字,模糊匹配 item_code、item_name、goods_code 以及关联的 barcode;为空时返回全部(仍受 limit 50 限制)。mode=\"combo\" 时模糊匹配 combo_code / combo_name / custom_code" }, { "name": "store_id", "type": "number", "required": false, "source": "body", "description": "货主ID,传入时仅返回指定货主的商品" }, { "name": "mode", "type": "string", "required": false, "source": "body", "description": "查询模式。传 \"combo\" 时搜索组合商品,不传或为空时保持原有 stock 搜索行为" }, { "name": "id", "type": "number", "required": false, "source": "body", "description": "当 mode=\"combo\" 时,按组合商品ID精确查询" }, { "name": "custom_code", "type": "string", "required": false, "source": "body", "description": "当 mode=\"combo\" 时,按自定义编码模糊查询" }, { "name": "with_stock", "type": "boolean", "required": false, "source": "body", "default": false, "description": "是否返回关联库存数据(wms_storage),为 true 时每条商品新增 storage[] 字段。注意:mode=\"combo\" 时不生效" }, { "name": "is_batch", "type": "boolean", "required": false, "source": "body", "default": false, "description": "是否按批次明细返回库存,仅 with_stock=true 时生效。false(默认)按库位分组汇总;true 逐条返回批次明细。注意:mode=\"combo\" 时不生效" } ], "response": [ { "name": "code", "type": "number", "description": "业务状态码,200 表示成功", "required": false }, { "name": "data", "type": "array", "description": "商品列表,每项包含以下字段。mode=\"combo\" 时返回组合商品结构", "children": [ { "name": "id", "type": "number", "description": "商品库存ID(stock_warehouse.id)。mode=\"combo\" 时返回组合商品ID", "required": false }, { "name": "item_code", "type": "string", "description": "商品编码。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "goods_code", "type": "string", "description": "货物编码。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "item_name", "type": "string", "description": "商品名称。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "sku_property", "type": "string", "description": "SKU 规格。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "stock_unit", "type": "string", "description": "库存单位。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "quantity", "type": "number", "description": "库存数量。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "locked_quantity", "type": "number", "description": "锁定数量。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "brand_name", "type": "string", "description": "品牌名称。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "item_type", "type": "string", "description": "商品类型。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "barcodes", "type": "array", "description": "商品条形码列表(string[])。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "images", "type": "array", "description": "商品图片URL列表(string[]),来自 wms_file_reference(business_type=stock)关联 wms_file.file_url,按 display_order 升序;无图片时为空数组。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "store_stock", "type": "object", "description": "关联的货主签约信息(LEFT JOIN),含 store_id、store_remask;无签约时为 null。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "is_shelf_life_mgmt", "type": "boolean", "description": "是否启用效期管理(true=启用)。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "shelf_life_days", "type": "number", "description": "商品标准效期/保质期(单位:天)。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "inbound_min_days", "type": "number", "description": "入库后最小可出库天数(单位:天)。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "outbound_min_days", "type": "number", "description": "出库前需保留的最小天数(单位:天)。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "remaining_threshold_days", "type": "number", "description": "剩余天数阈值,低于该值视为即将过期(单位:天)。mode=\"combo\" 时不返回此字段", "required": false }, { "name": "combo_code", "type": "string", "description": "组合商品编码,仅 mode=\"combo\" 时返回", "required": false }, { "name": "combo_name", "type": "string", "description": "组合商品名称,仅 mode=\"combo\" 时返回", "required": false }, { "name": "custom_code", "type": "string", "description": "自定义编码,仅 mode=\"combo\" 时返回", "required": false }, { "name": "items", "type": "array", "description": "子商品数组,仅 mode=\"combo\" 时返回。每项含 item_goods_sku_id(子商品ID)、item_quantity(子商品数量)", "children": [ { "name": "item_goods_sku_id", "type": "number", "description": "子商品SKU ID", "required": false }, { "name": "item_quantity", "type": "number", "description": "子商品数量", "required": false } ], "required": false }, { "name": "simpleNotation", "type": "string", "description": "子商品简写表示,格式为 stock_id|数量,多条用换行分隔。仅 mode=\"combo\" 时返回", "required": false }, { "name": "nameNotation", "type": "string", "description": "子商品名称表示,格式为【数量】商品名称,多条用换行分隔。仅 mode=\"combo\" 时返回", "required": false }, { "name": "storage", "type": "array", "description": "关联库存明细,仅 with_stock=true 时返回。is_batch=false 时按库位分组汇总,is_batch=true 时逐条返回批次明细。注意:mode=\"combo\" 时不返回", "children_grouped": { "description": "is_batch=false(默认):按库位分组汇总,每条包含以下字段", "fields": [ { "name": "space_id", "type": "number", "description": "库位ID", "required": false }, { "name": "inventory_type", "type": "string", "description": "库存类型", "required": false }, { "name": "quantity", "type": "number", "description": "该库位总库存数量(合并同库位)", "required": false }, { "name": "locked_quantity", "type": "number", "description": "该库位总锁定数量", "required": false }, { "name": "intercept_locked_quantity", "type": "number", "description": "该库位拦截锁定数量(拦截确认时不归还可用、移入该字段)", "required": false }, { "name": "available_quantity", "type": "number", "description": "可用数量(quantity - locked_quantity - intercept_locked_quantity)", "required": false }, { "name": "space", "type": "object", "description": "库位信息子对象,含 id、space_code、custom_name", "required": false } ] }, "children_batch": { "description": "is_batch=true:逐条批次明细,每条包含以下字段", "fields": [ { "name": "id", "type": "number", "description": "storage 记录ID", "required": false }, { "name": "stock_id", "type": "number", "description": "关联的商品库存ID", "required": false }, { "name": "space_id", "type": "number", "description": "库位ID", "required": false }, { "name": "batch_no", "type": "string", "description": "批次号", "required": false }, { "name": "inventory_type", "type": "string", "description": "库存类型", "required": false }, { "name": "quantity", "type": "number", "description": "库存数量", "required": false }, { "name": "locked_quantity", "type": "number", "description": "锁定数量", "required": false }, { "name": "intercept_locked_quantity", "type": "number", "description": "拦截锁定数量(默认 0)", "required": false }, { "name": "available_quantity", "type": "number", "description": "可用数量", "required": false }, { "name": "production_date", "type": "string", "description": "生产日期", "required": false }, { "name": "expiry_date", "type": "string", "description": "过期日期", "required": false }, { "name": "inbound_time", "type": "string", "description": "入库时间", "required": false }, { "name": "inbound_order_no", "type": "string", "description": "入库单号", "required": false }, { "name": "supplier_batch_no", "type": "string", "description": "供应商批次号", "required": false }, { "name": "created_at", "type": "string", "description": "记录创建时间", "required": false }, { "name": "space", "type": "object", "description": "库位信息子对象,含 id、space_code、custom_name", "required": false } ] }, "required": false } ], "required": false }, { "name": "total", "type": "number", "description": "本次返回的记录条数(≤50)", "required": false } ], "errors": [] }, { "method": "stock.transaction.list", "description": "商品出入库流水列表查询(wms_stock_transaction),支持 where 条件筛选与分页,支持 keyword 快捷搜索", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,包含 page / pageSize" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "统一 where 条件对象,支持以下字段:", "children": [ { "name": "start_time", "type": "string", "required": false, "description": "开始时间(闭区间下限),created_at >= start_time" }, { "name": "end_time", "type": "string", "required": false, "description": "结束时间(闭区间上限),created_at <= end_time" }, { "name": "store_ids", "type": "array", "required": false, "description": "货主ID数组,为空或未传表示不筛选" }, { "name": "stock_ids", "type": "array", "required": false, "description": "商品库存ID数组,为空或未传表示不筛选" }, { "name": "keyword", "type": "string", "required": false, "description": "快捷搜索关键字,支持按商品编码(item_code)、商品名称(item_name)、货物编码(goods_code)、条码(barcode)、SKU ID 模糊匹配。内部解析为 stock_id 列表后以 IN 条件合并查询。与 stock_ids 互斥(keyword 优先)" }, { "name": "transaction_type", "type": "string", "required": false, "description": "流水类型:INBOUND=入库 / OUTBOUND=出库 / TRANSFER_OUT=移库出 / TRANSFER_IN=移库入 / LOCK=锁定" }, { "name": "order_type", "type": "string", "required": false, "description": "单据类型筛选" }, { "name": "order_no", "type": "string", "required": false, "description": "单据号筛选(支持模糊匹配)" }, { "name": "batch_no", "type": "string", "required": false, "description": "批次号筛选" }, { "name": "entry_order_id", "type": "number", "required": false, "description": "入库单ID筛选" }, { "name": "receiving_id", "type": "number", "required": false, "description": "收货单ID筛选" }, { "name": "order_id", "type": "number", "required": false, "description": "发货单ID筛选" } ] }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数对象,支持 sortField / sortOrder 与 sort_field / sort_order 下划线别名兼容", "children": [ { "name": "sortField", "type": "string", "required": false, "description": "排序字段,白名单:created_at、quantity、stock_id、store_id。非法字段回退默认排序(created_at DESC)" }, { "name": "sort_field", "type": "string", "required": false, "description": "排序字段下划线别名(兼容 sort.sort_field),规则同 sortField" }, { "name": "sortOrder", "type": "string", "required": false, "description": "排序方向,ASC / DESC(大小写不敏感),非法值回退 DESC" }, { "name": "sort_order", "type": "string", "required": false, "description": "排序方向下划线别名(兼容 sort.sort_order),规则同 sortOrder" } ] } ], "response": [ { "name": "list", "type": "array", "description": "流水记录列表", "children": [ { "name": "id", "type": "number", "description": "流水记录ID" }, { "name": "created_at", "type": "string", "description": "流水创建时间" }, { "name": "transaction_type", "type": "string", "description": "流水类型:INBOUND / OUTBOUND / TRANSFER_OUT / TRANSFER_IN / LOCK" }, { "name": "store_id", "type": "number", "description": "货主ID" }, { "name": "stock_id", "type": "number", "description": "商品库存ID" }, { "name": "quantity", "type": "number", "description": "变动数量" }, { "name": "before_quantity", "type": "number", "description": "变更前库存" }, { "name": "after_quantity", "type": "number", "description": "变更后库存" }, { "name": "before_locked_quantity", "type": "number", "description": "变更前锁定库存" }, { "name": "after_locked_quantity", "type": "number", "description": "变更后锁定库存" }, { "name": "batch_no", "type": "string", "description": "批次号" }, { "name": "order_type", "type": "string", "description": "单据类型" }, { "name": "order_no", "type": "string", "description": "单据号" }, { "name": "order_id", "type": "number", "description": "发货单ID" }, { "name": "receiving_id", "type": "number", "description": "收货单ID" }, { "name": "entry_order_id", "type": "number", "description": "入库单ID" }, { "name": "operator_name", "type": "string", "description": "操作人名称" }, { "name": "remark", "type": "string", "description": "备注" } ] }, { "name": "pagination", "type": "object", "description": "分页信息,包含 page、pageSize、total" } ], "errors": [ { "code": 400, "message": "start_time 不合法" }, { "code": 400, "message": "end_time 不合法" }, { "code": 400, "message": "start_time 不能大于 end_time" } ] }, { "method": "stock.transaction.storeList", "description": "货主侧商品出入库流水列表查询(wms_stock_transaction),按货主 store_id 限定数据范围,支持 where 条件筛选与分页", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "store_id", "type": "number", "required": true, "source": "body", "description": "货主ID,必传;用于限定查询的货主范围" }, { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,包含 page / pageSize" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "统一 where 条件对象,支持以下字段:", "children": [ { "name": "start_time", "type": "string", "required": false, "description": "开始时间(闭区间下限),created_at >= start_time" }, { "name": "end_time", "type": "string", "required": false, "description": "结束时间(闭区间上限),created_at <= end_time" }, { "name": "warehouse_ids", "type": "array", "required": false, "description": "仓库ID数组,为空或未传表示不按仓库筛选(但仅返回当前货主有权限的仓库数据)" }, { "name": "stock_ids", "type": "array", "required": false, "description": "商品库存ID数组,为空或未传表示不筛选" }, { "name": "keyword", "type": "string", "required": false, "description": "快捷搜索关键字,支持按商品编码(item_code)、商品名称(item_name)、货物编码(goods_code)、条码(barcode)、SKU ID 模糊匹配。以当前登录货主 store_id 为主维度解析为 stock_id 列表后以 IN 条件合并查询。与 stock_ids 互斥(keyword 优先)" }, { "name": "transaction_type", "type": "string", "required": false, "description": "流水类型:INBOUND=入库 / OUTBOUND=出库 / TRANSFER_OUT=移库出 / TRANSFER_IN=移库入 / LOCK=锁定" }, { "name": "order_type", "type": "string", "required": false, "description": "单据类型筛选" }, { "name": "order_no", "type": "string", "required": false, "description": "单据号筛选(支持模糊匹配)" }, { "name": "batch_no", "type": "string", "required": false, "description": "批次号筛选" }, { "name": "entry_order_id", "type": "number", "required": false, "description": "入库单ID筛选" }, { "name": "receiving_id", "type": "number", "required": false, "description": "收货单ID筛选" }, { "name": "order_id", "type": "number", "required": false, "description": "发货单ID筛选" } ] }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数对象,支持 sortField / sortOrder 与 sort_field / sort_order 下划线别名兼容", "children": [ { "name": "sortField", "type": "string", "required": false, "description": "排序字段,白名单:created_at、quantity、stock_id、warehouse_id。非法字段回退默认排序(created_at DESC)" }, { "name": "sort_field", "type": "string", "required": false, "description": "排序字段下划线别名(兼容 sort.sort_field),规则同 sortField" }, { "name": "sortOrder", "type": "string", "required": false, "description": "排序方向,ASC / DESC(大小写不敏感),非法值回退 DESC" }, { "name": "sort_order", "type": "string", "required": false, "description": "排序方向下划线别名(兼容 sort.sort_order),规则同 sortOrder" } ] } ], "response": [ { "name": "list", "type": "array", "description": "流水记录列表", "children": [ { "name": "id", "type": "number", "description": "流水记录ID" }, { "name": "created_at", "type": "string", "description": "流水创建时间" }, { "name": "transaction_type", "type": "string", "description": "流水类型:INBOUND / OUTBOUND / TRANSFER_OUT / TRANSFER_IN / LOCK" }, { "name": "warehouse_id", "type": "number", "description": "仓库ID" }, { "name": "store_id", "type": "number", "description": "货主ID" }, { "name": "stock_id", "type": "number", "description": "商品库存ID" }, { "name": "quantity", "type": "number", "description": "变动数量" }, { "name": "before_quantity", "type": "number", "description": "变更前库存" }, { "name": "after_quantity", "type": "number", "description": "变更后库存" }, { "name": "before_locked_quantity", "type": "number", "description": "变更前锁定库存" }, { "name": "after_locked_quantity", "type": "number", "description": "变更后锁定库存" }, { "name": "batch_no", "type": "string", "description": "批次号" }, { "name": "order_type", "type": "string", "description": "单据类型" }, { "name": "order_no", "type": "string", "description": "单据号" }, { "name": "order_id", "type": "number", "description": "发货单ID" }, { "name": "receiving_id", "type": "number", "description": "收货单ID" }, { "name": "entry_order_id", "type": "number", "description": "入库单ID" }, { "name": "operator_name", "type": "string", "description": "操作人名称" }, { "name": "remark", "type": "string", "description": "备注" } ] }, { "name": "pagination", "type": "object", "description": "分页信息,包含 page、pageSize、total" } ], "errors": [ { "code": 400, "message": "store_id 不能为空" }, { "code": 400, "message": "start_time 不合法" }, { "code": 400, "message": "end_time 不合法" }, { "code": 400, "message": "start_time 不能大于 end_time" } ] } ] }, { "groupName": "拣货模块", "module": "pick", "list": [ { "method": "pick.query", "description": "按 keyword(运单号或波次号)获取或创建当前用户的拣货任务:命中同用户活动任务返回 existing;无活动任务则创建并返回 created;若活动任务归属他人则返回冲突提示。新增领单前置校验:扫描命中的波次属于普通波次(wms_wave_batch.source=0)时,若波次内存在未领料订单(claim_status != fin,拦截订单除外)则返回 400 并携带 action=wave_claim 提示「订单未领料,请先领料后再拣货」(pick.waveClaimScan),中止拣货任务创建;拦截订单未领料不阻隔拣货,且创建任务计算拣货数量时剔除未领料订单(拦截订单也不入任务)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "keyword", "type": "string", "required": true, "source": "body", "description": "关键字,支持运单号或波次号。" } ], "response": [ { "name": "task_id", "type": "number", "required": true, "description": "拣货任务ID。" }, { "name": "status", "type": "string", "required": true, "description": "任务状态:existing(命中当前用户已有活动任务)或 created(新建成功)。" }, { "name": "tip", "type": "string", "required": true, "description": "提示文案。" } ], "errors": [ { "code": 400, "message": "参数错误或目标波次不满足建任务条件(如 keyword 为空、缺少仓库上下文、目标波次信息不完整、散单波次无可用订单);普通波次(source=0)存在非拦截未领料订单时中止建任务并提示「订单未领料,请先领料后再拣货」(失败 data 含 action=wave_claim、wave_id、wave_no、wave_type、wave_source、pick_mode、unclaimed_order_count、intercepted_order_count、total_order_count,拦截订单未领料不阻隔)。" }, { "code": 401, "message": "未获取到操作人上下文。" }, { "code": 404, "message": "关键字未命中有效运单/波次,或命中的订单/波次不属于当前仓库。" }, { "code": 409, "message": "目标波次已存在他人创建的活动任务(失败 data 含 task_id、task_owner_id、task_owner_name)。" }, { "code": 500, "message": "内部错误(如分表模型不可用或任务创建异常)。" } ] }, { "method": "pick.wavePickComplete", "description": "按波次ID一键完成整个波次的拣货。内部先按 wave_id 定位波次,复用 query 的去重与任务创建逻辑:若波次已有当前用户的活动任务则直接复用并完成;已有他人活动任务返回 409;已完成则返回 already_completed;否则新建任务(source=2 后台抓取)后在内部调用 wavePickTaskComplete(mode=1 全部确认)完成拣货并回写任务进度。", "isNeedAuth": false, "isNeedLogin": true, "isNeedRight": false, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "wave_id", "type": "number", "required": true, "source": "body", "description": "波次ID(wms_wave_batch.wave_id)" } ], "response": [ { "name": "task_id", "type": "number", "required": true, "description": "拣货任务ID" }, { "name": "status", "type": "string", "required": true, "description": "操作结果:completed(拣货完成)或 already_completed(波次已存在完成任务)" }, { "name": "tip", "type": "string", "required": true, "description": "提示文案" }, { "name": "confirmed_order_ids", "type": "array", "required": false, "description": "已确认完成的订单ID列表" }, { "name": "is_completed", "type": "boolean", "required": false, "description": "任务是否已全部完成" }, { "name": "progress", "type": "object", "required": false, "description": "任务进度(total_orders / picked_orders / pending_orders)" } ], "errors": [ { "code": 400, "message": "参数错误(wave_id 为空/非正整数、缺少仓库上下文、波次信息不完整、波次下无可用订单)。" }, { "code": 401, "message": "未获取到操作人上下文。" }, { "code": 404, "message": "波次不存在或不属于当前仓库。" }, { "code": 409, "message": "当前波次已存在他人创建的活动任务(失败 data 含 task_id、task_owner_id、task_owner_name)。" }, { "code": 500, "message": "任务创建失败或拣货完成失败。" } ] }, { "method": "pick.wavePickTaskDetail", "description": "按任务ID获取拣货任务详情。查询前会校验任务内订单是否全部完成快递号与储位分配:若存在未分配快递号或未分配储位订单,将返回 400 并在 data 中返回 action 与 order_ids 供前端触发一键分配;详情响应新增中间态进度语义(task.is_completed、task.progress 与顶层 is_completed),用于前端判断是否已完成与展示阶段进度;仅允许任务的 pick_user_id 与当前登录用户一致时返回详情。当 pick_mode=1(团购小波次)或 pick_mode=5(团购大波次)时,picking_details 字段不返回以减少带宽。", "isNeedAuth": false, "isNeedLogin": true, "isNeedRight": false, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id", "type": "number", "required": true, "source": "body", "description": "wms_wave_pick_task 主键 ID" } ], "response": [ { "name": "task", "type": "object", "description": "拣货任务主表(精简字段)", "children": [ { "name": "task_id", "type": "number", "description": "任务ID", "required": false }, { "name": "task_no", "type": "string", "description": "任务编号", "required": false }, { "name": "wave_no", "type": "string", "description": "波次号,从 wms_wave_pick_task_wave 关联 wms_wave_batch 获取;无关联波次时为空字符串", "required": false }, { "name": "status", "type": "number", "description": "任务状态", "required": false }, { "name": "pick_mode", "type": "number", "description": "拣货模式", "required": false }, { "name": "start_at", "type": "string", "description": "开始时间(ISO 字符串或 null)", "required": false }, { "name": "finish_at", "type": "string", "description": "完成时间(ISO 字符串或 null)", "required": false }, { "name": "batch_no", "type": "string", "description": "批次号", "required": false }, { "name": "is_completed", "type": "boolean", "description": "任务是否已完成(订单维度全部已拣或任务状态已进入完成态)", "required": false }, { "name": "progress", "type": "object", "description": "任务订单拣货进度统计", "required": false, "children": [ { "name": "total_orders", "type": "number", "description": "任务订单总数", "required": false }, { "name": "picked_orders", "type": "number", "description": "已确认拣货订单数", "required": false }, { "name": "pending_orders", "type": "number", "description": "待确认拣货订单数", "required": false } ] } ], "required": false }, { "name": "is_completed", "type": "boolean", "description": "任务是否已完成(与 task.is_completed 含义一致,便于前端直接判断)", "required": false }, { "name": "boxes", "type": "array", "description": "箱列表;包含用于前端展示与拣货进度的统计字段", "children": [ { "name": "task_id", "type": "number", "description": "任务ID", "required": false }, { "name": "box_id", "type": "number", "description": "箱ID", "required": false }, { "name": "box_no", "type": "string", "description": "箱编码", "required": false }, { "name": "box_type", "type": "number", "description": "箱类型", "required": false }, { "name": "status", "type": "number", "description": "箱状态", "required": false }, { "name": "ref_label", "type": "string", "description": "箱参考标签或关联业务标识(用于前端定位/关联)", "required": false }, { "name": "required_qty", "type": "number", "description": "箱内需要拣货的总数量", "required": false }, { "name": "picked_qty", "type": "number", "description": "当前已完成拣货的数量", "required": false } ], "required": false }, { "name": "picking_details", "type": "array", "description": "拣货明细列表(按库位/商品/数量拆分),用于从明细视角展示拣货要求。注意:当 pick_mode=1(团购小波次)或 pick_mode=5(团购大波次)时该字段不返回,减少带宽浪费;其他 pick_mode(2/3/4)正常返回。", "children": [ { "name": "order_id", "type": "number", "description": "订单ID", "required": false }, { "name": "order_item_id", "type": "number", "description": "订单行ID", "required": false }, { "name": "quantity", "type": "number", "description": "本行需拣货数量", "required": false }, { "name": "storage_id", "type": "number", "description": "仓库ID", "required": false }, { "name": "space_id", "type": "number", "description": "库位ID", "required": false }, { "name": "space_name", "type": "string", "description": "库位名称", "required": false }, { "name": "location_space", "type": "object", "description": "库位扩展信息(当存在时返回)", "children": [ { "name": "space_code", "type": "string", "description": "库位编码", "required": false }, { "name": "custom_name", "type": "string", "description": "库位自定义名称", "required": false }, { "name": "custom_barcode", "type": "string", "description": "库位自定义条码", "required": false }, { "name": "pick_sequence", "type": "number", "description": "拣货序列,用于路线/优先级排序", "required": false }, { "name": "pick_priority", "type": "number", "description": "拣货优先级(数值越小优先级越高)", "required": false } ], "required": false }, { "name": "item_code", "type": "string", "description": "商品编码", "required": false }, { "name": "item_name", "type": "string", "description": "商品名称", "required": false }, { "name": "stock_id", "type": "number", "description": "库存记录ID(stock 主键)", "required": false }, { "name": "plan_qty", "type": "number", "description": "计划拣货数量(用于与实际拣货对比)", "required": false }, { "name": "item_snapshot", "type": "object", "description": "商品快照(下单时的商品信息,可能包含规格/属性等)", "required": false } ], "required": false }, { "name": "picking_summary", "type": "object", "description": "对 picking_details 的汇总信息,用于统计与前端显示", "children": [ { "name": "total_lines", "type": "number", "description": "明细行数(picking_details.length)", "required": false }, { "name": "total_qty", "type": "number", "description": "明细总数量(quantity 汇总)", "required": false }, { "name": "distinct_spaces", "type": "number", "description": "涉及的不同库位数量", "required": false }, { "name": "distinct_items", "type": "number", "description": "涉及的不同商品数量", "required": false } ], "required": false }, { "name": "picking_view", "type": "object", "description": "按 pick_mode 区分的 picking_view 形态输出(五种形态);用于前端按任务类型展示聚合视图。", "children": [ { "name": "mode_code", "type": "number", "description": "拣货视图模式编码,与 task.pick_mode 对应", "required": false }, { "name": "mode_name", "type": "string", "description": "拣货视图模式名称", "required": false }, { "name": "require_box_allocations", "type": "boolean", "description": "当前模式是否需要箱分配;pick_mode=1/3/4 时为 true,pick_mode=2/5 时为 false", "required": false }, { "name": "group_by", "type": "string", "description": "分组字段,示例值:\"space+item\"", "required": false }, { "name": "sort_by", "type": "array", "description": "排序字段数组,典型为 [\"pick_sequence\",\"pick_priority\",\"space_id\",\"item_code\"]", "required": false }, { "name": "items", "type": "array", "description": "分组后的拣货项数组(按库位+商品聚合)", "children": [ { "name": "space_id", "type": "number", "description": "库位 ID", "required": false }, { "name": "space_name", "type": "string", "description": "库位名称", "required": false }, { "name": "location_space", "type": "object", "description": "库位扩展信息(同 picking_details.location_space 结构)", "children": [ { "name": "space_code", "type": "string", "description": "库位编码", "required": false }, { "name": "custom_name", "type": "string", "description": "库位自定义名称", "required": false }, { "name": "custom_barcode", "type": "string", "description": "库位自定义条码", "required": false }, { "name": "pick_sequence", "type": "number", "description": "拣货序列,用于路线/优先级排序", "required": false }, { "name": "pick_priority", "type": "number", "description": "拣货优先级(数值越小优先)", "required": false } ], "required": false }, { "name": "item_code", "type": "string", "description": "商品编码", "required": false }, { "name": "item_name", "type": "string", "description": "商品名称", "required": false }, { "name": "stock_id", "type": "number", "description": "库存记录ID(stock 主键)", "required": false }, { "name": "total_qty", "type": "number", "description": "该库位该商品的总需拣货数量", "required": false }, { "name": "pick_requirements", "type": "string", "description": "拣货要求(商品资料维护;merge_requirements=Y 时回退为打包要求),团购形态(pick_mode=1/5)不返回 picking_details,前端以此字段展示拣货要求", "required": false }, { "name": "box_allocations", "type": "array", "description": "与该库位/商品相关的箱分配列表(当 require_box_allocations=true 时返回)", "children": [ { "name": "box_id", "type": "number", "description": "箱ID", "required": false }, { "name": "box_no", "type": "string", "description": "箱编码", "required": false }, { "name": "box_type", "type": "number", "description": "箱类型", "required": false }, { "name": "required_qty", "type": "number", "description": "该箱分配需要拣货的数量", "required": false }, { "name": "picked_qty", "type": "number", "description": "该箱已完成拣货的数量", "required": false }, { "name": "allocated_qty", "type": "number", "description": "该箱已分配的数量(由后端分配)", "required": false } ], "required": false } ], "required": false } ], "required": false } ], "errors": [ { "code": 400, "message": "业务校验失败:包含 task_id 参数不合法、未分配快递号(data.action=assign_express, data.order_ids)或未分配储位(data.action=assign_storage, data.order_ids)等场景。" }, { "code": 401, "message": "未获取到操作人上下文。" }, { "code": 403, "message": "当前操作人与任务创建人不一致,无权查看。" }, { "code": 404, "message": "拣货任务不存在。" }, { "code": 500, "message": "查询失败。" } ] }, { "method": "pick.wavePickTaskSubmit", "description": "提交拣货任务中间态。用于保存阶段性数据到任务 ext_json.pick_intermediate,并在任务初始状态时自动推进到进行中。", "isNeedAuth": false, "isNeedLogin": true, "isNeedRight": false, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id", "type": "number", "required": true, "source": "body", "description": "拣货任务ID" }, { "name": "payload", "type": "object", "required": false, "source": "body", "description": "中间态业务数据对象,将原样保存到 ext_json.pick_intermediate.payload" } ], "response": [ { "name": "task_id", "type": "number", "required": true, "description": "拣货任务ID" }, { "name": "status", "type": "string", "required": true, "description": "提交结果状态,固定为 submitted" }, { "name": "is_completed", "type": "boolean", "required": true, "description": "当前任务是否已完成" }, { "name": "progress", "type": "object", "required": true, "description": "任务订单拣货进度统计", "children": [ { "name": "total_orders", "type": "number", "required": true, "description": "任务订单总数" }, { "name": "picked_orders", "type": "number", "required": true, "description": "已确认拣货订单数" }, { "name": "pending_orders", "type": "number", "required": true, "description": "待确认拣货订单数" } ] } ], "errors": [ { "code": 400, "message": "参数或业务状态不满足提交条件(如 task_id 不合法、缺少仓库上下文、任务已完成/已取消)。" }, { "code": 401, "message": "未获取到操作人上下文。" }, { "code": 403, "message": "当前操作人与任务创建人不一致,无权操作。" }, { "code": 404, "message": "拣货任务不存在。" }, { "code": 500, "message": "提交失败。" } ] }, { "method": "pick.wavePickTaskComplete", "description": "完全提交拣货任务。支持 mode=1 全部确认,mode=2 部分确认(需传 order_ids)。提交后根据是否全部完成自动推进任务状态。后台抓取创建的任务(source=2)必须先绑定拣货车才能提交,否则返回 400。", "isNeedAuth": false, "isNeedLogin": true, "isNeedRight": false, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id", "type": "number", "required": true, "source": "body", "description": "拣货任务ID" }, { "name": "mode", "type": "number", "required": false, "source": "body", "description": "提交模式:1=全部确认(默认),2=部分确认" }, { "name": "order_ids", "type": "array", "required": false, "source": "body", "description": "部分确认模式(mode=2)时必填;仅会确认命中当前任务的订单ID" } ], "response": [ { "name": "task_id", "type": "number", "required": true, "description": "拣货任务ID" }, { "name": "mode", "type": "number", "required": true, "description": "实际生效的提交模式(1=全部确认,2=部分确认)" }, { "name": "confirmed_order_ids", "type": "array", "required": true, "description": "本次成功确认的订单ID列表" }, { "name": "is_completed", "type": "boolean", "required": true, "description": "提交后任务是否已完成" }, { "name": "progress", "type": "object", "required": true, "description": "任务订单拣货进度统计", "children": [ { "name": "total_orders", "type": "number", "required": true, "description": "任务订单总数" }, { "name": "picked_orders", "type": "number", "required": true, "description": "已确认拣货订单数" }, { "name": "pending_orders", "type": "number", "required": true, "description": "待确认拣货订单数" } ] } ], "errors": [ { "code": 400, "message": "参数或业务状态不满足提交条件(如 task_id 不合法、mode 非 1/2、部分确认未传 order_ids、任务下无可确认订单等)。后台抓取任务(source=2)未绑定拣货车时拒绝提交:\"后台抓取任务必须先绑定拣货车才能提交\"。" }, { "code": 401, "message": "未获取到操作人上下文。" }, { "code": 403, "message": "当前操作人与任务创建人不一致,无权操作。" }, { "code": 404, "message": "拣货任务不存在。" }, { "code": 500, "message": "提交失败。" } ] }, { "method": "pick.waveClaimScan", "description": "扫描面单号领取整波(领料)。按面单号(运单号)定位待处理订单表中的订单后反查订单所在波次,仅对普通波次(wms_wave_batch.source=0,含团购/散单)支持整波领料:命中后将该波次下全部未领单订单(拦截订单除外) claim_status 置为 fin(领料完成)并写入 ORDER_WAVE_CLAIM 订单操作日志,返回波次ID与波次编码;波次下存在未打印订单(print_status != fin,拦截订单除外)时返回 400「波次未打印,禁止领料」(data 含 wave_id、wave_no、unprinted_order_count、intercepted_order_count,拦截订单未打印不阻隔领料);拦截订单整体跳过领料(不置为 fin);策略抓取波次(source=1/2)无需领料,返回 400 并提示「该波次为抓取波次,无需领料」(失败 data 含 no_claim_needed=true、wave_id、wave_no);面单号查不到订单或订单不在待处理订单表返回 404 提示无记录;波次内订单已全部领料时返回 already_claimed 幂等结果并提示已领料。", "isNeedAuth": false, "isNeedLogin": true, "isNeedRight": false, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "waybill_no", "type": "string", "required": true, "source": "body", "description": "面单号(运单号,wms_order_express.waybill_code)" } ], "response": [ { "name": "wave_id", "type": "number", "required": true, "description": "波次ID" }, { "name": "wave_no", "type": "string", "required": true, "description": "波次号" }, { "name": "wave_type", "type": "number", "required": true, "description": "波次类型:1-团购 2-散单" }, { "name": "wave_source", "type": "number", "required": true, "description": "波次来源:0-普通波次 1-管理后台策略任务 2-PDA策略任务" }, { "name": "pick_mode", "type": "number", "required": true, "description": "拣货模式:1-团购小波次 2-散单单品单件 3-散单先拣后分 4-边拣边分 5-团购大波次(0 表示无关联拣货任务)" }, { "name": "matched_order_id", "type": "number", "required": true, "description": "面单号命中的订单ID" }, { "name": "waybill_no", "type": "string", "required": true, "description": "扫描的面单号" }, { "name": "total_order_count", "type": "number", "required": true, "description": "波次下订单总数" }, { "name": "intercepted_order_count", "type": "number", "required": true, "description": "波次下拦截订单数(拦截订单跳过领料,其未打印/未领料状态不阻隔领料与拣货)" }, { "name": "claimed_order_count", "type": "number", "required": true, "description": "本次置为 fin 的订单数(已全部领料时返回 0)" }, { "name": "status", "type": "string", "required": true, "description": "操作结果:claimed(整波领料完成)或 already_claimed(波次已领料)" }, { "name": "tip", "type": "string", "required": true, "description": "提示文案" } ], "errors": [ { "code": 400, "message": "参数错误(waybill_no 为空、缺少仓库上下文、订单未分配波次、波次下无可用订单);波次下存在未打印订单(拦截订单除外)返回「波次未打印,禁止领料」(data 含 wave_id、wave_no、unprinted_order_count、intercepted_order_count);策略抓取波次(source=1/2)返回「该波次为抓取波次,无需领料」(data 含 no_claim_needed=true、wave_id、wave_no);其余不支持类型返回通用提示。" }, { "code": 401, "message": "未获取到操作人上下文。" }, { "code": 404, "message": "未查询到该面单号对应的订单(无记录)、订单不在待处理订单表(无记录),或波次不存在/不属于当前仓库。" }, { "code": 500, "message": "运单模型/订单模型不可用或内部错误。" } ] } ] }, { "groupName": "拣货车模块", "module": "pickCart", "list": [ { "method": "pickCart.scan", "description": "按拣货车条码/编码查询拣货车信息,供 PDA 扫码后用于拣货任务绑定。", "isNeedAuth": false, "isNeedLogin": true, "isNeedRight": false, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "cart_code", "type": "string", "required": true, "source": "body", "description": "拣货车条码/编码" } ], "response": [ { "name": "cart_id", "type": "number", "required": true, "description": "拣货车ID" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "仓库ID" }, { "name": "cart_code", "type": "string", "required": true, "description": "拣货车编码" }, { "name": "cart_name", "type": "string", "required": false, "description": "拣货车名称" }, { "name": "status", "type": "number", "required": true, "description": "拣货车状态:0-停用 1-启用" }, { "name": "current_task_id", "type": "number", "required": false, "description": "当前绑定任务ID,无绑定时为 null" }, { "name": "current_task_no", "type": "string", "required": false, "description": "当前绑定任务编号,无绑定时为 null" } ], "errors": [ { "code": 400, "message": "cart_code 未传或缺少仓库上下文。" }, { "code": 404, "message": "拣货车不存在。" }, { "code": 500, "message": "查询失败。" } ] }, { "method": "pickCart.bindTaskCart", "description": "绑定拣货任务与拣货车。支持传 cart_id 或 cart_code;若任务已绑定其他拣货车则自动改绑,若目标拣货车已绑定其他活动任务则返回冲突。", "isNeedAuth": false, "isNeedLogin": true, "isNeedRight": false, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id", "type": "number", "required": true, "source": "body", "description": "拣货任务ID" }, { "name": "cart_id", "type": "number", "required": false, "source": "body", "description": "拣货车ID,和 cart_code 二选一即可" }, { "name": "cart_code", "type": "string", "required": false, "source": "body", "description": "拣货车编码,和 cart_id 二选一即可" } ], "response": [ { "name": "task_id", "type": "number", "required": true, "description": "拣货任务ID" }, { "name": "task_no", "type": "string", "required": true, "description": "拣货任务编号" }, { "name": "cart", "type": "object", "required": true, "description": "绑定后的拣货车信息", "children": [ { "name": "cart_id", "type": "number", "description": "拣货车ID" }, { "name": "cart_code", "type": "string", "description": "拣货车编码" }, { "name": "cart_name", "type": "string", "description": "拣货车名称" }, { "name": "current_task_id", "type": "number", "description": "当前绑定任务ID" }, { "name": "current_task_no", "type": "string", "description": "当前绑定任务编号" } ] } ], "errors": [ { "code": 400, "message": "参数不合法、任务已完成/已取消、拣货车已停用等业务校验失败。" }, { "code": 401, "message": "未获取到操作人上下文。" }, { "code": 403, "message": "当前操作人与任务创建人不一致,或任务不属于当前仓库。" }, { "code": 404, "message": "拣货任务或拣货车不存在。" }, { "code": 409, "message": "目标拣货车已绑定其他活动任务。" }, { "code": 500, "message": "绑定失败。" } ] }, { "method": "pickCart.create", "description": "创建拣货车。拣货车编码在当前仓库内不可重复。", "isNeedAuth": false, "isNeedLogin": true, "isNeedRight": false, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "cart_code", "type": "string", "required": true, "source": "body", "description": "拣货车编码,当前仓库内唯一" }, { "name": "cart_name", "type": "string", "required": false, "source": "body", "description": "拣货车名称" }, { "name": "status", "type": "number", "required": false, "source": "body", "description": "状态:0-停用 1-启用,默认 1" } ], "response": [ { "name": "cart_id", "type": "number", "required": true, "description": "拣货车ID" }, { "name": "cart_code", "type": "string", "required": true, "description": "拣货车编码" }, { "name": "cart_name", "type": "string", "required": false, "description": "拣货车名称" }, { "name": "status", "type": "number", "required": true, "description": "状态:0-停用 1-启用" } ], "errors": [ { "code": 400, "message": "cart_code 未传或缺少仓库上下文。" }, { "code": 409, "message": "拣货车编码已存在,请勿重复。" }, { "code": 500, "message": "创建失败。" } ] }, { "method": "pickCart.update", "description": "更新拣货车。支持修改编码、名称、状态;若修改后的编码与当前仓库内其他拣货车重复则拦截。", "isNeedAuth": false, "isNeedLogin": true, "isNeedRight": false, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "cart_id", "type": "number", "required": true, "source": "body", "description": "拣货车ID" }, { "name": "cart_code", "type": "string", "required": false, "source": "body", "description": "新的拣货车编码" }, { "name": "cart_name", "type": "string", "required": false, "source": "body", "description": "新的拣货车名称" }, { "name": "status", "type": "number", "required": false, "source": "body", "description": "新的状态:0-停用 1-启用" } ], "response": [ { "name": "cart_id", "type": "number", "required": true, "description": "拣货车ID" }, { "name": "cart_code", "type": "string", "required": true, "description": "拣货车编码" }, { "name": "cart_name", "type": "string", "required": false, "description": "拣货车名称" }, { "name": "status", "type": "number", "required": true, "description": "状态:0-停用 1-启用" } ], "errors": [ { "code": 400, "message": "参数不合法,或拣货车已绑定任务不能停用。" }, { "code": 404, "message": "拣货车不存在。" }, { "code": 409, "message": "拣货车编码已存在,请勿重复。" }, { "code": 500, "message": "更新失败。" } ] }, { "method": "pickCart.delete", "description": "删除拣货车。若拣货车当前已绑定任务或存在有效绑定记录,则不允许删除。", "isNeedAuth": false, "isNeedLogin": true, "isNeedRight": false, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "cart_id", "type": "number", "required": true, "source": "body", "description": "拣货车ID" } ], "response": [ { "name": "cart_id", "type": "number", "required": true, "description": "被删除的拣货车ID" }, { "name": "deleted", "type": "boolean", "required": true, "description": "是否删除成功,固定为 true" } ], "errors": [ { "code": 400, "message": "cart_id 不合法,或拣货车当前已绑定任务/存在有效绑定记录。" }, { "code": 404, "message": "拣货车不存在。" }, { "code": 500, "message": "删除失败。" } ] }, { "method": "pickCart.batchDelete", "description": "批量删除拣货车。已绑定任务的拣货车将被跳过,不会删除。", "isNeedAuth": false, "isNeedLogin": true, "isNeedRight": false, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "array", "required": true, "source": "body", "description": "拣货车ID列表,如 [1,2,3]" } ], "response": [ { "name": "deleted_ids", "type": "array", "required": true, "description": "成功删除的拣货车ID列表" }, { "name": "skipped_ids", "type": "array", "required": true, "description": "跳过的拣货车ID列表(已绑定任务或存在有效绑定记录)" }, { "name": "deleted_count", "type": "number", "required": true, "description": "成功删除数量" }, { "name": "skipped_count", "type": "number", "required": true, "description": "跳过数量" } ], "errors": [ { "code": 400, "message": "ids 参数不合法或缺少仓库上下文。" }, { "code": 500, "message": "批量删除失败。" } ] }, { "method": "pickCart.detail", "description": "查询拣货车详情。", "isNeedAuth": false, "isNeedLogin": true, "isNeedRight": false, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "cart_id", "type": "number", "required": true, "source": "body", "description": "拣货车ID" } ], "response": [ { "name": "cart_id", "type": "number", "required": true, "description": "拣货车ID" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "仓库ID" }, { "name": "cart_code", "type": "string", "required": true, "description": "拣货车编码" }, { "name": "cart_name", "type": "string", "required": false, "description": "拣货车名称" }, { "name": "status", "type": "number", "required": true, "description": "状态:0-停用 1-启用" }, { "name": "current_task_id", "type": "number", "required": false, "description": "当前绑定任务ID,无绑定时为 null" }, { "name": "current_task_no", "type": "string", "required": false, "description": "当前绑定任务编号,无绑定时为 null" } ], "errors": [ { "code": 400, "message": "cart_id 不合法或缺少仓库上下文。" }, { "code": 404, "message": "拣货车不存在。" }, { "code": 500, "message": "查询失败。" } ] }, { "method": "pickCart.list", "description": "分页查询拣货车列表。支持按关键字、状态、当前绑定任务筛选。", "isNeedAuth": false, "isNeedLogin": true, "isNeedRight": false, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page/pageSize,默认 1/20" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "筛选条件,支持 keyword、status、current_task_id" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "拣货车列表,元素结构同 pickCart.detail 返回" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息,包含 page、pageSize、total、totalPages" } ], "errors": [ { "code": 400, "message": "缺少仓库上下文。" }, { "code": 500, "message": "查询失败。" } ] }, { "method": "pickCart.codeDuplicateCheck", "description": "拣货车编码查重。支持传 exclude_cart_id 排除自身,用于编辑场景判断是否与其他车重复。", "isNeedAuth": false, "isNeedLogin": true, "isNeedRight": false, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "cart_code", "type": "string", "required": true, "source": "body", "description": "待校验的拣货车编码" }, { "name": "exclude_cart_id", "type": "number", "required": false, "source": "body", "description": "需排除的拣货车ID,通常为当前编辑记录自身ID" } ], "response": [ { "name": "duplicated", "type": "boolean", "required": true, "description": "是否存在重复编码" }, { "name": "cart_id", "type": "number", "required": false, "description": "命中的重复拣货车ID,无重复时为 null" }, { "name": "cart_code", "type": "string", "required": false, "description": "命中的重复编码,无重复时为 null" }, { "name": "cart_name", "type": "string", "required": false, "description": "命中的重复拣货车名称,无重复时为 null" }, { "name": "status", "type": "number", "required": false, "description": "命中的重复拣货车状态,无重复时为 null" } ], "errors": [ { "code": 400, "message": "cart_code 未传或缺少仓库上下文。" }, { "code": 500, "message": "校验失败。" } ] } ] }, { "groupName": "收货单模块", "module": "storage_receiving", "list": [ { "method": "storage.receiving.getReceivingList", "description": "查询收货单列表,支持分页和多条件筛选。支持 filterDepleted 参数过滤掉无可再用量的收货单(所有明细已被其他入库单 committed 绑定占满)。支持 entry_order_id 参数按入库单商品交集过滤。支持 stock_query_where 参数按商品条码/编码/ID 过滤。列表每项包含 store_name(货主名称,实时解析:合约表 wms_store_warehouse.store_remask 优先、无合约或备注为空时回退 wms_store.company_name 公司全称,均无时保留主表快照,可能为空字符串)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page/pageSize" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "统一 where 条件对象;推荐使用 { operator, value, type } 标准结构,历史简写会在 main 中自动标准化;支持 quickWhere、status、store_id、日期区间等字段。示例:where.status={operator:eq,value:finished}; where.store_id={operator:eq,value:1001}; where.create_time_start={value:2026-03-01}。" }, { "name": "filterDepleted", "type": "boolean", "required": false, "source": "body", "description": "是否过滤掉无可再用量的收货单(所有明细已被其他入库单 committed 绑定占满,即 available=0)。默认 false。" }, { "name": "entry_order_id", "type": "number", "required": false, "source": "body", "description": "按入库单商品交集过滤。传入入库单 ID 后,只返回至少有一条收货明细的 system_product_id 在入库单明细中存在的收货单。与 filterDepleted 可组合使用。不传则不过滤。" }, { "name": "stock_query_where", "type": "string|string[]", "required": false, "source": "body", "description": "按商品维度过滤。传入字符串或字符串数组后搜索商品条码(wms_stock_barcodes.barcode)、商品编码(wms_stock_warehouse.item_code)与商品ID(wms_stock_warehouse.id,纯数字时精确匹配),再经 wms_receiving_detail.system_product_id 关联,返回明细中含匹配商品的收货单;多个关键字取并集。与 filterDepleted、entry_order_id 可组合使用(组合时取交集)。不传则不过滤。" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "收货单列表" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)" }, { "name": "summary", "type": "object", "required": true, "description": "汇总信息(total_quantity、total_locked、total_available、total_items)" } ], "errors": [ { "code": "500", "message": "查询失败" } ] }, { "method": "storage.receiving.getStoreReceivingList", "description": "货主侧收货单列表查询,以当前平台激活的货主 store_id 为维度查询收货单,支持分页和多条件筛选。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page/pageSize" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "统一 where 条件对象;支持 quickWhere、status、warehouse_id、日期区间等字段。" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数,支持 sortField/sortOrder" }, { "name": "stock_query_where", "type": "string|string[]", "required": false, "source": "body", "description": "按商品维度过滤。传入字符串或字符串数组后搜索商品条码(wms_stock_barcodes.barcode)、商品编码(wms_stock_warehouse.item_code)与商品ID(wms_stock_warehouse.id,纯数字时精确匹配),再经 wms_receiving_detail.system_product_id 关联,返回明细中含匹配商品的收货单;多个关键字取并集。不传则不过滤。" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "收货单列表" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)" }, { "name": "summary", "type": "object", "required": true, "description": "汇总信息(total_quantity、total_locked、total_available、total_items)" } ], "errors": [ { "code": "500", "message": "查询失败" }, { "code": "0", "message": "未获取到货主平台激活上下文,请先切换至货主角色" } ] }, { "method": "storage.receiving.getReceivingDetail", "description": "storage.receiving.getReceivingDetail 接口", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "收货单ID" }, { "name": "pagination", "type": "object", "required": true, "source": "body", "description": "明细分页参数,支持 page/pageSize" } ], "response": [ { "name": "receiving", "type": "object", "required": true, "description": "收货单详情(含 details、images、pagination)" }, { "name": "receiving.store_name", "type": "string", "required": false, "description": "货主名称(string,可空)。优先取合约表 wms_store_warehouse.store_remask(货主备注名称,按 store_id + warehouse_id 维度),无合约或备注为空时回退 wms_store.company_name(公司全称),均无时保留主表快照(可能为空字符串)。" }, { "name": "receiving.details", "type": "array", "required": false, "description": "收货单明细列表,单条记录包含明细字段(见下文)" }, { "name": "receiving.details.*.stock_id", "type": "number", "required": false, "description": "商品/库存ID(number|null),语义与 system_product_id 一致,取值为 system_product_id,缺失时为 null;system_product_id 保留,向后兼容。" }, { "name": "receiving.details.*.space_id", "type": "string", "required": false, "description": "库位展示名称(string|null)。优先取 custom_space_name,其次取 space_name。兼容说明:该字段历史上为数值库位ID,现已调整为展示名称;原始ID请使用 receiving.details.*.space_id_raw。" }, { "name": "receiving.details.*.space_id_raw", "type": "number", "required": false, "description": "原始库位ID(number|null),用于兼容依赖旧语义(space_id=数字ID)的调用方。" }, { "name": "receiving.details.*.space_name", "type": "string", "required": false, "description": "库位名称/编码(string|null),作为展示名称的回退来源。" }, { "name": "receiving.details.*.custom_space_name", "type": "string", "required": false, "description": "库位自定义名称(string|null,可空)。" }, { "name": "receiving.details.*.box_remainder", "type": "number", "required": false, "description": "箱内剩余数量/零散数量(不满箱时的件数)" }, { "name": "receiving.details.*.box_weight", "type": "number", "required": false, "description": "实测箱重(单位与系统重量一致,如 g)" } ], "errors": [ { "code": "0", "message": "无记录或无权访问" }, { "code": "500", "message": "服务器错误" } ] }, { "method": "storage.receiving.batchCancelReceiving", "description": "storage.receiving.batchCancelReceiving 接口", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "array", "required": true, "source": "body", "description": "待作废收货单ID数组" } ], "response": [ { "name": "message", "type": "string", "required": true, "description": "批量作废处理结果" } ], "errors": [ { "code": "0", "description": "部分单据不存在、无权访问或状态不允许作废" }, { "code": "500", "description": "服务器错误" } ] }, { "method": "storage.receiving.rejectReceiving", "description": "驳回收货单:将已完成(completed)的收货单批量恢复为收货中(receiving),记录驳回人信息和驳回理由。若任意一张收货单状态非 completed,则整批拒绝操作。驳回人信息(reviewer_name、reviewer_employee_id)自动取当前登录用户上下文,无需传入.", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "array", "required": true, "source": "body", "description": "收货单ID数组,所有收货单必须属于当前仓库且状态为 completed,否则整批拒绝" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "驳回理由,覆盖收货单原备注字段;不传则保留原备注" } ], "response": [ { "name": "count", "type": "number", "description": "成功驳回的收货单数量" } ], "errors": [ { "code": "0", "description": "ids 为空、部分单据不存在/无权访问,或存在非 completed 状态的收货单" }, { "code": "500", "description": "服务器错误" } ] }, { "method": "storage.receiving.reviewReceiving", "description": "批量审核收货单:校验所有单据满足条件(收货完成、全部匹配、未入库、已绑定货主、未审核)后统一审核,任意一张不符合则整批失败回滚。审核人信息自动取当前登录用户上下文,无需传入.", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "array", "required": true, "source": "body", "description": "收货单ID数组,所有单据必须满足:status=completed、detail_status=all_matched、storage_status=none、store_id 已绑定、is_review=0,否则整批拒绝" } ], "response": [ { "name": "count", "type": "number", "description": "成功审核的收货单数量" } ], "errors": [ { "code": "0", "description": "ids 为空、单据不存在/无权访问,或不满足审核条件(含并发冲突)" }, { "code": "500", "description": "服务器错误,事务已回滚" } ] }, { "method": "storage.receiving.create", "description": "storage.receiving.create 接口", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "delivery_method", "type": "string", "required": true, "source": "body", "description": "到货方式:truck/express/air_freight/sea_freight/other" }, { "name": "loading_method", "type": "string", "required": true, "source": "body", "description": "装卸方式:with_pallet/without_pallet" }, { "name": "license_plate", "type": "string", "required": false, "source": "body", "description": "车牌号(delivery_method=truck 时建议传)" }, { "name": "tracking_number", "type": "string", "required": false, "source": "body", "description": "物流单号(非 truck/other 场景建议传)" }, { "name": "store_id", "type": "number", "required": false, "source": "body", "description": "货主ID" }, { "name": "total_boxes", "type": "number", "required": false, "source": "body", "description": "总箱数" }, { "name": "total_pallets", "type": "number", "required": false, "source": "body", "description": "总托盘数" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "新建收货单ID" }, { "name": "receiving_number", "type": "string", "required": true, "description": "收货单号" } ], "errors": [ { "code": "0", "description": "创建失败(如字段枚举不合法、数据库约束异常)" } ] }, { "method": "storage.receiving.bindStore", "description": "收货单绑定货主", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "收货单ID" }, { "name": "store_id", "type": "number", "required": true, "source": "body", "description": "货主ID(必须与当前仓库存在有效签约关系)" } ], "response": [ { "name": "data.id", "type": "number", "required": true, "description": "收货单ID" }, { "name": "data.store_id", "type": "number", "required": true, "description": "已绑定的货主ID" }, { "name": "data.store_name", "type": "string", "required": false, "description": "货主名称/签约备注名" }, { "name": "data.status", "type": "string", "required": true, "description": "当前收货单状态" } ], "errors": [ { "code": "400", "description": "用户未绑定仓库、收货单ID/货主ID为空、已取消或已绑定货主" }, { "code": "404", "description": "收货单不存在/无权访问,或货主与当前仓库未建立有效签约关系" }, { "code": "500", "description": "绑定货主失败" } ] }, { "method": "storage.receiving.bindDetailProduct", "description": "收货单明细绑定或改绑系统商品", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "detail_id", "type": "number", "required": true, "source": "body", "description": "收货单明细ID(兼容字段 `id`)" }, { "name": "system_product_id", "type": "number", "required": true, "source": "body", "description": "系统商品ID(`StockWarehouse.id`,且必须属于当前仓库)" } ], "response": [ { "name": "data.detail_id", "type": "number", "required": true, "description": "收货单明细ID" }, { "name": "data.receiving_id", "type": "number", "required": true, "description": "收货单ID" }, { "name": "data.system_product_id", "type": "number", "required": true, "description": "已绑定的系统商品ID" }, { "name": "data.product_name", "type": "string", "required": true, "description": "自动回填的商品名称" } ], "errors": [ { "code": "400", "description": "用户未绑定仓库、明细ID/商品ID为空,收货单状态不允许绑定/改绑,或收货单已审核禁止绑定/改绑" }, { "code": "404", "description": "收货单明细不存在,或商品不存在/不属于当前仓库" }, { "code": "500", "description": "绑定商品失败" } ] }, { "method": "storage.receiving.queryReceivingLogs", "description": "按收货单ID查询操作日志列表(分页),仅返回当前仓库上下文数据", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number|string", "required": false, "source": "body", "description": "收货单ID(与 receiving_id 二选一)" }, { "name": "receiving_id", "type": "number|string", "required": false, "source": "body", "description": "收货单ID(兼容字段,与 id 二选一)" }, { "name": "page", "type": "number", "required": false, "source": "body", "description": "页码(兼容顶层分页入参)" }, { "name": "pageSize", "type": "number", "required": false, "source": "body", "description": "每页数量(兼容顶层分页入参)" }, { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page / pageSize" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "日志列表" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息,包含 page、pageSize、total、totalPages" } ], "errors": [ { "code": "400", "description": "收货单ID为空或仓库上下文缺失" }, { "code": "500", "description": "查询失败" } ] }, { "method": "storage.receiving.removeItem", "description": "storage.receiving.removeItem 接口", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": false, "source": "body", "description": "id 参数" }, { "name": "item_id", "type": "number", "required": false, "source": "body", "description": "item_id 参数" } ], "response": [], "errors": [] }, { "method": "storage.receiving.save", "description": "修改收货单基础信息。按收货单ID更新当前仓库下收货单的基础字段。", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "收货单ID,按该ID修改当前仓库下的收货单" }, { "name": "delivery_method", "type": "string", "required": false, "source": "body", "description": "到货方式:truck/express/air_freight/sea_freight/other;不传则保持原值" }, { "name": "loading_method", "type": "string", "required": false, "source": "body", "description": "装卸方式:with_pallet/without_pallet;不传则保持原值" }, { "name": "license_plate", "type": "string", "required": false, "source": "body", "description": "车牌号;当 delivery_method=truck 时可更新,其他到货方式会被清空或忽略" }, { "name": "tracking_number", "type": "string", "required": false, "source": "body", "description": "物流单号;当 delivery_method 为 express/air_freight/sea_freight 时可更新,truck/other 场景会被清空或忽略" }, { "name": "store_id", "type": "number", "required": false, "source": "body", "description": "货主ID;若传入,会校验当前仓库下签约关系并同步更新货主名称;传 0/null 可清空货主" }, { "name": "total_boxes", "type": "number", "required": false, "source": "body", "description": "总箱数,默认 0" }, { "name": "total_pallets", "type": "number", "required": false, "source": "body", "description": "总托盘数,默认 0" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注信息" }, { "name": "status", "type": "string", "required": false, "source": "body", "description": "收货单状态;不传则保持原值" }, { "name": "video_device_id", "type": "string", "required": false, "source": "body", "description": "录像设备ID" } ], "response": [ { "name": "code", "type": "number", "required": true, "description": "业务状态码;200 表示修改成功" }, { "name": "id", "type": "number", "required": true, "description": "修改的收货单ID" }, { "name": "receiving_number", "type": "string", "required": true, "description": "收货单号" }, { "name": "message", "type": "string", "required": true, "description": "结果描述;成功时通常为收货单修改成功" } ], "errors": [ { "code": "400", "description": "收货单ID不能为空、已取消的收货单不允许修改或用户未绑定仓库" }, { "code": "404", "description": "收货单不存在/无权访问,或指定货主不存在/未与当前仓库建立有效签约关系" }, { "code": "0", "description": "修改失败,如字段枚举不合法或数据库写入异常" } ] }, { "method": "storage.receiving.get", "description": "storage.receiving.get 接口", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "收货单ID" } ], "response": [ { "name": "code", "type": "number", "description": "业务状态码,200 表示成功" }, { "name": "message", "type": "string", "description": "返回信息" }, { "name": "data", "type": "object", "description": "收货单详情对象,包含 details(明细数组)、images 及主表字段" }, { "name": "data.details", "type": "array", "description": "收货单明细数组(每项为明细对象)" }, { "name": "data.details.*.box_remainder", "type": "number", "required": false, "description": "箱内剩余数量/零散数量(不满箱时的件数),默认 0" }, { "name": "data.details.*.box_weight", "type": "number", "required": false, "description": "实测箱重(单位与系统重量一致,如 g),默认 0" } ], "errors": [] }, { "method": "storage.receiving.addDetail", "description": "支持新增可选入参 item;item 有值时按传入字段创建明细(服务端会覆盖 receiving_id 与 creator_id);item 无值时沿原链路创建空白明细。返回的 selectId 与 data.details 语义不变(仍返回新创建明细的 selectId 与更新后的明细列表)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "receiving_id", "type": "number", "required": true, "source": "body", "description": "收货单ID" }, { "name": "item", "type": "object", "required": false, "source": "body", "description": "可选:按传入字段创建明细;不传则创建空白明细。item.children 需覆盖以下字段(有则写、无则补齐):actual_quantity, box_quantity, boxes_per_pallet, space_id, system_product_id, box_width, box_height, box_length, box_remainder, box_weight, weight, barcode, product_name, pallet_quantity, receiving_time, production_date, expiry_date, remark, batch_number, product_snapshot。若传入 item,服务端仍会覆盖 receiving_id 与 creator_id。", "children": [ { "name": "actual_quantity", "type": "number", "description": "实收数量" }, { "name": "box_quantity", "type": "number", "description": "箱数量" }, { "name": "boxes_per_pallet", "type": "number", "description": "每托盘箱数" }, { "name": "space_id", "type": "number", "description": "库位 ID;未传时默认使用仓库设置 subject_config.default_location_id,未设置则兜底库位 1" }, { "name": "system_product_id", "type": "number", "description": "系统商品 ID" }, { "name": "box_width", "type": "number", "description": "箱宽(单位同系统)" }, { "name": "box_height", "type": "number", "description": "箱高" }, { "name": "box_length", "type": "number", "description": "箱长" }, { "name": "box_remainder", "type": "number", "description": "箱内剩余数量/零散数量" }, { "name": "box_weight", "type": "number", "description": "箱重(单位 g)" }, { "name": "weight", "type": "number", "description": "商品重量(单位 g)" }, { "name": "barcode", "type": "string", "description": "商品条码" }, { "name": "product_name", "type": "string", "description": "商品名称" }, { "name": "pallet_quantity", "type": "number", "description": "托盘数量" }, { "name": "receiving_time", "type": "string", "description": "收货时间(ISO 字符串)" }, { "name": "production_date", "type": "string", "description": "生产日期(ISO 或 YYYY-MM-DD)" }, { "name": "expiry_date", "type": "string", "description": "有效期/失效日期(ISO 或 YYYY-MM-DD)" }, { "name": "remark", "type": "string", "description": "备注" }, { "name": "batch_number", "type": "string", "description": "批次号" }, { "name": "product_snapshot", "type": "object", "description": "商品快照,具体结构以实现为准" } ] } ], "response": [ { "name": "code", "type": "number", "required": true, "description": "业务状态码,200 表示添加成功" }, { "name": "message", "type": "string", "required": true, "description": "结果描述,成功时为 '添加成功'" }, { "name": "data.details", "type": "array", "required": true, "description": "收货单明细数组(每项为明细对象)" }, { "name": "data.selectId", "type": "number", "required": true, "description": "新创建的明细ID,用于前端选中" } ], "errors": [ { "code": "400", "description": "收货单状态不允许添加明细" }, { "code": "404", "description": "收货单不存在" }, { "code": "500", "description": "服务器错误或添加失败(数据库写入异常等)" } ] }, { "method": "storage.receiving.deleteDetail", "description": "删除收货单明细并回算统计。仅允许明细创建者在收货中状态删除未入库的明细;服务端从登录用户上下文获取 creator_id(ctx.user.employees_id)与 warehouse_id(ctx.user.store_id)。若关联收货单状态为 completed(已完成)或 cancelled(已取消),接口会返回删除失败(400),不允许删除明细。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "detail_id", "type": "number", "required": true, "source": "body", "description": "收货单明细 ID(必填)" } ], "response": [ { "name": "code", "type": "number", "required": true, "description": "业务状态码,200 表示成功,400/404/500 表示失败" }, { "name": "message", "type": "string", "required": true, "description": "简短的错误或成功信息" }, { "name": "data", "type": "object", "required": true, "description": "成功时返回的结果对象" }, { "name": "data.details", "type": "array", "required": true, "description": "删除后收货单剩余的明细数组。每项字段与 storage.receiving.getReceivingDetail 返回的明细项一致(含新增的 stock_id,语义同 getReceivingDetail,number|null);product_snapshot 为解析后的对象或 null" }, { "name": "data.selectId", "type": "number|null", "required": true, "description": "删除后建议前端选中的明细 ID;无剩余明细时为 null" } ], "errors": [ { "code": "404", "message": "明细不存在(或非创建者/仓库无权访问)" }, { "code": "400", "message": "收货单已完成或已取消,禁止删除明细;或该明细已入库或已被占用,删除失败" }, { "code": "500", "message": "服务器内部错误或删除异常(含数据库写入/事务异常)" } ] }, { "method": "storage.receiving.detailChange", "description": "修改收货单明细(数量/箱规/批次/商品信息回写等)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "收货明细ID" }, { "name": "receiving_id", "type": "number", "required": true, "source": "body", "description": "收货单ID" }, { "name": "actual_quantity", "type": "number", "required": false, "source": "body", "description": "实际收货数量" }, { "name": "batch_number", "type": "string", "required": false, "source": "body", "description": "批次号" }, { "name": "production_date", "type": "string", "required": false, "source": "body", "description": "生产日期(可解析的日期字符串)" }, { "name": "expiry_date", "type": "string", "required": false, "source": "body", "description": "到期日期(可解析的日期字符串)。若早于当前日期,接口会返回 400 并拒绝录入。" }, { "name": "box_quantity", "type": "number", "required": false, "source": "body", "description": "箱数" }, { "name": "boxes_per_pallet", "type": "number", "required": false, "source": "body", "description": "每托盘箱数" }, { "name": "pallet_quantity", "type": "number", "required": false, "source": "body", "description": "托盘数" }, { "name": "space_id", "type": "number", "required": false, "source": "body", "description": "库位 ID(可回写)" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注" }, { "name": "system_product_id", "type": "number", "required": false, "source": "body", "description": "系统商品 ID(StockWarehouse.id)。若提供,服务端会尝试回填 barcode/weight/箱规/product_name/product_snapshot 等。" }, { "name": "barcode", "type": "string", "required": false, "source": "body", "description": "条码(未传 system_product_id 时可单独更新)" }, { "name": "product_name", "type": "string", "required": false, "source": "body", "description": "商品名称(未传 system_product_id 时可单独更新)" }, { "name": "box_width", "type": "number", "required": false, "source": "body", "description": "箱宽" }, { "name": "box_height", "type": "number", "required": false, "source": "body", "description": "箱高" }, { "name": "box_length", "type": "number", "required": false, "source": "body", "description": "箱长" }, { "name": "box_remainder", "type": "number", "required": false, "source": "body", "description": "箱内剩余数量/零散数量(不满箱时的件数)" }, { "name": "box_weight", "type": "number", "required": false, "source": "body", "description": "实测箱重(单位与系统重量一致,如 g)" }, { "name": "weight", "type": "number", "required": false, "source": "body", "description": "毛重/重量(单位 g)" } ], "response": [ { "name": "data.id", "type": "number", "required": true, "description": "收货明细 ID" }, { "name": "data.receiving_id", "type": "number", "required": true, "description": "收货单 ID" }, { "name": "data.actual_quantity", "type": "number", "required": false, "description": "实际收货数量" }, { "name": "data.product_name", "type": "string", "required": false, "description": "商品名称" }, { "name": "data.barcode", "type": "string", "required": false, "description": "条码" }, { "name": "data.system_product_id", "type": "number", "required": false, "description": "系统商品 ID" }, { "name": "data.box_remainder", "type": "number", "required": false, "description": "箱内剩余数量/零散数量(不满箱时的件数)" }, { "name": "data.box_weight", "type": "number", "required": false, "description": "实测箱重(单位与系统重量一致,如 g)" }, { "name": "data.updated_at", "type": "string", "required": false, "description": "记录更新时间(ISO)" } ], "errors": [ { "code": "400", "description": "收货明细ID不能为空 / 收货单ID不能为空 / 到期日期已过期,不能录入收货 / 箱数/托盘数不能为负数等参数校验失败" }, { "code": "404", "description": "收货明细不存在或无权访问" }, { "code": "500", "description": "服务器错误或修改失败" } ] }, { "method": "storage.receiving.cancel", "description": "storage.receiving.cancel 接口", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "storage.receiving.completeReceiving", "description": "storage.receiving.completeReceiving 接口", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "notes": [ "完成收货时会发送通知:通知 payload 或 metadata 将在每条明细中携带 box_remainder(箱内剩余数量/零散件数,number)与 box_weight(实测箱重,number,单位同系统重量,例如 g)。新增字段为可选,旧客户端可忽略。" ], "errors": [] } ] }, { "groupName": "入库单", "module": "storage.entry", "list": [ { "method": "storage.entry.list", "description": "入库单列表查询。where.order_status 支持 CREATING/CREATED/PENDING/COMPLETED/CANCELLED。CREATED=已创建待审核(需审核后才能绑定和完成入库),PENDING=已审核(可绑定和完成入库)。where 新增 hasReceiving 虚拟筛选字段,传 true/false 筛选已绑定/未绑定收货单的入库单(通过 wms_entry_order_receiving 表查询实现)。quickWhere 支持模糊搜索:entry_order_code(入库单号)、purchase_order_code(采购单号)、supplier_name(供应商名称)、store_name(货主名称)、warehouse_name(仓库名称)、receiving_id(收货单 ID / 托盘唛头,通过 wms_entry_order_receiving 绑定表关联搜索)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page/pageSize" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "统一 where 条件对象;推荐使用 { operator, value, type } 标准结构,历史简写会在 main 中自动标准化;支持 quickWhere、order_status(CREATING/CREATED/PENDING/COMPLETED/CANCELLED)、store_id、order_type、日期区间等字段。新增 expense_record(费用是否记录)筛选,支持 eq/in;值会归一化为 0/1,兼容 true/false、1/0、y/n、yes/no(大小写不敏感,含布尔/字符串/数字写法)。示例:where.expense_record={operator:eq,value:true} 等价 where.expense_record={operator:eq,value:1};where.expense_record={operator:in,value:[true,\"0\",\"yes\",\"n\"]} 会归一化为 [1,0]。若部署环境尚未完成 expense_record 字段迁移,传入该筛选可能返回 400,错误提示为\"当前环境未提供 expense_record 字段,暂不支持该筛选条件,请先完成表结构升级\"。新增 hasReceiving 虚拟筛选字段,传 true/false 筛选已绑定/未绑定收货单的入库单(虚拟字段,不直接对应数据库列,内部通过 wms_entry_order_receiving 表查询实现)。quickWhere 模糊搜索范围:entry_order_code(入库单号)、purchase_order_code(采购单号)、supplier_name(供应商名称)、store_name(货主名称)、warehouse_name(仓库名称)、receiving_id(收货单 ID / 托盘唛头,通过 wms_entry_order_receiving 绑定表关联搜索)。" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数,支持 sortField/sortOrder" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "入库单列表" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)" }, { "name": "summary", "type": "object", "required": true, "description": "状态汇总(total、pending、creating、created、completed、cancelled)" }, { "name": "list[].receivingBindings", "type": "array", "required": false, "description": "收货单绑定列表(主表级关联),每项含 id、entry_order_id、receiving_id 及 receiving 对象(id、receiving_number、status、storage_status、created_at)" }, { "name": "list[].hasReceiving", "type": "boolean", "required": false, "description": "是否存在收货单绑定" } ], "errors": [ { "code": "400", "message": "筛选条件格式错误", "description": "筛选条件格式错误" }, { "code": "500", "message": "查询失败", "description": "查询失败" } ] }, { "method": "storage.entry.listStore", "description": "货主侧入库单列表查询:以货主维度(store_id)过滤入库单,货主登录后仅能查看自己货主下的入库单。与 storage.entry.list 共享底层逻辑,但主维度为 store_id 而非 warehouse_id。where.order_status 支持 CREATING/CREATED/PENDING/COMPLETED/CANCELLED。CREATED=已创建待审核(需审核后才能绑定和完成入库),PENDING=已审核(可绑定和完成入库)。where 新增 hasReceiving 虚拟筛选字段,传 true/false 筛选已绑定/未绑定收货单的入库单。quickWhere 支持模糊搜索:entry_order_code(入库单号)、purchase_order_code(采购单号)、supplier_name(供应商名称)、store_name(货主名称)、warehouse_name(仓库名称)、receiving_id(收货单 ID / 托盘唛头)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page/pageSize" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "统一 where 条件对象;推荐使用 { operator, value, type } 标准结构,历史简写会在 main 中自动标准化;支持 quickWhere、order_status(CREATING/CREATED/PENDING/COMPLETED/CANCELLED)、order_type、日期区间等字段。新增 expense_record(费用是否记录)筛选,支持 eq/in。新增 hasReceiving 虚拟筛选字段,传 true/false 筛选已绑定/未绑定收货单的入库单。quickWhere 模糊搜索范围:entry_order_code(入库单号)、purchase_order_code(采购单号)、supplier_name(供应商名称)、store_name(货主名称)、warehouse_name(仓库名称)、receiving_id(收货单 ID / 托盘唛头)。" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数,支持 sortField/sortOrder" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "入库单列表" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)" }, { "name": "summary", "type": "object", "required": true, "description": "状态汇总(total、pending、creating、created、completed、cancelled)" }, { "name": "list[].receivingBindings", "type": "array", "required": false, "description": "收货单绑定列表(主表级关联),每项含 id、entry_order_id、receiving_id 及 receiving 对象(id、receiving_number、status、storage_status、created_at)" }, { "name": "list[].hasReceiving", "type": "boolean", "required": false, "description": "是否存在收货单绑定" } ], "errors": [ { "code": "400", "message": "筛选条件格式错误", "description": "筛选条件格式错误" }, { "code": "500", "message": "查询失败", "description": "查询失败" } ] }, { "method": "storage.entry.get", "description": "查询入库单详情。通过入库单 ID 定位,关联 Store、EntryItems、EntryOrderReceiving→Receiving,并通过仓库商品详情、直接入库进度、收货单可用明细进行数据合并。entryOrder.order_status 可能为 CREATING/CREATED/PENDING/COMPLETED/CANCELLED。CREATED=已创建待审核(需审核后才能绑定和完成入库),PENDING=已审核(可绑定和完成入库)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "入库单ID(必填)" } ], "response": [ { "name": "entryOrder", "type": "object", "required": true, "description": "入库单详情,包含 items 数组、receivingBindings(主表级收货单关联数组)。items 每项含 external_item_code / external_item_id / warehouse_item_code / warehouse_item_name / warehouse_item_spec / count / received_quantity / confirm_quantity / warehouse_quantity / warehouse_locked_quantity / warehouse_is_batch_mgmt / warehouse_is_shelf_life_mgmt / warehouse_image_url / warehouse_is_images / barcodes / direct_inbound_quantity / remaining_quantity / available_receiving_details" }, { "name": "entryOrder.items[].external_item_code", "type": "string", "required": true, "description": "外部商品编码(源自 EntryItems.item_code)" }, { "name": "entryOrder.items[].external_item_id", "type": "number", "required": true, "description": "外部商品ID(源自 EntryItems.item_id)" }, { "name": "entryOrder.items[].warehouse_item_code", "type": "string", "required": true, "description": "仓库商品编码(StockWarehouse.item_code),无匹配时为空字符串" }, { "name": "entryOrder.items[].warehouse_item_name", "type": "string", "required": true, "description": "仓库商品名称(StockWarehouse.item_name),无匹配时为空字符串" }, { "name": "entryOrder.items[].warehouse_item_spec", "type": "string", "required": true, "description": "仓库商品规格(StockWarehouse.sku_property),无匹配时为空字符串" }, { "name": "entryOrder.items[].count", "type": "number", "required": true, "description": "计划入库数量" }, { "name": "entryOrder.items[].received_quantity", "type": "number", "required": true, "description": "已收货数量(收货单途径)" }, { "name": "entryOrder.items[].confirm_quantity", "type": "number", "required": true, "description": "已确认收货数量" }, { "name": "entryOrder.items[].warehouse_quantity", "type": "number", "required": true, "description": "仓库当前库存总量(StockWarehouse.quantity),无匹配时为 null" }, { "name": "entryOrder.items[].warehouse_locked_quantity", "type": "number", "required": true, "description": "仓库锁定数量(StockWarehouse.locked_quantity),无匹配时为 null" }, { "name": "entryOrder.items[].warehouse_is_batch_mgmt", "type": "string", "required": true, "description": "是否批次管理(StockWarehouse.is_batch_mgmt),Y/N;无匹配时为 null" }, { "name": "entryOrder.items[].warehouse_is_shelf_life_mgmt", "type": "string", "required": true, "description": "是否效期管理(StockWarehouse.is_shelf_life_mgmt),Y/N;无匹配时为 null" }, { "name": "entryOrder.items[].warehouse_image_url", "type": "string", "required": true, "description": "商品图片 URL,当前固定返回空字符串 ''" }, { "name": "entryOrder.items[].warehouse_is_images", "type": "string", "required": true, "description": "是否有图片(StockWarehouse.is_images),Y/N;无匹配时为 null" }, { "name": "entryOrder.items[].barcodes", "type": "array", "required": true, "description": "条码列表,每项含 { id, barcode, sku_property };无匹配时为空数组 []" }, { "name": "entryOrder.items[].direct_inbound_quantity", "type": "number", "required": true, "description": "导入/PDA 已入库数量(InboundDirectLog 按 stock_id 聚合),无记录时为 0" }, { "name": "entryOrder.items[].remaining_quantity", "type": "number", "required": true, "description": "剩余可入库数量 = max(0, count - received_quantity),最小为 0" }, { "name": "entryOrder.items[].available_receiving_details", "type": "array", "required": true, "description": "可匹配的收货单明细及剩余可用量。每项含 receiving_id / receiving_number / receiving_detail_id / actual_quantity / allocated_quantity / available_quantity。仅返回收货单状态未完成且未完全入库的明细。无匹配时为空数组 []" }, { "name": "entryOrder.receivingBindings", "type": "array", "required": true, "description": "主表级收货单关联数组,每项含 id / receiving_id / receiving(receiving 含 id / receiving_number / status / storage_status / created_at)" } ], "errors": [ { "code": "400", "message": "id 参数不能为空" }, { "code": "0", "message": "入库单不存在或无权访问" }, { "code": "200", "message": "查询成功" } ] }, { "method": "storage.entry.getStore", "description": "货主侧查询入库单详情。与 get 共享底层逻辑,但以货主维度(store_id)校验权限(不使用 warehouse_id),货主登录后仅能查看自己货主下的入库单明细。返回结构与 get 一致。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "入库单ID(必填)" } ], "response": [ { "name": "entryOrder", "type": "object", "required": true, "description": "入库单基本信息(id、entry_order_code、order_status、store_remask)" }, { "name": "items", "type": "array", "required": true, "description": "商品明细列表,每项含 id、stock_id、planned、completed、stock(商品详情)、bindings(库位绑定信息)" }, { "name": "receivingBindings", "type": "array", "required": false, "description": "主表级收货单关联数组,每项含 id / receiving_id / receiving(receiving 含 id / receiving_number / status / storage_status / created_at)" } ], "errors": [ { "code": "400", "message": "id 参数不能为空" }, { "code": "404", "message": "入库单不存在或无权访问" } ] }, { "method": "storage.entry.cancel", "description": "作废入库单(支持单条或批量作废)。CREATED(已创建待审核)和 PENDING(已审核)状态的入库单可以直接作废;已完成(COMPLETED)入库单不允许作废,sync_status=SUCCESS(已完成回传)的入库单也不允许作废;QM 来源入库单作废前先发送奇门取消同步。作废成功后按绑定行数量台账(wms_entry_order_receiving.allocated_quantity,旧数据按收货侧累计量兜底)逐绑定回收本入库单在收货单上的 stored_quantity 占用、重算各收货单 storage_status、清空台账(绑定行保留不软删),并同步重算入库单明细 received_quantity;同一收货单上其他入库单的占用不受影响(不再整体清零共享收货单);回滚失败不阻塞作废主流程(仅记录日志)。另支持按 entryOrderCode(兼容别名 entry_order_code)按单号定位入库单,供奇门/openapi 外部渠道复用(外部渠道经此复用同一作废流程并透传 skipExternalSync/idempotent/notFoundMessage 等内部选项);本渠道 id/ids 入参、响应结构与失败文案不变。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": false, "source": "body", "description": "入库单ID,兼容旧调用;与 ids 二选一。若同时传入 ids,以 ids 为准。" }, { "name": "ids", "type": "array", "required": false, "source": "body", "description": "入库单ID数组(number[]),用于批量作废;必须为非空数组,建议批量操作使用 ids,优先于 id。" }, { "name": "entryOrderCode", "type": "string", "required": false, "source": "body", "description": "入库单号(可选,内部复用口径):传入时按 entry_order_code 定位(兼容别名 entry_order_code,定位条件含 warehouse_id + is_enabled=1 + deleted_at=null),优先于 id/ids;供奇门/openapi 外部渠道复用,系统方法入口可继续使用 id/ids,行为与文案不变" } ], "response": [ { "name": "id", "type": "number", "required": false, "description": "单条作废时返回的入库单ID" }, { "name": "ids", "type": "array", "required": false, "description": "批量作废时返回的已成功作废入库单ID数组(number[])" } ], "errors": [ { "code": 400, "message": "参数错误/参数不合法:需传入非空的 id 或 ids;ids 必须为数字数组且不得包含非法或重复值;已完成(COMPLETED)入库单不允许作废" }, { "code": 400, "message": "入库单已完成回传,不可取消" }, { "code": 404, "message": "入库单不存在或无权访问" } ] }, { "method": "storage.entry.addItem", "description": "按商品增量添加导入/PDA 入库记录(支持单条和批量)。单条模式传 stock_id/quantity/inbound_type/remark,批量模式传 items 数组。批量模式所有商品共享同一个入库单状态校验,任一商品校验失败整批拒绝。若某商品累计入库量超过计划数量则拒绝(PENDING 非绑定模式)。PENDING 状态可传 receiving_detail_id 绑定收货明细(不传则走非绑定模式,数量受计划数量限制),不再强制绑定收货单、不再强制传收货单 ID;CREATED 人工导入允许超过计划数量;传入 receiving_detail_id 时 quantity 可选(自动计算可用数量),space_id 必填。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "entry_order_id", "type": "number", "required": true, "source": "body", "description": "入库单 ID" }, { "name": "stock_id", "type": "number", "required": true, "source": "body", "description": "商品SKU ID(对应 wms_stock_warehouse.id)" }, { "name": "quantity", "type": "number", "required": false, "source": "body", "description": "本次入库数量(正整数)。传入 receiving_detail_id 时可选,自动计算收货明细可用数量;非绑定模式必填" }, { "name": "inbound_type", "type": "string", "required": true, "source": "body", "description": "入库方式:import(导入入库)、pda(PDA入库)" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注(如导入文件名、PDA操作备注等)" }, { "name": "space_id", "type": "number", "required": false, "source": "body", "description": "存放库位ID(单条模式),关联 wms_location_space.id。绑定收货明细时必填;为空时 commit 默认使用库位 1" }, { "name": "receiving_detail_id", "type": "number", "required": false, "source": "body", "description": "收货单明细ID(PDA 上架绑定模式),传入后触发收货明细预占绑定,quantity 自动计算;不传则按非绑定模式直接导入,不要求绑定收货单" }, { "name": "allocated_quantity", "type": "number", "required": false, "source": "body", "description": "预分配数量(单条模式,可选,默认等于 quantity)" }, { "name": "items", "type": "array", "required": false, "source": "body", "description": "批量模式:商品列表,每项包含 stock_id(商品SKU ID, number, 必填)、quantity(入库数量, number, 绑定模式可选)、inbound_type(import/pda, string, 必填)、space_id(库位ID, number, 绑定模式必填)、remark(备注, string, 可选)、receiving_detail_id(收货明细ID, number, 可选)、allocated_quantity(预分配数量, number, 可选)。传入 items 时忽略顶层的 stock_id/quantity/inbound_type/remark/space_id。" } ], "response": [ { "name": "id", "type": "number", "required": false, "description": "单条模式返回:新增的入库记录ID" }, { "name": "stock_id", "type": "number", "required": false, "description": "商品SKU ID" }, { "name": "quantity", "type": "number", "required": false, "description": "本次入库数量" }, { "name": "inbound_type", "type": "string", "required": false, "description": "入库方式" }, { "name": "space_id", "type": "number", "required": false, "description": "存放库位ID" }, { "name": "plan_quantity", "type": "number", "required": false, "description": "入库单中该商品计划数量" }, { "name": "existing_before", "type": "number", "required": false, "description": "添加前已有入库总量" }, { "name": "existing_after", "type": "number", "required": false, "description": "添加后入库总量" }, { "name": "remaining", "type": "number", "required": false, "description": "剩余可入库数量" }, { "name": "receivingBindResult", "type": "object", "required": false, "description": "收货单绑定结果(仅绑定模式返回),含 binding_id、receiving_detail_id、allocated_quantity、status" }, { "name": "count", "type": "number", "required": false, "description": "批量模式:写入项数" }, { "name": "total_quantity", "type": "number", "required": false, "description": "批量模式:入库总数量" }, { "name": "items", "type": "array", "required": false, "description": "批量模式:每项入库记录详情(结构同单条模式)" } ], "errors": [ { "code": 400, "message": "entry_order_id 必填" }, { "code": 400, "message": "items[].stock_id 必填 / items[].quantity 必须为正整数 / items[].inbound_type 必须为 import 或 pda" }, { "code": 400, "message": "已作废入库单不允许操作 / 已完成的入库单不允许操作" }, { "code": 400, "message": "入库单已绑定收货单且状态为 CREATED,请先审核后再进行上架操作" }, { "code": 400, "message": "绑定收货明细时必须指定 space_id" }, { "code": 400, "message": "入库数量超过计划:商品计划 X,已入库 Y,本次 Z,合计 W" }, { "code": 400, "message": "收货明细可用数量不足:实际数量 X,已占用 Y,可用 Z" }, { "code": 400, "message": "入库单中不存在该商品" }, { "code": 404, "message": "入库单不存在或无权访问" } ] }, { "method": "storage.entry.commit", "description": "提交确认完成导入/PDA 入库。先同步奇门/API 回传,成功后在 onSuccess 回调内开启事务写入库存(wms_stock_warehouse.quantity 增量、wms_stock_transaction 流水),将 pending 状态的 InboundDirectLog 更新为 committed,更新入库单状态为 COMPLETED,同步 sync_status=SUCCESS。绑定收货明细的入库(InboundDirectLog.receiving_detail_id 非空)在事务内按 committed 汇总量覆写收货明细 stored_quantity/storage_status 并重算收货单主表 storage_status,同时覆写绑定行数量台账 allocated_quantity(与 stored_quantity 保持一致,setLedgerAllocation 覆写语义)。不足量提交时未入库商品跳过。noNeedNotice=1 时跳过入库完成通知(默认 0 通知)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "entry_order_id", "type": "number", "required": true, "source": "body", "description": "入库单 ID" }, { "name": "noNeedNotice", "type": "number", "required": false, "source": "body", "description": "是否跳过入库完成通知:0 通知(默认),1 不通知" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "入库单ID" }, { "name": "entry_order_code", "type": "string", "required": true, "description": "入库单号" }, { "name": "order_status", "type": "string", "required": true, "description": "入库单状态(固定为 COMPLETED)" }, { "name": "sync_status", "type": "string", "required": true, "description": "同步状态(固定为 SUCCESS)" }, { "name": "items_count", "type": "number", "required": true, "description": "入库商品种类数" }, { "name": "total_quantity", "type": "number", "required": true, "description": "入库总数量" } ], "errors": [ { "code": 400, "message": "entry_order_id 必填" }, { "code": 400, "message": "已作废入库单不允许完成 / 入库单已完成请勿重复提交 / 暂无导入/PDA 入库记录请先添加商品 / 入库单无明细" }, { "code": 404, "message": "入库单不存在或无权访问" }, { "code": 500, "message": "库存写入异常 / 同步回传失败" } ] }, { "method": "storage.entry.removeItem", "description": "移除一条导入/PDA 入库记录(仅限未提交的入库单,即状态非 CANCELLED/COMPLETED)。移除后该商品的可入库余量自动恢复。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "入库记录ID(wms_inbound_direct_log.id)" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "已移除的入库记录ID" }, { "name": "stock_id", "type": "number", "required": true, "description": "商品SKU ID" }, { "name": "quantity", "type": "number", "required": true, "description": "移除的入库数量" }, { "name": "inbound_type", "type": "string", "required": true, "description": "入库方式" } ], "errors": [ { "code": 400, "message": "id 必填 / 已作废入库单不允许操作 / 已完成的入库单不允许移除记录" }, { "code": 404, "message": "入库记录不存在 / 关联入库单不存在或无权访问" } ] }, { "method": "storage.entry.quickInbound", "description": "快捷直入(虚拟入库):将入库单商品直入到虚拟库位(space_id=2),跳过收货/质检流程。有绑定收货单时,只取收货单中与入库单明细有交集(按 stock_id 判断)且剩余可入数量(actual_quantity - stored_quantity)的商品直入,实际入库量 = min(明细计划数量, 收货单剩余可入数量),并在事务内回写收货单明细已入库数量与收货单入库状态、同步累加绑定行数量台账 allocated_quantity(recordLedgerAllocation 累计语义,旧台账为 null 的绑定行先按收货侧累计量兜底初始化);未绑定收货单时按明细计划数量全量直入。仅支持 CREATED 状态的入库单;CANCELLED(已作废)、COMPLETED(已完成)、PENDING 等其他状态均拒绝操作。事务内操作:更新入库明细收货量、累加库存总量、写入库存流水、写入虚拟库位库存、回写收货单明细、变更入库单状态为 COMPLETED,并在同一事务内回写入库单 is_virtual_inbound(是否虚拟入库):有绑定收货单 → 0(非虚拟入库),无绑定收货单 → 1(虚拟入库)。事务外异步回传奇门/API。noNeedNotice=1 时跳过入库完成通知(默认 0 通知)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "入库单ID" }, { "name": "noNeedNotice", "type": "number", "required": false, "source": "body", "description": "是否跳过入库完成通知:0 通知(默认),1 不通知" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "入库单ID" }, { "name": "entry_order_code", "type": "string", "required": true, "description": "入库单号" }, { "name": "order_status", "type": "string", "required": true, "description": "入库单状态(COMPLETED)" }, { "name": "sync_status", "type": "string", "required": true, "description": "同步状态(SUCCESS)" }, { "name": "items_count", "type": "number", "required": true, "description": "实际入库明细条目数(有绑定收货单时为与收货单有交集且实际入库量大于0的明细数)" }, { "name": "total_quantity", "type": "number", "required": true, "description": "实际入库总数量(有绑定收货单时=与收货单交集部分的实际直入数量)" }, { "name": "plan_quantity", "type": "number", "required": true, "description": "计划入库总数量" } ], "errors": [ { "code": 400, "message": "id 必填" }, { "code": 404, "message": "入库单不存在或无权访问" }, { "code": 400, "message": "已作废入库单不允许快捷入库" }, { "code": 400, "message": "入库单已完成,请勿重复提交" }, { "code": 400, "message": "入库单状态不允许快捷直入,当前状态:非CREATED(如PENDING等)" }, { "code": 400, "message": "请先添加入库明细" }, { "code": 400, "message": "收货单中无交集商品或剩余可入数量不足,无法快捷直入" }, { "code": 400, "message": "入库明细数量均为0,无法快捷直入" } ] }, { "method": "storage.entry.receivingCompare", "description": "入库单与收货单商品对照预览:给定入库单ID和收货单ID(支持多个),先将多个收货单的明细合并为一个整体,再与入库单商品做一次逐行对照,返回合并后的对照视图(每个入库明细仅一行,含匹配状态 matched/entry_only、合并收货数量与各收货单来源明细)及汇总统计。纯只读接口。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "entry_order_id", "type": "number", "required": true, "source": "body", "description": "入库单ID" }, { "name": "receiving_id", "type": "number", "required": false, "source": "body", "description": "收货单ID,单个时使用,与 receiving_ids 二选一" }, { "name": "receiving_ids", "type": "array", "required": false, "source": "body", "description": "收货单ID数组,优先使用;与 receiving_id 二选一,传了此参数则忽略 receiving_id" } ], "response": [ { "name": "entry_order_id", "type": "number", "required": true, "description": "入库单ID" }, { "name": "entry_order_code", "type": "string", "required": true, "description": "入库单号" }, { "name": "comparison", "type": "array", "required": true, "description": "合并后的逐行对照列表(多个收货单明细先合并,再与入库单对照;以入库单明细为主,每个入库明细仅一行)", "children": [ { "name": "entry_item_id", "type": "number", "required": true, "description": "入库单明细ID" }, { "name": "stock_id", "type": "number", "required": true, "description": "库存商品ID(stock_warehouse.id)" }, { "name": "warehouse_item_code", "type": "string", "required": true, "description": "入库商品编码" }, { "name": "warehouse_item_name", "type": "string", "required": true, "description": "入库商品名称" }, { "name": "warehouse_item_spec", "type": "string", "required": true, "description": "入库商品规格" }, { "name": "entry_count", "type": "number", "required": true, "description": "计划数量" }, { "name": "entry_received", "type": "number", "required": true, "description": "入库单已收数量" }, { "name": "match_status", "type": "string", "required": true, "description": "匹配状态:matched-已匹配, entry_only-仅入库(无收货商品)" }, { "name": "receiving_quantity", "type": "number", "required": true, "description": "合并后收货实际数量(所有收货单该商品明细数量之和,entry_only 时为 0)" }, { "name": "receiving_allocated", "type": "number", "required": true, "description": "合并后已分配数量" }, { "name": "receiving_available", "type": "number", "required": true, "description": "合并后可再用量(收货实际-已分配)" }, { "name": "receiving_sources", "type": "array", "required": true, "description": "收货来源明细列表(matched 时非空),每项含 receiving_id/receiving_number/receiving_detail_id/receiving_product_code/receiving_product_name/receiving_actual_quantity/receiving_allocated/receiving_available" } ] }, { "name": "receiving_only", "type": "array", "required": true, "description": "仅收货单有的商品列表(合并后仍未匹配到任何入库明细,按商品合并),每项含 stock_id/receiving_product_code/receiving_product_name/receiving_actual_quantity/receiving_allocated/receiving_available/receiving_sources" }, { "name": "summary", "type": "object", "required": true, "description": "合并对照汇总统计,含 total_entry_items/matched_items/entry_only_items/receiving_only_items" }, { "name": "errors", "type": "array", "required": false, "description": "校验失败的收货单列表(status=error 的记录)" }, { "name": "total_summary", "type": "object", "required": true, "description": "总体汇总统计", "children": [ { "name": "total_receivings", "type": "number", "description": "请求的收货单总数" }, { "name": "matched_count", "type": "number", "description": "有效参与对比的收货单数" }, { "name": "error_count", "type": "number", "description": "校验失败的收货单数" } ] } ], "errors": [ { "code": 400, "message": "entry_order_id 必填" }, { "code": 400, "message": "receiving_ids 或 receiving_id 必填" }, { "code": 404, "message": "入库单不存在或无权访问" } ] }, { "method": "storage.entry.bindReceiving", "description": "将收货单绑定到入库单(主表级关联 wms_entry_order_receiving)。入库单仅 CREATED、COMPLETED 状态允许绑定,其他状态抛错;收货单须存在且未删除、与入库单同仓库、同货主、未取消(status≠cancelled)、已审核(is_review)。CREATED 绑定:逐条写入主表绑定(幂等,已存在跳过),绑定行数量台账 allocated_quantity 初始化为空对象 {}(区别于旧数据 null),仅建立关联、不做入库进度同步。COMPLETED 绑定:事务内完成主表绑定 + 收货单入库进度同步(数量台账版防超扣)——FOR UPDATE 行锁入库单主行、该入库单全部未删除绑定行及相关收货单明细行,串行化同一入库单的分配事务;入库单明细按 SKU 汇总(entry_items.stock_id ≡ wms_receiving_detail.system_product_id),每 SKU 分配目标 = min(入库单计划数量 − 其他未删除绑定已分配量, 当前收货单该 SKU 剩余可入量),按明细 id 升序逐行补分配或回收(多退少补:旧数据超分回收、亏分补分配),同步更新收货明细 stored_quantity/storage_status(none/partial/all)、回写绑定行台账 allocated_quantity(收货明细ID→分配数量)、重算收货单主表 storage_status,并同步重算 entry_items.received_quantity(入库单侧已入库量,与各绑定收货单 stored_quantity 之和可对账);绑定已存在且未删除时跳过进度同步(幂等不重复分配),软删除绑定恢复后按归一化目标仅分配剩余量(旧超分数据归一化回收);SKU 未匹配的入库明细仅记录 unmatched_items 不阻塞;任一异常事务整体回滚。creator_id 由服务端从登录态自动注入,无需前端传值。支持部分成功:逐个收货单处理,跳过项计入 skipped。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "entry_order_id", "type": "number", "required": true, "source": "body", "description": "入库单ID" }, { "name": "receiving_ids", "type": "array", "required": true, "source": "body", "description": "要绑定的收货单ID列表,每项为 integer" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "success" }, { "name": "code", "type": "number", "required": true, "description": "1" }, { "name": "message", "type": "string", "required": true, "description": "提示信息(绑定完成)" }, { "name": "bound", "type": "array", "required": true, "description": "绑定/进度同步成功列表。CREATED 每项含 receiving_id、receiving_number、created;COMPLETED 每项额外含 restored(软删除恢复为 true)与 storage_sync(入库进度同步结果,含 stored_total、matched_item_count、unmatched_items)", "children": [ { "name": "receiving_id", "type": "number", "required": true, "description": "收货单ID" }, { "name": "receiving_number", "type": "string", "required": true, "description": "收货单号" }, { "name": "created", "type": "boolean", "required": true, "description": "本次是否新建绑定行;绑定已存在(未删除)或由软删除行恢复时为 false" }, { "name": "restored", "type": "boolean", "required": true, "description": "是否由已软删除(解绑产生)的绑定行恢复;CREATED 恢复后台账重置为 {} 不重算进度,COMPLETED 恢复后按归一化目标执行进度同步" }, { "name": "storage_sync", "type": "object", "required": false, "description": "仅 COMPLETED 新建/恢复绑定时返回的入库进度同步结果", "children": [ { "name": "stored_total", "type": "number", "required": true, "description": "本次补分配到收货单明细 stored_quantity 的总数量(归一化回收的超分数量不计入;无分配变化时可为 0)" }, { "name": "matched_item_count", "type": "number", "required": true, "description": "成功补分配数量(allocated>0)的 SKU 数量" }, { "name": "unmatched_items", "type": "array", "required": true, "description": "未匹配到收货明细的入库明细 SKU 列表(仅记录跳过,不影响绑定),每项含 stock_id、item_code、count" } ] } ] }, { "name": "skipped", "type": "array", "required": true, "description": "跳过列表,每项含 receiving_id、receiving_number、error_code、message。error_code 可能值:ALREADY_BOUND(绑定已存在,COMPLETED 幂等跳过进度同步,不重复分配)、BINDING_WRITE_FAILED(CREATED 写入绑定失败)。收货单校验失败(不存在/跨仓/跨货主/已取消/未审核)时 skipped 为空数组、仅 summary.skipped_count 计数(失败明细仅服务端日志)" }, { "name": "summary", "type": "object", "required": true, "description": "汇总统计", "children": [ { "name": "bound_count", "type": "number", "required": true, "description": "成功数量" }, { "name": "skipped_count", "type": "number", "required": true, "description": "跳过/失败数量(含收货单校验失败数)" } ] }, { "name": "timestamp", "type": "number", "required": true, "description": "响应时间戳(秒)" } ], "errors": [ { "code": 500, "message": "接口错误: entry_order_id 不能为空" }, { "code": 500, "message": "接口错误: receiving_ids 不能为空且必须为数组" }, { "code": 500, "message": "接口错误: 入库单不存在" }, { "code": 500, "message": "接口错误: 入库单状态不允许绑定,当前状态: {当前状态},仅 CREATED、COMPLETED 状态可操作" }, { "code": 500, "message": "接口错误: 入库单绑定收货单失败,已回滚: {原因}(COMPLETED 事务内主表绑定+进度同步任一异常整体回滚)" }, { "code": "RECEIVING_NOT_FOUND", "message": "收货单不存在或已删除(业务校验失败不抛错:skipped 为空数组,计入 summary.skipped_count,失败明细仅服务端日志)" }, { "code": "WAREHOUSE_MISMATCH", "message": "收货单与入库单不属于同一仓库(处理同上)" }, { "code": "OWNER_MISMATCH", "message": "收货单与入库单货主不一致(处理同上)" }, { "code": "RECEIVING_CANCELLED", "message": "收货单已取消(处理同上)" }, { "code": "RECEIVING_NOT_REVIEWED", "message": "收货单未审核(处理同上)" }, { "code": "ALREADY_BOUND", "message": "绑定关系已存在,跳过入库进度同步(COMPLETED 幂等,计入 skipped,不重复分配 stored_quantity)" }, { "code": "BINDING_WRITE_FAILED", "message": "写入绑定失败: {原因}(CREATED 逐条写入异常,计入 skipped)" } ] }, { "method": "storage.entry.reviewEntry", "description": "审核入库单(CREATED → PENDING),仅允许已绑定收货单的入库单推进状态", "isNeedAuth": false, "isNeedLogin": true, "isNeedRight": false, "isNeedLog": true, "headers": [], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "入库单ID" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "success/failure" }, { "name": "code", "type": "number", "required": true, "description": "200 成功 / 400 失败" }, { "name": "message", "type": "string", "required": true, "description": "提示信息" }, { "name": "data.id", "type": "number", "required": true, "description": "入库单ID" }, { "name": "data.order_status", "type": "string", "required": true, "description": "审核后状态(PENDING)" } ], "errors": [ { "code": 400, "message": "id 必填" }, { "code": 400, "message": "入库单不存在" }, { "code": 400, "message": "当前状态[xxx]不允许审核,仅 CREATED 可审核" }, { "code": 400, "message": "入库单未绑定收货单,请先绑定收货单后再审核" } ] }, { "method": "storage.entry.containerList", "description": "PDA 上架时拉取入库单已绑定收货单中指定商品的可用容器列表(未绑定的收货明细)。返回匹配明细的 detail_id、receiving_id、barcode、product_name、actual_quantity、receiving_status,以及商品详情 stock。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "entry_order_id", "type": "number", "required": true, "source": "body", "description": "入库单 ID" }, { "name": "stock_id", "type": "number", "required": true, "source": "body", "description": "商品 stock_id(即 wms_stock_warehouse.id)" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "可用容器(收货明细)列表" }, { "name": "list[].detail_id", "type": "number", "required": true, "description": "收货明细 ID" }, { "name": "list[].receiving_id", "type": "number", "required": true, "description": "收货单 ID" }, { "name": "list[].barcode", "type": "string", "required": true, "description": "商品条码" }, { "name": "list[].product_name", "type": "string", "required": true, "description": "商品名称" }, { "name": "list[].actual_quantity", "type": "number", "required": true, "description": "实收数量" }, { "name": "list[].receiving_status", "type": "string", "required": true, "description": "收货单状态" }, { "name": "list[].stock", "type": "object", "required": true, "description": "商品详情(通过 getStockDetails 获取,含 item_code、item_name、sku_property、barcodes 等缓存字段)" }, { "name": "total", "type": "number", "required": true, "description": "匹配总数" } ], "errors": [ { "code": 0, "message": "用户未绑定仓库" }, { "code": 0, "message": "entry_order_id 不能为空" }, { "code": 0, "message": "stock_id 不能为空" }, { "code": 0, "message": "入库单不存在或无权访问" }, { "code": 500, "message": "服务器查询失败" } ] }, { "method": "storage.entry.queryEntryLogs", "description": "查询入库单操作日志。根据入库单 ID 分页查询关联的操作日志记录(入库单创建、状态变更、审核等操作的审计轨迹)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "入库单 ID(必填)" }, { "name": "page", "type": "number", "required": false, "source": "body", "description": "页码,默认 1" }, { "name": "pageSize", "type": "number", "required": false, "source": "body", "description": "每页数量,默认 20" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "操作日志列表" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)" } ], "errors": [ { "code": 400, "message": "id 不能为空" }, { "code": 500, "message": "查询失败" } ] }, { "method": "storage.entry.unbindReceiving", "description": "解除入库单与收货单的主表绑定关系,并按数量台账回滚该收货单的入库进度。仅 CREATED / PENDING 状态的入库单可解绑(COMPLETED / CANCELLED 不允许),解绑不回退入库单状态。逐个收货单处理:主表绑定不存在计入 failed(BINDING_NOT_FOUND);存在则在事务内 FOR UPDATE 行锁入库单主行与绑定行,按绑定行台账(wms_entry_order_receiving.allocated_quantity,旧数据按收货侧累计量兜底)逐明细回收该收货单 stored_quantity、重算明细与主表 storage_status、台账重置为空对象 {},软删除主表绑定与关联明细绑定(InboundDirectLog 中 status=committed 且 receiving_detail_id 非空、属于该收货单的记录);同一收货单上其他入库单的占用不受影响。返回 success/failed/success_count/failed_count,success 项含 rolled_back_quantity(本次回滚的 stored_quantity 总量)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "entry_order_id", "type": "number", "required": true, "source": "body", "description": "入库单ID" }, { "name": "receiving_ids", "type": "array", "required": true, "source": "body", "description": "要解除绑定的收货单ID列表,每项为 integer" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "success" }, { "name": "code", "type": "number", "required": true, "description": "1" }, { "name": "message", "type": "string", "required": true, "description": "提示信息(解绑完成)" }, { "name": "success", "type": "array", "required": true, "description": "解绑成功列表,每项含 receiving_id、released_detail_ids、released_detail_count、rolled_back_quantity、message", "children": [ { "name": "receiving_id", "type": "number", "required": true, "description": "收货单ID" }, { "name": "released_detail_ids", "type": "array", "required": true, "description": "已软删除的关联明细绑定对应的收货明细ID列表(wms_receiving_detail.id)" }, { "name": "released_detail_count", "type": "number", "required": true, "description": "已软删除的关联明细绑定数(InboundDirectLog 中 status=committed 且 receiving_detail_id 非空的记录数)" }, { "name": "rolled_back_quantity", "type": "number", "required": true, "description": "本次按台账回滚的该收货单 stored_quantity 总量(无可回滚量时为 0)" }, { "name": "message", "type": "string", "required": true, "description": "处理结果说明(已解除绑定并回滚收货单入库进度)" } ] }, { "name": "failed", "type": "array", "required": true, "description": "解绑失败列表,每项含 receiving_id、error_code、message。error_code 可能值:BINDING_NOT_FOUND(主表绑定不存在)、ENTRY_ORDER_NOT_FOUND(入库单不存在)、ENTRY_ORDER_STATUS_INVALID(入库单状态不允许解绑)、UNBIND_ERROR(解绑过程异常)" }, { "name": "success_count", "type": "number", "required": true, "description": "解绑成功数量" }, { "name": "failed_count", "type": "number", "required": true, "description": "解绑失败数量" }, { "name": "timestamp", "type": "number", "required": true, "description": "响应时间戳(秒)" } ], "errors": [ { "code": 500, "message": "接口错误: entry_order_id 不能为空" }, { "code": 500, "message": "接口错误: receiving_ids 不能为空且必须为数组" }, { "code": "ENTRY_ORDER_NOT_FOUND", "message": "入库单不存在(业务校验失败不抛错:success 为空数组,全部收货单计入 failed,failed_count=请求收货单数)" }, { "code": "ENTRY_ORDER_STATUS_INVALID", "message": "入库单状态不允许解绑,当前状态: {状态}(仅 CREATED、PENDING 可解绑;处理同上不抛错)" }, { "code": "BINDING_NOT_FOUND", "message": "主表绑定不存在(计入 failed)" }, { "code": "UNBIND_ERROR", "message": "解绑过程异常: {原因}(计入 failed,已执行的回滚在事务内回退)" } ] } ] }, { "groupName": "出库单模块", "module": "storage.stockout", "list": [ { "method": "storage.stockout.list", "name": "出库单列表", "description": "非订单出库单能力(对应奇门 stockout.create):直接读取 wms_order_stockout 表;主出口为 storage.stockout.*,不再推荐通过 storage.delivery.* 命名使用。storage.delivery.* 仅保留兼容转发。", "isNeedAuth": true, "isNeedLogin": true, "isNeedRight": false, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page/pageSize" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "统一 where 条件对象;推荐使用 { operator, value, type } 标准结构,历史简写会在 main 中自动标准化;常用字段包括 stockout_order_code、order_status、order_type、source_type、remark 与日期区间字段。" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数,支持 sortField/sortOrder,可选字段:id、stockout_order_code、order_status、order_type、updated_at、created_at、order_create_time,默认按 updated_at DESC、id DESC" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "出库单列表(wms_order_stockout 表记录,含 store_id/store_name 货主信息与 sync_status/sync_message 出站同步状态字段;不含 id、warehouse_id、warehouse_name)" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)" } ], "errors": [ { "code": "400", "description": "筛选条件格式错误" }, { "code": "500", "description": "查询失败" } ] }, { "method": "storage.stockout.toOrder", "name": "出库单转订单", "description": "将非订单出库单转为正式销售订单:新订单 create_channel 固定为 STOCKOUT;转单时释放出库单占用的库存锁定并转由新订单重新锁定;转单成功后原出库单置为 TRANSFERRED(已转订单,该状态禁止一键出库)并记录已转订单号(幂等,重复调用返回原订单信息)。仅 CREATED / PENDING 状态允许转单;建单失败自动补偿恢复出库单锁定。收货信息必填:name、(tel/mobile) 至少一项、省市区镇详细地址,缺失返回错误禁止转单;收货信息优先接口传入,未传回填出库单已存的收件人字段;快递编码沿用出库单已解析的 express_code,平台优先使用出库单已存 source_platform_code,为空使用兜底平台。", "isNeedAuth": false, "isNeedLogin": true, "isNeedRight": false, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "出库单ID(必填)" }, { "name": "delivery_order_code", "type": "string", "required": false, "source": "body", "description": "新订单号,不传自动生成(SK 前缀)" }, { "name": "receiverInfo", "type": "object", "required": false, "source": "body", "description": "收件人信息(name/mobile/tel/province/city/area/town/detailAddress/zipCode 等),不传时回填出库单已存的收件人字段;name、(tel/mobile) 其一、省市区镇详细地址必填,缺失则报错不能转订单" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "出库单ID" }, { "name": "stockout_order_code", "type": "string", "required": true, "description": "出库单号" }, { "name": "order_id", "type": "number", "required": true, "description": "新订单ID" }, { "name": "delivery_order_code", "type": "string", "required": true, "description": "新订单号" }, { "name": "step", "type": "number", "required": false, "description": "订单步骤(0=待审核,1=待处理)" } ], "errors": [ { "code": "400", "description": "出库单不存在 / 状态不允许转单 / 无明细 / 订单创建失败" }, { "code": "500", "description": "释放或恢复库存锁定失败" } ] }, { "method": "storage.stockout.listItems", "name": "出库单拉取明细", "description": "按出库单查询商品明细(用于非订单出库单),直接读取 wms_order_stockout + wms_order_stockout_items 表。", "isNeedAuth": true, "isNeedLogin": true, "isNeedRight": false, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "stockout_order_code", "type": "string", "required": false, "source": "body", "description": "出库单号(推荐);兼容 delivery_order_code 旧参数名" }, { "name": "id", "type": "number", "required": false, "source": "body", "description": "出库单ID,可选;与 stockout_order_code 至少传一个" } ], "response": [ { "name": "order", "type": "object", "required": true, "description": "出库单基础信息(wms_order_stockout 表记录,含 id、stockout_order_code)" }, { "name": "list", "type": "array", "required": true, "description": "出库单商品明细(wms_order_stockout_items 表记录)" } ], "errors": [ { "code": "404", "description": "出库单不存在" }, { "code": "500", "description": "缺少定位参数或查询失败" } ] }, { "method": "storage.stockout.listLogs", "name": "出库单操作日志", "description": "查询出库单操作日志(分页)。日志业务类型 business_type=stockout、business_id=出库单ID,覆盖转订单(STOCKOUT_TO_ORDER)、确认直出(STOCKOUT_CONFIRM)、修改信息(STOCKOUT_UPDATE_INFO)、取消(STOCKOUT_CANCEL)等操作。按创建时间倒序。", "isNeedAuth": true, "isNeedLogin": true, "isNeedRight": false, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": false, "source": "body", "description": "出库单ID;与 stockout_order_code 至少传一个" }, { "name": "stockout_order_code", "type": "string", "required": false, "source": "body", "description": "出库单号(推荐);与 id 至少传一个" }, { "name": "page", "type": "number", "required": false, "source": "body", "description": "页码(默认1);与订单日志接口一致,支持顶层传参" }, { "name": "pageSize", "type": "number", "required": false, "source": "body", "description": "每页数量(默认20,兼容 page_size)" }, { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页对象写法({ page, pageSize }),与顶层 page/pageSize 二选一,顶层优先" } ], "response": [ { "name": "data.list", "type": "array", "required": true, "description": "操作日志列表(含 operation_code/operation_name/operator_name/message/created_at 等,与订单日志字段一致)" }, { "name": "data.pagination", "type": "object", "required": true, "description": "分页信息 { page, pageSize, total, totalPages }" } ], "errors": [ { "code": "400", "description": "id 或 stockout_order_code 至少传一个 / 缺少仓库上下文" } ] }, { "method": "storage.stockout.confirm", "name": "出库单确认(直出)", "description": "直出确认出库单:不改变内部库存,按出库单明细计划数量(plan_qty)直接确认。运单号以复数 waybill_codes 为准(一单多运单),回传时按奇门 packages.package[].expressCode 承载,不使用 deliveryOrder.expressCode;单数 waybill_code 已弃用,仅在复数缺失时对存量单做兼容回退。出站回传按出库单 source_type 分流:QM→奇门 taobao.qimen.stockout.confirm;API→OpenAPI 回调(method=stockout.confirm,appKey 按货主合约反查 wms_store_warehouse(auth_status=2) 与 wms_api_app(启用且 callback_url 非空));WMS 等内部来源无需通知外部、直接视为成功。回传成功后释放创建时占用的库存锁定(QM_STOCKOUT,写 UNLOCK 流水)并把状态推进到 COMPLETED;回传失败则返回错误,order_status 不变,sync_status 标记为 FAILED(可重试)。", "isNeedAuth": true, "isNeedLogin": true, "isNeedRight": false, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "出库单ID(必填)" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "出库单ID" }, { "name": "stockout_order_code", "type": "string", "required": true, "description": "出库单号" }, { "name": "order_status", "type": "string", "required": true, "description": "确认后状态(COMPLETED)" }, { "name": "logisticsName", "type": "string", "required": true, "description": "物流公司名称(当前实现固定返回字符串 OTHER)" }, { "name": "expressCode", "type": "string", "required": true, "description": "快递公司编码(当前实现取自 wms_order_stockout.express_code)。历史遗留命名:该字段名来源于旧口径,实际语义是快递公司编码,不是运单号;运单号见 waybill_codes" }, { "name": "expressCodes", "type": "array", "required": false, "description": "当前实现取自已废弃字段 wms_order_stockout.express_codes(通常为 null)。运单号请以 waybill_codes 为准,该字段待代码侧收敛" }, { "name": "qimenSync", "type": "string", "required": true, "description": "外部回传结果:success=通知成功,failure=通知失败(确认本身不受影响)。字段名为历史遗留,API/WMS 来源同样复用该字段表示回传结果" }, { "name": "qimenSyncMessage", "type": "string", "required": false, "description": "外部回传失败时的错误信息" } ], "errors": [ { "code": "400", "message": "缺少出库单ID" }, { "code": "400", "message": "出库单不存在" }, { "code": "400", "message": "出库单当前状态不允许确认(非 CREATED/PENDING)" }, { "code": "400", "message": "出库单未填写运单号(waybill_codes),请先更新运单号后再确认" }, { "code": "400", "message": "出站同步失败: <失败原因>(QM:奇门响应 code + message,如「-1 无法匹配货主」;API:「缺少 appKey,无法回传出库单」或 OpenAPI 回调失败原因;回传服务不可用:「出库单回传服务不可用」)" } ], "notes": [ "运单号口径(2026-09-13):校验与回传均以复数 waybill_codes 为准(不足则回退单数 waybill_code 兼容存量单),错误文案由 waybill_code 改为 waybill_codes。", "多运单模型:报文 packages.package[] 每个元素一个包裹(expressCode = 对应运单号),deliveryOrder.expressCode 不传(奇门多运单以 packages 为准)。", "已知待收敛项(代码侧,本次未做):packages.package[].packageCode 当前所有包裹共用出库单号(多包裹时重复);每个包裹的 items 为全量明细(未按包裹拆分),严格按包裹归属需补充「包裹-明细」关联模型。", "出站分流:confirm 复用 systems/order_async.js#notifyStockoutExternalInternal,与出库单转订单回传口径一致(QM→奇门、API→OpenAPI 回调 stockout.confirm、WMS 等内部来源直接成功)。", "报文组装复用 systems/order_async.js#buildStockoutConfirmDataInternal:快递信息取 express_code/express_name,orderLines[].ownerCode 取明细 owner_code(为空回退出库单 qimen_owner_code)。", "已知待收敛项:确认成功响应里的 expressCode / expressCodes 仍分别返回 express_code / express_codes,与 waybill_codes 不一致,待代码侧统一。" ] }, { "method": "storage.stockout.updateExpress", "name": "更新出库单快递/运单号", "description": "更新出库单的快递公司与运单号(express_code / waybill_codes),用于在确认前填写运单信息。express_code 是快递公司编码(如 SF/STO/ZT),传入后自动从系统快递表解析 express_name(匹配不到置空串,传空值则 express_code 与 express_name 置 NULL);运单号以复数 waybill_codes(JSON 数组)为准,支持一单多运单。单数 waybill_code 已弃用:传入 waybill_codes 时会自动把单数列镜像为复数首个(便于历史查询与展示),传入空数组或 null 时单数列同步置 NULL。已废弃字段 express_codes 不在本接口读写范围内。未传入的字段不更新,三个字段都未传时返回「没有需要更新的字段」。", "isNeedAuth": true, "isNeedLogin": true, "isNeedRight": false, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "出库单ID(必填)" }, { "name": "express_code", "type": "string", "required": false, "source": "body", "description": "快递公司编码(非运单号,如 SF/STO/ZT);传入后自动解析 express_name,传空值置 NULL" }, { "name": "waybill_codes", "type": "array", "required": false, "source": "body", "description": "运单号列表(JSON 数组或 null,支持一单多运单);回传与确认校验以此为准,非数组返回 400" }, { "name": "waybill_code", "type": "string", "required": false, "source": "body", "description": "运单号(单数,已弃用):仅作为 waybill_codes 首个的镜像保留;传 waybill_codes 时会以复数首个覆盖它,勿单独使用" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "出库单ID" }, { "name": "stockout_order_code", "type": "string", "required": true, "description": "出库单号" }, { "name": "express_code", "type": "string", "required": false, "description": "更新后的快递公司编码" }, { "name": "express_name", "type": "string", "required": false, "description": "由 express_code 解析出的快递公司名称" }, { "name": "waybill_codes", "type": "array", "required": false, "description": "更新后的运单号列表(以此为准)" }, { "name": "waybill_code", "type": "string", "required": false, "description": "单数列镜像值(等于 waybill_codes 首个;已弃用,仅为历史兼容)" } ], "errors": [ { "code": "400", "message": "缺少出库单ID" }, { "code": "400", "message": "出库单不存在" }, { "code": "400", "message": "没有需要更新的字段" }, { "code": "400", "message": "waybill_codes 必须是数组或 null" } ], "notes": [ "运单号口径变更(2026-09-13):以复数 waybill_codes 为准(对齐奇门 packages.package[] 多运单模型),单数 waybill_code 降级为镜像字段。", "镜像规则:传 waybill_codes(非空数组)→ waybill_code = 首个;传空数组或 null → 两列同时置 NULL;同时传单数与复数 → 以复数首个覆盖单数;仅传单数 → 行为不变(兼容旧调用方)。", "废弃字段提醒:express_codes(复数,历史名)已 @deprecated,本接口不读不写;运单号列表请用 waybill_codes。", "已知待收敛项(代码侧,本次未做):对未识别/废弃参数(如 express_codes)既不报错也不兼容,仍会返回「更新成功」造成静默失败;另外本方法缺少 warehouse_id 归属校验(同文件 storage.stockout.updateInfo 有该校验)。" ] }, { "method": "storage.stockout.updateInfo", "name": "修改出库单信息", "description": "修改出库单信息:收件人(name/tel/mobile/company/email 等)、地址(province/city/area/town/detailAddress/zipCode/countryCode)、快递编码(express_code,自动解析 express_name)、来源平台(source_platform_code/source_platform_name)。未传入的字段不修改;修改后收货信息不完整(name、(tel/mobile) 其一、省市区镇详细地址缺任一)禁止提交。仅 CREATED/PENDING 状态允许修改。", "isNeedAuth": true, "isNeedLogin": true, "isNeedRight": false, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "出库单ID(必填)" }, { "name": "name", "type": "string", "required": false, "source": "body", "description": "收件人姓名" }, { "name": "tel", "type": "string", "required": false, "source": "body", "description": "收件人固定电话" }, { "name": "mobile", "type": "string", "required": false, "source": "body", "description": "收件人移动电话" }, { "name": "company", "type": "string", "required": false, "source": "body", "description": "收件人公司名称" }, { "name": "email", "type": "string", "required": false, "source": "body", "description": "收件人电子邮箱" }, { "name": "zipCode", "type": "string", "required": false, "source": "body", "description": "邮编" }, { "name": "countryCode", "type": "string", "required": false, "source": "body", "description": "国家二字码" }, { "name": "province", "type": "string", "required": false, "source": "body", "description": "省份" }, { "name": "city", "type": "string", "required": false, "source": "body", "description": "城市" }, { "name": "area", "type": "string", "required": false, "source": "body", "description": "区/县" }, { "name": "town", "type": "string", "required": false, "source": "body", "description": "镇/街道" }, { "name": "detailAddress", "type": "string", "required": false, "source": "body", "description": "详细地址" }, { "name": "receiver_id", "type": "string", "required": false, "source": "body", "description": "收件人证件号" }, { "name": "express_code", "type": "string", "required": false, "source": "body", "description": "快递公司编码,传入后自动解析 express_name" }, { "name": "source_platform_code", "type": "string", "required": false, "source": "body", "description": "来源平台编码" }, { "name": "source_platform_name", "type": "string", "required": false, "source": "body", "description": "来源平台名称" } ], "response": [ { "name": "data", "type": "object", "required": true, "description": "更新后的出库单完整记录(wms_order_stockout 表字段,含 receiver_*、express_*、source_platform_* 等)" } ], "errors": [ { "code": "400", "description": "缺少出库单ID / 出库单不存在 / 状态不允许修改" }, { "code": "400", "description": "收货信息缺失,禁止提交(列出缺失字段)" } ] }, { "method": "storage.stockout.cancel", "name": "出库单取消", "description": "取消出库单:仅 CREATED/PENDING 状态允许取消;事务内释放创建时占用的库存锁定(QM_STOCKOUT,写 UNLOCK 流水),状态置为 CANCELLED,并写 wms_operation_log 操作日志(STOCKOUT_CANCEL)。TRANSFERRED(已转订单)与 COMPLETED(已完成)状态禁止取消。实现委托共享服务 systems/stockout_order.js#cancel(奇门 / openapi 同口径:单事务 + 行锁,并发取消/确认/转单更安全,已 CANCELLED 幂等返回成功)。", "isNeedAuth": true, "isNeedLogin": true, "isNeedRight": false, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "出库单ID(必填)" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "出库单ID" }, { "name": "stockout_order_code", "type": "string", "required": true, "description": "出库单号" }, { "name": "order_status", "type": "string", "required": true, "description": "取消后状态(CANCELLED)" } ], "errors": [ { "code": 400, "message": "缺少出库单ID" }, { "code": 400, "message": "缺少仓库上下文" }, { "code": 404, "message": "出库单不存在" }, { "code": 400, "message": "出库单当前状态(xxx)不允许取消(仅 CREATED/PENDING 可取消)" } ] } ] }, { "groupName": "库存管理模块", "module": "storage.inventory", "list": [ { "method": "storage.inventory.quickPutaway", "description": "收货单快捷入库:将已审核的收货单(completed + is_review=true)明细按 stock_id(system_product_id)分组合并数量后,直接创建入库单(SCRK,自动审批到 PENDING),写入 wms_entry_order_receiving 主表级绑定,并更新收货单及其明细的入库状态(storage_status)。要求货主仓库签约配置 policy_config.allow_receiving_quick_putaway=1 开启快捷入库功能。", "isNeedAuth": true, "isNeedLogin": true, "headers": [], "params": [ { "name": "receiving_id", "type": "number", "required": true, "source": "body", "description": "收货单ID(必填)" } ], "response": [ { "name": "entry_order_id", "type": "number", "description": "创建的入库单ID" }, { "name": "entry_order_code", "type": "string", "description": "入库单号(SCRK + 年月日 + 4位流水号)" }, { "name": "order_status", "type": "string", "description": "入库单状态(PENDING)" }, { "name": "receiving_id", "type": "number", "description": "收货单ID" }, { "name": "total_lines", "type": "number", "description": "入库单明细行数(按 stock_id 合并后的行数)" }, { "name": "total_quantity", "type": "number", "description": "入库总数量" } ], "errors": [ { "code": 400, "message": "receiving_id 必填" }, { "code": 400, "message": "无法获取当前仓库信息" }, { "code": 404, "message": "收货单不存在或无权访问" }, { "code": 400, "message": "收货单已作废,不允许快捷入库" }, { "code": 400, "message": "收货单状态不允许快捷入库,仅 completed 状态可操作" }, { "code": 400, "message": "收货单未审核,不允许快捷入库" }, { "code": 400, "message": "货主仓库签约关系不存在" }, { "code": 400, "message": "货主未开启收货单快捷入库功能" }, { "code": 400, "message": "收货单无明细,无法创建入库单" }, { "code": 400, "message": "收货单中所有明细均未关联系统商品,无法创建入库单" }, { "code": 400, "message": "以下商品在当前仓库中不存在或已失效" }, { "code": 500, "message": "系统异常" } ] }, { "method": "storage.inventory.directPutaway", "description": "收货单直入库存(一步完成):将已审核的收货单(completed + is_review=true)未入库明细直接写入 wms_storage 库位库存并生成入库单(SCRK,一步置为 COMPLETED),入库单明细与收货明细一一对应(不合并,逐行保留库位/批次/效期),同时更新 wms_stock_warehouse 总库存并写入出入库流水(wms_stock_transaction / wms_storage_transaction),并写入 wms_inbound_direct_log(status=committed,与 storage.entry.commit 链路口径一致),回填收货单及其明细的入库状态。库位规则:收货明细 space_id 有效则按其库位入库,否则使用仓库设置 subject_config.default_location_id,未设置则兜底库位 1。要求货主仓库签约配置 policy_config.allow_receiving_direct_putaway=1 开启直入库存功能。", "isNeedAuth": true, "isNeedLogin": true, "params": [ { "name": "receiving_id", "type": "number", "required": true, "source": "body", "description": "收货单ID(必填)" } ], "response": [ { "name": "entry_order_id", "type": "number", "description": "生成的入库单ID" }, { "name": "entry_order_code", "type": "string", "description": "入库单号(SCRK + 年月日 + 4位流水号)" }, { "name": "order_status", "type": "string", "description": "入库单状态(COMPLETED,一步完成)" }, { "name": "receiving_id", "type": "number", "description": "收货单ID" }, { "name": "total_lines", "type": "number", "description": "入库单明细行数(与待入库收货明细一一对应)" }, { "name": "total_quantity", "type": "number", "description": "入库总数量" } ], "errors": [ { "code": 400, "message": "receiving_id 必填" }, { "code": 400, "message": "无法获取当前仓库信息" }, { "code": 404, "message": "收货单不存在或无权访问" }, { "code": 400, "message": "收货单已作废,不允许直入库存" }, { "code": 400, "message": "收货单状态不允许直入库存,仅 completed 状态可操作" }, { "code": 400, "message": "收货单未审核,不允许直入库存" }, { "code": 400, "message": "货主仓库签约关系不存在" }, { "code": 400, "message": "货主未开启收货单直入库存功能" }, { "code": 400, "message": "收货单无明细,无法直入库存" }, { "code": 400, "message": "收货单所有明细均已入库,禁止重复直入库存" }, { "code": 400, "message": "以下商品未匹配系统商品,请先绑定" }, { "code": 400, "message": "以下商品在当前仓库中不存在或已失效" }, { "code": 500, "message": "系统异常" } ] }, { "method": "storage.inventory.transferLocation", "description": "单商品单库位移库,将库存从一个库位移动到另一个库位,支持部分数量移库和全量移库", "name": "库存移库(库位转移)", "isNeedAuth": true, "isNeedLogin": true, "params": [ { "name": "storage_id", "type": "number", "required": true, "source": "body", "description": "库存记录ID" }, { "name": "target_space_id", "type": "number", "required": true, "source": "body", "description": "目标库位ID" }, { "name": "quantity", "type": "number", "required": false, "source": "body", "description": "移库数量,不传则全部移动" } ], "response": { "storage_id": "原库存记录ID", "target_space_id": "目标库位ID", "quantity": "实际移库数量", "success": "是否成功(boolean)", "message": "结果说明" }, "errors": [ { "code": 400, "message": "storage_id 必填" }, { "code": 400, "message": "target_space_id 必填" }, { "code": 400, "message": "移库数量必须大于0且不超过可用库存" }, { "code": 400, "message": "目标库位与原库位相同" }, { "code": 404, "message": "库存记录不存在或无权访问" }, { "code": 404, "message": "目标库位不存在或不属于该仓库" } ] }, { "method": "storage.inventory.transferByProduct", "description": "按库位+商品维度移库,自动查找原库位下该商品的所有库存记录并合并移动。不适用于开启批次管理的商品", "name": "按商品移库(库位转移)", "isNeedAuth": true, "isNeedLogin": true, "params": [ { "name": "space_id", "type": "number", "required": true, "source": "body", "description": "原库位ID" }, { "name": "stock_id", "type": "number", "required": true, "source": "body", "description": "商品SKU ID(wms_stock_warehouse.id)" }, { "name": "target_space_id", "type": "number", "required": true, "source": "body", "description": "目标库位ID" }, { "name": "quantity", "type": "number", "required": true, "source": "body", "description": "移库数量" } ] }, { "method": "storage.inventory.list", "description": "库存列表查询(查 wms_storage),支持 where 条件、分页、排序、批次分组。默认按库位+商品合并数量(合并模式),group_by_batch=true 时返回每条库存明细(明细模式)。仅返回有量库存:明细模式过滤 quantity=0 的行,合并模式过滤总数量为 0 的商品。", "name": "库存列表", "isNeedAuth": false, "isNeedLogin": true, "isNeedRight": false, "params": [ { "name": "where", "type": "object", "required": false, "source": "body", "description": "统一 where 条件对象,可用字段:stock_id(商品ID)、space_id(库位ID)、store_id(货主ID)、inventory_type(ZP/CC/JS/XS/ZT/DJ/FP)、batch_no(批次号)、inbound_order_no(入库单号)、available_quantity(可用数量,支持 gt/lt)、inbound_time(入库时间,支持 between)、created_at(创建时间,支持 between)、stock_query(虚拟筛选字段:按商品编码/名称/货物编码/条码/SKU ID 模糊匹配,如 { operator: 'like', value: '111' })" }, { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数 { page, pageSize },默认 page=1, pageSize=20" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数 { sortField, sortOrder },默认 sortField='created_at', sortOrder='DESC'" }, { "name": "group_by_batch", "type": "boolean", "required": false, "source": "body", "description": "是否按批次查询,默认 false。false=合并模式(按库位+商品聚合quantity/locked_quantity/available_quantity),true=明细模式(逐条返回含 batch_no/production_date/expiry_date 等)" } ], "response": { "_note": "响应结构因 group_by_batch 而异", "_shelf_life_note": "production_date 和 expiry_date 为库存批次日期字段;is_shelf_life_warning_triggered 表示该库存在商品启用保质期管理且剩余天数小于等于阈值时是否触发效期预警。", "list_merged": { "_description": "group_by_batch=false(默认合并模式),仅按 stock_id 分组聚合,跨库位、跨库存类型汇总", "list": [ { "stock_id": "商品库存ID", "warehouse_id": "仓库ID(MIN 聚合值)", "store_id": "货主ID(MIN 聚合值)", "quantity": "总库存数量(SUM)", "locked_quantity": "总锁定数量(SUM)", "available_quantity": "总可用数量(SUM)", "first_inbound_time": "最早入库时间", "last_inbound_time": "最晚入库时间", "batch_count": "批次数", "production_date": "生产日期(库存批次日期字段,合并模式下可能为 null)", "expiry_date": "过期日期(库存批次日期字段,合并模式下可能为 null)", "is_shelf_life_warning_triggered": "布尔,表示效期预警是否触发(仅在商品启用保质期管理且剩余天数 ≤ 阈值时为 true)", "stock": { "id": "商品ID", "item_code": "商品编码", "item_name": "商品名称", "sku_property": "规格", "stock_unit": "单位", "store_name": "货主名称(来源于签约表 store_remask,若无签约关系则为 null)" } } ], "pagination": { "page": 1, "pageSize": 20, "total": 100, "totalPages": 5 } }, "list_detail": { "_description": "group_by_batch=true(明细模式)", "list": [ { "id": "库存记录ID", "warehouse_id": "仓库ID", "store_id": "货主ID", "space_id": "库位ID", "stock_id": "商品库存ID", "batch_no": "批次号", "inventory_type": "库存类型", "quantity": "库存数量", "locked_quantity": "锁定数量", "available_quantity": "可用数量", "production_date": "生产日期(库存批次日期字段)", "expiry_date": "过期日期(库存批次日期字段)", "inbound_time": "入库时间", "inbound_order_no": "入库单号", "receiving_id": "收货单ID", "entry_order_id": "入库单ID", "supplier_batch_no": "供应商批次号", "created_at": "创建时间", "updated_at": "更新时间", "is_shelf_life_warning_triggered": "布尔,表示效期预警是否触发(仅在商品启用保质期管理且剩余天数 ≤ 阈值时为 true)", "stock": { "id": "商品ID", "item_code": "商品编码", "item_name": "商品名称", "sku_property": "规格", "stock_unit": "单位", "store_name": "货主名称(来源于签约表 store_remask,若无签约关系则为 null)" }, "space": { "id": "库位ID", "space_code": "库位编码", "custom_name": "库位名称" } } ], "pagination": { "page": 1, "pageSize": 20, "total": 100, "totalPages": 5 } } } }, { "method": "storage.inventory.export", "description": "提交库存导出异步任务。支持两种导出模式(exportMode):stock_location(默认,按 stock_id + 库位聚合导出库存汇总,含库位编码/名称、商品信息、总库存/锁定/可用、批次数、最近入库时间等)、storage(按 storage_id 逐条导出库存明细,含库位编码/名称、商品信息、批次号、库存类型、数量、生产日期、过期日期、入库单号等)。立即返回任务受理信息(task_id/status/progress),不直接返回文件。通过 storage.inventory.exportTaskProgress 查询进度并获取下载地址。仅导出有量库存(与 storage.inventory.list 一致):明细模式过滤 quantity=0 的行,合并模式过滤总数量为 0 的商品。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "where", "type": "object", "required": false, "source": "body", "description": "统一 where 条件对象,与 storage.inventory.list 的 where 语义完全一致(暂不支持 stock_query 虚拟筛选)。支持字段:stock_id(商品ID)、space_id(库位ID)、store_id(货主ID)、inventory_type(ZP/CC/JS/XS/ZT/DJ/FP)、batch_no(批次号)、inbound_order_no(入库单号)、available_quantity(可用数量,支持 gt/lt)、inbound_time(入库时间,支持 between)、created_at(创建时间,支持 between)" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数,与 storage.inventory.list 的 sort 语义完全一致。sortField 支持:id/stock_id/space_id/created_at/updated_at/inbound_time/quantity,sortOrder 支持 ASC/DESC。默认 id DESC" }, { "name": "group_by_batch", "type": "boolean", "required": false, "source": "body", "description": "是否按批次导出,默认 false。与 storage.inventory.list 的 group_by_batch 语义一致。false=合并模式(按 stock_id+库位聚合导出库存汇总,含总库存/锁定/可用/批次数/最近入库时间),true=明细模式(按 storage_id 逐条导出库存明细,含批次号/库存类型/生产日期/过期日期/入库单号等)" } ], "response": [ { "name": "task_id", "type": "string", "description": "导出任务ID,用于后续查询进度" }, { "name": "status", "type": "string", "description": "任务状态:submitted" }, { "name": "progress", "type": "number", "description": "进度:0" }, { "name": "message", "type": "string", "description": "受理消息" }, { "name": "update_time", "type": "number", "description": "更新时间戳" } ], "errors": [ { "code": 400, "message": "where 条件格式不正确" }, { "code": 500, "message": "导出任务提交失败" } ] }, { "method": "storage.inventory.exportTaskProgress", "description": "按 task_id 查询库存导出任务进度,未找到时 status=not_found。任务完成(status=success)时返回 download_url 供客户端下载导出文件。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id / taskId", "type": "string", "required": true, "source": "body|query", "description": "任务ID,兼容 taskId 驼峰写法" } ], "response": [ { "name": "task_id", "type": "string", "description": "任务ID" }, { "name": "status", "type": "string", "description": "任务状态:submitted/running/success/failed/not_found" }, { "name": "progress", "type": "number", "description": "进度百分比(0-100)" }, { "name": "message", "type": "string", "description": "额外提示信息" }, { "name": "result", "type": "object", "description": "任务成功时返回的结果对象(含 fileKey/url 等)" }, { "name": "error", "type": "string", "description": "失败时的错误信息" }, { "name": "download_url", "type": "string", "description": "任务完成后可直接下载的文件地址" }, { "name": "update_time", "type": "number", "description": "最近一次状态更新时间戳" } ], "errors": [ { "code": 400, "message": "task_id 参数不能为空" }, { "code": 500, "message": "查询失败或内部错误" } ] }, { "method": "storage.expiry.list", "description": "库存有效期列表查询(效期预警),按 wms_storage 查询并计算剩余天数与过期状态,支持 where 条件与分页。注意:无需传 warehouse_id/store_id,服务端会从当前登录用户取仓库上下文。", "name": "库存有效期列表(或:库存效期预警列表)", "isNeedAuth": false, "isNeedLogin": true, "isNeedRight": false, "params": [ { "name": "where", "type": "object", "required": false, "source": "body", "description": "统一 where 条件对象;支持字段:item_code、goods_code、item_name、sku_property、stock_unit、is_shelf_life_mgmt、remaining_threshold_days。示例:where.item_code={operator:like,value:ABC}; where.remaining_threshold_days={operator:lte,value:7}。注意:无需传入 store_id 或 warehouse_id,服务端会从当前登录用户获取仓库上下文。" }, { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数 { page, pageSize },默认 page=1, pageSize=20" } ], "response": [ { "name": "data.list", "type": "array", "required": true, "description": "匹配到的库存效期项数组" }, { "name": "data.list[]", "type": "object", "description": "列表项,包含至少以下字段", "children": [ { "name": "id", "type": "number", "description": "库存记录ID(wms_storage.id)" }, { "name": "warehouse_id", "type": "number", "description": "仓库ID" }, { "name": "store_id", "type": "number", "description": "货主ID" }, { "name": "space_id", "type": "number", "description": "库位ID" }, { "name": "stock_id", "type": "number", "description": "商品库存ID(stock_warehouse.id)" }, { "name": "batch_no", "type": "string", "description": "批次号" }, { "name": "quantity", "type": "number", "description": "库存数量" }, { "name": "expiry_date", "type": "string", "description": "过期/到期日期(ISO)" }, { "name": "remaining_days", "type": "number", "description": "距到期剩余天数(正数表示未过期,0 当日到期,负数表示已过期)" }, { "name": "threshold_days", "type": "number", "description": "阈值天数,优先使用传入 remaining_threshold_days,否则使用商品配置" }, { "name": "is_expired", "type": "boolean", "description": "是否已过期(true=已过期)" }, { "name": "stock", "type": "object", "description": "关联商品信息(id、item_code、item_name、sku_property、stock_unit 等)" }, { "name": "space", "type": "object", "description": "关联库位信息(id、space_code、custom_name 等)" }, { "name": "created_at", "type": "string", "description": "记录创建时间" }, { "name": "updated_at", "type": "string", "description": "记录更新时间" }, { "name": "inbound_time", "type": "string", "description": "入库时间" }, { "name": "production_date", "type": "string", "description": "生产日期" } ] }, { "name": "data.pagination", "type": "object", "required": true, "description": "分页信息,含 page、pageSize、total、totalPages" } ], "errors": [ { "code": 400, "message": "where 条件格式不正确" } ] }, { "method": "storage.transaction.list", "description": "库位维度出入库流水逐条明细查询(wms_storage_transaction)。支持 where 条件、keyword 快捷搜索、分页、排序;仓库ID由服务端按当前登录上下文自动注入,不支持前端传参。历史版本默认按商品+单据类型聚合数量(合并模式),现已废弃聚合,恒返回逐条明细;group_by_batch 参数保留但不再影响返回结果。", "name": "出入库流水记录列表", "isNeedAuth": false, "isNeedLogin": true, "isNeedRight": false, "headers": [], "params": [ { "name": "where", "type": "object", "required": false, "source": "body", "description": "统一 where 条件对象,支持以下字段(可传标量或 { operator, value } 对象):", "children": [ { "name": "transaction_type", "type": "string", "required": false, "description": "流水类型枚举:INBOUND=入库 / OUTBOUND=出库 / TRANSFER_OUT=移库出 / TRANSFER_IN=移库入 / LOCK=锁定 / UNLOCK=取消锁定" }, { "name": "stock_id", "type": "number", "required": false, "description": "商品库存ID(单数,与 stock_ids 等效)" }, { "name": "stock_ids", "type": "array", "required": false, "description": "商品库存ID数组" }, { "name": "space_id", "type": "number", "required": false, "description": "库位ID" }, { "name": "store_id", "type": "number", "required": false, "description": "货主ID(单数,与 store_ids 等效)" }, { "name": "store_ids", "type": "array", "required": false, "description": "货主ID数组" }, { "name": "order_type", "type": "string", "required": false, "description": "单据类型(非限定枚举,常见值:SCRK=收货入库 / MATCH=匹配入库 / CGTH=采购退货 / INTERCEPT_LOCK=拦截锁定 / INTERCEPT_UNLOCK=拦截解锁)" }, { "name": "order_no", "type": "string", "required": false, "description": "单据号(模糊匹配)" }, { "name": "batch_no", "type": "string", "required": false, "description": "批次号(精确匹配)" }, { "name": "inventory_type", "type": "string", "required": false, "description": "库存类型枚举:ZP=正品 / CC=残次 / JS=机损 / XS=箱损 / ZT=在途库存 / DJ=冻结 / FP=废品" }, { "name": "operator_name", "type": "string", "required": false, "description": "操作人姓名(模糊匹配)" }, { "name": "order_id", "type": "number", "required": false, "description": "关联单据ID(发货单ID)" }, { "name": "created_at", "type": "array", "required": false, "description": "创建时间区间(operator=between,value=[start, end],闭区间)" }, { "name": "start_time", "type": "string", "required": false, "description": "开始时间(created_at >= start_time,与 created_at 区间等效)" }, { "name": "end_time", "type": "string", "required": false, "description": "结束时间(created_at <= end_time,与 created_at 区间等效)" }, { "name": "keyword", "type": "string", "required": false, "description": "商品关键字(item_code/item_name/goods_code/barcode/SKU ID 模糊匹配,等价于顶层 keyword)" } ] }, { "name": "keyword", "type": "string", "required": false, "source": "body", "description": "快捷搜索关键字(也可放 where.keyword),支持按商品编码(item_code)、商品名称(item_name)、货物编码(goods_code)、条码(barcode)、SKU ID 模糊匹配。内部先解析为 stock_id 列表,再以 IN 条件合并到查询中" }, { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数 { page, pageSize },默认 page=1、pageSize=20,pageSize 上限 200" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数 { sortField, sortOrder },sortField 白名单:created_at、quantity、stock_id、store_id、warehouse_id、space_id;非法字段回退默认排序 created_at DESC" }, { "name": "group_by_batch", "type": "boolean", "required": false, "source": "body", "description": "已废弃:历史版本用于切换聚合/明细模式,当前恒返回逐条明细,该参数不再生效,仅保留请求兼容" } ], "response": [ { "name": "list", "type": "array", "required": false, "description": "逐条流水明细列表(按 created_at 倒序)", "children": [ { "name": "id", "type": "number", "description": "流水记录ID" }, { "name": "created_at", "type": "string", "description": "流水创建时间" }, { "name": "transaction_type", "type": "string", "description": "流水类型枚举:INBOUND=入库 / OUTBOUND=出库 / TRANSFER_OUT=移库出 / TRANSFER_IN=移库入 / LOCK=锁定 / UNLOCK=取消锁定" }, { "name": "warehouse_id", "type": "number", "description": "仓库ID" }, { "name": "store_id", "type": "number", "description": "货主ID" }, { "name": "stock_id", "type": "number", "description": "商品库存ID(关联 wms_stock_warehouse.id)" }, { "name": "storage_id", "type": "number", "description": "库位库存ID(关联 wms_storage.id)" }, { "name": "space_id", "type": "number", "description": "库位ID" }, { "name": "quantity", "type": "number", "description": "变动数量" }, { "name": "before_quantity", "type": "number", "description": "变更前库存数量" }, { "name": "after_quantity", "type": "number", "description": "变更后库存数量" }, { "name": "before_locked_quantity", "type": "number", "description": "变更前锁定数量" }, { "name": "after_locked_quantity", "type": "number", "description": "变更后锁定数量" }, { "name": "before_intercept_locked_quantity", "type": "number", "description": "变更前拦截锁定数量" }, { "name": "after_intercept_locked_quantity", "type": "number", "description": "变更后拦截锁定数量" }, { "name": "batch_no", "type": "string", "description": "批次号" }, { "name": "inventory_type", "type": "string", "description": "库存类型枚举:ZP=正品 / CC=残次 / JS=机损 / XS=箱损 / ZT=在途库存 / DJ=冻结 / FP=废品" }, { "name": "order_type", "type": "string", "description": "关联单据类型" }, { "name": "order_no", "type": "string", "description": "关联单据号" }, { "name": "order_id", "type": "number", "description": "关联单据ID" }, { "name": "source_order_codes", "type": "string", "description": "来源订单号集合" }, { "name": "operator_id", "type": "string", "description": "操作人ID" }, { "name": "operator_name", "type": "string", "description": "操作人姓名" }, { "name": "remark", "type": "string", "description": "备注" }, { "name": "stockItem", "type": "object", "description": "商品信息(LEFT JOIN wms_stock_warehouse,关联不到时为 null)", "children": [ { "name": "id", "type": "number", "description": "商品ID" }, { "name": "item_code", "type": "string", "description": "商品编码" }, { "name": "item_name", "type": "string", "description": "商品名称" }, { "name": "sku_property", "type": "string", "description": "规格" }, { "name": "stock_unit", "type": "string", "description": "单位" } ] } ] }, { "name": "pagination", "type": "object", "required": false, "description": "分页信息", "children": [ { "name": "page", "type": "number", "description": "当前页" }, { "name": "pageSize", "type": "number", "description": "每页条数" }, { "name": "total", "type": "number", "description": "总记录数" }, { "name": "totalPages", "type": "number", "description": "总页数" } ] } ], "errors": [ { "code": 400, "message": "where 条件格式不正确" }, { "code": 400, "message": "分页参数不合法" } ] }, { "method": "storage.inventory.listByStockId", "name": "按商品查询有量库存明细", "description": "按商品查询库存明细:传入 stock_id,返回该商品在当前仓库下所有数量大于 1(quantity > 1)的 wms_storage 明细行。支持两种模式:group_by_space=false(默认,不汇总)逐条返回明细,结构与 storage.inventory.list 明细模式(group_by_batch=true)一致,含批次字段(batch_no/inventory_type/quantity/locked_quantity/available_quantity/production_date/expiry_date/inbound_time/inbound_order_no/receiving_id/entry_order_id/supplier_id/supplier_batch_no 等)、stock(商品信息,含 barcodes/images 附属信息)、space(库位信息)、store_name(货主名称,来源于当前仓库签约表 store_remask)以及效期/库存预警字段;group_by_space=true(按库位汇总)先筛 quantity > 1 的明细行,再按 space_id 汇总 quantity/locked_quantity/available_quantity,返回行含库位/商品信息与 batch_count、first_inbound_time、last_inbound_time,不含批次与效期/预警字段。仓库上下文来自当前登录用户(ctx.user.store_id)。", "isNeedAuth": false, "isNeedLogin": true, "isNeedRight": false, "headers": [], "params": [ { "name": "stock_id", "type": "number", "required": true, "source": "body", "description": "商品SKU ID(wms_stock_warehouse.id,必填)" }, { "name": "group_by_space", "type": "boolean", "required": false, "source": "body", "description": "是否按库位汇总,默认 false。false=不汇总(逐条明细);true=按库位汇总(先筛 quantity > 1 明细行,再按 space_id 求和)" } ], "response": [ { "name": "code", "type": "number", "required": true, "description": "状态码,200=成功" }, { "name": "message", "type": "string", "required": true, "description": "结果说明" }, { "name": "data.list", "type": "array", "required": true, "description": "库存数组(quantity > 1,按 id 倒序)。group_by_space=false 时为明细行,每项字段:id、warehouse_id、store_id、space_id、stock_id、batch_no、inventory_type、quantity、locked_quantity、intercept_locked_quantity(拦截锁定数量,默认 0)、available_quantity、production_date、expiry_date、inbound_time、inbound_order_no、receiving_id、entry_order_id、supplier_id、supplier_batch_no、is_enabled、created_at、updated_at、delete_at;stock 对象(id/item_code/item_name/sku_property/stock_unit/is_shelf_life_mgmt/remaining_threshold_days/is_batch_mgmt_enabled/store_name/barcodes/images);space 对象(id/space_code/custom_name);顶层 store_name(货主名称);is_shelf_life_warning_triggered(效期预警是否触发);expiry_remaining_days/inventory_warning_level/inventory_warning_color/inventory_warning_range/inventory_warning_tip_text(库存预警字段,无预警时为 null)。group_by_space=true 时为按库位汇总行,每项字段:warehouse_id、store_id、space_id、stock_id、quantity/locked_quantity/available_quantity(汇总值)、batch_count(批次数)、first_inbound_time(最早入库时间)、last_inbound_time(最晚入库时间)、stock 对象、space 对象、顶层 store_name;不含批次与效期/预警字段" } ], "errors": [ { "code": 400, "message": "stock_id 必填且必须为正整数" }, { "code": 400, "message": "无法获取当前仓库信息" }, { "code": 500, "message": "系统异常" } ] }, { "method": "storage.inventory.listBySpaceId", "name": "按库位查询有量库存商品列表", "description": "按库位查询库存商品列表:传入 space_id,先判断该库位是否为当前仓库的库位(不存在返回 404,存在但不属于当前仓库返回 400),是则返回该库位下有量库存(quantity > 0)的商品列表。列表按商品(stock_id)汇总为一条:每项含 warehouse_id/store_id/space_id/space_code/space_name/stock_id/quantity/locked_quantity/intercept_locked_quantity/available_quantity(汇总数量)/batch_count(批次数)/first_inbound_time(最早入库时间)/last_inbound_time(最晚入库时间)。商品信息使用 stock_warehouse 通用属性返回(stock 对象,由 getStockDetails 通用链路提供:id/item_code/item_name/sku_property/quantity/locked_quantity/is_batch_mgmt/is_shelf_life_mgmt/is_images/need_recheck/store_id/packing_requirements/stock_unit/barcodes(条码数组)/image_url(图片数组);未命中时为 null);顶层 store_name 为货主名称(当前仓库签约表 store_remask,未命中为 null)。该库位无有量库存时 list 为空数组。仓库上下文来自当前登录用户(ctx.user.store_id)。", "isNeedAuth": false, "isNeedLogin": true, "isNeedRight": false, "headers": [], "params": [ { "name": "space_id", "type": "number", "required": true, "source": "body", "description": "库位ID(wms_location_space.id,必填)" } ], "response": [ { "name": "code", "type": "number", "required": true, "description": "状态码,200=成功" }, { "name": "message", "type": "string", "required": true, "description": "结果说明" }, { "name": "data.space", "type": "object", "required": true, "description": "库位信息:id(库位ID)、warehouse_id(所属仓库ID)、space_code(库位编码)、custom_name(自定义名称)、space_status(库位状态)" }, { "name": "data.list", "type": "array", "required": true, "description": "该库位下有量库存(quantity > 0,按 id 倒序查询后汇总)的商品数组,每项字段:warehouse_id、store_id、space_id、stock_id、quantity(汇总数量)、locked_quantity(汇总锁定数量)、intercept_locked_quantity(汇总拦截锁定数量)、available_quantity(汇总可用数量)、batch_count(批次数)、first_inbound_time(最早入库时间,空为 '')、last_inbound_time(最晚入库时间,空为 '')、space_code(库位编码)、space_name(custom_name 优先,否则 space_code)、store_name(货主名称)、stock(stock_warehouse 通用属性对象:id/item_code/item_name/sku_property/quantity/locked_quantity/is_batch_mgmt/is_shelf_life_mgmt/is_images/need_recheck/store_id/packing_requirements/stock_unit/barcodes/image_url;商品详情未命中时为 null)。该库位无有量库存时为空数组 []" } ], "errors": [ { "code": 400, "message": "space_id 必填且必须为正整数" }, { "code": 400, "message": "无法获取当前仓库信息" }, { "code": 400, "message": "库位 {space_id} 不属于当前仓库" }, { "code": 404, "message": "库位不存在: space_id={space_id}" }, { "code": 500, "message": "系统异常" } ] }, { "method": "storage.inventory.updateExpiry", "name": "维护库存效期(生产日期/到期日期)", "description": "按库存记录维度维护生产日期与到期日期:传入 storage_id 与 production_date / expiry_date,更新 wms_storage 对应批次的两个日期字段。两个日期至少传一个:未传的字段保持库内原值,传 null 或空串表示清空该字段。日期支持 YYYY-MM-DD / YYYY/MM/DD / YYYY-MM-DD HH:mm:ss / ISO 字符串,内部统一按 YYYY-MM-DD 落库;合并后的生产日期不得晚于到期日期(未传字段取库内现值参与比较)。仅允许维护当前登录仓库(ctx.user.store_id)下的库存记录,跨仓库的 storage_id 按「不存在」处理(404);更新前后完全一致时返回 changed=false,不写库、不记操作日志。成功维护时写入业务操作日志(business_type=storage,operation_code=STORAGE_UPDATE_EXPIRY,message 记录两个日期的变更前后值)。", "isNeedAuth": true, "isNeedLogin": true, "headers": [], "params": [ { "name": "storage_id", "type": "number", "required": true, "source": "body", "description": "库存记录ID(wms_storage.id,必填,正整数)" }, { "name": "production_date", "type": "string", "required": false, "source": "body", "description": "生产日期,支持 YYYY-MM-DD / YYYY/MM/DD / YYYY-MM-DD HH:mm:ss / ISO 字符串;传 null 或空串表示清空。与 expiry_date 至少传一个,未传则保持库内原值" }, { "name": "expiry_date", "type": "string", "required": false, "source": "body", "description": "到期日期,格式要求同 production_date;传 null 或空串表示清空。与 production_date 至少传一个,未传则保持库内原值" } ], "response": [ { "name": "code", "type": "number", "required": true, "description": "状态码:200=成功,400=参数或业务校验失败,404=库存记录不存在或无权访问,409=库存记录被锁定" }, { "name": "message", "type": "string", "required": true, "description": "结果说明,成功为「更新成功」;两个日期均无变化为「生产日期与到期日期均无变化,未做修改」" }, { "name": "data", "type": "object", "required": true, "description": "维护结果;失败时为 null" }, { "name": "data.storage_id", "type": "number", "required": true, "description": "库存记录ID(wms_storage.id)" }, { "name": "data.warehouse_id", "type": "number", "required": true, "description": "仓库ID(来自当前登录用户 ctx.user.store_id)" }, { "name": "data.store_id", "type": "number", "required": true, "description": "货主ID" }, { "name": "data.space_id", "type": "number", "required": true, "description": "库位ID" }, { "name": "data.stock_id", "type": "number", "required": true, "description": "商品SKU ID(wms_stock_warehouse.id)" }, { "name": "data.batch_no", "type": "string", "required": true, "description": "批次号" }, { "name": "data.production_date", "type": "string", "required": true, "description": "维护后的生产日期(YYYY-MM-DD),未维护时为 null" }, { "name": "data.expiry_date", "type": "string", "required": true, "description": "维护后的到期日期(YYYY-MM-DD),未维护时为 null" }, { "name": "data.before_production_date", "type": "string", "required": true, "description": "维护前的生产日期(YYYY-MM-DD),原为空时为 null" }, { "name": "data.before_expiry_date", "type": "string", "required": true, "description": "维护前的到期日期(YYYY-MM-DD),原为空时为 null" }, { "name": "data.changed", "type": "boolean", "required": true, "description": "是否发生了实际变更(false 表示传入值与库内现值一致,未写库)" } ], "errors": [ { "code": 400, "message": "storage_id 必填且必须为正整数" }, { "code": 400, "message": "production_date 格式非法,须为 YYYY-MM-DD" }, { "code": 400, "message": "expiry_date 格式非法,须为 YYYY-MM-DD" }, { "code": 400, "message": "production_date 与 expiry_date 至少传入一个" }, { "code": 400, "message": "无法获取当前仓库信息" }, { "code": 400, "message": "生产日期(2026-08-01)不能晚于到期日期(2026-07-01)" }, { "code": 404, "message": "库存记录不存在或无权访问: storage_id=123" }, { "code": 409, "message": "库存记录被锁定,请稍后重试" } ], "notes": [ "仓库上下文来自当前登录用户(ctx.user.store_id),不接受请求体传入的 warehouse_id,避免跨仓库越权维护", "仅维护 wms_storage 中 is_enabled=1 且 delete_at IS NULL 的库存记录;维护前对目标行加行锁(SELECT ... FOR UPDATE),避免与移库/出入库并发冲突", "不对商品的保质期管理开关(stock_warehouse.is_shelf_life_mgmt)做限制:未启用效期管理的商品同样允许维护,维护后进入库存有效期列表的前提仍是商品启用效期管理且 remaining_threshold_days > 0", "接口需要 API 权限校验:wms_permission 中需存在 path=storage.inventory.updateExpiry 的记录并授予相应角色(permissions='*' 的角色自动放行),否则返回 403「无权访问该接口」" ] } ] }, { "groupName": "库存报表模块", "module": "stock.report", "list": [ { "method": "stock.report.search", "description": "库存报表查询(主入口):按时间闭区间统计商品出入库并支持按库位或按商品聚合", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "where", "type": "object", "required": false, "source": "body", "description": "查询条件对象。支持字段:start_time(闭区间下限)、end_time(闭区间上限)、by_space(是否按库位返回,默认 false)、store_ids(货主ID数组)、stock_id(商品库存ID,单数)、stock_ids(商品库存ID数组)、keyword(商品关键字模糊匹配,支持 SKU ID/item_code/item_name/goods_code/barcode)。仅返回在时间区间内存在流水的数据(无流水键不返回)。" }, { "name": "where.start_time", "type": "string", "required": false, "source": "body", "description": "开始时间,支持字符串/Date;用于闭区间过滤:created_at >= start_time" }, { "name": "where.end_time", "type": "string", "required": false, "source": "body", "description": "结束时间,支持字符串/Date;用于闭区间过滤:created_at <= end_time" }, { "name": "where.by_space", "type": "boolean", "required": false, "source": "body", "description": "是否按库位返回,默认 false。false=按商品+货主聚合(多库位汇总),true=按商品+库位+货主返回;当 where.by_space=true 时,额外返回 space_id、space_name(custom_name 优先,否则使用 space_code)。" }, { "name": "where.store_ids", "type": "array", "required": false, "source": "body", "description": "货主ID数组,用于过滤特定货主(空或未传表示不过滤)", "list": [] }, { "name": "where.stock_id", "type": "number", "required": false, "source": "body", "description": "商品库存ID(单数,兼容数组),精确过滤指定商品;与 stock_ids 二选一,与 keyword 互斥" }, { "name": "where.stock_ids", "type": "array", "required": false, "source": "body", "description": "商品库存ID数组,精确过滤指定商品列表;与 stock_id 二选一,与 keyword 互斥", "list": [] }, { "name": "where.keyword", "type": "string", "required": false, "source": "body", "description": "商品关键字,支持按 SKU ID(纯数字精确匹配)、商品编码(item_code)、商品名称(item_name)、货物编码(goods_code)、条码(barcode)模糊匹配;与 stock_id / stock_ids 互斥" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数对象(请求体 data.sort)。支持 data.sort.sortField / data.sort.sort_field 与 data.sort.sortOrder / data.sort.sort_order;sortField 白名单:stock_id、item_code、item_name、begin_total、inbound_total、outbound_total、end_total(item_code/item_name 按字典序,其余按数值);sortOrder 支持 ASC / DESC(大小写不敏感);非法字段或顺序将回退默认排序。" }, { "name": "sort.sortField", "type": "string", "required": false, "source": "body.sort", "description": "排序字段(兼容 data.sort.sortField)。白名单:stock_id、item_code、item_name、begin_total、inbound_total、outbound_total、end_total;非法值回退默认排序。" }, { "name": "sort.sort_field", "type": "string", "required": false, "source": "body.sort", "description": "排序字段下划线别名(兼容 data.sort.sort_field),规则同 sort.sortField。" }, { "name": "sort.sortOrder", "type": "string", "required": false, "source": "body.sort", "description": "排序方向(兼容 data.sort.sortOrder),支持 ASC / DESC(大小写不敏感);非法值回退默认排序。" }, { "name": "sort.sort_order", "type": "string", "required": false, "source": "body.sort", "description": "排序方向下划线别名(兼容 data.sort.sort_order),规则同 sort.sortOrder。" }, { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数(请求体 data.pagination),格式 { page, pageSize }。默认生效:未传或非法时按 { page: 1, pageSize: 20 } 返回第一页;先按排序规则排序再切片,data.list 仅返回当前页数据,响应始终返回 data.pagination 分页信息(page/pageSize/total/totalPages/hasPrevious/hasNext)。兼容顶层 data.page / data.pageSize / data.page_size(与其他 list 接口一致,顶层值优先)。" }, { "name": "pagination.page", "type": "number", "required": false, "source": "body.pagination", "description": "页码,从 1 开始的正整数" }, { "name": "pagination.pageSize", "type": "number", "required": false, "source": "body.pagination", "description": "每页条数,正整数(兼容 pagination.page_size)" }, { "name": "page", "type": "number", "required": false, "source": "body", "description": "页码(顶层兼容写法,与其他 list 接口一致,从 1 开始;与 pagination.page 等价,顶层值优先)" }, { "name": "pageSize", "type": "number", "required": false, "source": "body", "description": "每页条数(顶层兼容写法,与其他 list 接口一致;与 pagination.pageSize 等价,兼容 page_size,顶层值优先)" } ], "response": [ { "name": "data.list", "type": "array", "required": true, "description": "匹配到的报表行列表\n已按 sort 规则排序;按分页返回当前页数据(默认第 1 页、每页 20 条)。" }, { "name": "data.list[]", "type": "object", "required": true, "description": "单条报表记录字段", "children": [ { "name": "start_time", "type": "string", "description": "请求时传入的 start_time(或 null)" }, { "name": "end_time", "type": "string", "description": "请求时传入的 end_time(或 null)" }, { "name": "store_name", "type": "string", "description": "货主名称" }, { "name": "item_name", "type": "string", "description": "商品名称" }, { "name": "barcode", "type": "string", "description": "商品条码(逗号分隔)" }, { "name": "item_code", "type": "string", "description": "商品编码" }, { "name": "begin_total", "type": "number", "description": "期初库存量:取 start_time 前最后一条记录的 after_quantity(若 start_time 未传,默认为 0)" }, { "name": "end_total", "type": "number", "description": "期末库存量:取 end_time 时点(<= end_time)最后一条记录的 after_quantity(若 end_time 未传则取最近一条)" }, { "name": "inbound_total", "type": "number", "description": "在查询区间内累计入库数(INBOUND)" }, { "name": "outbound_total", "type": "number", "description": "在查询区间内累计出库数(OUTBOUND)" }, { "name": "stock_id", "type": "number", "description": "商品库存记录ID(stock_warehouse.id)" }, { "name": "store_id", "type": "number", "description": "货主ID" }, { "name": "begin_total", "type": "number", "description": "期初库存(数值)" }, { "name": "end_total", "type": "number", "description": "期末库存(数值)" }, { "name": "inbound_total", "type": "number", "description": "入库合计" }, { "name": "outbound_total", "type": "number", "description": "出库合计" }, { "name": "by_space_mode", "type": "string", "description": "说明当前返回模式:'by_space' 或 'by_product'" }, { "name": "space_id", "type": "number", "description": "库位ID(仅当 where.by_space=true 返回)" }, { "name": "space_name", "type": "string", "description": "库位名称(custom_name 优先,否则使用 space_code,where.by_space=true 时返回)" } ] }, { "name": "data.pagination", "type": "object", "required": true, "description": "分页信息(始终返回;未传分页参数时默认 page=1、pageSize=20)", "children": [ { "name": "page", "type": "number", "description": "当前页码(从 1 开始)" }, { "name": "pageSize", "type": "number", "description": "每页条数" }, { "name": "total", "type": "number", "description": "符合条件的总条数" }, { "name": "totalPages", "type": "number", "description": "总页数" }, { "name": "hasPrevious", "type": "boolean", "description": "是否有上一页" }, { "name": "hasNext", "type": "boolean", "description": "是否有下一页" } ] } ], "errors": [ { "code": 400, "message": "start_time 不合法" }, { "code": 400, "message": "end_time 不合法" }, { "code": 400, "message": "start_time 不能大于 end_time" } ] }, { "method": "stock.report.searchStore", "description": "货主侧库存报表查询:以货主维度统计商品出入库(入库和订单出库),不涉及库位维度。与 search 共享核心逻辑,但主维度为 store_id。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "where", "type": "object", "required": false, "source": "body", "description": "查询条件对象。支持字段:start_time(闭区间下限)、end_time(闭区间上限)、warehouse_ids(仓库ID数组,可选过滤)、stock_id(商品库存ID,单数)、stock_ids(商品库存ID数组)、keyword(商品关键字模糊匹配,支持 SKU ID/item_code/item_name/goods_code/barcode)。仅返回在时间区间内存在流水的数据。" }, { "name": "where.start_time", "type": "string", "required": false, "source": "body", "description": "开始时间,支持字符串/Date;用于闭区间过滤:created_at >= start_time" }, { "name": "where.end_time", "type": "string", "required": false, "source": "body", "description": "结束时间,支持字符串/Date;用于闭区间过滤:created_at <= end_time" }, { "name": "where.warehouse_ids", "type": "array", "required": false, "source": "body", "description": "仓库ID数组,用于过滤特定仓库(空或未传表示不过滤)", "list": [] }, { "name": "where.stock_id", "type": "number", "required": false, "source": "body", "description": "商品库存ID(单数,兼容数组),精确过滤指定商品;与 stock_ids 二选一,与 keyword 互斥" }, { "name": "where.stock_ids", "type": "array", "required": false, "source": "body", "description": "商品库存ID数组,精确过滤指定商品列表;与 stock_id 二选一,与 keyword 互斥", "list": [] }, { "name": "where.keyword", "type": "string", "required": false, "source": "body", "description": "商品关键字,支持按 SKU ID(纯数字精确匹配)、商品编码(item_code)、商品名称(item_name)、货物编码(goods_code)、条码(barcode)模糊匹配;与 stock_id / stock_ids 互斥" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数对象。支持 data.sort.sortField / data.sort.sort_field 与 data.sort.sortOrder / data.sort.sort_order;sortField 白名单:stock_id、item_code、item_name、begin_total、inbound_total、outbound_total、end_total(item_code/item_name 按字典序,其余按数值);sortOrder 支持 ASC / DESC。" }, { "name": "sort.sortField", "type": "string", "required": false, "source": "body.sort", "description": "排序字段(兼容 data.sort.sortField)。白名单:stock_id、item_code、item_name、begin_total、inbound_total、outbound_total、end_total。" }, { "name": "sort.sort_field", "type": "string", "required": false, "source": "body.sort", "description": "排序字段下划线别名(兼容 data.sort.sort_field),规则同 sort.sortField。" }, { "name": "sort.sortOrder", "type": "string", "required": false, "source": "body.sort", "description": "排序方向(兼容 data.sort.sortOrder),支持 ASC / DESC(大小写不敏感)。" }, { "name": "sort.sort_order", "type": "string", "required": false, "source": "body.sort", "description": "排序方向下划线别名(兼容 data.sort.sort_order),规则同 sort.sortOrder。" } ], "response": [ { "name": "data.list", "type": "array", "required": true, "description": "匹配到的报表行列表,已按 sort 规则排序返回。" }, { "name": "data.list[]", "type": "object", "required": true, "description": "单条报表记录字段", "children": [ { "name": "start_time", "type": "string", "description": "请求时传入的 start_time(或 null)" }, { "name": "end_time", "type": "string", "description": "请求时传入的 end_time(或 null)" }, { "name": "stock_id", "type": "integer", "description": "库存商品ID(wms_stock_warehouse.id)" }, { "name": "store_id", "type": "integer", "description": "货主ID" }, { "name": "warehouse_id", "type": "integer", "description": "仓库ID" }, { "name": "store_name", "type": "string", "description": "货主名称" }, { "name": "warehouse_name", "type": "string", "description": "仓库名称" }, { "name": "item_name", "type": "string", "description": "商品名称" }, { "name": "item_code", "type": "string", "description": "商品编码" }, { "name": "barcode", "type": "string", "description": "条码" }, { "name": "begin_total", "type": "number", "description": "期初库存" }, { "name": "inbound_total", "type": "number", "description": "入库总量" }, { "name": "outbound_total", "type": "number", "description": "出库总量" }, { "name": "end_total", "type": "number", "description": "期末库存" }, { "name": "space_id", "type": "integer", "description": "库位ID(where.by_space=true 时返回)" }, { "name": "space_name", "type": "string", "description": "库位名称(where.by_space=true 时返回)" } ] } ], "errors": [ { "code": 400, "message": "start_time 不合法" }, { "code": 400, "message": "end_time 不合法" }, { "code": 400, "message": "start_time 不能大于 end_time" }, { "code": 400, "message": "用户未绑定货主" } ] }, { "method": "stock.report.export", "description": "仓库侧提交库存报表导出异步任务(与 stock.report.search 使用相同查询条件),立即返回任务受理信息,不直接返回文件。可通过 stock.report.exportTaskProgress 查询进度。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "where", "type": "object", "required": false, "source": "body", "description": "查询条件对象。支持字段:start_time(闭区间下限)、end_time(闭区间上限)、by_space(是否按库位返回,默认 false)、store_ids(货主ID数组)、stock_id(商品库存ID,单数兼容数组)、stock_ids(商品库存ID数组)、keyword(商品关键字模糊匹配)。仅返回在时间区间内存在流水的数据(无流水键不返回)。" }, { "name": "where.start_time", "type": "string", "required": false, "source": "body", "description": "开始时间,支持字符串/Date;用于闭区间过滤:created_at >= start_time" }, { "name": "where.end_time", "type": "string", "required": false, "source": "body", "description": "结束时间,支持字符串/Date;用于闭区间过滤:created_at <= end_time" }, { "name": "where.by_space", "type": "boolean", "required": false, "source": "body", "description": "是否按库位返回,默认 false。false=按商品+货主聚合(多库位汇总),true=按商品+库位+货主返回;当 where.by_space=true 时,导出汇总 sheet 会额外包含 space_id、space_name。" }, { "name": "where.store_ids", "type": "array", "required": false, "source": "body", "description": "货主ID数组,用于过滤特定货主(空或未传表示不过滤)", "list": [] }, { "name": "export_mode", "type": "string", "required": false, "source": "body", "description": "导出模式(仅仓库侧接口生效,兼容驼峰 exportMode):传 'item' 时变更记录 sheet 包含 LOCK(锁定)类型记录;不传或传其他值则排除 LOCK。汇总 sheet 不受影响(只统计 INBOUND/OUTBOUND)。货主侧接口 stock.report.exportStore 不支持该参数,变更记录固定只含出入库流水(锁定/解锁不导出)。" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数对象(请求体 data.sort)。支持 data.sort.sortField / data.sort.sort_field 与 data.sort.sortOrder / data.sort.sort_order;sortField 白名单:stock_id、item_code、item_name、begin_total、inbound_total、outbound_total、end_total(item_code/item_name 按字典序,其余按数值);sortOrder 支持 ASC / DESC(大小写不敏感);非法字段或顺序将回退默认排序。" }, { "name": "sort.sortField", "type": "string", "required": false, "source": "body.sort", "description": "排序字段(兼容 data.sort.sortField)。白名单:stock_id、item_code、item_name、begin_total、inbound_total、outbound_total、end_total;非法值回退默认排序。" }, { "name": "sort.sort_field", "type": "string", "required": false, "source": "body.sort", "description": "排序字段下划线别名(兼容 data.sort.sort_field),规则同 sort.sortField。" }, { "name": "sort.sortOrder", "type": "string", "required": false, "source": "body.sort", "description": "排序方向(兼容 data.sort.sortOrder),支持 ASC / DESC(大小写不敏感);非法值回退默认排序。" }, { "name": "sort.sort_order", "type": "string", "required": false, "source": "body.sort", "description": "排序方向下划线别名(兼容 data.sort.sort_order),规则同 sort.sortOrder。" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "导出任务ID,用于后续查询进度。" }, { "name": "status", "type": "string", "required": true, "description": "任务状态,提交受理后初始为 submitted。" }, { "name": "progress", "type": "number", "required": true, "description": "任务进度百分比(0-100)。" }, { "name": "message", "type": "string", "required": true, "description": "任务受理提示信息。" }, { "name": "error", "type": "string", "required": true, "description": "错误信息;受理成功时通常为空字符串。" }, { "name": "result", "type": "object|null", "required": true, "description": "任务结果对象;受理阶段为 null。" }, { "name": "update_time", "type": "number", "required": true, "description": "任务状态更新时间(时间戳)。" } ], "errors": [ { "code": 400, "message": "start_time 不合法" }, { "code": 400, "message": "end_time 不合法" }, { "code": 400, "message": "start_time 不能大于 end_time" } ] }, { "method": "stock.report.exportStore", "description": "货主侧提交库存报表导出异步任务(与 stock.report.searchStore 使用相同查询条件),立即返回任务受理信息,不直接返回文件。可通过 stock.report.exportTaskProgress 查询进度。变更记录 sheet 只包含出入库流水(INBOUND/OUTBOUND),锁定/解锁(LOCK/UNLOCK)记录一律不导出;export_mode / exportMode 参数不支持也不生效(仅仓库侧 stock.report.export 支持)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "where", "type": "object", "required": false, "source": "body", "description": "查询条件对象。支持字段:start_time、end_time、warehouse_ids、stock_id(商品库存ID,单数兼容数组)、stock_ids(商品库存ID数组)、keyword(商品关键字模糊匹配)。" }, { "name": "where.start_time", "type": "string", "required": false, "source": "body", "description": "开始时间" }, { "name": "where.end_time", "type": "string", "required": false, "source": "body", "description": "结束时间" }, { "name": "where.warehouse_ids", "type": "array", "required": false, "source": "body", "description": "仓库ID数组,用于过滤特定仓库", "list": [] }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数" }, { "name": "sort.sortField", "type": "string", "required": false, "source": "body.sort", "description": "排序字段" }, { "name": "sort.sort_field", "type": "string", "required": false, "source": "body.sort", "description": "排序字段下划线别名" }, { "name": "sort.sortOrder", "type": "string", "required": false, "source": "body.sort", "description": "排序方向" }, { "name": "sort.sort_order", "type": "string", "required": false, "source": "body.sort", "description": "排序方向下划线别名" } ], "response": [ { "name": "data.task_id", "type": "string", "required": true, "description": "导出异步任务ID,用于后续查询进度" }, { "name": "data.status", "type": "string", "required": true, "description": "任务受理状态:submitted" }, { "name": "data.progress", "type": "number", "required": true, "description": "任务进度:0" }, { "name": "data.message", "type": "string", "required": true, "description": "任务受理消息" }, { "name": "data.update_time", "type": "number", "required": true, "description": "任务更新时间戳(ms)" } ], "errors": [ { "code": 400, "message": "start_time 不合法" }, { "code": 400, "message": "end_time 不合法" }, { "code": 400, "message": "start_time 不能大于 end_time" } ] }, { "method": "stock.report.exportTaskProgress", "description": "根据 task_id 查询库存报表导出任务进度与结果;status 可能值:submitted/running/success/failed/not_found。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id", "type": "string", "required": false, "source": "body", "description": "导出任务ID(下划线写法)。" }, { "name": "taskId", "type": "string", "required": false, "source": "body", "description": "导出任务ID(驼峰写法,兼容别名)。" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "导出任务ID。" }, { "name": "status", "type": "string", "required": true, "description": "任务状态:submitted/running/success/failed/not_found。" }, { "name": "progress", "type": "number", "required": true, "description": "任务进度百分比(0-100)。" }, { "name": "message", "type": "string", "required": true, "description": "任务状态说明。" }, { "name": "error", "type": "string", "required": true, "description": "失败时的错误信息;成功时通常为空字符串。" }, { "name": "download_url", "type": "string", "required": true, "description": "任务成功后返回的下载链接;未完成或失败时为空字符串。" }, { "name": "update_time", "type": "number", "required": true, "description": "任务状态更新时间(时间戳)。" }, { "name": "result", "type": "object|null", "required": true, "description": "任务结果对象(包含导出文件信息);未完成或失败时可能为 null。" } ], "errors": [] } ] }, { "groupName": "库存管理模块", "module": "storage.management", "list": [ { "method": "storage.management.replenishmentDemand", "description": "分拣缺货补货需求计算(仓库级别)。自动从用户上下文获取仓库,查询所有未完成储位分配的订单,计算每个SKU在分拣区与存货区的库存量、订单需求量、分拣区缺口、建议补货量及可补货库位。支持分页与排序。", "isNeedAuth": false, "isNeedLogin": true, "isNeedRight": false, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page / pageSize,默认 page=1 pageSize=20" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数,支持 sortField / sortOrder。sortField 可选值:stock_id / pick_zone_quantity / storage_zone_quantity / total_demand / shortage / replenishment_needed,默认 shortage;sortOrder 可选 ASC / DESC,默认 DESC" }, { "name": "store_id", "type": "number|array", "required": false, "source": "body", "description": "货主筛选:支持单值或数组(正整数),也可通过 where.store_id 传入;不传时返回全部货主;非法值(非正整数)报错" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "补货需求明细列表", "children": [ { "name": "stock_id", "type": "number", "required": true, "description": "SKU ID" }, { "name": "stock_code", "type": "string", "required": true, "description": "SKU 编码" }, { "name": "stock_name", "type": "string", "required": true, "description": "SKU 名称" }, { "name": "store_id", "type": "number", "required": true, "description": "货主ID" }, { "name": "store_name", "type": "string", "required": true, "description": "货主名称(货主签约表备注名优先,商家表公司名称兜底)" }, { "name": "barcodes", "type": "array", "required": true, "description": "SKU 条码列表", "children": [ { "name": "id", "type": "number", "required": true, "description": "条码记录ID" }, { "name": "barcode", "type": "string", "required": true, "description": "条码内容" } ] }, { "name": "pick_zone_quantity", "type": "number", "required": true, "description": "分拣区可用库存(allow_allocation=1且is_active=1的库位上的可用库存)" }, { "name": "storage_zone_quantity", "type": "number", "required": true, "description": "存货区可用库存(其余库位上的可用库存)" }, { "name": "total_demand", "type": "number", "required": true, "description": "订单总需求量(汇总自订单明细 plan_qty)" }, { "name": "shortage", "type": "number", "required": true, "description": "分拣区缺口 = max(0, total_demand - pick_zone_quantity)" }, { "name": "replenishment_needed", "type": "number", "required": true, "description": "建议补货量 = min(shortage, storage_zone_quantity)" }, { "name": "replenishment_status", "type": "string", "required": true, "description": "补货状态枚举:replenishable=存货区足够覆盖缺口,移库可解决;true_shortage=存货区不足以覆盖缺口或两区均无库存,需采购" }, { "name": "replenishment_locations", "type": "array", "required": true, "description": "存货区可补货库位列表(最多5条,按可用库存降序)", "children": [ { "name": "space_code", "type": "string", "required": true, "description": "库位编码" }, { "name": "space_name", "type": "string", "required": true, "description": "库位展示名称(优先自定义名称 custom_name,无自定义名称时回退为库位编码 space_code)" }, { "name": "available_quantity", "type": "number", "required": true, "description": "该库位可用库存数量" } ] } ] }, { "name": "summary", "type": "object", "required": true, "description": "汇总信息", "children": [ { "name": "total_skus", "type": "number", "required": true, "description": "涉及的SKU总数" }, { "name": "total_shortage_skus", "type": "number", "required": true, "description": "存在缺口的SKU数" }, { "name": "total_replenishment_needed", "type": "number", "required": true, "description": "总建议补货量" }, { "name": "total_true_shortage_skus", "type": "number", "required": true, "description": "真正缺货的SKU数(分拣区与存货区均无库存)" } ] }, { "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": [ { "code": 500, "message": "缺少仓库上下文" }, { "code": 200, "message": "无待处理订单时返回空列表(list: [], summary: { total_skus: 0, total_shortage_skus: 0, total_replenishment_needed: 0, total_true_shortage_skus: 0 })" } ] } ] }, { "groupName": "主体模块", "module": "store", "list": [ { "method": "store.createStore", "description": "store.createStore 接口,subject_config 未传时默认写入 max_notice_webhook_count=5、default_express_code=STO、default_platform_code=TB、group_wave_prefix=B、min_group_order_fetch_quantity=13、auto_grouping_enabled=false(是否自动加团,默认 false(关闭))、enable_external_express_code=false(是否启用外部快递编码,默认 false(关闭))", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "subject_config", "type": "object", "required": false, "source": "body", "description": "货主主体配置,不传时自动写入默认值" }, { "name": "subject_config.max_notice_webhook_count", "type": "number", "required": false, "source": "body.subject_config", "description": "当前主体最多允许绑定 / 触达的消息推送接口数量,默认 5" }, { "name": "subject_config.default_express_code", "type": "string", "required": false, "source": "body.subject_config", "description": "默认快递编码,缺省为 STO" }, { "name": "subject_config.default_platform_code", "type": "string", "required": false, "source": "body.subject_config", "description": "默认平台编码,缺省为 TB" }, { "name": "subject_config.group_wave_prefix", "type": "string", "required": false, "source": "body.subject_config", "description": "团购波次前缀,最多 5 个字符,默认 B" }, { "name": "subject_config.min_group_order_fetch_quantity", "type": "number", "required": false, "source": "body.subject_config", "description": "最小团购订单抓取数量,默认 13" }, { "name": "subject_config.auto_grouping_enabled", "type": "boolean", "required": false, "source": "body.subject_config", "description": "是否自动加团,默认 false(关闭)" }, { "name": "subject_config.enable_external_express_code", "type": "boolean", "required": false, "source": "body.subject_config", "description": "是否启用外部快递编码;默认 false(关闭)。开启后允许按外部系统传入的快递编码进行处理(如无匹配仍以业务校验为准)" } ], "response": [], "errors": [] }, { "method": "store.createWarehouse", "description": "store.createWarehouse 接口,subject_config 未传时默认写入 max_notice_webhook_count=5、default_express_code=STO、default_platform_code=TB、group_wave_prefix=B、min_group_order_fetch_quantity=13、auto_grouping_enabled=false(是否自动加团,默认 false(关闭))、enable_external_express_code=false(是否启用外部快递编码,默认 false(关闭))", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "subject_config", "type": "object", "required": false, "source": "body", "description": "货主主体配置,不传时自动写入默认值" }, { "name": "subject_config.max_notice_webhook_count", "type": "number", "required": false, "source": "body.subject_config", "description": "当前主体最多允许绑定 / 触达的消息推送接口数量,默认 5" }, { "name": "subject_config.default_express_code", "type": "string", "required": false, "source": "body.subject_config", "description": "默认快递编码,缺省为 STO" }, { "name": "subject_config.default_platform_code", "type": "string", "required": false, "source": "body.subject_config", "description": "默认平台编码,缺省为 TB" }, { "name": "subject_config.group_wave_prefix", "type": "string", "required": false, "source": "body.subject_config", "description": "团购波次前缀,最多 5 个字符,默认 B" }, { "name": "subject_config.min_group_order_fetch_quantity", "type": "number", "required": false, "source": "body.subject_config", "description": "最小团购订单抓取数量,默认 13" }, { "name": "subject_config.auto_grouping_enabled", "type": "boolean", "required": false, "source": "body.subject_config", "description": "是否自动加团,默认 false(关闭)" }, { "name": "subject_config.enable_external_express_code", "type": "boolean", "required": false, "source": "body.subject_config", "description": "是否启用外部快递编码;默认 false(关闭)。开启后允许按外部系统传入的快递编码进行处理(如无匹配仍以业务校验为准)" } ], "response": [], "errors": [] }, { "method": "store.joinStore", "description": "store.joinStore 接口", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "store.joinWarehouse", "description": "store.joinWarehouse 接口", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "store.getStoreRoles", "description": "store.getStoreRoles 接口", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "code", "type": "string", "required": true, "source": "body", "description": "申请码(join_token)" } ], "response": [], "errors": [] }, { "method": "store.auditApply", "description": "store.auditApply 接口", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "audit_status", "type": "string", "required": true, "source": "body", "description": "审核状态(approved/rejected)" }, { "name": "code", "type": "string", "required": true, "source": "body", "description": "申请码(join_token)" }, { "name": "store_id", "type": "number", "required": true, "source": "body", "description": "当前审批门店ID" }, { "name": "role_ids", "type": "array", "required": true, "source": "body", "description": "分配角色ID数组" }, { "name": "reject_reason", "type": "string", "required": false, "source": "body", "description": "拒绝原因(audit_status=rejected 时可传)" } ], "response": [], "errors": [] } ] }, { "groupName": "货主-仓库签约模块", "module": "storeWarehouse.store", "list": [ { "method": "storeWarehouse.store.list", "description": "查询当前主体可见的签约列表(当前主体在 store_id 方,对方在 warehouse_id 方)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "page", "type": "number", "required": false, "source": "body", "description": "页码,默认 1" }, { "name": "page_size", "type": "number", "required": false, "source": "body", "description": "分页大小,默认 20" }, { "name": "keyword", "type": "string", "required": false, "source": "body", "description": "签约备注或主体名称关键字" } ], "response": [ { "name": "data.list", "type": "array", "description": "签约关系列表" }, { "name": "data.list[].id", "type": "number", "description": "签约关系主键 ID" }, { "name": "data.list[].store_id", "type": "number", "description": "货主 ID" }, { "name": "data.list[].store_name", "type": "string", "description": "货主名称(优先取备注名,无则取 company_name)" }, { "name": "data.list[].warehouse_id", "type": "number", "description": "仓库 ID" }, { "name": "data.list[].warehouse_name", "type": "string", "description": "仓库名称(优先取备注名,无则取 company_name)" }, { "name": "data.list[].counterparty_id", "type": "number", "description": "对方主体 ID(当前为仓库则返回货主 ID,反之亦然)" }, { "name": "data.list[].counterparty_name", "type": "string", "description": "对方主体名称" }, { "name": "data.list[].counterparty_role", "type": "string", "description": "对方主体角色:warehouse 或 store" }, { "name": "data.list[].current_subject_role", "type": "string", "description": "当前主体角色:warehouse 或 store" }, { "name": "data.list[].auth_status", "type": "number", "description": "签约状态:1=申请中 2=已通过 3=已拒绝 4=已解除 5=已过期" }, { "name": "data.list[].auth_status_label", "type": "string", "description": "签约状态中文标签" }, { "name": "data.list[].apply_reason", "type": "string", "description": "申请原因" }, { "name": "data.list[].review_comment", "type": "string", "description": "审核评语" }, { "name": "data.list[].apply_time", "type": "string|null", "description": "申请时间" }, { "name": "data.list[].review_time", "type": "string|null", "description": "审核时间" }, { "name": "data.list[].auth_start", "type": "string|null", "description": "授权开始时间" }, { "name": "data.list[].auth_end", "type": "string|null", "description": "授权结束时间" }, { "name": "data.list[].actual_end", "type": "string|null", "description": "实际结束时间" }, { "name": "data.list[].print_quantity", "type": "number", "description": "面单余额数量" }, { "name": "data.list[].applied_by", "type": "number|null", "description": "申请人账号 ID" }, { "name": "data.list[].reviewed_by", "type": "number|null", "description": "审核人账号 ID" }, { "name": "data.list[].ended_by", "type": "number|null", "description": "解除人账号 ID" }, { "name": "data.list[].remask", "type": "string", "description": "备注名(当前为仓库则返回货主备注名,反之亦然)" }, { "name": "data.list[].warehouse_use_status", "type": "number", "description": "仓库侧启用状态:0=禁用 1=启用" }, { "name": "data.list[].store_use_status", "type": "number", "description": "货主侧启用状态:0=禁用 1=启用" }, { "name": "data.list[].policy_config", "type": "object|null", "description": "签约策略配置对象,无则为 null" }, { "name": "data.list[].is_auth_valid", "type": "boolean", "description": "签约是否在有效期内" }, { "name": "data.list[].remaining_days", "type": "number", "description": "剩余有效天数(未在有效期内时为 0)" }, { "name": "data.list[].has_qimen_config", "type": "boolean", "description": "该货主是否已配置奇门(true=已配置,false=未配置)" }, { "name": "data.total", "type": "number", "description": "总记录数" }, { "name": "data.page", "type": "number", "description": "当前页码" }, { "name": "data.page_size", "type": "number", "description": "每页条数" }, { "name": "data.current_subject.store_id", "type": "number", "description": "当前主体 ID" }, { "name": "data.current_subject.company_name", "type": "string", "description": "当前主体公司名称" }, { "name": "data.current_subject.role", "type": "string", "description": "当前主体角色:warehouse 或 store" } ], "errors": [] }, { "method": "storeWarehouse.store.sign", "description": "发起或确认签约(当前主体始终为 store_id 方/消费方,对方为 warehouse_id 方/提供方,支持仓库签仓库)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "counterparty_id", "type": "number", "required": true, "source": "body", "description": "对方主体 ID(兼容 warehouse_id / store_id),当前主体自动识别" }, { "name": "temp_code", "type": "string", "required": false, "source": "body", "description": "临时签约码;传入后进入确认或预览流程" } ], "response": [], "errors": [] }, { "method": "storeWarehouse.store.rename", "description": "修改当前主体视角下的签约备注名", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "签约关系ID,兼容 contract_id" } ], "response": [], "errors": [] }, { "method": "storeWarehouse.store.unbind", "description": "解除或停用签约关系", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "签约关系ID,兼容 contract_id" }, { "name": "warehouse_use_status", "type": "number", "required": false, "source": "body", "description": "仓库侧使用状态,0=停用,1=恢复" } ], "response": [], "errors": [] }, { "method": "storeWarehouse.store.adjustPrintQuantity", "description": "人工调整签约关系下的面单余额并记录变更日志", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "签约关系ID,兼容 contract_id" }, { "name": "print_quantity", "type": "number", "required": false, "source": "body", "description": "目标面单余额(覆盖值);优先使用该字段" }, { "name": "target_quantity", "type": "number", "required": false, "source": "body", "description": "目标面单余额(覆盖值);兼容别名" }, { "name": "change_quantity", "type": "number", "required": true, "source": "body", "description": "兼容旧字段;当前按目标面单余额(覆盖值)解释,差值将自动写入变更日志" }, { "name": "adjust_quantity", "type": "number", "required": false, "source": "body", "description": "兼容旧字段;当前按目标面单余额(覆盖值)解释" }, { "name": "reason", "type": "string", "required": true, "source": "body", "description": "人工调整缘由,必填" }, { "name": "business_type", "type": "string", "required": false, "source": "body", "description": "业务来源类型,预留给后续 order_express 等自动扣减场景" }, { "name": "business_id", "type": "number", "required": false, "source": "body", "description": "业务关联ID,预留给后续关联 wms_order_express.id" } ], "response": [], "errors": [] }, { "method": "storeWarehouse.store.queryPrintQuantityLogs", "description": "按 store_id 分页查询面单余额变更日志", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "store_id", "type": "number|string", "required": true, "source": "body", "description": "货主ID(必填)" }, { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页对象,包含 page 与 page_size;默认 { page: 1, page_size: 20 }", "children": [ { "name": "page", "type": "number", "required": false, "description": "页码,默认 1" }, { "name": "page_size", "type": "number", "required": false, "description": "每页条数,默认 20" } ] } ], "response": [ { "name": "data", "type": "object", "required": true, "description": "返回结果对象,包含 list 和 pagination", "children": [ { "name": "list", "type": "array", "required": true, "description": "变更日志列表,字段示例:id, contract_id, store_id, warehouse_id, change_type, business_type, business_id, change_quantity, balance_before, balance_after, reason, operator_id, created_by, created_at, updated_at" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)", "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": false, "description": "总页数" }, { "name": "hasPrevious", "type": "boolean", "required": false, "description": "是否有上一页" }, { "name": "hasNext", "type": "boolean", "required": false, "description": "是否有下一页" } ] } ] } ], "errors": [ { "code": "400", "description": "参数错误或缺少 store_id" }, { "code": "403", "description": "仅可查询当前货主的面单余额变更日志" }, { "code": "500", "description": "查询失败" } ] }, { "method": "storeWarehouse.store.getPolicyConfig", "description": "读取签约策略配置", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "签约关系ID,兼容 contract_id" } ], "response": [ { "name": "data.contract_id", "type": "number", "required": true, "description": "签约关系ID" }, { "name": "data.policy_config", "type": "object", "required": true, "description": "策略配置对象(包含默认值补齐后的字段)" }, { "name": "data.policy_config.enable_external_express_code", "type": "number", "required": true, "description": "是否启用外部快递编码(flag:0=关闭,1=开启;默认 0)" } ], "errors": [] }, { "method": "storeWarehouse.store.getPolicyConfigFields", "description": "获取签约策略可配置字段元信息列表(含自动分配时间窗口字段)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [ { "name": "data", "type": "array", "required": true, "description": "字段元信息数组,每项含 key/name/type/default/required/description/min/max/maxLength/options 等" }, { "name": "data[].cutoff_order_enabled", "type": "object", "required": false, "description": "启用截单字段元信息:key=cutoff_order_enabled,type=flag,default=1;启用后订单创建时间早于开始自动分配时间或超过截单时间(开始时间晚于截单时间时截单时间视为次日),不再自动分配快递和储位、不再自动加团" }, { "name": "data[].allocate_start_time", "type": "object", "required": false, "description": "开始自动分配时间字段元信息:key=allocate_start_time,type=string,default=08:00,min=00:00,max=23:59,maxLength=5;早于该时间的订单与超过截单时间行为一致,不自动分配快递和储位、不自动加团;开始时间晚于截单时间时截单时间视为次日(跨天窗口)" }, { "name": "data[].cutoff_order_time", "type": "object", "required": false, "description": "截单时间字段元信息:key=cutoff_order_time,type=string,default=18:00,min=00:00(下限已从 12:00 放开,支持凌晨截单/跨天窗口),max=23:59,maxLength=5" } ], "errors": [] }, { "method": "storeWarehouse.store.savePolicyConfig", "description": "保存签约策略配置", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "签约关系ID,兼容 contract_id" }, { "name": "policy_config", "type": "object", "required": true, "source": "body", "description": "策略配置对象;支持 receive_mode、auto_allocate_bin、auto_allocate_express(是否自动分配快递)、auto_allocate_storage(是否自动分配储位)、allow_mix_batch、allow_temp_storage、storage_separation、print_recharge_price(面单充值元/单,支持 2 位小数)、max_daily_inbound、remark、waybill_custom_display_type(面单自定义显示类型:1=隐藏,2=商品名称和数量,3=拣货库位和条码和数量,4=拣货库位和条码后5位和数量,5=拣货库位商品名称条码和数量)、enable_external_express_code(是否启用外部快递编码,flag:0=关闭,1=开启;默认 0)、cutoff_order_enabled(启用截单,flag:0=关闭,1=开启;默认 1)、cutoff_order_time(截单时间,HH:mm,默认 18:00,范围 00:00-23:59)、allocate_start_time(开始自动分配时间,HH:mm,默认 08:00,范围 00:00-23:59;开始时间晚于截单时间时截单时间视为次日)" }, { "name": "policy_config.enable_external_express_code", "type": "number", "required": false, "source": "body.policy_config", "description": "是否启用外部快递编码(flag:0=关闭,1=开启;默认 0)" }, { "name": "policy_config.cutoff_order_enabled", "type": "number", "required": false, "source": "body.policy_config", "description": "启用截单(flag:0=关闭,1=开启;默认 1)。启用后订单创建时间早于开始自动分配时间或超过截单时间(开始时间晚于截单时间时截单时间视为次日),不再自动分配快递和储位、不再自动加团" }, { "name": "policy_config.cutoff_order_time", "type": "string", "required": false, "source": "body.policy_config", "description": "截单时间,格式 HH:mm,默认 18:00,范围 00:00-23:59;作为最后允许自动分配的时间,开始时间晚于截单时间时截单时间视为次日(跨天窗口)" }, { "name": "policy_config.allocate_start_time", "type": "string", "required": false, "source": "body.policy_config", "description": "开始自动分配时间,格式 HH:mm,默认 08:00,范围 00:00-23:59;作为自动分配初始时间,当前时间早于该时间与超过截单时间行为一致(不自动分配快递和储位、不自动加团)。与截单时间相同(自动分配窗口为空)时报 400" } ], "response": [ { "name": "data.contract_id", "type": "number", "required": true, "description": "签约关系ID" }, { "name": "data.policy_config", "type": "object", "required": true, "description": "保存后并补齐默认值的策略配置对象" }, { "name": "data.policy_config.enable_external_express_code", "type": "number", "required": true, "description": "是否启用外部快递编码(flag:0=关闭,1=开启;默认 0)" }, { "name": "data.policy_config.allocate_start_time", "type": "string", "required": true, "description": "保存后并补齐默认值的开始自动分配时间(HH:mm,默认 08:00)" } ], "errors": [ { "code": "400", "message": "参数不合法:policy_config.allocate_start_time 与 policy_config.cutoff_order_time 相同(自动分配窗口为空)时拒绝保存;时间字段格式必须为 HH:mm" } ] }, { "method": "storeWarehouse.store.listApiConfig", "description": "查询签约关系下的接口配置列表", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "签约关系ID,兼容 contract_id" }, { "name": "interface_type_id", "type": "number", "required": false, "source": "body", "description": "接口类型ID,默认查询全部可用类型" } ], "response": [ { "name": "data.list[].callback_url", "type": "string", "description": "API回调通知URL,来自 serializeQimenConfig 序列化" } ], "errors": [] }, { "method": "storeWarehouse.store.saveApiConfig", "description": "新增或更新签约关系下的接口配置。QM_WMS 类型须填写奇门字段;OPEN_API 类型由系统自动生成 self_app_key 和 self_app_secret", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "签约关系ID,兼容 contract_id" }, { "name": "interface_type_id", "type": "number", "required": true, "source": "body", "description": "接口类型ID,必须是 wms_interface_type 已存在的类型" }, { "name": "qimen_app_key", "type": "string", "required": false, "source": "body", "description": "奇门 AppKey(QM_WMS 类型必填,OPEN_API 类型不需要)" }, { "name": "qimen_customer_id", "type": "string", "required": false, "source": "body", "description": "奇门客户ID(QM_WMS 类型必填,OPEN_API 类型不需要)" }, { "name": "qimen_warehouse_code", "type": "string", "required": false, "source": "body", "description": "奇门仓库编码(QM_WMS 类型必填,OPEN_API 类型不需要)" }, { "name": "app_name", "type": "string", "required": true, "source": "body", "description": "应用名称" }, { "name": "callback_url", "type": "string", "required": false, "source": "body", "description": "API 回调通知 URL(可选),最大 500 字符;配置后订单状态变更时将回调通知推送到此地址;兼容别名 callbackUrl" } ], "response": [], "errors": [], "notes": [ "callback_url:OpenAPI 类型的接口可配置回调地址,订单同步完成/取消等事件将推送到此 URL" ] }, { "method": "storeWarehouse.store.deleteQimenConfig", "description": "删除签约关系下的奇门接口配置", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "签约关系ID,兼容 contract_id" }, { "name": "interface_type_id", "type": "number", "required": false, "source": "body", "description": "接口类型ID" } ], "response": [], "errors": [] }, { "method": "storeWarehouse.store.openAccount", "description": "仓库代货主一键开户:同时完成账号注册、货主创建和仓库-货主签约", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(当前主体必须为仓库角色)" } ], "params": [ { "name": "username", "type": "string", "required": true, "source": "body", "description": "登录账号(用户名),全局唯一" }, { "name": "password", "type": "string", "required": false, "source": "body", "description": "初始密码,不传则自动随机生成 12 位密码" }, { "name": "real_name", "type": "string", "required": false, "source": "body", "description": "真实姓名" }, { "name": "company_name", "type": "string", "required": true, "source": "body", "description": "公司全称,全局唯一,1-200 字符" }, { "name": "business_license", "type": "string", "required": false, "source": "body", "description": "营业执照号" }, { "name": "contact_person", "type": "string", "required": true, "source": "body", "description": "联系人姓名,1-50 字符" }, { "name": "contact_phone", "type": "string", "required": false, "source": "body", "description": "联系电话" }, { "name": "legal_person", "type": "string", "required": false, "source": "body", "description": "法人代表" }, { "name": "contact_email", "type": "string", "required": false, "source": "body", "description": "联系邮箱" }, { "name": "address", "type": "string", "required": false, "source": "body", "description": "公司地址" }, { "name": "industry", "type": "string", "required": false, "source": "body", "description": "所属行业" }, { "name": "auth_start", "type": "string", "required": false, "source": "body", "description": "授权开始日期,默认当天(ISO 8601 格式)" }, { "name": "auth_end", "type": "string", "required": false, "source": "body", "description": "授权结束日期(ISO 8601 格式)" }, { "name": "print_quantity", "type": "number", "required": false, "source": "body", "description": "初始面单余额,默认 0" }, { "name": "apply_reason", "type": "string", "required": false, "source": "body", "description": "申请原因,默认\"仓库代开户\",最长 2000 字符" }, { "name": "store_remask", "type": "string", "required": false, "source": "body", "description": "货主备注名,最长 50 字符;不传或为空时默认取公司全称(截断 50 字符)填充" }, { "name": "warehouse_remask", "type": "string", "required": false, "source": "body", "description": "仓库备注名,最长 50 字符" } ], "response": [ { "name": "store_id", "type": "number", "required": true, "description": "新建的货主 ID" }, { "name": "account_id", "type": "number", "required": true, "description": "新建的账号 ID" }, { "name": "contract_id", "type": "number", "required": true, "description": "新建的签约关系 ID" }, { "name": "company_name", "type": "string", "required": true, "description": "货主公司名称" }, { "name": "username", "type": "string", "required": true, "description": "新建的登录账号名" }, { "name": "role_id", "type": "number", "required": true, "description": "分配的货主管理员角色 ID" } ], "errors": [] }, { "method": "storeWarehouse.store.confirmSign", "description": "确认签约:当前主体作为对方主体确认待签约的申请,签约状态从 1(申请中)变为 2(已通过);发起方不能确认自己的申请", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "签约关系ID,兼容 contract_id" } ], "response": [ { "name": "data.mode", "type": "string", "required": true, "description": "确认模式标识,固定为 confirm" }, { "name": "data.contract", "type": "object", "required": true, "description": "签约关系精简对象" }, { "name": "data.contract.id", "type": "number", "required": true, "description": "签约关系主键 ID" }, { "name": "data.contract.store_id", "type": "number", "required": true, "description": "货主方主体 ID" }, { "name": "data.contract.warehouse_id", "type": "number", "required": true, "description": "仓库方主体 ID" }, { "name": "data.contract.counterparty_name", "type": "string", "required": true, "description": "对方主体名称" }, { "name": "data.contract.remask", "type": "string", "required": true, "description": "当前主体视角的签约备注名" }, { "name": "data.contract.use_status", "type": "number", "required": true, "description": "当前主体启用状态:0=禁用 1=启用" }, { "name": "data.contract.auth_status", "type": "number", "required": true, "description": "签约状态:1=申请中 2=已通过 3=已拒绝 4=已解除 5=已过期" }, { "name": "data.contract.auth_status_label", "type": "string", "required": true, "description": "签约状态中文标签" }, { "name": "data.contract.auth_end", "type": "string|null", "required": true, "description": "授权结束时间" }, { "name": "data.contract.print_quantity", "type": "number", "required": true, "description": "面单余额数量" }, { "name": "data.contract.has_qimen_config", "type": "boolean", "required": true, "description": "是否已配置奇门" } ], "errors": [ { "code": 400, "message": "id 参数不能为空" }, { "code": 400, "message": "当前签约状态不允许确认,仅待签约状态可确认" }, { "code": 403, "message": "当前主体不在此签约关系中" }, { "code": 403, "message": "发起方不能确认自己的签约申请" }, { "code": 404, "message": "签约关系不存在" } ] }, { "method": "storeWarehouse.store.createUser", "description": "为货主创建用户:按用户名查询平台账号,账号不存在则自动注册并随机生成 12 位密码返回;两种情况统一完成货主工号绑定并授予货主管理员角色(wms_role.id=5)。幂等:重复调用不会重复创建账号或绑定", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(当前登录主体操作)" } ], "params": [ { "name": "username", "type": "string", "required": true, "source": "body", "description": "用户名,3-50 位字母、数字或下划线,全局唯一" }, { "name": "store_id", "type": "number", "required": true, "source": "body", "description": "货主 ID" } ], "response": [ { "name": "account_id", "type": "number", "required": true, "description": "账号 ID" }, { "name": "username", "type": "string", "required": true, "description": "用户名" }, { "name": "store_id", "type": "number", "required": true, "description": "货主 ID" }, { "name": "created", "type": "boolean", "required": true, "description": "是否本次新建账号;false 表示账号已存在仅完成授权" }, { "name": "password", "type": "string", "required": false, "description": "仅 created=true 时返回:随机生成的初始明文密码(12 位,随机大小写字母/数字)" } ], "errors": [ { "code": 400, "message": "username 参数不能为空" }, { "code": 400, "message": "用户名格式不合法,需为 3-50 位字母、数字或下划线" }, { "code": 400, "message": "store_id 参数不能为空" }, { "code": 401, "message": "未提供有效的认证令牌" }, { "code": 404, "message": "货主不存在" }, { "code": 500, "message": "货主管理员角色(id=5)未初始化" }, { "code": 500, "message": "服务内部错误" } ] }, { "method": "storeWarehouse.store.export", "description": "提交货主签约列表导出任务(异步)。入参筛选条件与 storeWarehouse.store.list 一致(keyword/counterparty_id/store_id/auth_status/use_status/warehouse_use_status/id 等,语义同 listForStore);page/page_size 忽略(全量导出)。提交后立即返回 task_id,后台异步生成 Excel 并上传,导出进度/下载请通过 storeWarehouse.store.exportTaskProgress 查询。数据来源 wms_store_warehouse 签约关系表;货主/仓库名称优先取签约备注名(store_remask/warehouse_remask),无则取 wms_store.company_name;角色/启用状态/是否有效/是否已配置奇门/是否需要我确认为中文展示列;全量导出无行数上限。任务缓存 Redis TTL 30 分钟;状态口径 submitted → running(10) → success(100),失败 failed + error。免权限免日志口径与 order.export 一致(isNeedAuth=false、isNeedLogin=true)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "keyword", "type": "string", "required": false, "source": "body", "description": "签约备注或主体名称关键字(与 list 一致,模糊匹配 store_remask/warehouse_remask/双方 company_name)" }, { "name": "counterparty_id", "type": "number", "required": false, "source": "body", "description": "对方主体ID(兼容 store_id),导出时过滤指定货主" }, { "name": "store_id", "type": "number", "required": false, "source": "body", "description": "货主ID(counterparty_id 的别名,两者传一即可)" }, { "name": "auth_status", "type": "number", "required": false, "source": "body", "description": "签约状态过滤:1=申请中 2=已通过 3=已拒绝 4=已解除 5=已过期" }, { "name": "use_status", "type": "number", "required": false, "source": "body", "description": "启用状态过滤:0=禁用 1=启用(兼容 warehouse_use_status)" }, { "name": "warehouse_use_status", "type": "number", "required": false, "source": "body", "description": "仓库侧启用状态过滤(use_status 的别名,两者传一即可)" }, { "name": "id", "type": "number", "required": false, "source": "body", "description": "签约关系ID,兼容 contract_id/relation_id;导出时仅导出该签约关系" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID(后端生成,格式 store_relation_list_export_{storeId}_{timestamp}_{random})" }, { "name": "status", "type": "string", "required": true, "description": "任务状态,枚举:submitted/running/success/failed/not_found(提交成功时为 submitted)" }, { "name": "progress", "type": "number", "required": true, "description": "当前进度百分比(0-100),提交时返回 0" }, { "name": "message", "type": "string", "required": true, "description": "任务提示信息" }, { "name": "result", "type": "object", "required": true, "description": "任务执行结果(提交时为 null;后台完成后为上传信息对象,含 filename/fileKey/url/cdnUrl/cosUrl/total_count)" }, { "name": "error", "type": "string", "required": true, "description": "失败时的错误信息(可选,非失败时为空字符串)" }, { "name": "update_time", "type": "number", "required": true, "description": "任务更新时间(Unix 毫秒时间戳)" } ], "errors": [ { "code": "400", "message": "参数格式不正确或筛选条件非法" }, { "code": "500", "message": "导出任务提交失败" } ] }, { "method": "storeWarehouse.store.exportTaskProgress", "description": "按 task_id 查询货主签约列表导出任务进度,返回 task_id、status、progress、message、result、error、download_url、update_time;上传完成后 download_url 返回下载链接(从 result.url/cdnUrl/cosUrl/fileKey 兜底取);任务缓存 Redis TTL 30 分钟,task_id 缺失或缓存未命中时 status=not_found(正常响应,非报错)。状态口径 submitted → running(10) → success(100),失败 failed + error。免权限免日志口径与 order.exportTaskProgress 一致。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id / taskId", "type": "string", "required": true, "source": "body|query", "description": "任务 ID,兼容 task_id(下划线)与 taskId(驼峰)两种写法" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID(task_id 缺失时为回显的空字符串,status=not_found)" }, { "name": "status", "type": "string", "required": true, "description": "任务状态:submitted/running/success/failed/not_found" }, { "name": "progress", "type": "number", "required": true, "description": "进度百分比(0-100)" }, { "name": "message", "type": "string", "required": true, "description": "任务提示信息" }, { "name": "result", "type": "object", "required": true, "description": "任务执行结果对象(完成后含 filename/fileKey/url/cdnUrl/cosUrl/total_count 等;未完成或 not_found 时为 null)" }, { "name": "error", "type": "string", "required": true, "description": "失败时的错误信息(可选,非失败时为空字符串)" }, { "name": "download_url", "type": "string", "required": true, "description": "任务完成后下载链接(从 result.url/cdnUrl/cosUrl/fileKey 兜底取);未完成或不存在时为空字符串" }, { "name": "update_time", "type": "number", "required": true, "description": "最近一次状态更新时间(Unix 毫秒时间戳)" } ], "errors": [ { "code": "500", "message": "查询失败或内部错误" } ] } ] }, { "groupName": "仓库-货主签约模块", "module": "storeWarehouse.warehouse", "list": [ { "method": "storeWarehouse.warehouse.list", "description": "仓库侧查询签约列表(支持查询外部合作仓库),当前仓库在 store_id 方(消费方),对方在 warehouse_id 方(提供方)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "page", "type": "number", "required": false, "source": "body", "description": "页码,默认 1" }, { "name": "page_size", "type": "number", "required": false, "source": "body", "description": "每页条数,默认 20,最大 200" }, { "name": "keyword", "type": "string", "required": false, "source": "body", "description": "搜索关键字,模糊匹配己方备注名、对方备注名、己方公司名、对方公司名" }, { "name": "warehouse_id", "type": "number", "required": false, "source": "body", "description": "对方主体 ID(兼容 counterparty_id)" }, { "name": "auth_status", "type": "number", "required": false, "source": "body", "description": "授权状态筛选:1=申请中 2=已通过 3=已拒绝 4=已解除 5=已过期" }, { "name": "use_status", "type": "number", "required": false, "source": "body", "description": "己方启用状态:0=禁用 1=启用" } ], "response": [ { "name": "data.list", "type": "array", "description": "签约关系列表" }, { "name": "data.list[].id", "type": "number", "description": "签约关系主键 ID" }, { "name": "data.list[].store_id", "type": "number", "description": "己方主体 ID(当前仓库)" }, { "name": "data.list[].store_name", "type": "string", "description": "己方主体名称" }, { "name": "data.list[].warehouse_id", "type": "number", "description": "对方主体 ID" }, { "name": "data.list[].warehouse_name", "type": "string", "description": "对方主体名称" }, { "name": "data.list[].counterparty_id", "type": "number", "description": "对方主体 ID(同 warehouse_id)" }, { "name": "data.list[].counterparty_name", "type": "string", "description": "对方主体名称" }, { "name": "data.list[].counterparty_role", "type": "string", "description": "对方主体角色:warehouse(外部合作仓库)或 store(货主)" }, { "name": "data.list[].remask", "type": "string", "description": "己方对本次签约的备注名" }, { "name": "data.list[].use_status", "type": "number", "description": "己方启用状态:0=禁用 1=启用" }, { "name": "data.list[].auth_status", "type": "number", "description": "签约状态:1=申请中 2=已通过 3=已拒绝 4=已解除 5=已过期" }, { "name": "data.list[].auth_status_label", "type": "string", "description": "签约状态中文标签" }, { "name": "data.list[].auth_end", "type": "string|null", "description": "授权结束时间" }, { "name": "data.list[].print_quantity", "type": "number", "description": "面单余额数量" }, { "name": "data.list[].has_qimen_config", "type": "boolean", "description": "是否已配置奇门" }, { "name": "data.list[].needs_my_confirm", "type": "boolean", "description": "是否需要当前仓库确认签约(对方发起且状态为申请中)" }, { "name": "data.total", "type": "number", "description": "总记录数" }, { "name": "data.page", "type": "number", "description": "当前页码" }, { "name": "data.page_size", "type": "number", "description": "每页条数" }, { "name": "data.current_subject", "type": "object", "description": "当前主体信息" }, { "name": "data.current_subject.store_id", "type": "number", "description": "当前主体 ID" }, { "name": "data.current_subject.company_name", "type": "string", "description": "当前主体公司名称" }, { "name": "data.current_subject.role", "type": "string", "description": "当前主体角色:warehouse" } ], "errors": [ { "code": 500, "message": "获取签约列表失败" } ] }, { "method": "storeWarehouse.warehouse.sign", "description": "仓库侧发起签约(当前仓库在 store_id 方,对方在 warehouse_id 方,支持签约外部合作仓库)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "counterparty_id", "type": "number", "required": true, "source": "body", "description": "对方主体 ID(兼容 warehouse_id / store_id),当前主体自动识别" } ], "response": [ { "name": "data.mode", "type": "string", "required": true, "description": "签约结果模式:initiate=新建或更新签约申请,already_exists=已存在待确认的签约关系,already_confirmed=已签约" }, { "name": "data.contract", "type": "object", "required": true, "description": "签约关系精简对象(data.mode 非空时返回)" }, { "name": "data.action", "type": "string", "required": false, "description": "initiate 模式下的操作类型:create=新建签约申请,update=更新已有申请" } ], "errors": [ { "code": 400, "message": "counterparty_id / 对方主体ID 参数不能为空" }, { "code": 400, "message": "counterparty_id / 对方主体ID 参数不合法" }, { "code": 400, "message": "auth_start 参数不合法" }, { "code": 400, "message": "auth_end 参数不合法" }, { "code": 400, "message": "auth_end 不能早于 auth_start" }, { "code": 404, "message": "签约对象不存在" } ] }, { "method": "storeWarehouse.warehouse.confirmSign", "description": "仓库侧确认签约:作为对方主体确认待签约申请,签约状态从 1(申请中)变为 2(已通过);发起方不能确认自己的申请", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "签约关系ID,兼容 contract_id" } ], "response": [ { "name": "data.mode", "type": "string", "required": true, "description": "确认模式标识,固定为 confirm" }, { "name": "data.contract", "type": "object", "required": true, "description": "签约关系精简对象,字段同 storeWarehouse.store.confirmSign 的 data.contract" } ], "errors": [ { "code": 400, "message": "id 参数不能为空" }, { "code": 400, "message": "当前签约状态不允许确认,仅待签约状态可确认" }, { "code": 403, "message": "当前主体不在此签约关系中" }, { "code": 403, "message": "发起方不能确认自己的签约申请" }, { "code": 404, "message": "签约关系不存在" } ] } ] }, { "groupName": "用户模块", "module": "user", "list": [ { "method": "user.login", "description": "用户登录(仅返回 token)", "isNeedAuth": false, "isNeedLogin": false, "headers": [], "params": [ { "name": "password", "type": "string", "required": false, "source": "body", "description": "password 参数" }, { "name": "username", "type": "string", "required": false, "source": "body", "description": "username 参数" } ], "response": [], "errors": [] }, { "method": "user.loginByCode", "description": "登录码登录(使用 ye4s_user.tmp_code)", "isNeedAuth": false, "isNeedLogin": false, "headers": [], "params": [ { "name": "code", "type": "string", "required": true, "source": "body", "description": "登录码,对应 ye4s_user.tmp_code" } ], "response": [], "errors": [] }, { "method": "user.getLoginWechatCode", "description": "获取微信扫码登录码(无 clientCode 时分配新客户端编码;有 clientCode 时可长轮询刷新)", "isNeedAuth": false, "isNeedLogin": false, "headers": [], "params": [ { "name": "clientCode", "type": "string", "required": false, "source": "body", "description": "客户端编码;首次可不传,后续轮询建议透传已有值" } ], "response": [], "errors": [] }, { "method": "user.getBindWechatCode", "description": "获取微信绑定码(默认立即返回;显式开启长轮询后,最长等待60秒,状态变化立即返回)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "forceRefresh", "type": "boolean", "required": false, "source": "body", "description": "是否强制刷新状态,true 时跳过缓存等待窗口" }, { "name": "waitForChange", "type": "boolean", "required": false, "source": "body", "description": "是否显式开启长轮询等待(推荐字段);true 时进入最长60秒等待" }, { "name": "longPoll", "type": "boolean", "required": false, "source": "body", "description": "长轮询开关(兼容字段);true 时进入最长60秒等待" }, { "name": "waitTimeoutMs", "type": "number", "required": false, "source": "body", "description": "等待超时毫秒数;后端自动封顶60000" }, { "name": "init", "type": "boolean", "required": false, "source": "body", "description": "初始化请求标记;true 时强制立即返回,不进入长等待" } ], "response": [], "errors": [] }, { "method": "user.unbindWechat", "description": "解绑微信账号(清理 ye4s 关联账号数据)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "user.logout", "description": "用户登出", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "user.info", "description": "获取当前用户信息(支持微信登录态中间层:微信登录未绑定真实用户时返回微信层信息 is_bound=false/id=0,不 401;绑定/正常登录返回用户完整信息)。可选入参 wechat_appId:传入时按该小程序归属仓库过滤工号列表,只保留非仓库工号(货主)与仅该仓库工号;未传或查不到仓库时保持原逻辑", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "wechat_appId", "type": "string", "required": false, "source": "body", "description": "小程序 AppID(可选):按 wms_wechat_app.appid 反查归属仓库,过滤 employees 列表" } ], "response": [], "errors": [] }, { "method": "user.changeRole", "description": "user.changeRole 接口", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "user.register", "description": "user.register 接口", "isNeedAuth": false, "isNeedLogin": false, "headers": [], "params": [], "response": [], "errors": [] } ] }, { "groupName": "仓库模块", "module": "warehouse", "list": [ { "method": "warehouse.getWarehouseZones", "description": "warehouse.getWarehouseZones 接口", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "warehouse.getWarehouseTree", "description": "warehouse.getWarehouseTree 接口", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "warehouseId", "type": "number", "required": true, "source": "body", "description": "warehouseId 参数" } ], "response": [], "errors": [] }, { "method": "warehouse.getChildren", "description": "warehouse.getChildren 接口", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "zoneId", "type": "number", "required": true, "source": "body", "description": "zoneId 参数" } ], "response": [], "errors": [] }, { "method": "warehouse.create", "description": "warehouse.create 接口", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "warehouse.update", "description": "warehouse.update 接口", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "id 参数" }, { "name": "aisles", "type": "string", "required": false, "source": "body", "description": "aisles 参数" }, { "name": "cell_height", "type": "string", "required": false, "source": "body", "description": "cell_height 参数" }, { "name": "cell_length", "type": "string", "required": false, "source": "body", "description": "cell_length 参数" }, { "name": "cell_width", "type": "string", "required": false, "source": "body", "description": "cell_width 参数" }, { "name": "direction", "type": "string", "required": false, "source": "body", "description": "direction 参数" }, { "name": "height", "type": "number", "required": false, "source": "body", "description": "height 参数" }, { "name": "is_active", "type": "boolean", "required": false, "source": "body", "description": "是否启用,支持 true/false 或 1/0" }, { "name": "length", "type": "number", "required": false, "source": "body", "description": "length 参数" }, { "name": "rack_columns", "type": "string", "required": false, "source": "body", "description": "rack_columns 参数" }, { "name": "rack_levels", "type": "string", "required": false, "source": "body", "description": "rack_levels 参数" }, { "name": "rack_rows", "type": "string", "required": false, "source": "body", "description": "rack_rows 参数" }, { "name": "width", "type": "number", "required": false, "source": "body", "description": "width 参数" }, { "name": "x", "type": "number", "required": false, "source": "body", "description": "x 参数" }, { "name": "y", "type": "number", "required": false, "source": "body", "description": "y 参数" }, { "name": "z", "type": "number", "required": false, "source": "body", "description": "z 参数" }, { "name": "zone_code", "type": "string", "required": false, "source": "body", "description": "zone_code 参数" }, { "name": "zone_name", "type": "string", "required": false, "source": "body", "description": "zone_name 参数" } ], "response": [], "errors": [] }, { "method": "warehouse.delete", "description": "warehouse.delete 接口", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "id 参数" } ], "response": [], "errors": [] }, { "method": "warehouse.detail", "description": "warehouse.detail 接口", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "id 参数" } ], "response": [], "errors": [] }, { "method": "warehouse.checkBarcodeUnique", "description": "warehouse.checkBarcodeUnique 接口", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "barcode", "type": "string", "required": true, "source": "body", "description": "barcode 参数" }, { "name": "id", "type": "number", "required": true, "source": "body", "description": "id 参数" } ], "response": [], "errors": [] }, { "method": "warehouse.toggleActive", "description": "warehouse.toggleActive 接口", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "id 参数" }, { "name": "isActive", "type": "string", "required": false, "source": "body", "description": "isActive 参数" } ], "response": [], "errors": [] }, { "method": "warehouse.getPath", "description": "warehouse.getPath 接口", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "id 参数" } ], "response": [], "errors": [] }, { "method": "warehouse.getPickPath", "description": "warehouse.getPickPath 接口", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "warehouse_id", "type": "number", "required": true, "source": "query", "description": "warehouse_id 参数" }, { "name": "include_spaces", "type": "string", "required": false, "source": "query", "description": "include_spaces 参数" }, { "name": "limit", "type": "number", "required": false, "source": "query", "description": "limit 参数" }, { "name": "sort_by", "type": "string", "required": false, "source": "query", "description": "sort_by 参数" } ], "response": [], "errors": [] }, { "method": "warehouse.updateRackPosition", "description": "warehouse.updateRackPosition 接口", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "x", "type": "number", "required": true, "source": "body", "description": "x 参数" }, { "name": "y", "type": "number", "required": true, "source": "body", "description": "y 参数" }, { "name": "rack_id", "type": "number", "required": false, "source": "path", "description": "rack_id 参数" }, { "name": "z", "type": "number", "required": false, "source": "body", "description": "z 参数" } ], "response": [], "errors": [] }, { "method": "warehouse.recalculatePickPath", "description": "warehouse.recalculatePickPath 接口", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "warehouse_id", "type": "number", "required": true, "source": "body", "description": "warehouse_id 参数" } ], "response": [], "errors": [] }, { "method": "warehouse.updateNeighbors", "description": "warehouse.updateNeighbors 接口", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "warehouse_id", "type": "number", "required": true, "source": "body", "description": "warehouse_id 参数" } ], "response": [], "errors": [] }, { "method": "warehouse.getAreaRacks", "description": "warehouse.getAreaRacks 接口", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "area_id", "type": "number", "required": true, "source": "query", "description": "area_id 参数" } ], "response": [], "errors": [] }, { "method": "warehouse.getSpacesByRack", "description": "warehouse.getSpacesByRack 接口", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "id 参数" } ], "response": [], "errors": [] }, { "method": "warehouse.createRackWithSpaces", "description": "warehouse.createRackWithSpaces 接口", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "id 参数" } ], "response": [], "errors": [] }, { "method": "warehouse.exportRackSpaces", "description": "按货架ID导出仓位模板(含仓库编码、仓位编码、自定义名称、自定义条码、拣货顺序、仓位类型)", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "货架ID,仅导出该货架下仓位" } ], "response": [ { "name": "count", "type": "number", "description": "导出记录数" }, { "name": "fileName", "type": "string", "description": "导出文件名" }, { "name": "fileUrl", "type": "string", "description": "导出文件下载地址" } ], "errors": [] }, { "method": "warehouse.batchUpdateSpaceInfo", "description": "按导出模板批量修改货架仓位信息,任一行越界或冲突则整批失败。前端提交示例:{ id: 36, items: [ { space_code: 'A01-01-01', custom_name: '拣货位1', custom_barcode: 'PICK-001', pick_sequence: 10, location_type_id: 3 } ] }。其中 id 为货架ID(可选,传入时只允许操作该货架下的仓位),space_code 为必填定位键,location_type_id 为仓位类型主键(可通过 index.getLocationTypeList 获取)。", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": false, "source": "body", "description": "货架ID,传入时校验所有 space_code 必须属于该货架,不传则只校验属于任意货架类型库位" }, { "name": "items", "type": "array", "required": true, "source": "body", "description": "批量修改数据数组;每项支持字段:space_code、custom_name、custom_barcode、pick_sequence、location_type_name" }, { "name": "items[].space_code", "type": "string", "required": true, "source": "body", "description": "仓位编码,作为批量修改的唯一定位键;缺失、重复或不存在都会整批失败" }, { "name": "items[].custom_name", "type": "string", "required": false, "source": "body", "description": "自定义名称,空字符串会被清空" }, { "name": "items[].custom_barcode", "type": "string", "required": false, "source": "body", "description": "自定义条码,批次内或系统内冲突都会整批失败;空字符串会被清空" }, { "name": "items[].pick_sequence", "type": "number", "required": false, "source": "body", "description": "拣货顺序,必须为非负整数,超出边界则整批失败" }, { "name": "items[].location_type_id", "type": "number", "required": false, "source": "body", "description": "仓位类型ID,必须为正整数且在当前仓库或全局类型中存在(is_active=true),否则整批失败;传 null 或不传则不修改仓位类型" } ], "response": [ { "name": "count", "type": "number", "description": "成功更新的记录数" } ], "errors": [] }, { "method": "warehouse.getSpaceInfo", "description": "warehouse.getSpaceInfo 接口", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "id 参数" } ], "response": [], "errors": [ { "code": "0", "description": "仓位不存在" }, { "code": "0", "description": "仓位不属于当前仓库" } ] }, { "method": "warehouse.updateSpaceInfo", "description": "warehouse.updateSpaceInfo 接口", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "id 参数" }, { "name": "custom_barcode", "type": "string", "required": false, "source": "body", "description": "custom_barcode 参数" }, { "name": "custom_name", "type": "string", "required": false, "source": "body", "description": "custom_name 参数" }, { "name": "location_type_id", "type": "number", "required": false, "source": "body", "description": "location_type_id 参数" }, { "name": "pick_sequence", "type": "string", "required": false, "source": "body", "description": "pick_sequence 参数" }, { "name": "space_status", "type": "string", "required": false, "source": "body", "description": "space_status 参数" } ], "response": [], "errors": [] } ] }, { "groupName": "出库模块", "module": "order", "list": [ { "method": "order.wave.batchList", "description": "波次列表查询。仅使用当前登录操作者仓库上下文(禁止传入 warehouse_id/warehouseId)。支持 where 白名单过滤,固定查询 wave_status=0/1;返回波次基础信息及分配状态汇总(storage_assignment_status / express_assignment_status / print_assignment_status / confirm_print_assignment_status / claim_assignment_status / pick_assignment_status / review_assignment_status / sync_assignment_status)。支持 only_todo=1 仅返回仍有未复核订单的波次,并返回复核状态汇总(review_assignment_status)与未复核数量(unreviewed_order_count)。列表每条记录返回货主信息 store_name:当波次内所有订单均为同一货主(store_id)时返回货主名称,否则返回“混合”。货主名称优先取合约表 wms_store_warehouse.store_remask(货主备注名称),无合约或备注为空时回退 wms_store.company_name(公司全称)。where 中各字段支持裸值与 {operator,value,type} 标准结构(eq/ne/gt/lt/ge/le/in/notin/between/notbetween/like/contains/notlike/startswith/endswith/isnull/isnotnull;未显式传 operator 时保持历史默认语义:wave_no/creator/logistics_name/item_part/item_snapshot_key/item_detail_machine 默认模糊,其余默认等值),详见 where 参数说明。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page / pageSize" }, { "name": "only_todo", "type": "number|boolean|string", "required": false, "source": "body", "description": "是否仅返回待处理(仍有未复核订单)的波次,默认 0;传 1/true 时仅返回 unreviewed_order_count > 0 的波次。" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "筛选白名单字段(object,可选)。仅支持下列字段过滤,且禁止传入 warehouse_id / warehouseId。\n【操作符传参】每个字段均支持「裸值」或「标准结构 {'operator':'eq','value':'...','type':'text'}」两种写法;未显式传 operator 时按该字段默认语义(见下方括号)。支持的操作符:eq、ne、gt、lt、ge、le、in、notin、between、notbetween、like、contains、notlike、startswith、endswith、isnull、isnotnull,按字段分组允许:\n- 数值类(wave_id、wave_type、wave_status、source、total_orders、processed_orders 及 total_orders_min/max、processed_orders_min/max):eq/ne/gt/lt/ge/le/in/notin/between/notbetween/isnull/isnotnull;\n- 文本类(wave_no、creator、logistics_name、item_part_type、item_part、item_snapshot_key、item_detail_machine):eq/ne/like/contains/notlike/startswith/endswith/in/notin/isnull/isnotnull;\n- 布尔类(distinguish_express):eq/ne/in/notin;\n- 分配/复核状态类(storage_assignment_status、express_assignment_status、print_assignment_status、confirm_print_assignment_status、claim_assignment_status、review_assignment_status、sync_assignment_status):仅 eq;\n- 货主(store_id):eq/in/ne/notin。\nvalue 支持数组:like/contains/startswith/endswith 多值按 OR 展开,notlike 多值按 AND 展开;in/notin 要求 value 为非空数组;eq 传数组等价于 in;between/notbetween 要求 value 为长度 2 的数组(也接受 {start,end} / {from,to})。\n【字段清单】(括号内为未显式传 operator 时的默认语义)\n- wave_id(等值)\n- wave_no(模糊)\n- wave_type(等值)\n- wave_status(等值,接口固定叠加状态 0/1)\n- creator(模糊)\n- logistics_name(模糊)\n- item_part_type(等值)\n- item_part(模糊)\n- item_snapshot_key(模糊)\n- item_detail_machine(模糊)\n- distinguish_express(等值,value 兼容 true/false/1/0)\n- total_orders / processed_orders(等值,新增:波次订单总数/已处理数,可直接用 between 等操作符)\n- total_orders_min / total_orders_max(范围,等价于 total_orders 的 ge / le)\n- processed_orders_min / processed_orders_max(范围,等价于 processed_orders 的 ge / le)\n- express_assignment_status(等值,string,可选,英文枚举,取值:unassigned、partially_assigned、assigned;语义:按快递分配聚合判断,assigned 表示聚合后全部 fin,partially_assigned 表示部分已分配且不含 error,unassigned 表示全 none 或包含 error(异常并入未分配集合))。\n- print_assignment_status(等值,string,可选,英文枚举,取值:unprinted、partially_printed、printed;语义:按打印分配聚合判断,printed 表示聚合后全部已打印)。\n- confirm_print_assignment_status(等值,string,可选,英文枚举,取值:unconfirmed、partially_confirmed、confirmed;语义:按确认打印聚合判断,confirmed 表示聚合后全部已确认打印,unconfirmed 表示全部未确认,partially_confirmed 表示部分已确认)。\n- claim_assignment_status(等值,string,可选,取值:unclaimed / claimed,兼容中文 未领料 / 已领料;语义:以波次表 wms_wave_batch.claim_time 是否为空判定,二态无部分状态)。\n- storage_assignment_status(等值,string,可选,取值:未分配、部分分配、已分配;默认不传不做限制)。过滤语义:已分配=聚合后全部 fin;部分分配=不含 error,且既不是全 none,也不是全 fin;未分配=全 none 或包含 error(异常并入未分配筛选集合)。说明:返回字段 storage_assignment_status 的展示值保持不变,包含 error 时仍可显示“分配异常”;此处 where 的过滤语义会把异常计入“未分配”,以避免把过滤语义与展示值混淆。\n- source(可选,number)来源过滤:0=普通波次(正常后台操作),1=管理后台策略任务,2=PDA策略任务;不传则不过滤。\n说明:express_assignment_status 与 print_assignment_status 要求使用英文枚举值;storage_assignment_status 仍向后兼容中文展示值。若传入的枚举值不在允许集合内,接口会返回 400(参数校验失败),并在 message 中说明错误字段与允许取值。\n- review_assignment_status(等值,string,可选,英文枚举:unreviewed、partially_reviewed、reviewed;分别表示未复核、部分复核、已复核)。\n- sync_assignment_status(等值,string,可选,英文枚举:unsynced、partially_synced、synced;分别表示未同步、部分同步、已同步;按订单 sync_status 聚合判断,synced 表示聚合后全部 fin,partially_synced 表示部分已同步且不含 error,unsynced 表示全未同步或包含 error(异常并入未同步集合))。\n- store_id(货主ID,可选,正整数,支持单值/数组/{operator,value} 结构,如 {\"operator\":\"\",\"value\":[1000281,1000000]};语义:默认 eq/in 返回包含任一筛选货主订单的波次,含混合货主波次;ne/notin 返回不包含所选货主订单的波次;不支持 like 等文本操作符)。" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "波次列表,包含波次基础信息与状态汇总(order_count / storage_assignment_status / express_assignment_status / print_assignment_status / confirm_print_assignment_status / claim_assignment_status / pick_assignment_status / review_assignment_status / sync_assignment_status / unreviewed_order_count)。其中 pick_assignment_status 按订单 pick_status 聚合判定,取值:未拣货/部分拣货/已拣货/拣货异常。sync_assignment_status 按订单 sync_status 聚合判定,取值:未同步/部分同步/已同步/同步异常(error 并入未同步集合)。confirm_print_assignment_status 按订单 confirm_print_status 聚合判定,取值:未确认打印/部分确认打印/已确认打印。claim_assignment_status 按波次表 wms_wave_batch.claim_time 判定(已领料/未领料,二态),并同步返回 claim_time 与 claim_operator。每条记录新增字段 source(number):来源标识,0=普通波次(正常后台操作),1=管理后台策略任务,2=PDA策略任务。每条记录新增字段 store_name(string):货主信息,当波次内所有订单均为同一货主(store_id)时返回货主名称,否则返回“混合”;货主名称优先取合约表 wms_store_warehouse.store_remask(货主备注名称),无合约或备注为空时回退 wms_store.company_name(公司全称)。" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)" } ], "errors": [ { "code": 400, "message": "未识别到当前仓库上下文" }, { "code": 500, "message": "查询失败" } ] }, { "method": "order.pendingOrder.downloadCreateTemplate", "description": "下载创建订单的 Excel 导入模板。返回 base64 编码的 xlsx 文件,前端解码后作为 .xlsx 附件下载。表头中标注 * 的列为必填项(橙色背景),可选列为灰色背景,包含示例数据行和填写说明工作表。多行相同订单号的行组成一个完整订单,每行代表一条商品明细。模板共 25 列(A-Y):店铺名称(shop_nick)位于第2列B列,紧接*订单号(delivery_order_code)之后;其余必填列为*收件人姓名(name)、*手机号(mobile)、*详细地址(detail_address)、*商品编码(item_code)、*计划数量(plan_qty);非必填列依次为货主ID(store_id)、电话(tel)、省份(province)、城市(city)、区/县(area)、镇/街道(town)、邮编(zip_code)、快递编码(logistics_code)、快递名称(logistics_name)、系统平台编码(sys_platform_code)、来源平台编码(source_platform_code)、来源订单号(source_order_codes)、订单类型(order_type)、是否紧急(is_urgency)、是否需要发票(invoice_flag)、商品名称(item_name)、行号(order_line_no)、实际价格(actual_price)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [ { "name": "base64", "type": "string", "required": true, "description": "base64 编码的 xlsx 文件内容" }, { "name": "filename", "type": "string", "required": true, "description": "建议保存的文件名,固定为 创建订单导入模板.xlsx" }, { "name": "mime", "type": "string", "required": true, "description": "文件 MIME 类型,固定为 application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" } ], "errors": [] }, { "method": "order.pendingOrder.manualWaybill", "description": "手工录入运单号。为指定待处理订单创建一条运单记录(wms_order_express 表),仅允许 step 在 [1,2,3] 且 outbound_status 不为 'padding' 的订单操作。完成后自动更新订单表的 print_status 与 post_status 为 'fin',表示外部已打印。可选传入 express_code,行为参考 updateOrderExpress:从当前仓库快递列表(带缓存)中查找对应项,若为自定义映射(is_system_setting=true),订单 sys_logistics_code/name 写系统快递编码和名称、logistics_code/name 写自定义编码和名称;若为系统快递(is_system_setting=false),四个字段均写系统快递的 code/name;未找到则报错;不传则运单记录沿用订单当前系统快递信息。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "order_id", "type": "number", "required": true, "source": "body", "description": "订单 ID,必须为正整数" }, { "name": "waybill_code", "type": "string", "required": true, "source": "body", "description": "运单号,非空字符串" }, { "name": "logistics_interface_name", "type": "string", "required": false, "source": "body", "description": "物流接口名称(选填),手工填入的值,trim 后为空则传 null" }, { "name": "express_code", "type": "string", "required": false, "source": "body", "description": "快递编码(选填),可为系统编码或仓库自定义编码。传入时同步修改订单的快递信息,行为参考 updateOrderExpress;不传时运单记录沿用订单当前系统快递信息" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "创建的运单记录 ID" }, { "name": "order_id", "type": "number", "required": true, "description": "订单 ID" }, { "name": "waybill_code", "type": "string", "required": true, "description": "运单号" }, { "name": "business_key", "type": "number", "required": true, "description": "递增的业务键,同一订单下从 1 开始递增" }, { "name": "logistics_interface_name", "type": "string", "required": false, "description": "写入的物流接口名称,未传时为 null" }, { "name": "create_at", "type": "string", "required": true, "description": "创建时间" }, { "name": "express_code", "type": "string", "required": false, "description": "传入的快递编码,未传时不返回" }, { "name": "sys_logistics_code", "type": "string", "required": false, "description": "写入订单的系统快递编码,仅在传入 express_code 时返回" }, { "name": "sys_logistics_name", "type": "string", "required": false, "description": "写入订单的系统快递名称,仅在传入 express_code 时返回" }, { "name": "logistics_code", "type": "string", "required": false, "description": "写入订单与运单记录的快递编码(自定义或系统),仅在传入 express_code 时返回" }, { "name": "logistics_name", "type": "string", "required": false, "description": "写入订单与运单记录的快递名称(自定义或系统),仅在传入 express_code 时返回" } ], "errors": [ { "code": 400, "message": "order_id 必须为正整数" }, { "code": 400, "message": "waybill_code(运单号)不能为空" }, { "code": 400, "message": "订单不存在或不属于当前仓库" }, { "code": 400, "message": "订单当前步骤不在允许范围,仅允许待处理状态(step 1/2/3)的订单手工录入运单号" }, { "code": 400, "message": "订单已标记待出库,不允许手工录入运单号" }, { "code": 404, "message": "快递编码 不存在" }, { "code": 500, "message": "内部错误:OrderExpress 模型未加载或数据库写入失败" } ] }, { "method": "order.pendingOrder.allocateSubOrderNumber", "description": "分配子单号(异步任务模式)。为指定订单按 business_key(从 2 开始)全量传入 createWaybillCodePipeline,由其内部事务 + UNIQUE(order_id,business_key,status,warehouse_id) 索引保证并发安全:已分配(status=1)自动跳过,未分配 INSERT status=0 占位后分配。请求立即返回 task_id(sub_ 前缀),后续通过 allocateSubOrderNumberProgress 按 task_id 或 business_key 查询进度与结果。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "order_id", "type": "number", "required": true, "source": "body", "description": "订单 ID,必须为正整数" }, { "name": "sub_order_count", "type": "number", "required": true, "source": "body", "description": "子单号数量,>= 1。business_key 从 2 开始递增,如 count=1 则创建 business_key=2,count=3 则创建 2/3/4" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID(sub_ 前缀),用于查询进度" }, { "name": "order_id", "type": "number", "required": true, "description": "订单 ID" }, { "name": "status", "type": "string", "required": true, "description": "任务状态:submitted/running/success/partial/failed" }, { "name": "progress", "type": "number", "required": true, "description": "进度百分比:5/50/80/100" }, { "name": "message", "type": "string", "required": true, "description": "任务状态说明" }, { "name": "result", "type": "object", "required": true, "description": "分配结果摘要,含 total_count/skip_count/pending_count/business_keys/skipped_business_keys/pending_business_keys/details 等字段" } ], "errors": [ { "code": 400, "message": "order_id 必须为正整数" }, { "code": 400, "message": "sub_order_count 必须为正整数且 >= 1" }, { "code": 400, "message": "订单不存在或不属于当前仓库" }, { "code": 400, "message": "订单当前步骤不在允许范围,仅允许待处理状态(step 1/2/3)的订单分配子单号" }, { "code": 400, "message": "订单已标记待出库,不允许分配子单号" }, { "code": 500, "message": "内部错误:OrderExpress 模型未加载或运单分配链路异常" } ] }, { "method": "order.pendingOrder.allocateSubOrderNumberProgress", "description": "查询子单号分配任务进度。可按 task_id 查询整体进度,也可传入 business_key 进一步过滤该业务ID对应的分配详情与最终结果。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id", "type": "string", "required": true, "source": "body", "description": "任务 ID(返回的 task_id),支持 task_id 或 taskId 两种写法" }, { "name": "business_key", "type": "number", "required": false, "source": "body", "description": "子单号业务ID(可选),传入后返回该 business_key 对应的分配详情。支持 business_key 或 businessKey 两种写法" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID" }, { "name": "order_id", "type": "number", "required": true, "description": "订单 ID" }, { "name": "status", "type": "string", "required": true, "description": "任务状态:submitted/running/success/partial/failed/not_found" }, { "name": "progress", "type": "number", "required": true, "description": "进度百分比" }, { "name": "message", "type": "string", "required": true, "description": "任务状态说明" }, { "name": "result", "type": "object", "required": true, "description": "分配结果。若传了 business_key,额外返回 filtered_business_key 与 matched_detail" } ], "errors": [ { "code": 500, "message": "查询缓存异常" } ] }, { "method": "order.pendingOrder.batchMarkPrinted", "description": "批量设置订单为已打印状态。将给定订单ID列表中属于当前仓库的订单的 print_status 更新为 'fin'。先查 current 表(wms_order_delivery_{warehouseId}),未命中的 ID 再兜底查 dispatch 表(wms_order_delivery_{warehouseId}_dispatch)。仅允许 step 在 [1,2,3] 且 status 不为 'cancel' 的订单操作,已打印的订单会被静默跳过。仓库ID统一使用当前上下文(ctx.user.store_id)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "order_ids / orderIds / ids", "type": "number[]", "required": true, "source": "body", "description": "订单ID数组;优先级 order_ids > orderIds > ids" } ], "response": [ { "name": "updated_count", "type": "number", "required": true, "description": "实际更新的订单数量(已打印的订单会被静默跳过,不计入)" }, { "name": "ids", "type": "number[]", "required": true, "description": "请求的订单ID列表(原样回传)" } ], "errors": [ { "code": 400, "message": "未识别到当前仓库上下文" }, { "code": 400, "message": "order_ids 参数不能为空或格式错误" } ] }, { "method": "order.bindExpressPackageMaterialByWaybill", "description": "按运单号绑定包材。仅需传入运单号与包材ID,系统自动根据运单号反查对应订单运单记录并绑定包材,无需传入订单ID。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "waybill_code", "type": "string", "required": true, "source": "body", "description": "运单号,必填。" }, { "name": "package_material_id", "type": "number|string", "required": true, "source": "body", "description": "包材ID,必填。" } ], "response": [ { "name": "order_id", "type": "number", "required": true, "description": "运单号对应的订单ID(成功时返回于 data 对象中)。" }, { "name": "waybill_code", "type": "string", "required": true, "description": "运单号(成功时返回于 data 对象中)。" }, { "name": "package_material_id", "type": "number", "required": true, "description": "绑定后的包材ID(成功时返回于 data 对象中)。" }, { "name": "package_material_name_snapshot", "type": "string", "required": true, "description": "绑定后的包材名称快照(成功时返回于 data 对象中)。" }, { "name": "package_material_code", "type": "string", "required": true, "description": "绑定后的包材编码(成功时返回于 data 对象中)。" } ], "errors": [ { "code": 404, "message": "运单号不存在" }, { "code": 400, "message": "包材不存在或已禁用" }, { "code": 500, "message": "绑定包材失败" } ] }, { "method": "order.wave.confirmPrintScan", "description": "确认打印扫描(与领单 pick.waveClaimScan 操作一致):扫波次内任一订单的面单号,将波次下全部已打印(print_status='fin')且非拦截的订单批量标记 confirm_print_status='fin',并写订单操作日志(ORDER_CONFIRM_PRINT)。拦截订单跳过(不确认、不阻断);波次下存在未打印订单(print_status != 'fin')时阻断;全部已确认时重复扫描返回 already_confirmed。成功后递增确认打印未领单统计版本号,驱动 confirmPrintUnclaimedWaveCount 长轮询立即返回新值。", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "waybill_no", "type": "string", "required": true, "source": "body", "description": "面单号/运单号(必填,用于定位订单及所属波次)" } ], "response": [ { "name": "waybill_no", "type": "string", "required": false, "description": "扫描的面单号" }, { "name": "matched_order_id", "type": "number", "required": false, "description": "面单号匹配到的订单ID" }, { "name": "wave_id", "type": "number", "required": false, "description": "波次ID" }, { "name": "wave_no", "type": "string", "required": false, "description": "波次编码" }, { "name": "total_order_count", "type": "number", "required": false, "description": "波次下总订单数" }, { "name": "intercepted_order_count", "type": "number", "required": false, "description": "波次下拦截订单数(跳过确认)" }, { "name": "confirmed_order_count", "type": "number", "required": false, "description": "已确认打印订单数(confirm_print_status='fin')" }, { "name": "newly_confirmed_order_count", "type": "number", "required": false, "description": "本次新增确认订单数(仅 status=confirmed 时返回)" }, { "name": "status", "type": "string", "required": false, "description": "确认结果:confirmed=本次完成确认 / already_confirmed=已全部确认" } ], "errors": [ { "code": 400, "message": "waybill_no 必填(面单号/运单号)" }, { "code": 400, "message": "缺少当前用户仓库上下文 store_id" }, { "code": 400, "message": "运单对应订单未分配波次" }, { "code": 400, "message": "波次存在未打印订单,禁止确认打印(返回 unprinted_order_count)" }, { "code": 404, "message": "未查询到该面单号对应的订单,无记录" }, { "code": 500, "message": "内部错误(OrderDeliveryFactory/订单模型不可用或更新失败)" } ] }, { "method": "order.wave.confirmPrintUnclaimedWaveCount", "description": "快速查询「已确认打印但未领单」的波次数量,使用当前登录操作者仓库上下文。口径(波次表驱动):未领单以 wms_wave_batch.claim_time IS NULL 为准(历史领单发生在波次表增加 claim_time 字段之前时,订单维度 claim_status 可能已是 fin 但波次表无记录,故不用订单 claim_status 判断),已确认打印以波次下存在 confirm_print_status='fin' 的非取消订单为准,仅统计 wave_status 0/1 的波次。支持长轮询(参考扫码登录):不传 last_count 立即返回当前值(status=current);传 last_count 且与当前值不同立即返回新值(status=changed);传 last_count 且与当前值相同则进入等待,每 1 秒检查统计版本号(确认打印/领单成功会递增版本号),最长等待 60 秒:期间变化立即返回新值(status=changed),超时未变化重查后返回当前值(status=timeout)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "last_count", "type": "number", "required": false, "source": "body", "description": "上次调用返回的 count(可选基线);传入后进入最长 60s 长轮询等待变化,不传则立即返回当前值" } ], "response": [ { "name": "count", "type": "number", "required": true, "description": "已确认打印但未领单的波次数量" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "当前仓库ID" }, { "name": "status", "type": "string", "required": true, "description": "返回状态:current=即时返回当前值 / changed=检测到变化返回新值 / timeout=等待 60s 未变化返回当前值" } ], "errors": [ { "code": 400, "message": "未识别到当前仓库上下文" }, { "code": 500, "message": "查询失败" } ] } ] }, { "groupName": "店铺模块", "module": "shops", "list": [ { "method": "shops.list", "description": "分页查询店铺,支持 where 条件(支持字段:id, platform_code, custom_name, shop_name, status, quickWhere),兼容 snake_case 与 camelCase 入参;返回分页信息与标准化店铺列表。", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "page", "type": "number", "required": false, "source": "body", "description": "页码,兼容 pagination.page/currentPage" }, { "name": "pageSize", "type": "number", "required": false, "source": "body", "description": "每页大小,兼容 page_size/pagination.page_size,最大 200" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "查询条件,支持标准 where 结构或 quickWhere 简写,字段兼容 id/platform_code/custom_name/shop_name/status/quickWhere" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "调用结果标识,成功为 success" }, { "name": "code", "type": "number", "required": true, "description": "业务状态码,成功为 200" }, { "name": "message", "type": "string", "required": true, "description": "提示信息" }, { "name": "data.list", "type": "array", "required": true, "description": "店铺数组,元素结构见 children", "children": [ { "name": "id", "type": "number", "description": "店铺 ID" }, { "name": "warehouse_id", "type": "number", "description": "仓库 ID" }, { "name": "platform_code", "type": "string", "description": "平台编码,返回大写" }, { "name": "platform_name", "type": "string", "description": "平台名称(来自关联 printPlatform)" }, { "name": "shop_name", "type": "string", "description": "店铺原始名称" }, { "name": "custom_name", "type": "string|null", "description": "店铺自定义名称" }, { "name": "status", "type": "number", "description": "授权状态:0=未授权,1=已授权" }, { "name": "created_at", "type": "string", "description": "创建时间" }, { "name": "updated_at", "type": "string", "description": "更新时间" } ] }, { "name": "data.pagination", "type": "object", "required": true, "description": "分页信息", "children": [ { "name": "page", "type": "number", "description": "当前页" }, { "name": "pageSize", "type": "number", "description": "每页大小" }, { "name": "total", "type": "number", "description": "总记录数" }, { "name": "totalPages", "type": "number", "description": "总页数" }, { "name": "hasNext", "type": "boolean", "description": "是否有下一页" }, { "name": "hasPrevious", "type": "boolean", "description": "是否有上一页" } ] } ], "errors": [ { "code": 400, "message": "未识别到当前仓库" }, { "code": 400, "message": "where 参数解析失败" }, { "code": 500, "message": "查询店铺列表失败" } ] }, { "method": "shops.add", "description": "新增店铺,校验 platform_code 必须匹配已配置且处于 ACTIVE 且未删除的打印平台;custom_name 必填且长度<=100。shop_name 由服务端生成待授权占位名(PENDING_*),授权后再同步真实店铺名。支持 snake_case 与 camelCase 入参兼容。", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "platform_code", "type": "string", "required": true, "source": "body", "description": "平台编码,兼容 platformCode,服务端会标准化为大写并验证" }, { "name": "custom_name", "type": "string", "required": true, "source": "body", "description": "店铺自定义名称,最大长度 100" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "success" }, { "name": "code", "type": "number", "required": true, "description": "200 成功" }, { "name": "message", "type": "string", "required": true, "description": "提示信息" }, { "name": "data.id", "type": "number", "required": true, "description": "新建店铺 ID" } ], "errors": [ { "code": 400, "message": "platform_code 未匹配到打印平台编码" }, { "code": 400, "message": "custom_name 不能为空" }, { "code": 400, "message": "custom_name 长度不能超过 100" }, { "code": 409, "message": "同仓同平台下 shop_name 已存在" }, { "code": 500, "message": "新增店铺失败" } ] }, { "method": "shops.del", "description": "软删除店铺:将 shop_name 修改为 DELETED_SHOP__ 并清空敏感字段;若存在 ExpressInterface 引用则返回 409;返回 deleted=true 与 id。", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "店铺 ID,兼容 shop_id/shopId" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "success" }, { "name": "code", "type": "number", "required": true, "description": "200 成功" }, { "name": "message", "type": "string", "required": true, "description": "提示信息" }, { "name": "data.deleted", "type": "boolean", "required": true, "description": "是否已删除" }, { "name": "data.id", "type": "number", "required": true, "description": "删除的店铺 ID" } ], "errors": [ { "code": 400, "message": "shop_id 参数不合法" }, { "code": 404, "message": "店铺不存在" }, { "code": 409, "message": "店铺存在快递接口引用,无法删除" }, { "code": 500, "message": "删除店铺失败" } ] }, { "method": "shops.edit", "description": "编辑店铺,仅允许修改 platform_code、custom_name 或 shop_name,至少传入其中一个。platform_code 会校验平台存在且为 ACTIVE(未匹配返回 400);custom_name/shop_name 传入时需非空且长度<=100;shop_name 修改需满足同仓同平台唯一(同时改 platform_code 时按新平台校验,冲突返回 409);服务端兼容 snake_case/camelCase 入参。", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "店铺 ID,兼容 shop_id/shopId" }, { "name": "platform_code", "type": "string", "required": false, "source": "body", "description": "平台编码,兼容 platformCode,服务端会转为大写并校验" }, { "name": "custom_name", "type": "string", "required": false, "source": "body", "description": "自定义名称,兼容 customName,若传入需非空且 <=100 字符" }, { "name": "shop_name", "type": "string", "required": false, "source": "body", "description": "店铺名称(平台真实店铺名),兼容 shopName,若传入需非空且 <=100 字符,且同仓同平台下不可重复" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "success" }, { "name": "code", "type": "number", "required": true, "description": "200 成功" }, { "name": "message", "type": "string", "required": true, "description": "提示信息" }, { "name": "data.updated", "type": "boolean", "required": true, "description": "是否已更新" }, { "name": "data.id", "type": "number", "required": true, "description": "被更新的店铺 ID" } ], "errors": [ { "code": 400, "message": "仅允许修改 platform_code、custom_name 或 shop_name" }, { "code": 400, "message": "platform_code 未匹配到打印平台编码" }, { "code": 400, "message": "custom_name 不能为空" }, { "code": 400, "message": "shop_name 不能为空" }, { "code": 400, "message": "shop_name 长度不能超过 100" }, { "code": 400, "message": "shop_id 参数不合法" }, { "code": 400, "message": "未识别到当前仓库" }, { "code": 404, "message": "店铺不存在" }, { "code": 409, "message": "同仓同平台下 shop_name 已存在" }, { "code": 500, "message": "编辑店铺失败" } ] }, { "method": "shops.GetAuthorizeSessionKey", "description": "按店铺所属平台向授权服务换取授权会话(saveShop)。入参兼容 id/shop_id/shopId 与 callbackurl/callback_url,callbackurl 必填;视频号平台还需 appId 与 toUserName(此时不带 RedirectCodeUrl),京东平台附带 VenderID。成功后更新店铺 access_token 与 status=1,返回 data.message='获取授权成功'。", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "店铺 ID,兼容 shop_id/shopId" }, { "name": "callbackurl", "type": "string", "required": true, "source": "body", "description": "授权回调地址,兼容 callback_url,最长 500 字符" }, { "name": "appId", "type": "string", "required": false, "source": "body", "description": "视频号平台必填:授权服务应用 ID" }, { "name": "toUserName", "type": "string", "required": false, "source": "body", "description": "视频号平台必填:授权服务用户名" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "success" }, { "name": "code", "type": "number", "required": true, "description": "200 成功" }, { "name": "message", "type": "string", "required": true, "description": "提示信息" }, { "name": "data.message", "type": "string", "required": true, "description": "成功时固定返回「获取授权成功」" } ], "errors": [ { "code": 400, "message": "shop_id 不能为空" }, { "code": 400, "message": "shop_id 参数不合法" }, { "code": 400, "message": "callbackurl 不能为空" }, { "code": 400, "message": "callbackurl 长度不能超过 500" }, { "code": 400, "message": "未识别到当前仓库" }, { "code": 404, "message": "店铺不存在" }, { "code": 400, "message": "platform_code 不能为空" }, { "code": 400, "message": "platform_code 未匹配到打印平台编码" }, { "code": 400, "message": "视频号授权需要提供 appId 和 toUserName" }, { "code": 500, "message": "获取授权失败,未返回 sessionKey" }, { "code": 500, "message": "获取授权失败:接口请求异常(上游返回非 0 时携带上游 msg)" } ] } ] }, { "groupName": "包材管理模块", "module": "setting.packageMaterial", "list": [ { "method": "setting.packageMaterial.create", "description": "创建包材(当前仓库范围)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "material_code", "type": "string", "required": true, "source": "body", "description": "包材编码(大写且在当前仓库唯一)" }, { "name": "material_name", "type": "string", "required": true, "source": "body", "description": "包材名称" }, { "name": "material_type", "type": "string", "required": false, "source": "body", "description": "包材类型" }, { "name": "spec", "type": "string", "required": false, "source": "body", "description": "规格" }, { "name": "length", "type": "number", "required": false, "source": "body", "description": "长度" }, { "name": "width", "type": "number", "required": false, "source": "body", "description": "宽度" }, { "name": "height", "type": "number", "required": false, "source": "body", "description": "高度" }, { "name": "weight", "type": "number", "required": false, "source": "body", "description": "重量(单位 g)" }, { "name": "cost_price", "type": "number", "required": false, "source": "body", "description": "成本价" }, { "name": "status", "type": "number", "required": false, "source": "body", "description": "状态 0/1,默认 1" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "包材 ID" } ], "errors": [ { "code": 400, "message": "参数错误" }, { "code": 409, "message": "material_code 冲突" }, { "code": 500, "message": "服务器错误" } ] }, { "method": "setting.packageMaterial.update", "description": "更新包材(按 id 更新,支持部分字段)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "包材 ID(也兼容 material_id/materialId)" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "包材 ID" } ], "errors": [ { "code": 400, "message": "参数错误" }, { "code": 404, "message": "未找到包材或无权限" }, { "code": 409, "message": "material_code 冲突" } ] }, { "method": "setting.packageMaterial.delete", "description": "删除包材(支持 ids 数组或逗号分隔字符串,兼容 id/material_id/materialId)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "array|number|string", "required": true, "source": "body", "description": "要删除的 ID 列表" } ], "response": [ { "name": "deleted", "type": "boolean", "required": true, "description": "是否删除成功" } ], "errors": [ { "code": 400, "message": "ids 参数错误" }, { "code": 404, "message": "存在不存在或无权限删除的项" } ] }, { "method": "setting.packageMaterial.get", "description": "查询包材列表,支持 where + pagination(兼容旧别名 list,建议使用 get)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page/pageSize" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "筛选条件,支持 material_code/material_name/material_type/status/quickWhere" } ], "response": [ { "name": "page", "type": "number", "required": true, "description": "当前页" }, { "name": "page_size", "type": "number", "required": true, "description": "每页大小" }, { "name": "total", "type": "number", "required": true, "description": "总数" }, { "name": "list", "type": "array", "required": true, "description": "包材项数组" } ], "errors": [ { "code": 400, "message": "参数解析失败" } ] }, { "method": "setting.packageMaterial.list", "description": "兼容旧称 list,内部转发至 get;建议改用 setting.packageMaterial.get", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] }, { "method": "setting.packageMaterial.search", "description": "包材关键字搜索,按 material_code / material_name 模糊匹配,最多返回 50 条(仅返回启用中的包材)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "keyword", "type": "string", "required": false, "source": "body", "description": "搜索关键字,模糊匹配 material_code、material_name;为空时返回前 50 条启用中的包材" } ], "response": [ { "name": "data[]", "type": "array", "required": true, "description": "包材列表,每项包含 id(包材ID)、material_code(包材编码)、material_name(包材名称)、material_type(包材类型)、spec(规格)、status(状态)" } ], "errors": [ { "code": 500, "message": "服务器错误" } ] } ] }, { "groupName": "package-supplier-module", "module": "setting.packageSupplier", "list": [ { "method": "setting.packageSupplier.create", "description": "Create package supplier (current warehouse scope)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "supplier_code", "type": "string", "required": true, "source": "body", "description": "Supplier code (uppercased, unique in warehouse)" }, { "name": "supplier_name", "type": "string", "required": true, "source": "body", "description": "Supplier name" }, { "name": "contact_name", "type": "string", "required": false, "source": "body", "description": "Contact name" }, { "name": "contact_phone", "type": "string", "required": false, "source": "body", "description": "Contact phone" }, { "name": "status", "type": "number", "required": false, "source": "body", "description": "Status 0/1, default 1" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "Created supplier id" } ], "errors": [ { "code": 400, "message": "Invalid parameters" }, { "code": 409, "message": "supplier_code conflict" } ] }, { "method": "setting.packageSupplier.update", "description": "Update package supplier by id (partial update supported)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "Supplier id (also supports supplier_id / supplierId)" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "Supplier id" } ], "errors": [ { "code": 400, "message": "Invalid parameters" }, { "code": 404, "message": "Supplier not found or no permission" } ] }, { "method": "setting.packageSupplier.delete", "description": "Delete package suppliers (supports ids array or comma-separated string)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "array|number|string", "required": true, "source": "body", "description": "IDs to delete" } ], "response": [ { "name": "deleted", "type": "boolean", "required": true, "description": "Deleted flag" } ], "errors": [ { "code": 400, "message": "ids invalid" }, { "code": 404, "message": "Some items not found or no permission" } ] }, { "method": "setting.packageSupplier.get", "description": "Get package supplier list (supports where + pagination). list is an alias to get; prefer get.", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "Pagination parameters" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "Filter conditions" } ], "response": [ { "name": "page", "type": "number", "required": true, "description": "Current page" }, { "name": "page_size", "type": "number", "required": true, "description": "Page size" }, { "name": "total", "type": "number", "required": true, "description": "Total" }, { "name": "list", "type": "array", "required": true, "description": "Supplier array" } ], "errors": [ { "code": 400, "message": "Invalid parameters" } ] }, { "method": "setting.packageSupplier.list", "description": "Compatibility alias for get; internally forwards to get. Prefer setting.packageSupplier.get.", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [], "errors": [] } ] }, { "groupName": "组合商品模块", "module": "comboGoods", "list": [ { "method": "comboGoods.list", "description": "组合商品列表查询(分页),支持按 combo_code/combo_name/status/warehouse_id 筛选。返回含 custom_code(自定义编码)、simpleNotation(stock_id|数量)和 nameNotation(【数量】商品名称)简记字段", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page / pageSize,默认 page=1 pageSize=20" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "筛选条件对象,支持 combo_code(精确匹配)、combo_name(模糊匹配)、status(等值)、warehouse_id(等值)" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "组合商品列表,每项包含 id、combo_code、combo_name、combo_sku_id、custom_code、status、warehouse_id、remark、creator_id、editor_id、created_at、updated_at、items(子商品明细数组)、simpleNotation、nameNotation", "children": [ { "name": "id", "type": "number", "description": "组合商品ID" }, { "name": "combo_code", "type": "string", "description": "组合商品编码" }, { "name": "combo_name", "type": "string", "description": "组合商品名称" }, { "name": "combo_sku_id", "type": "number", "description": "组合商品SKU ID" }, { "name": "custom_code", "type": "string", "description": "自定义编码,可为 null" }, { "name": "status", "type": "number", "description": "状态:1=启用 0=停用" }, { "name": "warehouse_id", "type": "number", "description": "仓库ID" }, { "name": "remark", "type": "string", "description": "备注" }, { "name": "creator_id", "type": "number", "description": "创建人ID" }, { "name": "editor_id", "type": "number", "description": "最后编辑人ID" }, { "name": "created_at", "type": "string", "description": "创建时间" }, { "name": "updated_at", "type": "string", "description": "更新时间" }, { "name": "items", "type": "array", "description": "子商品明细列表,每项含 id、combo_id、item_goods_sku_id、item_quantity、sort_order" }, { "name": "simpleNotation", "type": "string", "description": "简记字符串,格式:stock_id|数量,stock_id2|数量" }, { "name": "nameNotation", "type": "string", "description": "商品名称简记,格式:【数量】商品名称+【数量】商品名称" } ] }, { "name": "total", "type": "number", "required": true, "description": "总记录数" }, { "name": "page", "type": "number", "required": true, "description": "当前页码" }, { "name": "pageSize", "type": "number", "required": true, "description": "每页大小" } ], "errors": [ { "code": "500", "message": "查询失败" } ] }, { "method": "comboGoods.create", "description": "创建组合商品(含明细一次性提交)。校验:combo_code唯一性、custom_code按货主唯一(排除已删除记录)、所有子商品在wms_stock_warehouse中合法有效(is_valid=Y 且未删除)、所有子商品必须属于同一货主(store_id一致)。创建过程在事务中完成,保证主表和明细表的原子写入。", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "combo_code", "type": "string", "required": true, "source": "body", "description": "组合商品编码,必填,全局唯一" }, { "name": "combo_name", "type": "string", "required": true, "source": "body", "description": "组合商品名称,必填" }, { "name": "warehouse_id", "type": "number", "required": false, "source": "body", "description": "仓库ID,可选" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注,可选" }, { "name": "custom_code", "type": "string", "required": false, "source": "body", "description": "自定义编码,可选。传入时校验按货主唯一(排除已删除记录)" }, { "name": "items", "type": "array", "required": true, "source": "body", "description": "子商品明细数组,每项含 item_goods_sku_id(number, 必填)和 item_quantity(number, 必填, 正整数)以及 sort_order(number, 可选, 排序号)" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "新建的组合商品ID" }, { "name": "combo_code", "type": "string", "required": true, "description": "组合商品编码" }, { "name": "combo_name", "type": "string", "required": true, "description": "组合商品名称" }, { "name": "custom_code", "type": "string", "required": false, "description": "自定义编码,未传入时为 null" } ], "errors": [ { "code": "400", "message": "组合商品编码不能为空" }, { "code": "400", "message": "组合商品名称不能为空" }, { "code": "400", "message": "子商品列表不能为空" }, { "code": "400", "message": "组合商品编码 \"{code}\" 已存在(409语义)" }, { "code": "400", "message": "自定义编码 \"{code}\" 已被货主其他组合商品使用" }, { "code": "400", "message": "以下子商品不存在或已停用:{ids}" }, { "code": "400", "message": "所有子商品必须属于同一个货主,不允许跨货主组合" }, { "code": "500", "message": "创建组合商品主记录失败" } ] }, { "method": "comboGoods.update", "description": "编辑组合商品(含明细替换)。校验同 create。传入 items 则先删旧明细再批量插入新明细,事务保证原子性。支持部分更新:不传的字段保持原值不变。custom_code 校验按货主唯一(排除已删除记录和自身)。", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "组合商品ID,必填" }, { "name": "combo_name", "type": "string", "required": false, "source": "body", "description": "组合商品名称,可选" }, { "name": "warehouse_id", "type": "number", "required": false, "source": "body", "description": "仓库ID,可选" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注,可选" }, { "name": "custom_code", "type": "string", "required": false, "source": "body", "description": "自定义编码,可选。传入非空值时校验按货主唯一(排除已删除记录和自身 id)" }, { "name": "status", "type": "number", "required": false, "source": "body", "description": "状态:1=启用 0=停用,可选" }, { "name": "items", "type": "array", "required": false, "source": "body", "description": "子商品明细数组,可选。传入非空数组时先删除旧明细再批量插入新明细;不传或传空数组则保持原明细不变。每项含 item_goods_sku_id(number)和 item_quantity(number)以及 sort_order(number, 可选)" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "更新后的组合商品ID" } ], "errors": [ { "code": "400", "message": "组合商品ID不能为空" }, { "code": "404", "message": "组合商品不存在" }, { "code": "400", "message": "自定义编码 \"{code}\" 已被货主其他组合商品使用" }, { "code": "400", "message": "以下子商品不存在或已停用:{ids}" }, { "code": "400", "message": "所有子商品必须属于同一个货主,不允许跨货主组合" }, { "code": "500", "message": "更新失败" } ] }, { "method": "comboGoods.delete", "description": "删除组合商品(软删除,将 status 置为 0)", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "组合商品ID,必填" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "已软删除的组合商品ID" } ], "errors": [ { "code": "400", "message": "组合商品ID不能为空" }, { "code": "404", "message": "组合商品不存在" }, { "code": "500", "message": "删除失败" } ] }, { "method": "comboGoods.search", "description": "关键字搜索组合商品(供手工建单选择)。模糊匹配 custom_code、combo_code 或 combo_name,仅返回启用状态(status=1)的记录,默认20条上限100条。custom_code 匹配项优先排在前面。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "keyword", "type": "string", "required": true, "source": "body", "description": "搜索关键字,模糊匹配 custom_code、combo_code 和 combo_name" }, { "name": "limit", "type": "number", "required": false, "source": "body", "description": "最大返回条数,默认20,最大100" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "搜索结果列表,每项包含 id、combo_code、combo_name、custom_code、combo_sku_id、status、warehouse_id、items、simpleNotation、nameNotation" }, { "name": "total", "type": "number", "required": true, "description": "本次返回的记录条数" } ], "errors": [ { "code": "400", "message": "搜索关键字不能为空" }, { "code": "500", "message": "搜索失败" } ] } ] }, { "groupName": "收货管理", "module": "storage.receiving", "list": [ { "method": "storage.receiving.getAvailableInboundQuantity", "description": "[已删除] 按 stock_id 查询可入库数量。该方法已从代码中删除,不再可用。原依赖已弃用的 wms_entry_receiving_binding(明细绑定表),入库单与收货单的关系已改为通过 wms_entry_order_receiving 主表级关联。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [], "response": [], "errors": [] }, { "method": "storage.receiving.scanDetail", "description": "PDA 上架扫码定位收货明细:扫描商品条码/箱唛/托盘唛,快速定位收货明细。同一条码可能匹配多条收货明细,以列表 { list, total } 格式返回所有匹配结果。若 barcode 为纯数字优先按明细 ID 精确匹配,否则按商品条码精确匹配。PDA专用。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "entry_order_id", "type": "number", "required": true, "source": "body", "description": "入库单 ID" }, { "name": "barcode", "type": "string", "required": true, "source": "body", "description": "扫描条码,支持:收货明细 ID(托盘唛头)、商品条码" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "匹配的收货明细列表" }, { "name": "list[].detail_id", "type": "number", "required": true, "description": "收货明细 ID" }, { "name": "list[].receiving_id", "type": "number", "required": true, "description": "收货单 ID" }, { "name": "list[].barcode", "type": "string", "required": true, "description": "商品条码" }, { "name": "list[].product_name", "type": "string", "required": true, "description": "商品名称" }, { "name": "list[].actual_quantity", "type": "number", "required": true, "description": "实收数量" }, { "name": "list[].receiving_status", "type": "string", "required": true, "description": "收货单状态" }, { "name": "list[].stock", "type": "object", "required": true, "description": "商品详情(通过 getStockDetails 获取,含 item_code、item_name、sku_property、barcodes 等缓存字段)" }, { "name": "total", "type": "number", "required": true, "description": "匹配总数" } ], "errors": [ { "code": 0, "message": "用户未绑定仓库" }, { "code": 0, "message": "入库单ID不能为空" }, { "code": 0, "message": "扫描条码不能为空" }, { "code": 0, "message": "入库单不存在或无权访问" }, { "code": 0, "message": "该入库单尚未关联收货单" }, { "code": 0, "message": "未找到可用的收货明细" }, { "code": 0, "message": "未找到匹配的收货明细" }, { "code": 500, "message": "服务器扫描查询失败" } ] }, { "method": "storage.receiving.export", "description": "提交收货单导出任务(仓库维度,异步)。导出为 Excel 文件,包含两个 Sheet:Sheet1=收货单列表(ID/单号/货主/状态/明细匹配状态/入库状态/来货方式/车牌号/快递单号/装卸方式/商品种类/总数量/总箱数/总托盘数/审核状态/创建人/备注/收货时间/创建时间/更新时间),Sheet2=收货单明细(收货单号/收货单ID/明细ID/商品名称/商品条码/系统商品ID/实收数量/箱数/托盘数/收货状态/入库状态/已入库数量/批次号/生产日期/到期日期/备注/创建时间)。筛选和排序规则与 getReceivingList 一致,按当前仓库维度(ctx.user.store_id)过滤。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "where", "type": "object", "required": false, "source": "body", "description": "筛选条件(与 getReceivingList 一致),支持 quickWhere(模糊搜索收货单号/货主名称/快递单号/创建人/车牌号)等字段" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数,支持 sortField(id/receiving_number/status/created_at/updated_at/store_id/warehouse_id)和 sortOrder(ASC/DESC),默认按 created_at DESC" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "导出任务ID,用于轮询进度" }, { "name": "status", "type": "string", "required": true, "description": "任务状态:submitted-已提交 / running-执行中 / success-成功 / failed-失败" }, { "name": "progress", "type": "number", "required": true, "description": "任务进度,0-100" }, { "name": "message", "type": "string", "required": true, "description": "任务状态描述" }, { "name": "result", "type": "object", "required": false, "description": "导出结果(success 时包含 url/cdnUrl/cosUrl/fileKey 等下载地址信息)" }, { "name": "error", "type": "string", "required": false, "description": "错误信息(failed 时返回)" }, { "name": "update_time", "type": "number", "required": true, "description": "状态更新时间戳(毫秒)" } ], "errors": [ { "code": 0, "message": "用户未绑定仓库" } ] }, { "method": "storage.receiving.exportTaskProgress", "description": "查询收货单导出任务进度(仓库维度)。提交导出任务后,通过 task_id 轮询此接口获取实时进度和最终下载地址。任务缓存 TTL 为 30 分钟。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id", "type": "string", "required": false, "source": "body", "description": "导出任务ID(下划线写法),与 taskId 二选一" }, { "name": "taskId", "type": "string", "required": false, "source": "body", "description": "导出任务ID(驼峰写法),与 task_id 二选一" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "导出任务ID" }, { "name": "status", "type": "string", "required": true, "description": "任务状态:submitted-已提交 / running-执行中 / success-成功 / failed-失败 / not_found-任务不存在" }, { "name": "progress", "type": "number", "required": true, "description": "任务进度,0-100" }, { "name": "message", "type": "string", "required": true, "description": "任务状态描述" }, { "name": "result", "type": "object", "required": false, "description": "导出结果(success 时包含 url/cdnUrl/cosUrl/fileKey 等下载地址信息)" }, { "name": "error", "type": "string", "required": false, "description": "错误信息(failed 时返回)" }, { "name": "download_url", "type": "string", "required": false, "description": "Excel 文件下载地址(success 时有效)" }, { "name": "update_time", "type": "number", "required": true, "description": "状态更新时间戳(毫秒)" } ], "errors": [] }, { "method": "storage.receiving.storeExport", "description": "提交货主侧收货单导出任务(货主维度,异步)。以当前平台激活的货主 store_id 为维度导出。导出为 Excel 文件,包含两个 Sheet:Sheet1=收货单列表,Sheet2=收货单明细(字段同 export)。筛选和排序规则与 getStoreReceivingList 一致,需当前用户已切换至货主角色。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "where", "type": "object", "required": false, "source": "body", "description": "筛选条件(与 getStoreReceivingList 一致),支持 quickWhere(模糊搜索收货单号/货主名称/快递单号/创建人/车牌号)等字段" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数,支持 sortField(id/receiving_number/status/created_at/updated_at/store_id/warehouse_id)和 sortOrder(ASC/DESC),默认按 created_at DESC" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "导出任务ID,用于轮询进度" }, { "name": "status", "type": "string", "required": true, "description": "任务状态:submitted-已提交 / running-执行中 / success-成功 / failed-失败" }, { "name": "progress", "type": "number", "required": true, "description": "任务进度,0-100" }, { "name": "message", "type": "string", "required": true, "description": "任务状态描述" }, { "name": "result", "type": "object", "required": false, "description": "导出结果(success 时包含 url/cdnUrl/cosUrl/fileKey 等下载地址信息)" }, { "name": "error", "type": "string", "required": false, "description": "错误信息(failed 时返回)" }, { "name": "update_time", "type": "number", "required": true, "description": "状态更新时间戳(毫秒)" } ], "errors": [ { "code": 0, "message": "未获取到货主平台激活上下文,请先切换至货主角色" } ] }, { "method": "storage.receiving.storeExportTaskProgress", "description": "查询货主侧收货单导出任务进度。复用 exportTaskProgress 的缓存查询逻辑,任务 ID 前缀不同。任务缓存 TTL 为 30 分钟。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id", "type": "string", "required": false, "source": "body", "description": "导出任务ID(下划线写法),与 taskId 二选一" }, { "name": "taskId", "type": "string", "required": false, "source": "body", "description": "导出任务ID(驼峰写法),与 task_id 二选一" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "导出任务ID" }, { "name": "status", "type": "string", "required": true, "description": "任务状态:submitted-已提交 / running-执行中 / success-成功 / failed-失败 / not_found-任务不存在" }, { "name": "progress", "type": "number", "required": true, "description": "任务进度,0-100" }, { "name": "message", "type": "string", "required": true, "description": "任务状态描述" }, { "name": "result", "type": "object", "required": false, "description": "导出结果(success 时包含 url/cdnUrl/cosUrl/fileKey 等下载地址信息)" }, { "name": "error", "type": "string", "required": false, "description": "错误信息(failed 时返回)" }, { "name": "download_url", "type": "string", "required": false, "description": "Excel 文件下载地址(success 时有效)" }, { "name": "update_time", "type": "number", "required": true, "description": "状态更新时间戳(毫秒)" } ], "errors": [] } ] }, { "groupName": "工作台模块", "module": "workbench", "list": [ { "method": "workbench.list", "description": "查询工作台列表(仓库隔离,支持分页与关键词筛选;列表项返回 login_code,不返回 token;工作台条码 barcode 字段已下线)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数,支持 page / pageSize" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "筛选条件,支持 name(模糊)、status(等值)" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "工作台列表", "children": [ { "name": "id", "type": "number", "description": "工作台ID" }, { "name": "warehouse_id", "type": "number", "description": "仓库ID" }, { "name": "name", "type": "string", "description": "工作台名称" }, { "name": "status", "type": "number", "description": "状态:0-禁用 1-启用" }, { "name": "remark", "type": "string", "description": "备注" }, { "name": "login_code", "type": "string", "description": "工作台登录码(前缀 wblc + 随机段共 64 位,创建时自动生成)" }, { "name": "created_at", "type": "string", "description": "创建时间" }, { "name": "updated_at", "type": "string", "description": "更新时间" } ] }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息" } ], "errors": [ { "code": "400", "message": "参数格式错误或缺少仓库上下文" } ] }, { "method": "workbench.detail", "description": "查询单个工作台详情(仓库隔离)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "工作台ID" } ], "response": [ { "name": "data", "type": "object", "required": true, "description": "工作台详情对象" } ], "errors": [ { "code": "400", "description": "工作台ID不能为空" }, { "code": "404", "description": "工作台不存在或无权访问" } ] }, { "method": "workbench.create", "description": "新增工作台(仓库隔离);创建时自动生成 login_code(前缀 wblc + 随机段共 64 位,全局唯一),不接受外部传入 login_code;工作台条码 barcode 字段已下线,不再接收", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "name", "type": "string", "required": true, "source": "body", "description": "工作台名称(必填)" }, { "name": "status", "type": "number", "required": false, "source": "body", "description": "状态:0-禁用 1-启用,默认1" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注" } ], "response": [ { "name": "data", "type": "object", "required": true, "description": "新建的工作台对象(含自动生成的 login_code)" } ], "errors": [ { "code": "400", "message": "工作台名称不能为空" } ] }, { "method": "workbench.update", "description": "更新工作台信息(仓库隔离);login_code / token 不允许编辑,传入 login_code 不予受理;工作台条码 barcode 字段已下线,传入不予受理", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "工作台ID(必填)" }, { "name": "name", "type": "string", "required": false, "source": "body", "description": "工作台名称" }, { "name": "status", "type": "number", "required": false, "source": "body", "description": "状态:0-禁用 1-启用" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注" } ], "response": [ { "name": "data", "type": "object", "required": true, "description": "更新后的工作台对象" } ], "errors": [ { "code": "400", "message": "工作台ID不能为空" }, { "code": "404", "message": "工作台不存在或无权操作" } ] }, { "method": "workbench.delete", "description": "删除工作台(软删除,仓库隔离)", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "工作台ID(必填)" } ], "response": [], "errors": [ { "code": "400", "description": "工作台ID不能为空" }, { "code": "404", "description": "工作台不存在或无权操作" } ] }, { "method": "workbench.business", "description": "工作台业务入口(免登录免鉴权,入参 name + data)。name 支持 queryOrder/query(条码查订单,data 需 barcode+warehouseId)、packOrder(开始打包,凭 key 从后端缓存取订单信息防篡改;不传 key 时旧参数模式过渡兼容;business 旧链路支持传入 users 上报打包人,未上报时自动回填工作台绑定成员)、finishPack(结束打包)、sendWeight(称重);不支持的业务名称报错。以下响应结构为 queryOrder/query(条码查订单)的返回。", "isNeedAuth": false, "isNeedLogin": false, "headers": [], "params": [ { "name": "name", "type": "string", "required": true, "source": "body", "description": "业务名称:queryOrder/query(条码查订单)、packOrder、finishPack、sendWeight" }, { "name": "data", "type": "object", "required": false, "source": "body", "description": "业务数据(透传)。queryOrder/query 需 barcode(运单号,必填)+ warehouseId(仓库ID,必填)" } ], "response": [ { "name": "barcode", "type": "string", "required": true, "description": "条码(运单号)" }, { "name": "waybill_code", "type": "string", "required": true, "description": "运单号" }, { "name": "isSandan", "type": "number", "required": true, "description": "是否散单:1=散单 0=团购(波次类型 wave_type=1 时判定为团购)" }, { "name": "store_remark", "type": "string", "required": true, "description": "货主备注(合约表 store_warehouse.store_remask,无合约或为空时为空字符串)" }, { "name": "express", "type": "object", "required": true, "description": "运单信息:logistics_name(快递公司名称)、weighing_weight(称重重量)、package_material_name(包材名称快照)" }, { "name": "order", "type": "object", "required": true, "description": "订单详情", "children": [ { "name": "id", "type": "number", "description": "订单ID" }, { "name": "delivery_order_code", "type": "string", "description": "发货单号" }, { "name": "order_type", "type": "number", "description": "订单类型" }, { "name": "warehouse_id", "type": "number", "description": "仓库ID" }, { "name": "store_id", "type": "number", "description": "货主ID" }, { "name": "status", "type": "number", "description": "订单状态" }, { "name": "step", "type": "number", "description": "订单步骤" }, { "name": "wave_id", "type": "number", "description": "波次ID" }, { "name": "wave_no", "type": "string", "description": "波次号" }, { "name": "post_status", "type": "string", "description": "过账状态" }, { "name": "pick_status", "type": "string", "description": "拣货状态" }, { "name": "pack_status", "type": "string", "description": "打包状态(原始值):none/padding/fin/error,空值/null 归一化为 none" }, { "name": "intercept_status", "type": "string", "description": "拦截状态(原始值):空值/null 归一化为 none;散单/团购均返回" }, { "name": "recheck_status", "type": "string", "description": "复核状态" }, { "name": "outbound_status", "type": "string", "description": "出库状态" }, { "name": "items_count", "type": "number", "description": "商品件数" }, { "name": "items_total", "type": "number", "description": "商品总数" }, { "name": "items_weight", "type": "number", "description": "商品总重量" }, { "name": "source_platform_code", "type": "string", "description": "来源平台编码" }, { "name": "logistics_name", "type": "string", "description": "快递公司名称" }, { "name": "create_at", "type": "string", "description": "创建时间" }, { "name": "updated_at", "type": "string", "description": "更新时间" }, { "name": "intercept_flag", "type": "number", "description": "拦截标志(仅散单 isSandan=1 返回,团购不返回):拦截状态(intercept_status)不等于 none 时为 1,等于 none 时为 0" }, { "name": "pack_flag", "type": "number", "description": "打包标志(仅散单 isSandan=1 返回,团购不返回):按运单维度判定——该运单号已有打包流水(wms_pack_task.waybill_code 命中,或历史订单级流水 waybill_code 为空兜底)时为 1,否则为 0;主单号/子单号互不影响" } ] }, { "name": "items", "type": "array", "required": true, "description": "订单商品明细,每项含 id/order_id/item_id/item_code/item_name/plan_qty/actual_price/stock_id/order_line_no/inventory_type/sku_property/stock_unit/barcodes/image_url/packing_requirements(打包要求,来自 stock,未命中/异常时为空字符串)" }, { "name": "source_table", "type": "string", "required": true, "description": "订单命中分表:current(待处理表)或 dispatch(配送表)" }, { "name": "batch", "type": "object", "required": false, "description": "波次汇总(仅团购 isSandan=0 返回):wave_id(波次ID)、wave_no(波次号)、wave_type(波次类型,1=团购)、total_orders(波次订单总数)" } ], "errors": [ { "code": "400", "message": "条码不能为空" }, { "code": "400", "message": "仓库ID不能为空" }, { "code": "400", "message": "未找到条码 [xxx] 对应的运单记录" }, { "code": "400", "message": "未在待处理或配送表中找到订单 [id=xxx, warehouse=xxx]" }, { "code": "400", "message": "不支持的业务类型: xxx" } ] }, { "method": "workbench.bindCamera", "description": "工作台绑定/解绑摄像头,校验工作台与摄像头归属后更新 device_ids", "isNeedAuth": true, "isNeedLogin": true, "headers": [], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "工作台ID" }, { "name": "camera_ids", "type": "array", "required": false, "source": "body", "description": "摄像头ID数组,传空数组或 null 表示解绑所有摄像头" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "工作台ID" }, { "name": "name", "type": "string", "required": true, "description": "工作台名称" }, { "name": "device_ids", "type": "array", "required": false, "description": "绑定后的摄像头ID列表" } ], "errors": [ { "code": "400", "message": "工作台ID不能为空" }, { "code": "400", "message": "摄像头 xxx 不存在或无权操作" }, { "code": "404", "message": "工作台不存在或无权操作" } ] }, { "method": "workbench.bind", "description": "工作台绑定(需登录、需权限):入参缓存生成的绑定码 code 与工作台ID id,校验绑定码有效且工作台归属当前仓库后完成关联绑定;成功后在工作台写入随机生成的 64 位 token(若工作台已有 token,删除旧 workbench:token:{旧token} 缓存并写入新 token 缓存),同时更新绑定会话状态为已绑定,供 index.getWorkbenchBindCode 长轮询返回 token", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "code", "type": "string", "required": true, "source": "body", "description": "缓存生成的绑定码(6 位大写字母+数字)" }, { "name": "id", "type": "number", "required": true, "source": "body", "description": "要绑定的工作台ID" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "工作台ID" }, { "name": "workbench_id", "type": "number", "required": true, "description": "工作台ID(同 id)" }, { "name": "token", "type": "string", "required": true, "description": "随机生成的工作台 token(64 位)" } ], "errors": [ { "code": "400", "message": "绑定码格式无效" }, { "code": "400", "message": "工作台ID不能为空或无效" }, { "code": "400", "message": "绑定码不存在或已过期" }, { "code": "404", "message": "工作台不存在或无权操作" } ] }, { "method": "workbench.getWorkbenchInfo", "description": "使用 token 获取工作台信息(免登录、免鉴权):先查缓存 workbench:token:{token}(TTL 300s,缓存值已包含成员列表 members 与当前打包信息 current_wave/current_orders),未命中则按 token 查库并回填缓存后返回工作台信息(不含 token/login_code;工作台条码 barcode 字段已下线);响应 data 含 members 成员数组(wms_workbench_member 未软删除记录,按 id ASC 排序)、current_wave 当前正在打包的团购波次(wms_pack_task 中 pack_mode=2 且 wave_id>0 的最新一条未结束任务组装,含波次订单数 order_count 与商品总件数 items_total,无团购任务时为空对象)与 current_orders 当前正在打包的订单数组(未结束任务(status<2)对应订单,逐单按 current→dispatch 分表补发货单号/订单类型/货主/件数等字段,散单任务(pack_mode=1)另附 items 商品明细(含条码/图片/包装要求/是否需要复核 need_recheck 等,供工作台退出/刷新后恢复任务上下文),团购任务(pack_mode=2)items 为波次商品 SKU 聚合汇总(波次内全部未拦截订单按 SKU 聚合计划数量并合并 stock 详情,15s 短缓存兜底,元素另附 is_wave_summary=true;无进行中任务时为空数组);绑定/移除成员、packOrder/finishPack 打包状态变更后 token 缓存立即失效,下一次调用即返回最新成员与打包信息;打包信息查询异常时降级(current_wave 空对象、current_orders 空数组,单笔商品明细查询异常时 items 降级为空数组),不影响主信息与 members;token 缺失返回失败(flag=failure、code=401,消息「工作台 token 不能为空」)、token 不存在或无对应工作台返回失败(flag=failure、code=403)", "isNeedAuth": false, "isNeedLogin": false, "headers": [], "params": [ { "name": "token", "type": "string", "required": true, "source": "body", "description": "工作台 token(64 位)" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "工作台ID" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "仓库ID" }, { "name": "name", "type": "string", "required": true, "description": "工作台名称" }, { "name": "status", "type": "number", "required": true, "description": "状态:0-禁用 1-启用" }, { "name": "type", "type": "string", "required": true, "description": "工作台类型:personal-个人工作台 group-团体工作台" }, { "name": "remark", "type": "string", "required": false, "description": "备注" }, { "name": "device_ids", "type": "array", "required": false, "description": "设备ID列表" }, { "name": "created_at", "type": "string", "required": true, "description": "创建时间" }, { "name": "updated_at", "type": "string", "required": true, "description": "更新时间" }, { "name": "members", "type": "array", "required": true, "description": "成员列表(wms_workbench_member 未软删除记录,按 id ASC 排序;成员查询失败时降级为空数组)" }, { "name": "members[].id", "type": "number", "required": true, "description": "成员记录ID(对应 wms_workbench_member.id,可用于 workbench.removeMember 的 ids 参数)" }, { "name": "members[].user_id", "type": "number", "required": false, "description": "关联 wms_account.id;可空 null(非系统账号用户)" }, { "name": "members[].user_name", "type": "string", "required": false, "description": "成员名快照;可空 null" }, { "name": "current_wave", "type": "object", "required": true, "description": "当前正在打包的团购波次(wms_pack_task 中 pack_mode=2 且 wave_id>0 的最新一条未结束任务组装,按任务 id 倒序取最新;order_count 波次订单数与 items_total 商品总件数均按 current+dispatch 分表实时统计并带 15s 短缓存;无团购任务或查询异常时为空对象)" }, { "name": "current_wave.task_id", "type": "number", "required": true, "description": "打包任务ID(wms_pack_task.id)" }, { "name": "current_wave.wave_id", "type": "number", "required": true, "description": "波次ID" }, { "name": "current_wave.wave_no", "type": "string", "required": true, "description": "波次号" }, { "name": "current_wave.status", "type": "number", "required": true, "description": "任务状态:0=待处理 1=打包中" }, { "name": "current_wave.order_count", "type": "number", "required": true, "description": "波次订单数(current+dispatch 分表实时计数,15s 短缓存兜底)" }, { "name": "current_wave.items_total", "type": "number", "required": true, "description": "波次商品总件数(口径为商品总件数、非 SKU 品种数:订单分表 wms_order_delivery_{仓库}_{current/dispatch} 的 items_total 列按 wave_id+warehouse_id 求和,15s 短缓存兜底)" }, { "name": "current_wave.operator_text", "type": "string", "required": true, "description": "操作人文本(多人逗号分隔)" }, { "name": "current_wave.start_time", "type": "string", "required": false, "description": "开始打包时间;可空 null" }, { "name": "current_orders", "type": "array", "required": true, "description": "当前正在打包的订单数组(该工作台全部未结束任务(status<2)按任务 id 倒序,逐单按 current→dispatch 分表补发货单号,散单任务另补货主备注(store_remark)与运单信息(express:物流公司/称重重量/包材名称,与 workbench.queryOrder 口径一致);无进行中任务或查询异常时为空数组)" }, { "name": "current_orders[].task_id", "type": "number", "required": true, "description": "打包任务ID(wms_pack_task.id)" }, { "name": "current_orders[].order_id", "type": "number", "required": true, "description": "订单ID" }, { "name": "current_orders[].delivery_order_code", "type": "string", "required": true, "description": "发货单号(分表未命中时为空串)" }, { "name": "current_orders[].wave_id", "type": "number", "required": true, "description": "波次ID" }, { "name": "current_orders[].wave_no", "type": "string", "required": true, "description": "波次号" }, { "name": "current_orders[].pack_mode", "type": "number", "required": true, "description": "打包模式:1=散单 2=团购" }, { "name": "current_orders[].status", "type": "number", "required": true, "description": "任务状态:0=待处理 1=打包中" }, { "name": "current_orders[].pack_quantity", "type": "number", "required": true, "description": "打包数量(件数)" }, { "name": "current_orders[].item_quantity", "type": "number", "required": true, "description": "商品总数量(来自 wms_pack_task.item_quantity)" }, { "name": "current_orders[].sku_count", "type": "number", "required": true, "description": "商品种类数(SKU 数,来自 wms_pack_task.sku_count)" }, { "name": "current_orders[].waybill_code", "type": "string", "required": false, "description": "运单号(来自 wms_pack_task.waybill_code,散单任务创建时未回填则为空串)" }, { "name": "current_orders[].order_type", "type": "string", "required": false, "description": "订单类型(订单分表未命中时为空串)" }, { "name": "current_orders[].store_id", "type": "number", "required": true, "description": "货主ID(订单分表未命中时为 0)" }, { "name": "current_orders[].store_remark", "type": "string", "required": false, "description": "货主备注(合约表 wms_store_warehouse.store_remask;仅散单任务返回,团购为空字符串,与 workbench.queryOrder 的 store_remark 口径一致)" }, { "name": "current_orders[].express", "type": "object", "required": false, "description": "运单信息(仅散单任务返回,团购为 null;与 workbench.queryOrder 的 express 口径一致)" }, { "name": "current_orders[].express.waybill_code", "type": "string", "required": false, "description": "运单号" }, { "name": "current_orders[].express.logistics_name", "type": "string", "required": false, "description": "物流公司名称" }, { "name": "current_orders[].express.weighing_weight", "type": "number", "required": false, "description": "称重重量(克)" }, { "name": "current_orders[].express.package_material_name", "type": "string", "required": false, "description": "包材名称(wms_order_express.package_material_name_snapshot,无包材为空字符串)" }, { "name": "current_orders[].items_count", "type": "number", "required": true, "description": "订单商品品种数(订单分表 items_count,未命中时为 0)" }, { "name": "current_orders[].items_total", "type": "number", "required": true, "description": "订单商品总件数(订单分表 items_total,未命中时为 0)" }, { "name": "current_orders[].items", "type": "array", "required": true, "description": "商品数组:散单任务(pack_mode=1)为单笔订单商品明细(逐项合并 stock 详情(条码/图片/包装要求,走 getStockDetails 缓存));团购任务(pack_mode=2)为波次商品 SKU 聚合汇总(波次内全部未拦截订单按 SKU 聚合计划数量,15s 短缓存兜底,元素另附 is_wave_summary=true);查询异常降级为空数组" }, { "name": "current_orders[].items[].id", "type": "number", "required": true, "description": "订单商品明细ID(wms_order_items 分表 id;团购波次聚合行为 0)" }, { "name": "current_orders[].items[].order_id", "type": "number", "required": false, "description": "订单ID(团购波次聚合行为 0)" }, { "name": "current_orders[].items[].item_id", "type": "number", "required": false, "description": "商品ID" }, { "name": "current_orders[].items[].item_code", "type": "string", "required": true, "description": "商品编码(明细为空时回退 stock.item_code)" }, { "name": "current_orders[].items[].item_name", "type": "string", "required": true, "description": "商品名称(明细为空时回退 stock.item_name)" }, { "name": "current_orders[].items[].plan_qty", "type": "number", "required": false, "description": "计划数量(团购波次聚合行为波次内该 SKU 计划数量合计)" }, { "name": "current_orders[].items[].actual_price", "type": "number", "required": false, "description": "实际价格" }, { "name": "current_orders[].items[].stock_id", "type": "number", "required": true, "description": "库存ID(商品ID)" }, { "name": "current_orders[].items[].order_line_no", "type": "string", "required": true, "description": "订单行号" }, { "name": "current_orders[].items[].inventory_type", "type": "string", "required": true, "description": "库存类型" }, { "name": "current_orders[].items[].sku_property", "type": "string", "required": false, "description": "SKU 属性(来自 stock 详情,无则空串)" }, { "name": "current_orders[].items[].stock_unit", "type": "string", "required": false, "description": "库存单位(来自 stock 详情,无则空串)" }, { "name": "current_orders[].items[].barcodes", "type": "array", "required": false, "description": "条码列表(来自 stock 详情,无则空数组)" }, { "name": "current_orders[].items[].image_url", "type": "array", "required": false, "description": "商品图片地址数组(来自 stock 详情,无则空数组)" }, { "name": "current_orders[].items[].packing_requirements", "type": "string", "required": false, "description": "包装要求(来自 stock 详情,无则空串)" }, { "name": "current_orders[].items[].need_recheck", "type": "string", "required": true, "description": "是否需要复核:Y=需要复核,N=不需要复核(免验)(来自 stock 详情,缺省 Y)" }, { "name": "current_orders[].items[].is_wave_summary", "type": "boolean", "required": false, "description": "是否波次聚合行(仅团购任务 items 元素返回 true,用于区分单笔明细与波次 SKU 汇总)" }, { "name": "current_orders[].operator_text", "type": "string", "required": true, "description": "操作人文本(多人逗号分隔)" }, { "name": "current_orders[].start_time", "type": "string", "required": false, "description": "开始打包时间;可空 null" } ], "errors": [ { "code": "401", "message": "工作台 token 不能为空(返回 flag=failure、code=401)" }, { "code": "403", "message": "工作台不存在或 token 无效(返回 flag=failure、code=403)" } ] }, { "method": "workbench.resetLoginCode", "description": "重置工作台登录码(需登录、需权限):随机生成新的 login_code(前缀 wblc + 随机段共 64 位)并写入数据库,旧 login_code 随即失效;同时同步重置工作台 token:生成新 64 位 hex token 与 login_code 一并持久化到 wms_workbench,更新库前先删除旧 workbench:token:{旧token} 缓存(旧 token 随即失效),并立即回填新 token 信息缓存(复用 buildWorkbenchTokenInfo,含 members/current_wave/current_orders,TTL 300s);旧 token 失效后,使用旧 token 的会话返回 403,设备端需使用响应中新 token 继续工作", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "工作台ID(必填)" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "工作台ID" }, { "name": "login_code", "type": "string", "required": true, "description": "重置后的登录码(前缀 wblc + 随机段共 64 位)" }, { "name": "token", "type": "string", "required": true, "description": "重置后的工作台 token(64 位 hex,必返回;旧 token 已失效,设备端需使用新 token 继续工作)" } ], "errors": [ { "code": "400", "message": "工作台ID不能为空或无效" }, { "code": "404", "message": "工作台不存在或无权操作" }, { "code": "403", "message": "重置完成后旧 token 随即失效:旧 workbench:token:{旧token} 缓存已删除,使用旧 token 的会话请求返回 403,设备端需改用响应中新 token 继续工作" } ] }, { "method": "workbench.removeMember", "description": "移除工作台成员(免登录、免鉴权,以工作台 token 鉴权):入参成员行 ids 与工作台 token,token 优先校验(无 token 返回 401、token 无效返回 403),按 token 解析工作台后仅软删除归属于该工作台的成员行(wms_workbench_member 副表,user_id 可为空兼容非系统账号用户),返回移除数量与行ID列表;移除后该工作台已无任何成员时自动结束其所有未结束的打包任务(wms_pack_task.status<2 置 2 并写 end_time,同步回写订单打包状态与补确认打印状态、写完成操作日志、复位摄像头 OSD、失效 token 缓存,与 finishPack 语义一致),响应附 auto_finished_pack", "isNeedAuth": false, "isNeedLogin": false, "headers": [], "params": [ { "name": "ids", "type": "array|number|string", "required": true, "source": "body", "description": "成员行ID(wms_workbench_member.id),支持数组、单值或逗号分隔字符串" }, { "name": "token", "type": "string", "required": true, "source": "body", "description": "工作台 token(64 位,用于识别操作归属的工作台)" } ], "response": [ { "name": "removed", "type": "number", "required": true, "description": "实际移除的成员行数" }, { "name": "ids", "type": "array", "required": true, "description": "实际移除的成员行ID列表" }, { "name": "auto_finished_pack", "type": "object", "required": false, "description": "成员全部登出后的自动结束打包结果(仅移除后该工作台无成员时才有实际动作;其余情况 finished=0)" }, { "name": "auto_finished_pack.finished", "type": "number", "required": true, "description": "自动结束的打包任务数量" }, { "name": "auto_finished_pack.task_ids", "type": "array", "required": true, "description": "自动结束的打包任务ID列表" } ], "errors": [ { "code": "401", "message": "工作台 token 不能为空(返回 flag=failure、code=401)" }, { "code": "400", "message": "成员行ID不能为空或无效" }, { "code": "403", "message": "工作台不存在或 token 无效(返回 flag=failure、code=403)" }, { "code": "404", "message": "未找到可移除的成员" } ] }, { "method": "workbench.bindMember", "description": "绑定工作台成员(免登录、免鉴权,以工作台 token 鉴权):入参用户ID(可为空,兼容非系统账号用户)+ 姓名(必填)+ 工作台 token,token 优先校验(无 token 返回 401、token 无效返回 403),通过后在 wms_workbench_member 副表新增成员行(user_id 为空时仅存姓名快照),返回新建成员行信息", "isNeedAuth": false, "isNeedLogin": false, "headers": [], "params": [ { "name": "userId", "type": "number|null", "required": false, "source": "body", "description": "用户ID(wms_account.id),非系统账号用户可不传或传 null(兼容 user_id 下划线入参名)" }, { "name": "userName", "type": "string", "required": true, "source": "body", "description": "姓名(必填,非空,trim 后入库;兼容 user_name / name 入参名)" }, { "name": "token", "type": "string", "required": true, "source": "body", "description": "工作台 token(64 位,用于识别归属的工作台)" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "新建成员行ID(wms_workbench_member.id)" }, { "name": "workbench_id", "type": "number", "required": true, "description": "工作台ID" }, { "name": "user_id", "type": "number|null", "required": true, "description": "用户ID,非系统账号用户为 null" }, { "name": "user_name", "type": "string", "required": true, "description": "姓名快照" } ], "errors": [ { "code": "401", "message": "工作台 token 不能为空(返回 flag=failure、code=401)" }, { "code": "400", "message": "姓名不能为空" }, { "code": "400", "message": "用户ID无效" }, { "code": "403", "message": "工作台不存在或 token 无效(返回 flag=failure、code=403)" } ] }, { "method": "workbench.packOrder", "description": "工作台打包上报(免登录、免权限、免鉴权,以工作台 token 鉴权):推荐只传 token + key,订单相关信息(订单号/波次号/运单号)由后端从缓存拉取(前端先经 workbench.queryOrder 扫码拿到 key,20 分钟有效,防篡改);不传 key 时旧参数模式(delivery_order_code 等直传)过渡兼容,后续版本将移除;仓库与工作台均由服务端从 token 解析注入(禁止前端传值);跨仓库/跨工作台消费他人 key 返回 403、key 缺失或过期返回 400(请重新扫码)。打包流程:按发货单号定位订单(current→dispatch 分表),同一工作台存在上一个未结束任务时先关闭(同步回写旧订单打包状态并补确认打印状态,并将工作台绑定摄像头 OSD 复位为「无任务」,新任务 OSD 在其后串行下发避免被复位覆盖),散单去重(传运单号按 order_id+waybill_code、未传按 order_id)、团购按 wave_no 去重后创建打包任务(wms_pack_task,status 归一化为 1=打包中,散单传运单号时 waybill_code 写入流水),写入打包人员(wms_pack_task_packer,自动取该工作台绑定成员 wms_workbench_member)与 operator_text、下发 OSD 到工作台绑定摄像头(散单优先展示打包运单号、团购显示波次号+订单总量,并写 Redis osd_{workbenchId} 缓存)、写操作日志;打包状态变更后主动失效对应工作台 token 缓存,保证 getWorkbenchInfo 尽快返回最新打包信息;团购单(isSandan=0)响应附 batch 波次信息(波次订单数为 current+dispatch 分表实时统计);拦截流程中的订单不允许打包(散单直接拒绝、团购波次静默跳过并视为完成);保留系统日志(systemInit 未声明免日志);成功返回 flag=success、code=200;打包任务落库 wave_scope(波次范围:0=未分配 1=大团购 2=散单 3=小团购 4=单品单件,服务端复查:上报值非法/缺省时兜底订单行值);大团购波次(wave_scope=1)响应附倒计时字段 pack_wait_seconds(大团购打包系数 × 当前波次打包数 ÷ 当前工作台打包人数,单位秒;人数为 0 时任务已被成员全部登出流程自动结束,不会出现,仍按 1 兜底防除零)与 pack_start_time(开始打包时间,毫秒时间戳)供前端倒计时,其他波次两字段均为 0", "isNeedAuth": false, "isNeedLogin": false, "isNeedRight": false, "headers": [], "params": [ { "name": "token", "type": "string", "required": true, "source": "body", "description": "工作台 token(64 位,工作台身份凭证;仓库与工作台由服务端从 token 解析注入)" }, { "name": "key", "type": "string", "required": true, "source": "body", "description": "打包上下文 key(来自 workbench.queryOrder 响应,20 分钟有效;凭 key 由后端从缓存拉取订单号/波次号/运单号,参数后端维护防篡改,跨仓库/跨工作台使用返回 403、过期返回 400)" } ], "response": [ { "name": "task_id", "type": "number", "required": true, "description": "打包任务ID(wms_pack_task.id)" }, { "name": "order_id", "type": "number", "required": true, "description": "订单ID" }, { "name": "delivery_order_code", "type": "string", "required": true, "description": "发货单号" }, { "name": "wave_no", "type": "string", "required": true, "description": "波次号" }, { "name": "isSandan", "type": "number", "required": true, "description": "是否散单:1=散单 0=团购(波次类型 wave_type=1 时判定为团购)" }, { "name": "pack_mode", "type": "number", "required": true, "description": "打包模式:1=散单 2=团购" }, { "name": "status", "type": "number", "required": true, "description": "任务状态:1=打包中 2=已完成" }, { "name": "pack_wait_seconds", "type": "number", "required": true, "description": "大团购倒计时等待秒数(大团购打包系数 big_group_pack_coefficient × 当前波次打包数 ÷ 当前工作台打包人数;仅 wave_scope=1 返回实际值,其他波次为 0)" }, { "name": "pack_start_time", "type": "number", "required": true, "description": "开始打包时间(毫秒时间戳;仅 wave_scope=1 返回实际值,其他波次为 0)" }, { "name": "batch", "type": "object", "required": false, "description": "团购波次信息(仅团购单 isSandan=0 时返回)" }, { "name": "batch.wave_id", "type": "number", "required": true, "description": "波次ID" }, { "name": "batch.wave_no", "type": "string", "required": true, "description": "波次号" }, { "name": "batch.wave_type", "type": "number", "required": true, "description": "波次类型(1=团购)" }, { "name": "batch.total_orders", "type": "number", "required": true, "description": "波次订单总数(current+dispatch 分表实时统计)" } ], "errors": [ { "code": "401", "message": "工作台 token 不能为空(返回 flag=failure、code=401)" }, { "code": "403", "message": "工作台不存在或 token 无效(返回 flag=failure、code=403)" }, { "code": "403", "message": "工作台未绑定有效仓库" }, { "code": "400", "message": "发货单号不能为空" }, { "code": "400", "message": "未找到发货单 [xxx]" }, { "code": "400", "message": "订单已被拦截,无法打包 [xxx](散单)" } ] }, { "method": "workbench.finishPack", "description": "工作台打包完成(免登录、免权限、免鉴权,以工作台 token 鉴权):仓库与工作台均由服务端从 token 解析注入(body 传入 warehouse_id/workbench_id 一律忽略,禁止前端传值);查找该工作台最后一个未结束的打包任务(status<2,按 id 倒序取最新)并结束(写 end_time、status=2,结束时间按仓库配置的散单/团购打包最大时长上限截断),同步回写关联订单打包状态(散单更新单笔、团购批量更新波次下未拦截订单),并补确认打印状态(confirm_print_status 未写入时置 fin,团购按波次补、散单按单补)并写完成操作日志,随后将工作台绑定摄像头 OSD 复位为「无任务」(回写 Redis osd_{workbenchId} 缓存并逐台摄像头下发「无任务」,失败仅告警不阻塞主流程);无未结束任务时返回 finished=false(data 仅 workbench_id/finished/message);打包任务结束后主动失效对应工作台 token 缓存,保证 getWorkbenchInfo 尽快返回最新打包信息;保留系统日志(systemInit 未声明免日志);成功返回 flag=success、code=200", "isNeedAuth": false, "isNeedLogin": false, "isNeedRight": false, "headers": [], "params": [ { "name": "token", "type": "string", "required": true, "source": "body", "description": "工作台 token(64 位,工作台身份凭证;仓库与工作台由服务端从 token 解析注入)" } ], "response": [ { "name": "workbench_id", "type": "number", "required": true, "description": "工作台ID" }, { "name": "finished", "type": "boolean", "required": true, "description": "是否结束打包任务:false=无未结束的打包任务" }, { "name": "task_id", "type": "number", "required": false, "description": "已结束的打包任务ID(wms_pack_task.id,finished=false 时不返回)" }, { "name": "order_id", "type": "number", "required": false, "description": "订单ID(finished=false 时不返回)" }, { "name": "end_time", "type": "string", "required": false, "description": "任务结束时间(按仓库配置的打包最大时长上限截断,finished=false 时不返回)" } ], "errors": [ { "code": "401", "message": "工作台 token 不能为空(返回 flag=failure、code=401)" }, { "code": "403", "message": "工作台不存在或 token 无效(返回 flag=failure、code=403)" }, { "code": "403", "message": "工作台未绑定有效仓库" } ] }, { "method": "workbench.sendWeight", "description": "工作台称重上报(免登录、免权限、免鉴权,以工作台 token 鉴权):仓库由服务端从 token 解析注入(body 传入 warehouse_id/workbench_id 一律忽略,禁止前端传值),入参条码(运单号)+ 重量(单位克,必须为正整数);条码→运单记录(wms_order_express,按 waybill_code+warehouse_id 精确匹配)→ 定位订单分表(current→history→dispatch,序列表定位优先,命中先查对应分表)→ 更新运单称重重量 weighing_weight(DB 统一单位 g):散单(wave_id=0)仅更新该运单;团购波次(wave_type=1)批量更新波次下所有未拦截订单的运单称重重量并返回 total_weight(单件重量×订单数)与 order_count;非团购波次降级为散单逻辑;拦截流程中的订单不允许称重;写称重操作日志(ORDER_WEIGH,团购逐订单批量写);保留系统日志(systemInit 未声明免日志);成功返回 flag=success、code=200;散单称重前置打包校验:开启仓库配置 single_weigh_require_pack 后,散单路径(订单 wave_scope 非 1 大团购/3 小团购)在拦截校验后校验打包状态,pack_status 非 fin 时拒绝称重(业务失败 code=400,提示末尾附 [条码]);团购波次批量称重不校验", "isNeedAuth": false, "isNeedLogin": false, "isNeedRight": false, "headers": [], "params": [ { "name": "token", "type": "string", "required": true, "source": "body", "description": "工作台 token(64 位,工作台身份凭证;仓库由服务端从 token 解析注入)" }, { "name": "barcode", "type": "string", "required": true, "source": "body", "description": "条码(运单号 waybill_code)" }, { "name": "weight", "type": "number|string", "required": true, "source": "body", "description": "称重重量(单位:克,必须为正整数)" } ], "response": [ { "name": "barcode", "type": "string", "required": true, "description": "条码(运单号)" }, { "name": "waybill_code", "type": "string", "required": true, "description": "运单号" }, { "name": "order_id", "type": "number", "required": false, "description": "订单ID(散单 mode=single 返回)" }, { "name": "weighing_weight", "type": "number", "required": true, "description": "称重重量(单位 g)" }, { "name": "items_weight", "type": "number", "required": true, "description": "订单商品重量(单位 g,来自订单分表 items_weight 快照)" }, { "name": "mode", "type": "string", "required": true, "description": "称重模式:single=散单 wave=团购波次" }, { "name": "wave_id", "type": "number", "required": false, "description": "波次ID(团购 mode=wave 返回)" }, { "name": "wave_no", "type": "string", "required": false, "description": "波次号(团购 mode=wave 返回)" }, { "name": "total_weight", "type": "number", "required": false, "description": "波次总重量(单位 g,单件重量×订单数,团购 mode=wave 返回)" }, { "name": "order_count", "type": "number", "required": false, "description": "波次订单数(参与称重的未拦截订单数,团购 mode=wave 返回)" } ], "errors": [ { "code": "401", "message": "工作台 token 不能为空(返回 flag=failure、code=401)" }, { "code": "403", "message": "工作台不存在或 token 无效(返回 flag=failure、code=403)" }, { "code": "403", "message": "工作台未绑定有效仓库" }, { "code": "400", "message": "条码(sn)不能为空" }, { "code": "400", "message": "重量(weight)不能为空" }, { "code": "400", "message": "重量格式非法,必须为正整数(单位 g)" }, { "code": "400", "message": "未找到条码 [xxx] 对应的运单记录" }, { "code": "400", "message": "订单已被拦截,无法称重 [xxx]" }, { "code": 400, "message": "订单未打包(pack_status=padding 打包中时返回「订单打包中」)——开启仓库配置 single_weigh_require_pack 后,wave_scope 非 1 大团购/3 小团购 且 pack_status 非 fin 时拦截;团购波次不校验" } ] }, { "method": "workbench.queryOrder", "description": "工作台条码查询订单(免登录、免权限、免鉴权,以工作台 token 鉴权):仓库与工作台均由服务端从 token 解析注入(body 传入 warehouse_id/workbench_id 一律忽略,禁止前端传值,防止跨仓库查单),入参条码(运单号);条码→运单记录(wms_order_express,按 waybill_code+warehouse_id+status=1 精确匹配)→ 序列表定位优先、未命中按 current→dispatch 回退遍历订单分表 → 组装查询结果(barcode/waybill_code/isSandan/store_remark/express/order/items/source_table);散单(isSandan=1)order 附拦截/打包 0/1 标志 intercept_flag/pack_flag(拦截标志:拦截状态空值归一化为 none,非 none 记 1;打包标志:按运单维度判定,该运单号已有打包流水 wms_pack_task.waybill_code 命中或历史订单级流水 waybill_code 为空兜底时为 1,否则 0,主单号/子单号互不影响);团购(isSandan=0,波次类型 wave_type=1)附 batch 波次信息(wave_id/wave_no/wave_type/total_orders,total_orders 为 current+dispatch 分表实时统计并带 15s 短缓存兜底);items 逐项合并 stock 详情(sku_property/stock_unit/barcodes/image_url/packing_requirements/need_recheck(是否需要复核:Y=需要 N=不需要(免验)));store_remark 来自合约表 store_warehouse.store_remask;只读查询,不涉及缓存失效;保留系统日志(systemInit 未声明免日志);成功返回 flag=success、code=200;查询成功时生成打包上下文 key(wpck 前缀 + 随机段,Redis 缓存 workbench:packctx:{key},TTL 20 分钟,内容含订单号/波次号/运单号/归属仓库与工作台,后端维护防篡改)并在响应返回 key,供 workbench.packOrder 凭 key 打包;order 附 wave_scope(波次范围:0=未分配波次 1=大团购 2=散单 3=小团购 4=单品单件);大团购打包时长闸门:拉取当前工作台进行中的 wave_scope=1 打包任务(status<2,任务已结束则不计)并判断是否已到「大团购打包系数 × 当前波次打包数 ÷ 当前工作台打包人数」秒:未到时仅允许查询本波次订单,其他波次订单返回错误「打包时长不足」,已到时不受限制", "isNeedAuth": false, "isNeedLogin": false, "isNeedRight": false, "headers": [], "params": [ { "name": "token", "type": "string", "required": true, "source": "body", "description": "工作台 token(64 位,工作台身份凭证;仓库与工作台由服务端从 token 解析注入)" }, { "name": "barcode", "type": "string", "required": true, "source": "body", "description": "条码(运单号 waybill_code)" } ], "response": [ { "name": "key", "type": "string", "required": false, "description": "打包上下文 key(20 分钟有效,凭此 key 调用 workbench.packOrder 打包,参数后端维护防篡改;缓存写入失败时缺省)" }, { "name": "barcode", "type": "string", "required": true, "description": "条码(运单号,trim 后返回)" }, { "name": "waybill_code", "type": "string", "required": true, "description": "运单号" }, { "name": "isSandan", "type": "number", "required": true, "description": "是否散单:1=散单 0=团购(波次类型 wave_type=1 时判定为团购)" }, { "name": "store_remark", "type": "string", "required": true, "description": "货主备注(来自合约表 store_warehouse.store_remask,无记录或查询失败时为空串)" }, { "name": "express", "type": "object", "required": true, "description": "运单快照信息(来自 wms_order_express)" }, { "name": "express.logistics_name", "type": "string", "required": false, "description": "物流公司名称;可空 null" }, { "name": "express.weighing_weight", "type": "number|string", "required": false, "description": "运单称重重量(单位 g);未称重时为空" }, { "name": "express.package_material_name", "type": "string", "required": false, "description": "包材名称快照(package_material_name_snapshot,无快照时为空串)" }, { "name": "order", "type": "object", "required": true, "description": "订单信息(来自订单分表 current/dispatch 命中行;散单另附 intercept_flag/pack_flag 0/1 标志,团购原始字段不含该两标志)" }, { "name": "order.id", "type": "number", "required": true, "description": "订单ID" }, { "name": "order.delivery_order_code", "type": "string", "required": true, "description": "发货单号" }, { "name": "order.order_type", "type": "number|string", "required": false, "description": "订单类型" }, { "name": "order.warehouse_id", "type": "number", "required": true, "description": "仓库ID" }, { "name": "order.store_id", "type": "number", "required": false, "description": "货主ID" }, { "name": "order.status", "type": "number|string", "required": false, "description": "订单状态" }, { "name": "order.step", "type": "number|string", "required": false, "description": "订单步骤" }, { "name": "order.wave_id", "type": "number", "required": false, "description": "波次ID(散单为 0)" }, { "name": "order.wave_no", "type": "string", "required": false, "description": "波次号" }, { "name": "order.wave_scope", "type": "number", "required": false, "description": "波次范围:0=未分配波次 1=大团购 2=散单 3=小团购 4=单品单件(来自订单行 wave_scope)" }, { "name": "order.post_status", "type": "string", "required": false, "description": "打单状态" }, { "name": "order.pick_status", "type": "string", "required": false, "description": "拣货状态" }, { "name": "order.pack_status", "type": "string", "required": false, "description": "打包状态(原始值,空值未归一化)" }, { "name": "order.intercept_status", "type": "string", "required": false, "description": "拦截状态(原始值,空值未归一化)" }, { "name": "order.recheck_status", "type": "string", "required": false, "description": "复核状态" }, { "name": "order.outbound_status", "type": "string", "required": false, "description": "出库状态" }, { "name": "order.items_count", "type": "number", "required": false, "description": "SKU 品种数" }, { "name": "order.items_total", "type": "number", "required": false, "description": "商品总件数" }, { "name": "order.items_weight", "type": "number", "required": false, "description": "订单商品重量" }, { "name": "order.source_platform_code", "type": "string", "required": false, "description": "来源平台编码" }, { "name": "order.logistics_name", "type": "string", "required": false, "description": "物流公司名称" }, { "name": "order.create_at", "type": "string", "required": false, "description": "创建时间" }, { "name": "order.updated_at", "type": "string", "required": false, "description": "更新时间" }, { "name": "order.intercept_flag", "type": "number", "required": false, "description": "拦截标志(仅散单 isSandan=1 返回):拦截状态空值归一化为 none,非 none 记 1 否则 0" }, { "name": "order.pack_flag", "type": "number", "required": false, "description": "打包标志(仅散单 isSandan=1 返回):按运单维度判定——该运单号已有打包流水(wms_pack_task.waybill_code 命中,或历史订单级流水 waybill_code 为空兜底)时为 1,否则为 0;主单号/子单号互不影响" }, { "name": "items", "type": "array", "required": true, "description": "订单商品明细数组(按 id ASC,逐项合并 stock 详情;查询异常时为空数组)" }, { "name": "items[].id", "type": "number", "required": true, "description": "订单商品行ID" }, { "name": "items[].order_id", "type": "number", "required": true, "description": "订单ID" }, { "name": "items[].item_id", "type": "number", "required": false, "description": "商品ID" }, { "name": "items[].item_code", "type": "string", "required": false, "description": "商品编码(订单行缺失时取 stock.item_code)" }, { "name": "items[].item_name", "type": "string", "required": false, "description": "商品名称(订单行缺失时取 stock.item_name)" }, { "name": "items[].plan_qty", "type": "number", "required": false, "description": "计划数量" }, { "name": "items[].actual_price", "type": "number", "required": false, "description": "实际单价" }, { "name": "items[].stock_id", "type": "number", "required": false, "description": "库存商品ID" }, { "name": "items[].order_line_no", "type": "string", "required": false, "description": "订单行号" }, { "name": "items[].inventory_type", "type": "string", "required": false, "description": "库存类型" }, { "name": "items[].sku_property", "type": "string", "required": false, "description": "SKU 属性(来自 stock 详情)" }, { "name": "items[].stock_unit", "type": "string", "required": false, "description": "库存单位(来自 stock 详情)" }, { "name": "items[].barcodes", "type": "array", "required": false, "description": "条码列表(来自 stock 详情,无则空数组)" }, { "name": "items[].image_url", "type": "string", "required": false, "description": "商品图片地址(来自 stock 详情)" }, { "name": "items[].packing_requirements", "type": "string", "required": false, "description": "打包要求(来自 stock 详情,trim 后返回)" }, { "name": "items[].need_recheck", "type": "string", "required": true, "description": "是否需要复核:Y=需要复核,N=不需要复核(免验)(来自 stock 详情,缺省 Y)" }, { "name": "source_table", "type": "string", "required": true, "description": "订单所在分表:current=待处理表 dispatch=配送表" }, { "name": "batch", "type": "object", "required": false, "description": "团购波次信息(仅团购单 isSandan=0 时返回,散单不返回)" }, { "name": "batch.wave_id", "type": "number", "required": true, "description": "波次ID" }, { "name": "batch.wave_no", "type": "string", "required": true, "description": "波次号" }, { "name": "batch.wave_type", "type": "number", "required": true, "description": "波次类型(1=团购)" }, { "name": "batch.total_orders", "type": "number", "required": true, "description": "波次订单总数(current+dispatch 分表实时统计,15s 短缓存兜底)" } ], "errors": [ { "code": "401", "message": "工作台 token 不能为空(返回 flag=failure、code=401)" }, { "code": "403", "message": "工作台不存在或 token 无效(返回 flag=failure、code=403)" }, { "code": "403", "message": "工作台未绑定有效仓库" }, { "code": "0", "message": "条码不能为空(业务失败,返回 flag=failure、code=0)" }, { "code": "0", "message": "未找到条码 [xxx] 对应的运单记录(业务失败,返回 flag=failure、code=0)" }, { "code": "0", "message": "未在待处理或配送表中找到订单 [id=xxx, warehouse=xxx](业务失败,返回 flag=failure、code=0)" }, { "code": 0, "message": "打包时长不足(当前工作台大团购波次 wave_scope=1 打包未到时,扫描其他波次订单被限制;本波次订单不受限)" } ] }, { "method": "workbench.getWorkbenchCount", "description": "当前工作台班次打包统计(免登录、免权限、免鉴权,以工作台 token 鉴权):仓库与工作台均由服务端从 token 解析注入;统计窗口为本地时间当日 08:00 至次日 08:00,当前时间早于 08:00 时窗口为昨日 08:00 至今日 08:00;个人工作台(type=personal)统计涉及本人的打包数据(本人=工作台成员 user_id,范围=本工作台产生的任务∪本人作为打包人参与的任务),返回团购波次数量/团购订单数量(团购任务 pack_quantity 求和)/散单数量/团散(团购波次数/散单数,2位小数,散单为0时null)/均件数(本人打包任务按订单数量/人数折算求和,2位小数:本人作为打包人参与的任务按实际打包人数均分、本工作台单人任务整单计入);团体工作台(type=group)统计涉及本工作台的打包数据,返回团购波次数量/团购订单数量(团购任务 pack_quantity 快照求和)/散单数量;统计只查 wms_pack_task/wms_pack_task_packer 并走配套索引(idx_warehouse_create_time/idx_workbench_create_time/uix_pack_task_account),不做订单分表实时统计,避免慢 SQL;成功返回 flag=success、code=200", "isNeedAuth": false, "isNeedLogin": false, "isNeedRight": false, "headers": [], "params": [ { "name": "token", "type": "string", "required": true, "source": "body", "description": "工作台 token(64 位,工作台身份凭证;仓库与工作台由服务端从 token 解析注入)" } ], "response": [ { "name": "workbench_id", "type": "number", "required": true, "description": "工作台ID" }, { "name": "workbench_type", "type": "string", "required": true, "description": "工作台类型:personal-个人工作台 group-团体工作台" }, { "name": "time_range", "type": "object", "required": true, "description": "统计时间窗口" }, { "name": "time_range.start_time", "type": "string", "required": true, "description": "窗口开始时间(本地时间,格式 YYYY-MM-DD HH:mm:ss)" }, { "name": "time_range.end_time", "type": "string", "required": true, "description": "窗口结束时间(本地时间,格式 YYYY-MM-DD HH:mm:ss)" }, { "name": "group_wave_count", "type": "number", "required": true, "description": "团购波次数量(pack_mode=2 且 wave_id>0 按 wave_id 去重)" }, { "name": "single_order_count", "type": "number", "required": true, "description": "散单数量(pack_mode=1 任务数,每任务对应 1 单)" }, { "name": "group_single_ratio", "type": "number", "required": false, "description": "团散(仅个人工作台返回):团购波次数/散单数,保留 2 位小数;散单数为 0 时返回 null" }, { "name": "avg_piece_count", "type": "number", "required": false, "description": "均件数(仅个人工作台返回):本人打包任务按 订单数量/人数 折算后求和,保留 2 位小数;本人作为打包人参与的任务按任务实际打包人数均分(缺省 1),本工作台单人任务整单计入" }, { "name": "group_order_count", "type": "number", "required": false, "description": "团购订单数量(个人/团体工作台均返回):团购任务 pack_quantity 求和(服务端复查口径)" } ], "errors": [ { "code": "401", "message": "工作台 token 不能为空(返回 flag=failure、code=401)" }, { "code": "403", "message": "工作台不存在或 token 无效(返回 flag=failure、code=403)" } ] } ] }, { "groupName": "录像服务器模块", "module": "camera_server", "list": [ { "method": "camera_server.list", "description": "录像服务器列表(仓库隔离,分页+筛选)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数 page/pageSize" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "筛选:name(模糊)、status(等值)" } ], "response": [], "errors": [] }, { "method": "camera_server.detail", "description": "录像服务器详情", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "服务器ID" } ], "response": [], "errors": [ { "code": "404", "description": "不存在或无权访问" } ] }, { "method": "camera_server.create", "description": "新增录像服务器", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "name", "type": "string", "required": true, "source": "body", "description": "服务器名称(必填)" }, { "name": "brand", "type": "string", "required": false, "source": "body", "description": "品牌" }, { "name": "public_ip", "type": "string", "required": false, "source": "body", "description": "公网IP" }, { "name": "internal_ip", "type": "string", "required": false, "source": "body", "description": "内网IP" }, { "name": "port", "type": "number", "required": false, "source": "body", "description": "端口号" }, { "name": "username", "type": "string", "required": false, "source": "body", "description": "账号" }, { "name": "password", "type": "string", "required": false, "source": "body", "description": "密码" }, { "name": "status", "type": "number", "required": false, "source": "body", "description": "0-禁用 1-启用" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注" } ], "response": [], "errors": [ { "code": "400", "description": "名称不能为空" } ] }, { "method": "camera_server.update", "description": "更新录像服务器", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "服务器ID(必填)" }, { "name": "name", "type": "string", "required": false, "source": "body", "description": "名称" }, { "name": "brand", "type": "string", "required": false, "source": "body", "description": "品牌" }, { "name": "public_ip", "type": "string", "required": false, "source": "body", "description": "公网IP" }, { "name": "internal_ip", "type": "string", "required": false, "source": "body", "description": "内网IP" }, { "name": "port", "type": "number", "required": false, "source": "body", "description": "端口号" }, { "name": "username", "type": "string", "required": false, "source": "body", "description": "账号" }, { "name": "password", "type": "string", "required": false, "source": "body", "description": "密码" }, { "name": "status", "type": "number", "required": false, "source": "body", "description": "0-禁用 1-启用" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注" } ], "response": [], "errors": [ { "code": "404", "description": "不存在或无权操作" } ] }, { "method": "camera_server.delete", "description": "删除录像服务器(软删除)", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "服务器ID" } ], "response": [], "errors": [ { "code": "404", "description": "不存在或无权操作" } ] } ] }, { "groupName": "摄像头模块", "module": "camera", "list": [ { "method": "camera.list", "description": "摄像头列表(仓库隔离,分页+筛选)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数 page/pageSize" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "筛选:server_id(等值)、custom_name(模糊)、status(等值)" } ], "response": [], "errors": [] }, { "method": "camera.detail", "description": "摄像头详情", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "摄像头ID" } ], "response": [], "errors": [ { "code": "404", "description": "不存在或无权访问" } ] }, { "method": "camera.create", "description": "新增摄像头", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "server_id", "type": "number", "required": true, "source": "body", "description": "所属服务器ID(必填)" }, { "name": "channel_id", "type": "number", "required": true, "source": "body", "description": "通道编号(必填)" }, { "name": "channel_name", "type": "string", "required": false, "source": "body", "description": "通道名称" }, { "name": "custom_name", "type": "string", "required": false, "source": "body", "description": "自定义名称" }, { "name": "status", "type": "number", "required": false, "source": "body", "description": "0-禁用 1-启用" }, { "name": "username", "type": "string", "required": false, "source": "body", "description": "摄像头登录用户名" }, { "name": "password", "type": "string", "required": false, "source": "body", "description": "摄像头登录密码" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注" } ], "response": [], "errors": [ { "code": "400", "description": "server_id/channel_id 不能为空" } ] }, { "method": "camera.update", "description": "更新摄像头", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "摄像头ID(必填)" }, { "name": "server_id", "type": "number", "required": false, "source": "body", "description": "所属服务器ID" }, { "name": "channel_id", "type": "number", "required": false, "source": "body", "description": "通道编号" }, { "name": "channel_name", "type": "string", "required": false, "source": "body", "description": "通道名称" }, { "name": "custom_name", "type": "string", "required": false, "source": "body", "description": "自定义名称" }, { "name": "status", "type": "number", "required": false, "source": "body", "description": "0-禁用 1-启用" }, { "name": "username", "type": "string", "required": false, "source": "body", "description": "摄像头登录用户名" }, { "name": "password", "type": "string", "required": false, "source": "body", "description": "摄像头登录密码" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注" } ], "response": [], "errors": [ { "code": "404", "description": "不存在或无权操作" } ] }, { "method": "camera.setOsd", "description": "设置摄像头 OSD 文字叠加", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "摄像头ID(必填)" }, { "name": "text", "type": "string", "required": true, "source": "body", "description": "OSD 叠加文字(必填)" }, { "name": "x", "type": "number", "required": false, "source": "body", "description": "X 坐标(-1 到 1,默认 -0.9)" }, { "name": "y", "type": "number", "required": false, "source": "body", "description": "Y 坐标(-1 到 1,默认 0.8)" } ], "response": [], "errors": [ { "code": "400", "description": "摄像头ID/OSD文字不能为空" }, { "code": "404", "description": "摄像头不存在或无权操作" }, { "code": "500", "description": "打印服务调用失败" } ] }, { "method": "camera.delete", "description": "删除摄像头(软删除)", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "摄像头ID" } ], "response": [], "errors": [ { "code": "404", "description": "不存在或无权操作" } ] }, { "method": "camera.ptzControl", "description": "云台方向控制(按下):按指定方向持续转动摄像头,需配对调用 camera.ptzStop 停止", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "摄像头ID(必填)" }, { "name": "action", "type": "string", "required": true, "source": "body", "description": "云台方向(必填,8 个位置):up-上 / down-下 / left-左 / right-右 / upleft-左上 / upright-右上 / downleft-左下 / downright-右下;大小写不敏感,服务端统一转小写校验", "list": [ { "value": "up", "name": "上" }, { "value": "down", "name": "下" }, { "value": "left", "name": "左" }, { "value": "right", "name": "右" }, { "value": "upleft", "name": "左上" }, { "value": "upright", "name": "右上" }, { "value": "downleft", "name": "左下" }, { "value": "downright", "name": "右下" } ] }, { "name": "speed", "type": "number", "required": false, "source": "body", "description": "云台转速(可选,1-7 的整数,默认 4)" } ], "response": [], "errors": [ { "code": "400", "message": "摄像头ID不能为空;云台方向不能为空/不合法;云台转速不是 1-7 的整数;摄像头未配置IP地址" }, { "code": "404", "message": "摄像头不存在或无权操作" }, { "code": "500", "message": "打印服务调用失败" } ], "notes": [ "对接打印服务:POST {printService.url}/camera/ptzControl,请求体 { warehouse_id, cameraId, rtspUrl, action, speed }(warehouse_id 为字符串,与 camera.setOsd 口径一致)", "本接口与 camera.setOsd 同风格:独立端点 + 独立请求体,**不需要也不接收 computerId**(打印服务按 rtspUrl 定位摄像头,无需房间路由)", "action 枚举(8 个位置,与打印服务约定,顺序固定):up-上、down-下、left-左、right-右、upleft-左上、upright-右上、downleft-左下、downright-右下", "交互口径:按下调用本接口(持续转动),松手调用 camera.ptzStop(action 必须与按下时一致);长时间无 stop 指令时摄像头端会持续转动,前端需保证 pointerup/pointerleave 兜底停止", "rtspUrl 由服务端按摄像头记录组装(rtsp://{username}:{password}@{ip}:554/stream{channel_id},与 camera.setOsd 同口径),入参无需传入", "代码:app/service/systemMethods/camera.js#ptzControl(systemInit 已声明 _noNeedRight/_noNeedAuth/_noNeedLog 含 ptzControl)-> app/service/systems/camera.js#ptzControl -> app/lib/ptz_client.js#control" ] }, { "method": "camera.ptzStop", "description": "云台停止(松手):停止转动,action 必须与按下时一致", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "摄像头ID(必填)" }, { "name": "action", "type": "string", "required": true, "source": "body", "description": "云台方向(必填,必须与按下时的 action 一致):up-上 / down-下 / left-左 / right-右 / upleft-左上 / upright-右上 / downleft-左下 / downright-右下", "list": [ { "value": "up", "name": "上" }, { "value": "down", "name": "下" }, { "value": "left", "name": "左" }, { "value": "right", "name": "右" }, { "value": "upleft", "name": "左上" }, { "value": "upright", "name": "右上" }, { "value": "downleft", "name": "左下" }, { "value": "downright", "name": "右下" } ] } ], "response": [], "errors": [ { "code": "400", "message": "摄像头ID不能为空;云台方向不能为空/不合法;摄像头未配置IP地址" }, { "code": "404", "message": "摄像头不存在或无权操作" }, { "code": "500", "message": "打印服务调用失败" } ], "notes": [ "对接打印服务:POST {printService.url}/camera/ptzStop,请求体 { warehouse_id, cameraId, rtspUrl, action }(不带 speed)", "不需要 computerId,与 camera.setOsd / camera.ptzControl 口径一致", "action 必须与 camera.ptzControl 时传入的值一致,否则摄像头可能无法停止", "代码:app/service/systemMethods/camera.js#ptzStop -> app/service/systems/camera.js#ptzStop -> app/lib/ptz_client.js#stop" ] }, { "method": "camera.ptzPresetGoto", "description": "云台预置点跳转:跳转到指定预置点(一次调用即可,无需 stop)", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "摄像头ID(必填)" }, { "name": "presetId", "type": "number", "required": true, "source": "body", "description": "预置点编号(必填,1-256 的整数)" } ], "response": [], "errors": [ { "code": "400", "message": "摄像头ID不能为空;预置点编号不能为空/不是 1-256 的整数;摄像头未配置IP地址" }, { "code": "404", "message": "摄像头不存在或无权操作" }, { "code": "500", "message": "打印服务调用失败" } ], "notes": [ "对接打印服务:POST {printService.url}/camera/ptzPresetGoto,请求体 { warehouse_id, cameraId, rtspUrl, presetId }", "不需要 computerId,与 camera.setOsd / camera.ptzControl 口径一致", "预置点跳转是一次性动作,不需要配对 stop;预置点需提前在摄像头端配置", "代码:app/service/systemMethods/camera.js#ptzPresetGoto -> app/service/systems/camera.js#ptzPresetGoto -> app/lib/ptz_client.js#presetGoto" ] }, { "method": "camera.ptzPresetSet", "description": "云台预置点设置:把摄像头当前机位保存为指定预置点(一次调用即可)", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "摄像头ID(必填)" }, { "name": "presetId", "type": "number", "required": true, "source": "body", "description": "预置点编号(必填,1-256 的整数;已存在的编号会被当前机位覆盖)" } ], "response": [], "errors": [ { "code": "400", "message": "摄像头ID不能为空;预置点编号不能为空/不是 1-256 的整数;摄像头未配置IP地址" }, { "code": "404", "message": "摄像头不存在或无权操作" }, { "code": "500", "message": "打印服务调用失败" } ], "notes": [ "对接打印服务:POST {printService.url}/camera/ptzPresetSet,请求体 { warehouse_id, cameraId, rtspUrl, presetId }(warehouse_id 为字符串,与 camera.setOsd 口径一致)", "不需要 computerId,与 camera.setOsd / camera.ptzControl 口径一致", "语义:把摄像头**当前机位**保存为该 presetId 的预置点(同一编号重复设置即覆盖);常用于「先 ptzControl 转到目标位置 → 再 ptzPresetSet 存点 → 以后用 camera.ptzPresetGoto 一键回到该机位」", "与 camera.ptzPresetGoto 的区别:ptzPresetSet 写(存点)、ptzPresetGoto 读(跳转);两者均是一次性动作,无需配对 stop", "代码:app/service/systemMethods/camera.js#ptzPresetSet -> app/service/systems/camera.js#ptzPresetSet -> app/lib/ptz_client.js#presetSet" ] } ] }, { "groupName": "商品流水模块", "module": "stock.transaction", "list": [ { "method": "stock.transaction.export", "description": "提交商品出入库流水导出异步任务(仓库侧)。与 stock.transaction.list 使用相同查询条件,立即返回任务受理信息,不直接返回文件。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "where", "type": "object", "required": false, "source": "body", "description": "查询条件对象。支持字段:start_time(开始时间)、end_time(结束时间)、store_ids(货主ID数组)、stock_ids(商品库存ID数组)、transaction_type(流水类型 INBOUND/OUTBOUND/LOCK/UNLOCK)、order_type(单据类型)、order_no(单据号,模糊匹配)、batch_no(批次号)、entry_order_id(入库单ID)、receiving_id(收货单ID)、order_id(发货单ID)。仓库范围自动取自 ctx.user.store_id。" }, { "name": "where.start_time", "type": "string", "required": false, "source": "body", "description": "开始时间" }, { "name": "where.end_time", "type": "string", "required": false, "source": "body", "description": "结束时间" }, { "name": "where.store_ids", "type": "array", "required": false, "source": "body", "description": "货主ID数组" }, { "name": "where.stock_ids", "type": "array", "required": false, "source": "body", "description": "商品库存ID数组" }, { "name": "where.transaction_type", "type": "string", "required": false, "source": "body", "description": "流水类型:INBOUND/OUTBOUND/LOCK/UNLOCK" }, { "name": "where.order_type", "type": "string", "required": false, "source": "body", "description": "单据类型" }, { "name": "where.order_no", "type": "string", "required": false, "source": "body", "description": "单据号(模糊匹配)" }, { "name": "where.batch_no", "type": "string", "required": false, "source": "body", "description": "批次号" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数。sortField 白名单:created_at/quantity/stock_id/store_id/warehouse_id;sortOrder 支持 ASC/DESC" }, { "name": "sort.sortField", "type": "string", "required": false, "source": "body.sort", "description": "排序字段" }, { "name": "sort.sort_field", "type": "string", "required": false, "source": "body.sort", "description": "排序字段下划线别名" }, { "name": "sort.sortOrder", "type": "string", "required": false, "source": "body.sort", "description": "排序方向" }, { "name": "sort.sort_order", "type": "string", "required": false, "source": "body.sort", "description": "排序方向下划线别名" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "导出任务ID" }, { "name": "status", "type": "string", "required": true, "description": "任务状态:submitted" }, { "name": "progress", "type": "number", "required": true, "description": "进度:0" }, { "name": "message", "type": "string", "required": true, "description": "受理消息" }, { "name": "update_time", "type": "number", "required": true, "description": "更新时间戳" } ], "errors": [] }, { "method": "stock.transaction.exportStore", "description": "提交商品出入库流水导出异步任务(货主侧)。与 stock.transaction.storeList 使用相同查询条件,需传 store_id,立即返回任务受理信息。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "store_id", "type": "number", "required": true, "source": "body", "description": "货主ID" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "查询条件对象。支持字段:start_time、end_time、warehouse_ids(仓库ID数组)、stock_ids(商品库存ID数组)、transaction_type、order_type、order_no、batch_no、entry_order_id、receiving_id、order_id。兼容 warehouse_id 单数。" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数。sortField 白名单:created_at/quantity/stock_id/store_id/warehouse_id" }, { "name": "sort.sortField", "type": "string", "required": false, "source": "body.sort", "description": "排序字段" }, { "name": "sort.sort_field", "type": "string", "required": false, "source": "body.sort", "description": "排序字段下划线别名" }, { "name": "sort.sortOrder", "type": "string", "required": false, "source": "body.sort", "description": "排序方向" }, { "name": "sort.sort_order", "type": "string", "required": false, "source": "body.sort", "description": "排序方向下划线别名" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "导出任务ID" }, { "name": "status", "type": "string", "required": true, "description": "任务状态:submitted" }, { "name": "progress", "type": "number", "required": true, "description": "进度:0" }, { "name": "message", "type": "string", "required": true, "description": "受理消息" }, { "name": "update_time", "type": "number", "required": true, "description": "更新时间戳" } ], "errors": [] }, { "method": "stock.transaction.exportTaskProgress", "description": "根据 task_id 查询商品流水导出任务进度与结果。status 可能值:submitted/running/success/failed/not_found。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id", "type": "string", "required": false, "source": "body", "description": "导出任务ID(下划线写法)" }, { "name": "taskId", "type": "string", "required": false, "source": "body", "description": "导出任务ID(驼峰写法)" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务ID" }, { "name": "status", "type": "string", "required": true, "description": "任务状态:submitted/running/success/failed/not_found" }, { "name": "progress", "type": "number", "required": true, "description": "进度百分比(0-100)" }, { "name": "message", "type": "string", "required": true, "description": "状态说明" }, { "name": "error", "type": "string", "required": true, "description": "失败时错误信息" }, { "name": "download_url", "type": "string", "required": true, "description": "成功后下载链接" }, { "name": "update_time", "type": "number", "required": true, "description": "更新时间戳" } ], "errors": [] } ] }, { "groupName": "库存盘点模块", "module": "stock.check", "list": [ { "method": "stock.check.create", "description": "创建盘点任务(空任务):生成盘点单号(PD+YYYYMMDD+6位序号,序号全局递增(不按仓库隔离),并发下撞 uk_check_no 唯一键自动重取重试(最多 5 次),口径与收货单 receiving_number 一致),初始状态 created、明细进度 none_checked;warehouse_id 由服务端从当前登录上下文(ctx.user.store_id)自动注入,前端无需传递。盘点范围类型语义:all=按库位盘点(添加明细时未传库位自动拉取全仓库启用库位生成范围)/ location=按库位盘点 / store=按货主按商品盘点(必须指定货主)/ goods=按商品盘点;type=all/location 时明细为库位行(scope_type=location),type=store/goods 时明细为商品行(scope_type=goods)。盘点时间不传(主表已无 check_date):start_time=盘点开始时间(第一个盘点明细写入的时间,report 首次写入明细时补写)、end_time=盘点结束时间(完成盘点的时间,finish 时写入),与 patternCreate 口径一致。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(正常登录 token,携带仓库上下文)" } ], "params": [ { "name": "title", "type": "string", "required": false, "source": "body", "description": "盘点名称/主题(非必填)" }, { "name": "type", "type": "string", "required": false, "source": "body", "description": "盘点范围类型,缺省 all:all=按库位盘点(未传库位时自动全仓库启用库位生成盘点范围)/ location=按库位盘点 / store=按货主按商品盘点 / goods=按商品盘点;all/location 走库位明细行(scope_type=location),store/goods 走商品明细行(scope_type=goods)" }, { "name": "mode", "type": "string", "required": false, "source": "body", "description": "盘点方式,缺省 open:open=明盘(可见账面数量)/ blind=盲盘(不可见账面数量);按库位盘点(all/location)一律盲盘,忽略前端传入;按商品盘点(store/goods)按传入值(默认明盘)" }, { "name": "store_id", "type": "number", "required": false, "source": "body", "description": "货主ID(type=store 按货主按商品盘点时必填;添加商品明细时商品货主必须与该货主一致)" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记:success=成功 / failure=失败" }, { "name": "code", "type": "number", "required": true, "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { "name": "message", "type": "string", "required": true, "description": "提示信息:成功为 ok;失败为具体错误文案" }, { "name": "data", "type": "object", "required": true, "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", "children": [ { "name": "id", "type": "number", "required": true, "description": "盘点任务ID" }, { "name": "check_no", "type": "string", "required": true, "description": "盘点单号(PD+YYYYMMDD+6位序号)" }, { "name": "title", "type": "string", "required": true, "description": "盘点名称/主题" }, { "name": "type", "type": "string", "required": true, "description": "盘点范围类型:all/store/goods/location" }, { "name": "mode", "type": "string", "required": true, "description": "盘点方式:open/blind" }, { "name": "store_id", "type": "number", "required": false, "description": "货主ID(按货主盘点时有值)" }, { "name": "status", "type": "string", "required": true, "description": "主表状态(新建为 created)" }, { "name": "detail_status", "type": "string", "required": true, "description": "明细盘点进度:none_checked/partial_checked/all_checked(新建为 none_checked)" }, { "name": "start_time", "type": "string", "required": false, "description": "盘点开始时间(第一个盘点明细写入的时间,创建时为空)" }, { "name": "end_time", "type": "string", "required": false, "description": "盘点结束时间(完成盘点的时间,创建时为空)" }, { "name": "creator_id", "type": "number", "required": true, "description": "创建人账户ID" }, { "name": "creator_name", "type": "string", "required": true, "description": "创建人名称快照" }, { "name": "total_items", "type": "number", "required": true, "description": "明细行数" }, { "name": "checked_items", "type": "number", "required": true, "description": "已盘行数" }, { "name": "diff_items", "type": "number", "required": true, "description": "差异行数" }, { "name": "remark", "type": "string", "required": true, "description": "备注" }, { "name": "created_at", "type": "string", "required": false, "description": "创建时间" }, { "name": "updated_at", "type": "string", "required": false, "description": "更新时间" } ] }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": 400, "message": "无法获取当前仓库上下文 / 盘点范围类型不合法(仅支持 all/store/goods/location)/ 盘点方式不合法(仅支持 open/blind)/ 按货主盘点时必须指定货主" }, { "code": 500, "message": "服务器内部错误" } ], "notes": [ "代码依据:app/service/systems/stock_check.js#generateCheckNo 移除 warehouse_id 隔离条件,改为查询全局最大 PD+YYYYMMDD 前缀单号并取末尾 6 位序号 +1(不按仓库隔离);新增 isCheckNoDuplicateError()(parent.code === 'ER_DUP_ENTRY' 且 sqlMessage 命中 uk_check_no/check_no,参照收货单 isReceivingNumberDuplicateError 口径);create() 创建撞唯一键时自动重取单号重试,最多 5 次(maxCreateRetries=5,与收货单 create 重试口径一致);超过重试次数或非单号冲突错误原样抛出。", "原因说明:uk_check_no 为全局唯一索引(不区分仓库),原按仓库隔离序号各自从 1 起会跨仓撞号;改为全局递增后并发创建仍有极小概率撞号,由唯一键重试兜底。", "收货单参照口径:与收货单 receiving_number 一致——按全局最大序号 +1 生成 + 撞唯一键自动重取重试。", "并发重试说明:每次重试都重新调用 generateCheckNo() 取最新全局最大序号;仅 ER_DUP_ENTRY 且命中 uk_check_no 的错误才重试,其它错误不重试直接抛出。", "范围类型语义:type=all/location 为按库位盘点(明细为库位行 scope_type=location,all 未传库位时自动全仓库启用库位生成范围);type=store/goods 为按商品盘点(明细为商品行 scope_type=goods,store 必须指定货主)。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 stock.check.create/addDetail/report/detail/finish/export 六条(范围类型语义与库位行支持);根版本 0.3.205 → 0.3.206、updatedAt 保持 2026-09-30;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta);本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 后,同步回填开发库与生产库(import 当前 system.json → export 回写往返校验),保持库与文件一致。", "盘点方式规则:按库位盘点(type=all/location,明细为库位行)一律盲盘(blind),忽略前端传入的 mode;按商品盘点(type=store/goods,明细为商品行)按传入值,默认明盘(open)。代码依据:app/service/systems/stock_check.js#create 在 mode 合法性校验(仅支持 open/blind)通过后、写库前,normalizedType 为 all/location 时强制 normalizedMode='blind'。", "盘点时间口径(主表无 check_date):create 不写盘点时间(入参与主表均无 check_date,迁移 20260930150000-remove-check-date-from-wms-stock-check.js 已移除字段与索引);start_time=盘点开始时间(第一个盘点明细写入的时间,report 首次写入明细时补写)、end_time=盘点结束时间(完成盘点的时间,finish 时写入);_formatCheckRow 不再返回 check_date(仅返回 start_time/end_time);代码依据:app/service/systems/stock_check.js#create(不再写 check_date)、#report(start_time 为空补写)、#finish(写 end_time)、#_formatCheckRow(仅返回 start_time/end_time)。", "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。" ] }, { "method": "stock.check.list", "description": "拉取盘点任务列表:按当前用户仓库(ctx.user.store_id)限定数据范围,支持 status 状态筛选(单值或数组)、type 范围类型筛选(单值或数组)、mode 盘点方式筛选(单值或数组)、store_id 货主筛选、created_at 创建时间筛选、start_time 盘点开始时间筛选、end_time 盘点结束时间筛选(时间条件:单值=该字段 >= 该值,数组 [from,to]=between 区间)、keyword 关键字(盘点单号/标题模糊)与分页。 每行返回新增 store_name 货主名称(优先合约货主备注 store_remask、兜底公司全称 company_name,详见 response.rows)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(正常登录 token,携带仓库上下文)" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数 { page, pageSize },默认 page=1、pageSize=20,pageSize 上限 200" }, { "name": "where.status", "type": "string", "required": false, "source": "body", "description": "状态筛选(单值或数组,自动去重):created/submitted/rejected/approved/checking/completed/cancelled" }, { "name": "where.type", "type": "string", "required": false, "source": "body", "description": "盘点范围类型筛选(单值或数组,自动去重):all=按库位盘点 / location=按库位盘点 / store=按货主按商品盘点 / goods=按商品盘点" }, { "name": "where.mode", "type": "string", "required": false, "source": "body", "description": "盘点方式筛选(单值或数组,自动去重):open=明盘(可见账面数量)/ blind=盲盘(不可见账面数量)" }, { "name": "where.store_id", "type": "number", "required": false, "source": "body", "description": "货主筛选" }, { "name": "where.created_at", "type": "string", "required": false, "source": "body", "description": "创建时间筛选:单值=created_at >= 该值(从该值起);数组 [from,to]=between 闭区间(from <= created_at <= to,仅传 from=gte、仅传 to=lte);非法时间值静默忽略(不加入筛选条件)" }, { "name": "where.start_time", "type": "string", "required": false, "source": "body", "description": "盘点开始时间筛选(start_time,第一个盘点明细写入的时间),口径同 created_at:单值=start_time >= 该值(从该值起);数组 [from,to]=between 闭区间;非法时间值静默忽略" }, { "name": "where.end_time", "type": "string", "required": false, "source": "body", "description": "盘点结束时间筛选(end_time,完成盘点的时间),口径同 created_at:单值=end_time >= 该值(从该值起);数组 [from,to]=between 闭区间;非法时间值静默忽略" }, { "name": "where.keyword", "type": "string", "required": false, "source": "body", "description": "关键字,对盘点单号(check_no)/标题(title)模糊匹配" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记:success=成功 / failure=失败" }, { "name": "code", "type": "number", "required": true, "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { "name": "message", "type": "string", "required": true, "description": "提示信息:成功为 ok;失败为具体错误文案" }, { "name": "data", "type": "object", "required": true, "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", "children": [ { "name": "rows", "type": "array", "required": true, "description": "盘点任务行列表(主表全字段,含 check_no/title/type/mode/store_id/status/detail_status/start_time/end_time/creator_id/creator_name/total_items/checked_items/diff_items/remark/created_at/updated_at,每行新增 store_name 货主名称;start_time=盘点开始时间(第一个盘点明细写入的时间)、end_time=盘点结束时间(完成盘点的时间));store_name=货主名称:优先 wms_store_warehouse.store_remask(合约货主备注,按 store_id+warehouse_id 匹配);无合约或备注为空时回退 wms_store.company_name(公司全称);两者均查不到返回空字符串" }, { "name": "total", "type": "number", "required": true, "description": "总条数" }, { "name": "page", "type": "number", "required": true, "description": "当前页码" }, { "name": "pageSize", "type": "number", "required": true, "description": "每页条数" } ] }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": 500, "message": "服务器内部错误" } ], "notes": [ "store_name 代码依据:app/service/systems/stock_check.js#list 返回 rows 前调用 _resolveStoreNameMap()(按 store_id+warehouse_id 查 wms_store_warehouse.store_remask,无合约或备注为空回退 wms_store.company_name),每行新增 store_name 货主名称,查不到返回空字符串;未改动任何业务逻辑。", "代码依据:app/service/systems/stock_check.js#list——新增 type/mode 枚举筛选(_normalizeEnumValues 归一化 trim 去重,单值 eq、多值 Op.in)、store_id 数值 eq、created_at/start_time/end_time 时间筛选(_buildTimeRangeCondition:数组 [from,to] 两端合法=Op.between、仅 from=Op.gte、仅 to=Op.lte,单值=Op.gte,非法时间值返回 null 静默忽略);app/service/systemMethods/stock/check.js#list——经 prepareWhereContext 提取 where(支持 {operator,value} 标准结构,between 对象值归一为 [from,to])后传给 systems 层,并保留 data 顶层字段兜底(whereValue 优先、data 顶层兼容)。", "修复点:原方法层 list 未从 where 提取 type(方法层解构仅有 status/store_id/keyword,where.type 传入不生效);本次方法层补齐 type/mode/created_at/start_time/end_time 提取,status/keyword 已有逻辑不变。", "筛选口径:status/type/mode 支持单值 eq 或数组 in(归一化 trim 后自动去重,空值忽略);store_id 经 Number 归一化后 eq;keyword 对盘点单号 check_no 与标题 title 做 OR 模糊匹配;所有筛选均叠加在 warehouse_id(ctx.user.store_id 仓库隔离)之上。", "时间范围语义:created_at/start_time/end_time 三列口径一致——单值=该字段 >= 该值(从该值起);数组 [from,to] 两端都合法=between 闭区间,仅 from 合法=gte、仅 to 合法=lte;空值/无法解析的日期静默忽略(不加入 where 条件)。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 后,同步回填开发库与生产库(import 当前 system.json → export 回写往返校验),保持库与文件一致;stock.check 分组共 18 条 method 无损。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.list 一条(response.rows 描述新增 store_name 货主名称与解析口径,description/notes 同步;params/errors/headers/鉴权不变);根版本 0.3.219 → 0.3.220、updatedAt 保持 2026-10-01;methods/changes/system.json 新增本条(插入数组首位);其余 17 条 method 未改动。", "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。" ] }, { "method": "stock.check.addDetail", "description": "添加盘点明细(商品或库位,按任务盘点类型决定):type=store/goods 按 stock_ids 添加商品行(scope_type=goods,商品任务必须按库位盘点:按商品在仓库的启用库存库位(wms_storage is_enabled=1,按 space_id 分组 SUM)拆行——每个「商品+库位」生成一条明细行,location_id/location_code 快照绑定库存库位、system_quantity=该库位库存 SUM,一个商品多个库位对应多行;无启用库存库位的商品计入 invalid_stock_ids 不入明细),商品必须属于本仓库,且任务 store_id 非空时商品货主必须与任务货主一致(不一致的商品记入 invalid_stock_ids);type=all/location 按 locations(库位编码)或 location_ids(库位ID)添加库位行(scope_type=location),location_ids 优先(两者都传时 locations 忽略)——库位ID路径直接按 wms_location_space.id+warehouse_id 查库校验(不再按编码二次解析),查不到的 ID 记入 invalid_location_ids,编码路径按 warehouse_id+space_code 匹配 wms_location_space,不存在的编码记入 invalid_locations;type=all 未传库位且未传库位ID时自动拉取全仓库启用库位生成盘点范围;兼容历史任务:type=all 且已存在商品明细行(scope_type=goods,改造前创建)时继续按商品模式接受 stock_ids,避免旧调用报 400;stock_ids 与 locations/location_ids 按任务类型二选一(传错维度报 400:按库位盘点传 stock_ids 报『当前盘点类型按库位盘点,请传 locations 或 location_ids(如需按商品盘点请创建 type=goods 任务)』,按商品盘点传 locations 报『当前盘点类型按商品盘点,请传 stock_ids』、传 location_ids 报『当前盘点类型按商品盘点,不能添加库位明细』),locations 兼容 location_codes 写法(locations 优先)、location_ids 兼容 locationIds 驼峰写法(location_ids 优先);仅 created/rejected 状态允许;已存在同盘点项(商品行 stock_id / 库位行 location_code)自动跳过(幂等);完成后重算主表 total_items。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(正常登录 token,携带仓库上下文)" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "盘点任务ID" }, { "name": "stock_ids", "type": "array", "required": false, "source": "body", "description": "商品库存ID列表(wms_stock_warehouse.id);type=store/goods 按商品盘点时使用,与 locations/location_ids 按任务类型二选一;每个商品按其启用库存库位(wms_storage is_enabled=1,按 space_id 分组)拆分为多行,无启用库存库位的商品记入 invalid_stock_ids" }, { "name": "locations", "type": "array", "required": false, "source": "body", "description": "库位编码列表(wms_location_space.space_code);type=all/location 按库位盘点时使用,与 stock_ids 按任务类型二选一;与 location_ids 同时传入时被忽略(location_ids 优先);type=all 未传库位且未传 location_ids 时自动拉取全仓库启用库位生成盘点范围" }, { "name": "location_codes", "type": "array", "required": false, "source": "body", "description": "库位编码列表(兼容别名;locations 优先,两者都传时以 locations 为准)" }, { "name": "location_ids", "type": "array", "required": false, "source": "body", "description": "库位ID列表(wms_location_space.id);type=all/location 按库位盘点时使用,直接按 id+warehouse_id 查库校验(不再按编码二次解析),查不到的 ID 记入 invalid_location_ids(不报错);与 locations 同时传入时 location_ids 优先、locations 忽略;兼容 locationIds 驼峰写法(location_ids 优先)" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记:success=成功 / failure=失败" }, { "name": "code", "type": "number", "required": true, "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { "name": "message", "type": "string", "required": true, "description": "提示信息:成功为 ok;失败为具体错误文案" }, { "name": "data", "type": "object", "required": true, "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", "children": [ { "name": "added", "type": "number", "required": true, "description": "本次新增明细数(商品路径为按「商品+库位」拆行后的明细行数)" }, { "name": "skipped", "type": "number", "required": true, "description": "已存在被跳过(幂等)的盘点项数" }, { "name": "invalid_stock_ids", "type": "array", "required": true, "description": "无效商品库存ID列表(不存在、不属于当前仓库、商品货主与任务货主不一致或在仓库无启用库存库位)" }, { "name": "invalid_locations", "type": "array", "required": true, "description": "无效库位编码列表(当前仓库不存在对应库位编码)" }, { "name": "invalid_location_ids", "type": "array", "required": true, "description": "无效库位ID列表(按 wms_location_space.id 直查当前仓库不存在)" }, { "name": "total_items", "type": "number", "required": true, "description": "重算后的明细总行数" } ] }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": 400, "message": "盘点任务ID不能为空 / 盘点任务不存在 / 当前状态(非 created/rejected)不允许添加明细 / 请至少选择一个商品 / 当前盘点类型按商品盘点,请传 stock_ids / 当前盘点类型按商品盘点,不能添加库位明细 / 当前盘点类型按库位盘点,请传 locations 或 location_ids(如需按商品盘点请创建 type=goods 任务) / 请至少选择一个库位 / 当前仓库没有启用库位,无法按全盘自动生成盘点范围" }, { "code": 500, "message": "服务器内部错误" } ], "notes": [ "按类型二选一:type=store/goods 传 stock_ids(传 locations 报『当前盘点类型按商品盘点,请传 stock_ids』、传 location_ids 报『当前盘点类型按商品盘点,不能添加库位明细』);type=all/location 传 locations 或 location_ids(传 stock_ids 报『当前盘点类型按库位盘点,请传 locations 或 location_ids(如需按商品盘点请创建 type=goods 任务)』)。", "location_ids 优先:两者都传时忽略 locations,直接按 wms_location_space.id+warehouse_id 查库校验(不再按 space_code 二次解析),查不到的 ID 记入 invalid_location_ids(不报错)。", "历史任务兼容:改造前创建的 type=all 任务按商品添加明细(明细行 scope_type='goods');判定口径为该任务在 wms_stock_check_detail 中 scope_type='goods' 行存在(count>0)即继续按商品模式接受 stock_ids(此时传 locations/location_ids 分别报『当前盘点类型按商品盘点,请传 stock_ids』/『当前盘点类型按商品盘点,不能添加库位明细』);全新 type=all 任务(无任何商品明细行)维持按库位语义,只能传 locations/location_ids。仅 type=all 走兼容判定,store/goods/location 类型判定不变。", "商品货主限制:任务 store_id 非空时商品 store_id 必须与之一致,不一致计入 invalid_stock_ids(限制非本货主商品加入盘点)。", "全盘自动范围:type=all 且未传库位且未传 location_ids 时,自动拉取当前仓库全部启用库位(is_enabled=true)的 space_code 生成库位行;无启用库位时报 400。", "幂等:商品行按 check_id+stock_id 整体跳过(同商品重复添加整体跳过,不重复拆行)、库位行按 check_id+location_code 跳过(商品行唯一索引 uk_check_stock_location(check_id, stock_id, location_id),库位行原唯一约束 uk_check_location 已放宽为普通索引 idx_check_location、幂等由应用层查重保证);location_ids 路径跳过项按库位ID记入 skipped。", "商品拆行口径(本次改造,商品任务必须按库位盘点):type=store/goods 传 stock_ids 后按商品在仓库的启用库存库位(wms_storage is_enabled=1,按 space_id 分组 SUM(available_quantity+locked_quantity)(=可用+锁定))拆行——每个「商品+库位」生成一条 scope_type=goods 明细行(location_id/location_code 快照绑定库存库位、system_quantity=该库位库存 SUM(可用+锁定));一个商品多个库位对应多行;无启用库存库位的商品计入 invalid_stock_ids 不入明细;added/total_items 均为拆分明细行数。代码依据:app/service/systems/stock_check.js#_addGoodsDetailRows(Storage.findAll warehouse_id+stock_id in+is_enabled=1、attributes SUM(quantity)、group=[stock_id, space_id];LocationSpace 按 id 取 space_code 快照)。", "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。" ] }, { "method": "stock.check.detailDelete", "description": "批量删除盘点明细:入参 id(盘点任务ID)+ detail_ids(盘点明细ID数组,单次上限 200;兼容 detailIds 驼峰写法与旧版 detail_id 单值写法,单值自动转数组,优先级 detail_ids > detailIds > detail_id);仅主表状态 created/rejected 允许删除;未命中(明细不存在或不属于当前仓库)的明细ID计入 skipped_ids 不报错;命中明细批量删除并对 wms_stock_check_record 防御性清理作业记录(正常流程该状态不应有记录);删除后重算主表 total_items,返回 { deleted_count, deleted_ids, skipped_ids, total_items }。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(正常登录 token,携带仓库上下文)" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "盘点任务ID" }, { "name": "detail_ids", "type": "array", "required": true, "source": "body", "description": "盘点明细ID数组(单次上限 200;兼容 detailIds 驼峰写法与旧版 detail_id 单值写法,单值自动转数组;优先级 detail_ids > detailIds > detail_id)" }, { "name": "detailIds", "type": "array", "required": false, "source": "body", "description": "盘点明细ID数组(驼峰别名,兼容写法,单值自动转数组;detail_ids 优先)" }, { "name": "detail_id", "type": "number", "required": false, "source": "body", "description": "盘点明细ID(旧版单值写法,自动转数组;detail_ids/detailIds 优先)" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记:success=成功 / failure=失败" }, { "name": "code", "type": "number", "required": true, "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { "name": "message", "type": "string", "required": true, "description": "提示信息:成功为 ok;失败为具体错误文案" }, { "name": "data", "type": "object", "required": true, "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", "children": [ { "name": "deleted_count", "type": "number", "required": true, "description": "实际删除的明细数量" }, { "name": "deleted_ids", "type": "array", "required": true, "description": "实际删除的明细ID列表(保持入参顺序)" }, { "name": "skipped_ids", "type": "array", "required": true, "description": "未命中被跳过的明细ID列表(明细不存在或不属于当前仓库,不报错;保持入参顺序)" }, { "name": "total_items", "type": "number", "required": true, "description": "删除后重算的主表明细总行数" } ] }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": 400, "message": "盘点任务ID不能为空 / 盘点任务不存在 / 当前状态(非 created/rejected)不允许删除明细 / 请至少选择一个明细 / 单次最多删除 200 条明细" }, { "code": 500, "message": "服务器内部错误" } ], "notes": [ "写操作,记录操作日志(不在免日志清单 list/detail/result/recordList/export/exportTaskProgress/patternList 中)。", "入参兼容:detail_ids 优先于 detailIds、detail_id;detailIds/detail_id 为旧版兼容写法,单值自动转数组。", "批量口径:未命中(明细不存在或不属于当前仓库)的明细ID计入 skipped_ids 不报错;命中明细批量删除后对 wms_stock_check_record 按 { detail_id, check_id, warehouse_id } 防御性清理作业记录,并重算主表 total_items;deleted_ids/skipped_ids 均保持入参顺序。", "响应结构变更(兼容性影响):由旧版 { detail_id, deleted, total_items } 变更为 { deleted_count, deleted_ids, skipped_ids, total_items },前端需按新结构取值。", "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。" ] }, { "method": "stock.check.detail", "description": "拉取盘点任务详情(只返回任务本身信息):入参 id(盘点任务ID);返回 { check },check 为盘点主表信息(id/check_no/title/type/mode/store_id/status/detail_status/start_time/end_time/creator_id/creator_name/total_items/checked_items/diff_items/remark/created_at/updated_at;start_time=盘点开始时间(第一个盘点明细写入的时间)、end_time=盘点结束时间(完成盘点的时间))+ 数量差异汇总 profit_total(盘盈合计数量)/loss_total(盘亏合计数量,正数口径,与 finish 一致;商品行聚合 vs 账面快照(未盘商品行按实盘 0 计盘亏)、库位行按商品聚合 vs wms_storage 账面(SUM(available_quantity+locked_quantity)=可用+锁定,未盘库位行不计差异)、未知商品按实盘计盘盈;无作业记录时均为 0);不再返回明细范围行(rows)与明细总条数(total)——盘点明细范围行/盘点结果聚合请调用 stock.check.result,作业记录请调用 stock.check.recordList,盘点作业数据请调用 stock.check.workData;400 边界(任务ID为空/任务不存在)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(正常登录 token,携带仓库上下文)" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "盘点任务ID" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记:success=成功 / failure=失败" }, { "name": "code", "type": "number", "required": true, "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { "name": "message", "type": "string", "required": true, "description": "提示信息:成功为 ok;失败为具体错误文案" }, { "name": "data", "type": "object", "required": true, "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", "children": [ { "name": "check", "type": "object", "required": true, "description": "盘点主表信息(id/check_no/title/type/mode/store_id/status/detail_status/start_time/end_time/creator_id/creator_name/total_items/checked_items/diff_items/remark/created_at/updated_at + profit_total 盘盈合计数量 / loss_total 盘亏合计数量(正数口径,与 finish 一致;商品行聚合 vs 账面快照(未盘商品行按实盘 0 计盘亏)、库位行按商品聚合 vs wms_storage 账面(SUM(available_quantity+locked_quantity)=可用+锁定,未盘库位行不计差异)、未知商品按实盘计盘盈);start_time=盘点开始时间(第一个盘点明细写入的时间)、end_time=盘点结束时间(完成盘点的时间))" } ] }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": 400, "message": "盘点任务ID不能为空 / 盘点任务不存在" }, { "code": 500, "message": "服务器内部错误" } ], "notes": [ "只返回任务本身信息口径(本次改造):detail 不再查询/返回 wms_stock_check_detail 明细范围行与作业记录,响应仅含 { check }(不含 rows/total);同时移除商品行 stock 全局商品信息挂载(原 stockWarehouse.getStockDetails 挂载逻辑随 rows 一并移除)。明细范围行/盘点结果聚合见 stock.check.result,作业记录见 stock.check.recordList,盘点作业数据见 stock.check.workData。代码依据:app/service/systems/stock_check.js#detail(_formatDetailScopeRow 已删除)。", "调用方迁移:原依赖 detail.rows 的调用方需改调 stock.check.result(返回 { check, rows, total } 聚合行,含商品行已盘聚合、records、locations 与库位行 stocks)/ stock.check.recordList(作业记录)/ stock.check.workData(三视图作业数据)。", "查询类方法,不记录操作日志(免日志清单:list/detail/result/recordList/export/exportTaskProgress)。", "兼容性影响(破坏性变更):响应 data 由 { check, rows, total } 变更为 { check },rows/total 字段被移除,前端取值需同步调整。", "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。" ] }, { "method": "stock.check.result", "description": "拉取盘点明细结果(按范围行聚合作业记录):入参 id(盘点任务ID);返回 { check, rows, total };商品行(scope_type=goods)含商品快照 + 已盘聚合(checked_quantity=作业记录数量合计、diff_quantity=实盘-账面、is_diff、status=checked|unchecked、location_codes、checkers、last_checked_at)+ records(该明细在 wms_stock_check_record 的全部作业记录,每条含 barcode/item_name 与 images 图片列表)+ locations(按库位聚合 [{ location_id, location_code, quantity }],空库位归 location_code=null 组,按首条记录 id 升序)+ unknown_items(未知商品按条码聚合 [{ barcode, item_name, checked_quantity }],无账面、差异=实盘-0=盘盈);库位行(scope_type=location)含 is_empty(是否空库位标记)+ checked_quantity(行级合计=行内商品实盘合计)、diff_quantity(行内各商品差异代数和)、is_diff、status + records/locations + stocks(按商品聚合 [{ stock_id, item_code, item_name, system_quantity, checked_quantity, diff_quantity }],按 stock_id 升序,账面 system_quantity 查 wms_storage(space_id+stock_id SUM(available_quantity+locked_quantity)=可用+锁定),location_id 为空时账面按 0)+ unknown_items(口径同商品行);每条作业记录挂载 images(FileReference business_type=stock_check_record,仿收货 receivingItem 口径);空库位标记(is_empty=true)时:stocks=[]、unknown_items=[]、checked_quantity=0、status=checked(视为已盘点),账面有库存时 diff_quantity 为负数(盘亏,差异=0-库位账面库存总量)、is_diff=1;无作业记录时聚合字段为 null、records/locations/stocks 为空数组。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(正常登录 token,携带仓库上下文)" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "盘点任务ID" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记:success=成功 / failure=失败" }, { "name": "code", "type": "number", "required": true, "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { "name": "message", "type": "string", "required": true, "description": "提示信息:成功为 ok;失败为具体错误文案" }, { "name": "data", "type": "object", "required": true, "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", "children": [ { "name": "check", "type": "object", "required": true, "description": "盘点主表信息(id/check_no/title/type/mode/store_id/status/detail_status/start_time/end_time/creator_id/creator_name/total_items/checked_items/diff_items/remark/created_at/updated_at;start_time=盘点开始时间(第一个盘点明细写入的时间)、end_time=盘点结束时间(完成盘点的时间))" }, { "name": "rows", "type": "array", "required": true, "description": "明细结果行列表:商品行(scope_type=goods)含范围行字段 + 已盘聚合字段(checked_quantity 已盘数量=作业记录 quantity 合计,无记录为 null;diff_quantity 差异数量=已盘-账面快照,无记录为 null;is_diff 是否有差异 0|1;status 盘点状态 checked|unchecked;location_codes 库位编码数组去重;checkers 盘点人数组去重;last_checked_at 最近上报时间,无记录为 null)+ records(该明细全部盘点作业记录,每条含 id/check_id/warehouse_id/detail_id/stock_id/location_id/location_code/quantity/checker_id/checker_name/checked_at/remark/barcode/item_name/created_at/updated_at + images 图片列表 [{ id: file_id, url }],FileReference business_type=stock_check_record)+ locations(按库位聚合数组 [{ location_id, location_code, quantity }],quantity 为该库位下作业记录数量合计,空库位记录归 location_code=null 组,按首条记录 id 升序)+ unknown_items(未知商品聚合数组 [{ barcode, item_name, checked_quantity }],按条码升序;记录 stock_id 为空的未知商品按条码归组,无账面、差异=实盘-0=盘盈,已计入行级 checked_quantity/diff_quantity/is_diff;无未知商品为空数组);库位行(scope_type=location)含范围行字段 + is_empty(是否空库位标记:该明细存在空标记记录(is_empty=1)时为 true)+ stocks(按商品聚合数组 [{ stock_id, item_code, item_name, system_quantity, checked_quantity, diff_quantity }],按 stock_id 升序,仅含存在作业记录的已知商品;system_quantity 为 wms_storage 账面(space_id+stock_id SUM(available_quantity+locked_quantity)=可用+锁定),location_id 为空时按 0)+ checked_quantity(行级合计=行内商品实盘合计,无记录为 null)/ diff_quantity(行内各商品差异代数和,无记录为 null)/ is_diff / status + location_codes / checkers / last_checked_at + records / locations + unknown_items(口径同商品行);空库位标记(is_empty=true)时:stocks=[]、unknown_items=[]、checked_quantity=0、diff_quantity=0-库位账面库存总量(账面有库存时为负数=盘亏、账面为 0 时为 0)、is_diff=账面有库存时为 1、status=checked(视为已盘点);无作业记录时 records/locations/stocks/unknown_items 为空数组、checked_quantity/diff_quantity/last_checked_at 为 null" }, { "name": "total", "type": "number", "required": true, "description": "明细总条数" } ] }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": 400, "message": "盘点任务ID不能为空 / 盘点任务不存在" }, { "code": 500, "message": "服务器内部错误" } ], "notes": [ "权限口径:随 ALL_METHOD_NAMES(16 个)免 API 权限(isNeedAuth=false)、免仓库有效期鉴权(免鉴权清单)、必须登录(isNeedLogin=true,免登录清单为空);为查询类方法,加入免日志清单 _noNeedLog(list/detail/result/recordList/export/exportTaskProgress)。", "商品行聚合口径:checked_quantity=该明细全部作业记录 quantity 合计;diff_quantity=已盘-账面(账面为明细 system_quantity 快照);is_diff=存在记录且差异非 0 时为 1;status=存在记录 checked,否则 unchecked。", "库位行账面口径:wms_storage 按 (space_id, stock_id) SUM(available_quantity+locked_quantity)(=可用+锁定)现算(与 finish/export 汇总口径一致),location_id 为空时账面按 0;库位行 stocks 仅含存在作业记录的已知商品(stock_id 有值,无记录时为空数组),商品快照 item_code/item_name 从 wms_stock_warehouse 补齐。", "无作业记录时:checked_quantity/diff_quantity/last_checked_at 为 null、records/locations/stocks 为空数组、status=unchecked、is_diff=0。", "未知商品聚合口径:stock_id 为空的作业记录按 barcode 维度归组输出行级 unknown_items [{ barcode, item_name, checked_quantity }](按条码升序,item_name 为上报名称快照);未知商品无账面,差异=实盘-0=盘盈,已计入行级 checked_quantity/diff_quantity/is_diff;stocks 保持只输出已知商品(stock_id 有值)。代码依据:app/service/systems/stock_check.js#_formatDetailAggregationRow。", "图片挂载口径(图片独立维护,仿收货 receivingItem):_attachRecordImages 查询 wms_file_reference(business_type=stock_check_record,business_id in 记录ID)并关联 wms_file 取 file_url,每条作业记录挂载 images [{ id: file_id, url }],无图片返回空数组;上传走通用上传接口(uploadSuccessNotify 传 businessType=stock_check_record + businessId=作业记录ID,建 FileReference)。代码依据:app/service/systems/stock_check.js#result/#_attachRecordImages。", "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。", "空库位标记口径(本次新增):库位行存在空标记记录(is_empty=1)时 is_empty=true——stocks 为空数组、unknown_items 为空数组、checked_quantity=0、status=checked(视为已盘点);账面口径:按 location_id 查 wms_storage SUM(available_quantity+locked_quantity)(该库位全部库存账面总量=可用+锁定,location_id 为空时按 0),账面>0 时 diff_quantity=-账面总量(盘亏)、is_diff=1,账面=0 时 diff_quantity=0、is_diff=0。代码依据:app/service/systems/stock_check.js#_formatDetailAggregationRow。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 5 条 method(stock.check.report:params 新增 is_empty 入参、errors 400 补「仅库位盘点明细支持空库位标记」、description/response/notes 补充空库位语义与互斥及汇总口径;stock.check.workData:description/response.rows 的 location 行新增 is_empty 字段说明;stock.check.result:description/response.rows 库位行新增 is_empty 与空标记盘亏口径;stock.check.recordList:response.rows 记录全字段说明新增 is_empty;stock.check.export:description/notes 补 Sheet2 空库位行输出口径);根版本 0.3.233 → 0.3.234、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 15 条 method 未改动(stock.check 分组仍为 20 条)。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 后,同步回填开发库(显式 WMS_DB_TARGET=local,127.0.0.1:3307/wms)与生产库(显式 WMS_DB_TARGET=production,112.124.21.102:3306/wms)——import 当前 system.json → export 到临时文件往返校验,保持库与文件一致;stock.check 分组共 20 条 method 无损。" ] }, { "method": "stock.check.workData", "description": "拉取盘点作业数据(视图由任务范围与 is_goods 入参驱动,view 入参已废弃忽略):入参 id(盘点任务ID)+ is_goods(可选,商品任务是否按商品视图返回——true=goods 视图;缺省 false=聚合库位 space 视图;兼容 isGoods 驼峰写法;库位任务无视该参数)+ keyword(可选,关键字:仅库位任务 location 视图生效——按行 location_code/location_name 模糊匹配(不区分大小写)过滤任务明细后再分页;非库位任务忽略;空/纯空白视为未传)+ only_abnormal(可选,只看未盘和差异:过滤在 keyword 之后、分页切片之前完成,三视图均生效——location 视图仅保留 status=unchecked 或含未知商品记录(has_unknown=true)的行;goods 视图仅保留未盘行(locations 均无 record_ids)或明盘差异行(is_diff=1,盲盘无数量字段仅按未盘过滤);space 视图按行内 goods 子项过滤(status=unchecked 或明盘 checked_quantity≠system_quantity),过滤后 goods 为空的行整体移除;兼容 onlyAbnormal 驼峰写法);返回 { view, rows, total, page, pageSize }(view=服务端实际解析出的视图类型 location/goods/space,供调用方判断 rows 行结构;不返回任务主表信息 check——任务信息请调用 stock.check.detail),rows 结构随解析视图不同(先构建全量行——location 视图且 keyword 非空时先按 location_code/location_name 过滤,only_abnormal=true 时再按未盘/差异过滤,最后按页切片,rows 为当前页行)、total=全部行数(未分页口径;keyword/only_abnormal 过滤后 total 为过滤后行数)、page=当前页码(默认 1)、pageSize=每页数量(默认 20,上限 200),任务无对应范围行时 rows 返回空数组。分页:入参 data.pagination({ page, pageSize }),未传或非法时默认 page=1、pageSize=20(上限 200),分页口径与 stock.check.list 一致。视图解析:任务范围为库位(type=location/all)一律按 location 视图;任务范围为商品(type=goods/store)默认 space 视图、仅 is_goods=true 时 goods 视图。location(库位结构):以任务库位范围行(scope_type=location)为列表(按明细 id 升序),行内挂该库位的盘点作业记录 goods 子列表(已知商品与未知商品记录均入内,未知商品 stock_id=null、item_code 用条码兜底;每项含 record_id 作业记录 ID(单条记录直接定位,可调 recordDelete/recheckClearLocation 移除)与 images 作业记录照片——FileReference business_type=stock_check_record 经 _attachRecordImages 挂载,与 result/recordList 口径一致,无照片为空数组)+ has_unknown 标记(该库位是否含未知商品记录)+ is_empty 标记(该库位是否存在空库位标记记录:空标记记录不计入 goods 子列表,存在空标记后该行 status=checked 视为已盘点);goods(商品结构):以任务商品范围行(scope_type=goods)为列表(按明细 id 升序),行内 locations 为商品所在全部库位列表(商品库存库位取自 wms_storage——启用未删除存储 DISTINCT space_id 按拣货路径排序,无库存但已有作业记录的库位追加在末尾;每项含 record_ids 该库位该商品全部作业记录 ID(按记录 id 升序)与 images 该库位该商品全部作业照片(扁平去重),供前端编辑/移除记录;未盘库位 checked_at=null、record_ids/images 为空数组),明盘(mode=open)返回账面快照/已盘合计/差异,每库位含 system_quantity(该库位账面数量=可用+锁定,wms_storage SUM(available_quantity+locked_quantity),无库存记录库位为 0)、locked_quantity(该库位锁定数量,wms_storage SUM(locked_quantity))与 quantity(该库位盘点数量,未盘库位为 0),盲盘(mode=blind)不返回任何数量字段(行级 images 仍为商品主图);space(聚合库位列表):库位集合=当前库存库位 ∪ 作业记录库位(当前库存库位:wms_storage 中任务 stock_id 集合的启用未删除存储 DISTINCT space_id;作业记录库位:wms_stock_check_record 的 location_id 已回填直接用、未回填的按 location_code 匹配 wms_location_space.space_code 补查,与库存库位去重后取并集),仅按库位拣货顺序排序(pick_sequence 升序,pick_priority 与库位 id 不参与,同值保持库位查询顺序),行内 goods 为该库位下的任务商品(每项含 record_ids 该商品在该库位全部作业记录 ID(按记录 id 升序)与 images 该商品在该库位的作业照片聚合(扁平去重,不再输出商品主图),供前端编辑/移除记录),明盘含库位账面(可用+锁定)/锁定数量/已盘数量、盲盘不含数量;盘点前库存已出空但已有盘点作业记录的库位也能展示(该库位商品行账面 system_quantity 按 0、locked_quantity 按 0、checked_quantity 按该库位实盘合计)。状态限制:仅任务状态为 approved(审核完成)或 checking(盘点作业中)时可拉取盘点作业数据,其他状态(created 已创建/submitted 待审核/rejected 已驳回/completed 已完成/cancelled 已取消)返回 400「当前状态(xx)不允许拉取盘点作业数据,仅审核完成(approved)或盘点作业中(checking)的任务可拉取」。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(正常登录 token,携带仓库上下文)" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "盘点任务ID(wms_stock_check.id)" }, { "name": "is_goods", "type": "boolean", "required": false, "source": "body", "description": "商品任务是否按商品视图返回(true=goods);缺省 false=聚合库位视图 space;库位任务无视该参数(兼容 isGoods 驼峰写法)" }, { "name": "keyword", "type": "string", "required": false, "source": "body", "description": "关键字(可选,向后兼容新增):仅库位任务(服务端解析视图为 location,即任务类型 location/all)生效——按行 location_code(优先明细快照,缺失回退库位表 space_code)与 location_name(custom_name 兜底 space_code)做模糊匹配(contains、不区分大小写)过滤任务明细后再分页返回;非库位任务(goods/store,space/goods 视图)忽略该参数;keyword 为空/纯空白视为未传不过滤" }, { "name": "only_abnormal", "type": "boolean", "required": false, "source": "body", "description": "只看未盘和差异(可选,向后兼容新增,兼容 onlyAbnormal 驼峰写法):过滤在 keyword 之后、分页切片之前完成,三视图均生效——location 视图仅保留 status=unchecked 或含未知商品记录(has_unknown=true)的行(空库位标记 is_empty 后 status=checked 视为已盘点、不保留);goods 视图仅保留未盘行(locations 均无 record_ids,即无任何作业记录)或明盘差异行(is_diff=1,盲盘无数量字段仅按未盘过滤);space 视图按行内 goods 子项过滤(status=unchecked 或明盘 checked_quantity≠system_quantity),过滤后 goods 为空的行整体移除;未传/非 true(false/0/空串/缺省)不过滤;total 为过滤后行数" }, { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数 { page, pageSize }(可选),默认 page=1、pageSize=20,pageSize 上限 200,分页口径与 stock.check.list 一致" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记:success=成功 / failure=失败" }, { "name": "code", "type": "number", "required": true, "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { "name": "message", "type": "string", "required": true, "description": "提示信息:成功为 ok;失败为具体错误文案" }, { "name": "data", "type": "object", "required": true, "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", "children": [ { "name": "view", "type": "string", "required": true, "description": "服务端实际解析出的视图类型(location=库位结构 / goods=商品结构 / space=聚合库位结构),由任务范围(type=location/all 一律 location)与 is_goods 入参共同决定,供调用方判断 rows 行结构" }, { "name": "rows", "type": "array", "required": true, "description": "盘点作业数据行列表(当前页行:先构建全量行——location 视图且 keyword 非空时先按行 location_code/location_name 模糊匹配(不区分大小写)过滤,only_abnormal=true 时再按未盘/差异过滤(location 按行 status=unchecked/has_unknown;goods 按行未盘或明盘 is_diff=1;space 按行内 goods 子项过滤后空行移除),最后按页切片;total 为全部行数——未分页口径;location 视图 + keyword 或 only_abnormal=true 时 rows 为过滤后的行、total 同步过滤口径;非库位任务(goods/store,space/goods 视图)忽略 keyword),结构随解析视图不同——location 视图行:detail_id 明细ID / location_id 库位ID / location_code 库位编码(优先明细快照,缺失回退库位表 space_code)/ location_name 库位名称(custom_name 兜底 space_code)/ status 盘点状态(checked=存在作业记录,unchecked=无)/ has_unknown 是否含未知商品记录(该库位存在 stock_id 为空的作业记录时为 true,未知商品同样计入 goods) / is_empty 是否空库位标记(该库位存在空库位标记记录(is_empty=1)时为 true;空标记记录不计入 goods 子列表;存在空标记后该行 status=checked 视为已盘点) / checked_at 该库位最近上报时间(无记录为 null)/ checkers 盘点人去重数组 + goods 作业记录子列表(已知商品与未知商品记录均入内,字段统一 record_id 作业记录ID(单条记录直接定位,可调 recordDelete/recheckClearLocation 移除)/stock_id/item_code/item_name/barcode/images 作业记录照片(已知商品与未知商品均经 _attachRecordImages 挂载 FileReference business_type=stock_check_record,与 result/recordList 口径一致,不再输出商品主图,无照片为空数组)/store_id/store_name/quantity 实盘数量/checked_at/checker_name——已知商品(stock_id 有值)商品信息批量取自 stockWarehouse.getStockDetails 带缓存、货主名经 _resolveStoreNameMap 解析;未知商品(stock_id=null)item_code 用条码兜底、item_name 用名称快照兜底条码、store_id/store_name 为 null);goods 视图行:detail_id/stock_id/item_code/item_name/spec/store_id/store_name/barcode/images(行级 images 仍为商品主图 image_url)+ locations 商品所在全部库位列表(商品库存库位取自 wms_storage——启用未删除存储 DISTINCT space_id 按拣货路径排序;无库存但已有作业记录的库位按首条记录 id 升序追加在末尾;空库位归 location_code=null 组排在最后。每项 [{ location_code, checked_at, checker_name, record_ids 该库位该商品全部作业记录 ID(按记录 id 升序,供前端编辑/移除记录), images 该库位该商品全部记录的作业照片(扁平去重,无照片为空数组) }],未盘库位 checked_at/checker_name 为 null、record_ids/images 为空数组),明盘(mode=open)另含 system_quantity 账面快照/checked_quantity 已盘合计(locations 各库位 quantity 合计,未盘行恒 0)/diff_quantity 差异=已盘-账面(仅存在作业记录的行计算,未盘行恒 0)/is_diff 是否差异 0|1(未盘行恒 0),locations 各项另含 system_quantity 该库位账面数量(wms_storage 该库位 SUM(available_quantity+locked_quantity),无库存记录库位 0)、locked_quantity 该库位锁定数量(wms_storage 该库位 SUM(locked_quantity))与 quantity 该库位盘点数量(实盘合计,未盘库位 0),盲盘(mode=blind)不返回任何数量字段(locations 仅 location_code/checked_at/checker_name/record_ids/images);space 视图行:id(库位ID wms_location_space.id)/space_code(库位编码)/custom_barcode(库位自定义条码,空为 null)/custom_name(库位自定义名称,空为 null 不兜底 space_code;库位字段对齐库位查询惯例 index.searchSpace)+ goods 该库位下的任务商品子列表(detail_id/stock_id/item_code/item_name/spec/store_id/store_name/barcode/images 该商品在该库位的作业照片聚合(扁平去重,不再输出商品主图,无照片为空数组)/record_ids 该商品在该库位的全部作业记录 ID(按记录 id 升序,供前端编辑/移除记录) + status 已盘状态(该 detail_id+location_code 存在作业记录即 checked,否则 unchecked)),明盘 goods 各项另含 system_quantity(wms_storage space+stock SUM(available_quantity+locked_quantity) 账面=可用+锁定,该库位无库存记录时按 0)/locked_quantity(该库位锁定数量,SUM(locked_quantity))/checked_quantity(该商品在该库位的实盘合计),盲盘不含数量;库位集合=当前库存库位 ∪ 作业记录库位(盘点前库存已出空但已有盘点作业记录的库位也能展示)" }, { "name": "total", "type": "number", "required": true, "description": "行总数(全部行数——未分页口径,任务无对应范围行时为 0;分页时 rows 为当前页行、total 保持全部行数不变;location 视图 + keyword 非空或 only_abnormal=true 时 total 为过滤后的行数)" }, { "name": "page", "type": "number", "required": true, "description": "当前页码(未传或非法时默认 1,分页口径与 stock.check.list 一致)" }, { "name": "pageSize", "type": "number", "required": true, "description": "每页数量(默认 20,上限 200,分页口径与 stock.check.list 一致)" } ] }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": 400, "message": "盘点任务ID不能为空" }, { "code": 400, "message": "当前状态(xx)不允许拉取盘点作业数据,仅审核完成(approved)或盘点作业中(checking)的任务可拉取" }, { "code": 400, "message": "盘点任务不存在" }, { "code": 500, "message": "服务器内部错误" } ], "notes": [ "代码依据:app/service/systemMethods/stock/check.js#workData(warehouse_id 由服务端从 ctx.user.store_id 自动注入,前端无需传递;const { id, is_goods: isGoodsSnake, isGoods: isGoodsCamel, pagination } = data || {},isGoods=is_goods 未定义时回退 isGoods(兼容 isGoods 驼峰写法);不再读取、不再校验 view,透传 { warehouseId, id, isGoods, pagination })+ app/service/systems/stock_check.js#workData(id 非正整数抛 400『盘点任务ID不能为空』;任务不存在(按 id+warehouse_id 查 wms_stock_check)抛 400『盘点任务不存在』;状态守卫:任务状态非 REPORT_ALLOWED_STATUSES(approved/checking)时抛 400『当前状态(xx)不允许拉取盘点作业数据,仅审核完成(approved)或盘点作业中(checking)的任务可拉取』;视图解析:normalizedType=String(check.type||'').trim(),type=location/all 一律 location 视图(无视 view/is_goods),否则 goodsViewRequested=isGoods===true||'true'||1 时 goods 视图、其余默认 space 视图;按解析视图分派 _buildLocationWorkRows/_buildGoodsWorkRows/_buildSpaceWorkRows,统一返回 { check: _formatCheckRow 口径, rows, total: rows.length, page, pageSize })。本次代码已改(view 入参废弃、is_goods 驱动视图)并测试通过 197/197、ESLint 0 错误。", "三视图口径(由任务范围 + is_goods 解析后分派):location=库位结构(库位范围任务一律该视图),以任务库位范围行(scope_type=location)为列表(按明细 id 升序),行内挂该库位盘点作业记录 goods 子列表(已知商品与未知商品记录均入内:已知商品 stock_id 有值,商品信息批量取自 stockWarehouse.getStockDetails 带缓存、货主名 _resolveStoreNameMap 解析;未知商品 stock_id=null,item_code 用条码兜底、item_name 用名称快照兜底条码、store_id/store_name 为 null;已知/未知商品的 images 均为作业记录照片(经 _attachRecordImages 挂载 FileReference business_type=stock_check_record,已知商品不再输出商品主图 image_url)),has_unknown 标记该库位是否含未知商品记录;goods=商品结构(商品范围任务且 is_goods=true 时该视图),以任务商品范围行(scope_type=goods)为列表(按明细 id 升序),行内 locations 为商品所在全部库位列表(商品库存库位取自 wms_storage 启用未删除存储 DISTINCT space_id 按拣货路径排序,无库存但已有作业记录的库位按首条记录 id 升序追加在末尾,空库位归 location_code=null 组排在最后;明盘每库位含 system_quantity 该库位账面数量与 quantity 该库位盘点数量(未盘库位 0),盲盘仅 location_code/checked_at/checker_name/record_ids/images);space=聚合库位列表(商品范围任务默认该视图),库位集合=当前库存库位 ∪ 作业记录库位——当前库存库位:wms_storage(warehouse_id + stock_id 在集合 + is_enabled=1 未删除)DISTINCT space_id;作业记录库位:wms_stock_check_record 的 location_id 已回填直接用、未回填的按 location_code 匹配 wms_location_space.space_code 补查,与库存库位去重后并集;行内 goods 为该库位下的任务商品;盘点前库存已出空但已有盘点作业记录的库位也能展示(该库位商品行账面 system_quantity 按 0、checked_quantity 按该库位实盘合计)。", "明盘/盲盘数量控制:明盘(mode=open)goods 视图行返回 system_quantity(明细账面快照)/checked_quantity(已盘合计=locations.quantity 合计)/diff_quantity(已盘-账面,仅存在作业记录的行计算)/is_diff(差异非 0 为 1),locations 各项含 system_quantity(该库位账面数量=可用+锁定,wms_storage 该库位 SUM(available_quantity+locked_quantity),无库存记录库位为 0)、locked_quantity(该库位锁定数量,wms_storage 该库位 SUM(locked_quantity))与 quantity(该库位盘点数量=实盘合计,未盘库位为 0);space 视图 goods 各项含 system_quantity(wms_storage space+stock SUM(available_quantity+locked_quantity) 账面,该库位无库存记录时按 0)/locked_quantity(wms_storage space+stock SUM(locked_quantity))/checked_quantity(该商品在该库位的实盘合计);盲盘(mode=blind)不返回任何数量字段(goods 视图 locations 仅 location_code/checked_at/checker_name/record_ids/images,space 视图 goods 仅商品信息+images/record_ids/status);goods 视图 locations 为商品所在全部库位列表(含未盘库位,无作业记录时各项为空信息),无作业记录的行明盘已盘合计恒 0、差异/is_diff 恒 0(避免未盘行误显盘亏差异)。", "排序口径:space 视图库位仅按库位拣货顺序排序——pick_sequence 升序(pick_priority 与库位 id 均不参与,同值保持库位查询顺序);space 行内 goods 按 stock_id 升序;location/goods 视图行按明细 id 升序;goods 视图 locations 按首条记录 id 升序。", "权限口径:随 ALL_METHOD_NAMES(22 个:create/list/addDetail/addLocationDetail/detailDelete/detail/result/workData/report/markEmpty/recordList/recordDelete/recheckClearLocation/finish/submit/cancel/audit/batchDelete/export/exportTaskProgress/patternList/patternCreate)免 API 权限(isNeedAuth=false)、免仓库有效期鉴权(_noNeedAuth)、必须登录(isNeedLogin=true,免登录清单为空);为查询类方法,加入免日志清单 _noNeedLog(list/detail/result/workData/recordList/export/exportTaskProgress/patternList),不记录操作日志。", "文档变更范围:methods/system.json 的 module=stock.check 分组新增 stock.check.workData 一条(位于 stock.check.result 之后);根版本 0.3.224 → 0.3.225、updatedAt 2026-10-01 → 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 19 条 method 未改动(stock.check 分组由 19 条增至 20 条)。", "状态限制口径:仅任务状态为 approved(审核完成)或 checking(盘点作业中)可拉取盘点作业数据;其他状态(created 已创建/submitted 待审核/rejected 已驳回/completed 已完成/cancelled 已取消)返回 400,message 为『当前状态({状态中文标签,无标签时回退状态值})不允许拉取盘点作业数据,仅审核完成(approved)或盘点作业中(checking)的任务可拉取』,状态标签取 STOCK_CHECK_STATUS_LABELS。状态守卫复用 REPORT_ALLOWED_STATUSES 常量,与 report(盘点作业上报)及 finish(完成盘点)一致。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(errors 的 400 新增状态限制文案并拆分为独立条目、description/notes 补充状态限制口径;headers/params/response/isNeedAuth/isNeedLogin 不变);根版本 0.3.225 → 0.3.226、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 19 条 method 未改动(stock.check 分组仍为 20 条)。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 后,同步回填开发库(显式 WMS_DB_TARGET=local)与生产库(NODE_ENV=production + --env production 双设置)——import 当前 system.json → export 回写往返校验,保持库与文件一致;stock.check 分组共 20 条 method 无损。", "库位字段口径(本次对齐):space 视图行字段对齐库位查询惯例(index.searchSpace,app/service/systems/space.js#_searchByKeyword attributes)——id=wms_location_space.id、space_code=库位编码、custom_barcode=库位自定义条码(空为 null)、custom_name=库位自定义名称(空为 null,不再兜底 space_code);goods 子列表字段不变(detail_id/stock_id/item_code/item_name/spec/store_id/store_name/barcode/images/status,明盘另含 system_quantity/checked_quantity);仅 space 视图行字段变化,location/goods 视图行字段不变。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(description/response.rows/notes 同步 space 视图库位聚合来源扩展与行字段规范对齐;headers/params/errors/isNeedAuth/isNeedLogin 不变);根版本 0.3.227 → 0.3.228、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 19 条 method 未改动(stock.check 分组仍为 20 条)。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 后,同步回填开发库(显式 WMS_DB_TARGET=local)与生产库(显式 WMS_DB_TARGET=production + --env production)——import 当前 system.json → export 回写往返校验,保持库与文件一致;stock.check 分组共 20 条 method 无损。", "分页口径(本次新增):三视图先构建全量行(_buildLocationWorkRows/_buildGoodsWorkRows/_buildSpaceWorkRows)再按页切片(slice(offset, offset+pageSize));rows 为当前页行、total 为全部行数(未分页口径)、响应新增 page(当前页码)与 pageSize(每页数量);page 默认 1、pageSize 默认 20、上限 200(非法值回退默认)。代码依据:app/service/systems/stock_check.js#workData。", "分页入参口径(与 stock.check.list 一致):仅入参 data.pagination.{page,pageSize},不再兼容 page_size 蛇形写法、不再支持顶层 data.page / data.pageSize / data.page_size;方法层(app/service/systemMethods/stock/check.js#workData)直接透传 pagination 对象给系统层;系统层(app/service/systems/stock_check.js#workData)page=Math.max(1, Number(pagination.page)||1) 默认 1、pageSize=Math.min(200, Math.max(1, Number(pagination.pageSize)||20)) 默认 20 上限 200、非法回退默认;先构建全量行再按页切片,返回 { check, rows, total, page, pageSize }。本次代码已改并测试通过 197/197、ESLint 0 错误。", "向后兼容:旧调用方不传分页参数时默认 page=1、pageSize=20,rows 行为与旧版一致(全量行数不超过 20 时)、total 不变;仅响应新增 page/pageSize 两个字段,其余字段口径不变。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(params 新增 pagination、response 新增 page/pageSize 并同步 rows/total 口径、description/notes 补充分页口径;headers/errors/isNeedAuth/isNeedLogin 不变);根版本 0.3.228 → 0.3.229、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 19 条 method 未改动(stock.check 分组仍为 20 条)。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 后,同步回填开发库(显式 WMS_DB_TARGET=local)与生产库(显式 WMS_DB_TARGET=production + --env production)——import 当前 system.json → export 回写往返校验,保持库与文件一致;stock.check 分组共 20 条 method 无损。", "分页口径修正(本次):上一轮文档曾描述「支持顶层 data.page / data.pageSize / data.page_size(顶层优先)并兼容 page_size 蛇形写法」,实际代码已按用户要求改为与同模块 stock.check.list 完全一致的常规口径——仅 pagination.{page,pageSize};本次同步文档删除上述兼容描述,params.pagination/description/response.page/pageSize/notes 统一为常规口径。代码依据:app/service/systemMethods/stock/check.js#workData(const { id, is_goods: isGoodsSnake, isGoods: isGoodsCamel, pagination } = data || {},直接透传)+ app/service/systems/stock_check.js#workData(pagination 默认 {},page/pageSize 归一化后对全量行 slice)。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(params.pagination 描述、description、response.page/pageSize 描述、notes 同步常规分页口径,删除顶层参数兼容与 page_size 兼容表述;response.rows/total、headers/errors/isNeedAuth/isNeedLogin 不变);根版本 0.3.229 → 0.3.230、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 19 条 method 未改动(stock.check 分组仍为 20 条)。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 后,同步回填开发库(显式 WMS_DB_TARGET=local)与生产库(显式 WMS_DB_TARGET=production)——import 当前 system.json → export 到临时文件往返校验,保持库与文件一致;stock.check 分组共 20 条 method 无损。", "视图驱动规则(本次改造):view 入参废弃——方法层不再读取、不再校验 view,传任何值都被忽略、不报错;视图改由任务范围 + is_goods 驱动——任务范围为库位(type=location/all)一律按库位视图(location)返回,无视 view/is_goods;任务范围为商品(type=goods/store)默认聚合库位视图(space),仅 is_goods=true 时按商品视图(goods)返回;is_goods 其他值(false/0/缺省等)一律按默认 space。is_goods 兼容 isGoods 驼峰写法(is_goods 未定义时回退 isGoods)。分页能力不变(pagination.{page,pageSize},与 stock.check.list 口径一致,默认 20 上限 200)。影响面:前端如需商品视图须改传 is_goods=true;view 传值不再生效。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(params 删除 view、新增 is_goods(boolean,body,可选,兼容 isGoods 驼峰写法);description 同步「库位任务一律 location、商品任务默认 space、is_goods=true 才 goods;view 入参已废弃忽略」;errors 删除「视图类型非法(仅支持 location/goods/space)」条目;response 结构不变(check/rows/total/page/pageSize);notes 同步代码依据与视图驱动规则);根版本 0.3.230 → 0.3.231、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 19 条 method 未改动(stock.check 分组仍为 20 条)。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 后,同步回填开发库(显式 WMS_DB_TARGET=local,127.0.0.1:3307/wms)与生产库(显式 WMS_DB_TARGET=production,112.124.21.102:3306/wms)——import 当前 system.json → export 到临时文件往返校验,保持库与文件一致;stock.check 分组共 20 条 method 无损。", "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。", "location 视图行结构改造(本次):_buildLocationWorkRows 删除 unknown 未知商品子列表——未知商品记录(stock_id 为空)不再单独输出,与已知商品统一并入 goods 子列表、输出字段对齐已知商品(record_id/stock_id=null/item_code 用条码兜底/item_name 用名称快照兜底条码/barcode/images/store_id=null/store_name=null/quantity/checked_at/checker_name);行级 has_unknown 标记保留(该库位是否含未知商品记录)。代码依据:app/service/systems/stock_check.js#_buildLocationWorkRows。影响面:前端无需再处理 unknown 数组,直接遍历 goods、按 stock_id 是否为 null 区分未知商品。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(description/response.rows/notes 同步 location 视图行结构:删除 unknown 子列表字段说明、goods 改为「已知商品与未知商品记录均入内,未知商品 stock_id=null、item_code 用条码兜底、store_id/store_name 为 null」、has_unknown 保留说明;headers/params/errors/isNeedAuth/isNeedLogin 与 goods/space 视图及分页描述不变);根版本 0.3.232 → 0.3.233、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 19 条 method 未改动(stock.check 分组仍为 20 条)。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 后,同步回填开发库(显式 WMS_DB_TARGET=local,127.0.0.1:3307/wms)与生产库(显式 WMS_DB_TARGET=production,112.124.21.102:3306/wms)——import 当前 system.json → export 到临时文件往返校验,保持库与文件一致;stock.check 分组共 20 条 method 无损。", "空库位标记口径(本次新增):location 视图行新增 is_empty 字段——_buildLocationWorkRows 遍历该库位作业记录,存在空标记记录(is_empty=1)时 isEmptyLocation=true 且该记录不计入 goods 子列表(不输出为商品记录行);行级 status 仍按存在作业记录口径判断(空标记记录同样是记录),因此空标记后 status=checked 视为已盘点;checked_at/checkers 口径不变。代码依据:app/service/systems/stock_check.js#_buildLocationWorkRows。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 5 条 method(stock.check.report:params 新增 is_empty 入参、errors 400 补「仅库位盘点明细支持空库位标记」、description/response/notes 补充空库位语义与互斥及汇总口径;stock.check.workData:description/response.rows 的 location 行新增 is_empty 字段说明;stock.check.result:description/response.rows 库位行新增 is_empty 与空标记盘亏口径;stock.check.recordList:response.rows 记录全字段说明新增 is_empty;stock.check.export:description/notes 补 Sheet2 空库位行输出口径);根版本 0.3.233 → 0.3.234、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 15 条 method 未改动(stock.check 分组仍为 20 条)。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 后,同步回填开发库(显式 WMS_DB_TARGET=local,127.0.0.1:3307/wms)与生产库(显式 WMS_DB_TARGET=production,112.124.21.102:3306/wms)——import 当前 system.json → export 到临时文件往返校验,保持库与文件一致;stock.check 分组共 20 条 method 无损。", "作业照片与 record_ids 口径(本次新增):三视图统一挂载作业记录照片(FileReference business_type=stock_check_record,_attachRecordImages 挂载,与 result/recordList 口径一致)——location 视图 goods 子项 images 为作业记录照片(已知商品由商品主图 stockDetail.image_url 改为作业记录照片,未知商品维持记录照片,无照片为空数组),record_id 为单条作业记录 ID(可直接定位,供 recordDelete/recheckClearLocation 移除);goods 视图行级 images 仍为商品主图,locations 聚合项新增 images(该库位该商品全部记录的作业照片扁平去重,无照片为空数组)与 record_ids(该库位该商品全部作业记录 ID,按记录 id 升序);space 视图 goods 子项 images 由商品主图改为该商品在该库位的作业照片聚合(扁平去重,无照片为空数组),并新增 record_ids(该商品在该库位全部作业记录 ID,按记录 id 升序)。record_ids 供前端编辑/移除记录(stock.check.recordDelete 批量删除 / stock.check.recheckClearLocation 重盘清除库位);行级/未盘项无记录时 images/record_ids 为空数组。代码依据:app/service/systems/stock_check.js#_buildLocationWorkRows/#_buildGoodsWorkRows/#_buildSpaceWorkRows。本次代码已改并测试通过 214/214、ESLint 0 错误。", "影响面:location 视图已知商品子项 images 由商品主图变为作业记录照片;goods 视图 locations 项新增 record_ids/images;space 视图 goods 子项 images 由商品主图变为作业照片聚合并新增 record_ids;goods 视图行级 images(商品主图)不变;其余字段(check/rows/total/page/pageSize、明盘/盲盘数量控制、状态限制)不变。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(description/response.rows/notes 同步三视图作业照片挂载与 record_ids 输出口径);headers/params/errors/isNeedAuth/isNeedLogin 与分页/状态限制描述不变;根版本 0.3.238 → 0.3.239、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 21 条 method 未改动(stock.check 分组仍为 22 条)。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 与变更记录后,同步回填开发库(显式 WMS_DB_TARGET=local,127.0.0.1:3307/wms)与生产库(显式 WMS_DB_TARGET=production,112.124.21.102:3306/wms)——import 当前 system.json → export 到临时文件往返校验,保持库与文件一致;stock.check 分组共 22 条 method 无损。", "不返回 check、改返回 view 口径(本次改造):workData 响应由 { check, rows, total, page, pageSize } 调整为 { view, rows, total, page, pageSize }——移除任务主表信息 check(任务信息请调用 stock.check.detail),新增 view(服务端实际解析出的视图类型 location/goods/space,供调用方判断 rows 行结构)。check 仍由服务端内部查询(视图解析 normalizedType=check.type、盲盘/明盘 check.mode、状态守卫),仅不再对外返回。代码依据:app/service/systems/stock_check.js#workData(resolvedView 取自 normalizedType/is_goods 解析结果)。", "view 取值口径:任务范围为库位(type=location/all)一律 location(无视 is_goods/view 入参);任务范围为商品(type=goods/store)默认 space,仅 is_goods=true(含 true/\"true\"/1)时为 goods。与视图解析规则一一对应。", "兼容性影响(破坏性变更):响应 data 移除 check 字段;新增 view 字段;rows/total/page/pageSize 与三视图行结构、明盘盲盘数量控制、状态限制均不变;前端如需任务主表信息改调 stock.check.detail。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(description 同步 view/移除 check、response 的 data.children 以 view 替换 check、notes 补充 view 口径与兼容性说明;headers/params/errors/isNeedAuth/isNeedLogin 与 rows 三视图结构不变);根版本 0.3.241 → 0.3.242、updatedAt 保持 2026-10-03;methods/changes/system.json 新增本条(插入数组首位);其余 21 条 method 未改动(stock.check 分组仍为 22 条)。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 后,需另行同步回填开发库与生产库(import 当前 system.json → export 往返校验),保持库与文件一致。", "keyword 过滤口径(本次新增):keyword(string,可选,向后兼容)仅库位任务(服务端解析视图为 location,即任务类型 location/all)生效——resolvedView===\"location\" 且 normalizedKeyword=String(keyword||\"\").trim().toLowerCase() 非空时,先按行 location_code/location_name 模糊匹配(contains、不区分大小写)过滤全量任务明细行,再按 pagination 切片;非库位任务(goods/store,space/goods 视图)忽略该参数;keyword 为空/纯空白视为未传不过滤;total=filteredRows.length(过滤后行数),rows 为过滤后当前页行。代码依据:app/service/systemMethods/stock/check.js#workData(透传 keyword)+ app/service/systems/stock_check.js#workData(filteredRows)。本次代码已改并测试通过 214/214、ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(params 新增 keyword(string,可选);description 与 response.rows/total 描述同步 keyword 过滤口径(location 视图 + keyword 时 rows 为过滤后的库位行、total 同步过滤口径;非库位任务忽略);headers/errors/isNeedAuth/isNeedLogin 与响应结构不变);根版本 0.3.243 → 0.3.244、updatedAt 保持 2026-10-04;methods/changes/system.json 新增本条(插入数组首位);其余 21 条 method 未改动(stock.check 分组仍为 22 条)。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 与变更记录后,同步回填开发库(WMS_DB_TARGET=local)与生产库(WMS_DB_TARGET=production)(import 当前 system.json → export 往返校验),保持库与文件一致。", "goods 视图 locations 商品库位列表口径(本次改造):_buildGoodsWorkRows 的 locations 由「仅已盘库位(按首条记录 id 升序)」改为「商品所在全部库位列表」——基础库位取自 wms_storage(任务 stock_id 集合 + is_enabled=1 未删除,DISTINCT space_id)经库位表取 space_code 并按拣货路径排序(pick_sequence 升序、pick_priority 降序、库位 id 升序兜底);无库存但已有作业记录的库位按首条记录 id 升序追加在末尾;空库位(location_code 空)组仍排在最后。未盘库位输出空信息(checked_at/checker_name=null、record_ids/images 空数组、明盘 quantity=0);明盘 checked_quantity=locations 各库位 quantity 合计(未盘行恒 0);diff_quantity/is_diff 仅对存在作业记录(detailRecords.length>0)的行计算,未盘行恒 0(避免未盘行误显盘亏差异)。盲盘仍不返回任何数量字段。代码依据:app/service/systems/stock_check.js#_buildGoodsWorkRows;回归测试 222/222 通过、ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(description/response.rows/notes 同步 goods 视图 locations 商品所在全部库位列表口径:未盘库位空信息、明盘每库位 quantity(未盘 0)、diff/is_diff 仅已有记录行计算);根版本 0.3.245 → 0.3.246、updatedAt 2026-10-04 → 2026-10-05;methods/changes/system.json 新增本条(插入数组首位);其余 22 条 method 未改动(stock.check 分组仍为 23 条)。", "goods 视图 locations 明盘库位数量区分(本次改造):明盘每库位同时输出 system_quantity(该库位账面数量,wms_storage 该库位 SUM(quantity),无库存记录库位为 0)与 quantity(该库位盘点数量=实盘合计,未盘库位为 0)两字段区分开;盲盘仍不返回任何数量字段。Storage 查询改为 attributes 增加 fn('SUM', col('quantity')) 按 stock+space 分组汇总,构建 stockId→spaceCode→账面数量映射;行级 checked_quantity 仍为 locations.quantity 合计,diff/is_diff 计算条件不变。代码依据:app/service/systems/stock_check.js#_buildGoodsWorkRows;回归测试 222/222 通过、ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 与 stock.check.workDataDetail 两条(description/response.rows/notes 同步 goods 视图明盘库位 system_quantity(账面)+quantity(盘点)双数量字段口径);根版本 0.3.246 → 0.3.247、updatedAt 保持 2026-10-05;methods/changes/system.json 新增本条(插入数组首位);其余 21 条 method 未改动(stock.check 分组仍为 23 条)。", "库位账面口径改造(本次):盘点作业数据接口的库位账面 system_quantity 由 SUM(quantity) 改为 SUM(available_quantity+locked_quantity)(=可用+锁定),并新增 locked_quantity(该库位锁定数量,SUM(locked_quantity))——goods 视图 locations 各项与 space 视图 goods 子项(workData/workDataDetail/workDataSpaceDetails 共用构建器);盲盘仍不返回任何数量字段。代码依据:app/service/systems/stock_check.js#_buildGoodsWorkRows/#_buildSpaceWorkRows;回归测试 222/222 通过、ESLint 0 错误。(后续已按用户要求全部统一:result/report/finish/detail 差异汇总与 addDetail 拆行快照均改为可用+锁定口径,见 0.3.249 变更记录)", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData、stock.check.workDataDetail 与 stock.check.workDataSpaceDetails 三条(description/response.rows/notes 同步库位账面=可用+锁定口径与 locked_quantity 字段);根版本 0.3.247 → 0.3.248、updatedAt 保持 2026-10-05;methods/changes/system.json 新增本条(插入数组首位);其余 20 条 method 未改动(stock.check 分组仍为 23 条)。", "库位账面口径全量统一(本次,0.3.249 同步):全部盘点账面口径统一为 SUM(available_quantity+locked_quantity)(=可用+锁定)——result 库位行 stocks 账面与空库位标记盘亏、report 重算 diff_items 的库位行/空标记账面、finish 差异汇总、detail profit/loss 汇总、addDetail 按库位拆行的明细快照 system_quantity,与盘点作业视图(workData/workDataDetail/workDataSpaceDetails)一致;商品行仍以明细账面快照(system_quantity 列)对比。回归测试 222/222 通过、ESLint 0 错误。", "only_abnormal 过滤口径(本次新增):only_abnormal(boolean,可选,向后兼容,兼容 onlyAbnormal 驼峰写法;未传或非 true(false/0/空串/缺省)不过滤)——过滤在 keyword 之后、分页切片之前完成(total 为过滤后行数),三视图均生效:location 视图仅保留 status=unchecked 或 has_unknown=true 的行(未知商品无账面、差异=实盘-0=盘盈视为差异;空库位标记 is_empty 后 status=checked 视为已盘点、不保留);goods 视图仅保留未盘行(locations 均无 record_ids,即无任何作业记录)或明盘差异行(is_diff=1),盲盘无数量字段仅按未盘过滤(已盘行全部移除);space 视图按行内 goods 子项过滤(status=unchecked 或明盘 checked_quantity≠system_quantity,system_quantity 口径=可用+锁定),过滤后 goods 为空的行整体移除。与 keyword 过滤叠加(keyword 先过滤、only_abnormal 后过滤)。代码依据:app/service/systemMethods/stock/check.js#workData(only_abnormal/onlyAbnormal 蛇形驼峰兼容,透传 onlyAbnormal)+ app/service/systems/stock_check.js#workData/#_filterAbnormalWorkRows;回归测试新增 5 用例(location/goods 明盘/space 明盘/space 盲盘/keyword 叠加)全部通过、workData 相关 43 用例通过、ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(params 新增 only_abnormal、description/response.rows/response.total/notes 同步过滤口径;headers/errors/isNeedAuth/isNeedLogin 不变);根版本 0.3.249 → 0.3.250、updatedAt 保持 2026-10-06;methods/changes/system.json 新增本条(插入数组首位);其余 23 条 method 未改动(stock.check 分组仍为 24 条)。" ] }, { "method": "stock.check.workDataSpaceDetails", "description": "拉取盘点作业数据(space 视图分页版):入参 id(盘点任务ID)+ location_id(库位ID,可选,兼容 locationId 驼峰写法)+ pagination({page,pageSize},缺省 page=1/pageSize=20,上限 200);warehouse_id 由服务端从当前上下文自动注入,前端无需传递。行结构与 workData space 视图行一致:id=库位ID(wms_location_space.id)/ space_code 库位编码 / custom_barcode 自定义条码 / custom_name 库位名称 / goods 该库位下的任务商品子列表(detail_id 明细ID / stock_id 商品库存ID / item_code 商品编码 / item_name 商品名称 / spec 规格 / store_id 货主ID / store_name 货主名 / barcode 条码 / images 作业照片 / record_ids 作业记录ID列表;明盘 mode=open 另含 system_quantity 账面数量(wms_storage 该库位该商品 SUM(available_quantity+locked_quantity))、locked_quantity 锁定数量(wms_storage 该库位该商品 SUM(locked_quantity))与 checked_quantity 已盘合计;盲盘 mode=blind 不返回任何数量字段;status=checked 该 (detail_id, location_code) 存在作业记录 / unchecked 未盘)。库位仅按库位拣货顺序排序(pick_sequence 升序,pick_priority 与库位 id 不参与,同值保持库位查询顺序);传入 location_id 时只返回该库位行(total=1),不传时按分页返回全部库位行;返回 { view:'space', rows, total, page, pageSize }(不返回任务主表信息,任务信息请调用 stock.check.detail)。仅任务状态 approved(审核完成)或 checking(盘点作业中)可拉取(与 workData 同口径)。权限口径:免 API 权限校验,仅需登录(与 stock.check 分组其他方法一致)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(正常登录 token,携带仓库上下文)" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "盘点任务ID(正整数)" }, { "name": "location_id", "type": "number", "required": false, "source": "body", "description": "库位ID(wms_location_space.id,可选;传入时只返回该库位行,兼容 locationId 驼峰写法)" }, { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页配置:page(页码,默认1)、pageSize(每页数量,默认20,上限200);传入 location_id 时分页参数仅影响返回结构,total 恒为 1" } ], "response": [ { "name": "view", "type": "string", "required": true, "description": "恒为 space(聚合库位视图)" }, { "name": "rows", "type": "array", "required": true, "description": "当前页库位行:每行含 id/space_code/custom_barcode/custom_name/goods(goods 结构与 workData space 视图一致,明盘含 system_quantity/checked_quantity/status,盲盘不含数量字段)" }, { "name": "total / page / pageSize", "type": "object", "required": true, "description": "total=全部库位行数(传入 location_id 时恒为 1),page/pageSize=当前分页" } ], "errors": [ { "code": "400", "message": "盘点任务ID不能为空" }, { "code": "400", "message": "盘点任务不存在" }, { "code": "400", "message": "当前状态不允许拉取盘点作业数据(仅 approved/checking 可拉取)" }, { "code": "401", "message": "未提供有效的认证令牌" }, { "code": "500", "message": "拉取盘点作业数据失败" } ] }, { "method": "stock.check.workDataDetail", "description": "拉取单条盘点明细的作业数据(workData 单行版,按明细范围类型分流,均返回单行对象):入参 detail_id(盘点明细ID,兼容 detailId 驼峰写法);warehouse_id 由服务端从当前上下文自动注入,前端无需传递;返回统一 success 包装,data 为单行作业数据。① 库位明细(scope_type=location):行结构与 workData location 视图单行一致——detail_id 明细ID / location_id 库位ID(明细未绑定库位时为 null)/ location_code 库位编码(优先明细快照,缺失回退库位表 space_code)/ location_name 库位名称(custom_name 兜底 space_code,无库位编码时为 null)/ status 盘点状态(checked=存在作业记录(含空库位标记记录),unchecked=无作业记录)/ has_unknown 是否含未知商品记录 / is_empty 是否空库位标记(空标记记录不计入 goods 子列表)/ checked_at 该库位最近上报时间(无记录为 null)/ checkers 盘点人去重数组 + goods 作业记录子列表(已知商品与未知商品记录均入内,字段与 workData location 视图一致:record_id 作业记录ID(可调 stock.check.recordDelete / stock.check.recheckClearLocation 移除)/ stock_id 商品库存ID(未知商品为 null)/ item_code 商品编码(未知商品用条码兜底)/ item_name 商品名称(未知商品用名称快照兜底条码)/ barcode 条码 / images 作业记录照片(FileReference business_type=stock_check_record 经 _attachRecordImages 挂载,与 workData/result/recordList 口径一致,无照片为空数组)/ store_id 货主ID(未知商品为 null)/ store_name 货主名(未知商品为 null)/ quantity 实盘数量 / checked_at 上报时间 / checker_name 盘点人;空库位标记记录不计入 goods)。② 商品明细(scope_type=goods):行结构与 workData goods 视图行一致——detail_id 明细ID / stock_id 商品库存ID / item_code 商品编码 / item_name 商品名称 / spec 规格 / store_id 货主ID / store_name 货主名 / barcode 条码 / images 商品图片(URL 数组,与 workData goods 视图一致)/ locations 商品所在全部库位列表(商品库存库位按拣货路径排序在前,无库存但已有作业记录的库位按首条记录 id 升序追加在末尾,空库位归 location_code=null 组排在最后;每项 { location_code, checked_at, checker_name, record_ids, images },未盘库位 checked_at/checker_name 为 null、record_ids/images 为空数组;明盘另含 system_quantity 该库位账面数量(=可用+锁定)、locked_quantity 该库位锁定数量与 quantity 该库位盘点数量(未盘库位 0),盲盘只返回库位信息);明盘(mode=open)另含 system_quantity 账面快照 / checked_quantity 已盘合计 / diff_quantity 差异(仅存在作业记录时计算,未盘恒 0) / is_diff,盲盘(mode=blind)不返回任何数量字段。仅任务状态 approved(审核完成)或 checking(盘点作业中)可拉取(与 workData 同口径)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(正常登录 token,携带仓库上下文)" } ], "params": [ { "name": "detail_id", "type": "number", "required": true, "source": "body", "description": "盘点明细ID(wms_stock_check_detail.id,scope_type=location 的库位范围行;兼容 detailId 驼峰写法)" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记:success=成功 / failure=失败" }, { "name": "code", "type": "number", "required": true, "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { "name": "message", "type": "string", "required": true, "description": "提示信息:成功为 ok;失败为具体错误文案" }, { "name": "data", "type": "object", "required": true, "description": "业务数据对象(统一 data 层封装:本方法业务数据整体位于 data 内;失败时 data=null),为单行作业数据,结构与 stock.check.workData location 视图单行一致", "children": [ { "name": "detail_id", "type": "number", "required": true, "description": "盘点明细ID(wms_stock_check_detail.id)" }, { "name": "location_id", "type": "number", "required": true, "description": "库位ID(wms_location_space.id;明细未绑定库位时为 null)" }, { "name": "location_code", "type": "string", "required": true, "description": "库位编码(优先明细快照,缺失回退库位表 space_code;无库位时为 null)" }, { "name": "location_name", "type": "string", "required": true, "description": "库位名称(custom_name 兜底 space_code;无库位编码时为 null)" }, { "name": "status", "type": "string", "required": true, "description": "盘点状态:checked=存在作业记录(含空库位标记记录),unchecked=无作业记录" }, { "name": "has_unknown", "type": "boolean", "required": true, "description": "是否含未知商品记录(该库位存在 stock_id 为空的作业记录时为 true,未知商品同样计入 goods)" }, { "name": "is_empty", "type": "boolean", "required": true, "description": "是否空库位标记(该库位存在空库位标记记录(is_empty=1)时为 true;空标记记录不计入 goods 子列表)" }, { "name": "checked_at", "type": "string", "required": true, "description": "该库位最近上报时间(无记录为 null)" }, { "name": "checkers", "type": "array", "required": true, "description": "盘点人去重数组(字符串数组,无记录为空数组)" }, { "name": "goods", "type": "array", "required": true, "description": "该库位盘点作业记录子列表(已知商品与未知商品记录均入内,字段与 workData location 视图一致;空库位标记记录不计入;无记录为空数组):每项 record_id 作业记录ID(单条记录直接定位,可调 stock.check.recordDelete / stock.check.recheckClearLocation 移除)/ stock_id 商品库存ID(未知商品为 null)/ item_code 商品编码(未知商品用条码兜底)/ item_name 商品名称(未知商品用名称快照兜底条码)/ barcode 条码 / images 作业记录照片([{ id, url }],FileReference business_type=stock_check_record 经 _attachRecordImages 挂载,与 workData/result/recordList 口径一致,无照片为空数组)/ store_id 货主ID(未知商品为 null)/ store_name 货主名(未知商品为 null)/ quantity 实盘数量 / checked_at 上报时间 / checker_name 盘点人" } ] }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": 400, "message": "盘点明细ID不能为空" }, { "code": 400, "message": "盘点明细不存在" }, { "code": 400, "message": "仅库位任务明细支持拉取单行作业数据" }, { "code": 400, "message": "盘点任务不存在" }, { "code": 400, "message": "当前状态(xx)不允许拉取盘点作业数据,仅审核完成(approved)或盘点作业中(checking)的任务可拉取" }, { "code": 500, "message": "服务器内部错误" } ], "notes": [ "代码依据:app/service/systemMethods/stock/check.js#workDataDetail(ALL_METHOD_NAMES 由 22 增至 23 个(create,list,addDetail,addLocationDetail,detailDelete,detail,result,workData,workDataDetail,report,markEmpty,recordList,recordDelete,recheckClearLocation,finish,submit,cancel,audit,batchDelete,export,exportTaskProgress,patternList,patternCreate);_noNeedLog 查询类清单新增 workDataDetail(list,detail,result,workData,workDataDetail,recordList,export,exportTaskProgress,patternList);const { detail_id: detailIdSnake, detailId: detailIdCamel } = data || {},detailId=detail_id 未定义时回退 detailId(兼容 detailId 驼峰写法);warehouse_id 由服务端从 ctx.user.store_id 自动注入,前端无需传递,透传 { warehouseId, detailId })+ app/service/systems/stock_check.js#workDataDetail(detailId 非正整数抛 400『盘点明细ID不能为空』;按 id+warehouse_id 查 wms_stock_check_detail 不存在抛 400『盘点明细不存在』;_findCheck 查不到任务抛 400『盘点任务不存在』;任务状态非 REPORT_ALLOWED_STATUSES(approved/checking)抛 400『当前状态(xx)不允许拉取盘点作业数据,仅审核完成(approved)或盘点作业中(checking)的任务可拉取』;按明细 scope_type 分流:location 走 _buildLocationWorkRows 构建全量库位行并 find 匹配该明细ID、goods 走 _buildGoodsWorkRows 构建全量商品行并 find 匹配该明细ID,未命中抛 400『盘点明细不存在』,命中返回该单行)。本次代码已改并测试通过 216/216、ESLint 0 错误;后续 goods 分支扩展与 locations 商品库位列表口径见下方变更说明。", "单行口径:响应 data 为单行作业数据,与 stock.check.workData 对应视图单行完全一致(复用同一构建函数 _buildLocationWorkRows/_buildGoodsWorkRows),便于作业端按明细ID刷新单行数据;库位明细(scope_type=location)返回 location 视图单行(detail_id/location_id/location_code/location_name/status/has_unknown/is_empty/checked_at/checkers/goods),商品明细(scope_type=goods)返回 goods 视图单行(detail_id/stock_id/item_code/item_name/spec/store_id/store_name/barcode/images/locations 商品所在全部库位列表,明盘另含数量字段)。", "权限口径:随 ALL_METHOD_NAMES(23 个)免 API 权限(isNeedAuth=false)、免仓库有效期鉴权(_noNeedAuth)、必须登录(isNeedLogin=true,免登录清单为空);为查询类方法,加入免日志清单 _noNeedLog,不记录操作日志。", "状态限制口径:仅任务状态 approved(审核完成)或 checking(盘点作业中)可拉取,与 stock.check.workData / report / finish 同口径(REPORT_ALLOWED_STATUSES)。", "文档变更范围:methods/system.json 的 module=stock.check 分组新增 stock.check.workDataDetail 一条(位于 stock.check.workData 之后);根版本 0.3.244 → 0.3.245、updatedAt 保持 2026-10-04;methods/changes/system.json 新增本条(插入数组首位);其余 22 条 method 未改动(stock.check 分组由 22 条增至 23 条)。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 与变更记录后,同步回填开发库(WMS_DB_TARGET=local,127.0.0.1:3307/wms)与生产库(WMS_DB_TARGET=production,112.124.21.102:3306/wms)——import 当前 system.json → export 到临时文件往返校验,保持库与文件一致。", "goods 明细单行 locations 商品库位列表口径(本次同步 workData 改造):workDataDetail 商品明细分支复用 _buildGoodsWorkRows,locations 为商品所在全部库位列表(库存库位按拣货路径排序在前、无库存但已有作业记录的库位按首条记录 id 升序追加、空库位归 null 组排在最后;明盘每库位含 system_quantity 该库位账面数量(=可用+锁定)、locked_quantity 该库位锁定数量与 quantity 该库位盘点数量(未盘 0),盲盘只返回库位信息);未盘明细 checked_quantity 恒 0、diff_quantity/is_diff 仅存在作业记录时计算(未盘恒 0)。回归测试 222/222 通过、ESLint 0 错误。", "库位账面口径(本次同步 workData 改造):goods 明细单行 locations 各项库位账面 system_quantity = wms_storage 该库位 SUM(available_quantity+locked_quantity)(可用+锁定),locked_quantity = 该库位 SUM(locked_quantity);盲盘仍不返回任何数量字段。回归测试 222/222 通过、ESLint 0 错误。" ] }, { "method": "stock.check.report", "description": "盘点作业上报(覆盖式):商品明细行(scope_type=goods)固定上报明细商品(入参 stock_id 与明细商品不一致报错),库位可选(未传归入\"无库位\"分组,location_code 存空串 '');库位明细行(scope_type=location)必须指定商品(stock_id 或 barcode 至少一项),库位以明细库位为准(入参库位与明细库位不一致报错,不传时默认明细库位);空库位标记(is_empty=true,仅库位明细行支持):确认该库位为空——不要求商品/条码,quantity 恒为 0,写一条特殊作业记录(stock_id=null、barcode=null、item_name=null、quantity=0、is_empty=1);与商品记录互斥:标记空时删除该明细下所有商品记录(含未知商品),上报商品时删除该明细下空标记记录;商品明细行传 is_empty 报 400「仅库位盘点明细支持空库位标记」。覆盖式查重:已知商品维度 detail_id+stock_id+location_code、未知商品维度 detail_id+stock_id IS NULL+barcode+location_code,同明细+同商品+同库位重复上报时更新已有记录(quantity/checker_id/checker_name/checked_at,保留原 location_id,本次新匹配到 location_id 则回填),不再新增;仅 approved/checking 状态允许;库位编码匹配 wms_location_space.space_code 时回填 location_id;主表 approved 首次上报自动转 checking;完成后重算 checked_items/diff_items/detail_status(已盘口径=存在记录的明细数,差异=记录数量合计-账面:商品行 vs system_quantity 快照、库位行按商品 vs wms_storage 账面;未知商品无账面,实盘>0 即盘盈、必然计入差异;空标记记录同样计入已盘明细(checked_items/detail_status),空标记明细的库位账面有库存即计盘亏差异(diff_items));数据库层由唯一索引 uk_detail_stock_location(detail_id, stock_id, location_code) 保证已知商品覆盖式上报并发安全(并发下不产生重复记录),未知商品(stock_id=NULL)唯一索引不约束 NULL 行、应用层查重兜底。主表 start_time 为空时以本次明细写入时间补写(首个盘点明细写入时间记录为 start_time,即盘点开始时间)。未知商品上报(stock_id 与 barcode 至少传一项):仅传 barcode → 先按条码匹配系统商品(wms_stock_barcodes 按 barcode+本仓库,关联 StockWarehouse 校验商品属于本仓库),命中回填 stock_id 走已知商品逻辑;未命中记录未知商品(stock_id=NULL+barcode+item_name,item_name 缺省为 barcode);都未传沿用原报错口径。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(正常登录 token,携带仓库上下文)" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "盘点任务ID" }, { "name": "detail_id", "type": "number", "required": true, "source": "body", "description": "盘点明细ID" }, { "name": "location", "type": "string", "required": false, "source": "body", "description": "库位编码(可空;商品明细行:未传归入无库位分组(存空串 '');库位明细行:以明细库位为准,传入时必须与明细库位一致)" }, { "name": "quantity", "type": "number", "required": true, "source": "body", "description": "实盘数量(不小于 0 的整数)" }, { "name": "stock_id", "type": "number", "required": false, "source": "body", "description": "商品库存ID(wms_stock_warehouse.id);商品明细行可选(传入必须与明细商品一致,否则报错);库位明细行必填(或改传 barcode 按条码匹配),商品必须属于本仓库" }, { "name": "barcode", "type": "string", "required": false, "source": "body", "description": "扫描到的条码/编码(可选):未传 stock_id 时按条码匹配系统商品(wms_stock_barcodes 按 barcode+本仓库匹配并校验商品属于本仓库,关联 StockWarehouse),命中回填 stock_id 按已知商品处理;未命中记为未知商品(stock_id=NULL+barcode+item_name)" }, { "name": "item_name", "type": "string", "required": false, "source": "body", "description": "未知商品名称快照(可选):仅未知商品记录落库,缺省为 barcode;已知商品忽略" }, { "name": "is_empty", "type": "boolean", "required": false, "source": "body", "description": "空库位标记(可选,仅库位明细行 scope_type=location 支持):true 表示「确认该库位为空」——不要求商品/条码,quantity 恒为 0(不参与数量校验),写一条特殊作业记录(stock_id=null、barcode=null、item_name=null、quantity=0、is_empty=1);与商品记录互斥:标记空时删除该明细下所有商品记录(含未知商品),上报商品时删除该明细下空标记记录;商品明细行传 true 报 400「仅库位盘点明细支持空库位标记」" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记:success=成功 / failure=失败" }, { "name": "code", "type": "number", "required": true, "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { "name": "message", "type": "string", "required": true, "description": "提示信息:成功为 ok;失败为具体错误文案" }, { "name": "data", "type": "object", "required": true, "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", "children": [ { "name": "record", "type": "object", "required": true, "description": "新增或更新的盘点作业记录(wms_stock_check_record 行:id/check_id/warehouse_id/detail_id/stock_id/location_id/location_code/quantity/checker_id/checker_name/checked_at/remark/barcode/item_name/is_empty/created_at/updated_at);stock_id 可空:NULL=未知商品(此时 barcode=扫描条码、item_name=未知商品名称快照(缺省为条码)),已知商品 barcode/item_name 可能为空;is_empty=1 为空库位标记记录(stock_id/barcode/item_name 均为 null、quantity=0)" }, { "name": "detail_id", "type": "number", "required": true, "description": "盘点明细ID" }, { "name": "mode", "type": "string", "required": true, "description": "本次上报模式:created=首次上报新增记录 / updated=同明细+同商品+同库位重复上报更新已有记录(未知商品为同明细+同条码+同库位)" }, { "name": "total_items", "type": "number", "required": true, "description": "明细总行数" }, { "name": "checked_items", "type": "number", "required": true, "description": "已盘行数(存在作业记录的明细数;空库位标记记录同样计入已盘)" }, { "name": "diff_items", "type": "number", "required": true, "description": "差异行数(实盘合计与账面不一致的明细数;未知商品无账面,实盘>0 即盘盈、必然计入差异;空标记明细的库位账面有库存即计盘亏差异)" }, { "name": "detail_status", "type": "string", "required": true, "description": "明细盘点进度:none_checked/partial_checked/all_checked" } ] }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": 400, "message": "盘点任务ID不能为空 / 盘点明细ID不能为空 / 盘点任务不存在 / 当前状态(非 approved/checking)不允许盘点作业 / 实盘数量必须为不小于0的整数 / 盘点明细不存在 / 盘点明细缺少商品信息 / 上报商品与盘点明细商品不一致 / 按库位盘点时必须指定商品 / 上报商品不属于本仓库 / 盘点明细缺少库位信息 / 上报库位与盘点明细库位不一致 / 仅库位盘点明细支持空库位标记" }, { "code": 500, "message": "服务器内部错误" } ], "notes": [ "覆盖口径:同 detail_id + 同 stock_id + 同 location_code(未传库位存储空串 '',即\"无库位\"分组)视为同一作业记录,重复上报只更新不新增。", "并发保证:数据库层唯一索引 uk_detail_stock_location(detail_id, stock_id, location_code) 兜底,并发上报同一明细+商品+库位时不产生重复记录(模型 location_code allowNull=false 默认空串)。", "库位行上报:商品必填(按库位盘点时必须指定商品,stock_id 或 barcode 至少一项)且商品须属于本仓库(wms_stock_warehouse.id + warehouse_id),库位以明细库位为准(detail.location_code)。", "start_time 口径:主表 start_time 为空时以本次明细写入时间补写(首个盘点明细写入时间记录为 start_time=盘点开始时间);代码依据 app/service/systems/stock_check.js#report(start_time 为空则补写,保证任何状态下首个明细落盘时间都被记录)。", "未知商品上报口径(stock_id 与 barcode 至少传一项):传了 stock_id 按已知商品走现有逻辑(本仓库校验等);未传 stock_id 但传了 barcode,先按条码匹配系统商品(_resolveStockIdByBarcode:wms_stock_barcodes 按 barcode+本仓库匹配,再校验 wms_stock_warehouse 中该商品属于本仓库),命中回填 stock_id 按已知商品处理(商品明细行还会校验与明细商品一致),未命中记录未知商品(stock_id=NULL + barcode + item_name,item_name 缺省为 barcode);都未传沿用现有报错口径(商品行缺商品信息报 400 / 库位行缺商品报 400)。", "未知商品覆盖式查重:已知商品 where { detail_id, stock_id, location_code } 不变;未知商品 where { detail_id, stock_id: null, barcode, location_code } 应用层查重(唯一索引 uk_detail_stock_location 不约束 NULL 行,并发下撞索引/冲突时同样按查重条件降级更新兜底)。", "迁移依据:database/migrations/20261001100000-support-unknown-goods-in-stock-check-record.js(wms_stock_check_record:stock_id 改可空(NULL=未知商品)+ 新增 barcode VARCHAR(100)/item_name VARCHAR(255),本地与生产均已执行)。", "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。", "空库位标记上报口径(本次新增):is_empty 仅库位明细行(scope_type=location)支持,商品明细行传 is_empty 报 400『仅库位盘点明细支持空库位标记』;标记空时不要求商品/条码,quantity 恒为 0(跳过『实盘数量必须为不小于0的整数』校验),写一条特殊作业记录(stock_id=null、barcode=null、item_name=null、quantity=0、is_empty=1);覆盖式查重按(detail_id + is_empty=1 + location_code)应用层查重覆盖更新。互斥口径:标记空时删除该明细下所有商品记录(is_empty=false,含未知商品),上报商品时删除该明细下空标记记录(is_empty=true),两者不会并存。代码依据:app/service/systems/stock_check.js#report。", "汇总口径(本次同步 _recalcCheckSummary):空库位标记记录计入已盘明细(checked_items 按 DISTINCT detail_id 自然计入、detail_status 按已盘占比正常推进);差异口径:空标记明细的库位账面(wms_storage 按 space_id SUM(available_quantity+locked_quantity)=可用+锁定)有库存即计盘亏差异(diff_items 加 1),账面无库存不计差异。代码依据:app/service/systems/stock_check.js#_recalcCheckSummary。", "迁移依据:database/migrations/20261002160000-add-is-empty-to-stock-check-record.js(wms_stock_check_record 新增 is_empty TINYINT(1) NOT NULL DEFAULT 0,COMMENT 是否空库位标记(1=确认为空),开发与生产库均已执行)。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 5 条 method(stock.check.report:params 新增 is_empty 入参、errors 400 补「仅库位盘点明细支持空库位标记」、description/response/notes 补充空库位语义与互斥及汇总口径;stock.check.workData:description/response.rows 的 location 行新增 is_empty 字段说明;stock.check.result:description/response.rows 库位行新增 is_empty 与空标记盘亏口径;stock.check.recordList:response.rows 记录全字段说明新增 is_empty;stock.check.export:description/notes 补 Sheet2 空库位行输出口径);根版本 0.3.233 → 0.3.234、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 15 条 method 未改动(stock.check 分组仍为 20 条)。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 后,同步回填开发库(显式 WMS_DB_TARGET=local,127.0.0.1:3307/wms)与生产库(显式 WMS_DB_TARGET=production,112.124.21.102:3306/wms)——import 当前 system.json → export 到临时文件往返校验,保持库与文件一致;stock.check 分组共 20 条 method 无损。" ] }, { "method": "stock.check.markEmpty", "description": "标记库位为空(库位盘点模式专属,转调 report 的空库位标记口径):仅库位范围任务(type=location/all)支持——非库位任务报 400「仅库位盘点任务支持空库位标记」;仅 approved/checking 状态允许;明细必须属于本任务且为库位范围行(scope_type=location),非库位行报 400「仅库位盘点明细支持空库位标记」;行为与 report(is_empty=true) 完全一致——写/更新空标记记录(stock_id/barcode/item_name 均为 null、quantity=0、is_empty=1)、清除该明细商品记录、主表 approved 首次标记自动转 checking、重算 checked_items/diff_items/detail_status(空标记计入已盘;库位账面有库存计盘亏差异);warehouse_id 由服务端从当前登录上下文(ctx.user.store_id)自动注入,前端无需传递。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(正常登录 token,携带仓库上下文)" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "盘点任务ID(正整数;非法抛 400「盘点任务ID不能为空」)" }, { "name": "detail_id", "type": "number", "required": true, "source": "body", "description": "库位明细ID(正整数;非法抛 400「盘点明细ID不能为空」;明细必须属于本任务且为库位范围行 scope_type=location,非库位行报 400「仅库位盘点明细支持空库位标记」)" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记:success=成功 / failure=失败" }, { "name": "code", "type": "number", "required": true, "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { "name": "message", "type": "string", "required": true, "description": "提示信息:成功为 ok;失败为具体错误文案" }, { "name": "data", "type": "object", "required": true, "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,与 report 口径一致;失败时 data=null)", "children": [ { "name": "record", "type": "object", "required": true, "description": "新增或更新的空库位标记作业记录(wms_stock_check_record 行全字段:id/check_id/warehouse_id/detail_id/stock_id/location_id/location_code/quantity/checker_id/checker_name/checked_at/remark/barcode/item_name/is_empty/created_at/updated_at);is_empty=1 空库位标记记录:stock_id/barcode/item_name 均为 null、quantity=0" }, { "name": "detail_id", "type": "number", "required": true, "description": "盘点明细ID" }, { "name": "mode", "type": "string", "required": true, "description": "本次写入模式:created=首次写入空标记记录 / updated=重复标记更新已有空标记记录" }, { "name": "total_items", "type": "number", "required": true, "description": "明细总行数" }, { "name": "checked_items", "type": "number", "required": true, "description": "已盘行数(存在作业记录的明细数;空库位标记记录同样计入已盘)" }, { "name": "diff_items", "type": "number", "required": true, "description": "差异行数(实盘合计与账面不一致的明细数;空标记明细的库位账面有库存即计盘亏差异)" }, { "name": "detail_status", "type": "string", "required": true, "description": "明细盘点进度:none_checked/partial_checked/all_checked" } ] }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": 400, "message": "盘点任务ID不能为空" }, { "code": 400, "message": "盘点明细ID不能为空" }, { "code": 400, "message": "盘点任务不存在" }, { "code": 400, "message": "当前状态(xx)不允许盘点作业" }, { "code": 400, "message": "仅库位盘点任务支持空库位标记" }, { "code": 400, "message": "盘点明细不存在" }, { "code": 400, "message": "仅库位盘点明细支持空库位标记" }, { "code": 500, "message": "服务器内部错误" } ], "notes": [ "库位盘点专属便捷方法:内部转调 report(is_empty=true) 口径(查重/互斥/汇总/日志统一),行为与 report 空库位标记完全一致——写/更新空标记记录(stock_id=null、barcode=null、item_name=null、quantity=0、is_empty=1)、清除该明细商品记录、主表 approved 首次标记自动转 checking、完成后重算 checked_items/diff_items/detail_status。代码依据:app/service/systemMethods/stock/check.js#markEmpty(warehouse_id 由服务端从 ctx.user.store_id 自动注入,checkerId/checkerName 同口径注入)+ app/service/systems/stock_check.js#markEmpty(校验后转调 this.report({ is_empty: true }))。", "校验顺序口径:任务ID/明细ID 非正整数 → 400「盘点任务ID不能为空」/「盘点明细ID不能为空」;任务不存在(按 id+warehouse_id 查 wms_stock_check)→ 400「盘点任务不存在」;状态非 REPORT_ALLOWED_STATUSES(approved/checking)→ 400「当前状态(xx)不允许盘点作业」;任务范围非库位(type≠location/all)→ 400「仅库位盘点任务支持空库位标记」;明细不存在(id+check_id+warehouse_id 查 wms_stock_check_detail)→ 400「盘点明细不存在」;明细非库位行(scope_type≠location)→ 400「仅库位盘点明细支持空库位标记」。", "权限口径:随 ALL_METHOD_NAMES(22 个,已由 20 增至 21(markEmpty),本次再增 recheckClearLocation)免 API 权限(isNeedAuth=false)、免仓库有效期鉴权(_noNeedAuth)、必须登录(isNeedLogin=true,免登录清单为空);为写操作,不在免日志清单(_noNeedLog)中,记录操作日志(内部转调 report,走 STOCK_CHECK_REPORT 操作日志口径)。", "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内({ record, detail_id, mode, total_items, checked_items, diff_items, detail_status },与 report 完全一致)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。", "文档变更范围:methods/system.json 的 module=stock.check 分组新增 stock.check.markEmpty 一条(位于 stock.check.report 之后);分组内各 method notes 的「统一包装」描述与 workData「权限口径」note 中 ALL_METHOD_NAMES 方法清单由 20 增至 21 个(markEmpty 插在 report 之后);根版本 0.3.234 → 0.3.235、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);stock.check 分组由 20 条增至 21 条。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次先经 script/method-doc-create.cjs 在维护源新建本方法(--bump 版本 0.3.234→0.3.235),再按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入变更记录;随后同步回填开发库(显式 WMS_DB_TARGET=local,127.0.0.1:3307/wms)与生产库(显式 WMS_DB_TARGET=production,112.124.21.102:3306/wms)——import 当前 system.json → export 到临时文件往返校验,保持库与文件一致;stock.check 分组共 21 条 method 无损。" ] }, { "method": "stock.check.recordList", "description": "拉取盘点作业记录列表:至少传 id(盘点任务ID)或 detail_id(明细ID)之一(可同时传,detail_id 生效时只查该明细的作业记录);按当前用户仓库(ctx.user.store_id)限定数据范围;rows 每条为作业记录(wms_stock_check_record)全字段(id/check_id/warehouse_id/detail_id/stock_id/barcode/item_name/location_id/location_code/quantity/checker_id/checker_name/checked_at/is_empty/remark/created_at/updated_at 等)+ 商品信息列(item_code/item_name/spec/store_id/store_name/barcode,挂载口径对齐 workData);未知商品(stock_id 为空)商品编码列显示扫描条码(barcode)、名称列显示上报名称快照(item_name),spec/store_id/store_name 为 null、barcode=扫描条码;每条记录挂载 images(FileReference business_type=stock_check_record,仿收货 receivingItem 口径);按记录 id 倒序,分页返回。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(正常登录 token,携带仓库上下文)" } ], "params": [ { "name": "id", "type": "number", "required": false, "source": "body", "description": "盘点任务ID(可选;与 detail_id 至少传一个)" }, { "name": "detail_id", "type": "number", "required": false, "source": "body", "description": "盘点明细ID(可选;传了只查该明细的作业记录;与 id 至少传一个)" }, { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数 { page, pageSize },默认 page=1、pageSize=20,pageSize 上限 200(最小 1)" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记:success=成功 / failure=失败" }, { "name": "code", "type": "number", "required": true, "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { "name": "message", "type": "string", "required": true, "description": "提示信息:成功为 ok;失败为具体错误文案" }, { "name": "data", "type": "object", "required": true, "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", "children": [ { "name": "rows", "type": "array", "required": true, "description": "作业记录行列表:每条为 wms_stock_check_record 全字段(id/check_id/warehouse_id/detail_id/stock_id/location_id/location_code/quantity/checker_id/checker_name/checked_at/remark/barcode/item_name/is_empty/created_at/updated_at 等,保留记录全字段)+ 商品信息列 item_code/item_name/spec/store_id/store_name/barcode(挂载口径对齐 workData)+ images 图片列表 [{ id: file_id, url }](FileReference business_type=stock_check_record);stock_id 可空(NULL=未知商品);商品信息口径(对齐 workData):已知商品(stock_id 有值)item_code/item_name/spec 批量取自 stockWarehouse.getStockDetails(带缓存,未命中回退明细表 wms_stock_check_detail 商品快照)、store_id=商品货主ID、store_name=货主名(经 _resolveStoreNameMap 解析)、barcode=商品条码兜底(getStockDetails.barcodes[0],无则保留记录原始条码);未知商品(stock_id 为空)item_code=扫描条码(barcode,空则 null)、item_name=上报名称快照(item_name 或 barcode 兜底)、spec=null、store_id=null、store_name=null、barcode=扫描条码;location_code 口径:库中空串(\"无库位\"分组)返回时归一为 null(接口返回口径不变);is_empty 空库位标记:1=空库位标记记录(stock_id/barcode/item_name 均为 null、quantity=0)" }, { "name": "total", "type": "number", "required": true, "description": "总条数" }, { "name": "page", "type": "number", "required": true, "description": "当前页码" }, { "name": "pageSize", "type": "number", "required": true, "description": "每页条数" } ] }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": 400, "message": "请至少提供盘点任务ID或明细ID" }, { "code": 500, "message": "服务器内部错误" } ], "notes": [ "查询类方法,不记录操作日志(免日志清单:list/detail/result/recordList/export/exportTaskProgress)。", "rows 按记录 id 倒序返回。", "location_code 返回口径:库中空串(无库位分组)归一为 null,接口返回口径不变(与 detail 的 locations/location_codes 空库位组 location_code=null 一致)。", "商品信息挂载对齐 workData(本次更新):已知商品(stock_id 有值)item_code/item_name/spec 批量取自 stockWarehouse.getStockDetails(带缓存,未命中回退明细表 wms_stock_check_detail 商品快照),新增 store_id(商品货主ID)/store_name(货主名,经 _resolveStoreNameMap 解析)、barcode 兜底商品条码(getStockDetails.barcodes[0],无则保留记录原始条码);未知商品(stock_id 为空)item_code=扫描条码(barcode,空则 null)、item_name=上报名称快照(item_name 或 barcode 兜底)、spec=null、store_id=null、store_name=null、barcode=扫描条码。保留记录全字段不变、向后兼容(仅新增列)。代码依据:app/service/systems/stock_check.js#recordList。本次代码已改并测试通过 215/215、ESLint 0 错误。", "图片挂载口径(图片独立维护,仿收货 receivingItem):查询 wms_file_reference(business_type=stock_check_record)+ wms_file.file_url,每条记录挂载 images [{ id, url }],无图片返回空数组;上传走通用上传接口(businessType=stock_check_record + businessId=作业记录ID,建 FileReference)。", "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。", "空库位标记记录输出(本次新增):rows 每条为记录表全字段,is_empty 自动带出(1=空库位标记记录:stock_id/barcode/item_name 均为 null、quantity=0),未知商品显示口径不受影响。代码依据:app/service/systems/stock_check.js#recordList。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 5 条 method(stock.check.report:params 新增 is_empty 入参、errors 400 补「仅库位盘点明细支持空库位标记」、description/response/notes 补充空库位语义与互斥及汇总口径;stock.check.workData:description/response.rows 的 location 行新增 is_empty 字段说明;stock.check.result:description/response.rows 库位行新增 is_empty 与空标记盘亏口径;stock.check.recordList:response.rows 记录全字段说明新增 is_empty;stock.check.export:description/notes 补 Sheet2 空库位行输出口径);根版本 0.3.233 → 0.3.234、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 15 条 method 未改动(stock.check 分组仍为 20 条)。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 后,同步回填开发库(显式 WMS_DB_TARGET=local,127.0.0.1:3307/wms)与生产库(显式 WMS_DB_TARGET=production,112.124.21.102:3306/wms)——import 当前 system.json → export 到临时文件往返校验,保持库与文件一致;stock.check 分组共 20 条 method 无损。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.recordList 一条(description/response.rows 补充新增字段 spec/store_id/store_name 与 barcode 兜底口径(对齐 workData)、说明保留记录全字段;notes 补充「商品信息挂载对齐 workData」说明;headers/params/errors/isNeedAuth/isNeedLogin 不变);根版本 0.3.239 → 0.3.240、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 21 条 method 未改动(stock.check 分组仍为 22 条)。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 与变更记录后,同步回填开发库(显式 WMS_DB_TARGET=local,127.0.0.1:3307/wms)与生产库(显式 WMS_DB_TARGET=production,112.124.21.102:3306/wms)——import 当前 system.json → export 到临时文件往返校验,保持库与文件一致;stock.check 分组共 22 条 method 无损。" ] }, { "method": "stock.check.recordDelete", "description": "删除盘点作业记录(由旧版单值删除升级为批量删除,口径与 detailDelete 批量一致):入参 record_ids 数组(单次上限 200;兼容 recordIds 驼峰数组、recordId 单数驼峰、record_id 单值旧写法,单值自动转数组);仅主表状态 approved/checking 允许删除;记录必须属于该盘点任务与当前仓库,查不到的记录 ID 计入 skipped_ids 不报错(deleted_ids/skipped_ids 保持入参顺序);删除后清理该批记录的图片引用(FileReference business_type=stock_check_record,失败仅告警不影响主流程)、重算 checked_items/diff_items/detail_status(明细作业记录删光后回到未盘口径),主表状态不回退;写 STOCK_CHECK_DELETE_RECORD 操作日志(文案「批量删除盘点作业记录 N 条」)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(正常登录 token,携带仓库上下文)" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "盘点任务ID" }, { "name": "record_ids", "type": "array", "required": true, "source": "body", "description": "作业记录ID数组(wms_stock_check_record.id;单次上限 200;兼容旧版单值写法——传单值自动转数组)" }, { "name": "recordIds", "type": "array", "required": false, "source": "body", "description": "作业记录ID数组(驼峰别名,兼容写法;record_ids 优先)" }, { "name": "recordId", "type": "number", "required": false, "source": "body", "description": "作业记录ID(单数驼峰,兼容旧版单值写法;record_ids/recordIds 优先,单值自动转数组)" }, { "name": "record_id", "type": "number", "required": false, "source": "body", "description": "作业记录ID(旧版单值写法,兼容;record_ids/recordIds/recordId 优先,单值自动转数组)" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记:success=成功 / failure=失败" }, { "name": "code", "type": "number", "required": true, "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { "name": "message", "type": "string", "required": true, "description": "提示信息:成功为 ok;失败为具体错误文案" }, { "name": "data", "type": "object", "required": true, "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径见 data.children;失败时 data=null)", "children": [ { "name": "deleted_count", "type": "number", "required": true, "description": "实际删除的作业记录条数" }, { "name": "deleted_ids", "type": "array", "required": true, "description": "实际删除的作业记录ID列表(保持入参顺序)" }, { "name": "skipped_ids", "type": "array", "required": true, "description": "未删除(未命中:记录不存在或不属于该任务/仓库)的ID列表(保持入参顺序;查不到不报错)" }, { "name": "total_items", "type": "number", "required": true, "description": "明细总行数" }, { "name": "checked_items", "type": "number", "required": true, "description": "重算后的已盘行数(存在作业记录的明细数)" }, { "name": "diff_items", "type": "number", "required": true, "description": "重算后的差异行数(实盘合计与账面快照不一致的明细数;未知商品无账面,实盘>0 即盘盈、必然计入差异)" }, { "name": "detail_status", "type": "string", "required": true, "description": "重算后的明细盘点进度:none_checked/partial_checked/all_checked" } ] }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": 400, "message": "盘点任务ID不能为空" }, { "code": 400, "message": "盘点任务不存在" }, { "code": 400, "message": "当前状态(非 approved/checking)不允许删除作业记录" }, { "code": 400, "message": "请至少选择一条作业记录" }, { "code": 400, "message": "单次最多删除 200 条作业记录" }, { "code": 500, "message": "服务器内部错误" } ], "notes": [ "删除为写操作,记录操作日志(不在免日志清单),operationCode=STOCK_CHECK_DELETE_RECORD、文案「批量删除盘点作业记录 N 条」(N=deleted_count,附跳过数量)。", "批量口径(与 detailDelete 批量口径一致):查不到的记录 ID(记录不存在或不属于该任务/仓库)计入 skipped_ids 不报错;deleted_ids/skipped_ids 保持入参顺序;单值入参自动转数组。", "删除后仅重算盘点进度汇总(checked_items/diff_items/detail_status),主表状态不回退。", "图片清理口径(图片独立维护,仿收货):删除作业记录后同步清理 wms_file_reference(business_type=stock_check_record + business_id=记录ID),失败仅告警(warn 日志)不影响主流程。代码依据:app/service/systems/stock_check.js#recordDelete。", "本接口由旧版单值删除升级为批量删除(2026-10-02):旧版入参 record_id(兼容 recordId)、响应 { record_id, deleted, total_items, checked_items, diff_items, detail_status }、记录不存在报 400「作业记录不存在或不属于该盘点任务」;新版入参 record_ids 数组(单次上限 200)、响应 { deleted_count, deleted_ids, skipped_ids, total_items, checked_items, diff_items, detail_status }、查不到计入 skipped_ids 不报错(旧版 record_id/deleted 响应字段与「作业记录不存在」错误文案不再返回)。", "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径见 data.children。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。" ] }, { "method": "stock.check.recheckClearLocation", "description": "重盘清除库位(按库位清除盘点信息,库位盘点模式专属):传盘点任务ID与库位ID,清除该库位范围内明细(scope_type=location)的全部作业记录(含空库位标记),该库位回到未盘;仅任务范围为库位(type=location/all)且状态 approved/checking 允许;删除后清理被删记录图片引用(失败仅告警不影响主流程)、重算 checked_items/diff_items/detail_status(主表状态不回退)、写 STOCK_CHECK_CLEAR_LOCATION 操作日志。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(正常登录 token,携带仓库上下文)" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "盘点任务ID" }, { "name": "location_id", "type": "number", "required": true, "source": "body", "description": "库位ID(wms_location_space.id)" }, { "name": "locationId", "type": "number", "required": false, "source": "body", "description": "库位ID(驼峰别名,兼容写法;location_id 优先)" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记:success=成功 / failure=失败" }, { "name": "code", "type": "number", "required": true, "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { "name": "message", "type": "string", "required": true, "description": "提示信息:成功为 ok;失败为具体错误文案" }, { "name": "data", "type": "object", "required": true, "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内;失败时 data=null)", "children": [ { "name": "detail_id", "type": "number", "required": true, "description": "该库位范围明细ID(wms_stock_check_detail.id)" }, { "name": "location_id", "type": "number", "required": true, "description": "库位ID(与入参一致,wms_location_space.id)" }, { "name": "deleted_count", "type": "number", "required": true, "description": "删除的作业记录条数(该库位范围明细下全部作业记录,含空库位标记)" }, { "name": "total_items", "type": "number", "required": true, "description": "明细总行数" }, { "name": "checked_items", "type": "number", "required": true, "description": "重算后的已盘行数(存在作业记录的明细数)" }, { "name": "diff_items", "type": "number", "required": true, "description": "重算后的差异行数(实盘合计与账面快照不一致的明细数;未知商品无账面,实盘>0 即盘盈、必然计入差异)" }, { "name": "detail_status", "type": "string", "required": true, "description": "重算后的明细盘点进度:none_checked/partial_checked/all_checked" } ] }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": 400, "message": "盘点任务ID不能为空" }, { "code": 400, "message": "库位ID不能为空" }, { "code": 400, "message": "盘点任务不存在" }, { "code": 400, "message": "当前状态(非 approved/checking)不允许清除库位盘点信息" }, { "code": 400, "message": "仅库位盘点任务支持重盘清除库位" }, { "code": 400, "message": "该库位不在盘点任务范围内" }, { "code": 500, "message": "服务器内部错误" } ], "notes": [ "校验顺序口径(按代码实现顺序):任务ID 非正整数 → 400「盘点任务ID不能为空」;库位ID 非正整数 → 400「库位ID不能为空」;任务不存在(按 id+warehouse_id 查 wms_stock_check)→ 400「盘点任务不存在」;状态非 REPORT_ALLOWED_STATUSES(approved/checking)→ 400「当前状态(xx)不允许清除库位盘点信息」;任务范围非库位(type≠location/all)→ 400「仅库位盘点任务支持重盘清除库位」;库位不在任务范围(按 check_id+warehouse_id+location_id+scope_type=location 查 wms_stock_check_detail)→ 400「该库位不在盘点任务范围内」。代码依据:app/service/systems/stock_check.js#recheckClearLocation。", "行为口径:清除该库位范围内明细(scope_type=location)的全部作业记录(wms_stock_check_record,含空库位标记记录 is_empty=1),该库位回到未盘(明细无作业记录);删除后清理被删记录图片引用(FileReference business_type=stock_check_record,失败仅告警不影响主流程)、重算 checked_items/diff_items/detail_status(_recalcCheckSummary),主表状态不回退;写操作日志 operationCode=STOCK_CHECK_CLEAR_LOCATION(文案「重盘清除库位:删除作业记录 N 条」)。warehouse_id 由服务端从 ctx.user.store_id 自动注入,前端无需传递。", "权限口径:随 ALL_METHOD_NAMES(22 个,已由 21 增至 22、本次加入 recheckClearLocation,位于 recordDelete 之后)免 API 权限(isNeedAuth=false)、免仓库有效期鉴权(_noNeedAuth)、必须登录(isNeedLogin=true,免登录清单为空);为写操作,不在免日志清单(_noNeedLog)中,记录操作日志(STOCK_CHECK_CLEAR_LOCATION)。", "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内({ detail_id, location_id, deleted_count, total_items, checked_items, diff_items, detail_status })。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。", "文档变更范围:methods/system.json 的 module=stock.check 分组新增 stock.check.recheckClearLocation 一条(位于 stock.check.recordDelete 之后);分组内各 method notes 的「统一包装」描述由 21 个更新为 22 个、workData「权限口径」note 的 ALL_METHOD_NAMES 清单更新为 22 个(加入 recheckClearLocation);根版本 0.3.235 → 0.3.236、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);stock.check 分组由 21 条增至 22 条。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 与变更记录后,同步回填开发库(显式 WMS_DB_TARGET=local,127.0.0.1:3307/wms)与生产库(显式 WMS_DB_TARGET=production + --env production,112.124.21.102:3306/wms)——import 当前 system.json → export 到临时文件往返校验,保持库与文件一致;stock.check 分组共 22 条 method 无损。" ] }, { "method": "stock.check.finish", "description": "完成盘点作业(允许部分未盘完成):仅 approved/checking 状态允许;未盘商品明细=无作业记录(wms_stock_check_record)的明细,按实盘 0 处理(差异=-账面快照,计入盘亏与差异行数);未盘库位明细行因无法枚举商品不计差异;已盘商品明细按作业记录数量合计与账面快照(system_quantity)对比聚合;已盘库位明细按商品聚合实盘 vs wms_storage 账面(space_id+stock_id SUM(available_quantity+locked_quantity)=可用+锁定,space_id 为空时账面按 0)对比聚合;盘盈=正差异合计、盘亏=负差异绝对值合计;完成后主表置 completed、回填 end_time(完成盘点的时间)、detail_status=all_checked,返回差异汇总(盘盈/盘亏合计)与未盘明细数(unchecked_items)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(正常登录 token,携带仓库上下文)" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "盘点任务ID" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记:success=成功 / failure=失败" }, { "name": "code", "type": "number", "required": true, "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { "name": "message", "type": "string", "required": true, "description": "提示信息:成功为 ok;失败为具体错误文案" }, { "name": "data", "type": "object", "required": true, "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", "children": [ { "name": "id", "type": "number", "required": true, "description": "盘点任务ID" }, { "name": "status", "type": "string", "required": true, "description": "完成后的主表状态(completed)" }, { "name": "total_items", "type": "number", "required": true, "description": "明细总行数" }, { "name": "checked_items", "type": "number", "required": true, "description": "已盘行数(存在作业记录的明细数)" }, { "name": "unchecked_items", "type": "number", "required": true, "description": "未盘明细数(无作业记录的明细数;未盘商品明细按实盘 0 处理计为盘亏,未盘库位明细不计差异)" }, { "name": "diff_items", "type": "number", "required": true, "description": "差异行数(商品行实盘合计与账面快照不一致、库位行任一商品实盘与账面不一致的明细数,未盘商品明细按实盘 0 计入)" }, { "name": "profit_total", "type": "number", "required": true, "description": "盘盈合计(商品行:作业记录数量合计大于账面快照的差异合计;库位行:按商品实盘大于 wms_storage 账面(SUM(available_quantity+locked_quantity)=可用+锁定)的差异合计)" }, { "name": "loss_total", "type": "number", "required": true, "description": "盘亏合计(商品行:实盘小于账面快照的差异绝对值合计,含未盘明细的账面快照数;库位行:按商品实盘小于 wms_storage 账面的差异绝对值合计)" } ] }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": 400, "message": "盘点任务ID不能为空 / 盘点任务不存在 / 当前状态(非 approved/checking)不允许完成盘点" }, { "code": 500, "message": "服务器内部错误" } ], "notes": [ "库位行账面口径:wms_storage 按 (space_id, stock_id) SUM(available_quantity+locked_quantity)(=可用+锁定),与 detail 接口的 stocks 账面一致。", "未盘库位明细行无法枚举商品(无作业记录即无商品维度),完成时不计差异、不计盘盈盘亏。", "end_time 语义:完成盘点时主表写入 end_time(完成盘点的时间);接口响应不返回 end_time(响应结构不变:id/status/total_items/checked_items/unchecked_items/diff_items/profit_total/loss_total),主表时间字段请通过 detail/result/list 查看。", "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。" ] }, { "method": "stock.check.submit", "description": "完成盘点任务(提交审核):仅 created/rejected 状态允许;校验 total_items>0(无明细行时拒绝)后主表置 submitted(待审核);所有明细行(库位型 scope_type=location 与商品型 scope_type=goods)缺少库位(location_id 为空或 location_code 为空/空串)时不可提交(脏数据防御;商品任务按「商品+库位」拆行后商品行同样必须带库位,正常流程 addDetail/addLocationDetail 不会产生此类明细)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(正常登录 token,携带仓库上下文)" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "盘点任务ID" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记:success=成功 / failure=失败" }, { "name": "code", "type": "number", "required": true, "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { "name": "message", "type": "string", "required": true, "description": "提示信息:成功为 ok;失败为具体错误文案" }, { "name": "data", "type": "object", "required": true, "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", "children": [ { "name": "id", "type": "number", "required": true, "description": "盘点任务ID" }, { "name": "status", "type": "string", "required": true, "description": "提交后的主表状态(submitted)" } ] }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": 400, "message": "盘点任务ID不能为空 / 盘点任务不存在 / 当前状态(非 created/rejected)不允许提交审核 / 盘点任务还没有明细行,无法提交审核 / 存在缺少库位的盘点明细,无法提交审核" }, { "code": 500, "message": "服务器内部错误" } ], "notes": [ "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。", "提交校验口径(本次扩展):全部明细行(库位型 scope_type=location 与商品型 scope_type=goods)缺少库位(location_id 为空或 location_code 为空/空串)时抛 400「存在缺少库位的盘点明细,无法提交审核」——校验不再限定 scope_type=location(商品任务按「商品+库位」拆行后商品行同样必须带库位),脏数据防御,正常流程 addDetail/addLocationDetail 写入的明细均带有效库位。代码依据:app/service/systems/stock_check.js#submit(StockCheckDetail.count where check_id+(location_id 为空或 location_code 为空/空串)>0 即拒绝,不再按 scope_type 过滤)。本次代码已改并测试通过 213/213、ESLint 0 错误。", "影响面:前端无需改动——该校验拦截缺库位明细(含商品拆行后缺库位的历史脏数据),正常盘点流程不受影响;原有校验顺序不变(任务ID 为空→任务不存在→状态非 created/rejected→无明细行→缺库位明细)。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 5 条 method(stock.check.addDetail:description/params/response/notes 补商品拆行口径(拆多行、无库存库位 invalid、system_quantity=该库位账面、added=拆分行数);stock.check.detail:description/response.rows/notes 商品行 location_id/location_code 绑定库存库位;stock.check.submit:description/notes 缺库位校验改为覆盖全部明细行;stock.check.patternCreate:description/notes 补 goods 定式按库存库位拆行;stock.check.addLocationDetail:notes 幂等索引口径同步 uk_check_location 唯一约束放宽为普通索引 idx_check_location);根版本 0.3.237 → 0.3.238、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 17 条 method 未改动(stock.check 分组仍为 22 条)。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 与变更记录后,同步回填开发库(显式 WMS_DB_TARGET=local,127.0.0.1:3307/wms)与生产库(显式 WMS_DB_TARGET=production,112.124.21.102:3306/wms)——import 当前 system.json → export 到临时文件往返校验,保持库与文件一致;stock.check 分组共 22 条 method 无损。" ] }, { "method": "stock.check.cancel", "description": "取消盘点任务:仅 created/submitted/rejected 状态允许;取消后主表置 cancelled(终态)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(正常登录 token,携带仓库上下文)" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "盘点任务ID" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记:success=成功 / failure=失败" }, { "name": "code", "type": "number", "required": true, "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { "name": "message", "type": "string", "required": true, "description": "提示信息:成功为 ok;失败为具体错误文案" }, { "name": "data", "type": "object", "required": true, "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", "children": [ { "name": "id", "type": "number", "required": true, "description": "盘点任务ID" }, { "name": "status", "type": "string", "required": true, "description": "取消后的主表状态(cancelled)" } ] }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": 400, "message": "盘点任务ID不能为空 / 盘点任务不存在 / 当前状态(非 created/submitted/rejected)不允许取消" }, { "code": 500, "message": "服务器内部错误" } ], "notes": [ "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。" ] }, { "method": "stock.check.audit", "description": "审核盘点任务:仅 submitted 状态允许;action=approve → 主表置 approved(审核完成,待盘点作业);action=reject → 主表置 rejected(驳回,可重新添加明细再提交),reason 可选(缺省保留原备注)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(正常登录 token,携带仓库上下文)" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "盘点任务ID" }, { "name": "action", "type": "string", "required": true, "source": "body", "description": "审核动作:approve=通过 / reject=驳回" }, { "name": "reason", "type": "string", "required": false, "source": "body", "description": "驳回原因(写入备注,可选;缺省保留原备注)" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记:success=成功 / failure=失败" }, { "name": "code", "type": "number", "required": true, "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { "name": "message", "type": "string", "required": true, "description": "提示信息:成功为 ok;失败为具体错误文案" }, { "name": "data", "type": "object", "required": true, "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", "children": [ { "name": "id", "type": "number", "required": true, "description": "盘点任务ID" }, { "name": "status", "type": "string", "required": true, "description": "审核后的主表状态:approved(通过)/ rejected(驳回)" } ] }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": 400, "message": "盘点任务ID不能为空 / 审核动作仅支持 approve/reject / 盘点任务不存在 / 当前状态(非 submitted)不允许审核" }, { "code": 500, "message": "服务器内部错误" } ], "notes": [ "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。" ] }, { "method": "stock.check.batchDelete", "description": "批量删除盘点任务(仅删除已作废任务,非作废或查不到的任务跳过):入参 ids(盘点任务ID数组,兼容单值,服务端归一化为去重后的正整数,单次上限 200),warehouse_id 由服务端从当前登录上下文(ctx.user.store_id)自动注入,前端无需传递;按 id in ids + warehouse_id 查询主表做仓库隔离;状态分流:status=cancelled(作废)的任务级联删除,其他状态及查不到的任务跳过(计入 skipped_ids);删除级联顺序(事务内):先删作业记录(wms_stock_check_record,where check_id in 删除集),再删明细(wms_stock_check_detail,where check_id in 删除集),最后删主表(wms_stock_check,where id in 删除集);返回 { total, deleted_count, skipped_count, deleted_ids, skipped_ids },deleted_ids/skipped_ids 保持入参顺序。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(正常登录 token,携带仓库上下文)" } ], "params": [ { "name": "ids", "type": "array", "required": true, "source": "body", "description": "盘点任务ID数组(兼容单值;服务端归一化为去重后的正整数,单次上限 200)" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记:success=成功 / failure=失败" }, { "name": "code", "type": "number", "required": true, "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { "name": "message", "type": "string", "required": true, "description": "提示信息:成功为 ok;失败为具体错误文案" }, { "name": "data", "type": "object", "required": true, "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", "children": [ { "name": "total", "type": "number", "required": true, "description": "入参去重后的任务ID数量" }, { "name": "deleted_count", "type": "number", "required": true, "description": "实际删除的任务数量(仅作废任务)" }, { "name": "skipped_count", "type": "number", "required": true, "description": "跳过的任务数量(非作废状态或查不到的任务)" }, { "name": "deleted_ids", "type": "array", "required": true, "description": "已删除的任务ID列表(保持入参顺序)" }, { "name": "skipped_ids", "type": "array", "required": true, "description": "跳过的任务ID列表(保持入参顺序)" } ] }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": 400, "message": "无法获取当前仓库上下文 / ids 不能为空 / 单次最多删除 200 个盘点任务" }, { "code": 500, "message": "服务器内部错误" } ], "notes": [ "仅作废(status=cancelled)任务执行删除;其他状态及仓库内查不到的任务跳过(计入 skipped_ids,保持入参顺序),不视为业务错误。", "级联删除在事务内执行,顺序为:作业记录(StockCheckRecord)→ 明细(StockCheckDetail)→ 主表(StockCheck)。", "写操作:随 ALL_METHOD_NAMES(16 个 method)免 API 权限(isNeedAuth=false)、免仓库有效期鉴权,需登录(isNeedLogin=true);不在免日志清单(_noNeedLog),保留操作日志。", "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。" ] }, { "method": "stock.check.export", "description": "提交盘点任务导出任务(异步):Excel 分两个 Sheet 生成——Sheet1「盘点单」一行一个盘点任务(盘点单号/盘点名称/盘点范围/盘点方式/盘点状态/盘点进度/货主ID/创建人/明细行数/已盘行数/差异行数/开始时间/结束时间/备注;主表移除 check_date 后已移除「盘点日期」列,保留开始/结束时间列);Sheet2「盘点明细」一行一条实际盘点记录(作业记录 wms_stock_check_record,列:盘点单号/商品编码/商品名称/库位编码(空库位输出为空)/实盘数量/盘点人/盘点时间;未知商品(stock_id 为空)商品编码列显示扫描条码(barcode)、商品名称列显示上报名称快照(item_name),已知商品快照从 wms_stock_warehouse 补齐;空库位记录(is_empty=1)商品编码列输出「(空库位)」、商品名称为空、实盘数量输出 0),未盘的任务范围行不再导出;ExcelJS 流式生成后上传 COS;进度通过 Redis 缓存(key stock_check_export_task_*,TTL 1800 秒)追踪,立即返回任务ID;单次最多 50 个盘点任务。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(正常登录 token,携带仓库上下文)" } ], "params": [ { "name": "ids", "type": "array", "required": false, "source": "body", "description": "盘点任务ID数组(兼容单值;与 task_ids 二选一,优先级高于 task_ids)" }, { "name": "task_ids", "type": "array", "required": false, "source": "body", "description": "盘点任务ID数组(兼容别名)" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记:success=成功 / failure=失败" }, { "name": "code", "type": "number", "required": true, "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { "name": "message", "type": "string", "required": true, "description": "提示信息:成功为 ok;失败为具体错误文案" }, { "name": "data", "type": "object", "required": true, "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", "children": [ { "name": "task_id", "type": "string", "required": true, "description": "导出任务ID(格式 stock_check_export_{warehouseId}_{时间戳}_{随机串})" }, { "name": "status", "type": "string", "required": true, "description": "任务状态:submitted/running/success/failed/not_found" }, { "name": "progress", "type": "number", "required": true, "description": "进度百分比(0-100)" }, { "name": "current_count", "type": "number", "required": true, "description": "当前已处理明细行数(Sheet2 已写入的作业记录行数)" }, { "name": "total_count", "type": "number", "required": true, "description": "Sheet2 盘点明细总行数(作业记录总数,导出前即确定)" }, { "name": "message", "type": "string", "required": true, "description": "任务提示信息" }, { "name": "result", "type": "object", "required": false, "description": "任务成功时的结果对象(含 filename/fileKey/url/cdnUrl/cosUrl)" }, { "name": "error", "type": "string", "required": true, "description": "失败时的错误信息(可选)" }, { "name": "update_time", "type": "number", "required": true, "description": "最近一次状态更新时间戳(毫秒)" } ] }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": 400, "message": "请至少选择一个盘点任务 / 单次最多导出 50 个盘点任务" }, { "code": 400, "message": "未找到可导出的盘点任务" }, { "code": 500, "message": "服务器内部错误" } ], "notes": [ "兼容 ids / task_ids 两种入参写法,ids 优先;自动去重并过滤非正整数。", "异步执行:查询任务与作业记录(wms_stock_check_record,不按任务范围行展开)→ 商品快照从 wms_stock_warehouse 补齐(item_code/item_name)→ ExcelJS 流式写入(Sheet1「盘点单」一行一个盘点任务;Sheet2「盘点明细」一行一条实际盘点记录,列:盘点单号/商品编码/商品名称/库位编码(空库位输出为空)/实盘数量/盘点人/盘点时间,未盘的任务范围行不导出)→ COS 上传。", "进度缓存 Redis key stock_check_export_task_{taskId},TTL 1800 秒;totalCount=作业记录总数(导出前即确定),进度按已写入明细行数/总数计算(每 200 行汇报一次)。", "Sheet1「盘点单」一行一个盘点任务,列:盘点单号/盘点名称/盘点范围/盘点方式/盘点状态/盘点进度/货主ID/创建人/明细行数/已盘行数/差异行数/开始时间/结束时间/备注(主表移除 check_date 后不再导出「盘点日期」列,保留开始/结束时间列);Sheet2「盘点明细」由『按任务范围行展开(含未盘空行)』调整为『一行一条实际盘点记录(作业记录)』,未盘的任务范围行不再导出。", "未知商品导出口径:stock_id 为空的记录商品编码列输出扫描条码(barcode,空则留空)、商品名称列输出上报名称快照(item_name 或 barcode 兜底);已知商品维持 wms_stock_warehouse 商品快照(item_code/item_name)。代码依据:app/service/systems/stock_check.js#exportStockChecks/#_generateAndUploadStockCheckExcel。", "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。", "空库位标记导出口径(本次新增):Sheet2「盘点明细」空库位记录(is_empty=1)商品编码列输出『(空库位)』、商品名称列为空、实盘数量输出 0(row.is_empty ? '(空库位)' : (row.item_code || '')、row.is_empty ? '' : (row.item_name || '')、row.is_empty ? 0 : (Number(row.quantity) || 0))。代码依据:app/service/systems/stock_check.js#_generateAndUploadStockCheckExcel。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 5 条 method(stock.check.report:params 新增 is_empty 入参、errors 400 补「仅库位盘点明细支持空库位标记」、description/response/notes 补充空库位语义与互斥及汇总口径;stock.check.workData:description/response.rows 的 location 行新增 is_empty 字段说明;stock.check.result:description/response.rows 库位行新增 is_empty 与空标记盘亏口径;stock.check.recordList:response.rows 记录全字段说明新增 is_empty;stock.check.export:description/notes 补 Sheet2 空库位行输出口径);根版本 0.3.233 → 0.3.234、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 15 条 method 未改动(stock.check 分组仍为 20 条)。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 后,同步回填开发库(显式 WMS_DB_TARGET=local,127.0.0.1:3307/wms)与生产库(显式 WMS_DB_TARGET=production,112.124.21.102:3306/wms)——import 当前 system.json → export 到临时文件往返校验,保持库与文件一致;stock.check 分组共 20 条 method 无损。" ] }, { "method": "stock.check.exportTaskProgress", "description": "查询盘点任务导出进度:按 task_id(兼容 taskId 驼峰写法)读取 Redis 任务缓存;任务不存在时正常返回(status=not_found),不视为错误;任务成功时 download_url 从 result 兜底提取(url/cdnUrl/cosUrl/fileKey)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(正常登录 token,携带仓库上下文)" } ], "params": [ { "name": "task_id", "type": "string", "required": false, "source": "body", "description": "任务ID(下划线写法)" }, { "name": "taskId", "type": "string", "required": false, "source": "body", "description": "任务ID(驼峰写法)" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记:success=成功 / failure=失败" }, { "name": "code", "type": "number", "required": true, "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { "name": "message", "type": "string", "required": true, "description": "提示信息:成功为 ok;失败为具体错误文案" }, { "name": "data", "type": "object", "required": true, "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", "children": [ { "name": "task_id", "type": "string", "required": true, "description": "任务ID(未传任务ID时为空字符串)" }, { "name": "status", "type": "string", "required": true, "description": "任务状态:submitted/running/success/failed/not_found" }, { "name": "progress", "type": "number", "required": true, "description": "进度百分比(0-100)" }, { "name": "current_count", "type": "number", "required": true, "description": "当前已处理明细数" }, { "name": "total_count", "type": "number", "required": true, "description": "明细总行数" }, { "name": "message", "type": "string", "required": true, "description": "任务提示信息" }, { "name": "result", "type": "object", "required": false, "description": "任务成功时的结果对象(含 filename/fileKey/url/cdnUrl/cosUrl)" }, { "name": "error", "type": "string", "required": true, "description": "失败时的错误信息(可选)" }, { "name": "download_url", "type": "string", "required": true, "description": "任务完成后可直接下载的文件地址(从 result 兜底提取,未完成或未找到时为空字符串)" }, { "name": "update_time", "type": "number", "required": true, "description": "最近一次状态更新时间戳(毫秒)" } ] }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": 500, "message": "服务器内部错误" } ], "notes": [ "任务不存在为正常响应(status=not_found),非业务错误。", "进度缓存 Redis key stock_check_export_task_{taskId},TTL 1800 秒。", "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。" ] }, { "method": "stock.check.patternList", "description": "拉取盘点定式清单(供前端选择定式快速创建盘点任务):返回代码注册的 5 个内置定式(注册于 app/service/systems/stock_check_patterns.js,不建表),每条含 id/name/description/type;无入参。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(正常登录 token,携带仓库上下文)" } ], "params": [], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记:success=成功 / failure=失败" }, { "name": "code", "type": "number", "required": true, "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { "name": "message", "type": "string", "required": true, "description": "提示信息:成功为 ok;失败为具体错误文案" }, { "name": "data", "type": "object", "required": true, "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", "children": [ { "name": "patterns", "type": "array", "required": true, "description": "盘点定式列表(共 5 条:空库位/错发/临期/静态/预警),每条含 id/name/description/type", "children": [ { "name": "id", "type": "string", "required": true, "description": "定式唯一标识(patternCreate 的 pattern_id 入参):empty_location=空库位盘点 / mis_shipment=错发盘点 / expiring=临期盘点 / static=静态盘点 / warning=预警盘点" }, { "name": "name", "type": "string", "required": true, "description": "定式名称(创建任务时作为默认标题)" }, { "name": "description", "type": "string", "required": true, "description": "定式描述(含对象收集口径,详见 notes)" }, { "name": "type", "type": "string", "required": true, "description": "对应盘点任务 type:location=按库位(仅 empty_location)/ goods=按商品(其余 4 个)" } ] }, { "name": "total", "type": "number", "required": true, "description": "定式总数(当前为 5)" } ] }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": 500, "message": "服务器内部错误" } ], "notes": [ "5 个定式口径(与代码注释一致):① empty_location 空库位盘点(type=location):wms_location_space 中启用且未删除、在 wms_storage 不存在任何 quantity>0 库存记录的账面空库位;② mis_shipment 错发盘点(type=goods):登记过错发工单(wms_after_sale type=order 且 sub_type=mis_shipment,凡登记过即纳入、排除 closed/cancelled 状态)关联订单的商品按 stock_id 去重;③ expiring 临期盘点(type=goods):开启保质期管理(wms_stock_warehouse.is_shelf_life_mgmt=Y)且存在临期库存(最早到期日 <= 当前时间+该商品 remaining_threshold_days 天,阈值 <=0 时按已到期)的商品维度去重;④ static 静态盘点(type=goods):最后一次 INBOUND/OUTBOUND 流水(wms_stock_transaction)距今超过仓库配置 stock_static_hours 小时(默认 168,无流水按 wms_stock_warehouse.create_at)且未进入 wms_stock_static_check_task 的商品;⑤ warning 预警盘点(type=goods):库存 quantity < 仓库配置 stock_warning_quantity 的商品(要求仓库配置 stock_warning_enabled=true 才可执行)。", "查询类接口:免 API 权限(isNeedAuth=false)、免仓库有效期鉴权、必须登录(isNeedLogin=true);在免日志清单(_noNeedLog)中,不记录操作日志。", "返回字段仅对外 4 个(id/name/description/type),不含内部执行函数。", "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。" ] }, { "method": "stock.check.patternCreate", "description": "按定式快速创建盘点任务:入参 pattern_id(兼容 patternId 驼峰写法,pattern_id 优先)+ 可选 title/remark;warehouse_id 与创建人由服务端从登录上下文(ctx.user.store_id / ctx.user.id / employees_name)自动注入,前端无需传递;盘点方式由定式范围类型固定:库位类定式(empty_location,type=location)一律盲盘 blind、商品类定式(type=goods,其余 4 个)一律明盘 open;盘点方式与盘点时间均无需前端传入(主表已无 check_date,start_time=盘点开始时间(第一个盘点明细写入的时间)、end_time=盘点结束时间(完成盘点的时间),由盘点作业流程自动回填);按定式收集盘点对象(goods 型得到 stock_ids、location 型得到库位列表),goods 型明细同样按「商品+库位」拆行(商品任务必须按库位盘点,同 addDetail 商品路径),无符合条件对象报 400;创建后主表状态直接 submitted(进入待审核)、detail_status=none_checked、total_items 按明细重算;static 定式在任务创建成功后把命中的 stock_id 批量写入 wms_stock_static_check_task(失败不影响主流程);写操作,记录操作日志。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(正常登录 token,携带仓库上下文)" } ], "params": [ { "name": "pattern_id", "type": "string", "required": true, "source": "body", "description": "定式ID:empty_location=空库位盘点 / mis_shipment=错发盘点 / expiring=临期盘点 / static=静态盘点 / warning=预警盘点(兼容 patternId 驼峰写法,两者都传时 pattern_id 优先)" }, { "name": "patternId", "type": "string", "required": false, "source": "body", "description": "定式ID(驼峰别名,兼容写法)" }, { "name": "title", "type": "string", "required": false, "source": "body", "description": "盘点名称/主题,缺省取定式 name" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记:success=成功 / failure=失败" }, { "name": "code", "type": "number", "required": true, "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { "name": "message", "type": "string", "required": true, "description": "提示信息:成功为 ok;失败为具体错误文案" }, { "name": "data", "type": "object", "required": true, "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", "children": [ { "name": "check", "type": "object", "required": true, "description": "创建后的盘点任务信息(_formatCheckRow 口径:id/check_no/title/type/mode/store_id/status/detail_status/start_time/end_time/creator_id/creator_name/total_items/checked_items/diff_items/remark/created_at/updated_at,无 check_date);status 直接为 submitted(待审核),mode 由定式范围类型固定(location→blind、goods→open),start_time/end_time 创建时为空(分别由首个盘点明细写入与完成盘点回填)" }, { "name": "total_items", "type": "number", "required": true, "description": "明细总行数(创建明细后按 wms_stock_check_detail 重算)" }, { "name": "pattern_id", "type": "string", "required": true, "description": "本次创建使用的定式ID" } ] }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": 400, "message": "无法获取当前仓库上下文 / 盘点定式不存在 / 当前仓库没有账面为空的库位 / 没有符合条件的商品 / 未开启库存预警" }, { "code": 500, "message": "服务器内部错误" } ], "notes": [ "5 个定式口径(与代码注释一致):① empty_location 空库位盘点(type=location):wms_location_space 中启用且未删除、在 wms_storage 不存在任何 quantity>0 库存记录的账面空库位;② mis_shipment 错发盘点(type=goods):登记过错发工单(wms_after_sale type=order 且 sub_type=mis_shipment,凡登记过即纳入、排除 closed/cancelled 状态)关联订单的商品按 stock_id 去重;③ expiring 临期盘点(type=goods):开启保质期管理(is_shelf_life_mgmt=Y)且存在临期库存(最早到期日 <= 当前时间+remaining_threshold_days 天,阈值 <=0 时按已到期)的商品维度去重;④ static 静态盘点(type=goods):最后一次 INBOUND/OUTBOUND 流水距今超过仓库配置 stock_static_hours 小时(默认 168,无流水按 wms_stock_warehouse.create_at)且未进入 wms_stock_static_check_task 的商品;⑤ warning 预警盘点(type=goods):库存 quantity < 仓库配置 stock_warning_quantity 的商品(要求仓库配置 stock_warning_enabled=true 才可执行,未开启报 400「未开启库存预警」)。", "盘点方式与盘点时间固定规则(前端不传):盘点方式由定式范围类型固定——库位类定式(type=location,即 empty_location)一律盲盘(blind)、商品类定式(type=goods,其余 4 个定式)一律明盘(open);盘点时间不传(主表已无 check_date,start_time=盘点开始时间(第一个盘点明细写入的时间)、end_time=盘点结束时间(完成盘点的时间),由盘点作业流程自动回填);入参已移除 mode/check_date。", "状态口径:创建后主表 status 直接 submitted(进入待审核)、detail_status=none_checked,无需再调 stock.check.submit;store_id/scope_snapshot 为空,type 取定式类型(location/goods),mode 由定式范围类型固定(location→blind、goods→open),start_time/end_time 创建时为空。", "static 定式静态记录表口径:收集阶段排除 wms_stock_static_check_task 已有记录(未删除)的 stock_id(已进入静态已盘点商品);任务创建成功后把本次命中的 stock_id 批量写入该表(task_time=创建时间),写入失败仅记告警日志、不影响主流程。", "权限口径:免 API 权限(isNeedAuth=false)、免仓库有效期鉴权、必须登录(isNeedLogin=true);patternCreate 为写操作,不在免日志清单(_noNeedLog)中,记录操作日志(patternList 为查询类,免日志)。", "单号生成:check_no=PD+YYYYMMDD+6 位序号(全局递增不按仓库隔离),并发下撞 uk_check_no 唯一键自动重取重试(最多 5 次)。", "goods 定式拆行口径(本次改造):商品类定式(mis_shipment/expiring/static/warning,type=goods)收集到 stock_ids 后走 _addGoodsDetailRows 同款逻辑——按商品在仓库的启用库存库位(wms_storage is_enabled=1,按 space_id 分组 SUM)拆行,每个「商品+库位」一条 scope_type=goods 明细行(location_id/location_code 绑定库存库位、system_quantity=该库位库存 SUM);无启用库存库位的商品不产生明细行,total_items 按拆分行重算。代码依据:app/service/systems/stock_check.js#patternCreate(pattern.type==='goods' 调 _addGoodsDetailRows)。", "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。" ] }, { "method": "stock.check.addLocationDetail", "description": "批量添加库位明细(兼容入口,薄封装转调 addDetail 的库位ID直查路径):入参 id(盘点任务ID)+ location_ids(库位ID列表,兼容 locationIds 驼峰写法);服务端直接按 wms_location_space.id+warehouse_id 查库校验,不经过 space_code 二次解析;转发前保留旧口径参数校验(任务ID不能为空、库位ID不能为空、单次上限 200),任务存在性/状态/类型分派校验统一由 addDetail 处理;幂等添加 scope_type=location 明细行,已存在的同库位明细自动跳过;返回结构从 addDetail 映射为 { added, skipped, invalid_location_ids, total_items }(过滤 invalid_locations/invalid_stock_ids),保持原返回口径不变。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(正常登录 token,携带仓库上下文)" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "盘点任务ID" }, { "name": "location_ids", "type": "array", "required": true, "source": "body", "description": "库位ID列表(wms_location_space.id,单次上限 200;兼容 locationIds 驼峰写法,location_ids 优先)" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "请求结果标记:success=成功 / failure=失败" }, { "name": "code", "type": "number", "required": true, "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { "name": "message", "type": "string", "required": true, "description": "提示信息:成功为 ok;失败为具体错误文案" }, { "name": "data", "type": "object", "required": true, "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", "children": [ { "name": "added", "type": "number", "required": true, "description": "本次新增明细数" }, { "name": "skipped", "type": "number", "required": true, "description": "已存在被跳过(幂等)的盘点项数" }, { "name": "invalid_location_ids", "type": "array", "required": true, "description": "无效库位ID列表(按 wms_location_space.id 直查当前仓库不存在)" }, { "name": "total_items", "type": "number", "required": true, "description": "重算后的明细总行数" } ] }, { "name": "timestamp", "type": "number", "required": true, "description": "服务器时间戳(秒)" } ], "errors": [ { "code": 400, "message": "盘点任务ID不能为空 / 请至少选择一个库位 / 单次最多添加 200 个库位 / 盘点任务不存在 / 当前状态(非 created/rejected)不允许添加明细 / 当前盘点类型按商品盘点,不能添加库位明细" }, { "code": 500, "message": "服务器内部错误" } ], "notes": [ "兼容入口:保留旧接口名与返回结构({ added, skipped, invalid_location_ids, total_items }),内部转调 addDetail 库位ID直查路径(stockIds/locations 置空、传 locationIds),返回结构过滤 invalid_locations/invalid_stock_ids 保持原口径。", "转发前校验:任务ID不能为空、库位ID不能为空(请至少选择一个库位)、单次上限 200(超过报『单次最多添加 200 个库位』);任务不存在/状态不允许/商品任务不可添加库位明细由 addDetail 透传同款错误。", "ID 直查:按 wms_location_space.id+warehouse_id 直查校验(仓库隔离),查不到的 ID 记入 invalid_location_ids(不报错);幂等按 check_id+location_code(原 uk_check_location 唯一约束已放宽为普通索引 idx_check_location,幂等由应用层查重保证),已存在同库位明细跳过。", "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。" ] } ] }, { "groupName": "运单模块(仓库侧)", "module": "waybill.warehouse", "list": [ { "method": "waybill.warehouse.list", "description": "运单列表-仓库侧:分页查询运单号列表,支持多条件筛选。仓库隔离(自动注入 warehouse_id = ctx.user.store_id),所有查询仅返回当前仓库数据。通过快照字段(delivery_order_code、store_id_snapshot、store_name_snapshot、warehouse_name_snapshot)避免 JOIN 订单表和货主表,列表核心查询为 wms_order_express 单表 + SELF JOIN(主单号)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token,从中解析 warehouseId(仓库上下文,ctx.user.store_id)" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数。默认 page=1, pageSize=20" }, { "name": "pagination.page", "type": "number", "required": false, "source": "body.pagination", "description": "页码,默认 1" }, { "name": "pagination.pageSize", "type": "number", "required": false, "source": "body.pagination", "description": "每页条数,默认 20" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "筛选条件对象,所有字段均为可选" }, { "name": "where.waybillCode", "type": "string|string[]", "required": false, "source": "body.where", "description": "运单号筛选:字符串时为模糊搜索(LIKE '%值%',向后兼容);字符串数组时为精确匹配(Op.in,元素自动 trim 并过滤空值,空数组或全空值时不加该筛选条件)" }, { "name": "where.mainWaybillCode", "type": "string|string[]", "required": false, "source": "body.where", "description": "主单号筛选:字符串时为精确匹配(通过主单号定位 order_id,返回该订单下所有运单(主+子));字符串数组时按 Op.in 精确匹配多个主单号,返回这些主单对应订单下的全部运单(元素自动 trim 并过滤空值;全部不存在时返回空列表;空数组或全空值时不加该筛选条件)。与 waybillCode 同时传入时按 AND 叠加,不做互斥优先级处理" }, { "name": "where.orderId", "type": "number", "required": false, "source": "body.where", "description": "订单ID(等值匹配)" }, { "name": "where.orderNo", "type": "string", "required": false, "source": "body.where", "description": "订单号(模糊搜索,暂不可用,待快照字段就绪)" }, { "name": "where.waybillType", "type": "string", "required": false, "source": "body.where", "description": "运单类型:\"main\"/\"1\"=主单号(business_key=1),\"child\"/\"2\"=子单号(business_key>1)" }, { "name": "where.storeId", "type": "number", "required": false, "source": "body.where", "description": "货主ID(等值匹配)" }, { "name": "where.logisticsCode", "type": "string", "required": false, "source": "body.where", "description": "物流公司编码(等值匹配),如 SF/YT/STO/ZTO 等" }, { "name": "where.logisticsInterfaceId", "type": "number", "required": false, "source": "body.where", "description": "物流接口ID(等值匹配),对应 wms_order_express.logistics_interface_id" }, { "name": "where.platformCode", "type": "string", "required": false, "source": "body.where", "description": "平台编码(等值匹配),如 PDD/DY/KS/JD/CAINIAO/SPH/XHS" }, { "name": "where.status", "type": "number", "required": false, "source": "body.where", "description": "运单状态:0=未分配,1=已分配" }, { "name": "where.isBack", "type": "string", "required": false, "source": "body.where", "description": "是否退回:Y/N" }, { "name": "where.isIntercept", "type": "string", "required": false, "source": "body.where", "description": "是否拦截:Y/N" }, { "name": "where.isGalaxyReceive", "type": "string", "required": false, "source": "body.where", "description": "是否星河签收:Y/N" }, { "name": "where.packageMaterialId", "type": "number", "required": false, "source": "body.where", "description": "包材ID(等值匹配)" }, { "name": "where.hasWeighingWeight", "type": "boolean", "required": false, "source": "body.where", "description": "是否已称重:true=weighing_weight>0,false=weighing_weight=0" }, { "name": "where.keyword", "type": "string", "required": false, "source": "body.where", "description": "关键词搜索:同时匹配运单号(waybill_code)、主单号、订单号" }, { "name": "where.createdAt", "type": "object", "required": false, "source": "body.where", "description": "创建时间范围:{operator:\"between\", value:[起始时间, 结束时间]},value 为 ISO 8601 或 \"YYYY-MM-DD HH:mm:ss\" 字符串数组" }, { "name": "where.createdAtStart", "type": "string", "required": false, "source": "body.where", "description": "创建时间起始,格式 YYYY-MM-DD(兼容旧写法)" }, { "name": "where.createdAtEnd", "type": "string", "required": false, "source": "body.where", "description": "创建时间截止,格式 YYYY-MM-DD(兼容旧写法)" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数。默认 create_at desc" }, { "name": "sort.field", "type": "string", "required": false, "source": "body.sort", "description": "排序字段,白名单:create_at / weighing_weight / id" }, { "name": "sort.order", "type": "string", "required": false, "source": "body.sort", "description": "排序方向:asc / desc,默认 desc" } ], "response": [ { "name": "code", "type": "number", "required": true, "description": "业务状态码,200 表示成功" }, { "name": "message", "type": "string", "required": true, "description": "业务提示信息" }, { "name": "data", "type": "object", "required": true, "description": "成功时返回的运单列表数据", "children": [ { "name": "list", "type": "array", "required": true, "description": "运单列表数组", "children": [ { "name": "id", "type": "number", "required": true, "description": "运单记录ID(wms_order_express.id)" }, { "name": "waybill_code", "type": "string", "required": true, "description": "运单号" }, { "name": "main_waybill_code", "type": "string", "required": true, "description": "主单号。business_key=1 时等于 waybill_code 本身;business_key>1 时通过 SELF JOIN 查找同 order_id 下 business_key=1 的运单号" }, { "name": "waybill_type", "type": "string", "required": true, "description": "运单类型:business_key=1→'主单号',business_key>1→'子单号'" }, { "name": "order_id", "type": "number", "required": true, "description": "订单ID" }, { "name": "order_no", "type": "string", "required": true, "description": "订单号。优先取 wms_order_express.delivery_order_code(快照列),为空时回退取 source_order_codes" }, { "name": "source_order_codes", "type": "string", "required": true, "description": "原始订单号(平台订单号),来自 wms_order_express.source_order_codes 快照列" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "仓库ID" }, { "name": "warehouse_name", "type": "string", "required": true, "description": "仓库名称(来自 warehouse_name_snapshot 快照列)" }, { "name": "store_id", "type": "number", "required": true, "description": "货主ID(来自 wms_order_express.store_id)" }, { "name": "store_name", "type": "string", "required": true, "description": "货主名称。通过订单ID批量关联订单发货表(current/history/dispatch)获取 store_name 字段" }, { "name": "business_key", "type": "number", "required": true, "description": "拆单序号:1=主单号,>1=子单号" }, { "name": "status", "type": "number", "required": true, "description": "运单状态:0=未分配,1=已分配" }, { "name": "status_text", "type": "string", "required": true, "description": "状态文本:'未分配'/'已分配'" }, { "name": "logistics_interface_id", "type": "number", "required": false, "description": "物流接口ID" }, { "name": "logistics_code", "type": "string", "required": false, "description": "物流公司编码" }, { "name": "logistics_name", "type": "string", "required": false, "description": "物流公司名称" }, { "name": "logistics_interface_name", "type": "string", "required": false, "description": "物流接口名称" }, { "name": "platform_code", "type": "string", "required": false, "description": "平台编码" }, { "name": "platform_name", "type": "string", "required": false, "description": "平台名称(前端映射)" }, { "name": "is_back", "type": "string", "required": false, "description": "是否退回:Y/N" }, { "name": "is_intercept", "type": "string", "required": false, "description": "是否拦截:Y/N" }, { "name": "is_galaxy_receive", "type": "string", "required": false, "description": "是否星河签收:Y/N" }, { "name": "weighing_weight", "type": "number", "required": false, "description": "称重重量(单位:g)" }, { "name": "weighing_weight_display", "type": "string", "required": false, "description": "称重重量可读展示(如 '1.25 kg')" }, { "name": "package_material_id", "type": "number", "required": false, "description": "包材ID" }, { "name": "package_material_name", "type": "string", "required": false, "description": "包材名称(来自 package_material_name_snapshot 快照列)" }, { "name": "print_count", "type": "number", "required": false, "description": "打印次数(COUNT express_print_record)" }, { "name": "last_print_at", "type": "string", "required": false, "description": "最近打印时间" }, { "name": "create_at", "type": "string", "required": true, "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": [ { "code": "401", "message": "未登录,请先登录" }, { "code": "405", "message": "参数校验失败:{具体原因}" }, { "code": "500", "message": "服务器内部错误:运单列表查询失败" } ], "notes": [ "mainWaybillCode 支持字符串数组(2026-10-04):数组按 Op.in 精确匹配多个主单号,返回这些主单对应订单下的全部运单(主+子);单值保持原「先定位 order_id 再查」行为不变,且 order_id 条件保持标量。" ] }, { "method": "waybill.warehouse.detail", "description": "运单详情-仓库侧:查看单个运单的完整信息,包含关联订单、打印记录、称重信息。仓库隔离校验。支持按运单记录ID(id)或运单号(waybillCode)查询,waybillCode 优先。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token,从中解析 warehouseId(仓库上下文,ctx.user.store_id)" } ], "params": [ { "name": "id", "type": "number", "required": false, "source": "body", "description": "运单记录ID(wms_order_express.id)。与 waybillCode 二选一,waybillCode 优先" }, { "name": "waybillCode", "type": "string", "required": false, "source": "body", "description": "运单号。与 id 二选一,waybillCode 优先。需配合仓库隔离校验" } ], "response": [ { "name": "code", "type": "number", "required": true, "description": "业务状态码,200 表示成功" }, { "name": "message", "type": "string", "required": true, "description": "业务提示信息" }, { "name": "data", "type": "object", "required": true, "description": "成功时返回的运单详情数据", "children": [ { "name": "id", "type": "number", "required": true, "description": "运单记录ID" }, { "name": "waybill_code", "type": "string", "required": true, "description": "运单号" }, { "name": "main_waybill_code", "type": "string", "required": true, "description": "主单号" }, { "name": "waybill_type", "type": "string", "required": true, "description": "运单类型:'主单号'/'子单号'" }, { "name": "business_key", "type": "number", "required": true, "description": "拆单序号" }, { "name": "sibling_waybills", "type": "array", "required": false, "description": "同订单下所有运单(兄弟运单),含 waybill_code、business_key、waybill_type", "children": [ { "name": "waybill_code", "type": "string", "required": true, "description": "运单号" }, { "name": "business_key", "type": "number", "required": true, "description": "拆单序号" }, { "name": "waybill_type", "type": "string", "required": true, "description": "运单类型" } ] }, { "name": "order", "type": "object", "required": true, "description": "关联订单信息(通过 OrderDeliveryFactory 多表遍历查找)", "children": [ { "name": "order_id", "type": "number", "required": true, "description": "订单ID" }, { "name": "order_no", "type": "string", "required": true, "description": "订单号" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "仓库ID" }, { "name": "warehouse_name", "type": "string", "required": true, "description": "仓库名称(快照)" }, { "name": "store_id", "type": "number", "required": true, "description": "货主ID(快照)" }, { "name": "store_name", "type": "string", "required": true, "description": "货主名称(快照)" }, { "name": "wave_id", "type": "number", "required": false, "description": "波次ID" }, { "name": "wave_no", "type": "string", "required": false, "description": "波次号" }, { "name": "order_type", "type": "string", "required": false, "description": "订单类型:delivery/entry 等" } ] }, { "name": "logistics", "type": "object", "required": true, "description": "物流信息", "children": [ { "name": "logistics_code", "type": "string", "required": false, "description": "物流公司编码" }, { "name": "logistics_name", "type": "string", "required": false, "description": "物流公司名称" }, { "name": "logistics_interface_id", "type": "number", "required": false, "description": "物流接口ID" }, { "name": "logistics_interface_name", "type": "string", "required": false, "description": "物流接口名称" }, { "name": "platform_code", "type": "string", "required": false, "description": "平台编码" } ] }, { "name": "status_info", "type": "object", "required": true, "description": "运单状态信息", "children": [ { "name": "status", "type": "number", "required": true, "description": "运单状态:0=未分配,1=已分配" }, { "name": "status_text", "type": "string", "required": true, "description": "状态文本" }, { "name": "is_back", "type": "string", "required": false, "description": "是否退回" }, { "name": "is_intercept", "type": "string", "required": false, "description": "是否拦截" }, { "name": "is_galaxy_receive", "type": "string", "required": false, "description": "是否星河签收" } ] }, { "name": "weight", "type": "object", "required": false, "description": "称重信息", "children": [ { "name": "weighing_weight", "type": "number", "required": false, "description": "称重重量(g)" }, { "name": "weighing_weight_display", "type": "string", "required": false, "description": "称重重量可读展示" } ] }, { "name": "package", "type": "object", "required": false, "description": "包材信息", "children": [ { "name": "package_material_id", "type": "number", "required": false, "description": "包材ID" }, { "name": "package_material_name", "type": "string", "required": false, "description": "包材名称(快照)" } ] }, { "name": "print_records", "type": "array", "required": false, "description": "打印记录列表(LEFT JOIN express_print_record ON express_no = waybill_code)", "children": [ { "name": "id", "type": "number", "required": true, "description": "打印记录ID" }, { "name": "printer_name", "type": "string", "required": false, "description": "打印机名称" }, { "name": "template_id", "type": "number", "required": false, "description": "打印模板ID" }, { "name": "template_name", "type": "string", "required": false, "description": "打印模板名称" }, { "name": "platform", "type": "string", "required": false, "description": "平台" }, { "name": "printed_at", "type": "string", "required": false, "description": "打印时间" } ] }, { "name": "print_count", "type": "number", "required": false, "description": "打印次数" }, { "name": "printinfo", "type": "string", "required": false, "description": "打印信息(TEXT 字段)" }, { "name": "ver", "type": "string", "required": false, "description": "打印版本号" }, { "name": "retry_count", "type": "number", "required": false, "description": "重试次数" }, { "name": "create_at", "type": "string", "required": true, "description": "运单创建时间" }, { "name": "delete_at", "type": "string", "required": false, "description": "删除时间(软删除),null 表示未删除" } ] } ], "errors": [ { "code": "401", "message": "未登录,请先登录" }, { "code": "404", "message": "运单不存在" }, { "code": "405", "message": "参数校验失败:请提供运单ID或运单号" }, { "code": "405", "message": "无权访问该运单(仓库隔离校验不通过)" }, { "code": "500", "message": "服务器内部错误:运单详情查询失败" } ] }, { "method": "waybill.warehouse.export", "description": "运单导出-仓库侧:按筛选条件导出运单列表为 Excel 文件。复用 waybill.warehouse.list 的筛选逻辑,去掉分页,全量导出。导出为异步任务模式,立即返回任务受理信息,通过 exportTaskProgress 查询进度。仓库隔离(自动注入 warehouse_id)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token,从中解析 warehouseId(仓库上下文,ctx.user.store_id)" } ], "params": [ { "name": "where", "type": "object", "required": false, "source": "body", "description": "筛选条件对象,同 waybill.warehouse.list 的 where 参数,另支持 ids(运单ID数组,勾选导出)" }, { "name": "where.waybillCode", "type": "string|string[]", "required": false, "source": "body.where", "description": "运单号筛选:字符串时为模糊搜索(LIKE '%值%',向后兼容);字符串数组时为精确匹配(Op.in,元素自动 trim 并过滤空值,空数组或全空值时不加该筛选条件)" }, { "name": "where.mainWaybillCode", "type": "string|string[]", "required": false, "source": "body.where", "description": "主单号筛选:字符串/字符串数组均可(数组按 Op.in 精确匹配多个主单号),先定位 order_id 再导出对应订单下全部运单(元素自动 trim 并过滤空值,空数组或全空值时不加该筛选条件)" }, { "name": "where.ids", "type": "array", "required": false, "source": "body.where", "description": "运单ID列表(勾选导出,按 wms_order_express.id 精确过滤)" }, { "name": "where.orderId", "type": "number", "required": false, "source": "body.where", "description": "订单ID(等值匹配)" }, { "name": "where.orderNo", "type": "string", "required": false, "source": "body.where", "description": "订单号(模糊搜索,暂不可用,待快照字段就绪)" }, { "name": "where.waybillType", "type": "string", "required": false, "source": "body.where", "description": "运单类型:\"main\"/\"1\"=主单号,\"child\"/\"2\"=子单号" }, { "name": "where.storeId", "type": "number", "required": false, "source": "body.where", "description": "货主ID(等值匹配)" }, { "name": "where.logisticsCode", "type": "string", "required": false, "source": "body.where", "description": "物流公司编码(等值匹配)" }, { "name": "where.logisticsInterfaceId", "type": "number", "required": false, "source": "body.where", "description": "物流接口ID(等值匹配)" }, { "name": "where.platformCode", "type": "string", "required": false, "source": "body.where", "description": "平台编码(等值匹配)" }, { "name": "where.status", "type": "number", "required": false, "source": "body.where", "description": "运单状态:0=未分配,1=已分配" }, { "name": "where.isBack", "type": "string", "required": false, "source": "body.where", "description": "是否退回:Y/N" }, { "name": "where.isIntercept", "type": "string", "required": false, "source": "body.where", "description": "是否拦截:Y/N" }, { "name": "where.isGalaxyReceive", "type": "string", "required": false, "source": "body.where", "description": "是否星河签收:Y/N" }, { "name": "where.packageMaterialId", "type": "number", "required": false, "source": "body.where", "description": "包材ID(等值匹配)" }, { "name": "where.hasWeighingWeight", "type": "boolean", "required": false, "source": "body.where", "description": "是否已称重" }, { "name": "where.keyword", "type": "string", "required": false, "source": "body.where", "description": "关键词搜索" }, { "name": "where.createdAt", "type": "object", "required": false, "source": "body.where", "description": "创建时间范围:{operator:\"between\", value:[起始时间, 结束时间]},value 为 ISO 8601 或 \"YYYY-MM-DD HH:mm:ss\" 字符串数组" }, { "name": "where.createdAtStart", "type": "string", "required": false, "source": "body.where", "description": "创建时间起始,格式 YYYY-MM-DD(兼容旧写法)" }, { "name": "where.createdAtEnd", "type": "string", "required": false, "source": "body.where", "description": "创建时间截止,格式 YYYY-MM-DD(兼容旧写法)" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数,同 waybill.warehouse.list" }, { "name": "sort.field", "type": "string", "required": false, "source": "body.sort", "description": "排序字段:create_at / weighing_weight / id" }, { "name": "sort.order", "type": "string", "required": false, "source": "body.sort", "description": "排序方向:asc / desc" }, { "name": "exportFields", "type": "array", "required": false, "source": "body", "description": "需要导出的字段列表,不传则导出全部字段。可选字段:waybill_code, main_waybill_code, waybill_type, order_no, warehouse_name, store_name, business_key, status_text, logistics_code, logistics_name, logistics_interface_name, platform_code, weighing_weight, package_material_name, print_count, last_print_at, create_at" } ], "response": [ { "name": "code", "type": "number", "required": true, "description": "业务状态码,200 表示任务已受理" }, { "name": "message", "type": "string", "required": true, "description": "业务提示信息" }, { "name": "data", "type": "object", "required": true, "description": "成功时返回的导出任务受理信息(异步任务模式,不含导出数据)", "children": [ { "name": "task_id", "type": "string", "required": true, "description": "异步导出任务ID,前缀 waybill_export_,用于后续通过 exportTaskProgress 查询进度和获取下载链接" }, { "name": "status", "type": "string", "required": true, "description": "任务状态:submitted(已提交)/ running(执行中)/ success(成功)/ failed(失败)" }, { "name": "progress", "type": "number", "required": false, "description": "任务进度百分比(0-100)" }, { "name": "message", "type": "string", "required": false, "description": "任务状态说明" }, { "name": "update_time", "type": "string", "required": false, "description": "任务最近更新时间(ISO 8601)" } ] } ], "errors": [ { "code": "401", "message": "未登录,请先登录" }, { "code": "405", "message": "参数校验失败:{具体原因}" }, { "code": "500", "message": "服务器内部错误:运单导出任务创建失败" } ], "notes": [ "mainWaybillCode 支持字符串数组(2026-10-04):数组按 Op.in 精确匹配多个主单号,返回这些主单对应订单下的全部运单(主+子);单值保持原「先定位 order_id 再查」行为不变,且 order_id 条件保持标量。" ] }, { "method": "waybill.warehouse.exportTaskProgress", "description": "运单导出进度查询-仓库侧:按 task_id 或 taskId 查询异步导出任务的执行进度。任务进度通过 Redis 缓存存储,任务 ID 前缀 waybill_export_。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token,从中解析 warehouseId(仓库上下文,ctx.user.store_id)" } ], "params": [ { "name": "task_id", "type": "string", "required": false, "source": "body", "description": "异步导出任务ID(前缀 waybill_export_)。与 taskId 二选一,taskId 优先" }, { "name": "taskId", "type": "string", "required": false, "source": "body", "description": "异步导出任务ID(别名,优先使用)。至少传入 taskId 或 task_id 之一" } ], "response": [ { "name": "code", "type": "number", "required": true, "description": "业务状态码,200 表示成功" }, { "name": "message", "type": "string", "required": true, "description": "业务提示信息" }, { "name": "data", "type": "object", "required": true, "description": "成功时返回的导出任务进度信息", "children": [ { "name": "task_id", "type": "string", "required": true, "description": "任务ID" }, { "name": "status", "type": "string", "required": true, "description": "任务状态:submitted(已提交)/ running(执行中)/ success(成功)/ failed(失败)" }, { "name": "progress", "type": "number", "required": false, "description": "任务进度百分比(0-100)" }, { "name": "current_count", "type": "number", "required": false, "description": "当前已处理的运单记录数" }, { "name": "total_count", "type": "number", "required": false, "description": "需要导出的总运单记录数" }, { "name": "message", "type": "string", "required": false, "description": "任务状态说明或错误信息" }, { "name": "result", "type": "object", "required": false, "description": "任务执行结果(status=success 时返回)", "children": [ { "name": "total_exported", "type": "number", "required": false, "description": "实际导出的记录数" }, { "name": "file_size", "type": "number", "required": false, "description": "导出文件大小(字节)" } ] }, { "name": "error", "type": "string", "required": false, "description": "错误信息(status=failed 时返回)" }, { "name": "download_url", "type": "string", "required": false, "description": "导出文件下载地址(COS 临时签名 URL,status=success 时返回)" }, { "name": "update_time", "type": "string", "required": false, "description": "任务最近更新时间(ISO 8601)" } ] } ], "errors": [ { "code": "401", "message": "未登录,请先登录" }, { "code": "404", "message": "任务不存在或已过期" }, { "code": "405", "message": "参数校验失败:请提供 taskId 或 task_id" }, { "code": "500", "message": "服务器内部错误:导出进度查询失败" } ] } ] }, { "groupName": "API应用管理模块", "module": "apiApp", "list": [ { "method": "apiApp.list", "description": "查询当前仓库的 API 应用列表(分页),返回脱敏后的 AppSecret", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "page", "type": "number", "required": false, "source": "body", "description": "页码,默认 1" }, { "name": "pageSize", "type": "number", "required": false, "source": "body", "description": "每页数量,默认 20,最大 100" }, { "name": "app_name", "type": "string", "required": false, "source": "body", "description": "应用名称(模糊搜索)" }, { "name": "is_enabled", "type": "number", "required": false, "source": "body", "description": "启用状态:1-启用,0-停用" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "应用列表", "children": [ { "name": "id", "type": "number", "required": true, "description": "应用 ID" }, { "name": "app_name", "type": "string", "required": true, "description": "应用名称" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "仓库 ID" }, { "name": "interface_type_id", "type": "number", "required": true, "description": "接口类型 ID" }, { "name": "self_app_key", "type": "string", "required": true, "description": "自身 AppKey(对外提供)" }, { "name": "self_app_secret", "type": "string", "required": true, "description": "自身 AppSecret(脱敏,仅显示前8位+****)" }, { "name": "self_ip_whitelist", "type": "array", "required": false, "description": "IP 白名单", "children": [ { "name": "ip", "type": "string", "required": false, "description": "IP 地址或 CIDR" } ] }, { "name": "callback_url", "type": "string", "required": false, "description": "回调通知 URL" }, { "name": "callback_functions", "type": "array", "required": false, "description": "承接的出站回调 method 列表(空/未勾选=不承接任何回调)", "children": [ { "name": "method", "type": "string", "required": false, "description": "回调方法名,如 notify.reply" } ] }, { "name": "rate_limit", "type": "number", "required": false, "description": "速率限制(次/秒)" }, { "name": "sign_method", "type": "string", "required": false, "description": "签名方法(当前仅支持 md5)" }, { "name": "is_enabled", "type": "number", "required": false, "description": "启用状态:1-启用,0-停用" }, { "name": "created_at", "type": "string", "required": false, "description": "创建时间" }, { "name": "updated_at", "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": "总页数" }, { "name": "hasNext", "type": "boolean", "required": true, "description": "是否有下一页" }, { "name": "hasPrevious", "type": "boolean", "required": true, "description": "是否有上一页" } ] } ], "errors": [ { "code": "401", "message": "未登录,请先登录" }, { "code": "500", "message": "服务器内部错误:查询 API 应用列表失败" } ] }, { "method": "apiApp.detail", "description": "查询单个 API 应用详情", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "应用 ID" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "应用 ID" }, { "name": "app_name", "type": "string", "required": true, "description": "应用名称" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "仓库 ID" }, { "name": "interface_type_id", "type": "number", "required": true, "description": "接口类型 ID" }, { "name": "self_app_key", "type": "string", "required": true, "description": "自身 AppKey" }, { "name": "self_app_secret", "type": "string", "required": true, "description": "自身 AppSecret(脱敏)" }, { "name": "self_ip_whitelist", "type": "array", "required": false, "description": "IP 白名单" }, { "name": "callback_url", "type": "string", "required": false, "description": "回调通知 URL" }, { "name": "callback_functions", "type": "array", "required": false, "description": "承接的出站回调 method 列表(空/未勾选=不承接任何回调)" }, { "name": "rate_limit", "type": "number", "required": false, "description": "速率限制" }, { "name": "sign_method", "type": "string", "required": false, "description": "签名方法(当前仅支持 md5)" }, { "name": "is_enabled", "type": "number", "required": false, "description": "启用状态" }, { "name": "created_at", "type": "string", "required": false, "description": "创建时间" }, { "name": "updated_at", "type": "string", "required": false, "description": "更新时间" } ], "errors": [ { "code": "400", "message": "ID不能为空" }, { "code": "401", "message": "未登录,请先登录" }, { "code": "404", "message": "API应用不存在" }, { "code": "500", "message": "服务器内部错误:查询 API 应用详情失败" } ] }, { "method": "apiApp.create", "description": "创建 API 应用,自动生成 AppKey(AK{时间戳}{随机8位hex})和 AppSecret(64位hex)。仅创建时返回完整 Secret。签名方法固定为 md5", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "app_name", "type": "string", "required": true, "source": "body", "description": "应用名称,最大 200 字符" }, { "name": "interface_type_id", "type": "number", "required": false, "source": "body", "description": "接口类型 ID,不传则默认取 WH_CHANNEL 类型" }, { "name": "self_ip_whitelist", "type": "array", "required": false, "source": "body", "description": "IP 白名单,如 [\"192.168.1.1\", \"10.0.0.0/24\"]", "children": [ { "name": "ip", "type": "string", "required": false, "description": "IP 地址或 CIDR" } ] }, { "name": "callback_url", "type": "string", "required": false, "source": "body", "description": "API 回调通知 URL" }, { "name": "callback_functions", "type": "array", "required": false, "source": "body", "description": "承接的出站回调 method 列表,仅允许注册表中的方法(如 notify.reply);空数组/不传 = 不承接任何回调", "children": [ { "name": "method", "type": "string", "required": false, "description": "回调方法名" } ] }, { "name": "rate_limit", "type": "number", "required": false, "source": "body", "description": "速率限制(次/秒),默认 1000,范围 1-100000" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "应用 ID" }, { "name": "app_name", "type": "string", "required": true, "description": "应用名称" }, { "name": "self_app_key", "type": "string", "required": true, "description": "自动生成的 AppKey" }, { "name": "self_app_secret", "type": "string", "required": true, "description": "自动生成的 AppSecret(仅创建和重新生成时返回完整值,请妥善保存)" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "所属仓库 ID" }, { "name": "interface_type_id", "type": "number", "required": true, "description": "接口类型 ID" }, { "name": "callback_functions", "type": "array", "required": false, "description": "承接的出站回调 method 列表" }, { "name": "rate_limit", "type": "number", "required": false, "description": "速率限制" }, { "name": "sign_method", "type": "string", "required": false, "description": "签名方法(固定为 md5)" }, { "name": "is_enabled", "type": "number", "required": false, "description": "启用状态,创建后默认 1" }, { "name": "created_at", "type": "string", "required": false, "description": "创建时间" } ], "errors": [ { "code": "400", "message": "应用名称不能为空" }, { "code": "400", "message": "应用名称不能超过200个字符" }, { "code": "401", "message": "未登录,请先登录" }, { "code": "403", "message": "无法获取当前仓库ID" }, { "code": "500", "message": "服务器内部错误:创建 API 应用失败" } ] }, { "method": "apiApp.update", "description": "更新 API 应用(名称、白名单、回调地址、限流、启用状态),不可变字段:app_key、interface_type_id、sign_method(固定为 md5,不允许修改)", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "应用 ID" }, { "name": "app_name", "type": "string", "required": false, "source": "body", "description": "应用名称,最大 200 字符" }, { "name": "self_ip_whitelist", "type": "array", "required": false, "source": "body", "description": "IP 白名单" }, { "name": "callback_url", "type": "string", "required": false, "source": "body", "description": "回调通知 URL" }, { "name": "callback_functions", "type": "array", "required": false, "source": "body", "description": "承接的出站回调 method 列表,仅允许注册表中的方法;空数组 = 不承接任何回调", "children": [ { "name": "method", "type": "string", "required": false, "description": "回调方法名" } ] }, { "name": "rate_limit", "type": "number", "required": false, "source": "body", "description": "速率限制,范围 1-100000" }, { "name": "is_enabled", "type": "number", "required": false, "source": "body", "description": "启用状态:1-启用,0-停用" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "应用 ID" }, { "name": "app_name", "type": "string", "required": true, "description": "应用名称" }, { "name": "self_app_key", "type": "string", "required": true, "description": "AppKey(不可变)" }, { "name": "self_app_secret", "type": "string", "required": true, "description": "AppSecret(脱敏)" }, { "name": "callback_functions", "type": "array", "required": false, "description": "承接的出站回调 method 列表" }, { "name": "is_enabled", "type": "number", "required": false, "description": "启用状态" }, { "name": "updated_at", "type": "string", "required": false, "description": "更新时间" } ], "errors": [ { "code": "400", "message": "ID不能为空" }, { "code": "400", "message": "应用名称不能为空/不能超过200个字符" }, { "code": "400", "message": "签名方法当前仅支持 md5,不允许修改" }, { "code": "401", "message": "未登录,请先登录" }, { "code": "404", "message": "API应用不存在或不属于当前仓库" }, { "code": "500", "message": "服务器内部错误:更新 API 应用失败" } ] }, { "method": "apiApp.delete", "description": "停用 API 应用(软删除,设置 is_enabled=0,不物理删除数据)", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "应用 ID" } ], "response": { "type": "object", "properties": [] }, "errors": [ { "code": "400", "message": "ID不能为空" }, { "code": "401", "message": "未登录,请先登录" }, { "code": "404", "message": "API应用不存在或不属于当前仓库" }, { "code": "500", "message": "服务器内部错误:停用 API 应用失败" } ] }, { "method": "apiApp.regenerateSecret", "description": "重新生成 AppSecret,旧 Secret 立即失效。仅此次返回完整 Secret,请妥善保存", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "应用 ID" } ], "response": { "type": "object", "properties": [ { "name": "id", "type": "number", "description": "应用 ID" }, { "name": "app_name", "type": "string", "description": "应用名称" }, { "name": "self_app_key", "type": "string", "description": "AppKey(不变)" }, { "name": "self_app_secret", "type": "string", "description": "新生成的 AppSecret,64位十六进制(仅此次返回完整值,请妥善保存)" } ] }, "errors": [ { "code": "400", "message": "ID不能为空" }, { "code": "401", "message": "未登录,请先登录" }, { "code": "404", "message": "API应用不存在或不属于当前仓库" }, { "code": "500", "message": "服务器内部错误:重新生成 AppSecret 失败" } ] }, { "method": "apiApp.listCallbackFunctions", "description": "拉取出站回调 method 注册表(代码注册,供管理端多选列表使用;应用勾选后按 method 自动路由)", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [ { "name": "list", "type": "array", "required": true, "description": "可选的出站回调方法列表", "children": [ { "name": "method", "type": "string", "required": true, "description": "回调方法名(如 notify.reply)" }, { "name": "name", "type": "string", "required": true, "description": "方法显示名称" }, { "name": "description", "type": "string", "required": false, "description": "方法说明" } ] }, { "name": "total", "type": "number", "required": true, "description": "数量" } ], "errors": [ { "code": "401", "message": "未登录,请先登录" } ] } ] }, { "groupName": "站内信", "module": "inbox", "list": [ { "method": "inbox.message.list", "description": "站内信消息列表,支持货主/群/用户名/正文/来源等多条件筛选,时间字段使用统一格式化输出,分页返回(默认20条/页,最大200条)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(从中解析 warehouseId 仓库上下文)" } ], "params": [ { "name": "storeId", "type": "string", "required": false, "source": "body", "description": "货主ID筛选,支持逗号分隔多选,如 \"1000000,1000001\"" }, { "name": "groupId", "type": "string", "required": false, "source": "body", "description": "群ID筛选,支持逗号分隔多选" }, { "name": "groupName", "type": "string", "required": false, "source": "body", "description": "群名称模糊搜索" }, { "name": "userName", "type": "string", "required": false, "source": "body", "description": "用户名模糊搜索" }, { "name": "content", "type": "string", "required": false, "source": "body", "description": "正文模糊搜索" }, { "name": "sourceType", "type": "string", "required": false, "source": "body", "description": "来源类型筛选:im / api / system" }, { "name": "direction", "type": "string", "required": false, "source": "body", "description": "消息方向筛选:inbound(收件)/ outbound(回信)" }, { "name": "pushStatus", "type": "number", "required": false, "source": "body", "description": "推送状态筛选:0=待推送 1=推送中 2=已送达 3=失败" }, { "name": "startDate", "type": "string", "required": false, "source": "body", "description": "开始日期(created_at >=),格式 YYYY-MM-DD 或 YYYY-MM-DD HH:mm:ss" }, { "name": "endDate", "type": "string", "required": false, "source": "body", "description": "结束日期(created_at <=),格式 YYYY-MM-DD 或 YYYY-MM-DD HH:mm:ss" }, { "name": "page", "type": "number", "required": false, "source": "body", "description": "页码,默认 1", "defaultValue": 1 }, { "name": "pageSize", "type": "number", "required": false, "source": "body", "description": "每页数量,默认 20,最大 200", "defaultValue": 20 } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "消息列表(不含 ext_data、push_response、target_channel 字段,时间已格式化)", "children": [ { "name": "id", "type": "number", "required": true, "description": "消息ID" }, { "name": "ext_id", "type": "string", "required": true, "description": "外部唯一消息主键" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "所属仓库ID" }, { "name": "store_id", "type": "number", "required": false, "description": "关联货主ID" }, { "name": "store_name", "type": "string", "required": false, "description": "货主名称(批量回填)" }, { "name": "direction", "type": "string", "required": true, "description": "消息方向:inbound / outbound" }, { "name": "source_type", "type": "string", "required": true, "description": "来源类型:im / api / system" }, { "name": "target_type", "type": "string", "required": true, "description": "目标类型:im / api / webhook" }, { "name": "group_id", "type": "string", "required": false, "description": "外部群ID" }, { "name": "group_name", "type": "string", "required": false, "description": "群名称" }, { "name": "user_id", "type": "string", "required": false, "description": "外部用户ID" }, { "name": "user_name", "type": "string", "required": false, "description": "用户名称" }, { "name": "content", "type": "string", "required": false, "description": "消息正文/摘要" }, { "name": "push_status", "type": "number", "required": true, "description": "推送状态:0=待推送 1=推送中 2=已送达 3=失败" }, { "name": "retry_count", "type": "number", "required": true, "description": "已重试次数" }, { "name": "created_at", "type": "string", "required": true, "description": "创建时间(YYYY-MM-DD HH:mm:ss 格式化)" }, { "name": "updated_at", "type": "string", "required": true, "description": "更新时间(YYYY-MM-DD HH:mm:ss 格式化)" }, { "name": "pushed_at", "type": "string", "required": false, "description": "推送完成时间(YYYY-MM-DD HH:mm:ss 格式化)" } ] }, { "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": "总页数" }, { "name": "hasPrevious", "type": "boolean", "required": true, "description": "是否有上一页" }, { "name": "hasNext", "type": "boolean", "required": true, "description": "是否有下一页" } ] } ], "errors": [ { "code": "400", "message": "method 参数无效" }, { "code": "500", "message": "warehouseId 无效" } ] }, { "method": "inbox.message.detail", "description": "站内信消息详情,含完整 push_response 推送响应信息", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(从中解析 warehouseId 仓库上下文)" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "消息ID" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "消息ID" }, { "name": "ext_id", "type": "string", "required": true, "description": "外部唯一消息主键" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "所属仓库ID" }, { "name": "direction", "type": "string", "required": true, "description": "消息方向" }, { "name": "source_type", "type": "string", "required": true, "description": "来源类型" }, { "name": "target_type", "type": "string", "required": true, "description": "目标类型" }, { "name": "target_channel", "type": "string", "required": true, "description": "目标渠道" }, { "name": "target_url", "type": "string", "required": true, "description": "推送目标URL" }, { "name": "push_status", "type": "number", "required": true, "description": "推送状态" }, { "name": "retry_count", "type": "number", "required": true, "description": "已重试次数" }, { "name": "push_response", "type": "object", "required": false, "description": "推送目标响应(http_status, body, error)" }, { "name": "ext_data", "type": "object", "required": false, "description": "外部透传数据" }, { "name": "created_at", "type": "string", "required": true, "description": "创建时间" }, { "name": "updated_at", "type": "string", "required": true, "description": "更新时间" } ], "errors": [ { "code": "400", "message": "method 参数无效" }, { "code": "404", "message": "消息不存在或无权访问" }, { "code": "500", "message": "消息ID无效 / warehouseId 无效" } ] }, { "method": "inbox.message.thread", "description": "站内信对话链查询,返回原消息 + 所有回信(按 parent_id 递归),按时间升序排列", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(从中解析 warehouseId 仓库上下文)" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "消息ID(可为对话链中任意一条消息,自动向上查找根消息并收集所有回信)" } ], "response": [ { "name": "thread", "type": "array", "required": true, "description": "对话链消息数组,按时间升序排列,首元素为根消息,后续为回信" } ], "errors": [ { "code": "400", "message": "method 参数无效" }, { "code": "404", "message": "消息不存在或无权访问" }, { "code": "500", "message": "消息ID无效 / warehouseId 无效" } ] }, { "method": "inbox.message.reply", "description": "系统回信:写入 outbound 记录 + 异步推送到目标渠道。自动继承原消息的 ext_data、ref_code 等字段", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(从中解析 warehouseId 仓库上下文)" } ], "params": [ { "name": "parentId", "type": "number", "required": true, "source": "body", "description": "原消息ID(回信指向的原消息)" }, { "name": "targetChannel", "type": "string", "required": true, "source": "body", "description": "目标渠道:wecom / dingtalk / feishu / warehouse_api / webhook" }, { "name": "targetType", "type": "string", "required": false, "source": "body", "description": "目标类型:im / api / webhook,默认继承原消息的 target_type" }, { "name": "extData", "type": "object", "required": false, "source": "body", "description": "透传数据,默认继承原消息的 ext_data" }, { "name": "flags", "type": "object", "required": false, "source": "body", "description": "处理标记" } ], "response": [ { "name": "ok", "type": "boolean", "required": true, "description": "操作是否成功" }, { "name": "id", "type": "number", "required": true, "description": "回信记录 ID" }, { "name": "ext_id", "type": "string", "required": true, "description": "回信唯一标识(sys:{uuid})" } ], "errors": [ { "code": "400", "message": "method 参数无效 / parentId 无效 / targetChannel 不能为空 / targetUrl 不能为空" }, { "code": "404", "message": "原消息不存在或无权访问" }, { "code": "500", "message": "warehouseId 无效 / 回信失败" } ] }, { "method": "inbox.message.retry", "description": "手动重推失败(push_status=3)的站内信消息,重置为待推送状态并触发异步推送", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(从中解析 warehouseId 仓库上下文)" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "消息ID" } ], "response": [ { "name": "ok", "type": "boolean", "required": true, "description": "操作是否成功" }, { "name": "id", "type": "number", "required": true, "description": "消息ID" }, { "name": "ext_id", "type": "string", "required": true, "description": "外部唯一消息主键" }, { "name": "message", "type": "string", "required": true, "description": "操作结果描述" } ], "errors": [ { "code": "400", "message": "method 参数无效 / 仅失败状态的消息可以手动重推" }, { "code": "404", "message": "消息不存在或无权访问" }, { "code": "500", "message": "消息ID无效 / warehouseId 无效" } ] }, { "method": "inbox.message.stats", "description": "站内信推送统计:按方向汇总、按推送状态汇总、最近24小时新增数量", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(从中解析 warehouseId 仓库上下文)" } ], "params": [ { "name": "direction", "type": "string", "required": false, "source": "body", "description": "可选:按方向筛选统计(inbound / outbound),不传则统计全部" } ], "response": [ { "name": "total_by_direction", "type": "array", "required": true, "description": "按方向汇总统计", "children": [ { "name": "direction", "type": "string", "required": true, "description": "消息方向" }, { "name": "count", "type": "number", "required": true, "description": "消息数量" } ] }, { "name": "total_by_status", "type": "array", "required": true, "description": "按推送状态汇总统计", "children": [ { "name": "push_status", "type": "number", "required": true, "description": "推送状态:0/1/2/3" }, { "name": "count", "type": "number", "required": true, "description": "消息数量" } ] }, { "name": "recent_24h_count", "type": "number", "required": true, "description": "最近24小时新增消息数量" } ], "errors": [ { "code": "400", "message": "method 参数无效" }, { "code": "500", "message": "warehouseId 无效" } ] }, { "method": "inbox.bindCode", "description": "生成货主绑群码。校验 StoreWarehouse 合约有效后,生成12位随机码(大写字母+数字),缓存 key 为 chat:bind:{warehouseId}:{code},TTL 300秒。warehouseId 从 token 自动注入", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(从中解析 warehouseId 仓库上下文)" } ], "params": [ { "name": "storeId", "type": "number", "required": true, "source": "body", "description": "货主ID(需在目标仓库有有效合约 auth_status=2 warehouse_use_status=1)" }, { "name": "subType", "type": "string", "required": false, "source": "body", "description": "群子类型:after_sales(售后) / finance(财务) / receiving(收货)" } ], "response": [ { "name": "code", "type": "string", "required": true, "description": "12位绑群随机码(大写字母+数字),5分钟有效" } ], "errors": [ { "code": "400", "message": "storeId 无效 / 缺少仓库信息 / 子类型无效" }, { "code": "500", "message": "货主在仓库无有效合约" } ] }, { "method": "inbox.group.list", "description": "拉取当前仓库的群列表,支持按群类型筛选和关键词搜索,express_interfaces 逗号分隔存储输出为数组", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(从中解析 warehouseId 仓库上下文)" } ], "params": [ { "name": "groupType", "type": "string", "required": false, "source": "body", "description": "群类型筛选:store(货主) / warehouse(仓库) / express(快递)" }, { "name": "keyword", "type": "string", "required": false, "source": "body", "description": "群名称模糊搜索" }, { "name": "page", "type": "number", "required": false, "source": "body", "description": "页码,默认1" }, { "name": "pageSize", "type": "number", "required": false, "source": "body", "description": "每页条数,默认20,最大100" } ], "response": [ { "name": "total", "type": "number", "required": true, "description": "总记录数" }, { "name": "list", "type": "array", "required": true, "description": "群记录列表,含id/group_name/group_id/store_id/group_type/sub_type/is_blocked/ai_enabled/template_reply_enabled/express_interfaces(数组)/system_express_code/created_at" } ], "errors": [ { "code": "400", "message": "warehouseId 无效" } ] }, { "method": "inbox.group.disable", "description": "禁用或解禁群,通过群主键ID操作", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(从中解析 warehouseId 仓库上下文)" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "群记录主键ID" }, { "name": "isBlocked", "type": "number", "required": false, "source": "body", "description": "是否禁用:1=禁用 0=启用,默认1" } ], "response": [ { "name": "message", "type": "string", "required": true, "description": "操作结果提示:群已禁用 / 群已启用" } ], "errors": [ { "code": "400", "message": "群ID无效 / warehouseId 无效" }, { "code": "500", "message": "群不存在或无权限操作" } ] }, { "method": "inbox.group.update", "description": "修改群信息:群类型/子类型/货主/快递接口/系统快递编码/AI开关/模板消息回复开关。子类型受群类型约束,合法取值见 groupType.list[].subTypes。aiEnabled支持灰度控制,templateReplyEnabled控制命中处理后是否以模板消息形式回复(独立于aiEnabled),切换为express类型时systemExpressCode必填", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(从中解析 warehouseId 仓库上下文)" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "群记录主键ID" }, { "name": "groupType", "type": "string", "required": false, "source": "body", "description": "群类型:store(货主群) / warehouse(仓库群) / express(快递群)", "list": [ { "value": "store", "description": "货主群", "subTypes": [ { "value": "after_sales", "description": "售后" }, { "value": "finance", "description": "财务" }, { "value": "receiving", "description": "收货" } ] }, { "value": "warehouse", "description": "仓库群", "subTypes": [ { "value": "receiving", "description": "收货" }, { "value": "production", "description": "生产" }, { "value": "stockout", "description": "出库" }, { "value": "finance", "description": "财务" }, { "value": "all", "description": "全体" }, { "value": "customer_service", "description": "客服" }, { "value": "exception", "description": "异常" } ] }, { "value": "express", "description": "快递群", "subTypes": [ { "value": "pickup", "description": "揽收" }, { "value": "after_sales", "description": "售后" } ] } ] }, { "name": "subType", "type": "string", "required": false, "source": "body", "description": "群子类型,值取决于groupType。store→after_sales(售后)/finance(财务)/receiving(收货)。warehouse→receiving(收货)/production(生产)/stockout(出库)/finance(财务)/all(全体)/customer_service(客服)/exception(异常)。express→pickup(揽收)/after_sales(售后)" }, { "name": "storeId", "type": "number", "required": false, "source": "body", "description": "关联货主ID" }, { "name": "expressInterfaces", "type": "array", "required": false, "source": "body", "description": "快递接口ID数组,仅groupType=express时生效。空数组表示全部快递类型。需校验wms_express_interface.id存在" }, { "name": "systemExpressCode", "type": "string", "required": false, "source": "body", "description": "系统快递编码,groupType=express时必填。需校验wms_express.code存在" }, { "name": "aiEnabled", "type": "number", "required": false, "source": "body", "description": "是否启用AI自动回复: 0=关闭 1=开启,默认1(所有群类型均支持,用于灰度测试)" }, { "name": "templateReplyEnabled", "type": "number", "required": false, "source": "body", "description": "是否启用模板消息回复: 0=关闭(普通文本回复) 1=开启(模板消息回复),默认0(所有群类型均支持,独立于aiEnabled;开启后命中处理以模板消息形式回复)" } ], "response": [ { "name": "message", "type": "string", "required": true, "description": "操作结果提示:群信息修改成功" } ], "errors": [ { "code": "400", "message": "群ID无效 / 子类型不在对应群类型的合法范围内 / 系统快递编码不能为空(express类型时)" }, { "code": "500", "message": "群不存在或无权限操作 / 系统快递编码不存在 / 快递接口ID无效" } ] }, { "method": "inbox.group.reset", "description": "清空群类型配置:清空群类型/子类型/货主/快递接口/系统快递编码,AI开关与模板消息回复开关重置关闭,仅保留群创建时信息(群名称/群ID/仓库/来源/屏蔽状态/扩展数据)。入参群记录主键ID", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(从中解析 warehouseId 仓库上下文)" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "群记录主键ID" } ], "response": [ { "name": "message", "type": "string", "required": true, "description": "操作结果提示:群类型配置已清空" } ], "errors": [ { "code": "400", "message": "群ID无效" }, { "code": "500", "message": "群不存在或无权限操作" } ] }, { "method": "inbox.group.messages", "description": "按群拉取消息列表,支持方向/关键词筛选,分页返回。warehouseId服务端自动注入,查询命中idx_warehouse_group_created索引", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(从中解析 warehouseId 仓库上下文)" } ], "params": [ { "name": "groupId", "type": "string", "required": true, "source": "body", "description": "群ID(必填)" }, { "name": "direction", "type": "string", "required": false, "source": "body", "description": "消息方向筛选:inbound(入站) / outbound(出站)" }, { "name": "keyword", "type": "string", "required": false, "source": "body", "description": "关键词搜索(ext_id / content)" }, { "name": "page", "type": "number", "required": false, "source": "body", "description": "页码,默认1" }, { "name": "pageSize", "type": "number", "required": false, "source": "body", "description": "每页条数,默认20,最大200" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "消息记录列表" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息:page/pageSize/total/totalPages/hasPrevious/hasNext" } ], "errors": [ { "code": "400", "message": "groupId 不能为空 / warehouseId 无效" } ] }, { "method": "inbox.group.quickList", "description": "群快速查询(下拉选择用,不分页):关键词同时模糊匹配群名称与外部群ID,按创建时间倒序返回轻量字段,软删除记录自动排除;支持双维度可选过滤:store_id(货主维度,对应 wms_inbox_group.store_id 列)与 warehouse_id(仓库维度,对应 wms_inbox_group.warehouse_id 列)均可选,可单独传、可同时传(AND 关系),也可都不传(返回所有仓库/货主的群),非法值分别报「store_id 无效」「warehouse_id 无效」。需 566 权限(inbox.group.quickList,已授权仓库组-主管/客服组-主管/生产组-主管/经理,超级管理员与仓库管理员持通配符自动拥有)", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(登录凭证,权限校验用)" } ], "params": [ { "name": "store_id", "type": "number|string", "required": false, "source": "body", "description": "货主ID(可选,货主维度,对应 wms_inbox_group.store_id 列):传入时须为正整数,仅返回该货主的群;不传或为空时不加货主过滤(返回所有货主的群);与 warehouse_id 可单独传或同时传(AND 关系)" }, { "name": "warehouse_id", "type": "number|string", "required": false, "source": "body", "description": "仓库ID(可选,仓库维度,对应 wms_inbox_group.warehouse_id 列):传入时须为正整数,仅返回该仓库的群;不传或为空时不加仓库过滤(返回所有仓库的群);与 store_id 可单独传或同时传(AND 关系)" }, { "name": "keyword", "type": "string", "required": false, "source": "body", "description": "关键词,模糊匹配 group_name(群名称)与 group_id(外部群ID)" }, { "name": "groupType", "type": "string", "required": false, "source": "body", "description": "群类型筛选:store(货主) / warehouse(仓库) / express(快递)" }, { "name": "limit", "type": "number", "required": false, "source": "body", "description": "返回条数上限,默认20,最大100(无分页)" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "群快速列表(按创建时间倒序,无分页),每项含 id/group_id/group_name/group_type/sub_type/is_blocked/template_reply_enabled", "children": [ { "name": "id", "type": "number", "required": true, "description": "群记录主键ID(wms_inbox_group.id)" }, { "name": "group_id", "type": "string", "required": false, "description": "外部群ID(未绑定时为 null)" }, { "name": "group_name", "type": "string", "required": true, "description": "群名称" }, { "name": "group_type", "type": "string", "required": false, "description": "群类型:store / warehouse / express(未配置时为 null)" }, { "name": "sub_type", "type": "string", "required": false, "description": "群子类型(未配置时为 null)" }, { "name": "is_blocked", "type": "number", "required": true, "description": "是否屏蔽:1=屏蔽 0=正常" }, { "name": "template_reply_enabled", "type": "number", "required": true, "description": "是否启用模板消息回复:0=关闭(普通文本回复) 1=开启(模板消息回复)" } ] } ], "errors": [ { "code": "400", "message": "store_id 无效 / warehouse_id 无效" } ] }, { "method": "inbox.group.members", "description": "查询一个或多个群的成员列表(下拉选择用,多群聚合):先按内部主键ID数组+仓库批量校验群存在(软删除自动排除),再聚合所有群的外部群ID(去重、剔除空值),按外部群ID集合在消息表中聚合去重成员(每个 user_id 取最新一条消息的 user_name),关键词在聚合结果上过滤,最后截断到 limit 条;所有外部群ID为空时返回空列表。多群共享同一聚合池(最多取最近 500 条消息,更早消息中的成员不会出现在结果中);user_id 为 NULL/空串的消息被排除。warehouseId 由服务端从登录上下文自动注入。需 567 权限(inbox.group.members,已授权仓库组-主管/客服组-主管/生产组-主管/经理,超级管理员与仓库管理员持通配符自动拥有)", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(从中解析 warehouseId 仓库上下文)" } ], "params": [ { "name": "groupIds", "type": "array", "required": true, "source": "body", "description": "群记录主键ID数组(wms_inbox_group.id,必填,非空数组,每个元素为正整数,支持数字或可解析数字字符串)" }, { "name": "keyword", "type": "string", "required": false, "source": "body", "description": "关键词,模糊匹配 user_name(用户名)与 user_id(用户ID),对聚合结果做小写包含过滤" }, { "name": "limit", "type": "number", "required": false, "source": "body", "description": "返回条数上限,默认20,最大100(无分页)" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "群成员列表(多群聚合去重,无分页),每项含 user_id/user_name;所有群外部群ID为空时返回空列表", "children": [ { "name": "user_id", "type": "string", "required": true, "description": "成员用户ID(外部IM用户ID,跨群去重)" }, { "name": "user_name", "type": "string", "required": true, "description": "成员用户名(该用户最新一条消息的 user_name,无则为空字符串)" } ] } ], "errors": [ { "code": "400", "message": "groupIds 无效 / warehouseId 无效" }, { "code": "500", "message": "群不存在或无权限操作" } ] } ] }, { "groupName": "回信引擎配置(v2)", "module": "inbox", "list": [ { "method": "inbox.v2.type.list", "description": "售后类型列表(系统级+本仓库自定义,分页);warehouseId 从登录上下文注入", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "isEnabled", "type": "number", "required": false, "source": "body", "description": "启用状态筛选:1/0" }, { "name": "page", "type": "number", "required": false, "source": "body", "description": "页码,默认 1" }, { "name": "pageSize", "type": "number", "required": false, "source": "body", "description": "每页数量,默认 20,最大 200" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "类型列表" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息" } ] }, { "method": "inbox.v2.type.create", "description": "创建仓库自定义售后类型;系统级只读", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "type", "type": "string", "required": true, "source": "body", "description": "类型编码(≤20),仓库内唯一" }, { "name": "name", "type": "string", "required": true, "source": "body", "description": "类型名称(≤50)" }, { "name": "sortOrder", "type": "number", "required": false, "source": "body", "description": "排序值,默认 0" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "新类型ID" }, { "name": "message", "type": "string", "required": true, "description": "操作结果" } ] }, { "method": "inbox.v2.type.update", "description": "更新仓库自定义售后类型(name/isEnabled/sortOrder);系统预设类型拒绝修改", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "类型ID" }, { "name": "name", "type": "string", "required": false, "source": "body", "description": "新名称" }, { "name": "isEnabled", "type": "number", "required": false, "source": "body", "description": "1 启用 0 停用" }, { "name": "sortOrder", "type": "number", "required": false, "source": "body", "description": "排序值" } ], "response": [ { "name": "message", "type": "string", "required": true, "description": "操作结果" } ] }, { "method": "inbox.v2.type.delete", "description": "删除仓库自定义售后类型(无子类型引用才可删);系统预设类型拒绝删除", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "类型ID" } ], "response": [ { "name": "message", "type": "string", "required": true, "description": "操作结果" } ] }, { "method": "inbox.v2.subType.list", "description": "售后子类型列表(系统级+本仓库自定义,分页,可按类型/启用状态筛选)", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "type", "type": "string", "required": false, "source": "body", "description": "类型编码筛选" }, { "name": "isEnabled", "type": "number", "required": false, "source": "body", "description": "启用状态筛选:1/0" }, { "name": "page", "type": "number", "required": false, "source": "body", "description": "页码" }, { "name": "pageSize", "type": "number", "required": false, "source": "body", "description": "每页数量" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "子类型列表" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息" } ] }, { "method": "inbox.v2.subType.create", "description": "创建仓库自定义子类型(可挂在系统级类型或本仓库自定义类型下;子类型写入本仓库,后续关键词/函数/取号/白名单/回复均可写)", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "type", "type": "string", "required": true, "source": "body", "description": "所属类型编码" }, { "name": "subType", "type": "string", "required": true, "source": "body", "description": "子类型编码(≤50)" }, { "name": "name", "type": "string", "required": true, "source": "body", "description": "子类型名称(≤50)" }, { "name": "sortOrder", "type": "number", "required": false, "source": "body", "description": "排序值" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "新子类型ID" }, { "name": "message", "type": "string", "required": true, "description": "操作结果" } ] }, { "method": "inbox.v2.subType.update", "description": "更新仓库自定义子类型(name/isEnabled/sortOrder);系统预设拒绝修改", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "子类型ID" }, { "name": "name", "type": "string", "required": false, "source": "body", "description": "新名称" }, { "name": "isEnabled", "type": "number", "required": false, "source": "body", "description": "1 启用 0 停用" }, { "name": "sortOrder", "type": "number", "required": false, "source": "body", "description": "排序值" } ], "response": [ { "name": "message", "type": "string", "required": true, "description": "操作结果" } ] }, { "method": "inbox.v2.subType.delete", "description": "删除仓库自定义子类型,自动级联清理关联(关键词/函数关联/取号关联/群白名单/回复);系统预设拒绝删除", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "子类型ID" } ], "response": [ { "name": "message", "type": "string", "required": true, "description": "操作结果(含级联清理统计)" } ] }, { "method": "inbox.v2.keyword.list", "description": "关键词列表(系统级+本仓库自定义,分页,可按子类型/启用状态筛选)", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "subTypeId", "type": "number", "required": false, "source": "body", "description": "子类型ID筛选" }, { "name": "isEnabled", "type": "number", "required": false, "source": "body", "description": "启用状态筛选" }, { "name": "page", "type": "number", "required": false, "source": "body", "description": "页码" }, { "name": "pageSize", "type": "number", "required": false, "source": "body", "description": "每页数量" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "关键词列表" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息" } ] }, { "method": "inbox.v2.keyword.create", "description": "创建仓库自定义关键词(关键词为仓库级数据,可绑定系统级或本仓库自定义子类型;同一仓库内关键词唯一);系统预设关键词只读", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "subTypeId", "type": "number", "required": true, "source": "body", "description": "子类型ID" }, { "name": "keyword", "type": "string", "required": true, "source": "body", "description": "关键词(≤100),仓库内唯一" }, { "name": "sortOrder", "type": "number", "required": false, "source": "body", "description": "排序值" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "新关键词ID" }, { "name": "message", "type": "string", "required": true, "description": "操作结果" } ] }, { "method": "inbox.v2.keyword.update", "description": "更新仓库自定义关键词(keyword/subTypeId/isEnabled/sortOrder);系统预设拒绝修改", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "关键词ID" }, { "name": "keyword", "type": "string", "required": false, "source": "body", "description": "新关键词" }, { "name": "subTypeId", "type": "number", "required": false, "source": "body", "description": "新子类型ID" }, { "name": "isEnabled", "type": "number", "required": false, "source": "body", "description": "1 启用 0 停用" }, { "name": "sortOrder", "type": "number", "required": false, "source": "body", "description": "排序值" } ], "response": [ { "name": "message", "type": "string", "required": true, "description": "操作结果" } ] }, { "method": "inbox.v2.keyword.delete", "description": "删除仓库自定义关键词;系统预设拒绝删除", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "关键词ID" } ], "response": [ { "name": "message", "type": "string", "required": true, "description": "操作结果" } ] }, { "method": "inbox.v2.numberRule.list", "description": "取号规则列表(全局资源只读,含 target/regexp/sort_order,供关联配置选择)", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [], "response": [ { "name": "list", "type": "array", "required": true, "description": "取号规则列表" } ] }, { "method": "inbox.v2.function.list", "description": "处理函数列表(代码同步权威,含 in_registry 标记与 isEnabled 开关;可按启用状态/关键词筛选)", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "isEnabled", "type": "number", "required": false, "source": "body", "description": "启用状态筛选" }, { "name": "keyword", "type": "string", "required": false, "source": "body", "description": "编码/名称模糊搜索" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "函数列表(含 in_registry)" } ] }, { "method": "inbox.v2.function.update", "description": "更新函数排序(是否启用由代码硬编码,不做接口配置)", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "函数ID" }, { "name": "sortOrder", "type": "number", "required": false, "source": "body", "description": "排序值" } ], "response": [ { "name": "message", "type": "string", "required": true, "description": "操作结果" } ] }, { "method": "inbox.v2.reply.merged", "description": "回复配置合并后生效配置:以全部有效子类型(系统级+本仓库)为基底,每子类型一条、全量返回;本仓库有自定义则返回仓库级并标记 is_custom=1,否则返回系统级(is_custom=0,warehouse_id=null);无回复配置的子类型返回初始值(id=null,reply={back_text},is_reply=1,create_work_order=1);无启用状态字段,停用即回退系统级由 restore 承担", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "subTypeId", "type": "number", "required": false, "source": "body", "description": "子类型ID筛选" } ], "response": [ { "name": "merged", "type": "array", "required": true, "description": "合并后生效配置全量列表;元素字段:id/sub_type_id/type/sub_type/sub_type_name/warehouse_id/is_custom(1仓库级 0系统级)/reply/is_reply/create_work_order/no_number_hint/created_at/updated_at" }, { "name": "total", "type": "number", "required": true, "description": "总条数" } ] }, { "method": "inbox.v2.reply.create", "description": "创建仓库级回复配置(每子类型一条,仓库级覆盖系统级;isReply=0 表示命中后静默;createWorkOrder=0 表示函数照常执行但内部跳过工单登记)", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "subTypeId", "type": "number", "required": true, "source": "body", "description": "子类型ID" }, { "name": "reply", "type": "string", "required": true, "source": "body", "description": "回复文案(支持 {keyword}/{express}/{sub_type_name}/{back_text} 占位符)" }, { "name": "isReply", "type": "number", "required": false, "source": "body", "description": "1 回复 0 静默,默认 1" }, { "name": "createWorkOrder", "type": "number", "required": false, "source": "body", "description": "1 函数正常创建工单(默认) 0 函数照常执行但内部跳过工单登记" }, { "name": "noNumberHint", "type": "string", "required": false, "source": "body", "description": "未取到单据号时的引导语(≤500)" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "新回复ID" }, { "name": "message", "type": "string", "required": true, "description": "操作结果" } ] }, { "method": "inbox.v2.reply.update", "description": "更新仓库级回复配置;系统级回复只读", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "回复ID" }, { "name": "reply", "type": "string", "required": false, "source": "body", "description": "新回复文案" }, { "name": "isReply", "type": "number", "required": false, "source": "body", "description": "1 回复 0 静默" }, { "name": "createWorkOrder", "type": "number", "required": false, "source": "body", "description": "1 函数正常创建工单 0 函数照常执行但内部跳过工单登记" }, { "name": "noNumberHint", "type": "string", "required": false, "source": "body", "description": "取号失败引导语" } ], "response": [ { "name": "message", "type": "string", "required": true, "description": "操作结果" } ] }, { "method": "inbox.v2.reply.delete", "description": "删除仓库级回复配置;系统级回复只读", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "回复ID" } ], "response": [ { "name": "message", "type": "string", "required": true, "description": "操作结果" } ] }, { "method": "inbox.v2.reply.save", "description": "保存仓库级回复配置(upsert,推荐接口):按传入字段保存,未传字段保持原值;无仓库级配置时按传入字段创建", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "subTypeId", "type": "number", "required": true, "source": "body", "description": "子类型ID" }, { "name": "reply", "type": "string", "required": false, "source": "body", "description": "回复文案(≤2000)" }, { "name": "isReply", "type": "number", "required": false, "source": "body", "description": "1 回复 0 静默,默认 1" }, { "name": "createWorkOrder", "type": "number", "required": false, "source": "body", "description": "1 函数正常创建工单 0 函数照常执行但内部跳过工单登记" }, { "name": "noNumberHint", "type": "string", "required": false, "source": "body", "description": "取号失败引导语(≤500)" } ], "response": [ { "name": "message", "type": "string", "required": true, "description": "操作结果" } ] }, { "method": "inbox.v2.reply.restore", "description": "还原仓库级回复配置:删除仓库级行,回退到系统级配置(幂等,无仓库级配置时返回已是系统级)", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "subTypeId", "type": "number", "required": true, "source": "body", "description": "子类型ID" } ], "response": [ { "name": "message", "type": "string", "required": true, "description": "操作结果" } ] }, { "method": "inbox.v2.relation.function.list", "description": "查询子类型的处理函数关联列表(含函数编码/名称,按 sort_order)", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "subTypeId", "type": "number", "required": true, "source": "body", "description": "子类型ID" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "关联列表" } ] }, { "method": "inbox.v2.relation.function.set", "description": "全量替换子类型的处理函数关联(items=[{functionId,sortOrder}]);仅本仓库自定义子类型可写,系统子类型关联只读", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "subTypeId", "type": "number", "required": true, "source": "body", "description": "子类型ID" }, { "name": "items", "type": "array", "required": true, "source": "body", "description": "函数关联数组 [{functionId, sortOrder}]" } ], "response": [ { "name": "message", "type": "string", "required": true, "description": "操作结果" } ] }, { "method": "inbox.v2.relation.rule.list", "description": "查询子类型的取号规则关联列表(含 target/规则名,按 sort_order)", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "subTypeId", "type": "number", "required": true, "source": "body", "description": "子类型ID" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "关联列表" } ] }, { "method": "inbox.v2.relation.rule.set", "description": "全量替换子类型的取号规则关联(items=[{ruleId,sortOrder}]);仅本仓库自定义子类型可写", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "subTypeId", "type": "number", "required": true, "source": "body", "description": "子类型ID" }, { "name": "items", "type": "array", "required": true, "source": "body", "description": "取号规则关联数组 [{ruleId, sortOrder}]" } ], "response": [ { "name": "message", "type": "string", "required": true, "description": "操作结果" } ] }, { "method": "inbox.v2.relation.group.list", "description": "查询子类型的群类型白名单关联列表(group_type + sub_group,含 is_system;sub_group='*' 表示主类型内所有子类型通配,group_type='*' 表示所有群)", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "subTypeId", "type": "number", "required": true, "source": "body", "description": "子类型ID" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "白名单关联列表" } ] }, { "method": "inbox.v2.relation.group.set", "description": "替换子类型的群白名单关联(items=[{groupType,subGroup,sortOrder}],groupType∈store/warehouse/express/'*';subGroup 支持 '*' 通配主类型下所有子类型且覆盖该主类型其他具体行;groupType='*' 表示所有群且覆盖其他具体类型行(subGroup 忽略,归一化为空));系统预设行(is_system=1)保留不可删", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "subTypeId", "type": "number", "required": true, "source": "body", "description": "子类型ID" }, { "name": "items", "type": "array", "required": true, "source": "body", "description": "白名单数组 [{groupType, subGroup, sortOrder}];subGroup='*' 表示该主类型下所有子类型通配,groupType='*' 表示所有群" } ], "response": [ { "name": "message", "type": "string", "required": true, "description": "操作结果" } ] } ] }, { "groupName": "店铺快递绑定策略模块", "module": "storeExpressBindingPolicy", "list": [ { "method": "storeExpressBindingPolicy.list", "description": "分页查询策略列表,按priority DESC updated_at DESC排序", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "page", "type": "number", "required": false, "source": "body", "description": "页码,兼容pagination.page/currentPage" }, { "name": "pageSize", "type": "number", "required": false, "source": "body", "description": "每页大小,兼容page_size/pagination.page_size,最大200" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "字段兼容id/custom_name/shop_name(数组)/store_ids(数组)/express_code/priority/is_enabled/regions(数组)/exclude_regions(数组)/prohibited_type_id(数组)/weight_type/min_weight_g/max_weight_g/creator_id/quickWhere" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "调用成功为success" }, { "name": "code", "type": "number", "required": true, "description": "业务状态码" }, { "name": "message", "type": "string", "required": true, "description": "提示信息" }, { "name": "data.list", "type": "array", "required": true, "description": "策略数组shop_name/store_ids/regions/exclude_regions/prohibited_type_id均为JSON数组,附带store_names/prohibited_type_names文本数组,express_name为快递名称" }, { "name": "data.list[].store_names", "type": "array", "required": false, "description": "货主名称文本数组,与store_ids一一对应" }, { "name": "data.list[].prohibited_type_names", "type": "array", "required": false, "description": "违禁品类型名称文本数组,与prohibited_type_id一一对应" }, { "name": "data.list[].express_name", "type": "string", "required": false, "description": "快递名称(含系统快递和自定义映射)" }, { "name": "data.pagination", "type": "object", "required": true, "description": "业务状态码" } ], "errors": [ { "code": 400, "message": "参数错误" }, { "code": 401, "message": "未认证" } ] }, { "method": "storeExpressBindingPolicy.add", "description": "新增策略。必填custom_name+express_code。weight_type默认0。同仓库custom_name唯一", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "custom_name", "type": "string", "required": true, "source": "body", "description": "策略名称同仓库唯一兼容customName" }, { "name": "shop_name", "type": "array", "required": false, "source": "body", "description": "包含店铺名称字符串数组兼容shopName" }, { "name": "store_ids", "type": "array", "required": false, "source": "body", "description": "限定货主ID数字数组兼容storeIds" }, { "name": "express_code", "type": "string", "required": true, "source": "body", "description": "快递编码兼容expressCode" }, { "name": "priority", "type": "number", "required": false, "source": "body", "description": "优先级默认0" }, { "name": "is_enabled", "type": "number", "required": false, "source": "body", "description": "0停用1启用默认1兼容isEnabled" }, { "name": "regions", "type": "array", "required": false, "source": "body", "description": "限定地区字符串数组" }, { "name": "exclude_regions", "type": "array", "required": false, "source": "body", "description": "排除地区字符串数组兼容excludeRegions" }, { "name": "min_weight_g", "type": "number", "required": false, "source": "body", "description": "最小重量克兼容minWeightG" }, { "name": "max_weight_g", "type": "number", "required": false, "source": "body", "description": "最大重量克兼容maxWeightG" }, { "name": "weight_type", "type": "number", "required": false, "source": "body", "description": "0常规1轻货2重货3冷链默认0兼容weightType" }, { "name": "prohibited_type_id", "type": "array", "required": false, "source": "body", "description": "违禁品类型ID数字数组兼容prohibitedTypeId" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注最大500字符" }, { "name": "creator_id", "type": "number", "required": false, "source": "body", "description": "创建人账户ID兼容creatorId" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "调用成功为success" }, { "name": "code", "type": "number", "required": true, "description": "业务状态码" }, { "name": "message", "type": "string", "required": true, "description": "提示信息" }, { "name": "data.id", "type": "number", "required": true, "description": "策略ID" } ], "errors": [ { "code": 400, "message": "参数错误" }, { "code": 401, "message": "未认证" }, { "code": 409, "message": "同仓库策略名已存在" } ] }, { "method": "storeExpressBindingPolicy.edit", "description": "编辑策略必填id仅更新传入字段", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "策略ID兼容policy_id/policyId" }, { "name": "custom_name", "type": "string", "required": false, "source": "body", "description": "兼容customName" }, { "name": "shop_name", "type": "array", "required": false, "source": "body", "description": "包含店铺名称字符串数组兼容shopName" }, { "name": "store_ids", "type": "array", "required": false, "source": "body", "description": "限定货主ID数字数组兼容storeIds" }, { "name": "express_code", "type": "string", "required": false, "source": "body", "description": "兼容expressCode" }, { "name": "priority", "type": "number", "required": false, "source": "body", "description": "优先级" }, { "name": "is_enabled", "type": "number", "required": false, "source": "body", "description": "兼容isEnabled" }, { "name": "regions", "type": "array", "required": false, "source": "body", "description": "限定地区字符串数组" }, { "name": "exclude_regions", "type": "array", "required": false, "source": "body", "description": "排除地区字符串数组兼容excludeRegions" }, { "name": "min_weight_g", "type": "number", "required": false, "source": "body", "description": "兼容minWeightG" }, { "name": "max_weight_g", "type": "number", "required": false, "source": "body", "description": "兼容maxWeightG" }, { "name": "weight_type", "type": "number", "required": false, "source": "body", "description": "兼容weightType" }, { "name": "prohibited_type_id", "type": "array", "required": false, "source": "body", "description": "违禁品类型ID数字数组兼容prohibitedTypeId" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注" }, { "name": "creator_id", "type": "number", "required": false, "source": "body", "description": "兼容creatorId" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "调用成功为success" }, { "name": "code", "type": "number", "required": true, "description": "业务状态码" }, { "name": "message", "type": "string", "required": true, "description": "提示信息" }, { "name": "data.id", "type": "number", "required": true, "description": "策略ID" } ], "errors": [ { "code": 400, "message": "参数错误" }, { "code": 401, "message": "未认证" }, { "code": 404, "message": "策略不存在" }, { "code": 409, "message": "同仓库策略名已存在" } ] }, { "method": "storeExpressBindingPolicy.del", "description": "软删除策略", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "id", "type": "number", "required": true, "source": "body", "description": "策略ID兼容policy_id/policyId" } ], "response": [ { "name": "flag", "type": "string", "required": true, "description": "调用成功为success" }, { "name": "code", "type": "number", "required": true, "description": "业务状态码" }, { "name": "message", "type": "string", "required": true, "description": "提示信息" }, { "name": "data.id", "type": "number", "required": true, "description": "策略ID" } ], "errors": [ { "code": 400, "message": "id为空" }, { "code": 401, "message": "未认证" }, { "code": 404, "message": "策略不存在" } ] } ] }, { "groupName": "售后模块", "module": "afterSale", "list": [ { "method": "afterSale.workList", "description": "售后工作列表。仅返回当前用户角色组负责的待处理工单。", "isNeedAuth": false, "isNeedLogin": true, "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页 { page: 1, pageSize: 20 }" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "可选筛选字段: type/sub_type/status/priority/after_sale_no/waybill_no/store_id/claim_status/carrier_claim_status" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序 { sortField: 'id'|'priority'|'created_at', sortOrder: 'asc'|'desc' }" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "售后单列表,每条含主表字段 + detail_count + store_name(货主名称:取合约表 wms_store_warehouse.store_remask 货主备注名称,无合约或备注为空时回退 wms_store.company_name 公司全称,无货主时为空字符串)" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息 { page, pageSize, total, totalPages }" } ] }, { "method": "afterSale.auditList", "description": "售后审计列表。全局售后单视图,不限角色组、不限状态。", "isNeedAuth": false, "isNeedLogin": true, "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页 { page: 1, pageSize: 20 }" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "可选筛选字段: type/sub_type/status/priority/after_sale_no/waybill_no/store_id/role_group/claim_status/carrier_claim_status。" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序 { sortField: 'id'|'priority'|'created_at', sortOrder: 'asc'|'desc' }" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "全局售后单列表" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息 { page, pageSize, total, totalPages }" } ] }, { "method": "afterSale.detail", "description": "售后单明细查询:返回主表信息、步骤列表(含附件)、关联详情(订单/运单/货主合约)。关联数据按 afterSale 中的 order_delivery_id / waybill_id / store_id 自动解析,任一查询失败不影响主流程。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "id", "type": "integer", "required": true, "source": "body", "description": "售后单主键ID" } ], "response": [ { "name": "after_sale", "type": "object", "required": true, "description": "售后主表完整记录(含格式化时间字段)" }, { "name": "steps", "type": "array", "required": true, "description": "售后进度步骤列表(含附件 attachments),按创建时间升序。售后主表 description(详细描述)非空时,列表第一条为默认描述虚拟步骤(action=售后描述、remark=详细描述、step_status=pending、created_at=主表创建时间、id=null、is_virtual=true、attachments=[],不落库)", "list": [ { "value": "object", "label": "{ id, after_sale_id, step_status, operator_id, action, remark, is_virtual, attachments: [{id,file_url,file_name}] }" } ] }, { "name": "related", "type": "object", "required": true, "description": "关联单据详情。仅在售后单关联了对应业务单据时有值,其他情况为空对象。" }, { "name": "related.order", "type": "object", "required": false, "description": "关联发货订单详情(order_delivery_id 不为空时)。含 delivery_order_code、status、current_table(main/dispatch/history)、recipient(收件人)、sender(发件人,从货主 subject_config 取)、items(订单商品明细数组)、pack_videos(打包视频列表)" }, { "name": "related.waybill", "type": "object", "required": false, "description": "关联运单详情(waybill_id 不为空时)。含 waybill_code、logistics_name(快递公司名称)、logistics_code(物流编码)、logistics_interface_name(使用的物流接口)、logistics_interface_id、status、is_back、is_intercept" }, { "name": "related.store_contract", "type": "object", "required": false, "description": "货主合约备注(store_id + warehouse_id 匹配时)。含 contract_id、store_remask(商家备注)、warehouse_remask(仓库备注)、store_use_status、warehouse_use_status" } ], "errors": [ { "code": 404, "message": "售后单不存在" } ] }, { "method": "afterSale.create", "description": "创建售后单:生成售后单号(AS+YYYYMMDD+6位序号),写入主表记录。warehouse_id 由服务端从 ctx.user.store_id 自动注入。关联单据ID可自动同步对应单号(如传 order_delivery_id 自动查 delivery_order_code)。role_group 默认 customer_service,status 默认 pending。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "type", "type": "string", "required": true, "source": "body", "description": "售后类型:order | receiving | entry | stockout" }, { "name": "sub_type", "type": "string", "required": true, "source": "body", "description": "售后子类型,与 type 组成二级分类,详见模型枚举" }, { "name": "title", "type": "string", "required": true, "source": "body", "description": "售后标题(简要描述)" }, { "name": "description", "type": "string", "required": false, "source": "body", "description": "售后详细描述" }, { "name": "priority", "type": "integer", "required": false, "source": "body", "description": "优先级,默认0(0=普通,10=紧急)" }, { "name": "order_delivery_id", "type": "integer", "required": false, "source": "body", "description": "关联发货订单ID,兼容别名 order_id" }, { "name": "waybill_id", "type": "integer", "required": false, "source": "body", "description": "关联运单ID(wms_order_express.id)" }, { "name": "entry_order_id", "type": "integer", "required": false, "source": "body", "description": "关联入库单ID" }, { "name": "order_stockout_id", "type": "integer", "required": false, "source": "body", "description": "关联出库单ID" }, { "name": "receiving_id", "type": "integer", "required": false, "source": "body", "description": "关联收货单ID" }, { "name": "store_id", "type": "integer", "required": false, "source": "body", "description": "关联货主ID" }, { "name": "inbox_message_id", "type": "integer", "required": false, "source": "body", "description": "关联站内信ID" } ], "response": [ { "name": "after_sale_no", "type": "string", "required": true, "description": "售后单号" }, { "name": "status", "type": "string", "required": true, "description": "售后状态,创建默认 pending" }, { "name": "role_group", "type": "string", "required": true, "description": "角色组,创建默认 customer_service" }, { "name": "id", "type": "integer", "required": true, "description": "售后单主键ID" } ], "errors": [] }, { "method": "afterSale.transfer", "description": "转单:将售后工单转给其他角色组处理。转单后原角色组不可见,目标角色组可见。", "isNeedAuth": false, "isNeedLogin": true, "params": [ { "name": "id", "type": "integer", "required": true, "source": "body", "description": "售后工单主表ID" }, { "name": "role_group", "type": "string", "required": true, "source": "body", "description": "目标角色组: customer_service(客服组) | warehouse(仓库组) | finance(财务组)" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "转单备注/原因" } ], "response": [ { "name": "after_sale_id", "type": "integer", "required": true, "description": "售后工单ID" }, { "name": "role_group", "type": "string", "required": true, "description": "更新后的 role_group" } ] }, { "method": "afterSale.handleWorkOrder", "description": "处理售后工单:写入进度步骤并绑定附件。操作人信息从登录上下文自动获取。非客服组处理完成后自动将 role_group 回退到 customer_service;status=completed 时自动写入 resolution + resolved_at。步骤 action 由服务端固定为\"处理工单\",step_status 与主表 status 完全一致。status 不填或填错时默认 processing。新增 pending_feedback 状态用于内部处理完成等待外部反馈(如已将拦截信息发给运方,等待运方反馈后再决定是否继续处理)。填写处理备注(remark)时会同步发送到对应的货主售后群(工单无 store_id 时从来源消息所在群反查货主,不转发快递群),响应 notified_groups 返回发送的群数量。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "id", "type": "integer", "required": true, "source": "body", "description": "售后工单主表ID" }, { "name": "status", "type": "string", "required": false, "source": "body", "description": "更新售后单状态: processing | pending_feedback | completed | closed | cancelled。不填或填错默认 processing。不含 pending(创建默认值)。pending_feedback=等待外部反馈" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "处理备注。填写后同步发送到对应的货主售后群,内容格式:\"【工单 售后单号】处理备注:备注内容\"" }, { "name": "attachment_ids", "type": "array", "required": false, "source": "body", "description": "附件 file_id 数组,如 [123, 456]。自动绑定到本次步骤" } ], "response": [ { "name": "detail_id", "type": "integer", "required": true, "description": "本次写入的步骤ID(wms_after_sale_detail.id)" }, { "name": "after_sale_id", "type": "integer", "required": true, "description": "售后工单ID" }, { "name": "notified_groups", "type": "integer", "required": false, "description": "处理备注发送到的货主售后群数量(未填写备注或未找到货主售后群时为0)" } ], "errors": [] }, { "method": "afterSale.registerClaim", "description": "登记售后理赔信息:一次性填入仓库理赔和运方理赔字段,同时写入进度步骤。两套理赔可同时填写(双赔场景)。", "isNeedAuth": false, "isNeedLogin": true, "params": [ { "name": "id", "type": "integer", "required": true, "source": "body", "description": "售后工单主表ID" }, { "name": "claim_needed", "type": "integer", "required": false, "source": "body", "description": "仓库理赔标记: 0=不需要, 1=需要" }, { "name": "claim_amount", "type": "number", "required": false, "source": "body", "description": "仓库理赔金额(元)" }, { "name": "claim_status", "type": "string", "required": false, "source": "body", "description": "仓库理赔状态: pending | reviewing | approved | paid | monthly | rejected" }, { "name": "carrier_claim_needed", "type": "integer", "required": false, "source": "body", "description": "运方理赔标记: 0=不需要, 1=需要" }, { "name": "carrier_claim_amount", "type": "number", "required": false, "source": "body", "description": "运方理赔金额(元)" }, { "name": "carrier_claim_status", "type": "string", "required": false, "source": "body", "description": "运方理赔状态: pending | reviewing | approved | paid | monthly | rejected" }, { "name": "action", "type": "string", "required": true, "source": "body", "description": "操作动作描述,如\"登记仓库理赔\"、\"登记运方理赔\"" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "处理备注,如\"快递破损核定赔200元\"" }, { "name": "attachment_ids", "type": "array", "required": false, "source": "body", "description": "附件 file_id 数组(破损照片、理赔单据等)" } ], "response": [ { "name": "detail_id", "type": "integer", "required": true, "description": "本次写入的步骤ID" }, { "name": "after_sale_id", "type": "integer", "required": true, "description": "售后工单ID" } ] }, { "method": "afterSale.export", "description": "提交售后审计列表导出任务(异步)。返回 task_id,通过 exportTaskProgress 查询进度。", "isNeedAuth": false, "isNeedLogin": true, "params": [ { "name": "where", "type": "object", "required": false, "source": "body", "description": "筛选条件,同 auditList.where" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序,同 auditList.sort" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "导出任务ID,用于轮询进度" }, { "name": "status", "type": "string", "required": true, "description": "pending | processing | completed | failed" }, { "name": "progress", "type": "number", "required": true, "description": "进度百分比 0-100" }, { "name": "message", "type": "string", "required": true, "description": "状态说明" } ] }, { "method": "afterSale.exportTaskProgress", "description": "查询售后导出任务进度和下载链接。", "isNeedAuth": false, "isNeedLogin": true, "params": [ { "name": "task_id", "type": "string", "required": true, "source": "body", "description": "export 接口返回的 task_id" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "导出任务ID" }, { "name": "status", "type": "string", "required": true, "description": "pending | processing | completed | failed" }, { "name": "progress", "type": "number", "required": true, "description": "进度百分比 0-100" }, { "name": "download_url", "type": "string", "required": false, "description": "完成后的文件下载链接(仅 status=completed 时返回)" } ] }, { "method": "afterSale.workCount", "description": "快速查询当前用户待处理售后工单数量(角标用),返回count字段,前端>99显示99+。", "isNeedAuth": false, "isNeedLogin": true, "params": [], "response": [ { "name": "count", "type": "integer", "required": true } ] }, { "method": "afterSale.batchSetPendingFeedback", "description": "批量将售后工单设为“待反馈”状态,按仓库 policy_config.after_sale_followup_hours 配置自动计算每个工单的 followup_at(下次跟进时间)。所有工单在同一事务中处理,任一失败则全部回滚。终态工单(completed/closed/cancelled)不可回退、跨仓库工单会被拒绝并返回 failed 列表。非客服组工单自动将 role_group 回设为 customer_service。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "ids", "type": "array", "required": true, "source": "body", "description": "售后单主键ID列表,如 [1, 2, 3]。非正整数会被自动过滤。", "list": [ { "value": "number", "label": "售后单ID(正整数)" } ] }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "统一处理备注,所有工单共用同一备注内容" } ], "response": [ { "name": "total", "type": "integer", "required": true, "description": "传入的工单总数(过滤非正整数后)" }, { "name": "success", "type": "integer", "required": true, "description": "成功设为待反馈的工单数量" }, { "name": "failed", "type": "array", "required": true, "description": "失败的工单列表,每项包含 id 和 reason", "list": [ { "value": "object", "label": "{ id: number, reason: string }" } ] } ], "errors": [] }, { "method": "afterSale.batchClose", "description": "批量将售后工单完结或关闭。status=completed 时自动写入 resolved_at 并清除 followup_at;status=closed 时仅更新状态。所有工单在同一事务中处理,任一失败则全部回滚。终态工单(completed/closed/cancelled)不可重复操作、跨仓库工单会被拒绝并返回 failed 列表。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "ids", "type": "array", "required": true, "source": "body", "description": "售后单主键ID列表,如 [1, 2, 3]。非正整数会被自动过滤。", "list": [ { "value": "number", "label": "售后单ID(正整数)" } ] }, { "name": "status", "type": "string", "required": true, "source": "body", "description": "目标状态:completed=完结(写入 resolved_at + resolution),closed=关闭(仅更新状态,不写入完结信息)" }, { "name": "resolution", "type": "string", "required": false, "source": "body", "description": "完结处理结果说明,仅 status=completed 时写入" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "统一处理备注,所有工单共用同一备注内容" } ], "response": [ { "name": "total", "type": "integer", "required": true, "description": "传入的工单总数(过滤非正整数后)" }, { "name": "success", "type": "integer", "required": true, "description": "成功操作的工单数量" }, { "name": "failed", "type": "array", "required": true, "description": "失败的工单列表,每项包含 id 和 reason", "list": [ { "value": "object", "label": "{ id: number, reason: string }" } ] } ], "errors": [] }, { "method": "afterSale.typeList", "description": "售后类型列表:返回系统级(warehouse_id=null、is_system=1,全部仓库可见)与当前仓库自定义(is_system=0)类型的合并列表,默认按 sort_order 升序、id 升序,pageSize 上限 500。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页 { page: 1, pageSize: 20 },pageSize 上限 500" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "可选筛选字段: id/type/name/is_system/is_enabled/sort_order/created_at/updated_at" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序 { sortField, sortOrder },支持 id/type/name/is_enabled/sort_order/created_at/updated_at;不传默认 sort_order ASC, id ASC" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "售后类型列表,每条含 { id, warehouse_id, type, name, is_system, is_enabled, sort_order, created_at, updated_at };系统级 warehouse_id=null、is_system=1" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息 { page, pageSize, total, totalPages, hasPrevious, hasNext }" } ], "errors": [] }, { "method": "afterSale.typeCreate", "description": "创建仓库自定义售后类型(is_system=0):warehouse_id 由服务端从当前仓库上下文自动注入,前端无需传递。type 编码仅允许小写字母/数字/下划线且长度≤20,不可与系统级编码重复,同仓库内唯一(MySQL 唯一索引 uk_type_warehouse 兜底)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "type", "type": "string", "required": true, "source": "body", "description": "类型编码,仅允许 /^[a-z0-9_]+$/(小写字母/数字/下划线),长度≤20,不可与系统级编码重复" }, { "name": "name", "type": "string", "required": true, "source": "body", "description": "类型名称,长度≤50" }, { "name": "sort_order", "type": "number", "required": false, "source": "body", "description": "排序值,越小越靠前,默认 0(非法值按 0 处理)" }, { "name": "is_enabled", "type": "integer", "required": false, "source": "body", "description": "是否启用:1=启用(默认 1),0=停用" } ], "response": [ { "name": "id", "type": "integer", "required": true, "description": "新类型主键ID" }, { "name": "warehouse_id", "type": "integer", "required": true, "description": "仓库ID(当前仓库自定义)" }, { "name": "type", "type": "string", "required": true, "description": "类型编码" }, { "name": "name", "type": "string", "required": true, "description": "类型名称" }, { "name": "is_system", "type": "integer", "required": true, "description": "是否系统级,固定 0(仓库自定义)" }, { "name": "is_enabled", "type": "integer", "required": true, "description": "是否启用:1=启用,0=停用" }, { "name": "sort_order", "type": "number", "required": true, "description": "排序值" }, { "name": "created_at", "type": "string", "required": false, "description": "创建时间(格式化字符串)" }, { "name": "updated_at", "type": "string", "required": false, "description": "更新时间(格式化字符串)" } ], "errors": [ { "code": 400, "message": "无法获取当前仓库上下文,不能创建售后类型" }, { "code": 400, "message": "类型编码不能为空 / 只能包含小写字母、数字和下划线 / 长度不能超过20个字符" }, { "code": 400, "message": "类型名称不能为空 / 长度不能超过50个字符" }, { "code": 409, "message": "该类型编码与系统预设类型重复,不允许使用" }, { "code": 409, "message": "该类型编码在当前仓库已存在" } ] }, { "method": "afterSale.typeUpdate", "description": "更新仓库自定义售后类型:仅命中 id + 当前仓库 + is_system=0 的记录,系统级类型不允许修改(未命中统一返回 404)。仅允许修改 name/is_enabled/sort_order,type 编码不可变。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "id", "type": "integer", "required": true, "source": "body", "description": "类型主键ID" }, { "name": "name", "type": "string", "required": false, "source": "body", "description": "类型名称,长度≤50" }, { "name": "is_enabled", "type": "integer", "required": false, "source": "body", "description": "是否启用:1=启用,0=停用" }, { "name": "sort_order", "type": "number", "required": false, "source": "body", "description": "排序值,越小越靠前" } ], "response": [ { "name": "id", "type": "integer", "required": true, "description": "类型主键ID" }, { "name": "warehouse_id", "type": "integer", "required": true, "description": "仓库ID" }, { "name": "type", "type": "string", "required": true, "description": "类型编码(不可变)" }, { "name": "name", "type": "string", "required": true, "description": "类型名称" }, { "name": "is_system", "type": "integer", "required": true, "description": "是否系统级,固定 0(仓库自定义)" }, { "name": "is_enabled", "type": "integer", "required": true, "description": "是否启用:1=启用,0=停用" }, { "name": "sort_order", "type": "number", "required": true, "description": "排序值" }, { "name": "created_at", "type": "string", "required": false, "description": "创建时间(格式化字符串)" }, { "name": "updated_at", "type": "string", "required": false, "description": "更新时间(格式化字符串)" } ], "errors": [ { "code": 400, "message": "无法获取当前仓库上下文,不能修改售后类型" }, { "code": 400, "message": "售后类型ID不合法" }, { "code": 400, "message": "类型名称不能为空 / 长度不能超过50个字符" }, { "code": 400, "message": "没有需要更新的字段" }, { "code": 404, "message": "售后类型不存在、无权操作或为系统预设类型" } ] }, { "method": "afterSale.typeDelete", "description": "删除仓库自定义售后类型(不做级联删除):系统级类型禁止删除;删除前检查该类型下是否存在当前仓库自定义子类型,存在则拒绝(需先删除子类型)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "id", "type": "integer", "required": true, "source": "body", "description": "类型主键ID" } ], "response": [ { "name": "data", "type": "object", "required": true, "description": "删除结果对象" }, { "name": "data.id", "type": "integer", "required": true, "description": "被删除的类型ID" }, { "name": "data.deleted", "type": "boolean", "required": true, "description": "固定 true" } ], "errors": [ { "code": 400, "message": "无法获取当前仓库上下文,不能删除售后类型" }, { "code": 400, "message": "售后类型ID不合法" }, { "code": 404, "message": "售后类型不存在、无权操作或为系统预设类型" }, { "code": 409, "message": "该类型下存在当前仓库的自定义子类型,请先删除子类型" } ] }, { "method": "afterSale.subTypeList", "description": "售后子类型列表:返回系统级(warehouse_id=null、is_system=1)+ 当前仓库自定义(is_system=0)子类型的合并列表,默认按 sort_order 升序、id 升序;group=true 时额外按 type 分组返回 groups(基于全量过滤结果、不受分页影响,组内 sort_order 升序)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页 { page: 1, pageSize: 20 },pageSize 上限 500" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "可选筛选字段: id/type/sub_type/name/is_system/is_enabled/sort_order/created_at/updated_at" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序 { sortField, sortOrder },支持 id/type/sub_type/name/is_enabled/sort_order/created_at/updated_at;不传默认 sort_order ASC, id ASC" }, { "name": "group", "type": "boolean", "required": false, "source": "body", "description": "是否按 type 分组返回 groups(true 时额外返回 groups 数组)" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "售后子类型列表,每条含 { id, warehouse_id, type, sub_type, name, is_system, is_enabled, sort_order, created_at, updated_at }" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息 { page, pageSize, total, totalPages, hasPrevious, hasNext }" }, { "name": "groups", "type": "array", "required": false, "description": "group=true 时返回:按 type 分组,每组 { type, name, items: [...] },组内按 sort_order 升序、id 升序" } ], "errors": [] }, { "method": "afterSale.subTypeCreate", "description": "创建仓库自定义售后子类型(is_system=0):所属 type 必须已存在(系统级或当前仓库自定义)且处于启用状态(is_enabled=1)。sub_type 编码仅允许小写字母/数字/下划线且长度≤50,不可与系统级同 type 下编码重复,同仓库同 type 下唯一(MySQL 唯一索引 uk_type_subtype_warehouse 兜底)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "type", "type": "string", "required": true, "source": "body", "description": "所属类型编码,必须已存在且启用(is_enabled=1)" }, { "name": "sub_type", "type": "string", "required": true, "source": "body", "description": "子类型编码,仅允许 /^[a-z0-9_]+$/(小写字母/数字/下划线),长度≤50,不可与系统级同 type 下编码重复" }, { "name": "name", "type": "string", "required": true, "source": "body", "description": "子类型名称,长度≤50" }, { "name": "sort_order", "type": "number", "required": false, "source": "body", "description": "排序值,越小越靠前,默认 0(非法值按 0 处理)" }, { "name": "is_enabled", "type": "integer", "required": false, "source": "body", "description": "是否启用:1=启用(默认 1),0=停用" } ], "response": [ { "name": "id", "type": "integer", "required": true, "description": "新子类型主键ID" }, { "name": "warehouse_id", "type": "integer", "required": true, "description": "仓库ID(当前仓库自定义)" }, { "name": "type", "type": "string", "required": true, "description": "所属类型编码" }, { "name": "sub_type", "type": "string", "required": true, "description": "子类型编码" }, { "name": "name", "type": "string", "required": true, "description": "子类型名称" }, { "name": "is_system", "type": "integer", "required": true, "description": "是否系统级,固定 0(仓库自定义)" }, { "name": "is_enabled", "type": "integer", "required": true, "description": "是否启用:1=启用,0=停用" }, { "name": "sort_order", "type": "number", "required": true, "description": "排序值" }, { "name": "created_at", "type": "string", "required": false, "description": "创建时间(格式化字符串)" }, { "name": "updated_at", "type": "string", "required": false, "description": "更新时间(格式化字符串)" } ], "errors": [ { "code": 400, "message": "无法获取当前仓库上下文,不能创建售后子类型" }, { "code": 400, "message": "类型编码不能为空 / 只能包含小写字母、数字和下划线 / 长度不能超过20个字符" }, { "code": 400, "message": "子类型编码不能为空 / 只能包含小写字母、数字和下划线 / 长度不能超过50个字符" }, { "code": 400, "message": "子类型名称不能为空 / 长度不能超过50个字符" }, { "code": 400, "message": "售后类型不存在" }, { "code": 400, "message": "售后类型已停用,不能添加子类型" }, { "code": 409, "message": "该子类型编码与系统预设重复,不允许使用" }, { "code": 409, "message": "该子类型编码在当前仓库已存在" } ] }, { "method": "afterSale.subTypeUpdate", "description": "更新仓库自定义售后子类型:仅命中 id + 当前仓库 + is_system=0 的记录,系统级子类型不允许修改。仅允许修改 name/is_enabled/sort_order,type 与 sub_type 编码均不可变。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "id", "type": "integer", "required": true, "source": "body", "description": "子类型主键ID" }, { "name": "name", "type": "string", "required": false, "source": "body", "description": "子类型名称,长度≤50" }, { "name": "is_enabled", "type": "integer", "required": false, "source": "body", "description": "是否启用:1=启用,0=停用" }, { "name": "sort_order", "type": "number", "required": false, "source": "body", "description": "排序值,越小越靠前" } ], "response": [ { "name": "id", "type": "integer", "required": true, "description": "子类型主键ID" }, { "name": "warehouse_id", "type": "integer", "required": true, "description": "仓库ID" }, { "name": "type", "type": "string", "required": true, "description": "所属类型编码(不可变)" }, { "name": "sub_type", "type": "string", "required": true, "description": "子类型编码(不可变)" }, { "name": "name", "type": "string", "required": true, "description": "子类型名称" }, { "name": "is_system", "type": "integer", "required": true, "description": "是否系统级,固定 0(仓库自定义)" }, { "name": "is_enabled", "type": "integer", "required": true, "description": "是否启用:1=启用,0=停用" }, { "name": "sort_order", "type": "number", "required": true, "description": "排序值" }, { "name": "created_at", "type": "string", "required": false, "description": "创建时间(格式化字符串)" }, { "name": "updated_at", "type": "string", "required": false, "description": "更新时间(格式化字符串)" } ], "errors": [ { "code": 400, "message": "无法获取当前仓库上下文,不能修改售后子类型" }, { "code": 400, "message": "售后子类型ID不合法" }, { "code": 400, "message": "子类型名称不能为空 / 长度不能超过50个字符" }, { "code": 400, "message": "没有需要更新的字段" }, { "code": 404, "message": "售后子类型不存在、无权操作或为系统预设类型" } ] }, { "method": "afterSale.subTypeDelete", "description": "删除仓库自定义售后子类型(不做级联):系统级子类型禁止删除;若该子类型已被当前仓库售后单使用(wms_after_sale 存在该 type/sub_type 引用),拒绝删除。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "id", "type": "integer", "required": true, "source": "body", "description": "子类型主键ID" } ], "response": [ { "name": "data", "type": "object", "required": true, "description": "删除结果对象" }, { "name": "data.id", "type": "integer", "required": true, "description": "被删除的子类型ID" }, { "name": "data.deleted", "type": "boolean", "required": true, "description": "固定 true" } ], "errors": [ { "code": 400, "message": "无法获取当前仓库上下文,不能删除售后子类型" }, { "code": 400, "message": "售后子类型ID不合法" }, { "code": 404, "message": "售后子类型不存在、无权操作或为系统预设类型" }, { "code": 409, "message": "该子类型已被售后单使用,无法删除" } ] } ] }, { "groupName": "退回收到模块", "module": "returnReceived", "list": [ { "method": "returnReceived.create", "description": "退回包裹扫码登记。30日内同仓库同单号只写一次(以第一次为准);反查 wms_order_express 判定是否原单退回,命中则回填 order_express_id/order_id/store_id 并同步标记 is_back='Y',同步处理关联拦截工单、更新订单拦截状态(不释放拦截锁定库存,拦截锁回落由后续入库处理链路接管)。仓库隔离:warehouse_id 由服务端注入 ctx.user.store_id,禁止前端传入。响应新增 is_urgent 加急标记(boolean):wms_return_query_log(退回查询记录表)中存在 warehouse_id=当前仓库且 waybill_code=登记运单号(精确匹配)的记录时为 true,否则 false;查询失败时降级为 false。", "isNeedAuth": true, "isNeedLogin": true, "headers": [], "params": [ { "name": "waybill_code", "type": "string", "required": true, "source": "body", "description": "退回收件运单号(扫描到的退回包裹单号)" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注" }, { "name": "return_received_task_id", "type": "number", "required": false, "source": "body", "description": "收件任务ID(wms_return_received_task.id),不传默认 1=系统预设「历史收件」;服务端缓存校验(return_received_task:{id}),任务不存在/非法/不属于当前仓库报 400" } ], "response": [ { "name": "record", "type": "object", "required": true, "description": "登记记录包装对象,含登记记录完整字段(id、waybill_code、scan_date、scanner_id、scanner_name、order_express_id、order_id、store_id、remark、created_at、updated_at 等,时间字段为格式化字符串)及派生字段 is_original_return、store_remark" }, { "name": "is_original_return", "type": "boolean", "required": true, "description": "是否原单退回" }, { "name": "store_remark", "type": "string", "required": true, "description": "货主的合约货主备注名称(wms_store_warehouse.store_remask),非原单退回时为空字符串" }, { "name": "is_urgent", "type": "boolean", "required": true, "description": "加急标记:wms_return_query_log(退回查询记录表)中存在 warehouse_id=当前仓库且 waybill_code=登记运单号(精确匹配)的记录时为 true,否则 false;查询失败时降级为 false。幂等命中(duplicated=true)与新创建(duplicated=false)均返回" }, { "name": "duplicated", "type": "boolean", "required": true, "description": "是否命中30日幂等、返回第一次记录" } ], "errors": [ { "code": "400", "message": "waybill_code 不能为空" }, { "code": "400", "message": "缺少仓库上下文" }, { "code": "400", "message": "缺少扫描人员工号上下文" }, { "code": "401", "message": "未提供有效的认证令牌" }, { "code": "403", "message": "无权访问该接口" } ] }, { "method": "returnReceived.list", "description": "退回收到登记分页列表。仓库隔离(服务端自动注入 warehouse_id = ctx.user.store_id,禁止前端传入)。支持按运单号模糊、扫描日期/登记时间/更新时间范围、扫描人员(ID/名称)、货主、运单/订单ID、是否原单退回筛选。", "isNeedAuth": true, "isNeedLogin": true, "headers": [], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页 { page: 1, pageSize: 20 }" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "筛选条件对象,所有字段均可选" }, { "name": "where.waybill_code", "type": "string", "required": false, "source": "body.where", "description": "退回收件运单号(模糊搜索,传 {operator:'like',value} 或直接值)" }, { "name": "where.scan_date", "type": "object", "required": false, "source": "body.where", "description": "扫描日期范围 { operator:'between'|'gte'|'lte', value:[start,end] 或单值 }" }, { "name": "where.created_at", "type": "object", "required": false, "source": "body.where", "description": "登记时间范围 { operator:'between'|'gte'|'lte', value:[start,end] 或单值 }" }, { "name": "where.updated_at", "type": "object", "required": false, "source": "body.where", "description": "更新时间范围 { operator:'between'|'gte'|'lte', value:[start,end] 或单值 }" }, { "name": "where.scanner_id", "type": "number", "required": false, "source": "body.where", "description": "扫描人员工号ID(等值)" }, { "name": "where.scanner_name", "type": "string", "required": false, "source": "body.where", "description": "扫描人员名称快照(等值)" }, { "name": "where.store_id", "type": "number", "required": false, "source": "body.where", "description": "货主ID(等值)" }, { "name": "where.order_express_id", "type": "number", "required": false, "source": "body.where", "description": "运单ID(等值,原单退回时回填)" }, { "name": "where.order_id", "type": "number", "required": false, "source": "body.where", "description": "订单ID(等值,原单退回时回填)" }, { "name": "where.is_original_return", "type": "boolean", "required": false, "source": "body.where", "description": "是否原单退回:true=有关联原运单,false=无关联" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序 { sortField: 'id'|'scan_date'|'created_at'|'updated_at'|'waybill_code', sortOrder: 'asc'|'desc' }" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "退回收到登记列表,每条含登记字段 + is_original_return + store_remark" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息 { page, pageSize, total, totalPages, hasPrevious, hasNext }" } ], "errors": [ { "code": "401", "message": "未提供有效的认证令牌" }, { "code": "403", "message": "无权访问该接口" } ] }, { "method": "returnReceived.detail", "description": "退回收到登记详情,含原运单(命中时)与货主合约备注(命中时)。免权限但需登录,仓库隔离校验(仅本仓库记录)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "id", "type": "integer", "required": true, "source": "body", "description": "登记记录主键ID" } ], "response": [ { "name": "record", "type": "object", "required": true, "description": "登记记录完整信息(含 is_original_return、store_remark、格式化时间字段)" }, { "name": "order_express", "type": "object", "required": false, "description": "原运单详情(order_express_id 不为空时)。含 waybill_code、order_id、store_id、warehouse_id、is_back、is_intercept、logistics_name、logistics_code" }, { "name": "store_contract", "type": "object", "required": false, "description": "货主合约备注(store_id 不为空时)。含 store_remask、warehouse_remask、store_use_status、warehouse_use_status" } ], "errors": [ { "code": "400", "message": "id 必填且必须为正整数" }, { "code": "401", "message": "未提供有效的认证令牌" }, { "code": "403", "message": "无权访问该登记记录" }, { "code": "404", "message": "登记记录不存在" } ] }, { "method": "returnReceived.delete", "description": "删除退回收到登记记录(物理删除)。仓库隔离校验(仅本仓库记录)。", "isNeedAuth": true, "isNeedLogin": true, "headers": [], "params": [ { "name": "id", "type": "integer", "required": true, "source": "body", "description": "登记记录主键ID" } ], "response": [ { "name": "id", "type": "integer", "required": true, "description": "被删除登记记录ID" } ], "errors": [ { "code": "400", "message": "id 必填且必须为正整数" }, { "code": "401", "message": "未提供有效的认证令牌" }, { "code": "403", "message": "无权访问该登记记录" }, { "code": "404", "message": "登记记录不存在" } ] }, { "method": "returnReceived.export", "description": "提交退回收到登记列表导出任务(异步)。入参 where/sort 语义与 returnReceived.list 一致;warehouse_id 由服务端从 ctx.user.store_id 注入,禁止前端传入。提交后立即返回 task_id,后台异步生成单 Sheet Excel(Sheet「退回收到登记列表」)并上传,导出进度/下载请通过 returnReceived.exportTaskProgress 查询。数据来源 wms_return_received 登记表;Excel 列:运单号/扫描日期/扫描人员/是否原单退回/订单ID/货主备注/备注/登记时间/更新时间。全量分页拉取(500/页,无行数上限);任务缓存 Redis TTL 30 分钟;状态口径 submitted → running(5) → 数据拉取(10~55,未命中数据时直接 85) → Excel 生成(60) → success(100),失败 failed + error。权限口径:默认走 API 权限校验(需 wms_permission 存在 returnReceived.export 类型为 api 的记录),需登录。", "isNeedAuth": true, "isNeedLogin": true, "headers": [], "params": [ { "name": "where", "type": "object", "required": false, "source": "body", "description": "查询条件,语义与 returnReceived.list 的 where 一致(支持 {operator,value} 标准结构或直接值;字段含 waybill_code 模糊、scan_date/created_at/updated_at 范围、scanner_id/scanner_name/store_id/order_express_id/order_id/return_received_task_id 等值、is_original_return 是否原单退回);禁止传入 warehouse_id/warehouseId(服务端注入)" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数,语义与 returnReceived.list 的 sort 一致:sortField 白名单 id/scan_date/created_at/updated_at/waybill_code,sortOrder asc/desc,默认 created_at desc" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID(后端生成,格式 return_received_export_{warehouseId}_{timestamp}_{random})" }, { "name": "status", "type": "string", "required": true, "description": "任务状态,枚举:submitted/running/success/failed/not_found(提交成功时为 submitted)" }, { "name": "progress", "type": "number", "required": true, "description": "当前进度百分比(0-100),提交时返回 0" }, { "name": "current_count", "type": "number", "required": true, "description": "当前已处理记录数(登记记录条数)" }, { "name": "total_count", "type": "number", "required": true, "description": "总记录数(若有)" }, { "name": "message", "type": "string", "required": true, "description": "任务提示信息" }, { "name": "result", "type": "object", "required": true, "description": "任务执行结果(提交时为 null;后台完成后为上传信息对象,含 filename/url/fileKey/cdnUrl/cosUrl/current_count/total_count)" }, { "name": "error", "type": "string", "required": true, "description": "失败时的错误信息(非失败时为空字符串)" }, { "name": "update_time", "type": "number", "required": true, "description": "任务更新时间(Unix 毫秒时间戳)" } ], "errors": [ { "code": "400", "message": "参数格式不正确、where 条件非法或缺少仓库上下文" }, { "code": "401", "message": "未提供有效的认证令牌" }, { "code": "403", "message": "无权访问该接口" }, { "code": "500", "message": "导出任务提交失败" } ] }, { "method": "returnReceived.exportTaskProgress", "description": "按 task_id 查询退回收到导出任务进度,返回 task_id、status、progress、current_count、total_count、message、result、error、download_url、update_time;上传完成后 download_url 返回下载链接(从 result.url/cdnUrl/cosUrl/fileKey 兜底取);任务缓存 Redis TTL 30 分钟,task_id 缺失或缓存未命中时 status=not_found(正常响应,非报错)。状态口径 submitted → running(5) → 数据拉取(10~55) → Excel 生成(60) → success(100),失败 failed + error。权限口径与 returnReceived.export 一致(默认走 API 权限校验,需 wms_permission 存在 returnReceived.exportTaskProgress 类型为 api 的记录),需登录。", "isNeedAuth": true, "isNeedLogin": true, "headers": [], "params": [ { "name": "task_id / taskId", "type": "string", "required": true, "source": "body|query", "description": "任务 ID,兼容 task_id(下划线)与 taskId(驼峰)两种写法" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID(task_id 缺失时为回显的空字符串,status=not_found)" }, { "name": "status", "type": "string", "required": true, "description": "任务状态:submitted/running/success/failed/not_found" }, { "name": "progress", "type": "number", "required": true, "description": "进度百分比(0-100)" }, { "name": "current_count", "type": "number", "required": true, "description": "当前已处理记录数(登记记录条数)" }, { "name": "total_count", "type": "number", "required": true, "description": "总记录数" }, { "name": "message", "type": "string", "required": true, "description": "任务提示信息" }, { "name": "result", "type": "object", "required": true, "description": "任务执行结果对象(完成后含 filename/url/fileKey/cdnUrl/cosUrl 等;未完成或 not_found 时为 null)" }, { "name": "error", "type": "string", "required": true, "description": "失败时的错误信息(非失败时为空字符串)" }, { "name": "download_url", "type": "string", "required": true, "description": "任务完成后下载链接(从 result.url/cdnUrl/cosUrl/fileKey 兜底取);未完成或不存在时为空字符串" }, { "name": "update_time", "type": "number", "required": true, "description": "最近一次状态更新时间(Unix 毫秒时间戳)" } ], "errors": [ { "code": "401", "message": "未提供有效的认证令牌" }, { "code": "403", "message": "无权访问该接口" }, { "code": "500", "message": "查询失败或内部错误" } ] } ] }, { "groupName": "收件任务模块", "module": "returnReceivedTask", "list": [ { "method": "returnReceivedTask.create", "description": "创建收件任务。主键 id 自增从 10000 开始(表级 AUTO_INCREMENT);批次号 batch_no 一律由服务端自动生成(格式 RT+YYYYMMDD+5位序号,如 RT2026100500001,基于 wms_number_sequence 序列表原子取号、全局递增、并发不撞号,参考波次号机制),**不接收外部输入**(前端传入 batch_no/batchNo 均被忽略);warehouse_id 由服务端从当前登录上下文(ctx.user.store_id)自动注入,creator_id/creator_name 从上下文(账号ID/员工名称)自动注入,禁止前端传入。系统预设任务 id=1(历史收件,warehouse_id=0)用于承接历史退回收件登记。权限口径:需要登录,免 API 权限校验(无需 wms_permission 记录)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(正常登录 token,携带仓库上下文)" } ], "params": [ { "name": "title", "type": "string", "required": false, "source": "body", "description": "标题(任务名称,最长 100 字符,缺省为空串)" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "收件任务ID(自增从 10000 开始)" }, { "name": "batch_no", "type": "string", "required": true, "description": "批次号" }, { "name": "title", "type": "string", "required": true, "description": "标题" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "仓库ID(服务端注入)" }, { "name": "creator_id", "type": "number", "required": true, "description": "创建人账户ID(服务端注入)" }, { "name": "creator_name", "type": "string", "required": true, "description": "创建人名称快照(服务端注入)" }, { "name": "created_at / updated_at", "type": "string", "required": true, "description": "创建时间/更新时间(YYYY-MM-DD HH:mm:ss 格式化字符串)" } ], "errors": [ { "code": "400", "message": "无法获取当前仓库上下文" }, { "code": "400", "message": "标题过长(最多100字符)" }, { "code": "401", "message": "未提供有效的认证令牌" }, { "code": "500", "message": "创建收件任务失败" } ] }, { "method": "returnReceivedTask.list", "description": "分页查询收件任务列表。warehouse_id 由服务端从当前登录上下文(ctx.user.store_id)自动注入(返回本仓库任务 + 系统级任务 warehouse_id=0,如系统预设「历史收件」),禁止前端传入。搜索关键词 where.quickWhere:在 title(标题)/batch_no(编号)/creator_name(创建人)三个字段中 OR 模糊匹配;title/batch_no/creator_name 也可传 {operator,value} 标准结构(like 模糊/eq 精确/in 等);has_register 是否有登记(true=仅看有登记任务,false=仅看无登记任务,按当前仓库的 wms_return_received.return_received_task_id 引用判定,不跨仓);其他字段 id/creator_id/created_at/updated_at。每行返回 register_count(该任务在当前仓库下的退回收件登记数量,按 wms_return_received.return_received_task_id + warehouse_id=当前仓库 分组统计,系统级任务如「历史收件」也只统计当前仓库,无登记为 0)。排序 sort:sortField 白名单 id/batch_no/created_at/updated_at,sortOrder asc/desc,默认 id desc;分页 pagination:page/pageSize(pageSize 上限 500)。时间字段返回格式化字符串(YYYY-MM-DD HH:mm:ss)。权限口径:需要登录,免 API 权限校验(无需 wms_permission 记录)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(正常登录 token,携带仓库上下文)" } ], "params": [ { "name": "where", "type": "object", "required": false, "source": "body", "description": "查询条件:quickWhere 关键词在 title/batch_no/creator_name 三个字段中 OR 模糊匹配;title/batch_no/creator_name 支持 {operator,value} 标准结构(like/eq/in 等);has_register 是否有登记(true/false,按当前仓库判定不跨仓);id/creator_id 等值或 in;created_at/updated_at 范围;禁止传入 warehouse_id/warehouseId(服务端注入)" }, { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数:page(页码,默认1)、pageSize(每页数量,默认20,上限500)" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数:sortField 白名单 id/batch_no/created_at/updated_at,sortOrder asc/desc,默认 id desc" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "任务行列表,每行含 id/batch_no/title/warehouse_id/creator_id/creator_name/created_at/updated_at(时间字段为格式化字符串)及 register_count(该任务下的退回收件登记数量,无登记为 0)" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息:page/pageSize/total/totalPages/hasPrevious/hasNext" } ], "errors": [ { "code": "401", "message": "未提供有效的认证令牌" }, { "code": "500", "message": "查询列表失败" } ] }, { "method": "returnReceivedTask.delete", "description": "删除收件任务(硬删除,物理删除行)。兼容两种入参:① ids(数组或单值,单次上限 200)批量删除——逐条分流不整体报错,任务不存在、系统预设 id=1(历史收件)、非当前仓库任务、已有收件登记(wms_return_received.return_received_task_id 引用)的任务计入 skipped_ids,其余硬删除并清理任务校验缓存(return_received_task:{id}),返回 { total, deleted_count, skipped_count, deleted_ids, skipped_ids }(保持入参顺序);② id(单值)单值删除——不满足条件抛出 404/409,返回 { id, deleted: true }。warehouse_id 由服务端从当前登录上下文(ctx.user.store_id)自动注入,禁止前端传入。权限口径:需要登录,免 API 权限校验(无需 wms_permission 记录)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(正常登录 token,携带仓库上下文)" } ], "params": [ { "name": "ids", "type": "array", "required": false, "source": "body", "description": "收件任务ID数组(批量删除,兼容单值,去重后单次上限 200;优先于 id)" }, { "name": "id", "type": "number", "required": false, "source": "body", "description": "收件任务ID(单值删除,正整数)" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "单值删除:被删除的收件任务ID(批量删除时不返回)" }, { "name": "deleted", "type": "boolean", "required": true, "description": "单值删除:是否已删除(恒为 true;批量删除时不返回)" }, { "name": "total / deleted_count / skipped_count / deleted_ids / skipped_ids", "type": "object", "required": true, "description": "批量删除(传 ids)时返回:total=入参去重总数,deleted_count=实际删除数,skipped_count=跳过数(不存在/系统预设/非本仓库/已有登记),deleted_ids/skipped_ids 保持入参顺序" } ], "errors": [ { "code": "400", "message": "收件任务ID不合法" }, { "code": "404", "message": "收件任务不存在" }, { "code": "404", "message": "系统预设任务不可删除" }, { "code": "404", "message": "收件任务不存在或无权操作" }, { "code": "409", "message": "该任务已有收件登记,无法删除" }, { "code": "401", "message": "未提供有效的认证令牌" }, { "code": "500", "message": "删除收件任务失败" } ] }, { "method": "returnReceivedTask.batchDelete", "description": "批量删除收件任务(硬删除,物理删除行)。逐条分流不整体报错:任务不存在、系统预设 id=1(历史收件)、非当前仓库任务、已有收件登记(wms_return_received.return_received_task_id 引用)的任务均计入 skipped_ids,其余任务硬删除并清理任务校验缓存(return_received_task:{id})。warehouse_id 由服务端从当前登录上下文(ctx.user.store_id)自动注入,禁止前端传入。入参 ids 支持数组或单值(去重后上限 200);返回 { total, deleted_count, skipped_count, deleted_ids, skipped_ids }(保持入参顺序)。权限口径:需要登录,免 API 权限校验(无需 wms_permission 记录)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token(正常登录 token,携带仓库上下文)" } ], "params": [ { "name": "ids", "type": "array", "required": true, "source": "body", "description": "收件任务ID数组(兼容单值,去重后单次上限 200)" } ], "response": [ { "name": "total", "type": "number", "required": true, "description": "入参去重后的任务ID总数" }, { "name": "deleted_count", "type": "number", "required": true, "description": "实际删除数量" }, { "name": "skipped_count", "type": "number", "required": true, "description": "跳过数量(不存在/系统预设/非本仓库/已有登记)" }, { "name": "deleted_ids", "type": "array", "required": true, "description": "已删除的任务ID列表(保持入参顺序)" }, { "name": "skipped_ids", "type": "array", "required": true, "description": "跳过的任务ID列表(保持入参顺序)" } ], "errors": [ { "code": "400", "message": "ids 不能为空" }, { "code": "400", "message": "单次最多删除 200 个收件任务" }, { "code": "400", "message": "无法获取当前仓库上下文" }, { "code": "401", "message": "未提供有效的认证令牌" }, { "code": "500", "message": "批量删除收件任务失败" } ] } ] }, { "groupName": "退回拆包模块", "module": "returnUnpack", "list": [ { "method": "returnUnpack.create", "description": "开拆包单(明细不在此提交,由 returnUnpack.addDetail 逐件录入)。用 waybill_code 反查 wms_order_express 判定是否原单退回,命中则回填 order_express_id/order_id/store_id 及订单信息快照(source_order_codes 平台交易单号 / shop_name 店铺名称=货主自定义店铺名称 store_remask)并返回原订单详情;未命中原单时按 warehouse_id+waybill_code 从 wms_return_query_log 反查货主(限最近 3 个月内登记)。幂等复用:同一仓库同一运单号 3 个月内已存在非 cancelled 拆包单时,不重复创建,直接返回已有拆包单的主表+明细(record.details)+视频(record.videos)+原订单详情(order),并携带 reused=true 标识;同运单号存在多张拆包单时优先复用已录明细的最新单(按明细表真实计数判定),超过 3 个月视为运单号已复用,按新单正常创建。拆包单号规则 RP+YYYYMMDD+6位序号。仓库隔离:warehouse_id 由服务端注入 ctx.user.store_id,禁止前端传入。", "isNeedAuth": true, "isNeedLogin": true, "headers": [], "params": [ { "name": "waybill_code", "type": "string", "required": true, "source": "body", "description": "拆包的运单号(退回包裹运单号,必填,用于反查原单/货主信息)" }, { "name": "camera_ids", "type": "array", "required": false, "source": "body", "description": "摄像头ID列表,如 [1,2,3],关联 wms_camera.id(非正整数会被过滤)" }, { "name": "return_received_id", "type": "integer", "required": false, "source": "body", "description": "关联退回收到单ID(wms_return_received.id),非必填,允许独立拆包" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注(最长 500 字符,超出截断)" } ], "response": [ { "name": "id", "type": "integer", "required": true, "description": "拆包单主键ID(后续明细收录的依据,传给 returnUnpack.addDetail)" }, { "name": "record", "type": "object", "required": true, "description": "拆包单主表记录(含 unpack_no、waybill_code、unpack_date、start_time、unpacker_id/unpacker_name、status、detail_status、camera_ids 数组、回填的 order_express_id/order_id/store_id/source_order_codes/shop_name 快照及 is_original_return 派生字段);幂等复用命中已有拆包单时,record 为已有单的详情记录并携带 details 明细数组(含 stockWarehouse 关联,识别明细另附加 stock 库存详情对象:barcodes 条码数组/image_url 图片数组等)、videos 视频数组与 returnReceived 关联" }, { "name": "is_original_return", "type": "boolean", "required": true, "description": "是否原单退回(反查 wms_order_express.waybill_code 命中为 true)" }, { "name": "store_remark", "type": "string", "required": true, "description": "货主的合约货主备注名称(wms_store_warehouse.store_remask),未命中时为空字符串" }, { "name": "order", "type": "object", "required": false, "description": "原订单详情(含 items 明细,仅原单退回时返回,非原单为 null)" }, { "name": "order_items", "type": "array", "required": false, "description": "原订单商品明细数组(即 order.items 的顶层透出,含 item_code/item_name/sku_property/quantity/plan_qty/barcodes/image_url 等,仅原单退回时返回;非原单退回或原订单详情缺失时为 null)" }, { "name": "reused", "type": "boolean", "required": false, "description": "是否幂等复用已有拆包单(true 表示 3 个月内同仓库同运单号已有非 cancelled 拆包单,本次未新建,record.details 即已有明细;新建时为 false 或不返回)" } ], "errors": [ { "code": "400", "message": "waybill_code 不能为空" }, { "code": "400", "message": "缺少仓库上下文" }, { "code": "400", "message": "缺少拆包人员工号上下文" }, { "code": "401", "message": "未提供有效的认证令牌" }, { "code": "403", "message": "无权访问该接口" }, { "code": "500", "message": "服务器内部错误" } ] }, { "method": "returnUnpack.addDetail", "description": "录明细:以拆包单ID为依据录入一条明细。主单非终态(unpacking)校验;stock_id 有值时校验货主归属并回填识别快照(is_recognized=1 + item_code/item_name/spec/product_snapshot),未指定 stock_id 时一律标注未知商品(is_recognized=0,item_name=未知商品),不做条码自动匹配(同一条码可能对应多个 stock_id,自动匹配易误配),barcode 仅作记录;主表 store_id 为空时以首个识别商品回填主表货主。写明细后重算主表 total_items/total_quantity/detail_status。仓库隔离校验(仅本仓库拆包单)。", "isNeedAuth": true, "isNeedLogin": true, "headers": [], "params": [ { "name": "id", "type": "integer", "required": true, "source": "body", "description": "拆包单ID(returnUnpack.create 返回的依据)" }, { "name": "stock_id", "type": "integer", "required": false, "source": "body", "description": "系统商品ID(wms_stock_warehouse.id),为空即无关联货物(商品名称标注未知商品)" }, { "name": "barcode", "type": "string", "required": false, "source": "body", "description": "扫描条码(最长100字符,仅作记录,不参与商品匹配)" }, { "name": "quantity", "type": "integer", "required": false, "source": "body", "description": "数量,默认 1(小于 1 按 1 处理)" }, { "name": "product_status", "type": "string", "required": false, "source": "body", "description": "产品状态:normal 正常(默认)/ damaged 破损" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注(最长 500 字符,超出截断)" } ], "response": [ { "name": "detail_id", "type": "integer", "required": true, "description": "新增明细ID(供 returnUnpack.updateDetail / returnUnpack.removeDetail 使用)" }, { "name": "detail", "type": "object", "required": true, "description": "新增的明细行(含 barcode/is_recognized/item_code/item_name(未知商品)/spec/product_snapshot 等;识别到系统商品时附加 stock 库存详情对象,含 item_code/item_name/sku_property/barcodes 条码数组/image_url 图片数组/packing_requirements/stock_unit 等,由 getStockDetails 通用方法拉取)" }, { "name": "total_items", "type": "integer", "required": true, "description": "主表最新物品种类数(明细行数)" }, { "name": "total_quantity", "type": "integer", "required": true, "description": "主表最新物品总数量(明细数量合计)" }, { "name": "detail_status", "type": "string", "required": true, "description": "主表最新明细识别状态:none_recognized 全未识别 / partial_recognized 部分识别 / all_recognized 全部识别" } ], "errors": [ { "code": "400", "message": "id 必填且必须为正整数" }, { "code": "400", "message": "拆包单已提交或已取消,不可操作" }, { "code": "401", "message": "未提供有效的认证令牌" }, { "code": "403", "message": "该商品不属于当前货主,无法录入" }, { "code": "403", "message": "无权访问该拆包单" }, { "code": "403", "message": "无权访问该接口" }, { "code": "404", "message": "拆包单不存在" }, { "code": "404", "message": "系统商品不存在" }, { "code": "500", "message": "服务器内部错误" } ] }, { "method": "returnUnpack.updateDetail", "description": "更新明细:仅允许更新 quantity/remark(更新范围白名单,暂限这两个字段)。校验拆包单存在且非终态(unpacking)、明细属于该拆包单;仅 quantity 变更时重算主表 total_quantity(total_items/detail_status 不变)。仓库隔离校验(仅本仓库拆包单)。", "isNeedAuth": true, "isNeedLogin": true, "headers": [], "params": [ { "name": "id", "type": "integer", "required": true, "source": "body", "description": "拆包单ID" }, { "name": "detail_id", "type": "integer", "required": true, "source": "body", "description": "明细ID(returnUnpack.addDetail 返回)" }, { "name": "quantity", "type": "integer", "required": false, "source": "body", "description": "数量(小于 1 按 1 处理,变更时才触发主表重算)" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注(最长 500 字符,超出截断)" } ], "response": [ { "name": "detail", "type": "object", "required": true, "description": "更新后的明细行(识别到系统商品时附加 stock 库存详情对象,含 barcodes 条码数组/image_url 图片数组等,由 getStockDetails 通用方法拉取)" }, { "name": "total_items", "type": "integer", "required": true, "description": "主表最新物品种类数" }, { "name": "total_quantity", "type": "integer", "required": true, "description": "主表最新物品总数量(quantity 变更时重算)" }, { "name": "detail_status", "type": "string", "required": true, "description": "主表最新明细识别状态:none_recognized/partial_recognized/all_recognized" } ], "errors": [ { "code": "400", "message": "id 必填且必须为正整数" }, { "code": "400", "message": "detail_id 必填且必须为正整数" }, { "code": "400", "message": "拆包单已提交或已取消,不可操作" }, { "code": "401", "message": "未提供有效的认证令牌" }, { "code": "403", "message": "无权访问该拆包单" }, { "code": "403", "message": "无权访问该接口" }, { "code": "404", "message": "拆包单不存在" }, { "code": "404", "message": "明细不存在或不属于该拆包单" }, { "code": "500", "message": "服务器内部错误" } ] }, { "method": "returnUnpack.removeDetail", "description": "移除明细:删除拆包单下的一条明细(明细表 paranoid:false,硬删除/物理删除),并重算主表 total_items/total_quantity/detail_status。校验拆包单存在且非终态(unpacking)、明细属于该拆包单。仓库隔离校验(仅本仓库拆包单)。", "isNeedAuth": true, "isNeedLogin": true, "headers": [], "params": [ { "name": "id", "type": "integer", "required": true, "source": "body", "description": "拆包单ID" }, { "name": "detail_id", "type": "integer", "required": true, "source": "body", "description": "明细ID(returnUnpack.addDetail 返回)" } ], "response": [ { "name": "removed_detail_id", "type": "integer", "required": true, "description": "被移除明细ID" }, { "name": "total_items", "type": "integer", "required": true, "description": "主表最新物品种类数" }, { "name": "total_quantity", "type": "integer", "required": true, "description": "主表最新物品总数量" }, { "name": "detail_status", "type": "string", "required": true, "description": "主表最新明细识别状态:none_recognized/partial_recognized/all_recognized" } ], "errors": [ { "code": "400", "message": "id 必填且必须为正整数" }, { "code": "400", "message": "detail_id 必填且必须为正整数" }, { "code": "400", "message": "拆包单已提交或已取消,不可操作" }, { "code": "401", "message": "未提供有效的认证令牌" }, { "code": "403", "message": "无权访问该拆包单" }, { "code": "403", "message": "无权访问该接口" }, { "code": "404", "message": "拆包单不存在" }, { "code": "404", "message": "明细不存在或不属于该拆包单" }, { "code": "500", "message": "服务器内部错误" } ] }, { "method": "returnUnpack.cancel", "description": "取消拆包单:仅在未完成(unpacking)状态可取消,事务内硬删除主表 + 该单所有明细,并同步软删视频副表记录。与 returnUnpack.delete 区别:cancel 仅供未完成状态作业取消;delete 为后台管理删除,不限制状态。仓库隔离校验(仅本仓库拆包单)。", "isNeedAuth": true, "isNeedLogin": true, "headers": [], "params": [ { "name": "id", "type": "integer", "required": true, "source": "body", "description": "拆包单ID" } ], "response": [ { "name": "id", "type": "integer", "required": true, "description": "被取消拆包单ID" } ], "errors": [ { "code": "400", "message": "id 必填且必须为正整数" }, { "code": "400", "message": "拆包单已提交或已取消,不可操作" }, { "code": "401", "message": "未提供有效的认证令牌" }, { "code": "403", "message": "无权访问该拆包单" }, { "code": "403", "message": "无权访问该接口" }, { "code": "404", "message": "拆包单不存在" }, { "code": "500", "message": "服务器内部错误" } ] }, { "method": "returnUnpack.submit", "description": "提交确认:未完成(unpacking)拆包单转 completed 终态并回写 end_time(拆包结束时间;结束时间超过仓库配置的拆包最大录制时长上限时,自动截断为 开始时间+上限——仓库配置项 subject_config.return_unpack_max_record_minutes,默认 5 分钟,配置缺失/非法或开始时间缺失时不约束);同步按 warehouse_id+waybill_code 更新 wms_return_query_log.is_back=1(标记该运单号已退回,更新失败不阻断主流程)。提交后进入终态,不可再录/移除明细。仓库隔离校验(仅本仓库拆包单)。拆包完成后按退回查询登记来源定向通知:仅登记表 is_back=1 且 is_notified=0 的记录,按登记时记录的 group_id+user_id 回信原查询群/用户(有用户信息时定向回原查询用户,否则退化为来源群系统通知;登记无来源群的记录不通知),不再泛推货主售后群;推送成功标记 is_notified=1。", "isNeedAuth": true, "isNeedLogin": true, "headers": [], "params": [ { "name": "id", "type": "integer", "required": true, "source": "body", "description": "拆包单ID" } ], "response": [ { "name": "record", "type": "object", "required": true, "description": "更新后的主表记录(含 status=completed、end_time 及格式化时间字段;end_time 为按仓库拆包最大录制时长上限约束后的结束时间,超过上限时截断为 开始时间+上限)" } ], "errors": [ { "code": "400", "message": "id 必填且必须为正整数" }, { "code": "400", "message": "拆包单已提交或已取消,不可操作" }, { "code": "401", "message": "未提供有效的认证令牌" }, { "code": "403", "message": "无权访问该拆包单" }, { "code": "403", "message": "无权访问该接口" }, { "code": "404", "message": "拆包单不存在" }, { "code": "500", "message": "服务器内部错误" } ] }, { "method": "returnUnpack.forceRecord", "description": "强制重新录制拆包视频。校验仓库录制电脑在线后,将视频记录(wms_return_unpack_video)重置为 created 并清空 video_url,再向打印服务 /record/force 推送 { unpack_id } 触发重新录制(参考 order.packing.forceRecord)。仓库隔离校验(仅本仓库拆包单)。", "isNeedAuth": true, "isNeedLogin": true, "headers": [], "params": [ { "name": "id", "type": "integer", "required": true, "source": "body", "description": "拆包单ID" } ], "response": [ { "name": "unpack_id", "type": "integer", "required": true, "description": "拆包单ID" }, { "name": "computer_id", "type": "integer", "required": true, "description": "录制电脑ID(wms_print_computer.id,is_recording=true)" }, { "name": "print_service_url", "type": "string", "required": true, "description": "打印服务强制录制接口地址(POST {printService.url}/record/force)" }, { "name": "print_service_request", "type": "object", "required": true, "description": "推送给打印服务的请求体({ unpack_id })" }, { "name": "print_service_response", "type": "object", "required": false, "description": "打印服务响应(status/headers/data)" } ], "errors": [ { "code": "400", "message": "id 必填且必须为正整数" }, { "code": "400", "message": "该仓库无录制电脑,无法强制录制" }, { "code": "400", "message": "该仓库录制电脑不在线,无法强制录制" }, { "code": "401", "message": "未提供有效的认证令牌" }, { "code": "403", "message": "无权访问该拆包单" }, { "code": "403", "message": "无权访问该接口" }, { "code": "404", "message": "拆包单不存在" }, { "code": "500", "message": "通知打印服务失败" } ] }, { "method": "returnUnpack.list", "description": "拆包单分页列表(主表)。仓库隔离:warehouse_id 由服务端自动注入 ctx.user.store_id,禁止前端传入。支持拆包单号/运单号模糊、日期/时间范围、状态、拆包人员、退回收到单、货主、原运单/原订单等筛选。", "isNeedAuth": true, "isNeedLogin": true, "headers": [], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页 { page: 1, pageSize: 20 }(pageSize 上限 500,默认 20)" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "筛选条件对象,所有字段均可选" }, { "name": "where.unpack_no", "type": "string", "required": false, "source": "body.where", "description": "拆包单号(模糊搜索,传 {operator:'like',value} 或直接值)" }, { "name": "where.waybill_code", "type": "string", "required": false, "source": "body.where", "description": "运单号(模糊搜索,传 {operator:'like',value} 或直接值)" }, { "name": "where.unpack_date", "type": "object", "required": false, "source": "body.where", "description": "拆包日期范围 { operator:'between'|'gte'|'lte'|'gt'|'lt', value:[start,end] 或单值 }" }, { "name": "where.start_time", "type": "object", "required": false, "source": "body.where", "description": "拆包开始时间范围 { operator:'between'|'gte'|'lte'|'gt'|'lt', value:[start,end] 或单值 }" }, { "name": "where.end_time", "type": "object", "required": false, "source": "body.where", "description": "拆包结束时间范围 { operator:'between'|'gte'|'lte'|'gt'|'lt', value:[start,end] 或单值 }" }, { "name": "where.status", "type": "string", "required": false, "source": "body.where", "description": "拆包状态(等值):unpacking 拆包中 / completed 完成 / cancelled 作废" }, { "name": "where.detail_status", "type": "string", "required": false, "source": "body.where", "description": "明细识别状态(等值):none_recognized / partial_recognized / all_recognized" }, { "name": "where.unpacker_id", "type": "number", "required": false, "source": "body.where", "description": "拆包人员工号ID(等值)" }, { "name": "where.unpacker_name", "type": "string", "required": false, "source": "body.where", "description": "拆包人筛选:目标列 wms_return_unpack.unpacker_name(STRING(50),拆包人员工号名称快照)。传 {operator:'like',value} 或直接值 → 模糊 LIKE '%值%';value 为数组时多值 LIKE 取并集(trim/去空归一后为空退化为全匹配、不过滤);也支持 eq/ne/in/notin/between 等既有操作符" }, { "name": "where.return_received_id", "type": "number", "required": false, "source": "body.where", "description": "关联退回收到单ID(等值)" }, { "name": "where.store_id", "type": "number", "required": false, "source": "body.where", "description": "货主ID(等值)" }, { "name": "where.order_express_id", "type": "number", "required": false, "source": "body.where", "description": "原运单ID(等值)" }, { "name": "where.order_id", "type": "number", "required": false, "source": "body.where", "description": "原订单ID(等值)" }, { "name": "where.has_video", "type": "number", "required": false, "source": "body.where", "description": "是否有视频记录(等值):1=有视频记录 2=无视频记录" }, { "name": "where.video_enable", "type": "number", "required": false, "source": "body.where", "description": "录像是否可用(等值):1=可用(存在 video_url 非空且 status!=failed 的记录) 2=不可用" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序 { sortField: 'id'|'created_at'|'updated_at'|'unpack_date'|'start_time'|'end_time'|'unpack_no'|'waybill_code', sortOrder: 'asc'|'desc' },默认 created_at desc" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "拆包单列表,每条含主表字段 + is_original_return 派生字段 + 格式化时间字段 + camera_ids 数组 + 视频派生字段 has_video(1=有视频记录/2=无)与 video_enable(1=录像可用/2=不可用)+ videos 视频数组(id/video_url/status/camera_id/camera_name),video_url 自动拼接 CDN 域名前缀 http://w{warehouseId}-c{recordingComputerId}.o.gztbyc.com{path}(录制电脑从 wms_print_computer 按 is_recording=true 获取,无录制电脑时返回原始相对路径)" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息 { page, pageSize, total, totalPages, hasPrevious, hasNext }" } ], "errors": [ { "code": "401", "message": "未提供有效的认证令牌" }, { "code": "403", "message": "无权访问该接口" }, { "code": "500", "message": "服务器内部错误" } ] }, { "method": "returnUnpack.detailList", "description": "拆包明细分页列表,命中识别商品时含 stockWarehouse 关联,并统一走 stockWarehouse.getStockDetails 通用方法为每条识别明细附加 stock 库存详情对象(item_code/item_name/sku_property/barcodes 条码数组/image_url 图片数组/packing_requirements/stock_unit/quantity/locked_quantity 等,带缓存)。仓库隔离:warehouse_id 由服务端自动注入 ctx.user.store_id,禁止前端传入。支持按拆包单ID、系统商品、条码、识别标记、产品状态筛选。", "isNeedAuth": true, "isNeedLogin": true, "headers": [], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页 { page: 1, pageSize: 20 }(pageSize 上限 500,默认 20)" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "筛选条件对象,所有字段均可选" }, { "name": "where.unpack_id", "type": "number", "required": false, "source": "body.where", "description": "拆包单ID(等值)" }, { "name": "where.stock_id", "type": "number", "required": false, "source": "body.where", "description": "系统商品ID(wms_stock_warehouse.id,等值)" }, { "name": "where.barcode", "type": "string", "required": false, "source": "body.where", "description": "扫描条码(模糊搜索,传 {operator:'like',value} 或直接值)" }, { "name": "where.is_recognized", "type": "number", "required": false, "source": "body.where", "description": "是否识别(等值):1 识别到系统商品 / 0 非识别物品" }, { "name": "where.product_status", "type": "string", "required": false, "source": "body.where", "description": "产品状态(等值):normal 正常 / damaged 破损" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序 { sortField: 'id'|'created_at'|'updated_at'|'quantity', sortOrder: 'asc'|'desc' },默认 created_at desc" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "明细行列表(含 is_recognized/item_code/item_name/spec/product_snapshot,识别命中时含 stockWarehouse 关联与 stock 库存详情对象:barcodes 条码数组/image_url 图片数组/sku_property/packing_requirements/stock_unit 等)" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息 { page, pageSize, total, totalPages, hasPrevious, hasNext }" } ], "errors": [ { "code": "401", "message": "未提供有效的认证令牌" }, { "code": "403", "message": "无权访问该接口" }, { "code": "500", "message": "服务器内部错误" } ] }, { "method": "returnUnpack.detail", "description": "拆包单详情:主表 + 明细(含 stockWarehouse 关联,命中时;每条识别明细另附加 stock 库存详情对象,含 barcodes 条码数组/image_url 图片数组等,由 getStockDetails 通用方法拉取)+ 视频副表(含 camera 关联,命中时)+ 退回收到单(命中时);原单退回时(order_id 有值)返回 related.order 原订单详情。需 548 权限(客服员工及以上),仓库隔离校验(仅本仓库拆包单)。", "isNeedAuth": true, "isNeedLogin": true, "headers": [], "params": [ { "name": "id", "type": "integer", "required": true, "source": "body", "description": "拆包单ID" } ], "response": [ { "name": "record", "type": "object", "required": true, "description": "主表完整记录(含 details 明细、videos 视频(video_url 自动拼接 CDN 域名前缀 http://w{warehouseId}-c{recordingComputerId}.o.gztbyc.com{path})、returnReceived 退回收到单关联与格式化时间字段)" }, { "name": "related", "type": "object", "required": true, "description": "关联信息对象" }, { "name": "related.order", "type": "object", "required": false, "description": "原订单详情(含 items 明细,仅原单退回时返回,非原单为 null)" } ], "errors": [ { "code": "400", "message": "id 必填且必须为正整数" }, { "code": "401", "message": "未提供有效的认证令牌" }, { "code": "403", "message": "无权访问该拆包单" }, { "code": "404", "message": "拆包单不存在" }, { "code": "500", "message": "服务器内部错误" } ] }, { "method": "returnUnpack.delete", "description": "删除拆包单(后台管理,不限制状态):事务内物理删除主表 + 所有明细,并同步软删视频副表记录。作业层未完成状态取消请走 returnUnpack.cancel。仓库隔离校验(仅本仓库拆包单)。", "isNeedAuth": true, "isNeedLogin": true, "headers": [], "params": [ { "name": "id", "type": "integer", "required": true, "source": "body", "description": "拆包单ID" } ], "response": [ { "name": "id", "type": "integer", "required": true, "description": "被删除拆包单ID" } ], "errors": [ { "code": "400", "message": "id 必填且必须为正整数" }, { "code": "401", "message": "未提供有效的认证令牌" }, { "code": "403", "message": "无权访问该拆包单" }, { "code": "403", "message": "无权访问该接口" }, { "code": "404", "message": "拆包单不存在" }, { "code": "500", "message": "服务器内部错误" } ] }, { "method": "returnUnpack.export", "description": "提交退回拆包导出任务(异步)。入参 where/sort 语义与 returnUnpack.list 一致;warehouse_id 由服务端从 ctx.user.store_id 注入,禁止前端传入。提交后立即返回 task_id,后台异步生成双 Sheet Excel(Sheet1「正常退回运单号列表」+ Sheet2「明细表」)并上传,导出进度/下载请通过 returnUnpack.exportTaskProgress 查询。数据来源 wms_return_unpack 主表 + wms_return_unpack_detail 明细表;货主名取自 wms_store.company_name,快递类型取自 wms_order_express.logistics_name;颜色列取自明细 product_snapshot.sku_property 中「颜色:xxx」片段(兜底 spec),无颜色信息为空;全量分页拉取,无行数上限;Sheet1 不加 status 过滤(如需只导特定状态由调用方传 where.status)。任务缓存 Redis TTL 30 分钟;状态口径 submitted → running → 数据拉取(10~30) → 明细拉取(30~50) → Excel(55~90) → 上传(92) → success(100),失败 failed + error。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "where", "type": "object", "required": false, "source": "body", "description": "查询条件,语义与 returnUnpack.list 的 where 一致(支持 {operator,value,type} 标准结构或直接值;字段含 unpack_no/waybill_code/unpacker_name 模糊、unpack_date/start_time/end_time/created_at/updated_at 范围、status/detail_status/store_id/order_express_id/order_id/unpacker_id/return_received_id 等值、has_video/video_enable 等);禁止传入 warehouse_id/warehouseId(服务端注入);不传 status 时不过滤状态" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数,语义与 returnUnpack.list 的 sort 一致:sortField 白名单 id/created_at/updated_at/unpack_date/start_time/end_time/unpack_no/waybill_code,sortOrder asc/desc,默认 created_at desc" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID(后端生成,格式 return_unpack_export_{warehouseId}_{timestamp}_{random})" }, { "name": "status", "type": "string", "required": true, "description": "任务状态,枚举:submitted/running/success/failed/not_found(提交成功时为 submitted)" }, { "name": "progress", "type": "number", "required": true, "description": "当前进度百分比(0-100),提交时返回 0" }, { "name": "current_count", "type": "number", "required": true, "description": "当前已处理记录数(拆包单条数)" }, { "name": "total_count", "type": "number", "required": true, "description": "总记录数(若有)" }, { "name": "message", "type": "string", "required": true, "description": "任务提示信息" }, { "name": "result", "type": "object", "required": true, "description": "任务执行结果(提交时为 null;后台完成后为上传信息对象,含 filename/url/fileKey/cdnUrl/cosUrl/current_count/total_count/total_details/sheet_count)" }, { "name": "error", "type": "string", "required": true, "description": "失败时的错误信息(可选,非失败时为空字符串)" }, { "name": "update_time", "type": "number", "required": true, "description": "任务更新时间(Unix 毫秒时间戳)" } ], "errors": [ { "code": "400", "message": "参数格式不正确或 where 条件非法" }, { "code": "500", "message": "导出任务提交失败" } ] }, { "method": "returnUnpack.exportTaskProgress", "description": "按 task_id 查询退回拆包导出任务进度,返回 task_id、status、progress、current_count、total_count、message、result、error、download_url、update_time;上传完成后 download_url 返回下载链接(从 result.url/cdnUrl/cosUrl/fileKey 兜底取);任务缓存 Redis TTL 30 分钟,task_id 缺失或缓存未命中时 status=not_found(正常响应,非报错)。状态口径 submitted → running → 数据拉取(10~30) → 明细拉取(30~50) → Excel(55~90) → 上传(92) → success(100),失败 failed + error。免权限免日志口径与 order.exportTaskProgress 一致。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "task_id / taskId", "type": "string", "required": true, "source": "body|query", "description": "任务 ID,兼容 task_id(下划线)与 taskId(驼峰)两种写法" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID(task_id 缺失时为回显的空字符串,status=not_found)" }, { "name": "status", "type": "string", "required": true, "description": "任务状态:submitted/running/success/failed/not_found" }, { "name": "progress", "type": "number", "required": true, "description": "进度百分比(0-100)" }, { "name": "current_count", "type": "number", "required": true, "description": "当前已处理记录数(拆包单条数)" }, { "name": "total_count", "type": "number", "required": true, "description": "总记录数" }, { "name": "message", "type": "string", "required": true, "description": "任务提示信息" }, { "name": "result", "type": "object", "required": true, "description": "任务执行结果对象(完成后含 filename/url/fileKey/cdnUrl/cosUrl 等;未完成或 not_found 时为 null)" }, { "name": "error", "type": "string", "required": true, "description": "失败时的错误信息(可选,非失败时为空字符串)" }, { "name": "download_url", "type": "string", "required": true, "description": "任务完成后下载链接(从 result.url/cdnUrl/cosUrl/fileKey 兜底取);未完成或不存在时为空字符串" }, { "name": "update_time", "type": "number", "required": true, "description": "最近一次状态更新时间(Unix 毫秒时间戳)" } ], "errors": [ { "code": "500", "message": "查询失败或内部错误" } ] }, { "method": "returnUnpack.transferByWaybills", "description": "运单批量转入退件登记:一次调用把多个运单批量转入退回拆包登记。ids 为运单表主键ID(wms_order_express.id,支持单个数值或 JSON 数组),服务端 Number() 归一化 + 过滤非正整数 + 去重,去重后单次上限 200。仓库隔离:warehouse_id 由服务端从 ctx.user.store_id 注入,禁止前端传入。逐单处理,单条失败不阻断主流程,失败项进入 failed[](HTTP 整体仍成功)。单运单处理口径:1) 服务端按 id IN (ids) + 仓库一次批量反查 wms_order_express,未命中(不存在或非本仓库)记失败原因「运单不存在」;2) 子单(business_key>1)跳过并记失败原因「运单为子单(business_key>1),跳过」(不处理子单,一个运单只允许一条有效拆包单);3) 运单号为空时记失败原因「运单号为空,无法转入退件登记」;4) 命中运单统一置 wms_order_express.is_back='Y',不做其它前置条件限制(标记失败仅告警不阻断);5) 幂等:同仓库 + 同运单号已存在 status != 'cancelled' 的拆包单时直接复用(reused=true,不重复创建;同运单号多张时优先复用已录明细的最新单);复用单明细为空时按订单明细补写,已有明细不重复写入;6) 明细来源:运单关联订单的原本明细 1:1 复制(订单 items JSON 优先,为空回退明细分表;通过订单索引表 wms_order_id_location_{warehouseId} 定位车道,复用 ctx.service.systems.afterSale._resolveOrderDetail);订单无明细可复制时记失败原因「运单关联订单无明细可复制」;明细字段映射 stock_id / is_recognized / item_code / item_name / spec / quantity(订单行 plan_qty,最小 1)/ product_status='normal' / product_snapshot,写入后回填主表 total_items / total_quantity / detail_status;7) 命中退回收到登记(wms_return_received 同仓库 + 同运单号)时回填主表 return_received_id(失败仅告警不阻断)。", "isNeedAuth": true, "isNeedLogin": true, "headers": [], "params": [ { "name": "ids", "type": "array", "required": true, "source": "body", "description": "运单表主键ID列表(wms_order_express.id,也兼容单个数值,服务端统一归一化:Number() 转换 → 过滤非正整数 → 去重,去重后单次上限 200)" } ], "response": [ { "name": "total", "type": "number", "required": true, "description": "去重后待处理运单总数" }, { "name": "success_count", "type": "number", "required": true, "description": "成功转入数量" }, { "name": "failed_count", "type": "number", "required": true, "description": "失败数量" }, { "name": "success", "type": "array", "required": true, "description": "成功项数组,每项含 waybill_id(运单表主键ID)/ waybill_code(运单号)/ unpack_id(拆包单ID)/ unpack_no(拆包单号)/ reused(boolean,true=命中已有有效拆包单未重复创建)/ detail_count(明细行数)/ total_quantity(明细数量合计)" }, { "name": "failed", "type": "array", "required": true, "description": "失败项数组,每项含 waybill_id(运单表主键ID)/ waybill_code(运单号,运单命中时才有值,否则为 null)/ reason(失败原因,如「运单不存在」「运单为子单(business_key>1),跳过」「运单号为空,无法转入退件登记」「运单关联订单无明细可复制」)" } ], "errors": [ { "code": "400", "message": "ids 不能为空" }, { "code": "400", "message": "单次最多批量转入 200 个运单" }, { "code": "400", "message": "缺少仓库上下文" }, { "code": "400", "message": "缺少拆包人员工号上下文" }, { "code": "400", "message": "运单为子单(business_key>1),跳过" }, { "code": "400", "message": "运单号为空,无法转入退件登记" }, { "code": "400", "message": "运单关联订单无明细可复制" }, { "code": "404", "message": "运单不存在" }, { "code": "500", "message": "反查运单失败,请稍后重试" }, { "code": "401", "message": "未提供有效的认证令牌" }, { "code": "403", "message": "无权访问该接口" }, { "code": "500", "message": "服务器内部错误" } ], "notes": [ "单运单业务失败(运单不存在 / 子单跳过 / 运单号为空 / 订单无明细可复制)不抛 HTTP 错误,对应项进入 failed[](waybill_id + waybill_code + reason),整体响应仍为 success", "鉴权口径:isNeedAuth=true、isNeedLogin=true,未加入 _noNeedRight/_noNeedLogin/_noNeedLog/_noNeedAuth 免检清单;权限 wms_permission id=568 path=returnUnpack.transferByWaybills(meta_title=API:运单批量转入退件登记),授权角色 27(仓库组-员工)/ 26(仓库组-主管),经理/仓库管理员/超级管理员持 * 通配符自动拥有", "幂等复用命中时 reused=true 不重复创建;复用单明细为空时按订单明细补写,已有明细不重复写入", "标记 wms_order_express.is_back='Y' 与回填 return_received_id 为尽力而为(失败仅告警不阻断主流程)" ] } ] }, { "groupName": "未退登记模块", "module": "returnWaybill", "list": [ { "method": "returnWaybill.create", "description": "未退登记(增):录入「货主 + 运单号」退回关系。waybill_code/store_id 必填;校验 wms_store_warehouse 存在 store_id + warehouse_id 货主合约,无合约拒绝写入;同仓库+货主+运单号已存在时幂等返回已有记录(duplicated=true,不重复插入)。写入 is_notified=0/is_back=0(由定时任务与拆包联动维护,登记接口不维护)。仓库隔离:warehouse_id 由服务端注入 ctx.user.store_id,禁止前端传入。", "isNeedAuth": true, "isNeedLogin": true, "headers": [], "params": [ { "name": "waybill_code", "type": "string", "required": true, "source": "body", "description": "运单号(登记入参,必填,trim 后不能为空)" }, { "name": "store_id", "type": "integer", "required": true, "source": "body", "description": "货主ID(必填,正整数,需存在 wms_store_warehouse 中 store_id + warehouse_id 合约记录)" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注(可选,最长 500 字符,超出截断)" } ], "response": [ { "name": "record", "type": "object", "required": true, "description": "登记记录包装对象,含登记记录完整字段(id、warehouse_id、store_id、waybill_code、group_id、group_name、user_id、user_name、remark、is_notified、is_back、created_at、updated_at,时间字段为格式化字符串;group_id/group_name/user_id/user_name 为登记来源,仅站内信「查退回」触发登记时写入,后台登记为 null)" }, { "name": "duplicated", "type": "boolean", "required": true, "description": "是否命中已有记录:同仓库+货主+运单号已存在时为 true(返回已有记录,不重复插入),否则 false" } ], "errors": [ { "code": "400", "message": "waybill_code 不能为空" }, { "code": "400", "message": "store_id 必填且必须为正整数" }, { "code": "400", "message": "缺少仓库上下文" }, { "code": "400", "message": "货主在当前仓库无合约关系,无法登记" }, { "code": "401", "message": "未提供有效的认证令牌" }, { "code": "403", "message": "无权访问该接口" }, { "code": "500", "message": "服务器内部错误" } ] }, { "method": "returnWaybill.update", "description": "修改登记(改):id 必填,可改 waybill_code/store_id/remark。校验记录存在且属于当前仓库;store_id 变更时重新校验新货主合约(wms_store_warehouse 存在 store_id + warehouse_id);改后与另一条同仓库+货主+运单号冲突则 409 拒绝(防重复登记)。仓库隔离校验(仅本仓库记录)。", "isNeedAuth": true, "isNeedLogin": true, "headers": [], "params": [ { "name": "id", "type": "integer", "required": true, "source": "body", "description": "登记记录主键ID(必填,正整数)" }, { "name": "waybill_code", "type": "string", "required": false, "source": "body", "description": "运单号(可选,改运单号,trim 后不能为空字符串)" }, { "name": "store_id", "type": "integer", "required": false, "source": "body", "description": "货主ID(可选,改货主ID;变更时校验新货主在当前仓库的合约)" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注(可选,最长 500 字符,超出截断)" } ], "response": [ { "name": "record", "type": "object", "required": true, "description": "更新后的登记记录完整信息(含格式化时间字段)" } ], "errors": [ { "code": "400", "message": "id 必填且必须为正整数" }, { "code": "400", "message": "waybill_code 不能为空" }, { "code": "400", "message": "store_id 必填且必须为正整数" }, { "code": "400", "message": "货主在当前仓库无合约关系,无法登记" }, { "code": "401", "message": "未提供有效的认证令牌" }, { "code": "403", "message": "无权访问该登记记录" }, { "code": "403", "message": "无权访问该接口" }, { "code": "404", "message": "登记记录不存在" }, { "code": "409", "message": "已存在相同货主 + 运单号的登记记录" }, { "code": "500", "message": "服务器内部错误" } ] }, { "method": "returnWaybill.list", "description": "未退登记分页列表。仓库隔离:warehouse_id 由服务端注入 ctx.user.store_id,禁止前端传入。支持按运单号模糊、货主、是否已通知、是否退回、登记时间范围筛选。is_notified/is_back 由定时任务与拆包联动维护,登记接口不维护。", "isNeedAuth": true, "isNeedLogin": true, "headers": [], "params": [ { "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页 { page: 1, pageSize: 20 }(pageSize 上限 500,默认 20)" }, { "name": "where", "type": "object", "required": false, "source": "body", "description": "筛选条件对象,所有字段均可选" }, { "name": "where.waybill_code", "type": "string", "required": false, "source": "body.where", "description": "运单号(模糊搜索,传 {operator:'like',value} 或直接值)" }, { "name": "where.store_id", "type": "number", "required": false, "source": "body.where", "description": "货主ID(等值)" }, { "name": "where.is_notified", "type": "number", "required": false, "source": "body.where", "description": "是否已通知(等值):1 已通知 / 0 未通知(由定时任务维护,登记接口不写入)" }, { "name": "where.is_back", "type": "number", "required": false, "source": "body.where", "description": "是否退回(等值):1 已退回 / 0 未退回(由拆包单提交联动维护,登记接口不写入)" }, { "name": "where.created_at", "type": "object", "required": false, "source": "body.where", "description": "登记日期范围 { operator:'between'|'gte'|'lte'|'gt'|'lt', value:[start,end] 或单值 }" }, { "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序 { sortField: 'id'|'created_at'|'updated_at'|'waybill_code', sortOrder: 'asc'|'desc' },默认 created_at desc" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "未退登记列表,每条含登记字段(id、warehouse_id、store_id、waybill_code、group_id、group_name、user_id、user_name、remark、is_notified、is_back)及格式化时间字段;group_id/group_name/user_id/user_name 为登记来源(站内信「查退回」触发时写入,后台登记为 null)" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息 { page, pageSize, total, totalPages, hasPrevious, hasNext }" } ], "errors": [ { "code": "401", "message": "未提供有效的认证令牌" }, { "code": "403", "message": "无权访问该接口" }, { "code": "500", "message": "服务器内部错误" } ] }, { "method": "returnWaybill.detail", "description": "未退登记详情。免权限(复用列表权限),仅需登录 + 仓库隔离校验(仅本仓库记录)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [], "params": [ { "name": "id", "type": "integer", "required": true, "source": "body", "description": "登记记录主键ID(必填,正整数)" } ], "response": [ { "name": "record", "type": "object", "required": true, "description": "登记记录完整信息(id、warehouse_id、store_id、waybill_code、group_id、group_name、user_id、user_name、remark、is_notified、is_back 及格式化时间字段;来源字段仅站内信「查退回」触发登记时写入,后台登记为 null)" } ], "errors": [ { "code": "400", "message": "id 必填且必须为正整数" }, { "code": "401", "message": "未提供有效的认证令牌" }, { "code": "403", "message": "无权访问该登记记录" }, { "code": "404", "message": "登记记录不存在" }, { "code": "500", "message": "服务器内部错误" } ] }, { "method": "returnWaybill.delete", "description": "删除未退登记(物理删除,表 paranoid:false)。仓库隔离校验(仅本仓库记录)。", "isNeedAuth": true, "isNeedLogin": true, "headers": [], "params": [ { "name": "id", "type": "integer", "required": true, "source": "body", "description": "登记记录主键ID(必填,正整数)" } ], "response": [ { "name": "id", "type": "integer", "required": true, "description": "被删除登记记录ID" } ], "errors": [ { "code": "400", "message": "id 必填且必须为正整数" }, { "code": "401", "message": "未提供有效的认证令牌" }, { "code": "403", "message": "无权访问该登记记录" }, { "code": "403", "message": "无权访问该接口" }, { "code": "404", "message": "登记记录不存在" }, { "code": "500", "message": "服务器内部错误" } ] } ] }, { "groupName": "通用报表模块", "module": "report", "list": [ { "method": "report.generate", "description": "提交报表导出异步任务(手动导出):按报表定义ID读取 wms_report_definition(is_enabled=1)配置,经注册类型对应的内置查询器(type=stockFlow / interceptOrder 等)取数,并按类型硬编码字段规格(app/lib/report/render.js renderSheetByType)渲染 Excel 上传。上传目录按(报表定义 + 货主/仓库)维度隔离:store_id 有效时为 exports/report/{report_id}/store-{store_id},store_id 缺省且 warehouse_id 有效时为 exports/report/{report_id}/warehouse-{warehouse_id},两者均缺省时按 exports/report/{report_id}/common 兜底(保持手动导出兼容),避免不同货主的报表文件在 COS 上互相覆盖。立即返回任务受理信息(task_id/status=submitted),后台异步执行(执行中的错误体现在任务进度 error 字段),完成后可通过 report.generateTaskProgress 轮询进度并获取下载链接。warehouse_id 由服务端从登录上下文(ctx.user.store_id)自动注入,前端无需传递。仅登录即可调用(免权限:systemInit 声明 generate/generateTaskProgress 免权限;generate 不写审计日志)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "report_id", "type": "number", "required": false, "source": "body", "description": "报表定义ID(必填,与 reportId 二选一;均传时优先 reportId)。须为 wms_report_definition 中已启用(is_enabled=1)的报表定义" }, { "name": "reportId", "type": "number", "required": false, "source": "body", "description": "报表定义ID驼峰别名(兼容,优先级高于 report_id)" }, { "name": "store_id", "type": "number", "required": false, "source": "body", "description": "货主ID(可选,货主维度报表时传入;>0 生效,<=0 视为不按货主过滤)。有效时报表文件 key 按 store-{store_id} 目录隔离(缺省时按 warehouse-{warehouse_id} 或 common 兜底),避免不同货主的报表文件互相覆盖" }, { "name": "storeId", "type": "number", "required": false, "source": "body", "description": "货主ID驼峰别名(兼容,优先级高于 store_id)" }, { "name": "params", "type": "object", "required": false, "source": "body", "description": "查询器业务参数(透传给内置查询器,如 bizDate/dayCount/cutoverHour)" }, { "name": "params.bizDate", "type": "string", "required": false, "source": "body", "description": "数据日期(YYYY-MM-DD):用于导出文件名 file_name 模板的 {date} 占位(缺省取服务器当天);同时是 interceptOrder 查询器的统计日覆盖(按该日自然日整天统计,缺省为昨日自然日;该类型统计日不得晚于昨天,传今天/未来一律回落昨日,保证当天生成/投递的报表不含当天数据)" }, { "name": "params.dayCount", "type": "number", "required": false, "source": "body", "description": "窗口数量覆盖(仅 stockFlow 查询器经 resolveWindowConfig 解析,缺省 7,<=0 视为 7;interceptOrder 不使用该参数)" }, { "name": "params.cutoverHour", "type": "number", "required": false, "source": "body", "description": "切点小时覆盖(仅 stockFlow 查询器生效,缺省 7,钳制到 0-23;interceptOrder 不使用该参数,固定按自然日 00:00 切日)" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "导出任务ID(report_generate_ 前缀)" }, { "name": "status", "type": "string", "required": true, "description": "任务状态:submitted/running/success/failed。受理时恒为 submitted,最终状态经 report.generateTaskProgress 查询" }, { "name": "progress", "type": "number", "required": true, "description": "任务进度百分比(0-100)" }, { "name": "message", "type": "string", "required": true, "description": "任务状态说明(受理时为「导出任务已提交」)" }, { "name": "result", "type": "object|null", "required": true, "description": "任务结果对象;导出成功后为 { fileKey, url, filename, size },fileKey 为 COS 文件 key(含 exports/report/{report_id}/store-{store_id} 或 warehouse-{warehouse_id} 或 common 隔离目录,经 excel.generateAndUpload 追加 {YYYYMMDD} 日期目录与文件名),未完成或失败时为 null" }, { "name": "error", "type": "string", "required": true, "description": "失败时的错误信息;成功时为空字符串" }, { "name": "update_time", "type": "number", "required": true, "description": "任务状态更新时间(毫秒时间戳)" } ], "errors": [ { "code": 0, "message": "报表ID report_id 必须为正整数" } ] }, { "method": "report.generateTaskProgress", "description": "查询报表导出任务进度与结果:按 task_id 读取任务缓存(缓存 TTL 1800 秒)。status 可能值:submitted/running/success/failed/not_found;任务成功后 download_url 返回报表文件下载链接。仅登录即可调用(免权限)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id", "type": "string", "required": false, "source": "body", "description": "导出任务ID(下划线写法,与 taskId 二选一)" }, { "name": "taskId", "type": "string", "required": false, "source": "body", "description": "导出任务ID(驼峰写法,兼容别名)" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "导出任务ID;未传入时为空字符串" }, { "name": "status", "type": "string", "required": true, "description": "任务状态:submitted/running/success/failed/not_found(任务不存在时)" }, { "name": "progress", "type": "number", "required": true, "description": "任务进度百分比(0-100);not_found 时为 0" }, { "name": "message", "type": "string", "required": true, "description": "任务状态说明" }, { "name": "result", "type": "object|null", "required": true, "description": "任务结果对象;导出成功后为 { fileKey, url, filename, size },未完成或失败时为 null" }, { "name": "error", "type": "string", "required": true, "description": "失败时的错误信息;成功时为空字符串" }, { "name": "download_url", "type": "string", "required": true, "description": "任务成功后返回的下载链接(取 result.url/cndUrl/cosUrl/fileKey 兜底);未完成或失败时为空字符串" }, { "name": "update_time", "type": "number", "required": true, "description": "任务状态更新时间(毫秒时间戳)" } ], "errors": [] }, { "method": "report.deliveryPlan.save", "description": "新增/更新货主报表投递计划(货主 store_id + 报表定义ID report_id 唯一,存在则更新):先校验报表定义存在且启用(wms_report_definition.is_enabled=1),schedule_times 自动去重并按升序排序,channel 仅支持 inbox(默认 inbox,wecom/link 已弃用,非法渠道报错;历史 wecom/link 计划在投递时按 inbox 兜底执行),late_grace_minutes 夹取到 0-1440。可选计划名称 name(仅展示字段,不参与幂等/关联逻辑;未传不覆盖,null/空串/全空白清空,非空 trim 后 ≤100 字符,超长报错)。inbox 推送失败自动经 inbox.message.retry 立即重推一次,重推仍失败进入 failed 退避重试(MAX_RETRY=3,退避 retry_count × 60s)。可选文本通知配置:notify_template(≤500,标签白名单 {time}/{url}/{report_name}/{biz_date},未知标签报错)、notify_group_ids(wms_inbox_group.id,正整数去重 ≤20,保存时校验存在性且排除软删)、notify_member_ids(外部 IM 用户 ID,非空字符串去重 ≤100);三者仅在入参存在时生效(未传保持原值,不传行为与旧版一致)。群路由口径(2026-09-01 修复,G1 缺陷):报表文件消息仅投递到计划配置的 notify_group_ids(投递与文本通知共用 resolveNotifyGroups 解析,过滤 is_blocked=1、软删、仓库维度不一致的群);配置了通知群但全部不可达(不存在/已删除/被屏蔽/仓库不一致)时投递抛错进入 failed 退避重试(MAX_RETRY=3,退避 retry_count × 60s),不再回退到未配置群;未配置通知群的历史计划保持旧行为,回退投递到货主默认站内信群(group_type=store,按 id ASC 取最早一条)。需授权接口(管理类操作,systemInit 未声明免权限,仅通配符角色或已授权角色可用)。", "isNeedAuth": true, "isNeedLogin": true, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "store_id", "type": "number", "required": true, "source": "body", "description": "货主ID(必填,正整数;<=0 报错)" }, { "name": "report_id", "type": "number", "required": false, "source": "body", "description": "报表定义ID(必填,与 reportId 二选一;均传时优先 reportId)。须为已启用(is_enabled=1)的报表定义" }, { "name": "reportId", "type": "number", "required": false, "source": "body", "description": "报表定义ID驼峰别名(兼容,优先级高于 report_id)" }, { "name": "schedule_times", "type": "array", "required": true, "source": "body", "description": "每日投递时间点数组(HH:mm 24 小时制,非空;自动去重并按升序排序;支持 JSON 字符串数组)" }, { "name": "channel", "type": "string", "required": false, "source": "body", "description": "投递渠道(可选):仅支持 inbox,默认 inbox;wecom/link 已弃用,传入非法渠道报错「投递渠道仅支持 inbox: 」;历史 wecom/link 计划在投递时按 inbox 兜底执行", "list": [ { "value": "inbox", "name": "站内信" } ] }, { "name": "late_grace_minutes", "type": "number", "required": false, "source": "body", "description": "补投宽限分钟(0-1440),默认 60;越界值夹取到 0-1440" }, { "name": "name", "type": "string|null", "required": false, "source": "body", "description": "计划名称(可选,仅展示字段,不参与幂等/关联逻辑)。未传不覆盖既有值;null/空串/全空白归一化为 null(显式清空);非空 trim 后最长 100 字符,超长报错「计划名称 name 长度不能超过 100 字符」" }, { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注(最长 500 字符,超出截断)" }, { "name": "notify_template", "type": "string", "required": false, "source": "body", "description": "文本通知模板(可选,最长 500 字符,超出报错)。支持标签 {time}/{url}/{report_name}/{biz_date},含白名单外标签时报错并列出非法标签;空值视为未启用(清空配置);仅入参存在时生效,未传不修改既有配置" }, { "name": "notify_group_ids", "type": "array", "required": false, "source": "body", "description": "通知群ID数组(可选,wms_inbox_group.id;正整数自动去重并升序,最多 20 个;保存时校验存在性,软删已删除的群报错并列出缺失 ID,被屏蔽的群仍可选中;支持 JSON 字符串数组;空数组视为不选择群)。该群同时作为报表文件消息的投递目标:配置后文件消息仅逐群投递到这些配置群;未配置(空数组/原值为空)的历史计划投递时回退到货主默认站内信群" }, { "name": "notify_member_ids", "type": "array", "required": false, "source": "body", "description": "通知成员ID数组(可选,外部 IM 用户 ID;非空字符串自动去重,最多 100 个;推送时 user_id 支持数组整体透传不循环拆发;支持 JSON 字符串数组;空数组视为不选择成员)" } ], "response": [ { "name": "id", "type": "number", "required": true, "description": "投递计划ID" }, { "name": "store_id", "type": "number", "required": true, "description": "货主ID" }, { "name": "report_definition_id", "type": "number", "required": true, "description": "报表定义ID(wms_report_definition.id)" }, { "name": "schedule_times", "type": "array", "required": true, "description": "每日投递时间点数组(HH:mm,去重升序)" }, { "name": "channel", "type": "string", "required": true, "description": "投递渠道:inbox(渠道已收敛,仅支持 inbox)" }, { "name": "enabled", "type": "number", "required": true, "description": "是否启用:0=停用 1=启用" }, { "name": "late_grace_minutes", "type": "number", "required": true, "description": "补投宽限分钟(0-1440)" }, { "name": "name", "type": "string", "required": true, "description": "计划名称(未设置时为空字符串)" }, { "name": "remark", "type": "string", "required": true, "description": "备注" }, { "name": "notify_template", "type": "string", "required": true, "description": "文本通知模板(未配置时为空字符串)" }, { "name": "notify_group_ids", "type": "array|null", "required": true, "description": "通知群ID数组(内部 wms_inbox_group.id,去重升序;未选择时 null);同时为报表文件消息投递目标群(配置后文件消息仅投递这些群,未配置时回退货主默认站内信群)" }, { "name": "notify_member_ids", "type": "array|null", "required": true, "description": "通知成员ID数组(外部 IM 用户 ID,去重;未选择时 null)" }, { "name": "created_at", "type": "string", "required": true, "description": "创建时间" }, { "name": "updated_at", "type": "string", "required": true, "description": "更新时间" } ], "errors": [ { "code": 500, "message": "货主ID store_id 不能为空" }, { "code": 500, "message": "报表ID report_id 必须为正整数" }, { "code": 500, "message": "报表定义不存在或已停用: id=" }, { "code": 500, "message": "schedule_times 必须为 HH:mm 字符串数组且不能为空" }, { "code": 500, "message": "schedule_times 含非法时间点(需 HH:mm 24 小时制):