oms/backend/app/service/externalSendSync.js
liufumingren da468f6cb2 fix(send): 取号记录必须与本单运单号匹配,不再取最近一条
上一版按「最近一次成功取号记录」取快递编码与面单标识,但同一单可能取过多次号
(每次分配新号,本地库里 dgj-10000267890142_1 就有 4 条不同运单号的记录)。
随便取一条会让发货模板(快递)和 WaybillCodes 面单标识与真正发出的运单号错位,
甚至把别的运单号发到平台。

- externalSendSync.findLatestFetchRecord:按配送单的运单号
  (express_codes / express_code)逐条匹配取号记录的 waybill_code / waybill_codes,
  主运单优先;运单号对不上返回 null 并 warn,报文宁可不带面单标识也不拿别人的;
  订单号 LIKE 前缀匹配转义下划线,避免 `..._1` 误匹配 `..._10`
- dgjSendRow:新增 parseOrderWaybills / parseFetchWaybills;
  pickWaybillFromFetchRecord(raw, waybills) 只取与订单运单号一致的那张;
  buildSendRow 的 WaybillCodes 只保留本单运单号,LastWaybillCode 以本单运单号为准
- 单测:dgjSendRow 补 3 例(按号选面单 / 对不上不回填 / 运单号清单解析),
  externalSendTemplate 补 3 例(按号挑记录 / 无匹配返回 null / 多包裹主运单优先)
- 文档补匹配口径与实测表

真实库实测:配送单运单 772085332374413 → 记录 #14;改成 772085215446719 → 记录 #13
(不再取最新那条);改成不存在的号 → null + warn。

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-07 09:22:16 +08:00

598 lines
24 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

