# Yoone Subscriptions

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

本版本新增后台“面板式订阅计划”管理（可折叠面板），支持配置多个订阅计划并保存为产品元数据；保存时如存在至少一个计划会自动启用订阅。前端当前仍基于“基础字段”（周期/数量/价格）进行渲染与计价，订阅计划的前端选择将在后续版本提供。

## 功能概述

- 产品级订阅计划（基础字段）：周期（月/年）、默认订阅数量、订阅价格（可选）、是否允许一次性购买；
- 后台支持“多个订阅计划”的配置（名称、周期、每周期价格或折扣百分比）；保存时若存在计划将自动启用订阅；
- 前端产品页展示订阅选项，显示每周期价格与相对常规价的折扣百分比；
- 加入购物车时记录订阅参数；
- 购物车行项目价格 = 每周期价格 × 周期系数（年=12）× 订阅数量 × 购物车数量；
- 购物车与订单中显示订阅摘要（购买方式、周期、订阅数量、每周期价格）。

## 安装说明

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

## 配置指南

1. 后台 → 产品 → 编辑某个产品；
2. 在“订阅计划”标签页：
   - 启用订阅（保存时如存在订阅计划将自动开启，即使未勾选也会开启）；
   - 基础字段（仍生效，当前前端基于这些字段渲染与计价）：
     - 订阅周期（月/年）、默认订阅数量、订阅价格（每周期，留空表示使用产品常规价）、分级折扣规则（数量:折扣%）；
     - 是否允许一次性购买（允许时前端可切换一次性/订阅购买）。
   - 订阅计划面板（新增）：使用“新增订阅计划”按钮添加计划，面板内包含：
     - 计划名称、周期（月/年）、每周期价格（留空使用产品价）、折扣百分比（可选，10 表示约 9 折）。
     - 支持折叠/展开、删除计划。保存后计划以数组形式写入产品元数据。
   - 注：当前前端尚未提供“在产品页选择某个计划”的 UI，因此建议仍按需设置基础字段以保证前端行为；订阅计划的选择与联动价格将在后续版本实现。

## 前端效果

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

## 技术实现与设计

- 主入口：`yoone-subscriptions.php`，注册资源、加载国际化、依赖检查、加载模块；
- 核心：`includes/class-yoone-subscriptions.php` 定义 postmeta 键名，提供 `get_config()` 与周期系数方法；
- 后台：`includes/admin/class-yoone-subscriptions-admin.php`
  - 在产品编辑页添加订阅面板（simple/variable/yoone_bundle）；
  - 渲染基础字段与“订阅计划列表”（以表格输出，`assets/js/admin.js` 动态转换为可折叠面板）；
  - 保存 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` 动态设置行项目价格。
  - My Account：注册 `subscriptions` 端点与菜单项“我的订阅”，显示当前用户的订阅实例列表（数据来源于 `includes/models/class-yoone-subscriptions-db.php`）。
- 资源：
  - 后台：`assets/css/admin.css`（面板式样式）、`assets/js/admin.js`（隐藏旧字段、计划的新增/删除与折叠交互）
  - 前端：`assets/css/frontend.css`（简版样式）、`assets/js/frontend.js`（一次性/订阅模式的样式钩子）

## 兼容性与支付

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

## 截图示例

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

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

## 常见问题（FAQ）

1. 订阅价格为空会如何？
   - 使用产品常规价作为“每周期价格”。
2. 年周期如何计价？
   - 使用“年=12×月”的系数，即总价=每周期价×12×订阅数量×购物车数量。
3. 购物车数量与订阅数量的关系？
   - 总价以两者乘积计算。若不希望用户在订阅场景改变购物车数量，可考虑在前端或后台强制 sold individually（可后续扩展）。
4. 是否支持变体产品？
   - 面板在 simple/variable 产品上显示；变体粒度订阅可后续扩展至变体级别元数据。
5. 后台新增的“多个订阅计划”前端是否可选？
   - 当前版本尚未提供选择 UI，计划数据已保存并可用于后续扩展；当前前端渲染与计价仍基于基础字段。
6. 为什么 My Account 没有出现“我的订阅”？
   - 首次启用插件后，访问 设置 → 固定链接 → 保存 以刷新路由规则；或停用再启用插件。然后在“我的账户”页面即可看到“我的订阅”菜单。

## 性能与测试

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

## 参考实现

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

## 许可证

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