# 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`

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