diff --git a/app/service/systemMethods/storage/stockout.js b/app/service/systemMethods/storage/stockout.js index bb18ef5..e63164a 100644 --- a/app/service/systemMethods/storage/stockout.js +++ b/app/service/systemMethods/storage/stockout.js @@ -559,9 +559,10 @@ class StorageStockoutService extends MainService { /** * 出库单确认(直出)。 * 不改变内部库存,直接按出库单明细的计划数量确认。 - * 出站同步 taobao.qimen.stockout.confirm 成功后,释放创建时占用的库存锁定(QM_STOCKOUT,写 UNLOCK 流水), - * 状态才推进到 COMPLETED。 - * 要求 express_code 已填写,否则拒绝确认。 + * 出站回传按 source_type 分流(QM→奇门 taobao.qimen.stockout.confirm, + * API→OpenAPI 回调 stockout.confirm,其他内部来源直接视为成功), + * 回传成功后释放创建时占用的库存锁定(QM_STOCKOUT,写 UNLOCK 流水),状态才推进到 COMPLETED。 + * 要求运单号已填写(以复数 waybill_codes 为准,存量单回退单数 waybill_code),否则拒绝确认。 * @param {Object} data 请求体 * @param {number} data.id 出库单ID(必填) * @return {Promise} 统一成功/失败包装响应 @@ -583,9 +584,15 @@ class StorageStockoutService extends MainService { return this.fail(`出库单当前状态(${order.order_status})不允许确认`); } - // 校验运单号是否已填写 - if (!order.waybill_code) { - return this.fail('出库单未填写运单号(waybill_code),请先更新运单号后再确认'); + // 校验运单号是否已填写:回传以复数 waybill_codes 为准(一单多运单 → 奇门 packages.package[]), + // 单数 waybill_code 已弃用,仅在复数缺失时对存量单做兼容回退。 + const confirmWaybillCodes = (Array.isArray(order.waybill_codes) && order.waybill_codes.length > 0 + ? order.waybill_codes + : [ order.waybill_code ]) + .map(code => String(code || '').trim()) + .filter(code => !!code); + if (confirmWaybillCodes.length === 0) { + return this.fail('出库单未填写运单号(waybill_codes),请先更新运单号后再确认'); } // 第一步:事务内写入明细 actual_qty(暂不改变 order_status) @@ -611,76 +618,39 @@ class StorageStockoutService extends MainService { return this.fail(`确认失败:${err.message}`); } - // 第二步:出站通知 ERP(taobao.qimen.stockout.confirm) - const { app } = this; + // 第二步:按出库单来源通知外部 + // QM → 奇门 taobao.qimen.stockout.confirm;API → OpenAPI 回调 stockout.confirm; + // WMS 等内部来源 → 无需通知外部,直接视为成功。 + // 与出库单转订单回传(orderAsync.syncStockoutOrders)共用同一分流实现,避免两处逻辑漂移。 + const orderAsyncService = ctx.service.systems && ctx.service.systems.orderAsync; let qimenSuccess = false; let qimenMessage = ''; - if (app.qimenClient && order.qimen_owner_code && order.qimen_warehouse_code) { + if (!orderAsyncService || typeof orderAsyncService.notifyStockoutExternal !== 'function') { + qimenMessage = '出库单回传服务不可用'; + ctx.logger.error('[stockout.confirm] 出库单回传服务不可用(ctx.service.systems.orderAsync 缺失)'); + } else { try { - const now = app.formatDate(new Date()); - const waybillCodes = Array.isArray(order.waybill_codes) && order.waybill_codes.length > 0 - ? order.waybill_codes - : [ order.waybill_code ].filter(Boolean); + // 直出确认没有发货单上下文,orderRow 传空对象:报文内快递信息回退出库单 express_code/express_name + // 运单号统一走复数(packages.package[].expressCode),不传 deliveryOrder.expressCode + const outboundData = orderAsyncService.buildStockoutConfirmRequest(order, {}, items, confirmWaybillCodes); - const outboundData = { - deliveryOrder: { - totalOrderLines: order.total_order_lines, - deliveryOrderCode: order.stockout_order_code, - deliveryOrderId: order.id, - warehouseCode: order.qimen_warehouse_code, - orderType: order.order_type, - status: 'DELIVERED', - outBizCode: order.stockout_order_code, - confirmType: 0, - orderConfirmTime: now, - operatorCode: '', - operatorName: '', - }, - packages: { - package: waybillCodes.map(code => ({ - logisticsCode: order.express_code || 'OTHER', - logisticsName: order.express_name || 'OTHER', - expressCode: code, - packageCode: order.stockout_order_code, - items: items.map(item => ({ - itemCode: item.item_code || '', - itemId: item.item_id || '', - quantity: item.plan_qty || 0, - })), - })), - }, - orderLines: items.map(item => ({ - orderLineNo: item.order_line_no || '', - ownerCode: item.owner_code || order.qimen_owner_code, - itemCode: item.item_code || '', - itemId: item.item_id || '', - itemName: item.item_name || '', - planQty: item.plan_qty || 0, - actualQty: item.plan_qty || 0, - inventoryType: item.inventory_type || 'ZP', - })), - }; + // API 来源需按货主合约反查回调 appKey;QM 来源由奇门 client 按货主编码发送,无需 appKey + let appKey = ''; + if (String(order.source_type || 'QM').trim().toUpperCase() === 'API') { + const resolvedApp = await orderAsyncService.resolveOpenApiAppByStore(order.store_id, order.warehouse_id); + appKey = String((resolvedApp && resolvedApp.appKey) || '').trim(); + } - const sendResult = await app.qimenClient.send( - 'taobao.qimen.stockout.confirm', - order.qimen_owner_code, - outboundData, - { ctx } - ); - - // 解析奇门响应 - const response = (sendResult && sendResult.xmlArray && sendResult.xmlArray.response) - ? (Array.isArray(sendResult.xmlArray.response) ? sendResult.xmlArray.response[0] : sendResult.xmlArray.response) - : {}; - qimenSuccess = String(response.flag || '').trim() === 'success'; - qimenMessage = qimenSuccess ? '' : `${response.code || ''} ${response.message || '未知错误'}`.trim(); + const notifyResult = await orderAsyncService.notifyStockoutExternal(order, outboundData, { appKey }); + qimenSuccess = !!(notifyResult && notifyResult.success === true); + qimenMessage = qimenSuccess + ? '' + : String((notifyResult && notifyResult.message) || '通知外部失败').trim(); } catch (outboundErr) { qimenMessage = outboundErr.message || '出站通知异常'; ctx.logger.error(`[stockout.confirm] 出站通知异常: ${qimenMessage}`); } - } else { - ctx.logger.warn(`[stockout.confirm] 跳过出站通知: qimenClient=${!!app.qimenClient}, ownerCode=${order.qimen_owner_code}, warehouseCode=${order.qimen_warehouse_code}`); } // 第三步:根据出站结果更新状态 @@ -814,13 +784,15 @@ class StorageStockoutService extends MainService { /** * 更新出库单快递和运单号。 - * 用于在确认前填写 express_code / waybill_code / waybill_codes。 + * 用于在确认前填写 express_code / waybill_codes。 + * 运单号以复数 waybill_codes 为准(一单多运单);单数 waybill_code 已弃用, + * 传入 waybill_codes 时会自动镜像为首个单号写回单数列。 * express_code 传入后自动从系统快递表解析 express_name。 * @param {Object} data 请求体 * @param {number} data.id 出库单ID(必填) * @param {string} [data.express_code] 快递公司编码(如 SF、STO),传入后自动解析 express_name - * @param {string} [data.waybill_code] 运单号 - * @param {string[]} [data.waybill_codes] 运单号列表 + * @param {string} [data.waybill_code] 运单号(单数,已弃用;仅作为 waybill_codes 首个的镜像,勿单独使用) + * @param {string[]} [data.waybill_codes] 运单号列表(复数,回传以此为准,支持一单多运单) * @return {Promise} 统一成功/失败包装响应 */ async updateExpress(data = {}) { @@ -855,6 +827,9 @@ class StorageStockoutService extends MainService { } } + // waybill_code(单数)已弃用:回传以 waybill_codes(复数)为准(一单多运单), + // 单数列仅作为复数首个的镜像保留,便于历史查询与展示; + // 传入 waybill_codes 时以复数首个覆盖单数,避免两列不一致。 if (data.waybill_code !== undefined) { updateData.waybill_code = data.waybill_code || null; } @@ -864,6 +839,9 @@ class StorageStockoutService extends MainService { return this.fail('waybill_codes 必须是数组或 null'); } updateData.waybill_codes = codes; + updateData.waybill_code = Array.isArray(codes) && codes.length > 0 + ? String(codes[0] || '').trim() || null + : null; } if (Object.keys(updateData).length <= 1) { diff --git a/app/service/systems/order_async.js b/app/service/systems/order_async.js index 418c84c..810376d 100644 --- a/app/service/systems/order_async.js +++ b/app/service/systems/order_async.js @@ -1629,7 +1629,7 @@ async function processStockoutOrderInternal(service, orderModel, orderItemsModel raw: true, }); - // 快递信息写回字段(回传成功落库):物流编码/名称 + 运单号列表 + // 快递信息写回字段(回传成功落库):物流编码/名称 + 运单号列表(复数为准,单数为镜像) const expressWriteback = { waybill_code: normalizedWaybillCodes[0] || '', waybill_codes: normalizedWaybillCodes, @@ -2768,3 +2768,42 @@ class OrderAsyncService extends MainService { } module.exports = OrderAsyncService; + + /** + * 组装出库单确认回传报文(与奇门 request 节点同层级,OpenAPI 回调复用)。 + * + * 供出库单转订单回传与出库单直出确认(storage.stockout.confirm)共用, + * 避免两处各写一份报文结构导致漂移。 + * + * @param {Object} stockoutOrder 出库单记录(模型实例或 raw 对象)。 + * @param {Object} orderRow 发货单记录(raw);直出确认无订单上下文时传空对象即可。 + * @param {Array} stockoutItems 出库单明细数组。 + * @param {Array} [waybillCodes] 运单号列表。 + * @return {Object} 出库单确认回传请求体。 + */ + buildStockoutConfirmRequest(stockoutOrder, orderRow, stockoutItems, waybillCodes = []) { + return buildStockoutConfirmDataInternal(this, stockoutOrder, orderRow, stockoutItems, waybillCodes); + } + + /** + * 按出库单 source_type 通知外部(QM→奇门,API→OpenAPI 回调,其他→无需通知直接成功)。 + * + * @param {Object} stockoutOrder 出库单记录。 + * @param {Object} requestData 出库单确认回传请求体。 + * @param {Object} [context] 上下文(API 来源需传 appKey)。 + * @return {Promise<{success: boolean, message: string}>} 通知结果。 + */ + async notifyStockoutExternal(stockoutOrder, requestData, context = {}) { + return await notifyStockoutExternalInternal(this, stockoutOrder, requestData, context); + } + + /** + * 按货主合约反查可用的 OpenAPI 应用配置(ApiApp),用于 API 来源出站回调。 + * + * @param {number|string} storeId 货主 ID。 + * @param {number|string} warehouseId 仓库 ID。 + * @return {Promise} { appKey, selfAppSecret, callbackUrl },未找到时返回 null。 + */ + async resolveOpenApiAppByStore(storeId, warehouseId) { + return await resolveOpenApiAppByStoreInternal(this, storeId, warehouseId); + } diff --git a/methods/changes/system.json b/methods/changes/system.json index daa93b9..4096b0c 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -1,4 +1,58 @@ [ + { + "version": "2026.09.13-stockout-waybill-codes-single-deprecate", + "date": "2026-09-13", + "type": "updated", + "module": "storage.stockout", + "summary": "出库单运单号口径收敛为复数:storage.stockout.confirm 的确认校验与出站回传改为以 waybill_codes 为准(对齐奇门 packages.package[] 多运单模型,不使用 deliveryOrder.expressCode),错误文案由「未填写运单号(waybill_code)」改为 (waybill_codes);storage.stockout.updateExpress 以 waybill_codes 为主,单数 waybill_code 降级为镜像字段(传复数时自动镜像首个数,传空数组/null 时同步置 NULL),仅传单数的旧调用方行为不变。存量单在复数缺失时仍回退单数,避免卡单。", + "methods": [ + "storage.stockout.confirm", + "storage.stockout.updateExpress" + ], + "notes": [ + "代码依据:app/service/systemMethods/storage/stockout.js#confirm(校验改为 waybill_codes 优先、单数回退;报文运单号复用校验结果)、#updateExpress(waybill_codes 写入时镜像 waybill_code = 首个);app/service/systems/order_async.js#syncStockoutOrders 写回注释同步为「复数为准、单数为镜像」", + "协议依据:taobao.qimen.stockout.confirm 中运单号在 packages.package[].expressCode(多包裹/多运单,每个包裹一个),deliveryOrder.expressCode 为单据级单运单号(多运单场景不使用)", + "回归测试:stockout.confirm.outbound.test.js 扩到 8 条(新增「一单多运单只填复数即可确认且回传 packages.package[] 两个包裹」「存量单仅有单数仍可确认」);新增 stockout.updateExpress.test.js 7 条(复数镜像、空数组/null 清空、复数优先覆盖单数、仅单数行为不变、非数组 400、无字段 400)", + "对外契约影响:确认失败文案变化(waybill_code → waybill_codes);updateExpress 响应仍同时返回两列(waybill_codes 为准,waybill_code 为镜像);仅传 waybill_codes 即可完成填写与确认,调用方可不再传单数", + "存量兼容:复数缺失时 confirm 回退单数、updateExpress 仅传单数行为不变,因此旧调用方无需强制同步升级", + "文档版本 0.3.118 -> 0.3.119,updatedAt 2026-09-13;写入通过 script/update-api-doc.cjs(先 --dry-run 校验)" + ] + }, + { + "version": "2026.09.13-storage-stockout-confirm-source-routing", + "date": "2026-09-13", + "type": "updated", + "module": "storage.stockout", + "summary": "修复 storage.stockout.confirm 出站回传未按出库单来源分流的问题:confirm 改为复用 systems/order_async.js#notifyStockoutExternalInternal(QM→奇门 taobao.qimen.stockout.confirm,API→OpenAPI 回调 method=stockout.confirm,WMS 等内部来源无需通知直接成功),与出库单转订单回传同一套分流口径;API 来源 appKey 按货主合约反查。修复后 API 来源出库单不再被错误发往奇门(此前被奇门以「-1 无法匹配货主」拒绝,且跳过出站同样走失败分支,导致该来源出库单无法确认);同时确认文档同步分流语义与新增失败文案。", + "methods": [ + "storage.stockout.confirm" + ], + "notes": [ + "代码依据:app/service/systemMethods/storage/stockout.js#confirm(第二步由硬编码 qimenClient.send 改为调用 ctx.service.systems.orderAsync.buildStockoutConfirmRequest / resolveOpenApiAppByStore / notifyStockoutExternal);app/service/systems/order_async.js 新增 3 个实例方法(buildStockoutConfirmRequest / notifyStockoutExternal / resolveOpenApiAppByStore)复用既有模块级实现,未改动原函数与其既有调用方", + "回归测试:test/app/service/systemMethods/storage/stockout.confirm.outbound.test.js 新增 6 条用例(API 走回调不发奇门、API 无可用 ApiApp 时不回落奇门、QM 仍走奇门且不发回调、WMS 内部来源直接完成、QM 奇门失败保持 CREATED、未填 waybill_code 前置拒绝)", + "对照验证:order_async.openapi.callback.test.js(5 failing)与 order_async.syncOrderIds.test.js(13 failing)为改动前既有失败(测试未跟上 2026-09-13 API 回传「不再静默跳过」的口径变更),已用「新增方法临时抛错后失败数不变」判定与本次改动无路径交集", + "对外契约影响:入参、成功响应结构不变;新增可能出现的失败文案「出库单回传服务不可用」与 API 来源的「缺少 appKey,无法回传出库单」;WMS 等内部来源出库单由「出站同步失败: 未发起出站通知」变为可正常确认完成", + "文档版本 0.3.117 -> 0.3.118,updatedAt 2026-09-13;写入通过 script/update-api-doc.cjs(先 --dry-run 校验)" + ] + }, + { + "version": "2026.09.13-storage-stockout-waybill-field-align", + "date": "2026-09-13", + "type": "updated", + "module": "storage.stockout", + "summary": "修正 storage.stockout.updateExpress / storage.stockout.confirm 的运单号字段口径(仅文档,未改代码):updateExpress 的入参由「express_code=运单号、express_codes=运单号列表」纠正为真实实现口径——express_code=快递公司编码(自动解析 express_name)、waybill_code=运单号、waybill_codes=运单号列表,并补齐 express_name/waybill_code/waybill_codes 响应字段与「没有需要更新的字段」错误项;confirm 的运单号校验字段由 express_code 纠正为 waybill_code,并如实描述响应 expressCode/expressCodes 的来源与历史遗留命名。", + "methods": [ + "storage.stockout.confirm", + "storage.stockout.updateExpress" + ], + "notes": [ + "代码依据:app/service/systemMethods/storage/stockout.js#updateExpress(L826 起,仅识别 express_code/waybill_code/waybill_codes,无 express_codes 分支)、#confirm(L577 校验 order.waybill_code)、app/model/order_stockout.js(express_codes 标注 @deprecated)", + "背景:2026-08-07 首次上线时 express_code/express_codes 即运单号口径;随后迁移 20260807140000 引入 waybill_code/waybill_codes 并改义 express_code 为快递公司编码,但 methods/system.json 与 confirm 错误文案未同步,导致调用方按旧文档传 express_codes 时静默失败。", + "对外契约影响:仅描述与错误文案纠偏,接口行为、参数名、HTTP 状态码均未变更;调用方需把运单号列表参数由 express_codes 改为 waybill_codes(confirm 前还需填 waybill_code)。", + "文档版本 0.3.116 -> 0.3.117,updatedAt 2026-09-13;写入通过 script/update-api-doc.cjs(先 --dry-run 校验)", + "后续代码侧待办(未在本次实施):updateExpress 增加 express_codes 兼容映射或对未识别参数报错、补 warehouse_id 归属校验;confirm 成功响应 expressCode/expressCodes 收敛为 waybill_code/waybill_codes。" + ] + }, { "version": "2026.09.12-storage-entry-cancel-entryOrderCode-doc", "date": "2026-09-12", diff --git a/methods/system.json b/methods/system.json index ba5be3f..5f69f96 100644 --- a/methods/system.json +++ b/methods/system.json @@ -24721,7 +24721,7 @@ { "method": "storage.stockout.confirm", "name": "出库单确认(直出)", - "description": "直出确认出库单:不改变内部库存,按出库单明细计划数量(plan_qty)直接确认。出站同步 taobao.qimen.stockout.confirm 成功后才将状态推进到 COMPLETED;同步失败则返回错误,order_status 不变,sync_status 标记为 FAILED。要求 express_code 已填写,否则拒绝确认。", + "description": "直出确认出库单:不改变内部库存,按出库单明细计划数量(plan_qty)直接确认。运单号以复数 waybill_codes 为准(一单多运单),回传时按奇门 packages.package[].expressCode 承载,不使用 deliveryOrder.expressCode;单数 waybill_code 已弃用,仅在复数缺失时对存量单做兼容回退。出站回传按出库单 source_type 分流:QM→奇门 taobao.qimen.stockout.confirm;API→OpenAPI 回调(method=stockout.confirm,appKey 按货主合约反查 wms_store_warehouse(auth_status=2) 与 wms_api_app(启用且 callback_url 非空));WMS 等内部来源无需通知外部、直接视为成功。回传成功后释放创建时占用的库存锁定(QM_STOCKOUT,写 UNLOCK 流水)并把状态推进到 COMPLETED;回传失败则返回错误,order_status 不变,sync_status 标记为 FAILED(可重试)。", "isNeedAuth": true, "isNeedLogin": true, "isNeedRight": false, @@ -24765,56 +24765,68 @@ "name": "logisticsName", "type": "string", "required": true, - "description": "物流公司名称(固定为 OTHER)" + "description": "物流公司名称(当前实现固定返回字符串 OTHER)" }, { "name": "expressCode", "type": "string", "required": true, - "description": "运单号(取自表中 express_code 字段)" + "description": "快递公司编码(当前实现取自 wms_order_stockout.express_code)。历史遗留命名:该字段名来源于旧口径,实际语义是快递公司编码,不是运单号;运单号见 waybill_codes" }, { "name": "expressCodes", "type": "array", "required": false, - "description": "运单号列表(取自表中 express_codes 字段)" + "description": "当前实现取自已废弃字段 wms_order_stockout.express_codes(通常为 null)。运单号请以 waybill_codes 为准,该字段待代码侧收敛" }, { "name": "qimenSync", "type": "string", "required": true, - "description": "奇门出站同步结果:success=通知成功,failure=通知失败(确认本身不受影响)" + "description": "外部回传结果:success=通知成功,failure=通知失败(确认本身不受影响)。字段名为历史遗留,API/WMS 来源同样复用该字段表示回传结果" }, { "name": "qimenSyncMessage", "type": "string", "required": false, - "description": "奇门出站失败时的错误信息" + "description": "外部回传失败时的错误信息" } ], "errors": [ { "code": "400", - "description": "缺少出库单ID" + "message": "缺少出库单ID" }, { "code": "400", - "description": "出库单不存在" + "message": "出库单不存在" }, { "code": "400", - "description": "出库单当前状态不允许确认(非 CREATED/PENDING)" + "message": "出库单当前状态不允许确认(非 CREATED/PENDING)" }, { "code": "400", - "description": "出库单未填写运单号(express_code),请先更新运单号后再确认" + "message": "出库单未填写运单号(waybill_codes),请先更新运单号后再确认" + }, + { + "code": "400", + "message": "出站同步失败: <失败原因>(QM:奇门响应 code + message,如「-1 无法匹配货主」;API:「缺少 appKey,无法回传出库单」或 OpenAPI 回调失败原因;回传服务不可用:「出库单回传服务不可用」)" } + ], + "notes": [ + "运单号口径(2026-09-13):校验与回传均以复数 waybill_codes 为准(不足则回退单数 waybill_code 兼容存量单),错误文案由 waybill_code 改为 waybill_codes。", + "多运单模型:报文 packages.package[] 每个元素一个包裹(expressCode = 对应运单号),deliveryOrder.expressCode 不传(奇门多运单以 packages 为准)。", + "已知待收敛项(代码侧,本次未做):packages.package[].packageCode 当前所有包裹共用出库单号(多包裹时重复);每个包裹的 items 为全量明细(未按包裹拆分),严格按包裹归属需补充「包裹-明细」关联模型。", + "出站分流:confirm 复用 systems/order_async.js#notifyStockoutExternalInternal,与出库单转订单回传口径一致(QM→奇门、API→OpenAPI 回调 stockout.confirm、WMS 等内部来源直接成功)。", + "报文组装复用 systems/order_async.js#buildStockoutConfirmDataInternal:快递信息取 express_code/express_name,orderLines[].ownerCode 取明细 owner_code(为空回退出库单 qimen_owner_code)。", + "已知待收敛项:确认成功响应里的 expressCode / expressCodes 仍分别返回 express_code / express_codes,与 waybill_codes 不一致,待代码侧统一。" ] }, { "method": "storage.stockout.updateExpress", - "name": "更新出库单运单号", - "description": "更新出库单的运单号字段(express_code / express_codes),用于在确认前填写运单信息。", + "name": "更新出库单快递/运单号", + "description": "更新出库单的快递公司与运单号(express_code / waybill_codes),用于在确认前填写运单信息。express_code 是快递公司编码(如 SF/STO/ZT),传入后自动从系统快递表解析 express_name(匹配不到置空串,传空值则 express_code 与 express_name 置 NULL);运单号以复数 waybill_codes(JSON 数组)为准,支持一单多运单。单数 waybill_code 已弃用:传入 waybill_codes 时会自动把单数列镜像为复数首个(便于历史查询与展示),传入空数组或 null 时单数列同步置 NULL。已废弃字段 express_codes 不在本接口读写范围内。未传入的字段不更新,三个字段都未传时返回「没有需要更新的字段」。", "isNeedAuth": true, "isNeedLogin": true, "isNeedRight": false, @@ -24839,14 +24851,21 @@ "type": "string", "required": false, "source": "body", - "description": "运单号" + "description": "快递公司编码(非运单号,如 SF/STO/ZT);传入后自动解析 express_name,传空值置 NULL" }, { - "name": "express_codes", + "name": "waybill_codes", "type": "array", "required": false, "source": "body", - "description": "运单号列表(JSON 数组)" + "description": "运单号列表(JSON 数组或 null,支持一单多运单);回传与确认校验以此为准,非数组返回 400" + }, + { + "name": "waybill_code", + "type": "string", + "required": false, + "source": "body", + "description": "运单号(单数,已弃用):仅作为 waybill_codes 首个的镜像保留;传 waybill_codes 时会以复数首个覆盖它,勿单独使用" } ], "response": [ @@ -24866,28 +24885,50 @@ "name": "express_code", "type": "string", "required": false, - "description": "更新后的运单号" + "description": "更新后的快递公司编码" }, { - "name": "express_codes", + "name": "express_name", + "type": "string", + "required": false, + "description": "由 express_code 解析出的快递公司名称" + }, + { + "name": "waybill_codes", "type": "array", "required": false, - "description": "更新后的运单号列表" + "description": "更新后的运单号列表(以此为准)" + }, + { + "name": "waybill_code", + "type": "string", + "required": false, + "description": "单数列镜像值(等于 waybill_codes 首个;已弃用,仅为历史兼容)" } ], "errors": [ { "code": "400", - "description": "缺少出库单ID" + "message": "缺少出库单ID" }, { "code": "400", - "description": "出库单不存在" + "message": "出库单不存在" }, { "code": "400", - "description": "express_codes 必须是数组或 null" + "message": "没有需要更新的字段" + }, + { + "code": "400", + "message": "waybill_codes 必须是数组或 null" } + ], + "notes": [ + "运单号口径变更(2026-09-13):以复数 waybill_codes 为准(对齐奇门 packages.package[] 多运单模型),单数 waybill_code 降级为镜像字段。", + "镜像规则:传 waybill_codes(非空数组)→ waybill_code = 首个;传空数组或 null → 两列同时置 NULL;同时传单数与复数 → 以复数首个覆盖单数;仅传单数 → 行为不变(兼容旧调用方)。", + "废弃字段提醒:express_codes(复数,历史名)已 @deprecated,本接口不读不写;运单号列表请用 waybill_codes。", + "已知待收敛项(代码侧,本次未做):对未识别/废弃参数(如 express_codes)既不报错也不兼容,仍会返回「更新成功」造成静默失败;另外本方法缺少 warehouse_id 归属校验(同文件 storage.stockout.updateInfo 有该校验)。" ] }, { diff --git a/test/app/service/systemMethods/storage/stockout.confirm.outbound.test.js b/test/app/service/systemMethods/storage/stockout.confirm.outbound.test.js new file mode 100644 index 0000000..18789c1 --- /dev/null +++ b/test/app/service/systemMethods/storage/stockout.confirm.outbound.test.js @@ -0,0 +1,336 @@ +'use strict'; + +const assert = require('node:assert/strict'); +const StorageStockoutService = require('../../../../../app/service/systemMethods/storage/stockout'); +const OrderAsyncService = require('../../../../../app/service/systems/order_async'); + +/** + * 构造 storage.stockout.confirm 出站分流测试桩。 + * + * 覆盖两条真实链路:systemMethods/storage/stockout 与 systems/order_async 共用同一 ctx, + * 便于断言「API 来源走 OpenAPI 回调、QM 来源走奇门、内部来源不发外部请求」。 + * + * @param {Object} [options] 可选配置。 + * @param {string} [options.sourceType] 出库单来源(API/QM/WMS),默认 API。 + * @param {string} [options.waybillCode] 运单号(单号),传 null 模拟未填。 + * @param {Array} [options.waybillCodes] 运单号列表。 + * @param {string} [options.qimenFlag] 奇门返回 flag,默认 success。 + * @param {Object|null} [options.storeWarehouseRow] 货主-仓库授权关系,传 null 模拟无授权。 + * @param {Object|null} [options.apiAppRow] ApiApp 配置,传 null 模拟无可用回调配置。 + * @param {boolean} [options.callbackSuccess] OpenAPI 回调结果,默认成功。 + * @return {Object} 服务实例与各调用记录。 + */ +function createHarness(options = {}) { + const callbackCalls = []; + const qimenCalls = []; + const stockoutUpdates = []; + const itemUpdates = []; + const storeWarehouseCalls = []; + const apiAppCalls = []; + const opLogCalls = []; + const lockCalls = []; + const warnLogs = []; + const errorLogs = []; + + const order = { + id: 23, + stockout_order_code: 'CK_2', + order_type: 'PTCK', + total_order_lines: 1, + order_status: 'CREATED', + sync_status: 'PENDING', + source_type: options.sourceType === undefined ? 'API' : options.sourceType, + warehouse_id: 100000, + store_id: 1000300, + qimen_owner_code: 'tbyc20260614', + qimen_warehouse_code: '100000', + express_code: 'ZT', + express_name: '自提', + waybill_code: options.waybillCode === undefined ? '5855555555' : options.waybillCode, + waybill_codes: options.waybillCodes === undefined ? [ '5855555555' ] : options.waybillCodes, + canConfirm() { + return this.order_status === 'CREATED' || this.order_status === 'PENDING'; + }, + }; + + const items = [ + { + id: 14, + order_id: 23, + order_line_no: '1', + owner_code: 'tbyc20260614', + item_code: 'P260911231515227608', + item_id: 9001, + item_name: '测试商品2', + plan_qty: 5, + actual_qty: 0, + inventory_type: 'ZP', + stock_id: 159077, + async update(values) { + itemUpdates.push(values); + Object.assign(this, values); + }, + }, + ]; + + const ctx = { + app: { + config: {}, + formatDate() { + return '2026-09-13 10:00:00'; + }, + Sequelize: { + Op: { + in: Symbol('in'), + ne: Symbol('ne'), + and: Symbol('and'), + }, + }, + qimenClient: { + async send(method, ownerCode, requestData, extra) { + qimenCalls.push({ method, ownerCode, requestData, extra }); + return { + xmlArray: { + response: options.qimenFlag === 'failure' + ? { flag: 'failure', code: '-1', message: '无法匹配货主' } + : { flag: 'success' }, + }, + }; + }, + }, + }, + user: { store_id: 100000 }, + model: { + async transaction(callback) { + const transaction = { + commit: async () => {}, + rollback: async () => {}, + }; + if (typeof callback === 'function') { + return await callback(transaction); + } + return transaction; + }, + OrderStockout: { + async findByPk() { + return order; + }, + async findOne() { + return order; + }, + async update(values) { + stockoutUpdates.push(values); + Object.assign(order, values); + return [ 1 ]; + }, + }, + OrderStockoutItems: { + async findAll() { + return items; + }, + }, + StoreWarehouse: { + async findOne(query) { + storeWarehouseCalls.push(query); + if (options.storeWarehouseRow === null) { + return null; + } + return options.storeWarehouseRow || { id: 20001 }; + }, + }, + ApiApp: { + async findOne(query) { + apiAppCalls.push(query); + if (options.apiAppRow === null) { + return null; + } + return options.apiAppRow || { + self_app_key: 'WMSD08A0001', + self_app_secret: 'SECRET-1', + callback_url: 'https://example.com/callback', + }; + }, + }, + }, + service: { + openapi: { + callback: { + async sendByAppKey(callOptions) { + callbackCalls.push(callOptions); + if (options.callbackSuccess === false) { + return { success: false, error: '回调地址不可达' }; + } + return { success: true }; + }, + }, + }, + systems: { + orderAsync: null, + stockoutOrder: { + async _writeStockoutOperationLog(opOrder, operationCode, message, logOptions) { + opLogCalls.push({ opOrder, operationCode, message, logOptions }); + }, + async cancel() { + return { flag: 'success', code: 1, message: '取消成功' }; + }, + }, + stockStore: { + async lockItemStorages(stockId, qty, transaction, oversellConfig, meta) { + lockCalls.push({ stockId, qty, transaction, oversellConfig, meta }); + return { success: true }; + }, + }, + }, + }, + logger: { + info() {}, + warn(message) { + warnLogs.push(String(message)); + }, + error(message) { + errorLogs.push(String(message)); + }, + }, + }; + + // 真实 OrderAsyncService 实例:出站分流逻辑不做桩替换,保证端到端覆盖 + ctx.service.systems.orderAsync = new OrderAsyncService(ctx); + + return { + order, + service: new StorageStockoutService(ctx), + callbackCalls, + qimenCalls, + stockoutUpdates, + itemUpdates, + storeWarehouseCalls, + apiAppCalls, + opLogCalls, + lockCalls, + warnLogs, + errorLogs, + }; +} + +describe('test/app/service/systemMethods/storage/stockout.confirm.outbound.test.js', () => { + it('API 来源出库单确认应走 OpenAPI 回调 stockout.confirm,且不调用奇门', async () => { + const harness = createHarness({ sourceType: 'API' }); + + const result = await harness.service.confirm({ id: 23 }); + + // 未调用奇门,改为 OpenAPI 回调 + assert.equal(harness.qimenCalls.length, 0, 'API 来源不应调用奇门'); + assert.equal(harness.callbackCalls.length, 1, 'API 来源应发送 OpenAPI 回调'); + assert.equal(harness.callbackCalls[0].event, 'stockout.confirm'); + assert.equal(harness.callbackCalls[0].appKey, 'WMSD08A0001'); + + // 回调报文与奇门同层级,快递/运单号取自重出库单字段 + const request = harness.callbackCalls[0].request; + assert.equal(request.deliveryOrder.deliveryOrderCode, 'CK_2'); + assert.equal(request.deliveryOrder.orderType, 'PTCK'); + assert.equal(request.deliveryOrder.warehouseCode, '100000'); + assert.equal(request.packages.package.length, 1); + assert.equal(request.packages.package[0].logisticsCode, 'ZT'); + assert.equal(request.packages.package[0].logisticsName, '自提'); + assert.equal(request.packages.package[0].expressCode, '5855555555'); + assert.equal(request.orderLines[0].ownerCode, 'tbyc20260614'); + assert.equal(request.orderLines[0].planQty, 5); + + // 回调成功 → 释放锁定并推进 COMPLETED + assert.equal(result.flag, 'success'); + assert.equal(harness.order.order_status, 'COMPLETED'); + assert.equal(harness.lockCalls.length, 1); + }); + + it('API 来源但货主无可用 ApiApp 时应失败且不回落奇门', async () => { + const harness = createHarness({ sourceType: 'API', apiAppRow: null }); + + const result = await harness.service.confirm({ id: 23 }); + + assert.equal(harness.qimenCalls.length, 0, 'API 来源不应回落奇门'); + assert.equal(harness.callbackCalls.length, 0, '无 appKey 时不应发送回调'); + assert.equal(result.flag, 'failure'); + assert.match(result.message, /缺少 appKey/); + assert.equal(harness.order.order_status, 'CREATED'); + assert.equal(harness.order.sync_status, 'FAILED'); + }); + + it('QM 来源出库单确认仍走奇门 stockout.confirm,且不发 OpenAPI 回调', async () => { + const harness = createHarness({ sourceType: 'QM' }); + + const result = await harness.service.confirm({ id: 23 }); + + assert.equal(harness.callbackCalls.length, 0, 'QM 来源不应发送 OpenAPI 回调'); + assert.equal(harness.qimenCalls.length, 1); + assert.equal(harness.qimenCalls[0].method, 'taobao.qimen.stockout.confirm'); + assert.equal(harness.qimenCalls[0].ownerCode, 'tbyc20260614'); + assert.equal(result.flag, 'success'); + assert.equal(harness.order.order_status, 'COMPLETED'); + }); + + it('内部来源(WMS)出库单确认无需外部通知,直接完成', async () => { + const harness = createHarness({ sourceType: 'WMS' }); + + const result = await harness.service.confirm({ id: 23 }); + + assert.equal(harness.qimenCalls.length, 0, '内部来源不应调用奇门'); + assert.equal(harness.callbackCalls.length, 0, '内部来源不应发送 OpenAPI 回调'); + assert.equal(result.flag, 'success'); + assert.equal(harness.order.order_status, 'COMPLETED'); + assert.equal(harness.lockCalls.length, 1); + }); + + it('QM 来源奇门返回失败时应保持 CREATED 并记录 sync_message', async () => { + const harness = createHarness({ sourceType: 'QM', qimenFlag: 'failure' }); + + const result = await harness.service.confirm({ id: 23 }); + + assert.equal(result.flag, 'failure'); + assert.match(result.message, /无法匹配货主/); + assert.equal(harness.order.order_status, 'CREATED'); + assert.equal(harness.order.sync_status, 'FAILED'); + assert.match(harness.order.sync_message, /无法匹配货主/); + assert.equal(harness.lockCalls.length, 0, '失败时不应释放库存锁定'); + }); + + it('未填写运单号(复数与单数均为空)时直接拒绝确认', async () => { + const harness = createHarness({ sourceType: 'API', waybillCode: null, waybillCodes: null }); + + const result = await harness.service.confirm({ id: 23 }); + + assert.equal(result.flag, 'failure'); + assert.match(result.message, /waybill_codes/); + assert.equal(harness.qimenCalls.length, 0); + assert.equal(harness.callbackCalls.length, 0); + }); + + it('一单多运单:只填复数 waybill_codes 即可确认,回传走 packages.package[]', async () => { + const harness = createHarness({ + sourceType: 'API', + waybillCode: null, // 单数已弃用,调用方不再传 + waybillCodes: [ 'WB-A', 'WB-B' ], + }); + + const result = await harness.service.confirm({ id: 23 }); + + assert.equal(result.flag, 'success'); + assert.equal(harness.callbackCalls.length, 1); + + // 多运单通过 packages.package[] 承载,不使用 deliveryOrder.expressCode + const pkgs = harness.callbackCalls[0].request.packages.package; + assert.equal(pkgs.length, 2); + assert.deepEqual(pkgs.map(item => item.expressCode), [ 'WB-A', 'WB-B' ]); + assert.equal(harness.callbackCalls[0].request.deliveryOrder.expressCode, undefined); + assert.equal(harness.order.order_status, 'COMPLETED'); + }); + + it('存量单仅有单数 waybill_code 时仍可确认(兼容回退)', async () => { + const harness = createHarness({ sourceType: 'API', waybillCode: 'OLD-WB-1', waybillCodes: null }); + + const result = await harness.service.confirm({ id: 23 }); + + assert.equal(result.flag, 'success'); + const pkgs = harness.callbackCalls[0].request.packages.package; + assert.deepEqual(pkgs.map(item => item.expressCode), [ 'OLD-WB-1' ]); + }); +}); diff --git a/test/app/service/systemMethods/storage/stockout.updateExpress.test.js b/test/app/service/systemMethods/storage/stockout.updateExpress.test.js new file mode 100644 index 0000000..535070d --- /dev/null +++ b/test/app/service/systemMethods/storage/stockout.updateExpress.test.js @@ -0,0 +1,161 @@ +'use strict'; + +const assert = require('node:assert/strict'); +const StorageStockoutService = require('../../../../../app/service/systemMethods/storage/stockout'); + +/** + * 构造 storage.stockout.updateExpress 测试桩。 + * + * 重点覆盖「单数 waybill_code 已弃用、以复数 waybill_codes 为准」的镜像写入口径。 + * + * @param {Object} [options] 可选配置。 + * @param {Map} [options.expressMap] 系统快递表映射(编码 → { name })。 + * @return {Object} 服务实例与写入记录。 + */ +function createHarness(options = {}) { + const writes = []; + const warnLogs = []; + + const order = { + id: 24, + stockout_order_code: 'CK_3', + express_code: null, + express_name: null, + waybill_code: null, + waybill_codes: null, + async update(values) { + writes.push(values); + Object.assign(this, values); + }, + async reload() { + // 无需实现:仅保证 updateExpress 内的 reload 调用可用 + }, + }; + + const expressMap = options.expressMap || new Map([ + [ 'ZT', { name: '自提' }], + [ 'SF', { name: '顺丰速运' }], + ]); + + const ctx = { + app: { config: {} }, + model: { + OrderStockout: { + async findByPk() { + return order; + }, + }, + }, + service: { + systems: { + setting: { + express: { + async getSystemExpressMap() { + return expressMap; + }, + }, + }, + }, + }, + logger: { + info() {}, + warn(message) { + warnLogs.push(String(message)); + }, + error() {}, + }, + }; + + return { + order, + service: new StorageStockoutService(ctx), + writes, + warnLogs, + }; +} + +describe('test/app/service/systemMethods/storage/stockout.updateExpress.test.js', () => { + it('传复数 waybill_codes 时以复数为准,并镜像单数 waybill_code 为首个', async () => { + const harness = createHarness(); + + const result = await harness.service.updateExpress({ + id: 24, + express_code: 'ZT', + waybill_codes: [ 'WB-A', 'WB-B' ], + }); + + assert.equal(result.flag, 'success'); + assert.deepEqual(harness.writes.length, 1); + const write = harness.writes[0]; + assert.deepEqual(write.waybill_codes, [ 'WB-A', 'WB-B' ]); + assert.equal(write.waybill_code, 'WB-A', '单数列应镜像为复数首个'); + assert.equal(write.express_code, 'ZT'); + assert.equal(write.express_name, '自提'); + assert.equal(result.waybill_code, 'WB-A'); + assert.deepEqual(result.waybill_codes, [ 'WB-A', 'WB-B' ]); + }); + + it('传 waybill_codes 为空数组时单数镜像为 null', async () => { + const harness = createHarness(); + + const result = await harness.service.updateExpress({ id: 24, waybill_codes: [] }); + + assert.equal(result.flag, 'success'); + assert.deepEqual(harness.writes[0].waybill_codes, []); + assert.equal(harness.writes[0].waybill_code, null); + }); + + it('传 waybill_codes 为 null 时两列同时清空', async () => { + const harness = createHarness(); + + const result = await harness.service.updateExpress({ id: 24, waybill_codes: null }); + + assert.equal(result.flag, 'success'); + assert.equal(harness.writes[0].waybill_codes, null); + assert.equal(harness.writes[0].waybill_code, null); + }); + + it('复数优先:同时传单数与复数时以复数首个覆盖单数', async () => { + const harness = createHarness(); + + const result = await harness.service.updateExpress({ + id: 24, + waybill_code: 'OLD-WB', + waybill_codes: [ 'NEW-WB-1', 'NEW-WB-2' ], + }); + + assert.equal(result.flag, 'success'); + assert.equal(harness.writes[0].waybill_code, 'NEW-WB-1'); + assert.deepEqual(harness.writes[0].waybill_codes, [ 'NEW-WB-1', 'NEW-WB-2' ]); + }); + + it('兼容:仅传单数 waybill_code 时行为不变(写入单数)', async () => { + const harness = createHarness(); + + const result = await harness.service.updateExpress({ id: 24, waybill_code: 'ONLY-SINGLE' }); + + assert.equal(result.flag, 'success'); + assert.equal(harness.writes[0].waybill_code, 'ONLY-SINGLE'); + assert.equal(harness.writes[0].waybill_codes, undefined); + }); + + it('waybill_codes 非数组时返回 400 且不写入', async () => { + const harness = createHarness(); + + const result = await harness.service.updateExpress({ id: 24, waybill_codes: 'WB-A' }); + + assert.equal(result.flag, 'failure'); + assert.match(result.message, /必须是数组或 null/); + assert.equal(harness.writes.length, 0); + }); + + it('三个字段都未传时返回「没有需要更新的字段」', async () => { + const harness = createHarness(); + + const result = await harness.service.updateExpress({ id: 24 }); + + assert.equal(result.flag, 'failure'); + assert.match(result.message, /没有需要更新的字段/); + assert.equal(harness.writes.length, 0); + }); +});