# Yoone Subscriptions

为 WooCommerce 提供基础订阅能力：在单个产品层面配置订阅计划（周期、数量、订阅价、一次性购买选项），在前端展示订阅选项，并在购物车/订单中显示订阅摘要与按订阅规则计算价格。

## 功能概述

- 产品级订阅计划：周期（月/年）、默认订阅数量、订阅价格（可选）、是否允许一次性购买；
- 前端产品页展示订阅选项，显示每周期价格与相对常规价的折扣百分比；
- 加入购物车时记录订阅参数；
- 购物车行项目价格 = 每周期价格 × 周期系数（年=12）× 订阅数量 × 购物车数量；
- 购物车与订单中显示订阅摘要（购买方式、周期、订阅数量、每周期价格）。

## 安装说明

1. 将 `yoone-subscriptions` 目录放置到 `wp-content/plugins/` 下；
2. 在后台 → 插件 → 启用 “Yoone Subscriptions”；
3. 确保 WooCommerce 插件已启用。

## 配置指南

1. 后台 → 产品 → 编辑某个产品；
2. 在“订阅计划”标签页：
   - 启用订阅；
   - 选择订阅周期（月/年）；
   - 设置默认订阅数量（前端默认值，可修改）；
   - 设置订阅价格（每周期、可选，留空则使用产品常规价）；
   - 是否允许一次性购买（允许时前端可切换一次性购买或订阅购买）。

## 前端效果

- 在产品页“加入购物车”按钮上方出现“订阅选项”框；
- 用户可选择一次性或订阅购买（若允许），选择周期与订阅数量；
- 显示每周期订阅价与相对常规价的折扣提示；
- 加入购物车后行项目价格按规则动态计算，购物车显示订阅摘要。

## 技术实现

- 主入口：`yoone-subscriptions.php`，注册资源、加载国际化、依赖检查、加载模块；
- 核心：`includes/class-yoone-subscriptions.php` 定义 postmeta 键名，提供 `get_config()` 与周期系数方法；
- 后台：`includes/admin/class-yoone-subscriptions-admin.php` 在产品编辑页添加订阅面板，保存 postmeta（含 nonce 与 sanitize）；
- 前端：`includes/frontend/class-yoone-subscriptions-frontend.php`
  - `woocommerce_before_add_to_cart_button` 渲染订阅选项；
  - `woocommerce_add_to_cart_validation` 校验参数；
  - `woocommerce_add_cart_item_data` 存储订阅数据到购物车项；
  - `woocommerce_get_item_data` 展示订阅摘要；
  - `woocommerce_before_calculate_totals` 动态设置行项目价格。

## 兼容性与支付

本插件基于 WooCommerce 标准购物车与订单流程，兼容 WooCommerce Payments API；
如需与 yoone-moneris-payments 深度集成，可在价格计算完成后通过订单元数据或支付网关参数传递订阅信息（留作扩展点）。

## 截图示例

- 后台产品编辑页 → 订阅计划面板（示例）
- 前端产品页 → 订阅选项区块（示例）

（请在实际部署后补充截图文件并更新此章节）

## 常见问题（FAQ）

1. 订阅价格为空会如何？
   - 使用产品常规价作为“每周期价格”。
2. 年周期如何计价？
   - 使用“年=12×月”的系数，即总价=每周期价×12×订阅数量×购物车数量。
3. 购物车数量与订阅数量的关系？
   - 总价以两者乘积计算。若不希望用户在订阅场景改变购物车数量，可考虑在前端或后台强制 sold individually（可后续扩展）。
4. 是否支持变体产品？
   - 面板在 simple/variable 产品上显示；变体粒度订阅可后续扩展至变体级别元数据。

## 性能与测试

- 针对大数据量场景（大量产品与并发请求）进行必要的缓存与数据库访问优化；
- 价格计算在购物车总计阶段进行，代码尽量保持简洁以降低开销；
- 与支付网关兼容性采用标准 WooCommerce 流程，原则上可与 yoone-moneris-payments 协同工作。

## 参考实现

- SUMO Subscriptions
- WooCommerce Subscriptions v8.0.0
- YITH WooCommerce Subscription Premium
- WPC Composite Products Premium v7.6.2

## 许可证

本插件源代码遵循与项目一致的许可协议（如未指定，默认 GPLv2 或更高）。