修复取号回调的订单级幂等与重放
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
parent
20b017c1b6
commit
4c2cfe1793
@ -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 参数
|
||||
|
||||
@ -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,
|
||||
|
||||
30
backend/app/model/waybillFetchIdempotency.js
Normal file
30
backend/app/model/waybillFetchIdempotency.js
Normal 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;
|
||||
};
|
||||
@ -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: {
|
||||
|
||||
@ -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');
|
||||
},
|
||||
};
|
||||
274
backend/test/app/lib/waybillGet.test.js
Normal file
274
backend/test/app/lib/waybillGet.test.js
Normal 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);
|
||||
});
|
||||
});
|
||||
Loading…
x
Reference in New Issue
Block a user