yoone-wc-subscriptions/README.md

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 或更高）。