2026-10-31-bundle-redesign-design.md 12 KB

商品套餐独立模型重写设计

日期:2026-10-31 状态:待评审 范围:cfc-backend(Spring Boot 2.7.18 / MyBatis-Plus / MySQL 8.0.34)、cfc-web(管理端 Vue2 + Element UI)、cfc-frontend(消费端 uni-app)

1. 背景与意图

代码库目前存在两套并行的「套餐/组合」机制,均与业务目标不符:

机制 归属 现状 问题
combo(product_sku_combo_items) SKU 级:SKU 可作为「组合」变体 迁移434 建表;SKU 编辑器「商品组合」模式;下单时扣子商品库存(deductComboStock/restockComboOrder 及 3 处回补) 组合被当作 SKU 变体处理,违反「组合≠SKU」
bundle(product_bundle_items) product 级:product_type='bundle' 独立商品 + bundle_sku_id 锚点 迁移435;ProductEdit 套餐编辑;BundlePricingCalculator 购物车自动计价(saving>0 才触发);消费端 cart.vue 自动展示已享套餐价 自动合并计价,用户要的是「提示 + 一键替换」

用户确认的新设计(2026-10-31):

  • 套餐 = 独立商品:有自己的 SKU(售价/库存)、主图、上下架,用户直接加购下单,下单/支付只扣套餐 SKU 自身库存,不扣子商品库存。
  • 组合/套餐内容 ≠ SKU:内容是「一个商品套餐上包含哪些商品」的定义——子商品 SKU(精确到规格)× 数量。
  • 购物车结算优惠购买:仅当勾选商品恰好凑成某套餐全部内容、且 套餐价 < 子商品单买总和 时,提示「一键替换为套餐」(把勾选子商品替换为套餐商品后继续结算);否则不提示,按原商品价。
  • 线上两表均 0 数据(combo items 0、bundle items 0、bundle 商品 0)——无需数据迁移,可整体删除旧模型。

决策:重写全新套餐模型,整体替换上述两套机制。

2. 目标 / 非目标 / 反目标

目标

  • 套餐作为独立在售商品(product_type='bundle'),用户直接加购、下单、支付、售后。
  • 套餐可配置「包含清单」:子商品 SKU × 数量(SKU 级精确,跨分类可选)。
  • 套餐 SKU 独立售价/库存;套餐订单只动套餐 SKU 库存。
  • 套餐详情页展示「内含 A×2、B×1」,订单按套餐整体展示。
  • 购物车结算勾选时:命中套餐且套餐价 < 子商品总和 → 提示「一键替换为套餐」;替换后订单按套餐商品结算。

非目标

  • 不做「套餐内子商品可单独购买/联动库存」(详情仅展示清单)。
  • 不做套餐多规格商品化(套餐以单规格为主)。
  • 不做「购物车自动合并计价」(旧 bundle 行为)——改为提示 + 用户确认替换。

反目标(即使技术上能做也不要)

  • 套餐 SKU 下单时扣减/回补子商品库存(旧 combo 行为)。
  • 库存校验依赖子商品库存(旧 checkBundleStock)。
  • 前端自动应用套餐优惠而不经用户确认(旧 bundlePromo 自动扣减)。
  • 保留两套并行机制造成语义混乱。

3. 约束

  • 生产库目前无套餐/组合数据 → 新表直接创建、旧表直接删除(幂等迁移)。
  • 套餐价格比较基准:套餐 SKU 售价(分)vs 子商品 SKU 单买价合计(分),均以「在下单口径下的结算单价」计算。
  • 替换操作必须防篡改:数量、份数、金额一律以后端重算为准。
  • 迁移走 DatabaseInitializer.runMigrations() 幂等模式,并同步 schema.sql。
  • MySQL 8.0:索引/唯一键不得使用函数表达式(历史教训)。

4. 新数据模型

products(沿用,无 schema 变更)

  • product_type='bundle' 表示套餐商品(现有枚举值)。
  • 套餐商品的主图/描述/详情沿用现有 product 字段。

product_skus(沿用)

  • 套餐自身的售价/库存/上下架走现有 SKU 表。
  • 套餐通常单 SKU(单规格);内容按 SKU 键控,天然支持未来多规格。

新表 product_combo_items(套餐内容,商品级定义、SKU 级键控)

