Yoone Product Bundles (混装产品)

为 WooCommerce 提供一个基础的“混装产品（Bundle）”类型：

• 后台为某个产品配置：可混装的简单商品列表、最小混装数量、展示用的分类分组；
• 前端在该混装产品的产品页显示一个表单，按分类分组列出可混装商品，用户为每个商品填写数量；
• 当总数量达到或者超过“最小混装数量”时，允许加入购物车；
• 购物车中该混装产品的行项目价格 = 所选简单商品单价 × 数量 的总和；
• 购物车与订单行项目显示所选组件的摘要；

本插件是一个可运行的 MVP，结构清晰、注释完整，方便后续扩展（动态价格、库存校验、分组规则、变体商品支持、打包折扣等）。

安装与启用

1. 将插件目录 yoone-product-bundles 放置到站点的 wp-content/plugins/ 下。
2. 在 WordPress 后台 -> 插件 中启用 “Yoone Product Bundles (混装产品)”。
3. 确保 WooCommerce 已安装并启用。

使用步骤（后台）

1. 新建或编辑一个产品，在“产品类型”下拉中选择 “混装产品 (Yoone Bundle)”。
2. 在出现的 “混装产品” 标签页中配置：
   • 可混装商品：搜索并选择多个 simple product；
   • 最小混装数量：顾客选择的总数需不小于此值；
   • 展示分类：用于在前端按分类分组显示可混装商品（仅显示属于所选分类的商品）。
3. 发布或更新该产品。

前端体验

访问该混装产品的产品页：

• 页面按分类分组列出可混装商品，并显示每个商品的价格；
• 用户为每个商品填写数量，页面实时展示“当前选择数量”；
• 当选择总数达到最小混装数量后，“加入购物车”按钮自动可用；
• 加入购物车后，购物车中该混装产品的价格为所选商品价格总和，并显示所选内容的摘要；

技术实现概览

• 产品类型注册：Yoone_Product_Bundles 在 product_type_selector 中注册类型标识 yoone_bundle，并通过 woocommerce_product_class 映射到 WC_Product_Yoone_Bundle；
• 后台配置面板：Yoone_Product_Bundles_Admin 在产品编辑页添加一个标签页与面板，使用 WooCommerce 原生的 wc-product-search 组件搜索选择产品；数据保存在以下 postmeta：
  • _yoone_bundle_allowed_products (int[]) 可混装的产品ID列表；
  • _yoone_bundle_min_quantity (int) 最小混装数量；
  • _yoone_bundle_categories (int[]) 用于分组显示的 product_cat 分类ID列表；
• 前端表单与购物车：Yoone_Product_Bundles_Frontend
  • 通过 woocommerce_yoone_bundle_add_to_cart 钩子渲染模板 templates/single-product/add-to-cart/yoone-bundle.php；
  • 在 woocommerce_add_to_cart_validation 中校验总数量是否达到最小值；
  • 在 woocommerce_add_cart_item_data 中把所选组件（pid=>qty）存入购物车项；
  • 在 woocommerce_get_item_data 中展示购物车行项目的组件摘要；
  • 在 woocommerce_before_calculate_totals 中根据组件动态设置该行项目价格（基础价，不含税），确保结算金额正确；

目录结构

yoone-product-bundles/
├── yoone-product-bundles.php                // 插件入口
├── includes/
│   ├── class-yoone-product-bundles.php      // 核心：类型注册、读取配置
│   ├── class-yoone-product-type-bundle.php  // 产品类型对象 WC_Product_Yoone_Bundle
│   ├── admin/
│   │   └── class-yoone-product-bundles-admin.php
│   └── frontend/
│       └── class-yoone-product-bundles-frontend.php
├── templates/
│   └── single-product/add-to-cart/yoone-bundle.php // 前端表单模板
└── assets/
    ├── css/{admin.css, frontend.css}
    └── js/{admin.js, frontend.js}

钩子与扩展点

• 读取配置：Yoone_Product_Bundles::get_bundle_config($product)，返回 allowed_products/min_qty/categories；
• 可在 Yoone_Product_Bundles_Frontend::adjust_bundle_price() 中替换价格计算逻辑，例如引入折扣、不同计价规则；
• 可添加库存校验：在 validate_add_to_cart() 中检验每个组件的可售数量；
• 可将组件拆分为独立行项目：在 add_to_cart 阶段为每个组件添加到购物车，并将 bundle 项设为 0 价（当前实现为一个行项目合计价格）。

常见问题

1. 为什么“加入购物车”不可用？
   • 需要先达到“最小混装数量”；
   • 或者后台未配置可混装商品。
2. 价格是否含税？
   • 当前以 get_price() 基础价计算总价，不含税；实际显示与结算是否含税取决于 WooCommerce 税设置。可在价格调整钩子中自定义。
3. 是否支持变体商品？
   • MVP 仅支持 simple product；后续可扩展到变体商品与多层组合。

参考实现

可参考以下现有插件：

• woocommerce-product-bundles_v8.5.2
• wpc-composite-products-premium_v7.6.2
• woocommerce-composite-products_v11.0.1
• woo-product-bundle-premium_v8.3.5

这些插件实现更复杂的组合逻辑与定价；本插件以轻量的方式提供一个可扩展的基础框架。