docs(methods): 同步 system 接口文档至 0.3.37 并追加 5 条变更记录

- order.export 新增 export_columns 导出表头白名单参数
- order.pendingOrder.allocateStorage 修复 allow_storage_location=true 未生效
- storage.entry.quickInbound 支持按绑定收货单交集直入并回写收货单入库状态
- storage.management.replenishmentDemand 新增货主筛选参数与 store_name/barcodes 响应字段
This commit is contained in:
liufumingren 2026-08-27 23:43:41 +08:00
parent d6d7b23f52
commit a5eba20a5e
2 changed files with 150 additions and 7 deletions

View File

@ -1,4 +1,20 @@
[
{
"version": "2026.08.27-order-allocateStorage-allow-storage-location",
"date": "2026-08-27",
"type": "fixed",
"summary": "order.pendingOrder.allocateStorage 修复 allow_storage_location=true 未生效:分配储位时仍强制校验库位类型 allow_allocation=1/is_active=1,存储储位被过滤。现在 allow_storage_location=true 时直接分配储位,无视库位类型的可分配/启用限制",
"methods": [
"order.pendingOrder.allocateStorage"
],
"notes": [
"app/service/systems/order_storage_allocation.js allocatePicking:storageRows 查询的 locationType include where(allow_allocation:1/is_active:1)改为仅当 allowStorageLocation=false 时生效;true 时不再过滤库位类型限制",
"无候选库位时的缺货诊断 diagnoseStorageTypeRestriction 仅在 allowStorageLocation=false 时执行,避免「库位类型不可分配/未启用」被误报为缺货原因",
"可分配库存查询完成日志补充 allowStorageLocation 字段",
"同步更新 methods/system.json:order.pendingOrder.allocateStorage 描述与 allow_storage_location 参数说明"
],
"module": "order"
},
{
"version": "2026.08.27-order-export-stock-query",
"date": "2026-08-27",
@ -49,6 +65,73 @@
],
"module": "storage.entry"
},
{
"version": "2026.08.27-storage-management-replenishmentDemand-owner-filter",
"date": "2026-08-27",
"type": "enhanced",
"summary": "storage.management.replenishmentDemand 新增货主筛选:store_id(单值或数组)或 where.store_id 传入,仅返回指定货主的 SKU,summary 同步只统计筛选后数据",
"methods": [
"storage.management.replenishmentDemand"
],
"notes": [
"app/service/systemMethods/storage/management.js replenishmentDemand:解析 store_id / store_ids / where.store_id(单值/数组),归一化为正整数数组去重,非法值(非正整数)抛错;空值不筛选。",
"app/service/systems/storage/management.js replenishmentDemand:options.storeIds 构建 Set,组装输出循环内非命中货主 SKU 直接跳过,list 与 summary 统计口径一致(仅含筛选货主)。",
"同步更新 methods/system.json 参数文档(新增 store_id 参数说明)。"
],
"module": "storage.management"
},
{
"version": "2026.08.27-quickInbound-receiving-intersection",
"date": "2026-08-27",
"type": "enhanced",
"summary": "storage.entry.quickInbound 支持绑定收货单交集直入:有绑定时按 stock_id 只取收货单中剩余可入数量(actual_quantity - stored_quantity)与入库明细的较小值直入,并回写收货单明细已入库数量与收货单入库状态",
"methods": [
"storage.entry.quickInbound"
],
"notes": [
"app/service/systems/storage/entry.js quickInbound:新增绑定收货单查询(wms_entry_order_receiving),按 stock_id(=收货明细 system_product_id)聚合剩余可入数量 actual_quantity - stored_quantity",
"入库明细实际直入量 = min(计划数量, 剩余可入数量);无交集商品跳过(明细 received_quantity 写 0),全部无交集或剩余为 0 时返回 400「收货单中无交集商品或剩余可入数量不足,无法快捷直入」",
"未绑定收货单保持原行为:按明细计划数量全量直入",
"存在截断/跳过明细时 isFin=false(confirmType=1, PARTFULFILLED)回传奇门/API",
"新增 _applyReceivingInboundUsage 事务内回写:行锁重读收货明细,按明细 id 升序分配本次入库量(每个明细最多分配其剩余可入数量),更新 stored_quantity(使用了多少写多少)与 storage_status(all/partial),并汇总更新收货单主表 storage_status",
"收货单主表 storage_status 按实际数量判定:全部明细 stored_quantity >= actual_quantity 才置 all;有部分入库置 partial;全部未入库置 none——收货单未全部使用所有商品时不会转为全部入库",
"入库单明细 received_quantity 改为写实际入库量(原来写计划数量)",
"响应新增 plan_quantity(计划入库总数量),total_quantity 语义改为实际入库总数量,items_count 语义改为实际入库明细条目数"
],
"module": "storage.entry"
},
{
"version": "2026.08.27-storage-management-replenishmentDemand-owner-barcode",
"date": "2026-08-27",
"type": "enhanced",
"summary": "storage.management.replenishmentDemand 响应 list 每项新增 store_id(货主ID)、store_name(货主名称)、barcodes(SKU 条码列表)字段",
"methods": [
"storage.management.replenishmentDemand"
],
"notes": [
"app/service/systems/storage/management.js replenishmentDemand:StockWarehouse 三处查询(严格/宽松/终极兜底)attributes 均新增 store_id,stockInfoMap 记录货主ID。",
"新增货主名称查询:StoreWarehouse(store_remask 签约表备注名)优先、Store(company_name 商家公司名)兜底;新增 StockBarcode 按 stock_id 批量查询条码并分组为 barcodes: [{id, barcode}]。",
"货主与条码查询与库存查询为顺序执行(货主/条码三表在 Promise.all 内并行)。",
"响应字段:store_id (number) 货主ID;store_name (string) 货主名称;barcodes (array) 条码列表,children: id (number)/barcode (string)。",
"同步更新 methods/system.json 响应文档。"
],
"module": "storage.management"
},
{
"version": "2026.08.27-order-export-columns",
"date": "2026-08-27",
"type": "enhanced",
"summary": "order.export 新增 export_columns/exportColumns 导出表头字段白名单参数(中文表头数组):不传或空数组输出全部列;传入时仅输出指定列;校验枚举覆盖 waybill/item 两种模式全部 51 个中文表头,非法表头抛错并列出非法值。",
"methods": [
"order.export"
],
"notes": [
"app/service/systems/order_export.js:新增 ORDER_EXPORT_ALL_COLUMN_HEADERS(waybill/item 两种模式表头并集,共 51 个);getOrderExportColumns(mode, selectedHeaders) 支持按中文表头过滤;新增 normalizeExportColumns(数组去重/trim/非法值抛错);exportOrders 读取 export_columns/exportColumns(下划线优先)并作用到初始 sheet 与自动续写的后续 sheet(resolvedColumns 复用)",
"app/service/systemMethods/order/index.js export:解构 export_columns/exportColumns 并透传数组,未传时传空数组(输出全部列)",
"methods/system.json order.export 新增 export_columns/exportColumns 参数文档:枚举全量 51 个中文表头,并标注仅 waybill 模式输出(系统订单号、外部订单号、平台单号、抓取波次号、商品明细)与仅 item 模式输出(订单ID、订单号、外部单号、波次号、仓库商品名称、商品条码、商品图片、数量)的字段"
],
"module": "order"
},
{
"version": "2026.08.26-wave-batchList-store-id-filter",
"date": "2026-08-26",

View File

@ -1,8 +1,8 @@
{
"module": "system",
"description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内",
"version": "0.3.36",
"updatedAt": "2026-08-25",
"version": "0.3.37",
"updatedAt": "2026-08-27",
"headers": [
{
"name": "platform",
@ -2537,6 +2537,13 @@
"required": false,
"source": "body",
"description": "导出模式:waybill(默认,按运单展开,items_detail 列汇总商品)或 item(按商品明细展开,每商品一行);支持 export_mode 与 exportMode 两种写法"
},
{
"name": "export_columns / exportColumns",
"type": "array",
"required": false,
"source": "body",
"description": "导出表头字段白名单(中文表头字符串数组,如 [\"系统订单号\",\"外部订单号\"]);不传或空数组时输出全部列。枚举(共 51 个,校验不区分导出模式):系统订单号、外部订单号、平台单号、订单ID、订单号、外部单号、订单状态、抓取波次号、波次号、波次序号、货主、平台、店铺昵称、收件人、收件人电话、省、市、区、镇、详细地址、商品明细、仓库商品名称、商品条码、商品图片、数量、物流公司、运单号、业务类型、运单接口、包材ID、包材编码、包材名称、分配时间、商品种数、商品件数、商品重量、称重重量(g)、订单金额、实收金额、创建时间、支付时间、发货时间、出库状态、复核状态、复核完成状态、配货状态、打包状态、备注、买家留言、卖家留言、归档时间。其中仅 waybill 模式输出:系统订单号、外部订单号、平台单号、抓取波次号、商品明细;仅 item 模式输出:订单ID、订单号、外部单号、波次号、仓库商品名称、商品条码、商品图片、数量;其余为两种模式通用(选了当前模式不存在的表头时该列自动忽略)。传入非法表头会报错(错误信息列出非法值);支持 export_columns 与 exportColumns 两种写法"
}
],
"response": [
@ -3412,7 +3419,7 @@
},
{
"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')。",
"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": [
@ -3429,7 +3436,7 @@
"type": "boolean",
"required": false,
"source": "body",
"description": "是否允许使用存储储位,支持多种字段别名。"
"description": "是否允许使用存储储位,支持多种字段别名。为 true 时直接分配储位,无视库位类型的 allow_allocation/is_active 限制;缺省时仅校验可分配储位。"
},
{
"name": "order_ids / orderIds / ids / order_id / orderId / id",
@ -22579,7 +22586,7 @@
},
{
"method": "storage.entry.quickInbound",
"description": "快捷直入(虚拟入库):将入库单所有商品按明细数量一键直入到虚拟库位(space_id=2),跳过收货/质检流程,入库单状态变为COMPLETED。仅支持 CREATED 状态的入库单;CANCELLED(已作废)、COMPLETED(已完成)、PENDING 等其他状态均拒绝操作。事务内操作:更新入库明细收货量、累加库存总量、写入库存流水、写入虚拟库位库存、变更入库单状态为 COMPLETED。事务外异步回传奇门/API。",
"description": "快捷直入(虚拟入库):将入库单商品直入到虚拟库位(space_id=2),跳过收货/质检流程。有绑定收货单时,只取收货单中与入库单明细有交集(按 stock_id 判断)且剩余可入数量(actual_quantity - stored_quantity)的商品直入,实际入库量 = min(明细计划数量, 收货单剩余可入数量),并在事务内回写收货单明细已入库数量与收货单入库状态;未绑定收货单时按明细计划数量全量直入。仅支持 CREATED 状态的入库单;CANCELLED(已作废)、COMPLETED(已完成)、PENDING 等其他状态均拒绝操作。事务内操作:更新入库明细收货量、累加库存总量、写入库存流水、写入虚拟库位库存、回写收货单明细、变更入库单状态为 COMPLETED。事务外异步回传奇门/API。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [],
@ -22621,13 +22628,19 @@
"name": "items_count",
"type": "number",
"required": true,
"description": "入库明细条目数"
"description": "实际入库明细条目数(有绑定收货单时为与收货单有交集且实际入库量大于0的明细数)"
},
{
"name": "total_quantity",
"type": "number",
"required": true,
"description": "入库总数量"
"description": "实际入库总数量(有绑定收货单时=与收货单交集部分的实际直入数量)"
},
{
"name": "plan_quantity",
"type": "number",
"required": true,
"description": "计划入库总数量"
}
],
"errors": [
@ -22654,6 +22667,14 @@
{
"code": 400,
"message": "请先添加入库明细"
},
{
"code": 400,
"message": "收货单中无交集商品或剩余可入数量不足,无法快捷直入"
},
{
"code": 400,
"message": "入库明细数量均为0,无法快捷直入"
}
]
},
@ -25579,6 +25600,13 @@
"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": [
@ -25606,6 +25634,38 @@
"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",