docs(api): 同步 system 接口文档、变更记录与方法路由
- 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 等模块方法数变化)
This commit is contained in:
parent
4d8297aecb
commit
aff7a4fe22
@ -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
|
||||
|
||||
<!-- SERVICE_METHOD_INVENTORY:BEGIN -->
|
||||
自动生成时间: 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)
|
||||
- <no-class-method-found>
|
||||
- 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
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -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",
|
||||
|
||||
@ -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 为尽力而为(失败仅告警不阻断主流程)"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user