payment-platform-readiness

決済プラットフォームの準備

このスキルは、アプリストア、ウェブチェックアウト、ウォレット、サブスクリプション、返金、異議申し立て、プロモーション、エンタイトルメントシステム全体で、決済の信頼性、コンプライアンス、サポートのしやすさ、リプレイ可能性、プロダクトとの親和性を確保するために使用します。

ワークフロー

1. 決済チャネル、プロダクトの種類、課金モデル、プロバイダー識別子、カタログのマッピング、エンタイトルメントの意味、返金／異議申し立てポリシー、決済／手数料モデル、サポート窓口、照合の担当者を特定します。
2. references/payment-platform-patterns.md を読みます。決済、財務締め、システム間の照合が対象となる場合は、references/billing-reconciliation-patterns.md も読み込みます。
3. カタログ、チェックアウト、レシート／Webhook 処理、冪等な台帳取り込み、エンタイトルメントのプロジェクション、返金／取り消し／異議申し立て処理、サポートによる修正、決済、照合をマッピングします。
4. Apple IAP、Google Play Billing、Stripe／ウェブチェックアウト、ウォレット、プロモーション／管理者による付与、購入の復元、更新、返金、チャージバック、遅延イベントについて、プロバイダー固有の優先順位を定義します。
5. プラットフォーム固有の制約、サンドボックスと本番環境の分離、フォールバック経路、顧客へのメッセージ、財務締め、運用上のロールバックを確認します。
6. 障害やバックログに備え、明示的な取り込み状態を定義します。状態には、一時停止、隔離、重複排除、プロバイダーの有効時刻順への並べ替え、リプレイ中、プロジェクターの修復済み、財務照合済み、再開済みを含めます。
7. 請求書／税金／財務締めに関わるローンチでは、請求書、税金、クーポン、クレジットノート、返金、異議申し立て、手数料、決済、収益エクスポート、エンタイトルメント、督促、手動調整を、それぞれ担当者と例外キューを持つ別個のイベントとしてモデル化します。
8. 財務締めでは、金銭／税金／決済／収益に関する各チェックについて、数値許容差、頻度、担当者、ソースシステム、例外キュー、締めを妨げる条件を明記します。
9. 決済状態モデル、台帳スキーマ、イベントの優先順位ルール、照合計画、サポートツール、ブロッカー、可観測性ダッシュボード、ロールバック制御、ローンチチェックリストを作成します。

使用しない場合

• 主な判断事項がパッケージ構成、価格、価値指標、商業的な実験である場合は、saas-subscription-pricing を使用します。
• 主な管轄範囲が販売者／クリエイターの収益、保留金、準備金、支払いである場合は、marketplace-payouts-review を使用します。
• 決済プラットフォームの再設計を必要としない返金／チャージバック／購入復元のサポート状態機械には、refund-and-support-flow-review を使用します。

ソースの検証

• Apple、Google、ウォレット、決済処理業者、税金、請求書、決済、異議申し立てに関する最新要件を、利用時に公式ソースで確認します。
• 資金移動または顧客アクセスを妨げる可能性のある要件について、プロバイダー、API／ポリシーのバージョン、管轄区域、アクセス日、ソース URL を記録します。
• 数値のしきい値、手数料体系、審査ルール、プラットフォームポリシーは、権威ある情報源で再確認するまで未検証として扱います。

ガードレール

• クライアント側だけの確認を根拠に、永続的な価値を付与しないでください。
• 決済記録、エンタイトルメントの状態、サポート案件を照合可能な状態に保ちます。
• 顧客の継続利用を促すために、決済を分かりにくくしないでください。
• 返金、キャンセル、取り消し、異議申し立て、チャージバック、猶予期間、課金リトライ、購入復元、プロモーション、手動調整を、汎用的な単一の状態にまとめないでください。
• エンタイトルメントをひそかに編集しないでください。修正イベントを台帳に追記し、プロジェクターをリプレイします。
• サポート担当者にプロバイダーの記録を変更させないでください。サポートによる修正には、ロールによるアクセス制御、理由コード、有効期限（適切な場合）、監査証跡が必要です。
• 手数料、税金、決済、請求書、返金、異議申し立て、エンタイトルメントの照合を示す証跡なしに、決済をリリースしないでください。
• 各ゲートで、対象フィクスチャ、ダッシュボード／アラート、ロールバックまたはキルスイッチの経路、担当者、承認証跡が明記されていない限り、リリースゲートを完了扱いにしないでください。
• Webhook のリプレイを汎用的なキューの一括処理として説明しないでください。すべてのリプレイ状態には、必要な証跡、順序付け／冪等性のルール、終了条件、デッドレター処理、顧客／サポートへの影響、インシデントレビュー成果物が必要です。

出力形式

Payment surfaces:
Billing model:
Authority boundary:

Readiness matrix:
- Catalog:
- Checkout:
- Confirmation and ledger:
- Entitlement projection:
- Refund/revoke/dispute:
- Support/reconciliation:

Payment and entitlement state model:
- <state> -> <provider evidence, internal projection, customer access, support note>

Provider precedence rules:
- <Apple/Google/Stripe/promo/admin/restore event> -> <idempotency key, effective timestamp, ledger event, entitlement effect>

Reconciliation and finance close:
- <money/settlement/tax/fee/entitlement check> -> <source, cadence, owner, exception action>
- Close control table -> check, source systems, cadence, numeric tolerance, owner, exception queue, close blocker
- Explicit close events -> invoice_created / tax_calculated / coupon_applied / credit_note_issued / payment_succeeded_or_failed / refund_or_dispute / fee_recorded / settlement_received / revenue_exported / entitlement_granted_or_revoked / dunning_started_or_exhausted / manual_adjustment

Support-safe correction flow:
- <case> -> lookup keys (account_id, user_id, invoice_id, payment_intent/charge, subscription, entitlement_id, tax document, support_case_id), evidence, allowed action, approval, ledger event, customer message

Webhook outage replay flow:
- Use a table: state, owner, required evidence, ordering/idempotency rule, dead-letter handling, exit gate, customer/support impact
- Include incident review: provider timeline, retry/dead-letter metrics, projector diff, false-revoke/over-grant disposition, finance exceptions, control fix, approval artifact

Blockers:
- <blocker>

Observability and rollback controls:
- <dashboard/alert> -> <signal, threshold, owner, runbook>
- <rollback/kill switch> -> <scope, trigger, customer impact, recovery proof>

Release gates:
- <gate> -> <test fixture, dashboard/alert, rollback or kill switch, owner approval>