用途:本技能用于向 Stripe 网关添加新的支付方式,触发场景包括“add payment method”“new UPE method”以及在结账中支持某个支付方式。添加支付方式会涉及 PHP 与前端至少五处改动,漏改任何一处都会导致方法在结账中缺失或仅在部分界面出现。
主要改动(按顺序):一、在 includes/payment-methods/ 创建 class-wc-stripe-upe-payment-method-<id>.php,继承 WC_Stripe_UPE_Payment_Method,至少重写 get_id()、get_label()、get_icon() 以及能力标记(is_subscription_supported()、is_pre_order_supported()、货币与国家限制);若支持定期付款,还需引入 WC_Stripe_Subscriptions_Trait 并在网关构造函数中初始化订阅/预购,可参考 Klarna、Card、SEPA 等已有方法。二、在 includes/constants/class-wc-stripe-payment-methods.php 按 STRIPE_<METHOD> 约定添加常量,该常量被 webhook 处理、支付处理与管理 REST 端点引用。三、在 WC_Stripe::init() 的支付方式类数组中注册新类,数组顺序影响结账显示顺序。四、将图标(建议 SVG)放入 client/payment-method-icons/ 并在 index.js 注册,使 get_icon() 能解析。五、在 client/blocks/upe/ 添加该方法配置,Blocks 集成与经典结账是独立注册,缺少此项则 Blocks 结账不可见。
验证矩阵(关键):任何影响支付方式可用性或渲染的改动必须在四种结账界面验证——经典结账(关闭 Blocks)、Blocks 结账(默认开启)、Optimized Checkout(OCS,在插件设置中启用)以及 Express checkout(ECE,需检查商品页、购物车、结账与 pay-for-order 上的 Apple Pay/Google Pay/Link/Amazon Pay 按钮)。若某方法有意不支持某界面,确认其被干净隐藏而非报错也属于测试结果。
测试:PHPUnit 添加 tests/phpunit/payment-methods/class-wc-stripe-upe-payment-method-<id>-test.php,用 @dataProvider 覆盖订阅/预购开关、货币、国家等能力矩阵;若 Blocks 配置或图标注册含逻辑,则在代码旁的 tests/ 目录加 Jest 测试;E2E 至少在 tests/e2e/specs/<method>/ 下提供一个购物者正常路径用例,并遵循既有 Playwright 项目约定。若支持订阅或预购,还需覆盖订阅续订路径(WC_Stripe_Subscriptions_Trait::renew_subscription)、预购发布路径(WC_Stripe_Pre_Orders_Trait)以及相关 payment_intent.* 与 setup_intent.* 事件的 webhook 处理,定期付款回归在 includes/AGENTS.md 中被明确列为常见陷阱。
常见错误:添加类但忘记在 WC_Stripe::init() 注册会导致方法静默缺失;忘记常量会使 webhook 无法分类扣款并破坏管理 REST 端点;忘记 Blocks 支持会在经典界面可用而 Blocks 中消失;忘记图标注册会出现破图占位符;只验证一个结账界面会导致其他三个出现回归;支持定期付款却缺少订阅/预购 trait 接线会使续订退回手动处理。