列 类型 说明
id BIGINT PK AUTO
combo_sku_id BIGINT NOT NULL 套餐 SKU id(内容归属;套餐单规格时即套餐唯一 SKU)
child_product_id BIGINT NOT NULL 子商品
child_sku_id BIGINT NOT NULL 子商品 SKU(必填,精确到规格)
quantity INT NOT NULL DEFAULT 1 数量(>0)
created_at DATETIME
  • UNIQUE KEY uk_combo_sku_child (combo_sku_id, child_sku_id)。
  • 不引用旧命名(product_sku_combo_items/product_bundle_items),避免与旧机制混淆。

删除

  • 旧表 product_sku_combo_items、product_bundle_items(0 数据,幂等 drop)。

5. 后端改动(cfc-backend)

5.1 新增

  • entity/ProductComboItem.java + mapper/ProductComboItemMapper.java。
  • 套餐内容接口(admin):
    • saveComboItems(comboProductId, items[]):先删后插;校验 combo 商品 product_type='bundle'、child_sku 存在且属于 child_product、quantity>0。
    • listComboItems(comboProductId):返回带子商品名称/图/规格描述的清单。
  • 购物车套餐 offer 检测(服务端权威):对勾选结算行聚合 (child_product_id, child_sku_id): qty,遍历所有套餐商品内容:
    • 覆盖判定:每个 child 的数量 ≥ 组成数量,取可覆盖组数 groups = min over children(floor(have/need));
    • 子商品单买总和 = 覆盖组内各 child 实际数量和 × 下单口径单价;
    • 套餐价 = 套餐 SKU 售价 × groups(按覆盖组计),仅当 套餐价 < 子商品单买总和(节省额 > 0)才返回 offer;
    • 命中多个套餐取节省额最大者(同额取先出现,确定性);offer 含:套餐 SKU id、套餐名、覆盖组数、套餐价、子商品单买总和、节省额。
  • 购物车「一键替换」接口:replaceCartWithCombo(userId, checkedCartItemIds, comboProductId, groups):
    • 后端重算覆盖组数(不信任前端);
    • 从购物车移除足额子商品(按 (product, sku) 扣减数量,剩余不足组数的余量保留);
    • 加入套餐 SKU 商品 groups 份,返回新购物车。

5.2 删除

  • entity/ProductSkuComboItem.java、mapper/ProductSkuComboItemMapper.java、ProductSku.comboItems 字段。
  • entity/ProductBundleItem.java、mapper/ProductBundleItemMapper.java。
  • pricing/ 包:BundlePricingCalculator、BundleDef、BundleChild、BundleHit、BundleDiscountResult、BundlePricingService、LineItem。
  • ProductSkuService:combo 相关(fillComboItems/validateComboItems/saveComboItems/buildComboSummary/hasComboItems)。
  • CartService:SKU 组合摘要(specDesc)、attachBundleMatches、computeBundlePromo、toBundlePromo、bundle 相关 import。
  • ProductOrderService:combo 子商品库存扣减/回补(deductComboStock、restockComboOrder、3 处回补调用、combo 行特殊处理)、checkBundleStock 调用(3 处)、bundleDiscount 应用(结算价)。
  • InventoryService:checkBundleStock、saveBundleItems、listBundleItems 及 bundle 出库联动逻辑。
  • ProductController.detail:SKU comboItems 组装。
  • AdminProductPickerController:bundle 相关(视情况)。

5.3 调整

  • 套餐商品下单:按普通商品流程(套餐 SKU 自身库存校验 + 扣减),订单行展示套餐商品 + 内含清单快照。
  • 详情接口:套餐商品挂「内含清单」(combo items + 子商品名/SKU 规格/数量),供消费端展示。

5.4 迁移

  • 迁移436(下一编号):CREATE TABLE IF NOT EXISTS product_combo_items ... + DROP TABLE IF EXISTS product_sku_combo_items, product_bundle_items(0 数据安全)。
  • schema.sql 同步新表。

6. 前端改动

