feat(product): 商品增加「订单唯一赠品」,明细解析整单只落一行

赠品类商品在平台上会随购买数量重复出现(数量 3 就是 3 件),也可能同时出现在多个组合里
(两份组合、不同组合都含同一赠品)。业务上赠品每单只送一份,需要按商品维度收敛。

- 迁移 add-unique-gift-to-products:products.is_order_unique_gift TINYINT 默认 0 + 索引
  (已在本机执行)
- 模型/契约/列表接口:字段透传;列表支持 is_order_unique_gift=1/0 筛选
- 明细解析:rebuildOrderItems 展开成最小单位后调用 collapseUniqueGifts
  → collapseUniqueGiftRows 收敛:同一赠品只保留第一行、数量固定 1
  (多数量 / 同一组合多份 / 不同组合都含该赠品,均只落一行);重复重建不会涨回数量
- 系统商品页:新增「订单唯一赠品」开关(带说明)、列表「唯一赠品」标记、筛选下拉;
  导出(exportDefs.product)同步加筛选与列
- 单测:orderItemUniqueGift.test.js(纯函数 5 例)+ orderItemUniqueGiftRebuild.test.js
  (真实库事务内验证两条明细数量 3 → 1 行数量 1,跑完回滚)
- 顺带修 model/product.js 里重复定义的 brand_name(eslint no-dupe-keys,两行内容相同)
- 文档 §6.1.1 补「组合拆分 + 订单唯一赠品」口径

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
liufumingren 2026-11-08 11:28:18 +08:00
parent 28adc28ea6
commit 62df580393
12 changed files with 333 additions and 5 deletions

View File

