96 lines
5.1 KiB
Markdown
96 lines
5.1 KiB
Markdown
# 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`
|
||
|
||
这些插件实现更复杂的组合逻辑与定价；本插件以轻量的方式提供一个可扩展的基础框架。 |