fix(agent-commerce): 決済プラグインのハンドラにタグが付かず payment_handlers が空になる問題を修正 by nanasess · Pull Request #6964 · EC-CUBE/ec-cube

nanasess · 2026-07-26T00:04:04Z

概要(Overview・Refs Issue)

エージェントコマース (ACP/UCP) の決済ハンドラが、決済プラグインから自動でタグ付けされなくなっている問題を修正します。

app/config/eccube/services.yaml の _instanceof で AgentCheckoutPaymentHandlerInterface に agent_commerce.payment_handler タグを付与していましたが、_instanceof はそれを記述したファイル内で定義されたサービスにしか適用されません。#6915 で Plugin\ の PSR-4 自動登録が services.yaml から services.php へ移ったため、決済プラグインの具象ハンドラにはタグが届かなくなっていました。

refs #6915, #6837, #6843

結果として現在の 4.4 では以下が発生します。

AgentCheckoutPaymentHandlerRegistry に注入される !tagged_iterator agent_commerce.payment_handler が空になる
UCP discovery (/.well-known/ucp) の payment_handlers が {} になり、登録済みハンドラが広告されない
ACP/UCP checkout の complete で決済ハンドラを解決できない

実測 (ec-cube/samplepayment44 を導入し、ACP/UCP ハンドラを 1 つずつ実装した状態):

$ bin/console debug:container --tag=agent_commerce.payment_handler
Symfony Container Services Tagged with "agent_commerce.payment_handler" Tag
===========================================================================

 ------------ ------------
  Service ID   Class name
 ------------ ------------

なお、この問題は #6963 で修正した redeclare fatal (全リクエストが HTTP 500) に隠れており、そちらが解消して初めて観測可能になりました。両者は別サブシステム・別起因の独立した不具合です。

方針(Policy)

_instanceof をやめ、Kernel::build() の registerForAutoconfiguration() でコンテナ全体にタグ付けする方式へ移行します。

これは同ファイルで PaymentMethodInterface / PurchaseProcessor / ItemPreprocessor / QueryCustomizer など既存 11 件が採用している方式で、agent commerce のハンドラだけが _instanceof を使っていた状態でした。本 PR で流儀が揃います。

_instanceof を維持したまま services.php 側にも複製する案は、正典が 2 箇所に分かれ再発しやすいため採りませんでした。

実装に関する補足(Appendix)

プラグイン側の期待挙動について

決済プラグインが自身の Resource/config/services.yaml で明示的に tags: ['agent_commerce.payment_handler'] と書けば、本修正が無くてもタグは付きます (自ファイルスコープのため #6915 の影響を受けない)。壊れているのはインターフェイスを実装するだけで載る「ゼロ設定」の契約の方です。

UcpPaymentHandlerDiscoveryRegistry の docblock も「UCP ハンドラを登録するだけで discovery にも自動的に広告される (ゼロ設定)」と記載しており、修正しないとドキュメントと実挙動が食い違ったままになります。

互換性への影響

AgentCheckoutPaymentHandlerInterface の具象実装は src/ にも app/Customize/ にも存在しない (インターフェイス定義と、それを消費する Registry/Discovery のみ) ため、registerForAutoconfiguration はコア既存サービスに対して no-op です。
_instanceof は autoconfigure: false のサービスにも効きますが registerForAutoconfiguration は効きません。services.yaml の autoconfigure: false は IgnoreRoutingNotFoundExtension / InitSubscriber / InitDriver の 3 件のみで、いずれも決済ハンドラではないため差は生じません。
削除した _instanceof は設定全体で唯一のもので、他のタグ規則を巻き込みません。

テスト（Test)

ローカル (SQLite / ec-cube/api44 + ec-cube/samplepayment44 を実際に導入) で確認しました。

修正前: bin/console debug:container --tag=agent_commerce.payment_handler が 0 件
修正後: 同コマンドで 2 件 (Plugin\SamplePayment44\Service\AgentCommerce\Acp\AcpSampleCardHandler / ...\Ucp\UcpSampleCardHandler)
ビルトインサーバの /.well-known/ucp が "payment_handlers":{"dev.ucp.payment.card":[{"id":"dev.ucp.payment.card","version":"2026-04-08"}]} を返すことを確認 (修正前は {})
php-cs-fixer --dry-run src/Eccube/Kernel.php = 0 件

あわせて、本修正を取り込んだ結合 E2E ワークフロー (本体 + api44 + samplepayment44) が全ジョブ green であることを確認済みです。

Integration smoke: PHP 8.2 / 8.3 / 8.4 / 8.5 × PostgreSQL / MySQL の 8 マトリクス全 pass
Checkout E2E: ACP 31 assertions / UCP 23 assertions。complete (決済実行) まで到達し、成功 / 3DS 中断・再開 / 拒否の各シナリオでハンドラが実際に実行されることを確認

相談（Discussion）

DI のタグ配線を固定するテストが現状ありません。既存の UcpPaymentHandlerDiscoveryRegistryTest は in-memory ハンドラを使う純ロジックの TestCase のため、今回の回帰を検知できませんでした。

agent_commerce.payment_handler タグが付いたサービスが解決できることを確認する機能テストの追加を検討していますが、テスト環境にはプラグインが導入されないため、テスト用のダミーハンドラを app/Customize 相当に置く等の工夫が要ります。本 PR に含めるべきか、別 PR とすべきかご意見をいただけると助かります。

マイナーバージョン互換性保持のための制限事項チェックリスト

