oms/backend/app/service/orderSyncTask.js
liufumingren e1e3bb638f feat(order): 拉单任务、外部发货同步与取号记录
- 拉单任务:新增 order_sync_tasks 异步任务池,按店铺逐店拉取外部打单平台订单,前端轮询进度
- 外部发货同步:配送后把发货结果同步回店管家,提供数量统计与批量重试(externalSendSync)
- 取号:新增 waybill_fetch_records 记录取号过程,外部快递接口补充菜鸟授权信息
- 补齐相关迁移、订单页同步入口/状态展示,并新增对接说明文档

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-04 20:53:35 +08:00

464 lines
16 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');
/** 任务状态:0待处理 1处理中 2已完成 3部分失败 4失败 */
const STATUS = { PENDING: 0, PROCESSING: 1, COMPLETED: 2, PARTIAL: 3, FAILED: 4 };
/** 状态中文(前端直接用,避免枚举漂移) */
const STATUS_LABELS = {
[STATUS.PENDING]: '待处理',
[STATUS.PROCESSING]: '处理中',
[STATUS.COMPLETED]: '已完成',
[STATUS.PARTIAL]: '部分失败',
[STATUS.FAILED]: '失败',
};
/** 拉单范围:当前仅外部打单平台店铺,后续新增来源在此登记 */
const SCOPES = {
external_print: '外部打单平台店铺',
};
/** 回看天数的默认值与上限(0 表示「全部待处理」,不限下单时间) */
const DEFAULT_LOOKBACK_DAYS = 3;
const MAX_LOOKBACK_DAYS = 120;
/** 「全部待处理」的起始时间(早于所有平台订单) */
const ALL_PENDING_START = new Date('2018-01-01T00:00:00+08:00');
/** 处理中的任务超过该时长视为异常中断(进程退出),允许重新认领 */
const STALE_MS = 30 * 60 * 1000;
/** 单任务最多拉取的店铺数(防止误提交拖垮平台) */
const MAX_SHOPS = 200;
/**
* 拉单任务服务
*
* 与导出任务同构:提交只落库,定时任务认领执行;区别是本服务按「店铺」维度推进,
* 逐店调用 externalPrintOrder.syncOrders(与手动/定时拉单完全同一条链路,入库口径一致)。
*/
class OrderSyncTaskService extends Service {
/** @return {Object} 任务状态枚举 */
get STATUS() {
return STATUS;
}
/** @return {Object} 范围枚举 */
get SCOPES() {
return SCOPES;
}
/**
* 按范围解析可拉取的店铺
* @param {string} scope 拉单范围
* @param {number} principalId 主体ID
* @param {Array<number>} [shopIds] 指定店铺ID
* @return {Promise<Array>} 店铺列表
*/
async resolveShops(scope, principalId, shopIds) {
const Op = this.app.Sequelize.Op;
const where = { principal_id: principalId, status: 1 };
if (scope === 'external_print') {
where.type = 2;
where.external_print_account_id = { [Op.ne]: null };
} else {
return [];
}
const ids = (shopIds || []).map(Number).filter(id => Number.isInteger(id) && id > 0);
if (ids.length) where.id = { [Op.in]: ids };
return await this.ctx.model.Shop.findAll({
where,
attributes: [ 'id', 'code', 'name', 'principal_id', 'type', 'external_print_account_id' ],
order: [[ 'id', 'ASC' ]],
limit: MAX_SHOPS,
});
}
/**
* 提交拉单任务:只落一条待处理记录,立即返回任务ID
* @param {Object} payload 提交参数
* @param {Object} payload.scope 拉单范围(默认 external_print)
* @param {number} [payload.lookback_days] 回看天数(0=全部待处理)
* @param {Array<number>} [payload.shop_ids] 指定店铺ID(空=全部)
* @param {number} principalId 主体ID
* @param {number} userId 提交人ID
* @return {Promise<Object>} 任务实例
*/
async submit(payload, principalId, userId) {
const { ctx } = this;
const scope = String(payload.scope || 'external_print').trim();
if (!SCOPES[scope]) {
const err = new Error(`不支持的拉单范围:${scope}`);
err.status = 400;
throw err;
}
// 已有未完成任务时拒绝重复提交:拉单会真实请求平台,重复提交只会互相拖慢
const running = await ctx.model.OrderSyncTask.findOne({
where: { principal_id: principalId, status: { [ ctx.app.Sequelize.Op.in ]: [ STATUS.PENDING, STATUS.PROCESSING ] } },
attributes: [ 'id', 'status' ],
order: [[ 'id', 'DESC' ]],
});
if (running) {
const err = new Error(`已有拉单任务在排队/执行中(任务 #${running.id}),请等待完成后再提交`);
err.status = 409;
throw err;
}
const shops = await this.resolveShops(scope, principalId, payload.shop_ids);
if (!shops.length) {
const err = new Error('没有可拉取的店铺:请先在「外部打单平台」同步商家并开启店铺状态');
err.status = 400;
throw err;
}
const lookbackDays = this.normalizeLookbackDays(payload.lookback_days);
const endTime = new Date();
const startTime = this.resolveStartTime(lookbackDays, endTime);
return await ctx.model.OrderSyncTask.create({
principal_id: principalId,
scope,
status: STATUS.PENDING,
start_time: startTime,
end_time: endTime,
lookback_days: lookbackDays,
shop_ids: shops.map(shop => Number(shop.id)),
total_shops: shops.length,
progress: 0,
items: [],
created_by: userId || null,
});
}
/**
* 归一化回看天数:0 表示「全部待处理」,其余限制在 1~MAX_LOOKBACK_DAYS
* @param {*} value 原始值
* @return {number} 天数
*/
normalizeLookbackDays(value) {
if (value === undefined || value === null || value === '') return DEFAULT_LOOKBACK_DAYS;
const days = Number(value);
if (!Number.isFinite(days) || days < 0) return DEFAULT_LOOKBACK_DAYS;
if (days === 0) return 0;
return Math.min(MAX_LOOKBACK_DAYS, Math.max(1, Math.floor(days)));
}
/**
* 按回看天数计算起始时间
* @param {number} lookbackDays 天数(0=全部待处理)
* @param {Date} endTime 结束时间
* @return {Date} 起始时间
*/
resolveStartTime(lookbackDays, endTime) {
if (lookbackDays === 0) return ALL_PENDING_START;
return new Date(endTime.getTime() - lookbackDays * 24 * 3600 * 1000);
}
/**
* 给任务补中文标签与汇总
* @param {Object} task 任务实例/纯对象
* @return {Object} 带标签的任务
*/
decorate(task) {
const item = task && task.get ? task.get({ plain: true }) : { ...task };
item.status_label = STATUS_LABELS[item.status] || String(item.status);
item.scope_label = SCOPES[item.scope] || item.scope;
const items = Array.isArray(item.items) ? item.items : [];
item.items = items;
item.failed_items = items.filter(row => !row.success);
return item;
}
/**
* 任务进度
* @param {number} id 任务ID
* @param {number} principalId 主体ID
* @return {Promise<Object|null>} 任务,不存在或跨主体为 null
*/
async progress(id, principalId) {
const task = await this.ctx.model.OrderSyncTask.findOne({
where: { id, principal_id: principalId },
});
return task ? this.decorate(task) : null;
}
/**
* 任务列表
* @param {number} principalId 主体ID
* @param {Object} opts 查询参数
* @param {number} opts.page 页码
* @param {number} opts.pageSize 每页条数
* @param {number} [opts.status] 状态筛选
* @param {string} [opts.scope] 范围筛选
* @return {Promise<{list: Array, total: number}>} 列表与总数
*/
async list(principalId, { page, pageSize, status, scope }) {
const where = { principal_id: principalId };
if (status !== undefined && status !== null && status !== '') where.status = Number(status);
if (scope) where.scope = String(scope).trim();
const { count, rows } = await this.ctx.model.OrderSyncTask.findAndCountAll({
where,
offset: (Number(page) - 1) * Number(pageSize),
limit: Number(pageSize),
// 列表不返回逐店明细,避免大任务把列表拖慢(明细看进度接口)
attributes: { exclude: [ 'items' ] },
order: [[ 'id', 'DESC' ]],
});
return { list: rows.map(row => this.decorate(row)), total: count };
}
/**
* 当前是否有排队/执行中的任务(前端进入页面时用于恢复进度条)
* @param {number} principalId 主体ID
* @return {Promise<Object|null>} 最新未完成任务
*/
async runningTask(principalId) {
const task = await this.ctx.model.OrderSyncTask.findOne({
where: {
principal_id: principalId,
status: { [ this.app.Sequelize.Op.in ]: [ STATUS.PENDING, STATUS.PROCESSING ] },
},
order: [[ 'id', 'DESC' ]],
});
return task ? this.decorate(task) : null;
}
/**
* 认领并执行一条任务(行锁保证集群下同一任务只被一个 worker 执行)
* @return {Promise<void>} 无返回值
*/
async processPending() {
const ctx = this.ctx;
const Model = ctx.model.OrderSyncTask;
const Op = this.app.Sequelize.Op;
// 先回收异常中断的任务(进程退出导致长期停在处理中):独立提交,避免被后续 rollback 抹掉
try {
const stale = new Date(Date.now() - STALE_MS);
await Model.update(
{ status: STATUS.PENDING, error_message: '上次执行中断,已重新排队' },
{ where: { status: STATUS.PROCESSING, updated_at: { [Op.lt]: stale } } }
);
} catch (err) {
ctx.logger.warn('[order-sync-worker] 回收中断任务失败:%s', err.message);
}
const transaction = await ctx.model.transaction();
let task = null;
try {
task = await Model.findOne({
where: { status: STATUS.PENDING },
order: [[ 'id', 'ASC' ]],
lock: true,
transaction,
});
if (!task) {
await transaction.rollback();
return;
}
task.status = STATUS.PROCESSING;
task.started_at = new Date();
await task.save({ transaction });
await transaction.commit();
} catch (err) {
await transaction.rollback().catch(() => {});
ctx.logger.error('[order-sync-worker] 认领任务失败', err);
return;
}
try {
await this.run(task);
} catch (err) {
ctx.logger.error(`[order-sync-worker] 任务失败 id=${task.id}`, err);
}
}
/**
* 执行任务:逐店拉单并实时写回进度
* @param {Object} task 任务实例
* @return {Promise<void>} 无返回值
*/
async run(task) {
const { ctx } = this;
const Model = ctx.model.OrderSyncTask;
let shops = [];
try {
shops = await this.resolveShops(task.scope, task.principal_id, task.shop_ids || []);
} catch (err) {
await Model.update(
{ status: STATUS.FAILED, error_message: truncate(err.message, 500), finished_at: new Date(), progress: 100 },
{ where: { id: task.id } }
);
return;
}
if (!shops.length) {
await Model.update(
{ status: STATUS.FAILED, error_message: '没有可拉取的店铺(店铺可能已被删除或停用)', finished_at: new Date(), progress: 100 },
{ where: { id: task.id } }
);
return;
}
// 店铺数可能因期间停用而变化,按实际可拉取数量校正
await Model.update({ total_shops: shops.length }, { where: { id: task.id } });
const accounts = await this.loadAccounts(shops);
const items = [];
const summary = { processed: 0, failed: 0, created: 0, updated: 0, skipped: 0, voided: 0, voidedShipped: 0, voidedMissing: 0 };
for (const shop of shops) {
const item = await this.runShop(shop, accounts, task);
items.push(item);
summary.processed += 1;
if (!item.success) summary.failed += 1;
summary.created += item.created || 0;
summary.updated += item.updated || 0;
summary.skipped += item.skipped || 0;
summary.voided += item.voided || 0;
summary.voidedShipped += item.voided_shipped || 0;
summary.voidedMissing += item.voided_missing || 0;
const total = shops.length;
await Model.update(
{
processed_shops: summary.processed,
failed_shops: summary.failed,
created_orders: summary.created,
updated_orders: summary.updated,
skipped_orders: summary.skipped,
voided_orders: summary.voided,
voided_shipped_orders: summary.voidedShipped,
voided_missing_orders: summary.voidedMissing,
progress: Math.min(99, Math.floor(summary.processed / total * 100)),
items,
},
{ where: { id: task.id } }
);
}
const finalStatus = summary.failed === 0
? STATUS.COMPLETED
: (summary.failed === shops.length ? STATUS.FAILED : STATUS.PARTIAL);
await Model.update(
{
status: finalStatus,
progress: 100,
processed_shops: summary.processed,
failed_shops: summary.failed,
created_orders: summary.created,
updated_orders: summary.updated,
skipped_orders: summary.skipped,
voided_orders: summary.voided,
voided_shipped_orders: summary.voidedShipped,
voided_missing_orders: summary.voidedMissing,
items,
finished_at: new Date(),
},
{ where: { id: task.id } }
);
ctx.logger.info(
`[order-sync-worker] 任务完成 id=${task.id} 店铺 ${summary.processed}(失败 ${summary.failed})` +
` 新增 ${summary.created} 更新 ${summary.updated} 跳过 ${summary.skipped}` +
` 作废 ${summary.voided}(已发货 ${summary.voidedShipped}、查不到 ${summary.voidedMissing})`
);
}
/**
* 预加载店铺关联的打单账号(含平台配置),避免逐店重复查询
* @param {Array} shops 店铺列表
* @return {Promise<Map<number, Object>>} 账号ID → 账号实例
*/
async loadAccounts(shops) {
const { ctx } = this;
const accountIds = Array.from(new Set(
shops.map(shop => Number(shop.external_print_account_id)).filter(id => Number.isInteger(id) && id > 0)
));
if (!accountIds.length) return new Map();
const accounts = await ctx.model.ExternalPrintAccount.findAll({
where: { id: { [ ctx.app.Sequelize.Op.in ]: accountIds } },
include: [
{
model: ctx.model.ExternalPrintPlatform,
as: 'platform',
attributes: [ 'id', 'code', 'name', 'url', 'fetch_waybill_no' ],
},
],
});
return new Map(accounts.map(account => [ Number(account.id), account ]));
}
/**
* 拉取单个店铺(失败只记录,不中断整批)
* @param {Object} shop 店铺实例
* @param {Map<number, Object>} accounts 账号映射
* @param {Object} task 任务实例
* @return {Promise<Object>} 该店铺结果
*/
async runShop(shop, accounts, task) {
const { ctx } = this;
const base = {
shop_id: Number(shop.id),
shop_code: shop.code,
shop_name: shop.name,
account_id: Number(shop.external_print_account_id) || null,
start_time: task.start_time,
end_time: task.end_time,
};
const account = accounts.get(Number(shop.external_print_account_id));
if (!account) {
const message = '店铺关联的打单账号不存在';
await ctx.service.externalPrintOrder.markShopSynced(shop, new Date(), `拉单失败:${message}`);
return { ...base, success: false, message };
}
try {
const result = await ctx.service.externalPrintOrder.syncOrders(shop, account, {
startTime: new Date(task.start_time),
endTime: new Date(task.end_time),
});
const message = `拉取成功:${result.orders} 单(新增 ${result.created},更新 ${result.updated})` +
`,跳过平台已发货 ${result.skipped || 0} 单,自动作废 ${result.voided || 0} 单` +
(result.voidedMissing ? `(其中平台已查不到 ${result.voidedMissing} 单)` : '');
await ctx.service.externalPrintOrder.markShopSynced(shop, new Date(), message);
return {
...base,
success: true,
message,
orders: result.orders || 0,
created: result.created || 0,
updated: result.updated || 0,
skipped: result.skipped || 0,
voided: result.voided || 0,
voided_shipped: result.voidedShipped || 0,
voided_missing: result.voidedMissing || 0,
items: result.items || 0,
};
} catch (err) {
const message = `拉取失败:${err.message}`;
await ctx.service.externalPrintOrder.markShopSynced(shop, new Date(), message).catch(() => {});
ctx.logger.warn(`[order-sync-worker] 店铺 ${shop.id} 拉单失败:${err.message}`);
return { ...base, success: false, message: err.message };
}
}
}
/**
* 截断文本
* @param {string} value 文本
* @param {number} max 最大长度
* @return {string} 截断后的文本
*/
function truncate(value, max) {
const text = String(value == null ? '' : value);
return text.length > max ? text.slice(0, max) : text;
}
module.exports = OrderSyncTaskService;