fix(agent-commerce): capture の戻り値と再試行可否を本体の契約に合わせる

EC-CUBE/ec-cube#7032 のマージで決済ハンドラの契約が 2 点明確になったため追随する。

- **capture の戻り値は COMPLETED か FAILED のみ**。従来は authorize と写像を共用しており、
  ゲートウェイが REQUIRES_CAPTURE / REQUIRES_ACTION / PROCESSING を返すと AUTHORIZED /
  REQUIRES_ACTION / PENDING をそのまま返していた。本体はこれらを失敗として扱うが、
  errorCode / errorMessage が無いぶん理由を伝えられない。capture 専用の写像を分け、
  非終端ステータスはログに残したうえで capture_unexpected_status の失敗へ畳む。
- **与信が残り再 authorize できない場合の capture 失敗は retryable=false**。本体には
  capture 単独の再実行入口が無く、ready からの再 complete は新規 authorize から始まる
  (保持した PSP 参照は渡らない)。ACP は入口が Shared Payment Token の償還でワンショット
  のため、ready へ戻しても再試行は必ず失敗し与信だけが残る。プロトコル別の
  captureFailureIsRetryable() で分岐し、ACP=false / UCP=true とする。UCP はエージェントが
  complete のたびに credential を送り直し exchange をやり直せるため再試行が成立する。

ゲートウェイが不可逆と判断した失敗 (金額不一致等) は、再 authorize できるプロトコルでも
再試行させないよう AND で畳む。capture の例外経路では metadata も引き継ぐようにした
(取消・照会に要る)。

紛らわしかった toOutcome() は toAuthorizeOutcome() へ改名し、capture からの流用を防ぐ。

検証: PHPUnit 86 tests / 177 assertions / 0 failures、PHPStan level 6 No errors。
追加した 6 テストは修正前に落ちることを確認済み。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: nanasess

Service/AgentCommerce/AbstractAgentCardHandler.php