既存機能の仕様変更はありません
フックポイントの呼び出しタイミングの変更はありません
フックポイントのパラメータの削除・データ型の変更はありません
twigファイルに渡しているパラメータの削除・データ型の変更はありません
Serviceクラスの公開関数の、引数の削除・データ型の変更はありません
入出力ファイル(CSVなど)のフォーマット変更はありません

レビュワー確認項目

動作確認
コードレビュー
E2E/Unit テスト確認(テストの追加・変更が必要かどうか)
互換性が保持されているか
セキュリティ上の問題がないか
- 権限を超えた操作が可能にならないか
- 不要なファイルアップロードがないか
- 外部へ公開されるファイルや機能の追加ではないか
- テンプレートでのエスケープ漏れがないか

Summary by CodeRabbit

改善
- 決済プラグインのハンドラー登録方法を見直し、プラグインの配置にかかわらず、Agent Commerce の決済処理が一貫して認識されるようになりました。
- 決済機能の構成を整理し、設定による登録漏れが発生しにくくなりました。

EC-CUBE#6915 で `Plugin\` の PSR-4 自動登録が services.yaml から services.php へ移ったことにより、services.yaml の `_instanceof` (ファイルスコープ) が決済プラグインの具象ハンドラに届かなくなり、`agent_commerce.payment_handler` タグが付かなくなっていた。結果として `AgentCheckoutPaymentHandlerRegistry` が空になり、UCP discovery の `payment_handlers` が `{}` を返して結合 E2E の Integration smoke が全マトリクスで失敗していた (`checkout-e2e` は `needs` で skip)。 `PaymentMethodInterface` と同様に、コンテナ全体へ効く `Kernel::build()` の `registerForAutoconfiguration()` でタグ付けする。検証: - 修正前後で `bin/console debug:container --tag=agent_commerce.payment_handler` が 0 件 → SamplePayment44 の ACP/UCP ハンドラ 2 件になることを確認 - ローカルの `/.well-known/ucp` が `payment_handlers: {"dev.ucp.payment.card":[{id, version}]}` を返すことを確認 - `AgentCheckoutPaymentHandlerInterface` の具象実装は src/・app/Customize に存在しないため、コアのサービス配線への影響はない Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> (cherry picked from commit 6bc673e)

coderabbitai · 2026-07-26T00:04:38Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 1b61a97e-7b8e-41ea-a65f-348ea6fdd0a8

📥 Commits

Reviewing files that changed from the base of the PR and between 1cfea14 and b19629d.

📒 Files selected for processing (2)

app/config/eccube/services.yaml
src/Eccube/Kernel.php

📝 Walkthrough

Walkthrough

Agent Commerce 決済ハンドラのタグ付与を services.yaml から Kernel::build() の自動構成へ移行し、プラグイン配下の具象ハンドラにも適用される構成に変更しました。

Changes

Agent Commerce 決済ハンドラ自動構成

Layer / File(s)	Summary
Kernel での自動タグ付与 `src/Eccube/Kernel.php`, `app/config/eccube/services.yaml`	`AgentCheckoutPaymentHandlerInterface` の自動構成を `Kernel::build()` に登録し、`agent_commerce.payment_handler` タグを付与します。`services.yaml` の `_instanceof` 設定を削除し、適用範囲に関する注記を追加しました。

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

EC-CUBE/ec-cube#6872: Agent Commerce 決済ハンドラの自動タグ付けを追加し、UCP の決済ハンドラ検出処理がそのタグに依存しています。

Suggested labels: Agentic Commerce

Poem

ぴょんと跳ねたらタグが舞う
Kernel の庭でハンドラ並ぶ
古い設定は土に還り
プラグインにも道が開く
うさぎも決済、にんじん払い 🐇

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	決済プラグインのハンドラにタグが付かず payment_handlers が空になる問題という、変更内容の主旨を的確に表しています。
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

codecov · 2026-07-26T00:21:57Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.25%. Comparing base (1cfea14) to head (b19629d).

Additional details and impacted files

@@            Coverage Diff             @@
##              4.4    #6964      +/-   ##
==========================================
+ Coverage   77.11%   77.25%   +0.14%     
==========================================
  Files         547      547              
  Lines       27163    27165       +2     
==========================================
+ Hits        20946    20987      +41     
+ Misses       6217     6178      -39

Flag	Coverage Δ
Unit	`77.25% <100.00%> (+0.14%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

nanasess · 2026-07-26T00:31:39Z

#6872 に含まれているためクローズします

nanasess closed this Jul 26, 2026

Navigation Menu

Uh oh!

fix(agent-commerce): 決済プラグインのハンドラにタグが付かず payment_handlers が空になる問題を修正 - #6964

fix(agent-commerce): 決済プラグインのハンドラにタグが付かず payment_handlers が空になる問題を修正#6964
nanasess wants to merge 1 commit into
EC-CUBE:4.4from
nanasess:fix/agent-commerce-payment-handler-autoconfigure

nanasess commented Jul 26, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 26, 2026 •

edited

Loading

Walkthrough

Changes

Uh oh!

codecov Bot commented Jul 26, 2026

Uh oh!

nanasess commented Jul 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

nanasess commented Jul 26, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

概要(Overview・Refs Issue)

方針(Policy)

実装に関する補足(Appendix)

テスト（Test)

相談（Discussion）

マイナーバージョン互換性保持のための制限事項チェックリスト

レビュワー確認項目

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Uh oh!

codecov Bot commented Jul 26, 2026

Codecov Report

Uh oh!

nanasess commented Jul 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

nanasess commented Jul 26, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 26, 2026 •

edited

Loading