# Yoone Subscriptions 插件

Yoone Subscriptions 是一个面向 WooCommerce 的订阅管理插件，用于实现订阅商品、自动续费、支付令牌管理、捆绑产品订阅、日志与分析、以及前后台管理页面等完整功能。

## 功能总览

- 订阅生命周期管理：创建、激活、暂停、恢复、取消、过期处理
- 续费与账期：续费订单创建、支付处理、下一次支付日期计算
- 支付集成：Moneris 网关（令牌化支付）、支付令牌管理
- 捆绑产品：支持将多个商品组合为订阅捆绑，前后台配置与展示
- 前台：我的订阅、订阅详情、订阅选项等模板
- 后台：订阅列表与编辑、捆绑产品列表与编辑、日志查看与分析
- 定时任务：自动处理续费、过期与清理任务
- 日志与分析：结构化日志记录、错误与告警分析
- API 与 AJAX：提供必要的接口与管理操作
- 测试：内置测试套件与场景测试脚本，辅助验证完整流程

## 环境与依赖

- WordPress 6.x 及以上
- WooCommerce 6.x 及以上（需启用）
- PHP 7.4 及以上
- Moneris 支付网关（可选，启用令牌化支付）

## 安装与启用

1. 将 yoone-subscriptions 插件拷贝到 `wp-content/plugins/yoone-subscriptions` 目录。
2. 在 WordPress 后台的“插件”页面启用该插件。
3. 在 WooCommerce 设置中启用并配置 Moneris 网关（如使用令牌化支付与自动续费）。
4. 访问后台的“订阅管理”和“捆绑产品”页面进行配置。

## 代码结构与架构

插件主入口文件：`yoone-subscriptions.php`
- 负责加载类文件、初始化前台与后台逻辑、注册网关与产品类型、挂载 AJAX 与定时任务。

核心目录：`includes/`
- abstracts/
  - `abstract-yoone-data.php`：数据抽象基类，统一提供读写、保存、删除、属性管理等通用能力。
- interfaces/
  - `interface-yoone-payment-gateway.php`：支付网关接口（扩展新网关的契约）。
  - `interface-yoone-subscription.php`：订阅接口（统一订阅对象的行为约束）。
- subscription/
  - `class-yoone-subscription.php`：订阅核心类，包含生命周期方法（activate/pause/resume/cancel）、续费处理（process_renewal / create_renewal_order / process_renewal_payment）、账期计算（calculate_next_payment_date / add_billing_period）、校验与日志、数据库操作（read/create/update/delete）。
- payment/
  - `class-yoone-moneris-gateway.php`：Moneris 支付网关集成，处理支付与令牌化逻辑。
  - `class-yoone-payment-token.php`：支付令牌模型，定义字段（customer_id、gateway_id、token、card_type、last_four、expiry 等）、默认令牌管理、有效性与过期判断、数据库读写、静态查询与清理。
- bundle/
  - `class-yoone-bundle.php`：捆绑产品核心逻辑。
  - `class-yoone-bundle-frontend.php`：捆绑产品的前端展示逻辑。
- admin/
  - `class-yoone-admin.php`：后台初始化与页面管理。
  - `class-yoone-admin-logs.php`：后台日志页面与工具。
  - `class-yoone-bundles-list-table.php`、`class-yoone-subscriptions-list-table.php`：列表页表格展示。
- frontend/
  - `class-yoone-frontend.php`：前端初始化与路由。
- 其他核心类
  - `class-yoone-install.php`：安装与升级（创建数据库表）。
  - `class-yoone-ajax.php`：AJAX 操作处理。
  - `class-yoone-api.php`：后端 API（如获取支付令牌、订阅数据等）。
  - `class-yoone-cron.php`：定时任务注册与处理。
  - `class-yoone-logger.php`：日志记录。
  - `class-yoone-log-analyzer.php`：日志分析与错误告警。
  - `class-yoone-helper.php`：通用帮助方法。

静态资源：`assets/`
- css/
  - `yoone-admin.css`、`yoone-frontend.css`：后台与前端样式。
- js/
  - `yoone-admin.js`、`yoone-frontend.js`、`admin-logs.js`、`bundle-frontend.js`：交互脚本。

模板视图：`templates/`
- admin/
  - `bundle-add.php`、`bundle-edit.php`、`bundle-list.php`：捆绑产品后台页面。
  - `subscription-edit.php`、`subscription-list.php`：订阅后台页面。