'use strict';
const Service = require('egg').Service;
const { buildSendRow, parseOrderWaybills, parseJson } = require('../lib/dgjSendRow');
/** 外部发货同步状态 */
const SEND_STATUS = {
PENDING: 0,
SYNCED: 1,
RETRY: 2,
EXCEPTION: 3,
};
/** 状态文案 */
const SEND_STATUS_LABELS = {
0: '待同步',
1: '已同步',
2: '同步失败待重试',
3: '同步异常',
};
/** 失败重试上限:达到后流转为「异常」,等人工批量重试 */
const MAX_SEND_TIMES = 3;
/**
* 同批逐单同步的间隔(毫秒)
*
* 店管家对高频请求会判成刷单/攻击,批量回传时逐单之间留一点间隔;
* 现在发货不再回读订单行(用本地快照拼报文),每单只有 1 次 POST。
*/
const SEND_INTERVAL_MS = Number(process.env.EXTERNAL_SEND_INTERVAL_MS || 300);
/**
* 简单等待
* @param {number} ms 毫秒
* @return {Promise<void>} 无返回值
*/
function sleep(ms) {
return new Promise(resolve => setTimeout(resolve, ms));
}
/**
* 截断字符串,避免超出表字段长度
* @param {*} value 原始值
* @param {number} max 最大长度
* @return {string} 截断后的字符串
*/
function truncateText(value, max) {
return String(value == null ? '' : value).slice(0, max);
}
/**
* 转义 LIKE 里的通配符(订单号可能含 `_`,如 `FH_2_1`)
* @param {string} value 原始值
* @return {string} 转义后的值
*/
function escapeLike(value) {
return String(value == null ? '' : value).replace(/([\\%_])/g, '\\$1');
}
/**
* 取号记录里是否包含指定运单号
* @param {Object} record 取号记录
* @param {string} waybill 运单号
* @return {boolean} 是否命中
*/
function fetchRecordHasWaybill(record, waybill) {
const wanted = String(waybill == null ? '' : waybill).trim();
if (!wanted || !record) return false;
if (String(record.waybill_code || '').trim() === wanted) return true;
const raw = record.waybill_codes;
const parsed = parseJson(raw);
const codes = Array.isArray(parsed) ? parsed : (raw ? String(raw).split(',') : []);
return codes.some(code => String(code).trim() === wanted);
}
/**
* 是否为平台登录态失效类错误(分区接口统一返回「登录信息过期,请重新登录」)
* @param {Error} err 异常
* @return {boolean} 是否需要重新登录
*/
function isSessionExpiredError(err) {
const message = String((err && err.message) || '');
return /登录信息过期|登录已失效|token is invalid|未登录|缺少 token/i.test(message);
}
/**
* 同步外部打单平台发货(店管家 `NewOrder/OnlineSendBatch`)
*
* 触发链路:
* - WMS 回传 `deliveryorder.confirm` → 订单流转到「配送」时把状态置为「待同步」(`markPending`);
* - 定时任务 `externalSendSyncWorker` 扫描「待同步 / 失败待重试」的配送单,逐单调平台发货接口;
* - 失败累加次数,达到 3 次转「异常」;人工在列表里批量重试(`retry`)会把次数清零重新排队。
*/
class ExternalSendSyncService extends Service {
/**
* 订单流转到配送后标记「待同步」
*
* 非外部打单订单(店铺不是 type=2 / 没有打单账号)直接标记为「已同步」,避免污染异常统计。
* @param {number[]} ids 订单ID(order_index.id)
* @param {number} principalId 主体ID
* @return {Promise<void>} 无返回值
*/
async markPending(ids, principalId) {
const { ctx } = this;
const idList = (Array.isArray(ids) ? ids : [ ids ]).map(Number).filter(Boolean);
if (!idList.length) return;
const Op = ctx.app.Sequelize.Op;
const rows = await ctx.model.OrderStatusDelivery.findAll({
where: { principal_id: principalId, id: { [Op.in]: idList } },
});
for (const row of rows) {
const applicable = await this.isExternalPrintOrder(row);
await row.update(applicable
? { external_send_status: SEND_STATUS.PENDING, external_send_times: 0, external_send_error: '' }
: {
external_send_status: SEND_STATUS.SYNCED,
external_send_times: 0,
external_send_error: '',
external_send_at: new Date(),
external_sent_at: new Date(),
});
}
}
/**
* 是否外部打单平台订单(店铺 type=2 且挂了打单账号)
* @param {Object} order 配送表订单行
* @return {Promise<boolean>} 是否需要同步
*/
async isExternalPrintOrder(order) {
const { ctx } = this;
if (!order || !order.shop_id) return false;
const shop = await ctx.model.Shop.findByPk(order.shop_id, {
attributes: [ 'id', 'type', 'external_print_account_id' ],
});
return !!(shop && Number(shop.type) === 2 && shop.external_print_account_id);
}
/**
* 同步单个订单的发货结果到外部打单平台
* @param {Object} order 配送表订单行(Sequelize 实例)
* @param {Object} [options] 参数
* @param {string} [options.trigger] 触发来源(schedule / manual)
* @return {Promise<{ok: boolean, message: string, skipped?: boolean}>} 同步结果
*/
async syncOrder(order, { trigger = 'schedule' } = {}) {
const { ctx } = this;
const now = new Date();
try {
const target = await this.resolveTarget(order);
if (!target) {
await order.update({
external_send_status: SEND_STATUS.SYNCED,
external_send_error: '',
external_send_at: now,
external_sent_at: now,
});
return { ok: true, skipped: true, message: '非外部打单订单,无需同步' };
}
const { service, platformType, dbname, platformCode, template, fetchRecord } = target;
const host = service.constructor.resolveOrderHost(platformType);
const row = await this.resolveSendRow(order, { service, host, dbname, platformCode, template, fetchRecord });
if (!row) {
throw new Error(`外部打单平台未找到该订单(平台 ${platformCode},系统编号 ${order.parent_order_no || order.order_no})`);
}
await service.sendOrders(host, {
traceId: await this.resolveTraceId(service),
dbname,
rows: [ row ],
templateId: template ? template.template_id : '',
expressCompanyId: template ? template.express_company_id : '',
expressCode: template ? template.express_company_code : '',
});
await order.update({
external_send_status: SEND_STATUS.SYNCED,
external_send_error: '',
external_send_at: now,
external_sent_at: now,
});
ctx.logger.info('[external-send] 同步外部发货成功 %s(%s)', order.order_no, trigger);
return { ok: true, message: 'ok' };
} catch (err) {
// 登录态失效:重新登录后重试一次
if (isSessionExpiredError(err)) {
try {
const target = await this.resolveTarget(order);
if (target) {
await target.service.loginByPassword();
const host = target.service.constructor.resolveOrderHost(target.platformType);
const row = await this.resolveSendRow(order, {
service: target.service,
host,
dbname: target.dbname,
platformCode: target.platformCode,
template: target.template,
fetchRecord: target.fetchRecord,
});
if (!row) throw new Error('外部打单平台未找到该订单');
await target.service.sendOrders(host, {
traceId: await this.resolveTraceId(target.service),
dbname: target.dbname,
rows: [ row ],
templateId: target.template ? target.template.template_id : '',
expressCompanyId: target.template ? target.template.express_company_id : '',
expressCode: target.template ? target.template.express_company_code : '',
});
await order.update({
external_send_status: SEND_STATUS.SYNCED,
external_send_error: '',
external_send_at: now,
external_sent_at: now,
});
ctx.logger.info('[external-send] 重新登录后同步成功 %s', order.order_no);
return { ok: true, message: 'ok' };
}
} catch (retryErr) {
return await this.recordFailure(order, retryErr, now);
}
}
return await this.recordFailure(order, err, now);
}
}
/**
* 组装发货回传用的订单行:优先用本地快照(不访问平台),快照缺失才回读平台
* @param {Object} order 配送状态行
* @param {Object} ctxInfo 上下文
* @param {Object} ctxInfo.service 打单平台服务
* @param {string} ctxInfo.host 订单域名
* @param {string} ctxInfo.dbname 分区库名
* @param {Object} [ctxInfo.template] 快递接口记录
* @param {Object} [ctxInfo.fetchRecord] 最近一次成功取号记录(已在 resolveTarget 查过就不再查)
* @return {Promise<Object|null>} 订单行
*/
async resolveSendRow(order, { service, host, dbname, template, fetchRecord }) {
const { ctx } = this;
const logicalOrderId = String(order.parent_order_no || order.order_no || '');
// 1) 拉单快照:老表 orders.external_data(平台整行,含 PathFlowCode / ShippingType / SubOrders)
let snapshot = null;
try {
const legacy = await ctx.model.Order.findOne({
where: { principal_id: order.principal_id, order_no: order.order_no },
attributes: [ 'id', 'external_data' ],
});
snapshot = legacy && legacy.external_data ? legacy.external_data : null;
} catch {
snapshot = null;
}
// 2) 最近一次成功取号记录:拿最新面单信息(WaybillCodeId / Pid / 快递编码)
if (!fetchRecord) fetchRecord = await this.findLatestFetchRecord(order);
const localRow = buildSendRow({ order, snapshot, fetchRecord, template });
if (localRow) {
// 报文里 WaybillCodes 是平台校验运单渠道的依据(WaybillCodeId / Pid / 快递编码),缺失时要能查到
const waybills = Array.isArray(localRow.WaybillCodes) ? localRow.WaybillCodes : [];
if (!waybills.length) {
ctx.logger.warn(
'[external-send] %s 没有带平台面单标识(取号记录 %s),WaybillCodes 为空,运单号 %s',
order.order_no,
fetchRecord ? `#${fetchRecord.id}` : '缺失',
localRow.LastWaybillCode || order.express_code || '-'
);
}
return localRow;
}
// 3) 没有快照(历史单/非平台单):退回回读平台订单行
ctx.logger.info('[external-send] %s 没有本地快照,回读平台订单行', order.order_no);
return await service.findPlatformOrderRow(host, {
traceId: await this.resolveTraceId(service),
dbname,
logicalOrderId,
platformOrderId: String((order.extend_props && order.extend_props.platform_order_no) || order.oaid_order_source_code || ''),
placeOrderTime: order.place_order_time || order.pay_time || order.created_at,
});
}
/**
* 记录一次失败:累加次数,达到上限转「异常」
* @param {Object} order 配送表订单行
* @param {Error} err 异常
* @param {Date} now 当前时间
* @return {Promise<{ok: boolean, message: string}>} 结果
*/
async recordFailure(order, err, now) {
const { ctx } = this;
const times = Number(order.external_send_times || 0) + 1;
const exception = times >= MAX_SEND_TIMES;
const message = truncateText(err && err.message ? err.message : '同步失败', 500);
await order.update({
external_send_status: exception ? SEND_STATUS.EXCEPTION : SEND_STATUS.RETRY,
external_send_times: times,
external_send_error: message,
external_send_at: now,
});
ctx.logger.warn('[external-send] 同步外部发货失败 %s(第 %d 次%s):%s',
order.order_no, times, exception ? ',转异常' : '', message);
return { ok: false, message };
}
/**
* 定位同步目标(打单账号 / 平台服务 / 分区)
* @param {Object} order 配送表订单行
* @return {Promise<Object|null>} 目标信息;非外部打单订单返回 null
*/
/**
* 最近一次**与本单运单号对得上**的成功取号记录(含运单号、快递编码、平台面单标识)
*
* 同一单可能取过多次号(每次分配新号),配送单上真正发出去的是 `express_codes` 里的号,
* 所以必须按运单号挑记录:拿别的号会让发货模板(快递)和面单标识都错位,
* 抖音这类平台会直接判「此运单号非抖音的运单号」。
*
* @param {Object} order 配送状态行
* @return {Promise<Object|null>} 取号记录;运单号对不上时返回 null
*/
async findLatestFetchRecord(order) {
const { ctx } = this;
if (!order || !order.order_no) return null;
const Op = ctx.app.Sequelize.Op;
const orderCode = String(order.order_no);
let records = [];
try {
records = await ctx.model.WaybillFetchRecord.findAll({
where: {
principal_id: order.principal_id,
status: 1,
// 本单本身 + 本单的拆包(`_1` / `_2`):order_no 里的下划线是字面量,需转义
[Op.or]: [
{ delivery_order_code: orderCode },
{ delivery_order_code: { [Op.like]: `${escapeLike(orderCode)}\\_%` } },
],
},
order: [[ 'id', 'DESC' ]],
limit: 20,
});
} catch {
return null;
}
if (!records.length) return null;
const waybills = parseOrderWaybills(order);
// 配送单还没有运单号(异常数据):保持原有行为,取最近一条
if (!waybills.length) return records[0];
for (const waybill of waybills) {
const hit = records.find(record => fetchRecordHasWaybill(record, waybill));
if (hit) return hit;
}
ctx.logger.warn(
'[external-send] %s 的运单号 %s 没有对应取号记录(最近 %d 条都不是),将不带平台面单标识',
orderCode,
waybills.join(','),
records.length
);
return null;
}
/**
* 定位发货用的快递接口(模板)
*
* 必须按**运单实际所属的快递**取模板:店管家把 TemplateId / ExpressCompanyId 透传给平台,
* 抖音/快手等平台会按模板的电子面单渠道校验运单号,模板与运单快递不一致会被判
* `风控拦截#NOT_MATCH_SEGMENT_CHANNEL#(此运单号非抖音的运单号)`。
* 取号就是按「账号 + 平台 + 快递编码」定位模板(`resolveByCode`),发货沿用同一口径。
*
* @param {Object} params 参数
* @param {Object} params.account 打单账号
* @param {string} params.platformCode OMS 平台编码
* @param {string} params.expressCode 运单实际使用的快递编码(取号记录优先)
* @param {number} params.principalId 主体ID
* @return {Promise<Object|null>} 快递接口记录(纯对象)
*/
async resolveSendTemplate({ account, platformCode, expressCode, principalId }) {
const { ctx } = this;
const code = String(expressCode || '').trim();
if (code && platformCode) {
// 1) 显式绑定关系(OMS 快递编码 → 模板)
const matched = await ctx.service.externalPrintExpressInterface.resolveByCode(
account.id,
{ platformCode, expressCode: code },
principalId
);
if (matched) return matched;
// 2) 没绑 custom_code 的历史数据:按模板自带的快递公司编码兜底匹配(如 STO / YUNDA / POSTB)
const byCompany = await ctx.model.ExternalPrintExpressInterface.findOne({
where: {
principal_id: principalId,
account_id: account.id,
platform_code: platformCode,
status: 1,
express_company_code: code.toUpperCase(),
},
order: [[ 'id', 'ASC' ]],
});
if (byCompany) return byCompany.get ? byCompany.get({ plain: true }) : byCompany;
}
// 3) 兜底(历史单没有取号记录 / 快递未绑定):退回该平台的第一条模板,保持原有行为
const row = await ctx.model.ExternalPrintExpressInterface.findOne({
where: { principal_id: principalId, account_id: account.id, platform_code: platformCode, status: 1 },
order: [[ 'id', 'ASC' ]],
});
if (!row) return null;
const fallback = row.get ? row.get({ plain: true }) : row;
if (code) {
// 运单快递没有对应模板时平台会按模板渠道校验运单号(风控/渠道不匹配),留痕便于排查
ctx.logger.warn(
'[external-send] 平台 %s 快递 %s 未绑定模板,退回 #%s(模板快递 %s)',
platformCode,
code,
fallback.id,
fallback.express_company_code || '-'
);
}
return fallback;
}
/**
* 定位发货目标(打单账号 / 发货域名 / 分区库名 / 快递接口)
* @param {Object} order 配送表订单行
* @return {Promise<Object|null>} 目标信息
*/
async resolveTarget(order) {
const { ctx } = this;
if (!order || !order.shop_id) return null;
const shop = await ctx.model.Shop.findByPk(order.shop_id, {
attributes: [ 'id', 'type', 'external_print_account_id' ],
});
if (!shop || Number(shop.type) !== 2 || !shop.external_print_account_id) return null;
const account = await ctx.model.ExternalPrintAccount.findByPk(shop.external_print_account_id, {
include: [{ model: ctx.model.ExternalPrintPlatform, as: 'platform' }],
});
if (!account || !account.platform) return null;
const platformCode = String(order.source_platform_code || '').trim();
const service = ctx.service.externalPrintOrder.createPlatformService(account);
const resolvePlatformType = service.constructor && service.constructor.resolvePlatformType;
// 运单实际用的快递:以最近一次成功取号记录为准(取号时按 WMS 传入的快递编码定位模板),
// 兜底用订单的物流公司编码;发货模板必须与之对齐,否则平台按模板渠道校验运单号会报风控
const fetchRecord = await this.findLatestFetchRecord(order);
const waybillExpressCode = String((fetchRecord && fetchRecord.express_code) || order.logistics_code || '').trim();
const template = await this.resolveSendTemplate({
account,
platformCode,
expressCode: waybillExpressCode,
principalId: order.principal_id,
});
// PlatformType(决定回传发货用哪个域名)优先按「订单原始平台」:1688 分销单在 OMS 里被换算成
// 抖音小店/淘宝(为了选对模板),但订单行仍在 Alibaba 分区(fxali),按换算后的平台会查错域名
const raw = order.extend_props && typeof order.extend_props === 'object' ? order.extend_props : {};
const originalCode = String(raw.original_platform_code || '').trim();
let platformType = '';
if (originalCode && typeof resolvePlatformType === 'function') {
platformType = resolvePlatformType(originalCode) || '';
}
if (!platformType) {
platformType = template ? template.platform_type : (typeof resolvePlatformType === 'function' ? resolvePlatformType(platformCode) : '');
}
if (!platformType) return null;
return { service, account, platformType, dbname: template ? template.dbname : '', platformCode, template, fetchRecord };
}
/**
* 取平台登录上下文 traceId(失败不阻断)
*
* 同一次批量同步里按账号缓存:`getUserInfo` 本身也是一次平台请求,
* 逐单重复取等于把请求量翻倍,容易被平台判成高频访问。
* @param {Object} service 平台服务实例
* @return {Promise<string>} traceId
*/
async resolveTraceId(service) {
const key = (service.account && service.account.id) || 'default';
if (!this.traceMemo) this.traceMemo = new Map();
if (this.traceMemo.has(key)) return this.traceMemo.get(key);
let traceId = '';
try {
const info = await service.getUserInfo();
traceId = (info.data && info.data.TraceId) || '';
} catch (err) {
traceId = '';
}
this.traceMemo.set(key, traceId);
return traceId;
}
/**
* 扫描并同步待同步 / 可重试的配送单(定时任务入口)
* @param {Object} [options] 参数
* @param {number} [options.limit] 单批上限
* @return {Promise<Object>} 统计结果
*/
async syncPending({ limit = 50 } = {}) {
const { ctx } = this;
const Op = ctx.app.Sequelize.Op;
// 主体停用后不再回传平台
const enabledPrincipalIds = await ctx.service.cache.getEnabledPrincipalIds();
if (!enabledPrincipalIds.length) return { total: 0, success: 0, failed: 0, exception: 0 };
const rows = await ctx.model.OrderStatusDelivery.findAll({
where: {
external_send_status: { [Op.in]: [ SEND_STATUS.PENDING, SEND_STATUS.RETRY ] },
external_send_times: { [Op.lt]: MAX_SEND_TIMES },
principal_id: { [Op.in]: enabledPrincipalIds },
},
order: [[ 'external_send_at', 'ASC' ]],
limit,
});
let success = 0;
let failed = 0;
let exception = 0;
for (let index = 0; index < rows.length; index += 1) {
const row = rows[index];
// 平台对高频请求会判成刷单/攻击:同批逐单之间留间隔(可按 SEND_INTERVAL_MS 调整)
if (index > 0) await sleep(SEND_INTERVAL_MS);
const result = await this.syncOrder(row, { trigger: 'schedule' });
if (result.ok) success += 1;
else if (row.external_send_status === SEND_STATUS.EXCEPTION) exception += 1;
else failed += 1;
}
return { total: rows.length, success, failed, exception };
}
/**
* 各状态数量(前端快速查看异常数量)
* @param {number} principalId 主体ID
* @return {Promise<Object>} { pending, retry, exception, synced, total }
*/
async counts(principalId) {
const { ctx } = this;
const Sequelize = ctx.app.Sequelize;
const rows = await ctx.model.OrderStatusDelivery.findAll({
where: { principal_id: principalId },
attributes: [ 'external_send_status', [ Sequelize.fn('COUNT', Sequelize.col('id')), 'cnt' ]],
group: [ 'external_send_status' ],
raw: true,
});
const result = { pending: 0, retry: 0, exception: 0, synced: 0, total: 0 };
for (const row of rows) {
const count = Number(row.cnt) || 0;
result.total += count;
if (Number(row.external_send_status) === SEND_STATUS.PENDING) result.pending += count;
else if (Number(row.external_send_status) === SEND_STATUS.RETRY) result.retry += count;
else if (Number(row.external_send_status) === SEND_STATUS.EXCEPTION) result.exception += count;
else if (Number(row.external_send_status) === SEND_STATUS.SYNCED) result.synced += count;
}
return result;
}
/**
* 批量重试同步(人工处理异常单)
*
* 把状态重置为「待同步」并把次数清零,随后立刻跑一批,避免等定时任务。
* @param {Object} p 参数
* @param {number[]} [p.ids] 指定订单ID;为空时按状态筛选
* @param {number} [p.principalId] 主体ID
* @param {number[]} [p.statuses] 状态筛选(默认异常 + 待重试)
* @return {Promise<Object>} { reset, result }
*/
async retry({ ids, principalId, statuses = [ SEND_STATUS.EXCEPTION, SEND_STATUS.RETRY ] } = {}) {
const { ctx } = this;
const Op = ctx.app.Sequelize.Op;
const idList = (Array.isArray(ids) ? ids : []).map(Number).filter(Boolean);
const where = { principal_id: principalId };
if (idList.length) where.id = { [Op.in]: idList };
else where.external_send_status = { [Op.in]: statuses };
const rows = await ctx.model.OrderStatusDelivery.findAll({ where });
for (const row of rows) {
await row.update({
external_send_status: SEND_STATUS.PENDING,
external_send_times: 0,
external_send_error: '',
});
}
let success = 0;
let failed = 0;
for (const row of rows) {
const result = await this.syncOrder(row, { trigger: 'manual' });
if (result.ok) success += 1;
else failed += 1;
}
return { reset: rows.length, success, failed };
}
}
module.exports = ExternalSendSyncService;
module.exports.SEND_STATUS = SEND_STATUS;
module.exports.SEND_STATUS_LABELS = SEND_STATUS_LABELS;
module.exports.MAX_SEND_TIMES = MAX_SEND_TIMES;