oms/backend/app/lib/orderItemExpand.js
liufumingren ab630e7c01 feat(external-print): 订单拉取与定时同步,组合商品拆分为最小单位
后端能力:
- 接入店管家订单接口(/NewOrder/List),明细归一化后按店铺商品匹配系统商品/组合商品
- 新增 service/externalPrintOrder:手动与定时拉单共用入库逻辑,同时写入待审核状态分表
- 新增 schedule/fetchExternalShopOrders:按店铺配置的间隔自动拉单(最小 3 分钟,起点重叠 10 分钟)
- 新增 lib/orderItemExpand + service/orderItemResolve:平台行与最小单位行互转;
  绑定组合商品时按「数量 = 平台数量 x 组合内数量、单价取子商品零售价」拆成子商品行,解绑可还原
- 明细新增 platform_snapshot,保留平台原样(编码/名称/规格/图片/原行号/原数量/原单价)
- 店铺商品列表支持 has_unbound_order 筛选,订单列表支持 exclude_unbound(均已同步导出定义)
- 店铺商品只读化:移除新增/编辑/删除动作,仅保留查询与绑定;
  同步商品时平台已不存在的商品自动清理(未绑定且未被订单引用直接删除,已绑定或被引用仅下架)
- 新增 scripts/rebuild-order-items 存量明细重建脚本,新增 orderItemExpand 单测(8 项)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-03 03:29:09 +08:00

266 lines
9.8 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;
}
module.exports = {
buildSnapshot,
normalizeSnapshot,
foldPlatformLines,
expandPlatformLine,
};