fix(order): 商品同步/补拉后自动重匹配未采集的订单明细

问题:拉单早于商品入库(新店铺第一次拉单,或商品是事后才补拉的)时,明细会停在
shop_product_id=null(parse_msg「未采集到该店铺商品」),之后商品补齐也不会自动
变化 —— 订单页一直显示未绑定,还被「仅已绑定」过滤掉,看起来像「有商品却匹配不上」。
另外「重新解析」旧接口只回写 order_items,改不动订单页读的状态明细表。

- 新增 lib/shopProductMatch:把「店铺 + 平台商品ID + 平台规格ID」等值匹配抽成纯函数,
  明细带规格ID时必须精确命中同规格,不退化按商品ID乱取(避免不同规格绑成一行)
- orderItemResolve.rematchUnboundItems:商品写入后在同一事务里补匹配该店铺
  shop_product_id 为空的明细,并重建命中订单(只动待审核/异常,已审核随审核锁定)
- saveShopProducts 调用它并返回 rematched;同步/单品补拉两个接口与前端提示都带上
- 文档补 §4.2.5:明细 → 店铺商品 → 系统商品的匹配口径、两种 parse_status=2 的区别
- 单测 shopProductMatch.test.js(精确命中 / 不退化 / 无规格取首行 / 空输入)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
liufumingren 2026-11-07 21:30:29 +08:00
parent 8e2419c870
commit c73cc826d7
9 changed files with 201 additions and 4 deletions

View File

