diff --git a/backend/app/lib/openapiIdempotency.js b/backend/app/lib/openapiIdempotency.js index 6e66702..24e381f 100644 --- a/backend/app/lib/openapiIdempotency.js +++ b/backend/app/lib/openapiIdempotency.js @@ -91,7 +91,8 @@ function buildReplay(row) { * 处理已存在的幂等记录 * * 只有「已成功」的记录才回放:失败结果不缓存,允许调用方用同一 request_id 重新处理 - * (取号类接口的重复保护靠业务侧幂等,如订单已有运单号直接复用,而不是锁死请求)。 + * (deliveryorder.getwaybill 的逐单重复保护由 waybill_fetch_idempotencies 按订单、 + * 快递编码和包裹序号完成)。 * @param {Object} ctx egg context * @param {Object} row 幂等记录 * @param {Object} params 参数 diff --git a/backend/app/lib/waybillGet.js b/backend/app/lib/waybillGet.js index ce0103b..dccb760 100644 --- a/backend/app/lib/waybillGet.js +++ b/backend/app/lib/waybillGet.js @@ -56,6 +56,12 @@ const BUSINESS_KEY_PATHS = [ /** 单次批量上限(避免一次回调过大、平台侧限流) */ const MAX_BATCH = 100; +const ITEM_STATUS = { + PROCESSING: 0, + SUCCESS: 1, + UNCERTAIN: 2, +}; +const ITEM_PROCESSING_STALE_MS = 30 * 60 * 1000; /** * 并发处理数(平台取号是网络请求,适度并发缩短总耗时) @@ -438,6 +444,7 @@ async function saveRecord(ctx, meta, result, extra = {}) { request_id: meta.requestId || '', delivery_order_code: meta.code, express_code: meta.expressCode || '', + package_index: meta.packageIndex, platform_code: meta.platformCode || '', account_id: meta.accountId || null, template_id: meta.templateId || '', @@ -445,6 +452,7 @@ async function saveRecord(ctx, meta, result, extra = {}) { waybill_source: (result && result.waybill_source) || '', waybill_code: (result && result.waybill_code) || '', waybill_codes: result && result.waybill_codes ? JSON.stringify(result.waybill_codes) : '', + result_data: result ? JSON.stringify(result) : '', printinfo: extra.printinfo || '', signature: extra.signature || '', print_history_ids: Array.isArray(extra.print_history_ids) ? JSON.stringify(extra.print_history_ids) : '', @@ -460,6 +468,129 @@ async function saveRecord(ctx, meta, result, extra = {}) { } } +/** + * 按订单、快递和包裹序号占用一个取号幂等键。 + * @param {Object} ctx egg context + * @param {Object} key 幂等键字段 + * @param {Object} meta 留痕上下文 + * @return {Promise<{entry: Object, owner: boolean}>} 记录和是否成功占用 + */ +async function claimItem(ctx, key, meta) { + const Model = ctx.model.WaybillFetchIdempotency; + const existing = await Model.findOne({ where: key }); + if (existing) return { entry: existing, owner: false }; + + try { + const entry = await Model.create({ + ...key, + request_id: meta.requestId || '', + status: ITEM_STATUS.PROCESSING, + }); + return { entry, owner: true }; + } catch (err) { + // 并发请求由数据库唯一索引仲裁;只有确认存在竞争记录时才将其视为重复请求 + const raced = await Model.findOne({ where: key }); + if (!raced) throw err; + return { entry: raced, owner: false }; + } +} + +/** + * 解析幂等记录中保存的逐单返回结果。 + * @param {Object} entry 幂等记录 + * @return {Object} 已保存结果 + */ +function parseSavedResult(entry) { + const result = JSON.parse(entry.result_data || ''); + if (!result || !result.success || !result.waybill_code) { + throw new Error('保存的取号结果不完整'); + } + return result; +} + +/** + * 兼容幂等表上线前已成功的默认包裹记录。 + * 历史记录没有 package_index 时,仅在单号本身没有子包裹序号且请求序号为 0 时复用。 + * @param {Object} ctx egg context + * @param {Object} params 查询条件 + * @param {number} params.principalId 主体ID + * @param {number} params.warehouseId 仓库ID + * @param {string} params.code 发货单号 + * @param {string} params.expressCode 快递编码 + * @param {number} params.packageIndex 包裹序号 + * @return {Promise} 已有成功记录 + */ +async function findLegacyRecord(ctx, { principalId, warehouseId, code, expressCode, packageIndex }) { + const where = { + principal_id: principalId, + warehouse_id: warehouseId, + delivery_order_code: code, + express_code: expressCode, + status: 1, + }; + if (packageIndex === 0 && resolvePackageIndex(code) === 0) { + const Op = ctx.app.Sequelize.Op; + where[Op.or] = [{ package_index: 0 }, { package_index: null }]; + } else { + where.package_index = packageIndex; + } + return await ctx.model.WaybillFetchRecord.findOne({ + where, + order: [[ 'created_at', 'DESC' ], [ 'id', 'DESC' ]], + }); +} + +/** + * 从旧取号记录组装可回给 WMS 的结果。 + * @param {Object} row 历史取号记录 + * @param {Object} params 当前订单参数 + * @param {string} params.code 发货单号 + * @param {string} params.expressCode 快递编码 + * @param {number} params.packageIndex 包裹序号 + * @return {Object} 取号结果 + */ +function resultFromLegacyRecord(row, { code, expressCode, packageIndex }) { + if (row.result_data) { + return parseSavedResult({ result_data: row.result_data }); + } + const waybillCodes = parseRecordArray(row.waybill_codes, 'waybill_codes'); + const printHistoryIds = parseRecordArray(row.print_history_ids, 'print_history_ids'); + const waybillCode = String(row.waybill_code || waybillCodes[0] || '').trim(); + if (!waybillCode) throw new Error('历史取号记录没有运单号'); + return { + delivery_order_code: code, + success: true, + message: '已复用数据库中的取号结果', + waybill_source: row.waybill_source || 'express_print', + express_code: expressCode, + platform_code: row.platform_code || '', + waybill_code: waybillCode, + waybill_codes: waybillCodes.length ? waybillCodes : [ waybillCode ], + package_index: packageIndex, + cai_niao_auth_info_id: row.cai_niao_auth_info_id == null ? null : Number(row.cai_niao_auth_info_id), + printinfo: row.printinfo || '', + signature: row.signature || '', + print_history_ids: printHistoryIds, + print_history_id: printHistoryIds[0] ? String(printHistoryIds[0].id || '') : '', + encryptprintinfo: '', + key: '', + ver: '', + }; +} + +/** + * 解析历史记录中的 JSON 数组字段。 + * @param {string} value JSON 文本 + * @param {string} field 字段名 + * @return {Array} 数组 + */ +function parseRecordArray(value, field) { + if (!value) return []; + const parsed = JSON.parse(value); + if (!Array.isArray(parsed)) throw new Error(`历史取号记录 ${field} 不是数组`); + return parsed; +} + /** * 处理单个订单取号 * @param {Object} ctx egg context @@ -468,40 +599,178 @@ async function saveRecord(ctx, meta, result, extra = {}) { * @param {number} params.warehouseId app_key 定位到的仓库ID * @param {Object} params.item 订单项(含单号与快递编码) * @param {Map} params.memo 批内缓存(账号实例等) + * @param {Map} params.itemMemo 批内订单级幂等缓存 * @param {string} [params.requestId] 调用方 request_id(留痕用) * @return {Promise} 结果项 */ -async function processItem(ctx, { principalId, warehouseId, item, memo, requestId }) { +async function processItem(ctx, { principalId, warehouseId, item, memo, itemMemo, requestId }) { const code = orderCallback.pickFirst(item || {}, CODE_PATHS); if (!code) return fail('', '缺少发货单号(deliveryOrderCode / outBizCode)'); // 快递编码必须由 WMS 传入;订单上的 logistics_code 不参与取号 - const expressCode = pickExpressCode(item); + const expressCode = String(pickExpressCode(item) || '').trim(); if (!expressCode) return fail(code, '缺少快递编码(expressCode)'); + const explicitIndex = pickPackageIndex(item); + const packageIndex = explicitIndex === null ? resolvePackageIndex(code) : explicitIndex; + const itemKey = JSON.stringify([ principalId, warehouseId, code, expressCode, packageIndex ]); + if (itemMemo.has(itemKey)) return await itemMemo.get(itemKey); + + const promise = processItemWithIdempotency(ctx, { + principalId, + warehouseId, + memo, + requestId, + code, + expressCode, + packageIndex, + }); + itemMemo.set(itemKey, promise); + try { + return await promise; + } catch (err) { + itemMemo.delete(itemKey); + throw err; + } +} + +/** + * 占用订单级幂等键后执行平台取号。 + * @param {Object} ctx egg context + * @param {Object} params 订单取号参数 + * @param {number} params.principalId 主体ID + * @param {number} params.warehouseId 仓库ID + * @param {Map} params.memo 批内账号缓存 + * @param {string} params.requestId 调用方 request_id + * @param {string} params.code 发货单号 + * @param {string} params.expressCode 快递编码 + * @param {number} params.packageIndex 包裹序号 + * @return {Promise} 逐单结果 + */ +async function processItemWithIdempotency(ctx, { + principalId, warehouseId, memo, requestId, code, expressCode, packageIndex, +}) { + const key = { + principal_id: principalId, + warehouse_id: warehouseId, + delivery_order_code: code, + express_code: expressCode, + package_index: packageIndex, + }; + const { entry, owner } = await claimItem(ctx, key, { requestId }); + if (!owner) { + if (Number(entry.status) === ITEM_STATUS.SUCCESS) { + try { + return parseSavedResult(entry); + } catch (err) { + ctx.logger.error('[waybill.get] 读取幂等结果失败 %s:%s', code, err.message); + await entry.update({ status: ITEM_STATUS.UNCERTAIN, error_message: err.message }); + return fail(code, '数据库中的取号结果无法安全读取,请核实运单后再处理'); + } + } + if (Number(entry.status) === ITEM_STATUS.PROCESSING) { + const updatedAt = new Date(entry.updated_at || entry.created_at || 0).getTime(); + if (updatedAt && Date.now() - updatedAt >= ITEM_PROCESSING_STALE_MS) { + const errorMessage = '取号任务超过 30 分钟仍未完成,平台侧结果需要人工核实'; + await entry.update({ status: ITEM_STATUS.UNCERTAIN, error_message: errorMessage }); + return fail(code, errorMessage); + } + } + const message = Number(entry.status) === ITEM_STATUS.UNCERTAIN + ? '上次取号结果待核实,已阻止重复取号' + : '相同订单、快递编码和包裹序号的取号正在处理中,请稍后重试'; + return fail(code, entry.error_message ? `${message}:${entry.error_message}` : message); + } + + const replayParams = { code, expressCode, packageIndex }; + let legacyRecord; + try { + legacyRecord = await findLegacyRecord(ctx, { + principalId, + warehouseId, + ...replayParams, + }); + } catch (err) { + await entry.destroy(); + throw err; + } + if (legacyRecord) { + try { + const result = resultFromLegacyRecord(legacyRecord, replayParams); + await entry.update({ + status: ITEM_STATUS.SUCCESS, + result_data: JSON.stringify(result), + error_message: '', + }); + return result; + } catch (err) { + ctx.logger.error('[waybill.get] 读取历史取号记录失败 %s:%s', code, err.message); + await entry.update({ status: ITEM_STATUS.UNCERTAIN, error_message: err.message }); + return fail(code, '历史取号记录无法安全重放,请核实运单后再处理'); + } + } + // 留痕上下文:处理过程中逐步补齐(平台编码 / 打单账号 / 模板) - const meta = { principalId, warehouseId, requestId, code, expressCode, platformCode: '', accountId: null, templateId: null }; + const meta = { + principalId, + warehouseId, + requestId, + code, + expressCode, + packageIndex, + platformCode: '', + accountId: null, + templateId: null, + }; const detail = { raw: null, printinfo: '', signature: '', encryptprintinfo: '', key: '', ver: '', print_history_ids: [] }; - const result = await callPlatform(ctx, { principalId, warehouseId, code, expressCode, item, memo, meta, detail }); + const result = await callPlatform(ctx, { + principalId, + warehouseId, + code, + expressCode, + memo, + meta, + detail, + packageIndex, + }); await saveRecord(ctx, meta, result, detail); + + if (result.success) { + try { + await entry.update({ + status: ITEM_STATUS.SUCCESS, + result_data: JSON.stringify(result), + error_message: '', + }); + } catch (err) { + ctx.logger.error('[waybill.get] 保存订单级幂等结果失败 %s:%s', code, err.message); + throw new Error(`订单 ${code} 已取号,但幂等结果保存失败;已阻止重复取号,请核实运单`); + } + } else if (meta.platformCallUncertain) { + const errorMessage = `平台取号结果暂不确定:${result.message}`; + await entry.update({ status: ITEM_STATUS.UNCERTAIN, error_message: errorMessage }); + return fail(code, errorMessage); + } else { + await entry.destroy(); + } return result; } /** - * 单订单取号主流程(结果由 processItem 统一留痕) + * 单订单取号主流程(结果由 processItemWithIdempotency 统一留痕) * @param {Object} ctx egg context * @param {Object} params 参数 * @param {number} params.principalId 主体ID * @param {number} params.warehouseId 仓库ID * @param {string} params.code 发货单号 * @param {string} params.expressCode 快递编码 - * @param {Object} params.item 订单项(可带 packageIndex 指定包裹序号) * @param {Map} params.memo 批内缓存 * @param {Object} params.meta 留痕上下文(会被补齐) * @param {Object} params.detail 平台返回数据(raw / printinfo / signature) + * @param {number} params.packageIndex 包裹序号 * @return {Promise} 结果项 */ -async function callPlatform(ctx, { principalId, warehouseId, code, expressCode, item, memo, meta, detail }) { +async function callPlatform(ctx, { principalId, warehouseId, code, expressCode, memo, meta, detail, packageIndex }) { try { const resolved = await orderCallback.resolveDeliveryBill(ctx, { code, principalId }); const order = resolved.order; @@ -571,17 +840,25 @@ async function callPlatform(ctx, { principalId, warehouseId, code, expressCode, // 1688 分销单被换算成抖音小店/淘宝后,取号域名仍要按原始平台(否则回读订单行查错域名) const extendProps = orderPlain.extend_props && typeof orderPlain.extend_props === 'object' ? orderPlain.extend_props : {}; // 包裹序号:报文显式指定优先(拆单场景),否则按单号尾部 `_N` 推导 - const explicitIndex = pickPackageIndex(item); - const packageIndex = explicitIndex === null ? resolvePackageIndex(code) : explicitIndex; - const fetched = await platformService.fetchWaybillNo(orderPlain, { - template: template.get ? template.get({ plain: true }) : template, - expressCode, - platformCode, - originalPlatformCode: extendProps.original_platform_code || '', - packageIndex, - }); + let fetched; + try { + fetched = await platformService.fetchWaybillNo(orderPlain, { + template: template.get ? template.get({ plain: true }) : template, + expressCode, + platformCode, + originalPlatformCode: extendProps.original_platform_code || '', + packageIndex, + }); + } catch (err) { + // 收到平台明确响应时允许重试;网络异常可能发生在平台已出号后,必须先核实避免重复消耗面单 + meta.platformCallUncertain = !err.rawResponse; + throw err; + } const waybill = normalizeWaybill(fetched); - if (!waybill.waybill_code) return fail(code, '平台未返回运单号'); + if (!waybill.waybill_code) { + meta.platformCallUncertain = true; + return fail(code, '平台响应中未解析到运单号'); + } // 面单打印数据原样保留:既要透传给 WMS,也要落取号记录备查 detail.raw = fetched && fetched.raw ? fetched.raw : null; @@ -673,22 +950,22 @@ async function getWaybills(ctx, { principalId, warehouseId, data, requestId }) { return { ok: false, message: `单次最多取号 ${MAX_BATCH} 单` }; } - // 同一批内按账号缓存完整账号实例(含 cookie/token,供平台客户端直接使用), - // 一次批量回调通常只涉及 1 个打单账号,避免逐单重复查库 + // 同一批内缓存打单账号与相同订单级幂等键的结果,避免重复查库或重复消耗面单 const memo = new Map(); + const itemMemo = new Map(); const results = await mapLimit(items, CONCURRENCY, item => processItem(ctx, { principalId, warehouseId, item, memo, + itemMemo, requestId, })); const success = results.filter(row => row.success).length; return { ok: true, message: 'ok', - // 有订单没取到号时不锁定 request_id:调用方用同一 request_id 重试会整批重跑, - // 已取到号的单会复用打单平台订单上的运单号(不重复消耗面单),只补真正失败的单 + // 有订单没取到号时不锁定 request_id:订单级幂等记录负责复用已取到的单,只重试失败单 replayable: success === results.length, data: { total: results.length, diff --git a/backend/app/model/waybillFetchIdempotency.js b/backend/app/model/waybillFetchIdempotency.js new file mode 100644 index 0000000..a7b2116 --- /dev/null +++ b/backend/app/model/waybillFetchIdempotency.js @@ -0,0 +1,30 @@ +'use strict'; + +/** + * 按订单、快递编码和包裹序号保护取号结果,避免不同批次重试重复消耗面单。 + * @param {Egg.Application} app egg application + * @return {object} waybillFetchIdempotency model + */ +module.exports = app => { + const { BIGINT, STRING, INTEGER, TINYINT, TEXT, DATE } = app.Sequelize; + + const WaybillFetchIdempotency = app.model.define('waybill_fetch_idempotency', { + id: { type: BIGINT.UNSIGNED, primaryKey: true, autoIncrement: true, comment: '主键' }, + principal_id: { type: BIGINT.UNSIGNED, allowNull: false, comment: '主体ID' }, + warehouse_id: { type: BIGINT.UNSIGNED, allowNull: false, comment: '仓库ID' }, + delivery_order_code: { type: STRING(100), allowNull: false, comment: 'OMS 发货单号' }, + express_code: { type: STRING(50), allowNull: false, comment: 'WMS 传入的快递编码' }, + package_index: { type: INTEGER.UNSIGNED, allowNull: false, comment: '包裹序号(0 基)' }, + request_id: { type: STRING(100), comment: '首次取号的 request_id' }, + status: { type: TINYINT, allowNull: false, defaultValue: 0, comment: '状态:0处理中 1成功 2结果待核实' }, + result_data: { type: TEXT('medium'), comment: '成功时完整的逐单返回结果(JSON)' }, + error_message: { type: TEXT, comment: '结果待核实时的原因' }, + created_at: { type: DATE, comment: '创建时间' }, + updated_at: { type: DATE, comment: '更新时间' }, + }, { + tableName: 'waybill_fetch_idempotencies', + comment: '取号订单级幂等记录', + }); + + return WaybillFetchIdempotency; +}; diff --git a/backend/app/model/waybillFetchRecord.js b/backend/app/model/waybillFetchRecord.js index 2f26009..14c58b2 100644 --- a/backend/app/model/waybillFetchRecord.js +++ b/backend/app/model/waybillFetchRecord.js @@ -3,14 +3,14 @@ /** * 取号明细记录模型,对应 waybill_fetch_records。 * - * 每次 `deliveryorder.getwaybill` 逐单取号(成功/复用/失败)都写一条,保存打单平台的原始返回, - * 以及需要透传给 WMS 的 `printinfo / signature`。 + * 每次实际调用平台取号都写一条,保存打单平台原始返回、完整结果及包裹序号。 + * 已有运单号的幂等重放不新增平台取号记录。 * 仅做留痕,不参与业务状态流转(取号与订单表暂不关联)。 * @param {Egg.Application} app egg application * @return {object} waybillFetchRecord model */ module.exports = app => { - const { BIGINT, STRING, TINYINT, TEXT, DATE } = app.Sequelize; + const { BIGINT, STRING, INTEGER, TINYINT, TEXT, DATE } = app.Sequelize; const WaybillFetchRecord = app.model.define('waybill_fetch_record', { id: { type: BIGINT.UNSIGNED, primaryKey: true, autoIncrement: true, comment: '主键' }, @@ -19,6 +19,7 @@ module.exports = app => { request_id: { type: STRING(100), comment: '调用方 request_id' }, delivery_order_code: { type: STRING(100), allowNull: false, comment: 'OMS 发货单号' }, express_code: { type: STRING(50), comment: '本次取号的快递编码' }, + package_index: { type: INTEGER.UNSIGNED, comment: '包裹序号(0 基);历史记录可能为空' }, platform_code: { type: STRING(50), comment: '订单来源平台编码' }, account_id: { type: BIGINT.UNSIGNED, comment: '外部打单账号ID' }, template_id: { type: STRING(100), comment: '面单模板ID' }, @@ -26,6 +27,7 @@ module.exports = app => { waybill_source: { type: STRING(20), comment: '运单号来源:express_print / platform_last' }, waybill_code: { type: STRING(100), comment: '主运单号' }, waybill_codes: { type: TEXT, comment: '全部运单号(JSON 数组)' }, + result_data: { type: TEXT('medium'), comment: '完整的逐单返回结果(JSON)' }, printinfo: { type: TEXT('medium'), comment: '面单打印数据(平台原样返回)' }, signature: { type: TEXT('medium'), comment: '面单签名(平台原样返回)' }, print_history_ids: { diff --git a/backend/database/migrations/20261117100000-create-waybill-fetch-idempotencies.js b/backend/database/migrations/20261117100000-create-waybill-fetch-idempotencies.js new file mode 100644 index 0000000..7d03192 --- /dev/null +++ b/backend/database/migrations/20261117100000-create-waybill-fetch-idempotencies.js @@ -0,0 +1,69 @@ +'use strict'; + +/** + * 为取号增加订单级幂等键,并在取号历史中保存包裹序号与完整返回结果。 + */ +module.exports = { + async up(queryInterface, Sequelize) { + await queryInterface.addColumn('waybill_fetch_records', 'package_index', { + type: Sequelize.INTEGER.UNSIGNED, + allowNull: true, + comment: '包裹序号(0 基);历史记录可能为空', + after: 'express_code', + }); + await queryInterface.addColumn('waybill_fetch_records', 'result_data', { + type: Sequelize.TEXT('medium'), + allowNull: true, + comment: '完整的逐单返回结果(JSON)', + after: 'waybill_codes', + }); + + await queryInterface.createTable('waybill_fetch_idempotencies', { + id: { type: Sequelize.BIGINT.UNSIGNED, primaryKey: true, autoIncrement: true, comment: '主键' }, + principal_id: { type: Sequelize.BIGINT.UNSIGNED, allowNull: false, comment: '主体ID' }, + warehouse_id: { type: Sequelize.BIGINT.UNSIGNED, allowNull: false, comment: '仓库ID' }, + delivery_order_code: { type: Sequelize.STRING(100), allowNull: false, comment: 'OMS 发货单号' }, + express_code: { type: Sequelize.STRING(50), allowNull: false, comment: 'WMS 传入的快递编码' }, + package_index: { type: Sequelize.INTEGER.UNSIGNED, allowNull: false, comment: '包裹序号(0 基)' }, + request_id: { type: Sequelize.STRING(100), allowNull: true, comment: '首次取号的 request_id' }, + status: { + type: Sequelize.TINYINT, + allowNull: false, + defaultValue: 0, + comment: '状态:0处理中 1成功 2结果待核实', + }, + result_data: { type: Sequelize.TEXT('medium'), allowNull: true, comment: '成功时完整的逐单返回结果(JSON)' }, + error_message: { type: Sequelize.TEXT, allowNull: true, comment: '结果待核实时的原因' }, + created_at: { type: Sequelize.DATE, allowNull: true, comment: '创建时间' }, + updated_at: { type: Sequelize.DATE, allowNull: true, comment: '更新时间' }, + }); + + await queryInterface.addIndex('waybill_fetch_idempotencies', [ + 'principal_id', + 'warehouse_id', + 'delivery_order_code', + 'express_code', + 'package_index', + ], { + unique: true, + name: 'uk_waybill_fetch_idempotency', + }); + await queryInterface.addIndex('waybill_fetch_records', [ + 'principal_id', + 'warehouse_id', + 'delivery_order_code', + 'express_code', + 'package_index', + 'status', + ], { + name: 'idx_waybill_fetch_idempotency_lookup', + }); + }, + + async down(queryInterface) { + await queryInterface.removeIndex('waybill_fetch_records', 'idx_waybill_fetch_idempotency_lookup'); + await queryInterface.dropTable('waybill_fetch_idempotencies'); + await queryInterface.removeColumn('waybill_fetch_records', 'result_data'); + await queryInterface.removeColumn('waybill_fetch_records', 'package_index'); + }, +}; diff --git a/backend/test/app/lib/waybillGet.test.js b/backend/test/app/lib/waybillGet.test.js new file mode 100644 index 0000000..9236c31 --- /dev/null +++ b/backend/test/app/lib/waybillGet.test.js @@ -0,0 +1,274 @@ +'use strict'; + +const { app, assert } = require('egg-mock/bootstrap'); +const mm = require('egg-mock'); +const orderCallback = require('../../../app/lib/orderCallback'); +const waybillGet = require('../../../app/lib/waybillGet'); + +const PRINCIPAL_ID = 5; +const WAREHOUSE_ID = 8; +const DELIVERY_ORDER_CODE = 'dgj-550598429043014280'; + +function makeEntry(data) { + const entry = { + ...data, + update: async values => Object.assign(entry, values), + destroy: async () => {}, + }; + return entry; +} + +function setupContext({ entries = [], legacyRecord = null, waybillCode = 'WB-NEW', fetchError = null } = {}) { + const ctx = app.mockContext(); + const fetchedKeys = []; + const platformRoutes = []; + let platformCalls = 0; + + ctx.model.WaybillFetchIdempotency.findOne = async ({ where }) => + entries.find(entry => Object.keys(where).every(key => entry[key] === where[key])) || null; + ctx.model.WaybillFetchIdempotency.create = async data => { + const duplicate = entries.find(entry => + [ 'principal_id', 'warehouse_id', 'delivery_order_code', 'express_code', 'package_index' ] + .every(key => entry[key] === data[key])); + if (duplicate) throw new Error('unique key conflict'); + const entry = makeEntry(data); + entries.push(entry); + return entry; + }; + ctx.model.WaybillFetchRecord.findOne = async options => { + fetchedKeys.push(options.where); + return legacyRecord; + }; + ctx.model.WaybillFetchRecord.create = async () => {}; + ctx.service.cache.getShopBasic = async () => ({ + id: 10, + principal_id: PRINCIPAL_ID, + type: 2, + external_print_account_id: 12, + }); + ctx.model.Shop.findByPk = async () => ({ + toJSON: () => ({ + id: 10, + principal_id: PRINCIPAL_ID, + type: 2, + external_print_account_id: 12, + }), + }); + ctx.model.ExternalPrintAccount.findOne = async () => ({ + id: 12, + platform: { code: 'TEST_PLATFORM', name: 'Test platform', fetch_waybill_no: 1 }, + get: () => ({ id: 12, platform: { code: 'TEST_PLATFORM', name: 'Test platform' } }), + }); + ctx.service.externalPrintExpressInterface.resolveByCode = async () => ({ + template_id: 'template-1', + get: () => ({ template_id: 'template-1' }), + }); + ctx.service.externalPrintOrder.createPlatformService = account => { + platformRoutes.push(account.platform.code); + return { + needFetchWaybillNo: true, + fetchWaybillNo: async () => { + platformCalls += 1; + if (fetchError) throw fetchError; + return { waybill_code: waybillCode, printinfo: 'print-data' }; + }, + }; + }; + mm(orderCallback, 'resolveDeliveryBill', async () => ({ + isNewModel: false, + order: { + warehouse_id: WAREHOUSE_ID, + status: 1, + source_platform_code: 'KS', + shop_id: 10, + get: () => ({ + warehouse_id: WAREHOUSE_ID, + status: 1, + source_platform_code: 'KS', + shop_id: 10, + }), + }, + })); + return { ctx, entries, fetchedKeys, platformRoutes, get platformCalls() { return platformCalls; } }; +} + +function requestItem(overrides = {}) { + return { + deliveryOrderCode: DELIVERY_ORDER_CODE, + expressCode: 'STO', + packageIndex: 0, + ...overrides, + }; +} + +function requestBody(item) { + return { request: { orders: [ item ], request_id: `request-${Date.now()}` } }; +} + +describe('lib/waybillGet 订单级幂等', () => { + afterEach(() => mm.restore()); + + it('同订单、快递和包裹序号直接重放数据库中的完整结果', async () => { + const savedResult = { + delivery_order_code: DELIVERY_ORDER_CODE, + success: true, + message: 'ok', + express_code: 'STO', + package_index: 0, + waybill_code: 'WB-SAVED', + waybill_codes: [ 'WB-SAVED' ], + printinfo: 'saved-print-data', + key: 'saved-key', + }; + const entry = makeEntry({ + principal_id: PRINCIPAL_ID, + warehouse_id: WAREHOUSE_ID, + delivery_order_code: DELIVERY_ORDER_CODE, + express_code: 'STO', + package_index: 0, + status: 1, + result_data: JSON.stringify(savedResult), + }); + const state = setupContext({ entries: [ entry ] }); + + const result = await waybillGet.getWaybills(state.ctx, { + principalId: PRINCIPAL_ID, + warehouseId: WAREHOUSE_ID, + data: requestBody(requestItem()), + }); + + assert.deepStrictEqual(result.data.results[0], savedResult); + assert.strictEqual(state.platformRoutes.length, 0); + assert.strictEqual(state.fetchedKeys.length, 0); + }); + + it('同一批里的重复订单项只调用一次平台并复用结果', async () => { + const state = setupContext(); + const item = requestItem(); + + const result = await waybillGet.getWaybills(state.ctx, { + principalId: PRINCIPAL_ID, + warehouseId: WAREHOUSE_ID, + data: { request: { orders: [ item, { ...item }] } }, + }); + + assert.strictEqual(result.data.success, 2); + assert.strictEqual(result.data.results[0].waybill_code, 'WB-NEW'); + assert.strictEqual(result.data.results[1].waybill_code, 'WB-NEW'); + assert.strictEqual(state.platformRoutes.length, 1); + }); + + it('相同订单但快递编码不同会按订单当前平台路由重新取号', async () => { + const state = setupContext(); + + const result = await waybillGet.getWaybills(state.ctx, { + principalId: PRINCIPAL_ID, + warehouseId: WAREHOUSE_ID, + data: requestBody(requestItem({ expressCode: 'ZTO' })), + }); + + assert.strictEqual(result.data.results[0].waybill_code, 'WB-NEW'); + assert.strictEqual(state.platformRoutes[0], 'TEST_PLATFORM'); + assert.strictEqual(state.entries[0].express_code, 'ZTO'); + }); + + it('相同订单和快递但包裹序号不同会独立取号', async () => { + const state = setupContext(); + + const result = await waybillGet.getWaybills(state.ctx, { + principalId: PRINCIPAL_ID, + warehouseId: WAREHOUSE_ID, + data: requestBody(requestItem({ packageIndex: 1 })), + }); + + assert.strictEqual(result.data.results[0].package_index, 1); + assert.strictEqual(state.entries[0].package_index, 1); + assert.strictEqual(state.platformRoutes[0], 'TEST_PLATFORM'); + }); + + it('另一请求已有相同订单键正在处理时不重复调用平台', async () => { + const state = setupContext({ + entries: [ makeEntry({ + principal_id: PRINCIPAL_ID, + warehouse_id: WAREHOUSE_ID, + delivery_order_code: DELIVERY_ORDER_CODE, + express_code: 'STO', + package_index: 0, + status: 0, + }) ], + }); + + const result = await waybillGet.getWaybills(state.ctx, { + principalId: PRINCIPAL_ID, + warehouseId: WAREHOUSE_ID, + data: requestBody(requestItem()), + }); + + assert.strictEqual(result.data.results[0].success, false); + assert.match(result.data.results[0].message, /正在处理中/); + assert.strictEqual(state.platformRoutes.length, 0); + }); + + it('并发的不同 request_id 由数据库唯一键仲裁,只执行一次平台取号', async () => { + const state = setupContext(); + const makePayload = requestId => ({ + principalId: PRINCIPAL_ID, + warehouseId: WAREHOUSE_ID, + data: { request: { orders: [ requestItem() ], request_id: requestId } }, + }); + + await Promise.all([ + waybillGet.getWaybills(state.ctx, makePayload('request-a')), + waybillGet.getWaybills(state.ctx, makePayload('request-b')), + ]); + + assert.strictEqual(state.platformCalls, 1); + assert.strictEqual(state.entries.length, 1); + assert.strictEqual(state.entries[0].status, 1); + }); + + it('平台请求超时后标记结果待核实,后续重试不再次消耗面单', async () => { + const state = setupContext({ fetchError: new Error('platform request timeout') }); + const payload = { + principalId: PRINCIPAL_ID, + warehouseId: WAREHOUSE_ID, + data: requestBody(requestItem()), + }; + + const first = await waybillGet.getWaybills(state.ctx, payload); + const second = await waybillGet.getWaybills(state.ctx, payload); + + assert.strictEqual(first.data.results[0].success, false); + assert.match(first.data.results[0].message, /结果暂不确定/); + assert.strictEqual(second.data.results[0].success, false); + assert.match(second.data.results[0].message, /待核实/); + assert.strictEqual(state.platformCalls, 1); + assert.strictEqual(state.entries[0].status, 2); + }); + + it('首次命中旧取号记录时回填幂等结果,不再调用平台', async () => { + const state = setupContext({ + legacyRecord: { + waybill_code: 'WB-LEGACY', + waybill_codes: '["WB-LEGACY"]', + waybill_source: 'express_print', + printinfo: 'legacy-print-data', + signature: 'legacy-signature', + print_history_ids: '[]', + cai_niao_auth_info_id: 123, + platform_code: 'KS', + }, + }); + + const result = await waybillGet.getWaybills(state.ctx, { + principalId: PRINCIPAL_ID, + warehouseId: WAREHOUSE_ID, + data: requestBody(requestItem()), + }); + + assert.strictEqual(result.data.results[0].waybill_code, 'WB-LEGACY'); + assert.strictEqual(result.data.results[0].printinfo, 'legacy-print-data'); + assert.strictEqual(state.platformRoutes.length, 0); + assert.strictEqual(state.entries[0].status, 1); + }); +});