210 lines
12 KiB
Markdown
210 lines
12 KiB
Markdown
# 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/实际开发/订阅制` 下的规范文档，并在代码中搜索对应模块的实现以获取最新内容。 |