zksu
/
subscription
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
subscription/README.md

12 KiB
Raw Blame History

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