fix(external-print): 拉单只取平台未发货订单,已发货/已终结不再进待审核

问题:店管家 /NewOrder/List 只支持按时间窗查询,不提供发货状态过滤,
原实现仅按 UpFxUserId 归属就整批入库,导致 sended/success/close 的订单
全部堆进「待审核」(实测店铺 19 近 7 天平台返回 385 单,真正待发货只有 11 单)。

- dgj 新增 isOrderFinished():ErpState∈sended/success/close(及各平台等价状态)、
  有 OnlineSendTime、面单 IsSended=true、LogisticStatus>0 任一命中即视为已处理;
  PrintState/ExpressPrintTime 仅表示已打印面单,不作为判定依据
- listOrders 过滤未发货订单,返回 skipped 与 finished 列表
- externalPrintOrder.syncOrders 新增 voidFinishedOrders():本地仍处于待审核、
  平台侧已发货的副本自动作废(写 void_at/void_reason + 操作日志),已审核订单不动
- orderStatus.voidOrder 支持 principalId(定时任务无登录态)
- 手动/自动拉单消息、接口返回、接口契约、前端提示补充「跳过已发货 / 自动作废」统计
- 新增 scripts/cleanup-shipped-pending-orders.js(npm run orders:cleanup-shipped):
  按同一口径清理历史脏单,默认 dry-run,--apply 才删除
- 新增 isOrderFinished 单测(7 项)

已清理历史脏单 103 条(备份见会话 files/backup-shipped-pending-orders.json),
清理后待审核仅剩 2 单真实的平台待发货订单。

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
liufumingren 2026-11-03 04:14:02 +08:00
parent 7f0651ed37
commit a4213bfd0d
12 changed files with 316 additions and 14 deletions

View File

