feat(agent-commerce): ACP/UCP エージェント決済ハンドラと Gateway 抽象を追加

[nanasess]

概要

EC-CUBE 本体のエージェントコマース対応（ACP / UCP）に対する、サンプル決済での決済ハンドラ参考実装です。本体が定義する決済ハンドラ interface の具象を本プラグイン側に実装し、AI エージェント経由の購入（authorize / capture / トークン償還・交換、3DS 中断・再開）を sample 決済で完結させます。

Important

このPRは本体側 PR の依存先がマージされるまでドラフトです。 本体に以下の型が入るまで autoload / CI は通りません（意図的）。

• Eccube\Service\AgentCommerce\Payment\AgentCheckoutPaymentHandlerInterface / PaymentOutcome（共通基盤 #6777）
• Eccube\Service\AgentCommerce\Payment\AcpPaymentHandlerInterface（ACP #6776）
• Eccube\Service\AgentCommerce\Payment\UcpPaymentHandlerInterface（UCP #6574）

本体側マージ後に CI を再実行し、ドラフトを解除します。

実装内容（Service/AgentCommerce/）

Gateway 抽象（PSP 境界の分離）

• Gateway/GatewayStatus.php — succeeded / requires_capture / requires_action / processing / failed の enum。決済ゲートウェイの状態語彙を中立化（PSP の状態にそのまま写像できる形）。
• Gateway/GatewayResult.php — 結果 DTO（readonly・ファクトリ付き）。
• Gateway/AgentPaymentGatewayInterface.php — authorize() / capture()（通貨・最小単位整数額・instrument・context）。
• Gateway/MockAgentPaymentGateway.php — トークン規約でシナリオを再現するモックゲートウェイ:
  • *-3ds* → 追加認証（requires_action、再開時 authentication_result 同伴で成功）
  • *-decline* → 与信拒否（failed・再試行可） / *-fraud* → 不正検知（failed・再試行不可）
  • *-processing* → 非同期処理中（processing） / それ以外 → 与信成功（requires_capture）→ capture で succeeded
  • 取引 ID は決定的（pi_mock_<sha256>）。

ハンドラ

• AbstractAgentCardHandler.php — 共通基底。supports() は支払方法が CreditCard かつ Order.getAgentProtocol() がプロトコル一致のときのみ true。GatewayResult → 本体 PaymentOutcome へマッピング（succeeded/requires_capture→completed、requires_action→requiresAction、processing→pending、failed→failed）。
• Acp/AcpSampleCardHandler.php — AcpPaymentHandlerInterface 実装。handler_id = card_tokenized、redeemSharedPaymentToken()（ACP Shared Payment Token の償還）。
• Ucp/UcpSampleCardHandler.php — UcpPaymentHandlerInterface 実装。handler_id = dev.ucp.payment.card、exchangePaymentToken()（UCP のトークン交換）。

具象ハンドラは agent_commerce.payment_handler タグ（本体の _instanceof 自動付与）で登録され、本体のレジストリが checkout 解決・discovery 広告に利用します。

検証

本体↔本プラグイン↔eccube-api4 の結合 E2E（本体側 agentic-commerce-e2e ワークフロー、run_payment=true）で、ACP / UCP の 成功 / 3DS 中断・再開 / 拒否 の全シナリオが通ることを確認済みです。

補足

• 本プラグインは「サンプル決済」での参考実装です。実 PSP 連携は各決済プラグインが本体 interface を実装して提供します（Gateway 抽象はその移植境界として設計）。
• 本プラグイン単体の PHPUnit ユニットテストは現状の基盤未整備のため別タスクとします（結合 E2E では検証済み）。