- frontend/
  - `bundle-product.php`、`subscription-options.php`、`subscription-details.php`、`my-subscriptions.php` 等：前端展示页与用户中心。
- emails/
  - `subscription-renewal.php`、`subscription-cancelled.php`：邮件模板。
- subscription/
  - `subscription-options.php`：订阅商品配置信息展示。
- myaccount/
  - `subscriptions.php`：我的订阅入口页面。

测试：`tests/`
- `class-yoone-test-suite.php`：测试套件（AJAX 驱动，支持单独运行订阅/支付/捆绑/定时任务测试）。
- `test-config.php`：测试配置与辅助方法（创建测试用户与产品、环境信息等）。
- `test-subscription-flow.php`：订阅全流程场景测试（创建/激活/暂停/恢复/续费/取消）。
- `test-payment-integration.php`：支付集成测试（令牌创建与验证、网关配置检查、支付数据校验）。
- `test-bundle-products.php`：捆绑产品场景测试（创建、价格计算、订阅建立、库存与子品管理）。
- `test-cron-jobs.php`：定时任务测试（续费/过期/清理任务的调度与模拟）。
- `run-tests.php`：浏览器端测试运行入口页面（展示环境信息与测试结果）。

## 数据模型与数据库表

由 `class-yoone-install.php` 管理数据库结构（安装/升级时创建），主要表包括：
- `wp_yoone_subscriptions`：订阅主表，包含客户、状态、账期、下一次支付日期等字段。
- `wp_yoone_payment_tokens`：支付令牌表，包含令牌、网关 ID、卡类型、后四位、过期信息、是否默认等。
- `wp_yoone_logs`：日志记录表（包含类型、消息、时间等）。
- 其他可能的辅助表（如订阅项目）按实现情况存在。

数据抽象层通过 `Abstract_Yoone_Data` 统一提供：
- `read/create/update/delete` 数据库操作
- `get_prop/set_prop/set_props` 属性管理
- `save()` 保存与触发钩子

## 订阅生命周期与续费流程

- 生命周期方法：
  - `activate()` 激活订阅（更新状态、保存、记录日志、触发动作）。
  - `pause()` 暂停订阅；`resume()` 恢复订阅。
  - `cancel()` 取消订阅（支持 pending-cancel 与彻底取消策略）。
- 续费与账期：
  - `process_renewal()` 续费流程入口。
  - `create_renewal_order()` 创建续费订单（用于 WooCommerce 支付）。
  - `process_renewal_payment()` 处理续费支付（结合令牌与网关）。
  - `calculate_next_payment_date()`、`add_billing_period()` 负责下一次支付日期计算。
- 校验与辅助：
  - `can_be_activated/can_be_renewed/can_be_paused/can_be_cancelled/is_trial` 等校验方法。
  - `add_log/get_logs` 日志记录与读取。
- 钩子与扩展：
  - 如 `yoone_subscription_updated`、`yoone_subscription_cancelled` 等动作。

## 支付集成与令牌化

- Moneris 网关（`class-yoone-moneris-gateway.php`）：
  - 负责与 Moneris 的对接、令牌化与交易处理。
  - 后台配置项（Store ID、API Token 等），通过 WooCommerce 网关设置管理。
- 支付令牌（`class-yoone-payment-token.php`）：
  - 字段：`customer_id`、`gateway_id`、`token`、`token_type`、`card_type`、`last_four`、`expiry_month/year`、`is_default`、`expires_at` 等。
  - 方法：`is_valid()`、`is_expired()`、`is_card_expired()`；`set_default()` 会自动取消其他令牌默认状态。
  - 静态查询：`get_customer_tokens($customer_id, $gateway_id = '')`、`get_default_token($customer_id, $gateway_id)`、`get_by_token($token, $gateway_id)`、`cleanup_expired_tokens()`。

> 与《订阅支付全流程.md》对齐：续费时优先使用客户默认令牌，若令牌无效或过期则记录日志并标记失败，支持重试或通知用户更新支付方式。

## 捆绑产品

- 后台模板：`templates/admin/bundle-add.php`, `bundle-edit.php`, `bundle-list.php`。
- 前端模板：`templates/frontend/bundle-product.php`、`templates/bundle/bundle-options.php`。
- 逻辑类：`class-yoone-bundle.php`（组合商品与定价策略）、`class-yoone-bundle-frontend.php`（展示与交互）。
- 常见场景：
  - 在捆绑产品中配置子产品及折扣，订阅价格与账期通过产品元数据（如 `_yoone_subscription_price`、`_yoone_subscription_period`、`_yoone_subscription_period_interval`）进行管理。

