From aff7a4fe22cb798a25763d0e718004eb833f76a3 Mon Sep 17 00:00:00 2001 From: liufumingren Date: Tue, 15 Sep 2026 16:19:22 +0800 Subject: [PATCH] =?UTF-8?q?docs(api):=20=E5=90=8C=E6=AD=A5=20system=20?= =?UTF-8?q?=E6=8E=A5=E5=8F=A3=E6=96=87=E6=A1=A3=E3=80=81=E5=8F=98=E6=9B=B4?= =?UTF-8?q?=E8=AE=B0=E5=BD=95=E4=B8=8E=E6=96=B9=E6=B3=95=E8=B7=AF=E7=94=B1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - methods/changes/system.json 补 6 条变更记录: - returnUnpack.transferByWaybills 新增及入参 waybill_codes → ids(运单表主键) - order 各列表补充 create_channel 查询条件说明;修正 pendingOrder/outboundOrder 默认筛选描述 - storage.inventory.updateExpiry 新接口 - workbench.packOrder / finishPack 打包结束复位 OSD - order.pendingOrder.syncOrderIds 同步顺序(先回传、成功再扣减) - methods/system.json 同步上述接口描述 - AI_METHOD_ROUTING.md 重新生成方法清单(order_async / receiving_entry_match / return_unpack / storage.inventory / stockout_order / storage.entry / wave_batch_closure / workbench 等模块方法数变化) --- AI_METHOD_ROUTING.md | 62 ++++---- methods/changes/system.json | 126 ++++++++++++++++ methods/system.json | 293 ++++++++++++++++++++++++++++++++++-- 3 files changed, 435 insertions(+), 46 deletions(-) diff --git a/AI_METHOD_ROUTING.md b/AI_METHOD_ROUTING.md index ae5e9ab..79665c1 100644 --- a/AI_METHOD_ROUTING.md +++ b/AI_METHOD_ROUTING.md @@ -216,7 +216,7 @@ rg "class .*Service|module.exports" app/service/qimenMethods > 破坏性协议变更(2026-09-12):OpenAPI 出站回调的 `method`(query)由 snake_case 事件名统一改为 `模块.动作`(与奇门 method 去掉 `taobao.qimen.` 前缀后对齐)。旧事件名已全部废弃,无新旧兼容、无双发,接收方必须同步改造。 > -> 破坏性协议变更(2026-09-13):报文体由 `{ event, data, metadata }` 改为奇门同层级的 `{ request: {...} }`,发送端不再发送数据/元数据,`event` 仅出现在 query 的 `method`;`deliveryorder.confirm` 由一次批量汇总通知改为逐单发送(仅对 `syncResults` 中 `status==='success'` 的订单,成功 N 单 = N 次回调)。接收方必须按新报文结构改造。 +> 破坏性协议变更(2026-09-13):报文体由 `{ event, data, metadata }` 改为奇门同层级的 `{ request: {...} }`,发送端不再发送数据/元数据,`event` 仅出现在 query 的 `method`;`deliveryorder.confirm` 由一次批量汇总通知改为逐单发送(每单在同步时发送,**回调成功才扣减库存并置 `sync_status='fin'`**,失败置 `error` + 待处理异常、不扣减库存;成功 N 单 = N 次回调)。接收方必须按新报文结构改造。 ### 5.6.1 method 命名规范 - 格式:`模块.动作`(如 `entryorder.confirm`、`stockout.confirm`) @@ -229,7 +229,7 @@ rg "class .*Service|module.exports" app/service/qimenMethods |---|---|---|---| | `entry_order_direct_inbound_completed` | `entryorder.confirm` | 直入入库(API 来源,`source_type=API`)完成后回传 | `app/service/systems/inbound_direct_log.js`(`qimenEntrySync` → `_sendOpenApiCallback`,约 1470 行) | | `entry_order_receiving_matched` | `entryorder.match` | 入库单匹配收货单完成后回传(API 来源) | `app/service/systems/receiving_entry_match.js`(`_sendCallback` → `_sendOpenApiCallback`,约 1864 行) | -| `order_completed` | `deliveryorder.confirm` | API 渠道订单同步(出库)完成后逐单触发(仅对 `syncResults` 中 `status==='success'` 的订单,成功 N 单 = N 次回调;fire-and-forget,失败仅 warn)。发送用 appKey 优先取调用上下文 `context.appKey`,缺失时按订单货主(`store_id`+`warehouse_id`)合约反查 `wms_store_warehouse(auth_status=2)` → `wms_api_app(is_enabled=1 且 callback_url 非空)` 的 `self_app_key`(同批次按货主缓存),解析不到则跳过该订单不发(此前 routeContext 缺 appKey 导致该回调从未发出,2026-09-13 已修复) | `app/service/systems/order_async.js`(`finalizeLocalChannelOrdersInternal` → `notifyApiDeliveryOrderConfirmsInternal`) | +| `order_completed` | `deliveryorder.confirm` | API 渠道订单同步时逐单发送(同一个 `finalizeLocalChannelOrdersInternal` 分发循环,`DISPATCH_BATCH_SIZE=20` 批内并行):每单先组装报文(缺 ownerCode → 失败)→ 解析 appKey → `sendByAppKey` 发送(最多 4 次尝试)→ **回调成功才扣减库存并置 `sync_status='fin'`**;失败统一置 `sync_status='error'` + 待处理异常、不扣减库存、可重新派发(成功 N 单 = N 次回调)。发送用 appKey 优先取调用上下文 `context.appKey`,缺失时按订单货主(`store_id`+`warehouse_id`)合约反查 `wms_store_warehouse(auth_status=2)` → `wms_api_app(is_enabled=1 且 callback_url 非空)` 的 `self_app_key`(同批次按货主缓存);解析不到 appKey(缺 store_id / 无授权关系 / 无可用 ApiApp)**不再静默跳过**,按失败处理(此前 routeContext 缺 appKey 导致该回调从未发出,2026-09-13 已修复) | `app/service/systems/order_async.js`(`finalizeLocalChannelOrdersInternal` → `processApiOrderInternal`) | | `stockout_completed` | `stockout.confirm` | 出库单确认回传(API 来源,`source_type=API`) | `app/service/systems/order_async.js`(`notifyStockoutExternalInternal` → `buildStockoutConfirmDataInternal`) | | `order_cancelled` | `deliveryorder.cancel` | 订单取消成功后触发(fire-and-forget;出站事件名与入站方法 `order.cancel` 区分,避免 `callback_url` 误指向 `/openapi` 时被路由到取消单据接口;**无奇门对应接口**,按 `deliveryOrder` 节点约定自定义,`status` 固定 `CANCELED`) | `app/service/openapiMethods/order.js`(`cancel`,约 296 行) | @@ -250,7 +250,7 @@ rg "class .*Service|module.exports" app/service/qimenMethods 各层字段口径详见 `methods/openapi_callback.json` / `docs/openapi-callback-events.md`(与 `callbackRegistry.js` 的 `request` 模板一致) - 签名(`app/lib/api_sign.js#signRequest`):`sign = md5(canonicalQuery + selfAppSecret + md5(stableStringify(body)))`;`canonicalQuery` 为除 `sign`/`signature` 外 query 按 key 字母序 `key=value&…` 拼接(签名用未 URL 编码原值,实际 URL 中 `method`/`app_key` 做 `encodeURIComponent`);`bodySign` 基于 `{ request }` 完整报文 -- 重试(`app/service/openapi/callback.js#sendWithRetry`):非 2xx 或网络错误最多重试 3 次(`MAX_RETRY=3`),间隔 2s → 5s → 15s,单次超时 30s;每次尝试写 `[OpenapiCallback]` 日志(`logCallback`) +- 重试(`app/service/openapi/callback.js#sendWithRetry`):非 2xx 或网络错误最多重试 3 次(`MAX_RETRY=3`),间隔 2s → 5s → 15s,单次超时 30s;每次尝试写 `[OpenapiCallback]` 日志(`logCallback`);`deliveryorder.confirm` 单订单 4 次尝试后仍失败 ⇒ 该订单同步判定失败(`sync_status='error'` + 待处理异常,不扣减库存,可重新派发) - 事件注册表:`app/service/openapi/callbackRegistry.js#CALLBACK_EVENTS`(5 条,每条含 `name`/`label`/`description`/`request`,`request` 为奇门同层级报文模板),回调调试页 `GET /docs/api/openapi/callback-test`(`app/controller/openapiCallback.js`)直接消费该注册表,并按注册表自动预填完整报文体 `{ request: {...} }` - 完整协议文档:`docs/openapi-callback-events.md` @@ -265,7 +265,7 @@ rg "class .*Service|module.exports" app/service/qimenMethods - 临时清单输出:temp/tmp-service-method-inventory.md -自动生成时间: 2026-09-12T11:41:21.651Z +自动生成时间: 2026-09-15T05:49:02.545Z 扫描范围: app/service/**/*.js 文件数: 210 @@ -302,8 +302,8 @@ rg "class .*Service|module.exports" app/service/qimenMethods - getRecordingComputerId, buildVideoUrl - app/service/main.js (18) - success, fail, normalizeDate, setInfo, getInfo, isPlainObject, normalizeWhereCondition, normalizeWhereParams, extractWhereValues, prepareWhereContext, findQimenAppWithContract, queryFromDatabase, checkAuth, checkApiPermission, extractApiPermissionState, collectApiPermissionValue, setUserContext, systemInit -- app/service/openapi/callback.js (4) - - signCallback, sendWithRetry, sendByAppKey, logCallback +- app/service/openapi/callback.js (6) + - md5, signCallback, sendWithRetry, sendByAppKey, _formatResponsePayload, logCallback - app/service/openapi/callbackRegistry.js (0) - - app/service/openapiEntry.js (9) @@ -420,8 +420,8 @@ rg "class .*Service|module.exports" app/service/qimenMethods - save, copy, list - app/service/systemMethods/returnReceived.js (12) - _call, create, list, detail, delete, export, exportTaskProgress, generateExportTaskId, normalizeExportTaskId, getExportTaskCacheKey, setExportTaskProgress, getExportTaskProgress -- app/service/systemMethods/returnUnpack.js (20) - - _call, create, addDetail, updateDetail, removeDetail, cancel, submit, forceRecord, list, detailList, videoList, detail, export, exportTaskProgress, generateExportTaskId, normalizeExportTaskId, getExportTaskCacheKey, setExportTaskProgress, getExportTaskProgress, delete +- app/service/systemMethods/returnUnpack.js (21) + - _call, create, transferByWaybills, addDetail, updateDetail, removeDetail, cancel, submit, forceRecord, list, detailList, videoList, detail, export, exportTaskProgress, generateExportTaskId, normalizeExportTaskId, getExportTaskCacheKey, setExportTaskProgress, getExportTaskProgress, delete - app/service/systemMethods/returnWaybill.js (6) - _call, create, update, list, detail, delete - app/service/systemMethods/setting/account.js (7) @@ -466,8 +466,8 @@ rg "class .*Service|module.exports" app/service/qimenMethods - list, listStore, get, getStore, cancel, addItem, commit, removeItem, bindReceiving, unbindReceiving, quickInbound, getPrintData, receivingCompare, queryEntryLogs, getReceivingDetailsForBind, containerList, reviewEntry, export, exportTaskProgress, generateExportTaskId, normalizeExportTaskId, getExportTaskCacheKey, setExportTaskProgress, getExportTaskProgress, storeExport, storeExportTaskProgress - app/service/systemMethods/storage/expiry.js (1) - list -- app/service/systemMethods/storage/inventory.js (15) - - transferLocation, transferByProduct, extractStockQueryVirtualFilter, list, listByStockId, listBySpaceId, quickPutaway, directPutaway, export, exportTaskProgress, generateExportTaskId, normalizeExportTaskId, getExportTaskCacheKey, setExportTaskProgress, getExportTaskProgress +- app/service/systemMethods/storage/inventory.js (16) + - transferLocation, transferByProduct, updateExpiry, extractStockQueryVirtualFilter, list, listByStockId, listBySpaceId, quickPutaway, directPutaway, export, exportTaskProgress, generateExportTaskId, normalizeExportTaskId, getExportTaskCacheKey, setExportTaskProgress, getExportTaskProgress - app/service/systemMethods/storage/management.js (1) - replenishmentDemand - app/service/systemMethods/storage/receiving.js (29) @@ -512,8 +512,8 @@ rg "class .*Service|module.exports" app/service/qimenMethods - list, detail, create, update, delete - app/service/systems/comboGoods.js (15) - fetchStockInfoMap, buildSimpleNotation, buildNameNotation, validateItems, getTargetStoreIdFromMap, checkCustomCodeUniqueForCreate, checkCustomCodeUniqueForUpdate, list, buildListWhere, create, update, delete, search, searchByIdOrCode, enrichComboList -- app/service/systems/delivery_order.js (54) - - getStoreSubjectConfigCacheKey, normalizeStoreSubjectConfig, getStoreSubjectConfig, findCodeOption, getOptionName, appendOrderOperationLog, getOrderLogOperator, getOrderLogWarehouseId, flushOrderOperationLogs, findPlatformOptionByCode, getPlatformSnapshotCode, getPlatformSnapshotName, resolvePlatformSnapshot, resolveExpressCodeFromSetting, resolveExpressSettingSnapshot, resolveEnableExternalExpressCode, resolveExpressSnapshot, addOrder, buildOrderStats, isRetryableLockError, isPrimaryKeyDuplicate, formatOrderCreateError, resolveOrderStep, generateItemsHash, calculateCRC32, normalizeOrderFromKey, resolveOperatorName, prepareOrderData, addOrderLines, buildOrderItemSnapshot, safeParseFloat, withPatchedCtxUser, buildAsyncProcessContext, buildExpressAllocateRequest, enqueueAutoWaybillAllocation, buildStorageAllocateRequest, getStoreWarehousePolicyConfig, normalizePolicyFlag, resolveCutoffOrderConfig, isPastCutoffTime, Date, isAllocationWindowClosed, buildAutoGroupingStructure, findAutoGroupingWaveId, appendOrderToWave, countCandidateGroupOrders, createGroupingWave, markWaveAutoGrouping, finishAutoGroupingIfNeeded, runAutoGrouping, runAsyncProcessStep, findAutoExpressExcludedRemark, appendAutoExpressSkipLog, asyncProcessOrderCreated +- app/service/systems/delivery_order.js (56) + - getStoreSubjectConfigCacheKey, normalizeStoreSubjectConfig, getStoreSubjectConfig, findCodeOption, getOptionName, appendOrderOperationLog, getOrderLogOperator, getOrderLogWarehouseId, flushOrderOperationLogs, findPlatformOptionByCode, getPlatformSnapshotCode, getPlatformSnapshotName, resolvePlatformSnapshot, resolveExpressCodeFromSetting, resolveExpressSettingSnapshot, resolveEnableExternalExpressCode, resolveExpressSnapshot, normalizeNeedOmsWaybill, addOrder, buildOrderStats, isRetryableLockError, isPrimaryKeyDuplicate, formatOrderCreateError, resolveOrderStep, generateItemsHash, calculateCRC32, normalizeOrderFromKey, resolveOperatorName, prepareOrderData, addOrderLines, buildOrderItemSnapshot, safeParseFloat, withPatchedCtxUser, buildAsyncProcessContext, buildExpressAllocateRequest, enqueueAutoWaybillAllocation, buildStorageAllocateRequest, getStoreWarehousePolicyConfig, normalizePolicyFlag, resolveCutoffOrderConfig, isPastCutoffTime, Date, isAllocationWindowClosed, buildAutoGroupingStructure, findAutoGroupingWaveId, appendOrderToWave, countCandidateGroupOrders, createGroupingWave, markWaveAutoGrouping, finishAutoGroupingIfNeeded, runAutoGrouping, runAsyncProcessStep, findAutoExpressExcludedRemark, appendAutoExpressSkipLog, appendNeedOmsWaybillWaitLog, asyncProcessOrderCreated - app/service/systems/entry_order.js (16) - addOrder, getLineCount, received, success, fail, findByOrderCode, findByStatus, getStatsByWarehouse, updateSyncStatus, updateOrderStatus, calculateReceivedQuantities, batchUpdateReceived, getOrderProgress, tryCreateEntryOrder, addItems, reviewEntry - app/service/systems/excel.js (26) @@ -528,8 +528,8 @@ rg "class .*Service|module.exports" app/service/qimenMethods - buildTree, getTreeByType, buildSubTree, getWithChildrenByType, getAllChildren, getByType, getGroups, getChildrenByPid, getTreeChildrenByPid, create, update, findById, delete - app/service/systems/file.js (2) - getImages, ReferenceFile -- app/service/systems/inbound_direct_log.js (14) - - getItems, _addSingleItem, _bindReceivingDetail, addItem, removeItem, commit, notifyEntryOrderCompleted, _queryCompletedEntryItems, _buildCompletedItemLines, _sendOpenApiCallback, operationLog, qimenEntrySync, _syncReceivingStorageStatus, _applyReceivingStockOccupancy +- app/service/systems/inbound_direct_log.js (15) + - getItems, _addSingleItem, _bindReceivingDetail, addItem, removeItem, commit, notifyEntryOrderCompleted, _queryCompletedEntryItems, _buildCompletedItemLines, buildEntryOrderConfirmRequest, _sendOpenApiCallback, operationLog, qimenEntrySync, _syncReceivingStorageStatus, _applyReceivingStockOccupancy - app/service/systems/inbox/group.js (10) - list, quickList, members, disable, update, reset, validateExpressInterfaces, validateSystemExpressCode, findGroupsByExpress, findStoreAfterSalesGroups - app/service/systems/intercept_auto_confirm.js (10) @@ -550,8 +550,8 @@ rg "class .*Service|module.exports" app/service/qimenMethods - getDriver, normalizeMessageType, toObject, normalizeEventList, matchesEvents, buildTraceId, getRegisteredEventCodes, isValidEventCode, assertEventRegistered, getRetryDelays, sleep, isSuccessfulResponse, getFailureMessage, persistFailureLog, sendWithRetry, getStoreInfoCacheKey, resolveStoreInfo, resolveSubjectConfig, normalizePayload, buildOutgoingPayload, getWebhookLimit, findMatchedWebhooks, getFixedGroupTargets, findSubscribedGroups, resolveStoreLabelInternal, sendToWarehouseChannel, send, sendViaWebhooks - app/service/systems/operation_log.js (14) - buildOperationLogData, buildBusinessLogWhere, formatOperationLogRows, createOperationLog, createOperationLogs, queryLogsByBusinessType, queryStockLogs, queryOrderLogs, queryAllOrderLogs, queryAllLogsByBusinessType, queryReceivingLogs, queryEntryOrderLogs, queryStockoutLogs, getMessageDetail -- app/service/systems/order_async.js (6) - - finalizeSuccessfulQimenSync, syncQmOrders, syncManualOrders, flushDeferredOrderSyncNotices, syncApiOrders, syncStockoutOrders +- app/service/systems/order_async.js (9) + - finalizeSuccessfulQimenSync, syncQmOrders, syncManualOrders, flushDeferredOrderSyncNotices, syncApiOrders, syncStockoutOrders, buildStockoutConfirmRequest, notifyStockoutExternal, resolveOpenApiAppByStore - app/service/systems/order_auto_outbound.js (7) - getEnabledAutoOutboundWarehouses, normalizeSubjectConfigForAutoOutbound, buildAutoOutboundWhere, findAutoOutboundOrders, findOrderIdsWithWeigh, processWarehouseAutoOutbound, executeAutoOutbound - app/service/systems/order_delivery_migration.js (15) @@ -592,8 +592,8 @@ rg "class .*Service|module.exports" app/service/qimenMethods - notifyRefreshInfo, list, update, setRecording, cancelRecording, delete - app/service/systems/qimen_query.js (3) - qimenClient, send, sendRequest -- app/service/systems/receiving_entry_match.js (27) - - matchAfterEntryCompleted, _bindEntryOrderReceiving, bindEntryOrderReceiving, _bindReceivingsWithStorageSync, _bindOneReceivingAndSyncStorage, max, _syncReceivingStorageByEntryItems, _parseLedgerMap, _serializeLedgerMap, min, _buildLegacyBaselineLedger, _bindingAllocationByStock, _recalcReceivingStorageStatus, _reconcileEntryReceivedQuantity, recordLedgerAllocation, setLedgerAllocation, rollbackEntryOrderBindings, _rollbackOneBindingStorage, _getRecentReceivingOrders, _findReceivingByRemark, _compareDetails, _sendCallback, _sendQimenCallback, _sendOpenApiCallback, _markReceivingPartialStorage, _commitBinding, unbindEntryOrderReceiving +- app/service/systems/receiving_entry_match.js (29) + - matchAfterEntryCompleted, _bindEntryOrderReceiving, bindEntryOrderReceiving, _bindReceivingsWithStorageSync, _bindOneReceivingAndSyncStorage, max, _syncReceivingStorageByEntryItems, _parseLedgerMap, _serializeLedgerMap, min, _buildLegacyBaselineLedger, _bindingAllocationByStock, _recalcReceivingStorageStatus, _reconcileEntryReceivedQuantity, recordLedgerAllocation, setLedgerAllocation, rollbackEntryOrderBindings, _rollbackOneBindingStorage, _getRecentReceivingOrders, _findReceivingByRemark, _compareDetails, _queryEntryOrderLines, buildEntryOrderConfirmRequest, _sendCallback, _sendQimenCallback, _sendOpenApiCallback, _markReceivingPartialStorage, _commitBinding, unbindEntryOrderReceiving - app/service/systems/report.js (17) - getDefinition, parseFieldsField, definitionToView, resolveTypeEntry, resolveQuerier, listRegisteredTypes, validateTypeFields, resolveOrderedFields, Date, buildFilename, buildWorkbookSheets, generate, generateBuffer, saveDefinition, findDefinitionById, listDefinitions, deleteDefinition - app/service/systems/report/queries/index.js (0) @@ -606,8 +606,8 @@ rg "class .*Service|module.exports" app/service/qimenMethods - normalizeScheduleTimes, parseJsonArray, readJsonArray, readJsonObject, normalizeNotifyTemplate, normalizePlanName, normalizeNotifyGroupIds, normalizeNotifyMemberIds, validateNotifyGroupExists, savePlan, copyPlan, planToView, listPlans, listLogs, hitTimePoints, bizDateOfTrigger, bizDateOfTimePoint, resolveStoreWarehouse, markDelivered, markFailed, markExporting, buildMessageContent, resolveNotifyGroups, Date, deliverByChannel, sendNotifyIfConfigured, processOne, parseScheduleTimes, dispatch - app/service/systems/return_received.js (18) - createBusinessError, create, notifyPending, _handleInterceptAfterSale, _updateOrderInterceptStatus, list, exportList, _generateExportExcel, detail, delete, _findByIdChecked, _enrichReturn, _resolveStoreRemark, _resolveStoreRemarkMap, _buildListWhere, _resolveConditionValue, _extractConditionValue, _buildListOrder -- app/service/systems/return_unpack.js (43) - - _getRecordingComputerId, _buildVideoUrl, createBusinessError, create, addDetail, updateDetail, removeDetail, cancel, _resolveSubmitEndTime, submit, _notifyUnpacked, forceRecord, list, detailList, videoList, exportUnpack, _resolveStoreNameMap, _resolveExpressNameMap, _extractDetailColor, detail, _buildWaybillMatch, _findWaybillFlexible, queryByWaybill, _resolveWarehouseName, _resolveStoreIdByWaybill, _resolveReturnOrderInfo, delete, _findByIdChecked, _assertUnpacking, _findDetailChecked, _recalcMain, _enrichRow, _flattenVideos, _enrichDetailsWithStock, _resolveStoreRemark, VALUES, _generateUnpackNo, _buildListWhere, _buildDetailListWhere, _buildVideoListWhere, _buildVideoListOrder, _resolveConditionValue, _buildListOrder +- app/service/systems/return_unpack.js (50) + - _getRecordingComputerId, _buildVideoUrl, createBusinessError, create, transferByWaybills, addDetail, updateDetail, removeDetail, cancel, _resolveSubmitEndTime, submit, _notifyUnpacked, forceRecord, list, detailList, videoList, exportUnpack, _resolveStoreNameMap, _resolveExpressNameMap, _extractDetailColor, detail, _buildWaybillMatch, _findWaybillFlexible, queryByWaybill, _resolveWarehouseName, _resolveStoreIdByWaybill, _resolveReturnOrderInfo, delete, _insertMainWithRetry, _transferOneWaybill, _backfillDetailsFromOrder, _countDetails, _resolveReturnReceivedId, _buildTransferDetailRows, _findByIdChecked, _assertUnpacking, _findDetailChecked, _recalcMain, _enrichRow, _flattenVideos, _enrichDetailsWithStock, _resolveStoreRemark, VALUES, _generateUnpackNo, _buildListWhere, _buildDetailListWhere, _buildVideoListWhere, _buildVideoListOrder, _resolveConditionValue, _buildListOrder - app/service/systems/return_waybill.js (12) - createBusinessError, create, update, list, detail, delete, _findByIdChecked, _assertStoreContract, _formatRow, _buildListWhere, _resolveConditionValue, _buildListOrder - app/service/systems/setting/account.js (31) @@ -644,16 +644,16 @@ rg "class .*Service|module.exports" app/service/qimenMethods - normalizeInboundOrderId, isOrderOutboundTransaction, resolveOutboundOrderReference, create, list, _buildStorageTransactionWhere, _resolveKeywordToStockIds, queryList, exportList, exportStorageList - app/service/systems/stock_warehouse.js (3) - _buildStockDetailCacheKey, getStockDetails, invalidateStockDetailCache -- app/service/systems/stockout_order.js (3) - - resolveStockoutExpress, create, query -- app/service/systems/storage/entry.js (25) - - normalizeExpenseRecordValue, normalizeExpenseRecordCondition, normalizeFilterValues, buildEntryStockTransactionExistsCondition, buildHasReceivingCondition, preprocessEntryListWhere, list, get, IN, enrichItemsWithAvailableReceivingDetails, normalizeCancelEntryOrderIds, getOwnedEntryOrderById, cancel, _rollbackReceivingStorageStatus, addItem, commit, removeItem, getReceivingDetailsForBind, containerList, _applyReceivingInboundUsage, quickInbound, receivingCompare, _buildMergedComparison, exportEntryOrders, exportStoreEntryOrders +- app/service/systems/stockout_order.js (5) + - resolveStockoutExpress, create, query, cancel, _writeStockoutOperationLog +- app/service/systems/storage/entry.js (27) + - normalizeExpenseRecordValue, normalizeExpenseRecordCondition, normalizeFilterValues, buildEntryStockTransactionExistsCondition, buildHasReceivingCondition, preprocessEntryListWhere, list, get, IN, enrichItemsWithAvailableReceivingDetails, normalizeCancelEntryOrderIds, getOwnedEntryOrderById, cancel, _guardCancelEntryOrder, _doCancelEntryOrder, _rollbackReceivingStorageStatus, addItem, commit, removeItem, getReceivingDetailsForBind, containerList, _applyReceivingInboundUsage, quickInbound, receivingCompare, _buildMergedComparison, exportEntryOrders, exportStoreEntryOrders - app/service/systems/storage/expiry.js (1) - list - app/service/systems/storage/index.js (15) - findByStockAndBatch, findBySpace, findAvailableByWarehouse, findExpiringSoon, updateQuantity, lockQuantity, unlockQuantity, allocateQuantity, interceptLockQuantity, interceptReceiveQuantity, interceptUnlockQuantity, min, offsetGapOnInbound, getStockSummary, getSpaceUsage -- app/service/systems/storage/inventory.js (15) - - createTransferStockTransactions, transferLocation, transferByProduct, resolveStockQueryToStockIds, getInventoryList, getStorageListByStockId, getStorageListBySpaceId, _aggregateStorageRowsByStock, _aggregateStorageRowsBySpace, _loadInventoryWarningRanges, _formatBatchStorageRows, quickPutaway, directPutaway, exportInventoryList, _generateEntryOrderCode +- app/service/systems/storage/inventory.js (16) + - createTransferStockTransactions, transferLocation, transferByProduct, updateExpiry, resolveStockQueryToStockIds, getInventoryList, getStorageListByStockId, getStorageListBySpaceId, _aggregateStorageRowsByStock, _aggregateStorageRowsBySpace, _loadInventoryWarningRanges, _formatBatchStorageRows, quickPutaway, directPutaway, exportInventoryList, _generateEntryOrderCode - app/service/systems/storage/management.js (1) - replenishmentDemand - app/service/systems/storage/receiving.js (44) @@ -676,12 +676,12 @@ rg "class .*Service|module.exports" app/service/qimenMethods - _getRecordingComputer, _isComputerOnline, _resetVideoRecords, _withinReuseWindow, _markFailed, requestPackVideo, requestUnpackVideo, requestFor, syncByVideos, settleStatuses, notifyResults, queryPackVideo, _buildResultMessage, _notifyManualHandling, _replyResult - app/service/systems/warehouseNotify.js (7) - truncateLogBody, getCallbackConfig, MD5, buildSignature, writeLog, push, pushSystemMessage -- app/service/systems/wave_batch_closure.js (1) - - closeFinishedWaves +- app/service/systems/wave_batch_closure.js (4) + - closeFinishedWaves, normalizeConfirmIntervalMs, readEmptyConfirmState, writeEmptyConfirmState - app/service/systems/waybill.js (5) - toOrder, list, detail, export, buildWaybillExportFile -- app/service/systems/workbench.js (61) - - list, detail, create, update, delete, bindCamera, business, _countWaveOrders, _countWaveOrdersCached, SUM, _sumWaveItemsTotal, _sumWaveItemsTotalCached, _getWaveOrderIds, Set, _buildPackChangeSummary, _writePackOperationLog, _updateOrderPackStatus, _packOrder, resolvePackTaskEndTime, _finishPack, _sendWeight, _writeWeighOpLog, _queryOrder, getWorkbenchBindClientCacheKey, getWorkbenchBindCodeCacheKey, getWorkbenchTokenCacheKey, generateRandomChars, generateWorkbenchToken, generateWorkbenchLoginCode, normalizeWorkbenchBindCode, generateUniqueWorkbenchLoginCode, createUniqueWorkbenchClientCode, createUniqueWorkbenchBindCode, buildWorkbenchBindState, getWorkbenchBindRemainingSeconds, setWorkbenchBindState, createWorkbenchBindSession, refreshWorkbenchBindCode, formatWorkbenchBindData, waitForWorkbenchBindComplete, getWorkbenchBindCode, formatWorkbenchTokenInfo, listWorkbenchMembers, listCurrentPackTasks, buildCurrentPackingInfo, invalidateWorkbenchTokenCacheByWorkbenchId, buildWorkbenchTokenInfo, bindWorkbench, getWorkbenchInfoByToken, loginWorkbenchByCode, resetLoginCode, clearExpiredWorkbenchTokens, resolveWorkbenchContext, resolveWorkbenchByToken, packOrderByToken, finishPackByToken, sendWeightByToken, queryOrderByToken, normalizeWorkbenchMemberIds, removeWorkbenchMember, bindWorkbenchMember +- app/service/systems/workbench.js (62) + - list, detail, create, update, delete, bindCamera, business, _countWaveOrders, _countWaveOrdersCached, SUM, _sumWaveItemsTotal, _sumWaveItemsTotalCached, _getWaveOrderIds, Set, _buildPackChangeSummary, _writePackOperationLog, _updateOrderPackStatus, _packOrder, resolvePackTaskEndTime, _finishPack, _resetPackOsd, _sendWeight, _writeWeighOpLog, _queryOrder, getWorkbenchBindClientCacheKey, getWorkbenchBindCodeCacheKey, getWorkbenchTokenCacheKey, generateRandomChars, generateWorkbenchToken, generateWorkbenchLoginCode, normalizeWorkbenchBindCode, generateUniqueWorkbenchLoginCode, createUniqueWorkbenchClientCode, createUniqueWorkbenchBindCode, buildWorkbenchBindState, getWorkbenchBindRemainingSeconds, setWorkbenchBindState, createWorkbenchBindSession, refreshWorkbenchBindCode, formatWorkbenchBindData, waitForWorkbenchBindComplete, getWorkbenchBindCode, formatWorkbenchTokenInfo, listWorkbenchMembers, listCurrentPackTasks, buildCurrentPackingInfo, invalidateWorkbenchTokenCacheByWorkbenchId, buildWorkbenchTokenInfo, bindWorkbench, getWorkbenchInfoByToken, loginWorkbenchByCode, resetLoginCode, clearExpiredWorkbenchTokens, resolveWorkbenchContext, resolveWorkbenchByToken, packOrderByToken, finishPackByToken, sendWeightByToken, queryOrderByToken, normalizeWorkbenchMemberIds, removeWorkbenchMember, bindWorkbenchMember - app/service/warehouse.js (7) - resolveWarehouseMethod, getWarehouseMethodService, dispatchWarehouseMethod, validateWarehouseParams, parseJsonBody, normalizeSignFields, processRequest - app/service/warehouseMethods/inbox.js (2) @@ -714,6 +714,8 @@ rg "class .*Service|module.exports" app/service/qimenMethods + + diff --git a/methods/changes/system.json b/methods/changes/system.json index 4096b0c..5e8bf7c 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -1,4 +1,116 @@ [ + { + "version": "2026.09.15-returnUnpack.transferByWaybills-ids", + "date": "2026-09-15", + "type": "updated", + "summary": "returnUnpack.transferByWaybills 入参口径变更:waybill_codes(运单号字符串/数组)改为 ids(运单表主键 wms_order_express.id,单个数值或数组,Number() 归一化 + 过滤非正整数 + 去重,单次上限 200)。系统层改为按 id IN (ids) + warehouse_id 一次批量反查运单,未命中即不存在或非本仓库,记失败「运单不存在」。失败项新增 waybill_id,waybill_code 仅运单命中时有值(否则为 null)。错误码新增 400「运单号为空,无法转入退件登记」与 500「反查运单失败,请稍后重试」。业务规则不变(统一置 is_back='Y'、子单跳过、明细按订单原本明细 1:1 复制、幂等复用非 cancelled 拆包单)。", + "methods": [ + "returnUnpack.transferByWaybills" + ], + "notes": [ + "本次为入参变更;同日已存在 change 记录 2026.09.15-returnUnpack.transferByWaybills(type=added,接口首次登记,尚未发布/未提交)。script/update-api-doc.cjs 的变更记录结构仅支持新记录插入数组头部、不支持对既有记录原位追加,故本次按兜底方案新增 version 带 -ids 后缀的独立记录(summary 已说明是入参变更)", + "代码依据:app/service/systems/return_unpack.js#transferByWaybills({ ids })(Number() 归一化 → 过滤非正整数 → 去重 → 上限 200 → id IN (ids)+warehouse_id 批量反查;failed[] 元素为 { waybill_id, waybill_code: 命中时有值否则 null, reason });app/service/systemMethods/returnUnpack.js#transferByWaybills(data) 取 data.ids 后透传,方法层包装不变", + "错误码变化:新增 400「运单号为空,无法转入退件登记」、500「反查运单失败,请稍后重试」;400「waybill_codes 不能为空」改为「ids 不能为空」;其余 400/404/401/403/500 口径不变", + "响应结构变化:failed[] 元素由 { waybill_code, reason } 调整为 { waybill_id, waybill_code, reason };success[] 元素由 { waybill_code, unpack_id, unpack_no, reused, detail_count, total_quantity } 调整为含 waybill_id 的 7 字段", + "回归:代码已先行修改并跑通 76/76 回归,本次仅同步文档;AI_METHOD_ROUTING.md 方法名与数量不变,无需同步", + "文档版本 0.3.124 -> 0.3.125,updatedAt 2026-09-15;写入通过 script/update-api-doc.cjs(先 --dry-run 校验)" + ] + }, + { + "version": "2026.09.15-order-list-default-where-fix", + "date": "2026-09-15", + "type": "updated", + "summary": "修正 order.pendingOrder.list / order.outboundOrder.list 的默认筛选说明,使其与 app/service/systemMethods/order/base.js#MODULE_CONFIGS 实现一致(前者 step in [1,2,3];后者 outbound_status in [fin,padding] 且 step in [4,9])。", + "methods": [ + "order.pendingOrder.list", + "order.outboundOrder.list" + ], + "notes": [ + "实现口径:base.js MODULE_CONFIGS.pendingOrder.defaultWhere = { outbound_status: { operator: \"ne\", value: \"padding\" }, step: { operator: \"in\", value: [1,2,3] } };outboundOrder.defaultWhere = { outbound_status: { operator: \"in\", value: [\"fin\",\"padding\"] }, step: { operator: \"in\", value: [4,9] } };两者 list 均直接 this.listByModule(module, data),无额外覆盖", + "原描述偏差:pendingOrder 写 step in [1,2](漏 3);outboundOrder 写 outbound_status in [none,padding] 且 step in [1,2](正确为 outbound_status in [fin,padding] 且 step in [4,9])", + "旁证:run/check-order-list-create-channel.cjs 的期望值按 MODULE_CONFIGS 语义独立构造(pendingOrder step in [1,2,3];outboundOrder outbound_status in [fin,padding] + step in [4,9]),45/45 通过", + "文档版本 0.3.123 -> 0.3.124,updatedAt 2026-09-15;通过 script/update-api-doc.cjs 写入(先 --dry-run),按分组拆 spec(首个带 change,其余 --doc-only)" + ] + }, + { + "version": "2026.09.15-order-list-create-channel-filter", + "date": "2026-09-15", + "type": "updated", + "summary": "订单工作台各订单列表接口(order.list、order.reviewOrder.list、order.pendingOrder.list、order.outboundOrder.list、order.expectionOrder.list、order.entrustOrder.list、order.deliveryOrder.list、order.deliveryExpectionOrder.list、order.archiveOrder.list)的 where 参数补充 create_channel 订单来源渠道查询条件说明与枚举(MANUAL=手工单、API=接口、QM=奇门、STOCKOUT=出库转单),并给出裸值/裸数组/标准 operator 结构写法。", + "methods": [ + "order.list", + "order.reviewOrder.list", + "order.pendingOrder.list", + "order.outboundOrder.list", + "order.expectionOrder.list", + "order.entrustOrder.list", + "order.deliveryOrder.list", + "order.deliveryExpectionOrder.list", + "order.archiveOrder.list" + ], + "notes": [ + "口径来源:9 个列表均走 app/service/systemMethods/order/base.js#listByModule -> buildWhere -> lib/query_condition_parser.js(where 无字段白名单,字段直接透传为订单分表条件),故 create_channel 可作精确/多选/排除筛选", + "枚举来源:app/service/systemMethods/order/base.js CREATE_CHANNEL_LABELS(MANUAL 手工单 / API 接口 / QM 奇门 / STOCKOUT 出库转单)、app/service/systems/order_async.js CREATE_CHANNEL_* 常量;列定义见 database/migrations/20260813140000-add-order-delivery-base-table-missing-columns.js(create_channel STRING(20),默认 MANUAL)", + "响应口径:base.js#normalizeOrderListItem 会把 create_channel 通过 formatCreateChannelLabel 转成中文标签,故文档中明确「查询传英文枚举、响应回中文标签」", + "已核实列存在性(本地库 information_schema):wms_order_delivery_{100000,1000028} 及 _dispatch/_history/_outsourced 分表均含 create_channel 列;本地数据取值分布仅 MANUAL(73715)/QM(1082)/API(18)/STOCKOUT(2)", + "不支持的订单类列表(未纳入本次说明):order.recheckOrder.recheckOrderList / queryRecheckOrderSingleList(手写 SQL,仅 keyword/wave_no/recheck_status/pick_status/wave_index/stock_query)、order.packing.list(仅 status/pack_mode/waybill_code/wave_no 等)、order.wave.batchList(wave.js#buildBatchListWhereClause 字段白名单不含 create_channel)", + "文档版本 0.3.122 -> 0.3.123,updatedAt 2026-09-15;写入走 script/update-api-doc.cjs(先 --dry-run),首个 spec 带 change,其余 --doc-only" + ] + }, + { + "version": "2026.09.15-returnUnpack.transferByWaybills", + "date": "2026-09-15", + "type": "added", + "summary": "新增退回拆包接口 returnUnpack.transferByWaybills(运单批量转入退件登记):waybill_codes 单个字符串或数组批量转入(trim+去重+过滤空值,上限 200),逐单处理、单条失败不阻断;命中运单统一置 wms_order_express.is_back='Y';子单(business_key>1)跳过;幂等复用同仓库同运单号有效拆包单(reused=true,复用单明细为空按订单明细补写);明细按运单关联订单原明细 1:1 复制(items JSON 优先回退明细分表,复用 afterSale._resolveOrderDetail);命中退回收到登记回填 return_received_id;新增权限 568(API:运单批量转入退件登记,授权角色 27/26)。", + "methods": [ + "returnUnpack.transferByWaybills" + ], + "notes": [ + "方法层:app/service/systemMethods/returnUnpack.js 新增 transferByWaybills(data)(位于 create 之后),统一 this.success('ok', data) 包装,未加入 _noNeedRight/_noNeedLogin/_noNeedLog/_noNeedAuth 免检清单(isNeedAuth=true、isNeedLogin=true)", + "系统层:app/service/systems/return_unpack.js 新增 transferByWaybills / _insertMainWithRetry / _transferOneWaybill / _backfillDetailsFromOrder / _countDetails / _resolveReturnReceivedId / _buildTransferDetailRows(共 7 个方法)", + "权限:database/migrations/20260915100000-add-return-unpack-transfer-waybills-permission.js 固定 ID 568 path=returnUnpack.transferByWaybills meta_title=API:运单批量转入退件登记,角色授权 27(仓库组-员工)→ 26(仓库组-主管),INSERT IGNORE + 权限数组追加去重排序幂等", + "响应错误码:400 参数/上下文/子单跳过/无明细可复制、404 运单不存在、401/403 与其它接口一致、500 服务器内部错误;单运单失败进入 failed[] 不抛错", + "AI_METHOD_ROUTING.md 同步:systemMethods/returnUnpack.js 20→21(新增 transferByWaybills)、systems/return_unpack.js 43→50(新增 7 个方法);docs/*.md 无退回拆包接口清单,无需同步", + "文档版本 0.3.121 -> 0.3.122,updatedAt 2026-09-15;写入通过 script/update-api-doc.cjs(先 --dry-run 校验)" + ], + "module": "returnUnpack" + }, + { + "version": "2026.09.15-storage-inventory-update-expiry", + "date": "2026-09-15", + "type": "added", + "summary": "新增 storage.inventory.updateExpiry 接口:传入 storage_id 与 production_date / expiry_date,维护当前库存批次的生产日期与到期日期;两个日期至少传一个,未传字段保持原值,传 null/空串清空,合并后生产日期不得晚于到期日期。", + "methods": [ + "storage.inventory.updateExpiry" + ], + "notes": [ + "app/service/systems/storage/inventory.js 新增 updateExpiry(data):校验 storage_id 为正整数、两个日期格式合法且至少传一个、当前仓库上下文(ctx.user.store_id);单事务 + 行锁(SELECT ... FOR UPDATE)按 id + warehouse_id + is_enabled=1 + delete_at IS NULL 定位库存记录,跨仓库按 404 处理", + "app/service/systems/storage/inventory.js 新增模块级 helper parseStorageDateInput:undefined=未传(provided=false)、null/空串=清空、YYYY-MM-DD / YYYY/MM/DD / YYYY-MM-DD HH:mm:ss / ISO / Date 统一规范化为 YYYY-MM-DD(并校验真实存在日期,如 2026-02-30 判非法)、其它非法", + "业务校验:合并后(未传字段取库内现值)生产日期不能晚于到期日期,违反返回 400「生产日期(x)不能晚于到期日期(y)」;两值均与库内一致时返回 changed=false,不写库、不记日志", + "成功路径写业务操作日志(operationLog.createOperationLog,失败仅告警不影响主流程):business_type=storage、operation_code=STORAGE_UPDATE_EXPIRY、before_changes 含维护前两个日期与 storage/space/stock/batch 快照、message 为「生产日期 A → B;到期日期 C → D」摘要", + "app/dict/businessDict.js OPERATION_CODE 新增 STORAGE_UPDATE_EXPIRY: '维护库存效期'", + "app/service/systemMethods/storage/inventory.js 新增 updateExpiry 包装方法(this.success('ok', result) 透传 code/message/data),未加入 _noNeedRight/_noNeedAuth 豁免列表:该接口为写操作,需要 API 权限与仓库有效期校验", + "权限联动:wms_permission 需新增 path=storage.inventory.updateExpiry 的接口权限并授予相关角色(校验逻辑 app/service/main.js checkApiPermission,路径比较不区分大小写);permissions='*' 的角色无需授权", + "响应错误码:400 参数/业务校验失败、404 库存记录不存在或无权访问、409 库存记录被锁定请稍后重试(Lock wait timeout)", + "验证:ESLint(npx eslint app/service/systems/storage/inventory.js app/service/systemMethods/storage/inventory.js app/dict/businessDict.js)0 error;parseStorageDateInput 通过临时脚本 temp/verify-update-expiry-date-parse.cjs 逐用例验证(未传/空/清空/多格式/非法日期/Date 对象);未执行任何部署/回退脚本,未改动数据库与 Redis 数据" + ], + "module": "storage.inventory" + }, + { + "version": "2026.09.15-workbench-pack-osd-reset", + "date": "2026-09-15", + "type": "updated", + "summary": "打包任务结束统一复位工作台摄像头 OSD 为「无任务」:覆盖三条结束路径 —— workbench.finishPack 手动结束、workbench.packOrder 关闭上一个未结束任务(先复位再串行下发新任务 OSD,避免复位覆盖新文字)、packTaskAutoFinish 定时任务自动结束;统一调用 workbench._resetPackOsd 回写 Redis osd_{workbenchId}=无任务 并逐台摄像头下发「无任务」,异常仅告警不阻塞打包主流程。", + "methods": [ + "workbench.packOrder", + "workbench.finishPack" + ], + "notes": [ + "代码:app/service/systems/workbench.js 新增 OSD_IDLE_TEXT/OSD_CACHE_KEY_PREFIX/OSD_CACHE_TTL_SECONDS 常量与 _resetPackOsd;_finishPack、_packOrder 步骤4/7.5 接入", + "代码:app/service/systems/pack_task_auto_finish.js 扫描补 workbench_id,自动结束后调用 _resetPackOsd;app/schedule/auto_finish_pack_task.js 注释同步", + "回归测试:test/workbench_reset_pack_osd.test.cjs(8 用例,mock ctx)全部通过" + ] + }, { "version": "2026.09.13-stockout-waybill-codes-single-deprecate", "date": "2026-09-13", @@ -53,6 +165,20 @@ "后续代码侧待办(未在本次实施):updateExpress 增加 express_codes 兼容映射或对未识别参数报错、补 warehouse_id 归属校验;confirm 成功响应 expressCode/expressCodes 收敛为 waybill_code/waybill_codes。" ] }, + { + "version": "2026.09.13-pendingOrder-syncOrderIds-api-confirm-before-deduct", + "date": "2026-09-13", + "type": "updated", + "summary": "order.pendingOrder.syncOrderIds 描述同步 API 渠道同步顺序变更(代码已先行落地):API 渠道订单改为逐单「先回传 deliveryorder.confirm、回调成功才扣减库存并置 sync_status='fin'」,回调失败/异常置 sync_status='error' + 待处理异常、不扣减库存、可重新派发;单订单失败统一「写入错误状态 + 标记待处理异常」。QM/MANUAL 口径不变。文档版本 0.3.115 → 0.3.116。", + "methods": [ + "order.pendingOrder.syncOrderIds" + ], + "notes": [ + "代码依据:app/service/systems/order_async.js#finalizeLocalChannelOrdersInternal → processApiOrderInternal(回调成功才 processLocalChannelOrderInternal 扣减并置 fin)、markApiSyncFailedInternal(error + markPendingException)", + "params / response / errors 未变,仅 description 同步语义", + "本次仅同步文档,未修改任何业务代码;写入通过 script/update-api-doc.cjs(先 --dry-run 校验)" + ] + }, { "version": "2026.09.12-storage-entry-cancel-entryOrderCode-doc", "date": "2026-09-12", diff --git a/methods/system.json b/methods/system.json index 5f69f96..74f59d8 100644 --- a/methods/system.json +++ b/methods/system.json @@ -1,8 +1,8 @@ { "module": "system", "description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内", - "version": "0.3.115", - "updatedAt": "2026-09-12", + "version": "0.3.125", + "updatedAt": "2026-09-15", "headers": [ { "name": "platform", @@ -2009,7 +2009,7 @@ "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} 筛选未分配波次订单)。" + "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", @@ -2902,7 +2902,7 @@ "type": "object", "required": false, "source": "body", - "description": "统一 where 条件对象;禁止传入 warehouse_id / warehouseId。" + "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", @@ -3169,7 +3169,7 @@ "list": [ { "method": "order.pendingOrder.list", - "description": "待处理订单列表,默认筛选 outbound_status != padding 且 step in [1,2]。;列表运单号回填强制同仓校验:wms_order_express 按「订单ID + 订单所属仓库ID」隔离读取,禁止仅凭订单ID跨仓串读运单号", + "description": "待处理订单列表,默认筛选 outbound_status != padding 且 step in [1,2,3]。;列表运单号回填强制同仓校验:wms_order_express 按「订单ID + 订单所属仓库ID」隔离读取,禁止仅凭订单ID跨仓串读运单号", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -3193,7 +3193,7 @@ "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\"}}。" + "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 已格式化为中文标签(手工单/接口/奇门/出库转单),查询条件请传英文枚举值。" }, { "name": "sort", @@ -3731,7 +3731,7 @@ }, { "method": "order.pendingOrder.syncOrderIds", - "description": "同步待处理订单(异步模式)。提交后立即返回 request_id,后台异步执行同步流程。调用方需通过 syncOrderIdsProgress 接口轮询任务进度与最终结果。后台会按 create_channel 分组并行派发同步任务(QM/MANUAL/API);单订单失败静默写入错误状态,不影响整批结果;已同步完成(sync_status='fin')的订单会被自动跳过防重复。SN管理订单和快递未分配订单在同步前即被标记为 error 并跳过派发。派发成功后会更新 sync_status='fin',防止重复同步。", + "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": [ @@ -10896,7 +10896,7 @@ "list": [ { "method": "order.outboundOrder.list", - "description": "待出库订单列表,默认筛选 outbound_status in [none,padding] 且 step in [1,2]。;列表运单号回填强制同仓校验:wms_order_express 按「订单ID + 订单所属仓库ID」隔离读取,禁止仅凭订单ID跨仓串读运单号", + "description": "待出库订单列表,默认筛选 outbound_status in [fin,padding] 且 step in [4,9]。;列表运单号回填强制同仓校验:wms_order_express 按「订单ID + 订单所属仓库ID」隔离读取,禁止仅凭订单ID跨仓串读运单号", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -10920,7 +10920,7 @@ "type": "object", "required": false, "source": "body", - "description": "统一 where 条件对象;禁止传入 warehouse_id / warehouseId。" + "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", @@ -11168,7 +11168,7 @@ "type": "object", "required": false, "source": "body", - "description": "统一 where 条件对象;禁止传入 warehouse_id / warehouseId。" + "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", @@ -11353,7 +11353,7 @@ "type": "object", "required": false, "source": "body", - "description": "统一 where 条件对象;禁止传入 warehouse_id / warehouseId。" + "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", @@ -11491,7 +11491,7 @@ "type": "object", "required": false, "source": "body", - "description": "统一 where 条件对象;禁止传入 warehouse_id / warehouseId。" + "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", @@ -11886,7 +11886,7 @@ "type": "object", "required": false, "source": "body", - "description": "统一 where 条件对象;禁止传入 warehouse_id / warehouseId。" + "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", @@ -12030,7 +12030,7 @@ "type": "object", "required": false, "source": "body", - "description": "统一 where 条件对象;禁止传入 warehouse_id / warehouseId。" + "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", @@ -26328,6 +26328,163 @@ "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「无权访问该接口」" + ] } ] }, @@ -34018,7 +34175,7 @@ }, { "method": "workbench.packOrder", - "description": "工作台打包上报(免登录、免权限、免鉴权,以工作台 token 鉴权):仓库与工作台均由服务端从 token 解析注入(body 传入 warehouse_id/workbench_id 一律忽略,禁止前端传值),入参发货单号、波次号、状态、打包时间、波次总订单数、SKU 品种数、商品总件数、打包人员;按发货单号定位订单(current→dispatch 分表),同一工作台存在上一个未结束任务时先关闭(同步回写旧订单打包状态),散单按 order_id、团购按 wave_no 去重后创建打包任务(wms_pack_task,缺失/非法 status 归一化为 1=打包中),写入打包人员(wms_pack_task_packer)与 operator_text、下发 OSD 到工作台绑定摄像头、写操作日志;打包状态变更后主动失效对应工作台 token 缓存,保证 getWorkbenchInfo 尽快返回最新打包信息;团购单(isSandan=0)响应附 batch 波次信息(波次订单数为 current+dispatch 分表实时统计);拦截流程中的订单不允许打包(散单直接拒绝、团购波次静默跳过并视为完成);保留系统日志(systemInit 未声明免日志);成功返回 flag=success、code=200", + "description": "工作台打包上报(免登录、免权限、免鉴权,以工作台 token 鉴权):仓库与工作台均由服务端从 token 解析注入(body 传入 warehouse_id/workbench_id 一律忽略,禁止前端传值),入参发货单号、波次号、状态、打包时间、波次总订单数、SKU 品种数、商品总件数、打包人员;按发货单号定位订单(current→dispatch 分表),同一工作台存在上一个未结束任务时先关闭(同步回写旧订单打包状态,并将工作台绑定摄像头 OSD 复位为「无任务」,新任务 OSD 在其后串行下发避免被复位覆盖),散单按 order_id、团购按 wave_no 去重后创建打包任务(wms_pack_task,缺失/非法 status 归一化为 1=打包中),写入打包人员(wms_pack_task_packer)与 operator_text、下发 OSD 到工作台绑定摄像头(散单显示运单号、团购显示波次号+订单总量,并写 Redis osd_{workbenchId} 缓存)、写操作日志;打包状态变更后主动失效对应工作台 token 缓存,保证 getWorkbenchInfo 尽快返回最新打包信息;团购单(isSandan=0)响应附 batch 波次信息(波次订单数为 current+dispatch 分表实时统计);拦截流程中的订单不允许打包(散单直接拒绝、团购波次静默跳过并视为完成);保留系统日志(systemInit 未声明免日志);成功返回 flag=success、code=200", "isNeedAuth": false, "isNeedLogin": false, "isNeedRight": false, @@ -34191,7 +34348,7 @@ }, { "method": "workbench.finishPack", - "description": "工作台打包完成(免登录、免权限、免鉴权,以工作台 token 鉴权):仓库与工作台均由服务端从 token 解析注入(body 传入 warehouse_id/workbench_id 一律忽略,禁止前端传值);查找该工作台最后一个未结束的打包任务(status<2,按 id 倒序取最新)并结束(写 end_time、status=2,结束时间按仓库配置的散单/团购打包最大时长上限截断),同步回写关联订单打包状态(散单更新单笔、团购批量更新波次下未拦截订单)并写完成操作日志;无未结束任务时返回 finished=false(data 仅 workbench_id/finished/message);打包任务结束后主动失效对应工作台 token 缓存,保证 getWorkbenchInfo 尽快返回最新打包信息;保留系统日志(systemInit 未声明免日志);成功返回 flag=success、code=200", + "description": "工作台打包完成(免登录、免权限、免鉴权,以工作台 token 鉴权):仓库与工作台均由服务端从 token 解析注入(body 传入 warehouse_id/workbench_id 一律忽略,禁止前端传值);查找该工作台最后一个未结束的打包任务(status<2,按 id 倒序取最新)并结束(写 end_time、status=2,结束时间按仓库配置的散单/团购打包最大时长上限截断),同步回写关联订单打包状态(散单更新单笔、团购批量更新波次下未拦截订单)并写完成操作日志,随后将工作台绑定摄像头 OSD 复位为「无任务」(回写 Redis osd_{workbenchId} 缓存并逐台摄像头下发「无任务」,失败仅告警不阻塞主流程);无未结束任务时返回 finished=false(data 仅 workbench_id/finished/message);打包任务结束后主动失效对应工作台 token 缓存,保证 getWorkbenchInfo 尽快返回最新打包信息;保留系统日志(systemInit 未声明免日志);成功返回 flag=success、code=200", "isNeedAuth": false, "isNeedLogin": false, "isNeedRight": false, @@ -41681,6 +41838,110 @@ "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 为尽力而为(失败仅告警不阻断主流程)" + ] } ] },