@ -494,6 +494,7 @@ module.exports = {
is_sn_mgmt: { type: 'string', description: '是否序列号管理:Y/N' },
is_shelf_life_mgmt: { type: 'string', description: '是否保质期管理:Y/N' },
is_batch_mgmt: { type: 'string', description: '是否批次管理:Y/N' },
is_order_unique_gift: { type: 'integer', description: '是否订单唯一赠品:1 是(整单只落一行、数量 1)0 否,默认 0' },
barcode: { type: 'string', description: '条码' },
brand_name: { type: 'string', description: '品牌名称' },
image: { type: 'string', description: '图片URL(主图,取 images 首张)' },
@ -552,6 +553,7 @@ module.exports = {
is_sn_mgmt: { type: 'string', description: '是否序列号管理:Y/N,默认N' },
is_shelf_life_mgmt: { type: 'string', description: '是否保质期管理:Y/N,默认N' },
is_batch_mgmt: { type: 'string', description: '是否批次管理:Y/N,默认N' },
is_order_unique_gift: { type: 'integer', description: '是否订单唯一赠品:1 是(整单只落一行、数量 1)0 否,默认 0' },
tag_price: { type: 'number', description: '标价' },
retail_price: { type: 'number', required: true, description: '零售价' },
cost_price: { type: 'number', description: '成本价' },
@ -583,6 +585,7 @@ module.exports = {
is_sn_mgmt: { type: 'string', description: '是否序列号管理:Y/N' },
is_shelf_life_mgmt: { type: 'string', description: '是否保质期管理:Y/N' },
is_batch_mgmt: { type: 'string', description: '是否批次管理:Y/N' },
is_order_unique_gift: { type: 'integer', description: '是否订单唯一赠品:1 是(整单只落一行、数量 1)0 否,默认 0' },
tag_price: { type: 'number', description: '标价' },
retail_price: { type: 'number', description: '零售价' },
cost_price: { type: 'number', description: '成本价' },

View File

@ -66,6 +66,7 @@ class ProductController extends Controller {
* @request query string brand_name 品牌名称,精确匹配
* @request query string stock_unit 库存单位,精确匹配
* @request query integer subsidiary_id 所属货主(下属公司ID)
* @request query integer is_order_unique_gift 是否订单唯一赠品:1 是 0 否,不传则不过滤
* @request query integer status 状态:1上架 0下架,不传则不过滤
* @response 200 productListResponse success
*/
@ -90,6 +91,9 @@ class ProductController extends Controller {
if (brandName) where.brand_name = brandName;
if (stockUnit) where.stock_unit = stockUnit;
if (status !== undefined && status !== '') where.status = Number(status);
// 订单唯一赠品筛选:1 只看赠品,0 只看非赠品
const giftFilter = ctx.query.is_order_unique_gift;
if (giftFilter !== undefined && giftFilter !== '') where.is_order_unique_gift = Number(giftFilter) ? 1 : 0;
if (ctx.query.subsidiary_id !== undefined && ctx.query.subsidiary_id !== '') {
where.subsidiary_id = Number(ctx.query.subsidiary_id);
}

View File

@ -257,9 +257,42 @@ function normalizeSnapshot(line) {
return snapshot;
}
/**
* 折叠「订单唯一赠品」行:同一赠品商品整单只保留一行,数量固定 1
*
* 场景:赠品在平台上可能随购买数量重复(数量 3 就是 3 件),也可能同时出现在**多个组合**里
* (两份组合、甚至不同组合都含同一赠品)。业务上赠品每个订单只送一份,所以展开成最小单位之后
* 统一收敛:第一次出现的那行数量改 1,其余同商品的整行丢弃。
* @param {Array<Object>} rows 展开后的明细行(含 product_id / plan_qty / quantity)
* @param {Set<number>|Array<number>} giftProductIds 标记为「订单唯一赠品」的商品ID
* @return {Array<Object>} 收敛后的明细行
*/
function collapseUniqueGiftRows(rows, giftProductIds) {
const gifts = giftProductIds instanceof Set
? giftProductIds
: new Set((Array.isArray(giftProductIds) ? giftProductIds : []).map(Number));
if (!gifts.size) return Array.isArray(rows) ? rows : [];
const seen = new Set();
const out = [];
for (const row of Array.isArray(rows) ? rows : []) {
const productId = row && row.product_id != null ? Number(row.product_id) : null;
if (!productId || !gifts.has(productId)) {
out.push(row);
continue;
}
if (seen.has(productId)) continue;
seen.add(productId);
// 赠品不按购买数量累加:整单固定 1 件
out.push({ ...row, plan_qty: 1, quantity: 1 });
}
return out;
}
module.exports = {
buildSnapshot,
normalizeSnapshot,
foldPlatformLines,
expandPlatformLine,
collapseUniqueGiftRows,
};

View File

@ -36,8 +36,8 @@ module.exports = app => {
is_sn_mgmt: { type: STRING(1), defaultValue: 'N', comment: '是否序列号管理' },
is_shelf_life_mgmt: { type: STRING(1), defaultValue: 'N', comment: '是否保质期管理' },
is_batch_mgmt: { type: STRING(1), defaultValue: 'N', comment: '是否批次管理' },
is_order_unique_gift: { type: TINYINT, allowNull: false, defaultValue: 0, comment: '是否订单唯一赠品:1 是(整单只落一行、数量 1)0 否' },
barcode: { type: STRING(100), comment: '条码' },
brand_name: { type: STRING(100), comment: '品牌名称' },
image: { type: STRING(255), comment: '图片(主图,取 images 首张)' },
images: { type: JSON, comment: '图片组(URL 数组,首张为主图)' },
status: { type: TINYINT, allowNull: false, defaultValue: 1, comment: '状态:1启用 0禁用' },

View File

@ -1,7 +1,7 @@
'use strict';
const Service = require('egg').Service;
const { foldPlatformLines, normalizeSnapshot, expandPlatformLine } = require('../lib/orderItemExpand');
const { foldPlatformLines, normalizeSnapshot, expandPlatformLine, collapseUniqueGiftRows } = require('../lib/orderItemExpand');
const { createShopProductMatcher } = require('../lib/shopProductMatch');
const { ORDER_STATUS } = require('../lib/orderStatus');
@ -180,6 +180,32 @@ class OrderItemResolveService extends Service {
return { matched, rebuilt };
}
/**
* 折叠「订单唯一赠品」明细行
*
* 展开成最小单位后,把标记了 `is_order_unique_gift` 的商品整单收敛为一行、数量 1:
* 平台数量 3 → 1;两份组合各带同一赠品 → 1;不同组合都含该赠品 → 1。
* @param {Array<Object>} payload 展开后的明细行
* @param {Object} transaction 事务
* @return {Promise<Array<Object>>} 收敛后的明细行
*/
async collapseUniqueGifts(payload, transaction) {
const { ctx } = this;
const rows = Array.isArray(payload) ? payload : [];
const productIds = [ ...new Set(rows.map(row => Number(row && row.product_id)).filter(id => id > 0)) ];
if (!productIds.length) return rows;
const Op = this.app.Sequelize.Op;
const gifts = await ctx.model.Product.findAll({
where: { id: { [Op.in]: productIds }, is_order_unique_gift: 1 },
attributes: [ 'id' ],
raw: true,
transaction,
});
const giftIds = new Set(gifts.map(row => Number(row.id)));
if (!giftIds.size) return rows;
return collapseUniqueGiftRows(rows, giftIds);
}
/**
* 按店铺商品批量重建其订单明细(绑定关系或商品资料变化后调用)
* @param {Array<number>} shopProductIds 店铺商品ID
@ -269,10 +295,13 @@ class OrderItemResolveService extends Service {
for (const part of parts) payload.push(part);
}
// 「订单唯一赠品」:整单只留一行、数量 1(多数量、多组合命中同一赠品都收敛成一条)
const collapsed = await this.collapseUniqueGifts(payload, transaction);
await ctx.model.OrderStatusItem.destroy({ where: { order_id: orderId }, transaction });
if (payload.length) {
if (collapsed.length) {
await ctx.model.OrderStatusItem.bulkCreate(
payload.map((row, idx) => ({
collapsed.map((row, idx) => ({
...row,
principal_id: rows[0].principal_id,
order_id: orderId,
@ -283,7 +312,7 @@ class OrderItemResolveService extends Service {
}
await ctx.service.orderStatus.refreshItemSummary(orderId, rows[0].principal_id, transaction);
affected += payload.length;
affected += collapsed.length;
}
if (ownedTransaction) await transaction.commit();

View File

@ -443,6 +443,7 @@ const PRODUCT_COLUMNS = [
{ key: 'retail_price', header: '零售价' },
{ key: 'cost_price', header: '成本价' },
{ key: 'tag_price', header: '标签价' },
{ key: 'is_order_unique_gift', header: '订单唯一赠品', format: labels({ 0: '否', 1: '是' }) },
{ key: 'status', header: '状态', format: labels(ENABLE_MAP) },
{ key: 'remark', header: '备注' },
{ key: 'created_at', header: '创建时间' },
@ -952,6 +953,7 @@ const EXPORT_TYPES = {
{ key: 'brand_name', label: '品牌', type: 'text', placeholder: '精确匹配' },
{ key: 'stock_unit', label: '单位', type: 'text', placeholder: '精确匹配(如 件)' },
{ key: 'subsidiary_id', label: '所属货主', type: 'subsidiary' },
{ key: 'is_order_unique_gift', label: '订单唯一赠品', type: 'select', options: [{ value: '1', label: '是' }, { value: '0', label: '否' }] },
{ key: 'status', label: '状态', type: 'select', options: ENABLE_OPTIONS },
],
build: (f, ctx) => {
@ -963,6 +965,7 @@ const EXPORT_TYPES = {
.eq('t.brand_name', f.brand_name)
.eq('t.stock_unit', f.stock_unit)
.eq('t.subsidiary_id', f.subsidiary_id)
.eq('t.is_order_unique_gift', f.is_order_unique_gift)
.eq('t.status', f.status);
// 所在公司权限:只能导出自己所属公司(货主)的商品
if (ctx.access && !ctx.access.isGroup) {

View File

@ -0,0 +1,27 @@
'use strict';
/**
* 商品增加「订单唯一赠品」标记。
*
* 置 1 后:订单明细解析到该商品时,**整单只保留一行、数量固定 1**,
* 不管平台明细带了多少数量、通过几个组合/几条明细命中(见 lib/orderItemExpand.collapseUniqueGiftRows)。
*/
module.exports = {
async up(queryInterface, Sequelize) {
await queryInterface.addColumn('products', 'is_order_unique_gift', {
type: Sequelize.TINYINT,
allowNull: false,
defaultValue: 0,
comment: '是否订单唯一赠品:1 是(整单只落一行、数量 1)0 否',
after: 'is_batch_mgmt',
});
await queryInterface.addIndex('products', [ 'principal_id', 'is_order_unique_gift' ], {
name: 'idx_products_principal_unique_gift',
});
},
async down(queryInterface) {
await queryInterface.removeIndex('products', 'idx_products_principal_unique_gift');
await queryInterface.removeColumn('products', 'is_order_unique_gift');
},
};

View File

@ -0,0 +1,68 @@
'use strict';
const { assert } = require('egg-mock/bootstrap');
const { collapseUniqueGiftRows } = require('../../../app/lib/orderItemExpand');
/**
* 造一行明细
* @param {Object} overrides 覆盖字段
* @return {Object} 明细行
*/
function row(overrides) {
return { product_id: null, plan_qty: 1, quantity: 1, item_code: 'X', ...overrides };
}
describe('app/lib/orderItemExpand 订单唯一赠品收敛', () => {
it('同一赠品数量 3 → 只留 1 行且数量 1', () => {
const rows = [ row({ product_id: 100, plan_qty: 3, quantity: 3 }) ];
const out = collapseUniqueGiftRows(rows, new Set([ 100 ]));
assert.strictEqual(out.length, 1);
assert.strictEqual(Number(out[0].quantity), 1);
assert.strictEqual(Number(out[0].plan_qty), 1);
});
it('不同组合都含同一赠品 → 只留 1 行', () => {
const rows = [
row({ product_id: 100, combo_product_id: 7, quantity: 2 }),
row({ product_id: 100, combo_product_id: 8, quantity: 4 }),
row({ product_id: 200, quantity: 1 }),
];
const out = collapseUniqueGiftRows(rows, [ 100 ]);
assert.strictEqual(out.length, 2, '赠品 1 行 + 普通商品 1 行');
assert.strictEqual(Number(out[0].combo_product_id), 7, '保留第一次出现的那行');
assert.strictEqual(Number(out[0].quantity), 1);
assert.strictEqual(Number(out[1].product_id), 200);
});
it('多个不同赠品各自保留 1 行,数量都归 1', () => {
const rows = [
row({ product_id: 100, quantity: 5 }),
row({ product_id: 101, quantity: 2 }),
row({ product_id: 100, quantity: 1 }),
row({ product_id: 101, quantity: 9 }),
];
const out = collapseUniqueGiftRows(rows, new Set([ 100, 101 ]));
assert.strictEqual(out.length, 2);
assert.deepStrictEqual(out.map(item => Number(item.product_id)), [ 100, 101 ]);
assert.deepStrictEqual(out.map(item => Number(item.quantity)), [ 1, 1 ]);
});
it('非赠品不受影响(数量原样保留)', () => {
const rows = [
row({ product_id: 100, quantity: 3 }),
row({ product_id: 100, quantity: 3 }),
row({ product_id: null, quantity: 2 }),
];
const out = collapseUniqueGiftRows(rows, new Set([ 999 ]));
assert.strictEqual(out.length, 3);
assert.deepStrictEqual(out.map(item => Number(item.quantity)), [ 3, 3, 2 ]);
});
it('空标记 / 空明细直接返回', () => {
const rows = [ row({ product_id: 100, quantity: 2 }) ];
assert.strictEqual(collapseUniqueGiftRows(rows, new Set()).length, 1);
assert.strictEqual(collapseUniqueGiftRows(rows, new Set()).at(0).quantity, 2);
assert.deepStrictEqual(collapseUniqueGiftRows(null, new Set([ 100 ])), []);
assert.deepStrictEqual(collapseUniqueGiftRows([], [ 100 ]), []);
});
});

View File

@ -0,0 +1,89 @@
'use strict';
const { app, assert } = require('egg-mock/bootstrap');
describe('service/orderItemResolve 订单唯一赠品收敛(真实库 + 回滚)', () => {
it('同一赠品的多条明细只落一行、数量 1', async () => {
const ctx = app.mockContext({ state: { principalId: 3 } });
const t = await ctx.model.transaction();
try {
const principalId = 3;
const now = new Date();
const product = await ctx.model.Product.create({
principal_id: principalId,
item_code: `TMP-GIFT-${Date.now()}`,
item_name: 'TMP gift',
retail_price: 0,
is_order_unique_gift: 1,
}, { transaction: t });
// 店铺商品绑定到该赠品:这样展开才会落到 product_id
const shopProduct = await ctx.model.ShopProduct.create({
principal_id: principalId,
shop_id: 18,
outer_item_id: 'tmp-item',
outer_sku_id: 'tmp-sku',
title: 'TMP gift shop product',
stock: 0,
status: 1,
bind_type: 1,
product_id: product.id,
}, { transaction: t });
const order = await ctx.model.Order.create({
principal_id: principalId,
order_no: `TMP-${Date.now()}`,
order_type: 1,
total_amount: 0,
pay_amount: 0,
receiver: 'TMP',
}, { transaction: t });
await ctx.model.OrderIndex.create({
id: order.id,
principal_id: principalId,
order_no: order.order_no,
parent_order_no: order.order_no,
current_status: 'pending',
current_table: 'pending',
created_at: now,
updated_at: now,
}, { transaction: t });
// 两条平台明细都命中同一赠品(模拟两份组合/多数量)
for (const idx of [ 1, 2 ]) {
await ctx.model.OrderStatusItem.create({
principal_id: principalId,
order_id: order.id,
shop_id: 18,
order_line_no: String(idx),
item_code: shopProduct.outer_item_id,
item_name: 'TMP line',
plan_qty: 3,
quantity: 3,
actual_price: 0,
shop_product_id: shopProduct.id,
product_id: product.id,
item_type: 1,
parse_status: 1,
outer_item_id: 'tmp-item',
outer_sku_id: 'tmp-sku',
platform_snapshot: { line_no: String(idx), item_code: 'tmp-item', plan_qty: 3, actual_price: 0 },
}, { transaction: t });
}
await ctx.service.orderItemResolve.rebuildOrderItems([ order.id ], { transaction: t });
const after = await ctx.model.OrderStatusItem.findAll({
where: { order_id: order.id },
attributes: [ 'product_id', 'quantity', 'plan_qty' ],
raw: true,
transaction: t,
});
console.log('rows after rebuild:', JSON.stringify(after));
assert.strictEqual(after.length, 1, 'two sources of the same gift collapse into one row');
assert.strictEqual(Number(after[0].quantity), 1);
assert.strictEqual(Number(after[0].plan_qty), 1);
assert.strictEqual(Number(after[0].product_id), Number(product.id));
} finally {
await t.rollback();
}
});
});

View File

@ -37,6 +37,8 @@ export interface ProductItem {
is_sn_mgmt: string
is_shelf_life_mgmt: string
is_batch_mgmt: string
/** 是否订单唯一赠品:1 是(整单只落一行、数量 1)0 否 */
is_order_unique_gift: number
tag_price: number | string | null
retail_price: number | string
cost_price: number | string | null
@ -96,6 +98,8 @@ export interface ProductPayload {
is_sn_mgmt?: string
is_shelf_life_mgmt?: string
is_batch_mgmt?: string
/** 是否订单唯一赠品:1 是(整单只落一行、数量 1)0 否 */
is_order_unique_gift?: number
tag_price?: number | null
retail_price: number
cost_price?: number | null

View File

@ -2,6 +2,7 @@
import { computed, onMounted, reactive, ref } from 'vue'
import { useRoute } from 'vue-router'
import { ElMessage, ElMessageBox, type FormInstance, type FormRules, type UploadFile, type UploadInstance } from 'element-plus'
import { QuestionFilled } from '@element-plus/icons-vue'
import {
getProducts,
createProduct,
@ -46,6 +47,7 @@ const query = reactive({
brand_name: '',
stock_unit: '',
subsidiary_id: '' as string | number,
is_order_unique_gift: '' as string | number,
status: '' as string | number,
})
@ -58,6 +60,7 @@ const { loading, list, total, elapsed, fetchList, search, handlePageChange, hand
if (!params.brand_name) delete params.brand_name
if (!params.stock_unit) delete params.stock_unit
if (params.subsidiary_id === '') delete params.subsidiary_id
if (params.is_order_unique_gift === '') delete params.is_order_unique_gift
if (params.status === '') delete params.status
return getProducts(params)
},
@ -69,6 +72,7 @@ function reset() {
query.brand_name = ''
query.stock_unit = ''
query.subsidiary_id = ''
query.is_order_unique_gift = ''
query.status = ''
search()
}
@ -80,6 +84,7 @@ const exportFilters = computed(() => ({
brand_name: query.brand_name,
stock_unit: query.stock_unit,
subsidiary_id: query.subsidiary_id,
is_order_unique_gift: query.is_order_unique_gift,
status: query.status,
}))
@ -213,6 +218,7 @@ const form = reactive({
is_sn_mgmt: 'N',
is_shelf_life_mgmt: 'N',
is_batch_mgmt: 'N',
is_order_unique_gift: 0,
tag_price: null as number | null,
retail_price: 0,
cost_price: null as number | null,
@ -245,6 +251,7 @@ const EMPTY_FORM = {
is_sn_mgmt: 'N',
is_shelf_life_mgmt: 'N',
is_batch_mgmt: 'N',
is_order_unique_gift: 0,
tag_price: null,
retail_price: 0,
cost_price: null,
@ -295,6 +302,7 @@ function openEdit(row: ProductItem) {
is_sn_mgmt: row.is_sn_mgmt || 'N',
is_shelf_life_mgmt: row.is_shelf_life_mgmt || 'N',
is_batch_mgmt: row.is_batch_mgmt || 'N',
is_order_unique_gift: Number(row.is_order_unique_gift) ? 1 : 0,
tag_price: toNumberOrNull(row.tag_price),
retail_price: Number(row.retail_price) || 0,
cost_price: toNumberOrNull(row.cost_price),
@ -549,6 +557,18 @@ onMounted(async () => {
<el-option v-for="o in subsidiaryOptions" :key="o.id" :label="o.name" :value="o.id" />
</el-select>
</el-form-item>
<el-form-item label="唯一赠品">
<el-select
v-model="query.is_order_unique_gift"
placeholder="全部"
clearable
style="width: 130px"
@change="search"
>
<el-option label="是" :value="1" />
<el-option label="否" :value="0" />
</el-select>
</el-form-item>
<el-form-item label="状态">
<el-select v-model="query.status" placeholder="全部" clearable style="width: 140px">
<el-option label="启用" :value="1" />
@ -599,6 +619,12 @@ onMounted(async () => {
<template #default="{ row }">{{ row.cc_locked ?? 0 }}</template>
</el-table-column>
<el-table-column prop="brand_name" label="品牌" width="100" />
<el-table-column label="唯一赠品" width="90" align="center">
<template #default="{ row }">
<el-tag v-if="Number(row.is_order_unique_gift) === 1" type="warning" size="small">赠品</el-tag>
<span v-else class="muted">-</span>
</template>
</el-table-column>
<el-table-column label="零售价" width="100" align="right">
<template #default="{ row }">{{ row.retail_price }}</template>
</el-table-column>
@ -843,6 +869,15 @@ onMounted(async () => {
<el-form-item label="批次管理">
<el-switch v-model="form.is_batch_mgmt" active-value="Y" inactive-value="N" />
</el-form-item>
<el-form-item label="订单唯一赠品">
<el-switch v-model="form.is_order_unique_gift" :active-value="1" :inactive-value="0" />
<el-tooltip
content="开启后:订单明细解析到该商品时整单只保留一行、数量固定 1(多数量、多个组合命中同一赠品都只落一条)"
placement="top"
>
<el-icon class="field-hint"><QuestionFilled /></el-icon>
</el-tooltip>
</el-form-item>
<el-divider content-position="left">图片</el-divider>
<el-form-item label="图片组" prop="images">
@ -987,6 +1022,14 @@ onMounted(async () => {
gap: 8px;
width: 100%;
}
.field-hint {
margin-left: 6px;
color: var(--el-text-color-placeholder);
cursor: help;
}
.muted {
color: var(--el-text-color-placeholder);
}
.select-with-add {
display: flex;
gap: 8px;

View File

@ -665,6 +665,31 @@ $documentID = $PrintDataList["task"]["documents"][0]["documentID"]; // = 运单
| `service/shopOrderGuard.voidPendingOrders/restorePendingOrders(shop)` | 店铺禁用时作废待审核订单、启用时恢复(只处理因禁用被暂停的单) |
| `service/externalPrintOrder.syncOrders(shop, account, { startTime, endTime })` | 拉取并写入店铺订单(手动/定时共用) |
### 6.1.1 订单明细解析:组合拆分与「订单唯一赠品」
订单明细按「店铺商品 → 系统商品 / 组合商品」展开成最小单位(`lib/orderItemExpand` + `service/orderItemResolve`):
| 绑定关系 | 明细行 |
|---|---|
| 系统商品 | 一行对一行,数量 = 平台数量 |
| 组合商品 | 拆成组合内每个子商品一行,数量 = 平台数量 × 组合内数量 |
| 未采集/未绑定 | 保留平台原样一行(`parse_status=2`) |
**订单唯一赠品**(`products.is_order_unique_gift = 1`,系统商品可配置、可筛选):
展开成最小单位后整单收敛——同一赠品商品只保留**第一行**、数量固定 **1**:
| 场景 | 结果 |
|---|---|
| 平台明细数量 3 | 1 行 × 1 |
| 买了 2 份同一个组合(组合里含该赠品) | 1 行 × 1 |
| 不同组合都含该赠品 | 1 行 × 1 |
| 多个不同赠品 | 各自 1 行 |
实现:`orderItemResolve.collapseUniqueGifts`(查 `products.is_order_unique_gift`)→
`orderItemExpand.collapseUniqueGiftRows`(纯函数收敛)。因为每次 `rebuildOrderItems`
都会在展开后收敛一次,重复重建不会把数量涨回去。注意:只影响 `order_status_items`
(订单页/推送仓库口径),老表 `order_items` 仍按平台明细逐行记录。
### 6.2 真实取号开关
```bash