Appearance
Stripe Agent Skills 照合結果（実装・テスト設計）
| 項目 | 内容 |
|---|---|
| 親 Issue | #2734 |
| 照合基準 | リポジトリ内 .agents/skills/stripe-best-practices / .agents/skills/upgrade-stripe（エージェント用。VitePress サイトには含めない） |
| 公式案内 | Stripe Agent skills |
| 最終更新 | 2026-07-18 |
1. 目的
有料記事の Stripe Checkout / Webhook 実装とテスト設計を、Stripe 公式 Agent Skills の推奨と突き合わせ、適合点とギャップを記録する。ギャップのうち修正・回収が必要なものは関連 Issue に紐づける。
2. 照合対象
| 領域 | 参照 |
|---|---|
| Checkout | PaidArticleCheckoutService / StripeCheckoutSessionGateway / StripeClientFactory |
| Webhook | StripeWebhookEventGateway / StripeWebhookService / API-002-1 |
| キー管理 | StripeSettings / stripe-api-key-config.md |
| テスト設計 | paid-article-stripe-e2e-policy.md / paid-article-payment-scenario.md |
※ Checkout 通し Playwright（#2730 / PR #2733）は本照合時点では develop 未マージの場合がある。方針ドキュメント（#2708）は対象に含む。
3. 適合（対応不要）
| ID | 観点 | 判定 | 根拠 |
|---|---|---|---|
| OK1 | 都度課金の API 選択 | 適合 | Checkout Sessions（mode: payment）を採用。skill の one-time payments 推奨と一致 |
| OK2 | payment_method_types | 適合 | checkout.sessions.create パラメータに含めていない（動的 PM） |
| OK3 | PCI / カード非保持 | 適合 | Stripe-hosted Checkout に委譲。自サーバーで PAN を扱わない |
| OK4 | Webhook 署名検証 | 適合 | Webhook::constructEvent を使用（StripeWebhookEventGateway） |
| OK5 | 購入記録の正本は Webhook | 適合 | checkout.session.completed → db_paid_article_purchase。success URL のみに依存しない設計 |
| OK6 | 冪等 | 適合 | external_transaction_id（Checkout Session ID）の UNIQUE |
| OK7 | 秘密鍵のコード非埋め込み | 適合 | wp-config.php の define のみ。リポジトリにキーなし |
| OK8 | 環境分離の方針 | 適合 | test / live をキー prefix で区別。ドキュメントで本番キーの扱いを明示 |
| OK9 | テスト設計（live 禁止） | 適合 | E2E 方針・シナリオとも live キー / 本番 URL / 実ユーザー禁止 |
| OK10 | テスト設計（CI 非載） | 適合 | Stripe CLI・秘密情報・flaky のため CI Quality Gate 非対象。Local opt-in 方針は Stripe Testing と整合 |
| OK11 | シナリオ線引き（S5/S9/S10） | 適合 | 外部 Checkout UI は Local 自動化、冪等・メールは Unit 正、Staging は手動。過剰自動化していない |
4. ギャップ（Issue 起票）
| ID | 優先度 | 内容 | Issue |
|---|---|---|---|
| G1 | Medium | skill は Restricted API key（rk_）推奨。現行は sk_* のみ受理し RAK を拒否する | #2736 |
| G2 | Medium | StripeClient で API version 未明示。skill 推奨最新は 2026-06-24.dahlia。版上げ後に integration_identifier も未付与 | #2735（API version 明示 + Checkout integration_identifier） |
5. ギャップ（対応不要 / Info）
| ID | 優先度 | 内容 | 判断 |
|---|---|---|---|
| I1 | Info | 秘密情報の保管を secrets vault 推奨。本プロジェクトは WordPress の wp-config.php パターン | 既存運用と一致。現状維持で可 |
| I2 | Info | Webhook の Stripe IP allowlist（defense in depth） | 共有ホスティング / WP REST では運用コスト大。署名検証を正とし見送り |
| I3 | Info | Stripe Tax / Connect / Billing / Payment Element | 都度課金・自サイト Checkout の現行スコープ外 |
| I4 | Info | ローカル core_src/vendor の stripe-php 実体と composer.lock の表記差があり得る | デプロイ前に composer install で lock に合わせる運用で十分 |
6. テスト設計についての結論
方針ドキュメント（#2708）と手動シナリオは、Stripe 公式のテストモード・テストカード・Webhook 転送（CLI）の使い方と矛盾しない。
- live キー禁止・専用テスト会員/記事・Session ID 限定の片付けは安全側
- CI に Stripe 秘密情報を載せない判断は skill のキー管理とも整合
- S6（再送冪等）・S14/S15（実メール）を E2E 自動化しない線引きも妥当
実装コードの回収は #2735 / #2736 で別途行う。本所見の PR では skills 導入とドキュメントのみを変更する。
7. 関連
- Stripe決済-技術選定理由.md
- commerce-module.md
- skills 更新:
npx skills update -y