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

[nanasess]

概要

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

本サンプルプラグインはダミーゲートウェイを持つため、実 PSP に依存しない ACP 決済ハンドラの参考実装として最適。

• 本体トラッキング: Agentic Commerce Protocol (ACP) の対応 ec-cube#6776 (ACP checkout) / 共通基盤 ACP/UCP 共通基盤: エージェントコマース向け CheckoutSession・マッピング層の整備 ec-cube#6777
• 関連 (UCP 版): UCP checkout 向け決済ハンドラの参考実装 (mock) #51

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 非依存 (ACP インバウンド認証は本体側で処理。決済ハンドラは認証と無関係)。

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

• 共通基底 Eccube\Service\AgentCommerce\Payment\AgentCheckoutPaymentHandlerInterface (authorize() / capture() / supports()) — ACP/UCP 共通基盤: エージェントコマース向け CheckoutSession・マッピング層の整備 ec-cube#6777 Phase 1b (PR #6825) で実装済。
• ACP 派生インターフェイス AcpPaymentHandlerInterface (Shared Payment Token の償還相当のメソッドを追加) — 本体 Agentic Commerce Protocol (ACP) の対応 ec-cube#6776 で定義予定。

やること

• (前提) 本プラグインの EC-CUBE 4.4 対応ブランチ上で作業する
• AcpPaymentHandlerInterface を実装する mock ハンドラを追加 (Shared Payment Token を擬似償還 → authorize/capture → PaymentStatus 遷移 → PurchaseFlow::commit()、失敗時 rollback)
• tagged service として登録 (本体のハンドラ収集口に乗せる)
• Config にエージェント決済用のダミー設定を必要に応じて追加
• OrderTrait に ACP 決済トークン/認可 ID 等の保持フィールドを必要に応じて追加
• mock ハンドラの単体テスト (authorize/capture 成功・失敗、在庫超過等のビジネス系結果)
• (4.4 対応後) E2E テスト

スコープ外

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

[nanasess]

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

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

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

• AcpPaymentHandlerInterface を実装する mock ハンドラ AcpSampleCardHandler を新設 (handler_id = card_tokenized、Shared Payment Token の擬似償還)。
• PSP 隔離のため Gateway 抽象 (AgentPaymentGatewayInterface) + MockAgentPaymentGateway (トークン規約で 成功/3DS/拒否/不正 を決定的に分岐) を導入。実 PSP 実装へ差し替え可能な構造。
• tagged service として自動登録 (本体 _instanceof がタグ付与)。authorize()/capture() → PurchaseFlow commit、失敗時 rollback。

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

• 正常系 → completed
• 3DS: 中断 (authentication_required) → authentication_result 付き再開 → completed
• 拒否 → 確定せず (HTTP 200 + messages[])

残課題: ハンドラ単体テスト (やること未チェック分) は別途。検証はフォーク開発ブランチで実施し、upstream への PR は別途行います。