带证据PDF的Stripe自动争议响应系统

为Stripe构建一个自动争议响应系统，该系统： 1. 共享证据收集（app/dispute_evidence.php） 创建一个共享文件，其中包含webhook和同步工作器都使用的函数。这避免了重复的证据逻辑。 关键函数： - getDisputeUserPlan($user, $stripe) - 从Stripe API获取用户的订阅计划（事实来源，因为本地数据库中的计划字段在取消时会被清除）。如果Stripe调用失败，则回退到本地数据库字段。将产品ID映射到计划名称，并包含价格/间隔和取消状态。 - collectDisputeEvidence($stripe, $user, $email, $charge, $photosDb) - 收集所有文本和文件证据，返回一个准备提交给Stripe的数组。 - generateServiceDocPdf($stripe, $user, $email, $photos_done, $recent_photos, $total_amount_paid) - 生成一个PDF，包含客户信息、使用摘要、最近活动表，以及最多6张实际产品图片（调整为500像素宽/质量75的JPEG，以保持在Stripe的5MB文件上传限制内）。返回Stripe文件ID和原始PDF数据。 重要：从Stripe charges API获取total_amount_paid（成功且未退款费用的总和），而不是信任可能为空/过期的本地数据库。 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张客户收到的实际产品图片/截图。嵌入前调整图片大小（500像素宽，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=认证） 一个简单的HTML页面，受?key=查询参数保护，显示： - 统计框：总争议、待处理、赢、输、最近30天争议（金额+数量）、最近12个月争议（金额+数量）、总争议金额 - 显示CLI同步命令和缓存中上次同步时间的说明 - 一个测试表单，您输入stripe_customer_id以预览将提交哪些证据（不实际提交） - 所有争议的表：日期、电子邮件、金额、原因、状态（彩色徽章）、证据提交状态、指向详细视图和Stripe仪表板的链接 详细视图（action=view&id=dispute_id）：显示所有争议信息、指向Stripe的链接，以及“重新生成证据”按钮、PDF文件链接、Stripe文件上传ID、所有文本证据字段。 重新生成证据（action=regen&id=dispute_id）：重新生成收据和服务文档PDF并上传到文件存储，用新的PDF URL更新evidence_json。使用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}” - 争议赢/输，包含结果和链接 - 数据库权限错误：“{site name} - 争议数据库错误：{error} - 检查data/disputes.db的权限” 7. 确保在Stripe仪表板中启用这些Stripe webhook事件：charge.dispute.created、charge.dispute.updated、charge.dispute.closed 8. 数据库权限 disputes.db文件必须可由Web服务器用户（例如www-data）写入。如果您以root身份从CLI创建它，请修复所有权以匹配您的其他数据库文件。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，则已安装）