@@ -51,6 +51,18 @@ public function __construct(
      */
     abstract protected function protocolId(): int;
 
+    /**
+     * capture 失敗を再試行可能 (ready へ戻す) として返してよいか.
+     *
+     * コアは **capture 単独の再実行入口を持たない**。ready からの再 complete は新規 {@link authorize()}
+     * から始まり、保持した PSP 参照はハンドラへ渡らない
+     * ({@link \Eccube\Service\AgentCommerce\Payment\AgentCheckoutPaymentHandlerInterface::capture()})。
+     * したがって「同じ $paymentData から instrument を作り直せるか」がそのまま再試行可否になる。
+     *
+     * 作り直せないのに true を返すと、再試行は必ず失敗したうえ与信だけが PSP 側に残る。
+     */
+    abstract protected function captureFailureIsRetryable(): bool;
+
     /**
      * complete リクエストの中立支払データを、ゲートウェイへ渡す instrument へ整形する.
      *
@@ -120,7 +132,7 @@ public function authorize(Order $order, array $paymentData, array $paymentRefere
             return PaymentOutcome::failed('payment_gateway_error', 'The payment gateway could not be reached.', true);
         }
 
-        return $this->toOutcome($result);
+        return $this->toAuthorizeOutcome($result);
     }
 
     /**
@@ -142,15 +154,20 @@ public function capture(Order $order, array $paymentData, PaymentOutcome $author
                 $this->context($order),
             );
         } catch (\Throwable $e) {
-            // capture 中の失敗は authorize と扱いが異なる。コアは在庫を rollback する一方、PSP 側の与信は
-            // 残るため、retryable=true でセッションを ready に戻し、同一取引の再 capture / 取消を可能にする
-            // (canceled にすると与信が残ったまま不可逆になる)。
+            // 与信は PSP 側に残るため、取消・照会できるよう取引識別子と metadata を引き継ぐ。
+            // 再試行可否は「新規 authorize をやり直せるか」で決まる ({@link captureFailureIsRetryable()})。
             $this->logger->error('Agent payment capture failed.', ['exception' => $e, 'order_no' => $order->getOrderNo(), 'transaction_id' => $transactionId]);
 
-            return PaymentOutcome::failed('payment_capture_error', 'The payment gateway could not be reached.', true, $transactionId);
+            return PaymentOutcome::failed(
+                'payment_capture_error',
+                'The payment gateway could not be reached.',
+                $this->captureFailureIsRetryable(),
+                $transactionId,
+                $authorization->metadata,
+            );
         }
 
-        return $this->toOutcome($result);
+        return $this->toCaptureOutcome($result, $order);
     }
 
     /**
@@ -173,12 +190,52 @@ private function context(Order $order): array
     }
 
     /**
-     * ゲートウェイ結果をコアの {@link PaymentOutcome} へ写像する.
+     * capture のゲートウェイ結果をコアの {@link PaymentOutcome} へ写像する.
+     *
+     * **コアの契約は「capture の戻り値は COMPLETED か FAILED のみ」**。中間状態を返してもコアは
+     * 失敗として扱い在庫を回収するため、authorize 用の {@link toAuthorizeOutcome()} は流用せず
+     * ここで終端 2 値へ畳む。REQUIRES_CAPTURE / REQUIRES_ACTION / PROCESSING が返るのは
+     * ゲートウェイ実装の誤りなので、ログに残したうえで失敗にする (fail-closed)。
+     */
+    private function toCaptureOutcome(GatewayResult $result, Order $order): PaymentOutcome
+    {
+        if ($result->status === GatewayStatus::SUCCEEDED) {
+            return PaymentOutcome::completed($result->transactionId, $result->metadata);
+        }
+
+        if ($result->status === GatewayStatus::FAILED) {
+            return PaymentOutcome::failed(
+                $result->errorCode ?? 'capture_failed',
+                $result->errorMessage ?? '',
+                // ゲートウェイが不可逆と判断した失敗 (金額不一致等) は、再 authorize できても再試行させない。
+                $result->retryable && $this->captureFailureIsRetryable(),
+                $result->transactionId,
+                $result->metadata,
+            );
+        }
+
+        $this->logger->error('The payment gateway returned a non-terminal status from capture.', [
+            'order_no' => $order->getOrderNo(),
+            'status' => $result->status->value,
+            'transaction_id' => $result->transactionId,
+        ]);
+
+        return PaymentOutcome::failed(
+            'capture_unexpected_status',
+            'The payment could not be captured.',
+            $this->captureFailureIsRetryable(),
+            $result->transactionId,
+            $result->metadata,
+        );
+    }
+
+    /**
+     * authorize のゲートウェイ結果をコアの {@link PaymentOutcome} へ写像する.
      *
      * 与信のみ (REQUIRES_CAPTURE) と売上確定済 (SUCCEEDED) を区別する点が要。潰して COMPLETED に
      * すると、auto-capture 型 PSP へ差し替えたときにコアが capture を二重発行する。
      */
-    private function toOutcome(GatewayResult $result): PaymentOutcome
+    private function toAuthorizeOutcome(GatewayResult $result): PaymentOutcome
     {
         return match ($result->status) {
             GatewayStatus::REQUIRES_CAPTURE => PaymentOutcome::authorized($result->transactionId, $result->metadata),

Service/AgentCommerce/Acp/AcpSampleCardHandler.php

@@ -53,6 +53,19 @@ protected function protocolId(): int
         return AgentProtocol::ACP;
     }
 
+    /**
+     * ACP の capture 失敗は**再試行させない**.
+     *
+     * ready からの再 complete は新規 authorize から始まるが、その入口である
+     * {@link redeemSharedPaymentToken()} は Shared Payment Token の償還であり、SPT はワンショットで
+     * 2 度目が失敗する。再試行を許しても必ず失敗し、与信だけが PSP 側に残るため canceled にする
+     * (与信の取消は PSP 側の運用に委ねる)。
+     */
+    protected function captureFailureIsRetryable(): bool
+    {
+        return false;
+    }
+
     protected function toGatewayInstrument(array $paymentData): array
     {
         // SPT の償還はワンショットなので authorize からの 1 度だけ。capture は与信結果を使う

Service/AgentCommerce/Ucp/UcpSampleCardHandler.php

@@ -57,6 +57,20 @@ protected function protocolId(): int
         return AgentProtocol::UCP;
     }
 
+    /**
+     * UCP の capture 失敗は**再試行を許す**.
+     *
+     * ready からの再 complete は新規 authorize から始まるが、UCP はエージェントが complete のたびに
+     * payment.instruments[].credential を送り直し、controller が {@link exchangePaymentToken()} で
+     * 交換をやり直す。つまり同じ入力から instrument を作り直せるため ready へ戻して再試行できる。
+     *
+     * ワンショットのクレデンシャルを扱う PSP へ差し替える場合は false を返すこと。
+     */
+    protected function captureFailureIsRetryable(): bool
+    {
+        return true;
+    }
+
     protected function toGatewayInstrument(array $paymentData): array
     {
         // UCP は controller の resolvePaymentData() が exchangePaymentToken() 済みの中立データを渡す。

Tests/Service/AgentCommerce/Acp/AcpSampleCardHandlerTest.php

@@ -17,6 +17,7 @@
 use Eccube\Service\AgentCommerce\MinorUnitConverter;
 use Eccube\Service\AgentCommerce\Payment\PaymentOutcome;
 use Eccube\Service\AgentCommerce\Payment\PaymentOutcomeStatus;
+use PHPUnit\Framework\Attributes\DataProvider;
 use Plugin\SamplePayment44\Service\AgentCommerce\Acp\AcpSampleCardHandler;
 use Plugin\SamplePayment44\Service\AgentCommerce\Exception\InvalidPaymentDataException;
 use Plugin\SamplePayment44\Service\AgentCommerce\Gateway\AgentPaymentGatewayInterface;
@@ -122,17 +123,65 @@ public function testGatewayExceptionOnAuthorizeIsMappedToRetryableFailure(): voi
         $this->assertStringNotContainsString('connection reset', $outcome->errorMessage ?? '', 'PSP の内部メッセージをエージェントへ露出しない');
     }
 
-    public function testGatewayExceptionOnCaptureKeepsTransactionReferenceAndStaysRetryable(): void
+    public function testGatewayExceptionOnCaptureIsNotRetryableAndKeepsTransactionReference(): void
     {
-        $spy = new SpyAgentPaymentGateway(GatewayResult::requiresCapture('pi_4'), new \RuntimeException('timeout'));
+        $spy = new SpyAgentPaymentGateway(GatewayResult::requiresCapture('pi_4', ['gateway' => 'spy']), new \RuntimeException('timeout'));
         $order = $this->createOrder(AgentProtocol::ACP, CreditCard::class);
 
         $authorization = $this->handler($spy)->authorize($order, ['token' => 'tok_ok']);
         $outcome = $this->handler($spy)->capture($order, ['token' => 'tok_ok'], $authorization);
 
         $this->assertSame('payment_capture_error', $outcome->errorCode);
-        $this->assertTrue($outcome->retryable, '与信は PSP 側に残るため canceled にせず ready へ戻す');
+        // コアに capture 単独の再実行入口は無く、ready からの再試行は新規 authorize = SPT の再償還になる。
+        // ワンショットのため必ず失敗するので、ready へ戻さず canceled にする。
+        $this->assertFalse($outcome->retryable, 'SPT は再償還できないため capture 失敗を再試行させない');
         $this->assertSame('pi_4', $outcome->transactionId, '取消・照会のため取引識別子を残す');
+        $this->assertSame(['gateway' => 'spy'], $outcome->metadata, '照会に必要な metadata も引き継ぐ');
+    }
+
+    public function testGatewayCaptureFailureIsForcedNonRetryable(): void
+    {
+        // ゲートウェイが「再試行可」と言っても、ACP では再 authorize が成立しないため上書きする。
+        $spy = new SpyAgentPaymentGateway(
+            GatewayResult::requiresCapture('pi_6'),
+            GatewayResult::failed('capture_failed', 'The capture was rejected.', true, 'pi_6'),
+        );
+        $order = $this->createOrder(AgentProtocol::ACP, CreditCard::class);
+
+        $authorization = $this->handler($spy)->authorize($order, ['token' => 'tok_ok']);
+        $outcome = $this->handler($spy)->capture($order, ['token' => 'tok_ok'], $authorization);
+
+        $this->assertSame(PaymentOutcomeStatus::FAILED, $outcome->status);
+        $this->assertSame('capture_failed', $outcome->errorCode);
+        $this->assertFalse($outcome->retryable);
+    }
+
+    #[DataProvider('nonTerminalCaptureResults')]
+    public function testCaptureNeverReturnsNonTerminalOutcome(GatewayResult $captureResult): void
+    {
+        // コアの契約は「capture の戻り値は COMPLETED か FAILED のみ」。中間状態を返すとコアは
+        // 失敗として扱うが、errorCode / errorMessage が無いぶん理由を伝えられない。
+        $spy = new SpyAgentPaymentGateway(GatewayResult::requiresCapture('pi_7'), $captureResult);
+        $order = $this->createOrder(AgentProtocol::ACP, CreditCard::class);
+
+        $authorization = $this->handler($spy)->authorize($order, ['token' => 'tok_ok']);
+        $outcome = $this->handler($spy)->capture($order, ['token' => 'tok_ok'], $authorization);
+
+        $this->assertSame(PaymentOutcomeStatus::FAILED, $outcome->status, 'capture は COMPLETED か FAILED しか返さない');
+        $this->assertSame('capture_unexpected_status', $outcome->errorCode);
+        $this->assertNotSame('', $outcome->errorMessage ?? '', '理由を伝えられるようメッセージを載せる');
+    }
+
+    /**
+     * capture が返してはならないゲートウェイ結果.
+     *
+     * @return \Iterator<string, array{GatewayResult}>
+     */
+    public static function nonTerminalCaptureResults(): \Iterator
+    {
+        yield 'requires_capture (未 capture のまま)' => [GatewayResult::requiresCapture('pi_7')];
+        yield 'requires_action (capture 中の追加認証)' => [GatewayResult::requiresAction(['type' => '3ds'], 'pi_7')];
+        yield 'processing (非同期確定)' => [GatewayResult::processing('pi_7')];
     }
 
     public function testRequiresActionCarriesActionDataMetadataAndReference(): void

Tests/Service/AgentCommerce/Ucp/UcpSampleCardHandlerTest.php

@@ -139,10 +139,26 @@ public function testCaptureFailureIsRetryableAndKeepsReference(): void
         $captured = $handler->capture($order, [], $authorization);
         $this->assertSame(PaymentOutcomeStatus::FAILED, $captured->status, 'capture 失敗の分岐を検証できる規約を持つ');
         $this->assertSame('capture_failed', $captured->errorCode);
-        $this->assertTrue($captured->retryable);
+        // UCP はエージェントが complete のたびに credential を送り直すため、ready からの再試行で
+        // exchange → authorize をやり直せる (ACP の SPT と非対称なのはここ)。
+        $this->assertTrue($captured->retryable, 'credential を再送すれば新規 authorize からやり直せる');
         $this->assertSame($authorization->transactionId, $captured->transactionId);
     }
 
+    public function testCaptureNeverReturnsNonTerminalOutcome(): void
+    {
+        // コアの契約は「capture の戻り値は COMPLETED か FAILED のみ」。
+        $spy = new SpyAgentPaymentGateway(GatewayResult::requiresCapture('pi_u1'), GatewayResult::processing('pi_u1'));
+        $order = $this->createOrder(AgentProtocol::UCP, CreditCard::class);
+
+        $authorization = $this->handler($spy)->authorize($order, ['token' => 'tok_ok']);
+        $outcome = $this->handler($spy)->capture($order, [], $authorization);
+
+        $this->assertSame(PaymentOutcomeStatus::FAILED, $outcome->status);
+        $this->assertSame('capture_unexpected_status', $outcome->errorCode);
+        $this->assertTrue($outcome->retryable, 'UCP は再 authorize できるため契約違反でも ready へ戻す');
+    }
+
     private function handler(AgentPaymentGatewayInterface $gateway): UcpSampleCardHandler
     {
         return new UcpSampleCardHandler(new MinorUnitConverter(), $gateway, new NullLogger());