## 定时任务（Cron）

由 `class-yoone-cron.php` 注册与维护，典型钩子：
- `yoone_process_subscription_renewals`：检查并处理到期续费。
- `yoone_process_expired_subscriptions`：过期订阅处理。
- `yoone_cleanup_logs`：日志清理与归档。
- `yoone_cleanup_expired_tokens`：清理过期支付令牌。

> 与《流程跑通.md》对齐：确保在站点激活后按预设频率调度，考虑 WooCommerce 与 WordPress Cron 的时差与站点请求触发机制。

## 日志与分析

- `Yoone_Logger`：统一日志记录，支持 info/warning/error 等级。
- `Yoone_Log_Analyzer`：分析日志数据、聚合错误与告警，辅助排查问题与生成报告。
- 后台“日志”页面：支持筛选、搜索与简单可视化（由 `admin-logs.js` 与相关模板驱动）。

## API 与 AJAX

- `class-yoone-api.php`：提供订阅数据与支付令牌相关接口（示例：获取用户令牌列表）。
- `class-yoone-ajax.php`：处理后台或前台触发的 AJAX 操作，如运行测试套件、更新订阅状态等。

## 前后台页面与模板

- 后台：订阅列表/编辑、捆绑产品列表/编辑、日志分析。
- 前台：我的订阅、订阅详情、订阅选项、捆绑商品展示。
- 模板可通过主题覆盖机制进行自定义，建议保持字段与钩子兼容。

## 测试与质量保障

- 浏览器运行入口：`wp-content/plugins/yoone-subscriptions/run-tests.php`。
- 测试套件：
  - 订阅流程（`test-subscription-flow.php`）
  - 支付集成（`test-payment-integration.php`）
  - 捆绑产品（`test-bundle-products.php`）
  - 定时任务（`test-cron-jobs.php`）
- 支持通过 AJAX 在后台界面运行不同测试类型，并生成概要与详细报告。

## 扩展指南

- 新增支付网关：实现 `interface-yoone-payment-gateway.php` 并在主入口注册，参考 Moneris 实现。
- 自定义订阅行为：扩展 `class-yoone-subscription.php` 的钩子与动作，或在子类中覆盖方法。
- 自定义模板：将模板文件复制到主题并保持关键字段与钩子一致。
- 数据与日志：通过 `Abstract_Yoone_Data` 统一操作数据模型，并记录关键流程的日志，便于分析与测试。

## 与内部文档的对应关系

- 《订阅需求.md》：覆盖订阅状态、账期、试用期、取消策略与用户交互；对应 `class-yoone-subscription.php` 与相关模板。
- 《订阅支付全流程.md》：覆盖令牌化支付、续费订单与失败重试；对应 `class-yoone-moneris-gateway.php` 与 `class-yoone-payment-token.php`。
- 《流程跑通.md》：覆盖从创建订阅到取消的全流程、定时任务调度与测试验证；对应 `tests/` 目录与 `class-yoone-cron.php`。
- 《技术需求与实现参考.md》《自实现技术设计文档.md》：对应整体架构、抽象层与扩展点；对应 `includes/` 目录下的抽象类、接口与核心模块。

## 常见问题与排查

- 令牌无效或过期：检查 `yoone_payment_tokens` 表、令牌过期字段、默认令牌设置，查看日志分析页面。
- 续费失败：查看续费订单与支付响应，确认网关配置（Store ID / API Token），检查定时任务是否被正确调度。
- 模板未生效：确认主题覆盖路径与文件名、清理缓存、检查钩子绑定是否正确。
- 测试失败：使用 `run-tests.php` 查看详细报错，定位对应类与方法进行修复。

## 开发建议

- 遵循 WooCommerce 与 WordPress 的编码规范及钩子机制。
- 对关键流程（创建、续费、取消）添加日志记录，辅助运维与测试。
- 编写场景测试用例，覆盖主要业务路径与异常路径。
- 在开发环境中开启调试模式与错误日志，结合 `Yoone_Log_Analyzer` 分析问题。

---
如需进一步信息或与内部文档对齐的详细说明，请参考项目目录 `/Users/zksu/Developer/work/work-yoone/实际开发/订阅制` 下的规范文档，并在代码中搜索对应模块的实现以获取最新内容。