UCP checkout 向け決済ハンドラの参考実装 (mock)

[nanasess]

概要

EC-CUBE 本体のエージェントコマース対応のうち、UCP (Universal Commerce Protocol) checkout における決済ハンドラの公開された参考実装 (mock) を本サンプルプラグインに用意する。

本体 (EC-CUBE/ec-cube) 側では、エージェント経由のチェックアウトをセッション/フォームに依存しない形で処理する基盤を実装しており、決済の具象は決済プラグイン側に置く設計になっている。本サンプルプラグインはダミーゲートウェイを持つため、実 PSP に依存しない UCP 決済ハンドラの参考実装として最適。

• 本体トラッキング: ユニバーサル コマース プロトコル（UCP）の対応 ec-cube#6574 (UCP checkout) / 共通基盤 ACP/UCP 共通基盤: エージェントコマース向け CheckoutSession・マッピング層の整備 ec-cube#6777
• 関連 (ACP 版): ACP checkout 向け決済ハンドラの参考実装 (mock) #52

Note

前提: 本サンプルプラグインの EC-CUBE 4.4 (Symfony 7 / PHP 8.2+ / Doctrine ORM 3 / attribute マッピング) 対応が必要。
現状の support-4.3 ブランチはアノテーションマッピング (@ORM\...) で、Doctrine ORM 3.x (doctrine/annotations 非同梱) の 4.4 ではエンティティをロードできない。4.4 対応は別途予定のため、本 issue の実装は 4.4 対応ブランチ上で行う。

設計方針

• エージェント決済は web の PaymentMethodInterface フロー (verify()/apply()/checkout() + form/twig/session/redirect) を使わない。本体は Eccube\Service\AgentCommerce\AgentCheckoutPurchaseFlowAdapter 経由で Cart → Order → shopping flow を再利用する。
• したがって既存の CreditCard クラスを流用するのではなく、エージェント用ハンドラを新設し、既存の足回り (ダミーゲートウェイ・Config・OrderTrait・PaymentStatus 遷移・PurchaseFlow commit/rollback) を共有する。
• 実 PSP SDK 不要 (mock)。eccube-api4 非依存 (UCP インバウンド認証は本体側で RFC 9421 署名により処理。決済ハンドラは認証と無関係)。

本体側の前提インターフェイス

• 共通基底 Eccube\Service\AgentCommerce\Payment\AgentCheckoutPaymentHandlerInterface (authorize() / capture() / supports()) — ACP/UCP 共通基盤: エージェントコマース向け CheckoutSession・マッピング層の整備 ec-cube#6777 Phase 1b (PR #6825) で実装済。
• UCP 派生インターフェイス UcpPaymentHandlerInterface (token exchange 相当の exchangePaymentToken() を追加) — 本体 ユニバーサル コマース プロトコル（UCP）の対応 ec-cube#6574 で定義予定。

やること

• (前提) 本プラグインの EC-CUBE 4.4 対応ブランチ上で作業する
• UcpPaymentHandlerInterface を実装する mock ハンドラを追加 (token exchange を擬似実行 → authorize/capture → PaymentStatus 遷移 → PurchaseFlow::commit()、失敗時 rollback)
• tagged service として登録し、本体 UCP discovery の payment_handlers (逆ドメイン名キーのレジストリ) へ寄与
• Config にエージェント決済用のダミー設定 (エンドポイント/キー等) を必要に応じて追加
• OrderTrait に UCP 決済トークン/認可 ID 等の保持フィールドを必要に応じて追加
• mock ハンドラの単体テスト (authorize/capture 成功・失敗、在庫超過等のビジネス系結果)
• (4.4 対応後) E2E テスト

スコープ外

• 実 PSP との接続・本番決済 (本 issue は mock 参考実装に限定)
• 特定 PSP の内部仕様 (公開可能な汎用 mock のみ扱う)

[nanasess]

E2E 検証完了 (mock UCP ハンドラ)

本 issue の mock UCP 決済ハンドラを実装し、本体 (EC-CUBE/ec-cube) との結合 E2E で検証しました。

実装 (4.4 対応ブランチ feature/agentic-commerce)

• UcpPaymentHandlerInterface を実装する mock ハンドラ UcpSampleCardHandler を新設 (handler_id = dev.ucp.payment.card、exchangePaymentToken() で擬似トークン交換)。
• ACP 版と共通の Gateway 抽象 + MockAgentPaymentGateway を共有。eccube-api4 非依存 (UCP インバウンドは本体側で RFC 9421 署名により処理)。
• tagged service として自動登録。authorize()/capture() → PurchaseFlow commit、失敗時 rollback。

E2E 検証結果 (本体 checkout E2E, run_payment=true)

• 正常系 → completed
• escalation (REQUIRES_ACTION) → requires_escalation
• 拒否 → 確定せず (HTTP 200 + messages[])

残課題: discovery の payment_handlers (逆ドメイン名レジストリ) への広告寄与、およびハンドラ単体テストは別途。検証はフォーク開発ブランチで実施し、upstream への PR は別途行います。