証拠PDF付きStripe自動異議応答システム

Stripe向けの自動異議申立対応システムを構築します。 1. 共有エビデンス収集（app/dispute_evidence.php） Webhookと同期ワーカーの両方で使用される関数を含む共有ファイルを作成します。これにより、エビデンスロジックの重複を回避できます。 主要な関数： - getDisputeUserPlan($user, $stripe) - Stripe APIからユーザーのサブスクリプションプランを取得します（真実の情報源。ローカルDBのプランフィールドはキャンセル時にクリアされるため）。Stripe呼び出しが失敗した場合は、ローカルDBフィールドにフォールバックします。製品IDをプラン名にマッピングし、価格/間隔とキャンセルステータスを含めます。 - collectDisputeEvidence($stripe, $user, $email, $charge, $photosDb) - すべてのテキストおよびファイルエビデンスを収集し、Stripeに提出する準備ができた配列を返します。 - generateServiceDocPdf($stripe, $user, $email, $photos_done, $recent_photos, $total_amount_paid) - 顧客情報、利用概要、最近のアクティビティ表、および最大6枚の実際の製品画像（Stripeの5MBファイルアップロード制限内に収まるように、幅500px/品質75のJPEGにリサイズ）を含むPDFを生成します。StripeファイルIDと生のPDFデータの両方を返します。 重要：total_amount_paidは、ローカルDB（nullまたは古い可能性がある）を信頼するのではなく、Stripe charges API（成功し、返金されていない請求の合計）から取得します。 2. Webhookハンドラー（stripe_webhook.php内） charge.dispute.createdイベントをキャッチします。異議申立が届いたとき： - Stripeから異議申立、請求、顧客オブジェクトを取得します - stripe_customer_idでローカルデータベース内のユーザーを検索します - 異議申立を異議申立SQLiteデータベースに保存します（フィールド：dispute_id, charge_id, payment_intent_id, stripe_customer_id, user_id, email, amount, currency, reason, status, epoch_created, epoch_evidence_submitted, evidence_json, stripe_response, epoch_resolved, outcome） - collectDisputeEvidence()を呼び出してすべてのエビデンス（テキスト+ファイルアップロード）を収集します - $stripe->disputes->update($dispute_id, ['evidence' => $evidence])を介してStripeにエビデンスを提出します - 新しい異議申立が届き、エビデンスが自動提出されたことをTelegram通知で送信します また、charge.dispute.updatedおよびcharge.dispute.closedイベントをキャッチして、異議申立の結果（勝訴/敗訴）をデータベースで追跡し、結果を含むTelegram通知を送信します。 3. Stripeに提出されるエビデンスフィールド テキストフィールド（文字列を直接記述）： - product_description - 製品/サービスが何であるかを説明します - customer_name / customer_email_address - Stripe顧客オブジェクトから - access_activity_log - 詳細な利用ログ：登録日、実行されたアイテム/アクションの数、最終アクティブ日、サブスクリプションプラン（Stripeから）、プラットフォーム、支払総額（Stripeから）、タイムスタンプ付きの最近のアクティビティ - uncategorized_text - 「なぜ私たちが勝つべきか」の主張：顧客はXで登録し、Yのことを行ってサービスを積極的に利用し、支払総額、サービスはデジタル/即時で提供され、顧客は異議申立前に返金を求めて私たちに連絡したことはありません - refund_policy_disclosure / cancellation_policy_disclosure - ポリシーがいつ提示されたか（チェックアウト中、/legalで常にアクセス可能） - refund_refusal_explanation / cancellation_rebuttal - 利用の証明と事前連絡の欠如 - service_date - 請求の日付（Y-m-d形式） ファイルアップロードフィールド（最初に$stripe->files->create(['purpose'=>'dispute_evidence', 'file'=>fopen($path,'r')])を介してファイルをStripeにアップロードし、返されたfile_xxxxx IDを渡します）： - receipt - Stripeから直接請求書PDFを取得し（$stripe->invoices->retrieve($charge->invoice)->invoice_pdf）、ダウンロードして異議申立エビデンスとしてアップロードします - service_documentation - 以下を含むPDFを生成します：顧客情報セクション、サービス利用概要、最近のアクティビティ表、および顧客が受け取った最大6枚の実際の製品画像/スクリーンショット。埋め込む前に画像をリサイズします（幅500px、JPEG品質75）Stripeの5MB制限内に収めるため。 また、両方のPDFをファイルストレージ（例：Cloudflare R2、S3）にハッシュ化されたファイル名で保存し、推測できないが管理ダッシュボードから表示できるようにします。ストレージURLをevidence_jsonに_receipt_r2_urlおよび_service_doc_r2_urlとして保存します。 4. CLI同期ワーカー（workers/syncDisputes.php） Stripe APIから既存のすべての異議申立を取得するスクリプト（$stripe->disputes->all(['limit' => 100])とstarting_afterでページネーション）、ローカルの異議申立データベースに保存し、まだneeds_responseまたはwarning_needs_responseステータスでエビデンスが提出されていないものについては、共有のcollectDisputeEvidence()関数を使用してエビデンスを自動提出します。これは、Webhookが将来の異議申立のみをキャッチし、既存のものはキャッチしないため必要です。CLIでのみ実行します（php workers/syncDisputes.php）。同期結果を含むJSONキャッシュファイルを保存し、ダッシュボードが最後の同期時刻を表示できるようにします。 5. ミニダッシュボード（disputes.php、?key=認証付き） ?key=クエリパラメータで保護されたシンプルなHTMLページで、以下を表示します： - 統計ボックス：総異議申立数、保留中、勝訴、敗訴、過去30日間の異議申立（金額+件数）、過去12か月間の異議申立（金額+件数）、総異議申立金額 - CLI同期コマンドとキャッシュからの最終同期時刻を示すメモ - stripe_customer_idを入力して、提出されるエビデンスをプレビューするテストフォーム（実際には提出しない） - すべての異議申立の表：日付、メール、金額、理由、ステータス（色付きバッジ）、エビデンス提出ステータス、詳細ビューとStripeダッシュボードの両方へのリンク 詳細ビュー（action=view&id=dispute_id）：すべての異議申立情報、Stripeへのリンク、「エビデンスを再生成」ボタン、PDFファイルリンク、StripeファイルアップロードID、すべてのテキストエビデンスフィールドを表示します。 エビデンスの再生成（action=regen&id=dispute_id）：領収書とサービス文書PDFを再生成し、ファイルストレージにアップロードし、evidence_jsonを新しいPDF URLで更新します。fastcgi_finish_request()を使用してHTTP応答を即座に送信し（「バックグラウンドで再生成中」の通知とともに詳細ページにリダイレクト）、その後バックグラウンドでPDFの生成を続行して、フロントエンドのタイムアウトを防ぎます。 ページのnginxリライトを追加します（例：rewrite ^/disputes/?$ /disputes.php）。正しいnginx設定ファイルにあることを確認します（sites-enabledのシンボリックリンクが実際にどのファイルを指しているかを確認します）。 6. Telegram通知 - 新しい異議申立：「{site name} - {email}から${amount}（{reason}）の新しい異議申立。エビデンスはStripeに自動提出されました。{stripe_dashboard_link}」 - エビデンス失敗：「{site name} - {email}から${amount}（{reason}）の新しい異議申立。エビデンス提出が失敗しました：{error}」 - 異議申立の勝訴/敗訴と結果およびリンク - DB権限エラー：「{site name} - 異議申立DBエラー：{error} - data/disputes.dbの権限を確認してください」 7. StripeダッシュボードでこれらのStripe Webhookイベントが有効になっていることを確認します：charge.dispute.created、charge.dispute.updated、charge.dispute.closed 8. データベース権限 disputes.dbファイルは、Webサーバーユーザー（例：www-data）が書き込み可能である必要があります。CLIからrootとして作成した場合は、他のDBファイルと一致するように所有権を修正します。PHP-FPMはrootとは異なるユーザーとして実行されます。 9. 依存関係 - FPDF（setasign/fpdf）PDF生成用、composer require setasign/fpdfでインストール - GD拡張機能（画像リサイズ用、通常は既にインストールされています） - Stripe PHP SDK（Stripe Webhookがある場合は既にインストールされています） - AWS S3 SDK（R2/S3アップロード用、Cloudflare R2を使用している場合は既にインストールされています）