fix(stockout): 出库单确认按来源分流回传,运单号口径收敛为复数

- storage.stockout.confirm 出站回传改为按 source_type 分流(复用 order_async.js 既有分流实现):
  QM→奇门 taobao.qimen.stockout.confirm;API→OpenAPI 回调 stockout.confirm(appKey 按货主合约
  反查 wms_store_warehouse(auth_status=2) + wms_api_app(启用且 callback_url 非空));
  WMS 等内部来源无需外部通知、直接视为成功。修复此前 API 来源出库单被硬编码发往奇门、
  遭「-1 无法匹配货主」拒绝后无法确认(跳过出站同样走失败分支)的问题。
- storage.stockout.confirm 运单号校验与回传改为以复数 waybill_codes 为准(对齐奇门
  packages.package[].expressCode 多运单模型,不使用 deliveryOrder.expressCode);
  单数 waybill_code 已弃用,仅在复数缺失时回退单数兼容存量单;失败文案改为 (waybill_codes)。
- storage.stockout.updateExpress 以 waybill_codes 为准,单数 waybill_code 降级为镜像字段
  (传非空复数时镜像首个、传空数组/null 时同步置 NULL、同时传两列时复数优先);
  仅传单数的旧调用方行为不变。
- app/service/systems/order_async.js 新增 3 个可复用实例方法(buildStockoutConfirmRequest /
  notifyStockoutExternal / resolveOpenApiAppByStore),薄封装既有模块级实现,
  未改动原函数及其既有调用方。
- 新增回归测试:stockout.confirm.outbound.test.js(8 条,覆盖 API/QM/WMS 三路来源、多运单复数
  回传、存量单单数回退)、stockout.updateExpress.test.js(7 条,覆盖复数镜像与兼容行为)。
- 同步 methods/system.json 与 methods/changes/system.json(storage.stockout.confirm /
  storage.stockout.updateExpress)。
This commit is contained in:
liufumingren 2026-09-15 15:40:39 +08:00
parent 8757dc6c2e
commit 55f766f643
6 changed files with 700 additions and 91 deletions

View File

@ -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<Object>} 统一成功/失败包装响应
@ -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<Object>} 统一成功/失败包装响应
*/
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) {

View File

@ -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<string>} [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<Object|null>} { appKey, selfAppSecret, callbackUrl },未找到时返回 null。
*/
async resolveOpenApiAppByStore(storeId, warehouseId) {
return await resolveOpenApiAppByStoreInternal(this, storeId, warehouseId);
}

View File

@ -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",

View File

@ -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 有该校验)。"
]
},
{

View File

@ -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<string>} [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' ]);
});
});

View File

@ -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<string, Object>} [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);
});
});