@ -1214,7 +1214,9 @@ module.exports = {
externalPrintShopOrderSyncResult: {
start_time: { type: 'string', description: '本次拉取的下单时间起' },
end_time: { type: 'string', description: '本次拉取的下单时间止' },
orders: { type: 'integer', description: '拉取到的订单数' },
orders: { type: 'integer', description: '拉取到的未发货订单数(平台已发货/已终结的订单不入库)' },
skipped: { type: 'integer', description: '跳过数量:平台侧已发货/已终结、不需要本系统处理的订单' },
voided: { type: 'integer', description: '自动作废数量:本地待审核、平台侧已发货的订单' },
created: { type: 'integer', description: '新增订单数' },
updated: { type: 'integer', description: '更新订单数' },
items: { type: 'integer', description: '写入的订单明细数' },

View File

@ -714,7 +714,11 @@ class ExternalPrintAccountController extends Controller {
return;
}
await ctx.service.externalPrintOrder.markShopSynced(shop, new Date(), `手动拉取成功:${saved.orders} 单`);
await ctx.service.externalPrintOrder.markShopSynced(
shop,
new Date(),
`手动拉取成功:${saved.orders} 单,跳过平台已发货 ${saved.skipped || 0} 单,自动作废 ${saved.voided || 0} 单`
);
ctx.body = {
code: 0,
message: 'success',
@ -722,6 +726,8 @@ class ExternalPrintAccountController extends Controller {
start_time: saved.startTime,
end_time: saved.endTime,
orders: saved.orders,
skipped: saved.skipped || 0,
voided: saved.voided || 0,
created: saved.created,
updated: saved.updated,
items: saved.items,

View File

@ -174,8 +174,10 @@ class PrintPlatformService {
/**
* 拉取店铺订单(含明细),由各平台实现。
* 必须是「仍需要本系统处理」的订单:平台侧已发货 / 已终结(完成、关闭、退款完成…)的订单要过滤掉,
* 否则会写进待审核形成脏单。被过滤掉的订单号通过 finished 返回,上层据此作废本地未处理的副本。
* 需返回统一结构,避免上层直接依赖各平台字段:
* { total, hosts: [命中来源], list: [{
* { total, hosts: [命中来源], skipped, finished: [{ external_order_id, platform_status }], list: [{
* external_order_id, external_shop_id, external_shop_name, platform_type, platform_status,
* order_no, total_amount, pay_amount, receiver, remark,
* external_created_at, external_updated_at, raw,
@ -185,7 +187,7 @@ class PrintPlatformService {
* 明细只保留平台商品快照,系统商品匹配由上层依据店铺商品绑定关系完成。
* @param {Object} shop OMS 店铺记录(type=2,external_data 为平台返回的商家原始结构)
* @param {Object} [options] 查询参数(startTime / endTime)
* @return {Promise<{total: number, list: Array, hosts: Array}>} 订单列表
* @return {Promise<{total: number, list: Array, hosts: Array, skipped: number, finished: Array}>} 订单列表
*/
async listOrders(shop, options) { // eslint-disable-line no-unused-vars
throw new Error(`外部打单平台 ${this.platformName} 未实现 listOrders()`);

View File

@ -56,6 +56,45 @@ const FALLBACK_PRODUCT_HOSTS = [
/** 商品列表单页条数(平台允许 200) */
const PRODUCT_PAGE_SIZE = 200;
/**
* 平台侧「已发货 / 已终结」的订单状态(ErpState):
* sended=已发货、success=交易成功、close=交易关闭,其余为各平台交易状态的等价写法。
* 这些订单平台已自行处理完毕,不需要进本系统的待审核,拉取时直接跳过。
*/
const FINISHED_ORDER_STATES = [
'sended',
'sendsuccess',
'success',
'tradeclosed',
'close',
'closed',
'finished',
'delivered',
'refundsuccess',
'refunded',
];
/**
* 订单是否已在平台侧发货或已终结(不需要本系统再处理)。
* 判断依据(任一命中即为已处理):
* - ErpState 属于已发货/已终结状态
* - 有 OnlineSendTime(平台发货时间)
* - 面单里存在 IsSended=true 的包裹
* - LogisticStatus > 0(已进入物流流程)
* 注意:PrintState / ExpressPrintTime 只表示面单已打印,未发货的订单仍需要处理,故不作为判定依据。
* @param {Object} row 店管家订单原始结构
* @return {boolean} 是否已发货/已终结
*/
function isOrderFinished(row) {
const data = row || {};
const state = String(data.ErpState || data.Status || '').trim().toLowerCase();
if (state && FINISHED_ORDER_STATES.includes(state)) return true;
if (String(data.OnlineSendTime || '').trim()) return true;
const waybills = Array.isArray(data.WaybillCodes) ? data.WaybillCodes : [];
if (waybills.some(code => code && code.IsSended === true)) return true;
return Number(data.LogisticStatus) > 0;
}
/**
* 商品状态是否为在售:平台不同分区返回的状态值不统一(published / 1 / db_del / jdp_delete 等)
* @param {string|number|null} status 平台商品状态
@ -856,14 +895,17 @@ class DgjService extends PrintPlatformService {
}
/**
* 拉取店铺订单(按商家 FxUserId 过滤)。
* 拉取店铺订单(按商家 FxUserId 过滤,只返回仍需本系统处理的未发货订单)。
* 店管家订单列表不提供商家维度的过滤参数(UpFxUserId 过滤会返回服务器繁忙),
* 因此按时间窗 + 分区域名拉取全量后,在本地按订单的 UpFxUserId 归属到店铺。
* 也不提供发货状态过滤,因此按时间窗 + 分区域名拉取全量后,在本地做两步过滤:
* 1. 按订单的 UpFxUserId 归属到店铺
* 2. 丢弃平台侧已发货/已终结的订单(见 isOrderFinished),只留未发货的
* 被丢弃的订单号会通过 finished 返回,供上层把本地仍处于待审核的副本作废。
* @param {Object} shop OMS 店铺记录(type=2,external_data 为商家原始结构)
* @param {Object} [options] 查询参数
* @param {Date|string} [options.startTime] 平台下单时间起(含)
* @param {Date|string} [options.endTime] 平台下单时间止(含)
* @return {Promise<{total: number, list: Array, hosts: Array}>} 订单列表
* @return {Promise<{total: number, list: Array, hosts: Array, skipped: number, finished: Array}>} 订单列表
*/
async listOrders(shop, options = {}) {
if (!this.token || !this.cookie) {
@ -889,6 +931,7 @@ class DgjService extends PrintPlatformService {
}
const orders = new Map();
const finished = new Map();
const hitHosts = [];
for (const host of hosts) {
const areas = await this.listProductAreas(host);
@ -904,12 +947,27 @@ class DgjService extends PrintPlatformService {
// 订单列表按账号维度返回,这里只保留当前商家的订单
if (String(row.UpFxUserId || '') !== merchantFxUserId) continue;
const order = this.normalizeOrder(row);
if (order.external_order_id) orders.set(order.external_order_id, order);
if (!order.external_order_id) continue;
// 平台已发货/已终结:不进待审核,只登记给上层用于作废本地未处理的副本
if (isOrderFinished(row)) {
finished.set(order.external_order_id, {
external_order_id: order.external_order_id,
platform_status: order.platform_status,
});
continue;
}
orders.set(order.external_order_id, order);
}
}
}
return { total: orders.size, list: Array.from(orders.values()), hosts: hitHosts };
return {
total: orders.size,
list: Array.from(orders.values()),
hosts: hitHosts,
skipped: finished.size,
finished: Array.from(finished.values()),
};
}
/**
@ -1244,6 +1302,15 @@ class DgjService extends PrintPlatformService {
async fetchWaybillNo() {
throw new Error('店管家不回平台取号(fetch_waybill_no=0),不应调用 fetchWaybillNo()');
}
/**
* 订单是否已在平台侧发货或已终结(供脚本/上层按落库的平台原始结构复用同一口径)
* @param {Object} row 店管家订单原始结构
* @return {boolean} 是否已发货/已终结
*/
static isOrderFinished(row) {
return isOrderFinished(row);
}
}
module.exports = DgjService;

View File

@ -88,11 +88,12 @@ module.exports = {
await ctx.service.externalPrintOrder.markShopSynced(
shop,
now,
`自动拉取成功:${result.orders} 单(新增 ${result.created},更新 ${result.updated}),明细 ${result.items} 条`
`自动拉取成功:${result.orders} 单(新增 ${result.created},更新 ${result.updated}),明细 ${result.items} 条` +
`,跳过平台已发货 ${result.skipped || 0} 单,自动作废 ${result.voided || 0} 单`
);
fetched++;
ctx.logger.info(
`[external-order-fetch] 店铺 ${shop.id} 拉单成功:订单 ${result.orders},明细 ${result.items}`
`[external-order-fetch] 店铺 ${shop.id} 拉单成功:订单 ${result.orders},明细 ${result.items},跳过已发货 ${result.skipped || 0},作废 ${result.voided || 0}`
);
} catch (err) {
await ctx.service.externalPrintOrder.markShopSynced(shop, now, `自动拉取失败:${err.message}`);

View File

@ -96,10 +96,14 @@ class ExternalPrintOrderService extends Service {
});
const saved = await this.saveOrders(shop, account, result.list);
// 平台侧已发货/已终结、但本地仍停留在待审核的副本:自动作废,避免脏单积压在待审核
const voided = await this.voidFinishedOrders(shop, result.finished || []);
return {
startTime,
endTime,
orders: result.total,
skipped: result.skipped || 0,
voided,
created: saved.created,
updated: saved.updated,
items: saved.items,
@ -109,6 +113,67 @@ class ExternalPrintOrderService extends Service {
};
}
/**
* 作废本地仍处于「待审核」、但平台侧已发货/已终结的订单。
* 已审核(待推送/委外中/…)的订单不受影响:那些订单的库存与仓库动作已经发生,交由人工处理。
* @param {Object} shop 店铺实例
* @param {Array<{external_order_id: string, platform_status: string}>} finished 平台侧已处理的订单
* @return {Promise<number>} 作废数量
*/
async voidFinishedOrders(shop, finished) {
const { ctx } = this;
const Op = this.app.Sequelize.Op;
const list = (finished || []).filter(item => item && item.external_order_id);
if (!list.length) return 0;
const statusMap = new Map(list.map(item => [ String(item.external_order_id), item.platform_status || null ]));
const indexRows = await ctx.model.OrderIndex.findAll({
where: {
principal_id: shop.principal_id,
parent_order_no: { [Op.in]: Array.from(statusMap.keys()) },
current_status: ORDER_STATUS.PENDING,
},
attributes: [ 'id', 'order_no', 'parent_order_no' ],
raw: true,
});
if (!indexRows.length) return 0;
// 先刷新订单头里的平台状态,作废后仍能看到平台侧最终状态
for (const row of indexRows) {
await ctx.model.Order.update(
{ platform_status: statusMap.get(String(row.parent_order_no)) || null, synced_at: new Date() },
{ where: { principal_id: shop.principal_id, order_no: row.order_no } }
);
}
const reason = '平台侧已发货或已终结,系统自动作废';
let result;
try {
result = await ctx.service.orderStatus.voidOrder({
ids: indexRows.map(row => Number(row.id)),
void_reason: reason,
principalId: shop.principal_id,
});
} catch (err) {
this.ctx.logger.warn('[externalPrintOrder] 自动作废平台已发货订单失败:%s', err.message);
return 0;
}
await ctx.service.operationLog.recordMany(
indexRows.map(row => ({
principalId: shop.principal_id,
targetType: 'order',
targetId: Number(row.id),
action: 'void',
title: `平台已发货自动作废:${row.order_no}`,
detail: { reason, platform_status: statusMap.get(String(row.parent_order_no)) || null, shop_id: shop.id },
})),
{ source: 'sync' }
);
return result.count || indexRows.length;
}
/**
* 写入平台订单与明细(按 order_no 去重,明细按 external_item_id 去重)
* @param {Object} shop 店铺实例

View File

@ -1126,7 +1126,7 @@ class OrderStatusService extends Service {
* 作废:待审核 / 异常 / 待推送 → 已作废(记录作废人 / 时间 / 原因,释放锁定库存)
*
* 与老发货单口径一致:作废针对尚未递交仓库成功的单据;已推送成功的(委外中)请用「取消」
* @param {Object} p { ids, void_reason, remark }
* @param {Object} p { ids, void_reason, remark, principalId }
* @return {Promise<Object>} 流转结果
*/
async voidOrder(p = {}) {
@ -1144,6 +1144,8 @@ class OrderStatusService extends Service {
void_reason: reason,
},
beforeMove: this._releaseStockHook('订单作废释放锁定库存'),
// 无登录态的内部任务(如平台已发货自动作废)需显式传主体
principalId: p.principalId,
});
}

View File

@ -19,6 +19,7 @@
"swagger:export": "node scripts/export-swagger.js",
"order-items:rebuild": "node scripts/rebuild-order-items.js",
"order-index:repair": "node scripts/repair-order-index.js",
"orders:cleanup-shipped": "node scripts/cleanup-shipped-pending-orders.js",
"deploy": "npm run deploy:prod",
"deploy:prod": "npm --prefix ../tools run deploy --",
"deploy:backend": "npm --prefix ../tools run deploy:backend --",

View File

@ -0,0 +1,106 @@
'use strict';
/**
* 清理「平台侧已发货/已终结、但本地仍停留在待审核」的外部打单平台订单。
*
* 背景:早期拉单只按时间窗 + 商家归属过滤,没有看平台发货状态,
* 把 sended(已发货)/ success(交易成功)/ close(已关闭)的订单也写进了待审核。
* 现在拉单已按 isOrderFinished 过滤,本脚本用于清理历史遗留的脏单。
*
* 判定口径与 app/lib/printPlatform/dgj.js 的 isOrderFinished 完全一致(直接复用该函数),
* 只处理 current_status = pending 的订单:已审核流转过的订单涉及库存与仓库动作,不在本脚本范围。
*
* 用法:
* node scripts/cleanup-shipped-pending-orders.js # 只统计(dry-run)
* node scripts/cleanup-shipped-pending-orders.js --apply # 真正删除
* node scripts/cleanup-shipped-pending-orders.js --apply --principal 5
*/
const mm = require('egg-mock');
const DgjService = require('../app/lib/printPlatform/dgj');
(async () => {
const apply = process.argv.includes('--apply');
const principalIndex = process.argv.indexOf('--principal');
const principalId = principalIndex > 0 ? Number(process.argv[principalIndex + 1]) : null;
const app = mm.app();
await app.ready();
const ctx = app.mockContext();
const where = { current_status: 'pending' };
if (principalId) where.principal_id = principalId;
const indexRows = await ctx.model.OrderIndex.findAll({
where,
attributes: [ 'id', 'order_no', 'parent_order_no', 'principal_id' ],
raw: true,
});
console.log(`待审核订单 ${indexRows.length} 条,开始按平台原始结构判定…`);
const targets = [];
for (const row of indexRows) {
const order = await ctx.model.Order.findOne({
where: { principal_id: row.principal_id, external_order_id: row.parent_order_no },
attributes: [ 'id', 'order_no', 'external_data', 'platform_status' ],
raw: true,
});
if (!order) continue;
const raw = typeof order.external_data === 'string'
? safeJson(order.external_data)
: (order.external_data || {});
if (!DgjService.isOrderFinished(raw)) continue;
targets.push({
index_id: Number(row.id),
order_id: Number(order.id),
principal_id: Number(row.principal_id),
order_no: row.order_no,
platform_status: order.platform_status || raw.ErpState || raw.Status || '',
});
}
for (const item of targets) {
console.log(` ${item.order_no} 主体 ${item.principal_id} 平台状态 ${item.platform_status}`);
}
console.log(`命中「平台已发货/已终结但仍在待审核」${targets.length} 条`);
if (!targets.length || !apply) {
if (targets.length) console.log('[dry-run] 未写库,确认后加 --apply 执行删除');
await app.close();
process.exit(0);
}
const transaction = await ctx.model.transaction();
try {
const ids = targets.map(item => item.index_id);
const orderIds = targets.map(item => item.order_id);
await ctx.model.OrderStatusItem.destroy({ where: { order_id: ids }, transaction });
await ctx.model.OrderStatusPending.destroy({ where: { id: ids }, transaction });
await ctx.model.OrderIndex.destroy({ where: { id: ids }, transaction });
await ctx.model.Order.destroy({ where: { id: orderIds }, transaction });
await transaction.commit();
} catch (err) {
await transaction.rollback();
console.error(`清理失败,已回滚:${err.message}`);
await app.close();
process.exit(1);
}
console.log(`已删除 ${targets.length} 条待审核脏单(含明细与索引)`);
await app.close();
process.exit(0);
})().catch(err => {
console.error(err);
process.exit(1);
});
/**
* 宽松解析 JSON:脏数据解析失败时返回空对象(视为未发货,避免误删)
* @param {string} text JSON 文本
* @return {Object} 解析结果
*/
function safeJson(text) {
try {
return JSON.parse(text) || {};
} catch {
return {};
}
}

View File

@ -0,0 +1,45 @@
'use strict';
const { assert } = require('egg-mock/bootstrap');
const DgjService = require('../../../app/lib/printPlatform/dgj');
describe('printPlatform/dgj isOrderFinished', () => {
const base = { ErpState: 'waitsellersend', PrintState: 0, LogisticStatus: 0, WaybillCodes: [] };
it('ErpState 为 sended / success / close 时判定为已处理', () => {
for (const state of [ 'sended', 'success', 'close', 'SENDED', 'Closed' ]) {
assert.strictEqual(DgjService.isOrderFinished({ ...base, ErpState: state }), true, state);
}
});
it('待发货且没有任何发货证据时保留(需要处理)', () => {
assert.strictEqual(DgjService.isOrderFinished(base), false);
});
it('有 OnlineSendTime 时判定为已发货', () => {
assert.strictEqual(DgjService.isOrderFinished({ ...base, OnlineSendTime: '2026-11-02 10:00:00' }), true);
});
it('面单包裹 IsSended=true 时判定为已发货', () => {
assert.strictEqual(
DgjService.isOrderFinished({ ...base, WaybillCodes: [{ WaybillCode: '770', IsSended: false }, { WaybillCode: '771', IsSended: true }] }),
true
);
});
it('LogisticStatus > 0 时判定为已发货', () => {
assert.strictEqual(DgjService.isOrderFinished({ ...base, LogisticStatus: 2 }), true);
});
it('只打印了面单、未发货(PrintState=1 且有 ExpressPrintTime)时仍需要处理', () => {
assert.strictEqual(
DgjService.isOrderFinished({ ...base, PrintState: 1, ExpressPrintTime: '2026-11-02 10:00:00' }),
false
);
});
it('状态字段缺失时不误判', () => {
assert.strictEqual(DgjService.isOrderFinished({}), false);
assert.strictEqual(DgjService.isOrderFinished(null), false);
});
});

View File

@ -191,6 +191,10 @@ export interface SyncShopOrdersResult {
start_time: string
end_time: string
orders: number
/** 跳过数量:平台侧已发货/已终结,不需要本系统处理的订单 */
skipped: number
/** 自动作废数量:本地待审核、平台侧已发货的订单 */
voided: number
created: number
updated: number
items: number

View File

@ -217,7 +217,8 @@ async function submitFetchOrder() {
days: fetchOrderForm.days,
})
ElMessage.success(
`拉取完成:${res.orders} 单(新增 ${res.created},更新 ${res.updated}),明细 ${res.items} 条`,
`拉取完成:未发货 ${res.orders} 单(新增 ${res.created},更新 ${res.updated}),明细 ${res.items} 条` +
`${res.skipped ? `;跳过平台已发货 ${res.skipped} 单` : ''}${res.voided ? `;自动作废 ${res.voided} 单` : ''}`,
)
fetchOrderVisible.value = false
await fetchList()
@ -550,7 +551,7 @@ onMounted(fetchList)
type="info"
:closable="false"
show-icon
title="按店铺所属商家逐平台分区拉取;下拉时间越长耗时越久。开启「自动拉取订单」后系统会按间隔定时拉取"
title="按店铺所属商家逐平台分区拉取;只拉取平台侧未发货的订单(已发货/已完成/已关闭的订单会跳过)。下拉时间越长耗时越久。开启「自动拉取订单」后系统会按间隔定时拉取"
class="fetch-order-tip"
/>
<el-form :model="fetchOrderForm" label-width="96px">