feat(pull): 拉单 0 单时给出「商家对不上」的排查提示

抖音平台订单拉不到排查结论:平台侧数据本身能拉到(意洁的 1688→抖店分销单
11-07 16:27 已入库 6 单 DYXD),问题出在「店铺声明的商家 FxUserId 与平台不一致」时
只回 0 单、看不出原因。本次让这种情况自己说话:

- dgj.listOrders:全量兜底扫描时记录平台实际出现的商家(UpFxUserId → 单量/店铺名),
  返回 merchantSeen / otherMerchants
- externalPrintOrder:新增 buildZeroOrderHint —— 0 单且本店商家没出现过时,
  输出「近 N 天没有出现 FxUserId=xxx(分区…),实际出现的是 意洁(953516,450 单)…」,
  并提示刷新店铺所在区/商家
- 自动拉取的 last_order_sync_msg、手动拉取响应 hint / 前端提示都带上该说明
- 单测 pullOrderHint.test.js(2 例:有提示/无误报,含分区去重)

排查记录(本地账号 1 实测):
- 意洁(953516):15 天待处理 10 单 = DYXD 6 + TB 3 + PDD 1,抖音分销单正常
- 抖店分区(fxdd) 近 90 天 1099+154 单全部已发货/关闭,0 条待发货 → 平台侧确实没得拉
- 两家「奇迹商贸」店铺绑的商家 1921984 / 1844767 在全部分区 90 天内 0 单;
  平台上真正有单的奇迹商贸商家是 401499 → 需要在 OMS 重新同步店铺

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
liufumingren 2026-11-07 18:44:02 +08:00
parent 673bd0bef3
commit 61a9587851
8 changed files with 105 additions and 3 deletions

View File

@ -1576,6 +1576,7 @@ module.exports = {
items_bound: { type: 'integer', description: '已匹配到绑定系统商品/组合商品的明细数' },
items_unbound: { type: 'integer', description: '未绑定系统商品的明细数(保留平台原样快照)' },
hosts: { type: 'array', itemType: 'string', description: '拉取命中的域名与分区' },
hint: { type: 'string', description: '0 单时的排查提示:平台侧未出现店铺声明的商家(FxUserId),列出实际出现的商家' },
},
externalPrintShopOrderSyncResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },

View File

@ -833,7 +833,8 @@ class ExternalPrintAccountController extends Controller {
shop,
new Date(),
`手动拉取成功:${saved.orders} 单,跳过平台已发货 ${saved.skipped || 0} 单,自动作废 ${saved.voided || 0} 单` +
(saved.voidedMissing ? `(其中平台已查不到 ${saved.voidedMissing} 单)` : '')
(saved.voidedMissing ? `(其中平台已查不到 ${saved.voidedMissing} 单)` : '') +
(saved.hint ? `;${saved.hint}` : '')
);
ctx.body = {
code: 0,
@ -852,6 +853,7 @@ class ExternalPrintAccountController extends Controller {
items_bound: saved.itemsBound,
items_unbound: saved.itemsUnbound,
hosts: saved.hosts,
hint: saved.hint || '',
},
};
}

View File

