修复取号回调的订单级幂等与重放

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
liufumingren 2026-11-17 17:16:14 +08:00
parent 20b017c1b6
commit 4c2cfe1793
6 changed files with 678 additions and 25 deletions

View File

@ -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 参数

View File

@ -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<Object|null>} 已有成功记录
*/
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<Object>} 结果项
*/
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<Object>} 逐单结果
*/
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<Object>} 结果项
*/
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,

View File

@ -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;
};

View File

@ -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: {

View File

@ -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');
},
};

View File

@ -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);
});
});