@ -1506,6 +1506,7 @@ module.exports = {
created: { type: 'integer', description: '新增商品行数' },
updated: { type: 'integer', description: '更新商品行数' },
rekeyed: { type: 'integer', description: '按 SkuId 校正平台规格ID 的行数(同商品同规格名就地改键,老行不会因此被下架)' },
rematched: { type: 'integer', description: '本次写入后补匹配上的订单明细行数(原本未采集到店铺商品的待审核明细)' },
removed: { type: 'integer', description: '已删除的商品行数(平台已不存在,且未绑定系统商品、未被订单明细引用)' },
offline: { type: 'integer', description: '保留并标为下架的商品行数(平台已不存在,但已绑定系统商品/组合商品或被订单明细引用)' },
verified: { type: 'boolean', description: '快照是否完整;不完整时不会移除任何商品' },
@ -1548,6 +1549,7 @@ module.exports = {
created: { type: 'integer', description: '新增的店铺商品行数' },
updated: { type: 'integer', description: '更新的店铺商品行数' },
rekeyed: { type: 'integer', description: '按 SkuId 校正平台规格ID 的行数(同商品同规格名就地改键)' },
rematched: { type: 'integer', description: '本次补拉后补匹配上的订单明细行数(原本未采集到店铺商品的待审核明细)' },
hosts: { type: 'array', itemType: 'string', description: '命中的域名与分区' },
missing: { type: 'array', itemType: 'externalPrintShopProductPullMissing', description: '未命中的商品及原因' },
products: { type: 'array', itemType: 'externalPrintShopProductPullItem', description: '拉取后写入的店铺商品' },

View File

@ -613,6 +613,7 @@ class ExternalPrintAccountController extends Controller {
created: saved.created,
updated: saved.updated,
rekeyed: saved.rekeyed || 0,
rematched: saved.rematched || 0,
removed: saved.removed,
offline: saved.offline,
verified: snapshot.verified,
@ -721,6 +722,7 @@ class ExternalPrintAccountController extends Controller {
created: saved.created,
updated: saved.updated,
rekeyed: saved.rekeyed || 0,
rematched: saved.rematched || 0,
hosts: result.hosts,
missing: result.missing,
products: savedRows,
@ -862,9 +864,10 @@ class ExternalPrintAccountController extends Controller {
* 把商品快照写入店铺商品表:按唯一键 upsert,快照完整时把本次未出现的商品移除(下架)。
* 未绑定且未被订单引用的直接删除;已绑定或被订单引用的只标为下架,避免丢配置、断溯源。
* 快照不完整(平台分页前后数据不一致)时只更新,不做移除处理,避免误删。
* 写入后会顺带把「未采集到店铺商品」的订单明细重新匹配一次(rematched)。
* @param {Object} shop 店铺实例
* @param {Object} snapshot 平台商品快照
* @return {Promise<{unique: number, created: number, updated: number, rekeyed: number, removed: number, offline: number}>} 写入结果
* @return {Promise<{unique: number, created: number, updated: number, rekeyed: number, removed: number, offline: number, rematched: number}>} 写入结果
*/
async saveShopProducts(shop, snapshot) {
const { ctx } = this;
@ -1039,13 +1042,25 @@ class ExternalPrintAccountController extends Controller {
}
}
// 商品补齐后,把仍是「未采集到店铺商品」的明细按最新数据重新匹配一次:
// 先拉单后同步商品是新店铺的常态,不补这一步明细会一直显示未绑定
const rematch = await ctx.service.orderItemResolve.rematchUnboundItems(shop.id, { transaction });
await transaction.commit();
return {
unique: rows.length,
created,
updated,
rekeyed: rekey.length,
removed,
offline,
rematched: rematch.matched,
};
} catch (err) {
await transaction.rollback();
throw err;
}
return { unique: rows.length, created, updated, rekeyed: rekey.length, removed, offline };
}
/**

View File

@ -0,0 +1,43 @@
'use strict';
/**
* 店铺商品匹配索引
*
* 把「店铺 + 平台商品ID + 平台规格ID」的等值匹配抽成纯函数:拉单时逐条查库,
* 商品同步后的批量重匹配则一次查全量再内存比对,两条链路共用同一套口径,避免出现
* 「拉单匹配上了、重匹配没匹配上」这类不一致。
*
* 匹配规则:
* - 明细带平台规格ID 时必须精确命中同一规格,**不允许退化成按商品ID随便取一条**
* (否则不同规格会绑到同一行店铺商品,出库发错货);
* - 明细没有平台规格ID(无规格商品/部分平台不给 SkuId)时按商品ID取 id 最小的那条。
*/
/**
* 生成匹配函数
* @param {Array<{id:number, outer_item_id:string, outer_sku_id?:string}>} rows 店铺商品行(建议按 id 升序)
* @return {(line: {outer_item_id?:string, outer_sku_id?:string}) => number|null} 匹配函数,返回命中的店铺商品ID
*/
function createShopProductMatcher(rows) {
const skuIndex = new Map();
const itemIndex = new Map();
for (const row of rows || []) {
const itemId = String((row && row.outer_item_id) || '').trim();
const id = Number(row && row.id);
if (!itemId || !id) continue;
const skuId = String((row && row.outer_sku_id) || '').trim();
if (skuId && !skuIndex.has(`${itemId}||${skuId}`)) skuIndex.set(`${itemId}||${skuId}`, id);
if (!itemIndex.has(itemId)) itemIndex.set(itemId, id);
}
return line => {
const itemId = String((line && line.outer_item_id) || '').trim();
if (!itemId) return null;
const skuId = String((line && line.outer_sku_id) || '').trim();
if (skuId) return skuIndex.get(`${itemId}||${skuId}`) || null;
return itemIndex.get(itemId) || null;
};
}
module.exports = { createShopProductMatcher };

View File

@ -2,6 +2,7 @@
const Service = require('egg').Service;
const { foldPlatformLines, normalizeSnapshot, expandPlatformLine } = require('../lib/orderItemExpand');
const { createShopProductMatcher } = require('../lib/shopProductMatch');
const { ORDER_STATUS } = require('../lib/orderStatus');
/**
@ -111,6 +112,74 @@ class OrderItemResolveService extends Service {
return map;
}
/**
* 商品同步/补拉后,把「未采集到店铺商品」的订单明细按最新店铺商品重新匹配一次
*
* 拉单早于商品入库是新店铺/新平台的常态:明细会停在 shop_product_id=null(未采集),
* 之后商品补齐也不会自动变化,订单页就一直显示未绑定、还被「仅已绑定」过滤掉。
* 这里在商品写入后按与拉单相同的口径(店铺 + 平台商品ID + 平台规格ID)补一次匹配,
* 并重建命中订单的明细(有绑定关系的直接变成已解析)。
* @param {number} shopId 店铺ID
* @param {Object} [options] { transaction }
* @return {Promise<{matched: number, rebuilt: number}>} 补上的明细行数与重建后的明细行数
*/
async rematchUnboundItems(shopId, options = {}) {
const { ctx } = this;
const Op = this.app.Sequelize.Op;
const shopKey = Number(shopId);
if (!shopKey) return { matched: 0, rebuilt: 0 };
// 以库内为准(不用平台快照的中间态),按 id 升序保证「无规格时取第一条」稳定
const products = await ctx.model.ShopProduct.findAll({
where: { shop_id: shopKey },
attributes: [ 'id', 'outer_item_id', 'outer_sku_id' ],
order: [[ 'id', 'ASC' ]],
raw: true,
transaction: options.transaction,
});
if (!products.length) return { matched: 0, rebuilt: 0 };
const pick = createShopProductMatcher(products);
const items = await ctx.model.OrderStatusItem.findAll({
where: { shop_id: shopKey, shop_product_id: { [Op.is]: null } },
attributes: [ 'id', 'order_id', 'outer_item_id', 'outer_sku_id' ],
raw: true,
transaction: options.transaction,
});
if (!items.length) return { matched: 0, rebuilt: 0 };
// 只补「待审核 / 异常」的订单:其余状态明细已随审核锁定(甚至已下发仓库),不跟着商品数据变化
const indexRows = await ctx.model.OrderIndex.findAll({
where: {
id: { [Op.in]: [ ...new Set(items.map(item => Number(item.order_id)).filter(id => id > 0)) ] },
current_status: { [Op.in]: [ ORDER_STATUS.PENDING, ORDER_STATUS.EXCEPTION ] },
},
attributes: [ 'id' ],
raw: true,
transaction: options.transaction,
});
const editableIds = new Set(indexRows.map(row => Number(row.id)));
if (!editableIds.size) return { matched: 0, rebuilt: 0 };
const orderIds = new Set();
let matched = 0;
for (const item of items) {
if (!editableIds.has(Number(item.order_id))) continue;
const shopProductId = pick(item);
if (!shopProductId) continue;
await ctx.model.OrderStatusItem.update(
{ shop_product_id: shopProductId },
{ where: { id: item.id }, transaction: options.transaction }
);
orderIds.add(Number(item.order_id));
matched++;
}
if (!matched) return { matched: 0, rebuilt: 0 };
const rebuilt = await this.rebuildOrderItems(Array.from(orderIds), { transaction: options.transaction });
return { matched, rebuilt };
}
/**
* 按店铺商品批量重建其订单明细(绑定关系或商品资料变化后调用)
* @param {Array<number>} shopProductIds 店铺商品ID

View File

@ -0,0 +1,38 @@
'use strict';
const { assert } = require('egg-mock/bootstrap');
const { createShopProductMatcher } = require('../../../app/lib/shopProductMatch');
describe('app/lib/shopProductMatch 店铺商品匹配口径', () => {
const rows = [
{ id: 11, outer_item_id: '3773823319627923739', outer_sku_id: '3548726733104642' },
{ id: 12, outer_item_id: '3773823319627923739', outer_sku_id: '3548726733104898' },
{ id: 21, outer_item_id: '881526926136', outer_sku_id: '' },
{ id: 22, outer_item_id: '881526926136', outer_sku_id: '006-1' },
];
it('明细带规格ID时精确命中同规格', () => {
const pick = createShopProductMatcher(rows);
assert.strictEqual(pick({ outer_item_id: '3773823319627923739', outer_sku_id: '3548726733104898' }), 12);
assert.strictEqual(pick({ outer_item_id: '881526926136', outer_sku_id: '006-1' }), 22);
});
it('规格ID对不上时不退化成按商品ID随便取一条', () => {
const pick = createShopProductMatcher(rows);
assert.strictEqual(pick({ outer_item_id: '3773823319627923739', outer_sku_id: '999' }), null);
});
it('明细没有规格ID时按商品ID取 id 最小的那条', () => {
const pick = createShopProductMatcher(rows);
assert.strictEqual(pick({ outer_item_id: '3773823319627923739', outer_sku_id: '' }), 11);
assert.strictEqual(pick({ outer_item_id: '881526926136' }), 21);
});
it('空输入返回 null', () => {
const pick = createShopProductMatcher(rows);
assert.strictEqual(pick({ outer_item_id: '', outer_sku_id: '1' }), null);
assert.strictEqual(pick({ outer_item_id: '404' }), null);
assert.strictEqual(pick(null), null);
assert.strictEqual(createShopProductMatcher([])({ outer_item_id: '1' }), null);
});
});

View File

@ -134,6 +134,8 @@ export interface ExternalPrintShopProductSyncResult {
updated: number
/** 平台规格ID 统一取 SkuId 后就地改键的行数(同商品同规格名唯一命中才改) */
rekeyed?: number
/** 本次写入后补匹配上的订单明细行数(原本未采集到店铺商品) */
rematched?: number
/** 平台已不存在、且未绑定未被订单引用 → 已删除的行数 */
removed: number
/** 平台已不存在、但已绑定或被订单引用 → 保留并标为下架的行数 */
@ -178,6 +180,8 @@ export interface PullShopProductsResult {
matched: number
created: number
updated: number
/** 本次补拉后补匹配上的订单明细行数(原本未采集到店铺商品) */
rematched?: number
hosts: string[]
missing: Array<{ outer_item_id: string; outer_sku_id: string; reason: string }>
products: PulledShopProductRow[]

View File

@ -852,6 +852,7 @@ async function handleSyncProducts(row: ShopItem) {
const res = await syncExternalPrintShopProducts(accountId, row.id)
const parts = [ `新增 ${res.created}`, `更新 ${res.updated}` ]
if (res.rekeyed) parts.push(`校正规格ID ${res.rekeyed}`)
if (res.rematched) parts.push(`自动匹配订单明细 ${res.rematched} 条`)
if (res.removed) parts.push(`移除 ${res.removed}`)
if (res.offline) parts.push(`下架 ${res.offline}(已绑定或被订单引用,已保留)`)
const suffix = res.verified ? '' : '(平台数据在拉取过程中有变动,本次未处理下架,建议重试)'

View File

@ -489,7 +489,8 @@ async function submitPull() {
ElMessage.warning(`未拉取到商品:${reason}`)
return
}
ElMessage.success(`拉取成功:新增 ${res.created},更新 ${res.updated},来源 ${res.hosts.join('、')}`)
const rematch = res.rematched ? `,自动匹配订单明细 ${res.rematched} 条` : ''
ElMessage.success(`拉取成功:新增 ${res.created},更新 ${res.updated},来源 ${res.hosts.join('、')}${rematch}`)
pullVisible.value = false
await fetchList()
} catch {

View File

@ -406,6 +406,30 @@ WaybillCodeCreateDate='2026-11-04 08:20:37'
>
> ⚠️ 代价:每次取号都真实消耗一张面单(`ExpressPrintTimes` 累加),重试务必复用同一个 `request_id`。
#### 4.2.5 订单明细 → 店铺商品 → 系统商品(匹配口径)
拉单时每条明细按「店铺 + 平台商品ID + 平台规格ID」命中店铺商品(`service/externalPrintOrder.matchShopProduct`):
| 明细字段 | 来源 | 店铺商品字段 |
|---|---|---|
| `outer_item_id` | 明细 `ProductId`(商品级) | `shop_products.outer_item_id` = 商品 `PlatformId` |
| `outer_sku_id` | 明细 `SkuId`(无合法值退 `SkuCode`) | `shop_products.outer_sku_id` = `Skus[].SkuId`(**早期用过 `SpecId`,两者在部分平台不一致**) |
- 明细带规格ID时**必须精确命中同规格**,不允许退化成「按商品ID随便取一条」(会绑错规格、发错货);
规格ID对不上 → 保持未采集,等商品补齐后重匹配;
- 命中店铺商品后才看绑定关系:`bind_type=1/2` → 已解析;`bind_type=0` → `parse_status=2`
(`parse_msg=店铺商品未绑定系统商品`);没命中 → `parse_status=2`(`parse_msg=未采集到该店铺商品`);
- **两种 `parse_status=2` 都会被待审核列表的「仅已绑定」过滤掉**,列表会给出「另有 N 单未显示」提示
(`order_status.list` 的 `hidden_unbound`)。
**商品写入后自动重匹配**(`service/orderItemResolve.rematchUnboundItems`):同步 / 单品补拉商品后,
在同一事务里把该店铺「`shop_product_id` 为空」的**待审核 / 异常**明细按上述口径再匹配一次并重建明细,
避免「先拉单、后同步商品」导致明细永远停在未采集(已审核之后的订单明细不参与,随审核锁定)。
接口返回 `rematched`(补上的明细行数)。
沿用旧口径的坑:老数据里 `shop_products.outer_sku_id` 可能是 `SpecId`,与明细的 `SkuId` 对不上;
重新同步商品会按 `SkuId` 就地改键(同商品同规格名唯一命中),之后重匹配即可命中。
### 4.3 模板校验:`POST /TemplateSet/CheckTemplateAvaliable`
```json