6.1 cfc-web(管理端)

  • ProductEdit.vue:productType='bundle' 时展示「套餐内容编辑」:跨分类搜索子商品 → 选子商品 SKU 规格 + 数量(复用 ProductPicker 的多选+SKU 选择能力);保存调 saveComboItems,加载调 listComboItems。替换现有 bundleItems 编辑。
  • ProductSkuEditor.vue:移除「商品组合」模式(radio 只留「规格变体」),删除 comboItems/ProductPicker 组合调用与相关样式;保留单选/多选公共组件 ProductPicker 无需改动或按需精简。

6.2 cfc-frontend(消费端 uni-app)

  • pages/shop/cart/cart.vue:
    • 删除「已享套餐价」自动优惠区块与总价扣减(bundlePromo 展示/applyBundleDiscount)。
    • 结算勾选后渲染套餐 offer 提示:「这 N 件组成套餐「XX」,套餐价 ¥Y(省 ¥Z)」+「一键替换为套餐」按钮;点击调替换接口 → 刷新购物车与选中态。
  • pages/shop/checkout/checkout.vue:适配(移除自动优惠展示;若有未处理 offer 时不自动保留)。
  • utils/bundle-pricing.js:改为套餐 offer 展示辅助(安全读取后端 offer 字段,纯展示,杜绝前端算金额)。

7. 交互流程(购物车优惠购买)

用户在购物车勾选 A×2 + B×1 准备结算
  │
  ├─ 后端 offer 检测:A、B 恰为套餐X内容,套餐X价 < A+B 单买总和?
  │    是 → 购物车顶部提示「这 3 件组成套餐「XX」,套餐价 ¥Y(省 ¥Z)」[一键替换为套餐]
  │    否 → 不提示,按原商品价结算
  │
  └─ 用户点「一键替换为套餐」
        → 后端重算:购物车删除 A×2、B×1,加入「套餐X」SKU ×1
        → 刷新购物车 → 用户继续按套餐商品结算

边界:

  • 覆盖不足(如购物车 A×1+B×1,套餐需 A×2+B×1)→ 无 offer。
  • 超量(A×4+B×2 = 可覆盖 2 组)→ offer 提示可替换 2 份,余量(若有)保留。
  • 套餐商品已被直接加购 → 不触发替换提示(避免同套餐重复)。
  • 套餐价 ≥ 子商品总和 → 无 offer(原商品价)。
  • 替换后购物车金额以后端重算为准(防篡改)。

8. 测试计划

后端

  • 单元测试(计算逻辑纯度):
    • 覆盖检测:恰好覆盖 / 超量 / 不足 / 跨 child 共用行。
    • 节省额规则:套餐价 = 子商品总和 → 无 offer;套餐价 > 总和 → 无 offer;套餐价 < 总和 → offer。
    • 多套餐候选:取节省额最大者;同额确定性。
  • 接口/服务测试:
    • saveComboItems/listComboItems 校验(非 bundle 商品拒绝、child_sku 不存在拒绝、quantity≤0 拒绝)。
    • replaceCartWithCombo:购物车行扣减/新增/余量保留/防篡改(组数后端重算)。
    • 下单:套餐订单仅扣套餐 SKU 库存;子商品库存不变;支付/取消回补只对套餐 SKU。
  • 删除/改写旧测试:ProductSkuComboServiceTest、ProductOrderComboStockTest(组合语义已删除)。

前端

  • cfc-web:jest(ProductEdit 套餐内容编辑逻辑;ProductSkuEditor 无组合模式)。既有 90 测试回归。
  • cfc-frontend:jest(offer 展示辅助;购物车替换按钮触发;移除 bundlePromo 自动扣减相关断言)。

9. 迁移与兼容

  • 数据迁移:无(0 数据)。仅结构迁移(建新表、删旧表)。
  • 兼容:消费端/管理端与后端同批部署;后端删除旧接口前先保证新旧前端不再调用(管理端与消费端同步发布)。
  • 已存在套餐商品(0 个)无需转换。

10. 实施者决策(我的裁定,可按约定调整)

  • 新表命名 product_combo_items、归属列 combo_sku_id(命名决策,避开旧表名)。
  • 替换算法:可用覆盖组数 = floor(have/need) 逐 child 取最小;余量保留。
  • 多套餐候选:仅提示节省额最大的 1 个(确定性:同额取先出现)。
  • 套餐内容编辑复用 ProductPicker 的子商品/SKU 选择能力(避免重复造轮子)。
  • 迁移编号暂定 436(上线前以数据库当前最大迁移号为准调整)。