oms/backend/app/lib/orderItemExpand.js
liufumingren 62df580393 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>
2026-11-08 11:28:18 +08:00

299 lines
11 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';
/**
* 订单明细「平台行 ↔ 最小单位行」互转。
*
* 平台订单一条明细在绑定组合商品后需要拆成组合内的子商品行(数量 = 平台数量 × 组合内数量,
* 单价取子商品自身零售价),这样出库推送、导出、统计都是最小单位;
* 解绑或变更绑定时再按 platform_snapshot 折叠回平台行重新展开。
*
* 可逆的前提:明细行的 platform_snapshot 保留平台原样
* (编码 / 名称 / 规格 / 图片 + 原行号 / 原数量 / 原单价),拆开的子行共用同一份快照。
*/
/**
* 截断字符串,避免超出表字段长度
* @param {*} value 原始值
* @param {number} [max] 最大长度
* @return {string} 处理后的字符串
*/
function text(value, max) {
const str = value == null ? '' : String(value).trim();
return max ? str.slice(0, max) : str;
}
/**
* 数值化(空值按 0)
* @param {*} value 原始值
* @return {number} 数值
*/
function number(value) {
const num = Number(value);
return Number.isFinite(num) ? num : 0;
}
/**
* 数量保留 3 位小数(与 plan_qty DECIMAL(12,3) 一致)
* @param {*} value 原始数量
* @return {number} 数量
*/
function roundQty(value) {
return Number(number(value).toFixed(3));
}
/**
* 金额保留 2 位小数(空值保持 null,表示平台未给价)
* @param {*} value 原始金额
* @return {number|null} 金额
*/
function roundMoney(value) {
if (value == null || value === '') return null;
const num = Number(value);
return Number.isFinite(num) ? Number(num.toFixed(2)) : null;
}
/**
* 由平台明细生成快照(写入 order_status_items.platform_snapshot)
* @param {Object} line 平台明细(统一结构:sku_code/name/spec/image/quantity/price/outer_item_id)
* @param {String|Number} lineNo 原行号
* @return {Object} 快照
*/
function buildSnapshot(line, lineNo) {
const data = line || {};
return {
item_code: text(data.sku_code || data.outer_item_id, 100) || null,
item_name: text(data.name, 255) || null,
sku_code: text(data.sku_code, 100) || null,
spec: text(data.spec, 255) || null,
image: text(data.image, 255) || null,
line_no: text(lineNo == null ? '' : lineNo, 20),
plan_qty: roundQty(data.quantity),
actual_price: roundMoney(data.price),
};
}
/**
* 明细行折叠回平台行:拆开的子行按快照的原行号归并回一行
* @param {Array} rows 订单明细行(order_status_items,任意顺序)
* @return {Array} 平台行(含 template 原行用于复制其它字段)
*/
function foldPlatformLines(rows) {
const groups = new Map();
for (const row of rows || []) {
const snapshot = row.platform_snapshot && typeof row.platform_snapshot === 'object' ? row.platform_snapshot : null;
const snapshotLineNo = snapshot && snapshot.line_no ? String(snapshot.line_no) : '';
// 没有快照行号的历史数据按行自身 id 独立成行,避免把不同平台行误并
const key = snapshotLineNo ? `L${snapshotLineNo}` : `R${row.id}`;
if (groups.has(key)) continue;
groups.set(key, {
line_no: snapshotLineNo || text(row.order_line_no, 20) || '',
item_code: snapshot ? snapshot.item_code : row.item_code,
item_name: snapshot ? snapshot.item_name : row.item_name,
sku_code: snapshot ? snapshot.sku_code : row.sku_code,
spec: snapshot ? snapshot.spec : row.spec,
image: snapshot ? snapshot.image : row.image,
plan_qty: snapshot && snapshot.plan_qty != null ? number(snapshot.plan_qty) : number(row.plan_qty),
actual_price: roundMoney(snapshot && snapshot.actual_price != null ? snapshot.actual_price : row.actual_price),
shop_product_id: row.shop_product_id == null ? null : Number(row.shop_product_id),
outer_item_id: row.outer_item_id || null,
outer_sku_id: row.outer_sku_id || null,
platform_snapshot: snapshot,
template: row,
});
}
return Array.from(groups.values()).sort((a, b) => {
const left = Number(a.line_no);
const right = Number(b.line_no);
if (Number.isFinite(left) && Number.isFinite(right) && left !== right) return left - right;
return String(a.line_no).localeCompare(String(b.line_no));
});
}
/**
* 展开平台行为明细行(最小单位)
* @param {Object} line foldPlatformLines 产出的平台行
* @param {Object} binding 绑定上下文 { shopProduct, product, combo, comboItems }
* @return {Array} 明细行(不含 principal_id / order_id / order_line_no)
*/
function expandPlatformLine(line, binding = {}) {
const template = line.template || {};
const base = {
shop_id: template.shop_id == null ? null : Number(template.shop_id),
shop_product_id: line.shop_product_id || null,
outer_item_id: line.outer_item_id || null,
outer_sku_id: line.outer_sku_id || null,
raw: template.raw || null,
platform_snapshot: line.platform_snapshot || null,
ext_code: template.ext_code == null ? null : template.ext_code,
inventory_type: template.inventory_type || 'ZP',
source_order_code: template.source_order_code == null ? null : template.source_order_code,
extend_props: template.extend_props && typeof template.extend_props === 'object' ? template.extend_props : null,
item_id: null,
stock_id: null,
};
const qty = roundQty(line.plan_qty);
const price = roundMoney(line.actual_price);
const { shopProduct, product, combo, comboItems } = binding;
// 绑定组合:拆成组合内每个子商品一行,数量 = 平台数量 × 组合内数量,单价取子商品零售价
if (combo) {
const children = (comboItems || []).filter(item => item && item.product_id);
if (children.length) {
return children.map((child, idx) => ({
...base,
item_code: text(child.item_code, 100) || null,
item_name: text(child.item_name, 255) || null,
sku_code: text(child.item_code, 100) || null,
spec: text(child.sku_property, 255) || null,
image: text(child.image, 255) || null,
plan_qty: roundQty(qty * (number(child.quantity) || 1)),
quantity: roundQty(qty * (number(child.quantity) || 1)),
actual_price: roundMoney(child.retail_price) == null ? 0 : roundMoney(child.retail_price),
retail_price: roundMoney(child.retail_price) == null ? 0 : roundMoney(child.retail_price),
product_id: Number(child.product_id),
combo_product_id: combo.id,
item_type: 1,
parse_status: 1,
parse_msg: null,
sub_source_order_code: childSubCode(base.source_order_code, idx + 1),
}));
}
// 组合没有配置子商品:保留组合行并提示,避免把组合编码推给仓库
return [{
...base,
item_code: text(combo.code, 100) || null,
item_name: text(combo.name, 255) || null,
sku_code: text(combo.code, 100) || null,
spec: line.spec || null,
image: line.image || null,
plan_qty: qty,
quantity: qty,
actual_price: price,
retail_price: price,
product_id: null,
combo_product_id: combo.id,
item_type: 2,
parse_status: 1,
parse_msg: '组合商品未配置子商品,无法拆分为最小单位',
}];
}
// 绑定系统商品:一行对一行,商品信息取系统商品
if (product) {
return [{
...base,
item_code: text(product.item_code, 100) || null,
item_name: text(product.item_name, 255) || null,
sku_code: text(product.item_code, 100) || null,
spec: text(product.sku_property, 255) || null,
image: text(product.image, 255) || null,
plan_qty: qty,
quantity: qty,
actual_price: price,
retail_price: price,
product_id: Number(product.id),
combo_product_id: null,
item_type: 1,
parse_status: 1,
parse_msg: null,
}];
}
// 未采集到店铺商品 / 店铺商品未绑定系统商品:保留平台原样一行
return [{
...base,
item_code: line.item_code || null,
item_name: line.item_name || null,
sku_code: line.sku_code || null,
spec: line.spec || null,
image: line.image || null,
plan_qty: qty,
quantity: qty,
actual_price: price,
retail_price: price,
product_id: null,
combo_product_id: null,
item_type: 0,
parse_status: 2,
parse_msg: shopProduct
? '店铺商品未绑定系统商品,已保留平台原样数据'
: '未采集到该店铺商品,已保留平台原样数据',
}];
}
/**
* 子行来源编码(保留原来源 + 序号,便于溯源)
* @param {string} [sourceCode] 原行来源编码
* @param {number} seq 子行序号
* @return {string|null} 子行来源编码
*/
function childSubCode(sourceCode, seq) {
const base = text(sourceCode, 40);
if (!base) return null;
return `${base}#${seq}`.slice(0, 50);
}
/**
* 补齐平台快照:保证每行都带完整快照(原行号 / 原数量 / 原单价),便于下次折叠回平台行
* @param {Object} line foldPlatformLines 产出的平台行
* @return {Object} 快照
*/
function normalizeSnapshot(line) {
const source = line.platform_snapshot && typeof line.platform_snapshot === 'object' ? line.platform_snapshot : {};
const snapshot = { ...source };
if (!snapshot.item_code) snapshot.item_code = line.item_code || null;
if (!snapshot.item_name) snapshot.item_name = line.item_name || null;
if (snapshot.sku_code === undefined) snapshot.sku_code = line.sku_code || null;
if (snapshot.spec === undefined) snapshot.spec = line.spec || null;
if (snapshot.image === undefined) snapshot.image = line.image || null;
if (!snapshot.line_no) snapshot.line_no = text(line.line_no, 20);
if (snapshot.plan_qty == null) snapshot.plan_qty = roundQty(line.plan_qty);
if (snapshot.actual_price == null) snapshot.actual_price = roundMoney(line.actual_price);
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,
};