@ -1847,6 +1847,8 @@ class DgjService extends PrintPlatformService {
const orders = new Map();
const finished = new Map();
const hitHosts = [];
// 平台实际出现的商家(UpFxUserId → 单量/店铺名),用于诊断「店铺声明的商家与平台不一致」
const seenMerchants = new Map();
// 不支持状态/商家过滤的老分区(旧系统库):退化为只按时间窗拉全量,本地过滤
const fallbackHosts = [];
// 店铺没有声明该平台的老分区(只有新系统分区)时,该平台的老分区属于迁移前遗留数据,跳过不拉
@ -1900,8 +1902,19 @@ class DgjService extends PrintPlatformService {
if (!fetched.length) continue;
hitHosts.push(`${host}(${area.name || area.dbname})`);
for (const row of fetched) {
const upFxUserId = String(row.UpFxUserId || '');
// 记录平台实际出现的商家:店铺声明的 FxUserId 过期时(重新授权/换绑),
// 按老 FxUserId 过滤永远是 0 条,这里留痕便于直接看出「该换成谁」
if (upFxUserId) {
const seen = seenMerchants.get(upFxUserId) || {
count: 0,
shopName: String(row.ShopName || row.AgentShopName || row.SelfShopName || ''),
};
seen.count += 1;
seenMerchants.set(upFxUserId, seen);
}
// 订单列表按账号维度返回,这里只保留当前商家的订单
if (String(row.UpFxUserId || '') !== merchantFxUserId) continue;
if (upFxUserId !== merchantFxUserId) continue;
const order = this.normalizeOrder(row);
if (!order.external_order_id) continue;
// 平台已发货/已终结:不进待审核,只登记给上层用于作废本地未处理的副本
@ -1930,6 +1943,13 @@ class DgjService extends PrintPlatformService {
skippedLegacy,
skipped: finished.size,
finished: Array.from(finished.values()),
// 店铺声明的商家在平台结果里是否出现过;没出现过通常是 FxUserId 过期(重新授权/换绑)
merchantSeen: seenMerchants.has(merchantFxUserId),
otherMerchants: Array.from(seenMerchants.entries())
.filter(([ fxUserId ]) => fxUserId !== merchantFxUserId)
.map(([ fxUserId, item ]) => ({ fx_user_id: fxUserId, shop_name: item.shopName, count: item.count }))
.sort((left, right) => right.count - left.count)
.slice(0, 5),
// 供上层做「按订单号精确核对」时复用本次登录上下文
traceId,
};

View File

@ -101,7 +101,8 @@ module.exports = {
now,
`自动拉取成功:${result.orders} 单(新增 ${result.created},更新 ${result.updated}),明细 ${result.items} 条` +
`,跳过平台已发货 ${result.skipped || 0} 单,自动作废 ${result.voided || 0} 单` +
(result.voidedMissing ? `(其中平台已查不到 ${result.voidedMissing} 单)` : '')
(result.voidedMissing ? `(其中平台已查不到 ${result.voidedMissing} 单)` : '') +
(result.hint ? `;${result.hint}` : '')
);
fetched++;
ctx.logger.info(

View File

@ -186,9 +186,41 @@ class ExternalPrintOrderService extends Service {
itemsUnbound: saved.itemsUnbound,
hosts: result.hosts,
fallbackHosts: result.fallbackHosts || [],
hint: this.buildZeroOrderHint(shopPlain, result, { startTime, endTime }),
};
}
/**
* 一单都没拉到、且平台结果里根本没有本店铺声明的商家时给出排查提示
*
* 典型场景:商家重新授权 / 换绑后 `shops.external_data.FxUserId` 过期,
* 按老 FxUserId 过滤永远是 0 条,看起来就像「这个平台的订单拉不到」。
* @param {Object} shopPlain 店铺纯对象
* @param {Object} result listOrders 结果
* @param {Object} [range] 拉取时间窗
* @param {Date} [range.startTime] 下单时间起
* @param {Date} [range.endTime] 下单时间止
* @return {string} 提示(无需提示时为空字符串)
*/
buildZeroOrderHint(shopPlain, result, { startTime, endTime } = {}) {
if (!result || result.total > 0) return '';
if (result.merchantSeen !== false) return '';
const others = Array.isArray(result.otherMerchants) ? result.otherMerchants : [];
if (!others.length) return '';
const declared = String((shopPlain && shopPlain.external_data && shopPlain.external_data.FxUserId) || '') || '-';
const othersText = others
.map(item => `${item.shop_name || '未命名'}(${item.fx_user_id},${item.count} 单)`)
.join('、');
const areas = Array.from(new Set((result.hosts || []).concat(result.fallbackHosts || []))).join('、') || '-';
const days = startTime && endTime
? Math.max(1, Math.round((new Date(endTime).getTime() - new Date(startTime).getTime()) / 86400000))
: null;
const windowText = days ? `近 ${days} 天` : '本次窗口';
return `${windowText}平台结果里没有出现店铺声明的商家 FxUserId=${declared}(分区:${areas}),` +
`实际出现的是 ${othersText}。可能是该商家近段时间没有待发货订单,或商家重新授权/换绑导致 FxUserId 变化;` +
'请核对店铺「所在区/商家」是否需要刷新';
}
/**
* 核对「本次拉取窗口内本地仍是待审核、但平台待发货结果里没有」的订单
*

View File

@ -0,0 +1,41 @@
'use strict';
const { app, assert } = require('egg-mock/bootstrap');
describe('service/externalPrintOrder 拉单 0 单的排查提示', () => {
let service;
beforeEach(() => {
service = app.mockContext().service.externalPrintOrder;
});
it('平台出现了别的商家、没出现本店商家时给出提示', () => {
const hint = service.buildZeroOrderHint(
{ external_data: { FxUserId: 1921984 } },
{
total: 0,
merchantSeen: false,
otherMerchants: [{ fx_user_id: '953516', shop_name: '13668975305(意洁)', count: 450 }],
hosts: [ 'fxdd.dgjapp.com(抖店-186)' ],
fallbackHosts: [ 'fxdd.dgjapp.com(抖店-186)' ],
},
{ startTime: new Date('2026-10-23T00:00:00Z'), endTime: new Date('2026-11-07T00:00:00Z') }
);
console.log('提示:', hint);
assert.match(hint, /近 15 天/);
assert.match(hint, /FxUserId=1921984/);
assert.match(hint, /953516/);
assert.match(hint, /刷新/);
// 分区去重
assert.strictEqual(hint.split('抖店-186').length - 1, 1);
});
it('有单 / 商家出现过 / 没看到别的商家时都不提示', () => {
const shop = { external_data: { FxUserId: 1 } };
const base = { merchantSeen: false, otherMerchants: [{ fx_user_id: '2', shop_name: 'A', count: 3 }], hosts: [] };
assert.strictEqual(service.buildZeroOrderHint(shop, { ...base, total: 5 }), '');
assert.strictEqual(service.buildZeroOrderHint(shop, { ...base, total: 0, merchantSeen: true }), '');
assert.strictEqual(service.buildZeroOrderHint(shop, { ...base, total: 0, otherMerchants: [] }), '');
assert.strictEqual(service.buildZeroOrderHint(shop, null), '');
});
});

View File

@ -211,6 +211,8 @@ export interface SyncShopOrdersResult {
items_bound: number
items_unbound: number
hosts: string[]
/** 0 单时的排查提示(平台侧未出现本店商家,多半是换绑导致 FxUserId 过期) */
hint?: string
}
/** 手动拉取外部打单平台商家订单(按天数或时间窗) */

View File

@ -780,6 +780,9 @@ async function submitFetchOrder() {
`拉取完成(${scope}):未发货 ${res.orders} 单(新增 ${res.created},更新 ${res.updated}),明细 ${res.items} 条` +
`${res.skipped ? `;跳过平台已发货 ${res.skipped} 单` : ''}${res.voided ? `;自动作废 ${res.voided} 单` : ''}`,
)
} else if (res.hint) {
// 0 单且平台侧没出现本店商家:直接把排查原因说清楚(多半是商家换绑导致 FxUserId 过期)
ElMessage({ type: 'warning', message: res.hint, duration: 0, showClose: true })
} else {
ElMessage.warning(`该范围(${scope})内没有平台未发货的订单`)
}