Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/11-backlog/stripe-marketplace-ui.md
T

8.9 KiB

Stripe-Marketplace-UI (Connect Onboarding + Splits + Payouts)

Status: backlog: B2B2C-Marketplace-Modell aktiviert (Portal-Owner verkaufen via Plattform an Endkunden, Plattform nimmt application_fee) Task-ID: #57 Phase: 11 (Backlog) Estimated Effort: 3-4 Wochen wenn aktiviert Owner: unassigned

Problem

Die Boilerplate unterstützt heute klassische B2B-Subscriptions (Plattform-Tenant zahlt Plattform-Owner). Sobald das Geschäftsmodell sich Richtung B2B2C öffnet — Portal-Owner verkaufen über die Plattform Subscriptions/One-Time-Purchases an ihre Endkunden, Plattform behält eine application_fee — fehlt die komplette Connect-UI-Schicht: Connect-Onboarding für Portal-Owner, Splits-Konfiguration, Payouts-Dashboard, Refund-/Dispute-Workflow.

Zusätzlich ist application_fee_amount heute auf 0 hardcoded — das funktioniert nur, weil Connect noch gar nicht produktiv genutzt wird. Bei Aktivierung muss diese Stelle gehärtet werden, sonst verschenkt die Plattform jede Connect-Transaktion.

Depends on

  • ../05-business-features/feature-flags.md — Connect-Features hinter Flag commerce.connect_enabled, damit nicht-Marketplace-Tenants es nicht sehen
  • bestehendes Stripe-Subscription-Setup (heute schon im Codebase, siehe apps/web/app/modules/subscriptions/)
  • ../10-compliance-polish/compliance-audit-export.md — Connect-Onboarding-Verifikations-Status muss audit-loggable sein (KYC-Events)

Blocks

  • nichts (Backlog-Item, blockt keine aktive Roadmap; entblockt aber plugin-marketplace.md indirekt, weil Connect dort wiederverwendet wird)

Approach

Drei-Phasen-Rollout wenn aktiviert. Begründung gegen Alternativen:

  • Manuelle Splits via Stripe-Dashboard: zu fehleranfällig + nicht skalierbar bei vielen Portal-Ownern. Verworfen.
  • Stripe-Standard-Account-Onboarding (Redirect): schlechter UX-Übergang, brüchige Brand-Experience. Verworfen.
  • Embedded-Onboarding (gewählt): Stripe-Connect-Embedded-Components rendern direkt in der App, bleiben in der Plattform-Domain, geben strukturierte Status-Events zurück.

Phase 1 (Wochen 1-2): Connect-Onboarding-Wizard + Splits-Editor

  • Connect-Onboarding-Wizard für Portal-Owner mit Stripe-Connect-Embedded-Onboarding-Components, Verifikations-Status-Polling (KYC pending / verified / restricted), destination-Validation gegen Connect-Account-Owner (cross-check dass übergebene transfer_data.destination zum eingeloggten Portal-Owner-Tenant gehört)
  • Splits-Editor: Plattform-Admin setzt globale + per-Plan application_fee_percent oder application_fee_amount (in basis points), Portal-Owner sieht effective Earnings pro Transaktion in Echtzeit-Preview
  • Hardening: application_fee_amount wird serverseitig aus Plan-Konfiguration berechnet, niemals vom Client gesetzt (heute hardcoded 0, wird durch Settings-driven Berechnung ersetzt)

Phase 2 (Woche 3): Payouts-Dashboard + KYC-Monitoring

  • Payouts-Dashboard für Portal-Owner: kommende Payouts (Stripe Balance API), Historie der vergangenen Payouts, CSV-Export
  • KYC-Status-Monitoring: Background-Job pollt Connect-Accounts auf Status-Changes (verified → restricted etc.), Notification an Portal-Owner + Plattform-Admin bei Hold/Restriction
  • Audit-Events: commerce.connect.onboarding.completed, commerce.connect.kyc.status_changed, commerce.payout.scheduled

Phase 3 (Woche 4): Refund-/Dispute-Flow + Doku

  • Refund-Flow: Portal-Owner kann Refunds aus Order-Detail-Seite triggern; application_fee wird Stripe-default proportional zurückerstattet (oder konfigurierbar pro Refund)
  • Dispute-Flow: Dispute-Webhook → Notification an Portal-Owner + Plattform-Admin, Evidence-Upload-UI für Portal-Owner, Status-Tracking
  • Doku: docs/commerce/connect-setup.md (Plattform-Admin-Sicht), docs/commerce/portal-owner-guide.md (Portal-Owner-Sicht inkl. KYC-FAQ)

Implementation Steps

  1. Connect-Module-Skeleton + Feature-Flag — app/modules/commerce-connect/, Feature-Flag commerce.connect_enabled. Commit: 11-backlog/stripe-marketplace-ui: scaffold connect module
  2. Embedded-Onboarding-UI — Connect-Account erstellen (Server-Action), Embedded-Onboarding-Component mounten, Status-Polling. Commit: 11-backlog/stripe-marketplace-ui: connect onboarding wizard
  3. Splits-Editor + Server-side Fee-Calculation — Settings-UI für Splits, Server berechnet application_fee_amount aus Plan-Config, alte hardcoded 0 ersetzt. Commit: 11-backlog/stripe-marketplace-ui: splits editor + fee hardening
  4. Payouts-Dashboard — Balance + Payout-Liste via Stripe API, CSV-Export. Commit: 11-backlog/stripe-marketplace-ui: payouts dashboard
  5. KYC-Status-Background-Job — Worker (Phase 03 Worker-Queues) pollt täglich, schreibt Audit-Events, sendet Notifications. Commit: 11-backlog/stripe-marketplace-ui: kyc monitoring
  6. Refund-Flow — UI + Server-Action + Webhook-Handling für charge.refunded. Commit: 11-backlog/stripe-marketplace-ui: refund flow
  7. Dispute-Flow — Webhook-Handler für charge.dispute.*, Evidence-Upload, Status-Tracking. Commit: 11-backlog/stripe-marketplace-ui: dispute flow
  8. Doku — docs/commerce/connect-setup.md + docs/commerce/portal-owner-guide.md. Commit: 11-backlog/stripe-marketplace-ui: documentation

Test Requirements

  • Unit-Tests: Fee-Calculation (Plan + global Override + per-Plan-Override), destination-Validation (Tenant-Ownership-Check), CSV-Export-Formatter
  • Integration-Tests: Onboarding-Flow End-to-End mit Stripe-Test-Mode, Webhook-Handling für account.updated / charge.refunded / charge.dispute.created, Splits-korrekte-Verbuchung
  • E2E-Tests (Playwright): Onboarding-Wizard Happy-Path, Refund aus Order-Detail-Seite, Dispute-Evidence-Upload
  • Coverage-Target: ≥75% für app/modules/commerce-connect/
  • Test-Files: neben Source, E2E unter apps/web/playwright/commerce-connect/

NICHT als completed markieren bevor alle Tests grün sind.

Acceptance Criteria

  • Portal-Owner kann sich via Embedded-Onboarding-Wizard durchführen, Status-Update nach Stripe-Verifikation erscheint im Dashboard
  • Splits-Editor: Plattform-Admin setzt Fee, Portal-Owner sieht korrekte Effective-Earnings-Preview
  • application_fee_amount wird serverseitig aus Plan-Config berechnet (kein hardcoded 0 mehr), Cross-Check mit Stripe-Dashboard zeigt korrekte Verbuchung
  • Payouts-Dashboard zeigt kommende + historische Payouts, CSV-Export funktioniert
  • KYC-Status-Change-Notification erreicht Portal-Owner binnen 24h
  • Refund-Flow funktioniert, application_fee wird proportional erstattet
  • Dispute-Webhook erzeugt Notification, Evidence-Upload funktioniert
  • Tests grün
  • Docs angelegt
  • Progress-Log + PROGRESS.md aktualisiert

Rollback Strategy

  • Feature-Flag commerce.connect_enabled schaltet alle Connect-UIs ab; bestehende Connect-Accounts bleiben in Stripe gültig
  • Splits-Editor-Wert kann auf 0 zurückgesetzt werden — Plattform nimmt dann keine Fee, ohne dass Transactions brechen
  • Webhook-Handler für Refund/Dispute können einzeln deaktiviert werden, Stripe queued Webhooks für Retry
  • DB-Migration: commerce_connect_account + commerce_payout Tables; Drop-Reihenfolge in der Migration-Down dokumentiert

Security Notes

  • destination-Validation ist sicherheitskritisch — ohne Cross-Check könnte Tenant-A bei Checkout destination auf Connect-Account von Tenant-B setzen und dessen Earnings stehlen. Server-Validation Pflicht
  • application_fee_amount darf niemals vom Client beeinflusst sein
  • Webhook-Signatur-Verifikation (stripe-signature) muss bei jedem Webhook geprüft werden (heute teils schon der Fall, hier auf alle Connect-Webhooks ausweiten)
  • KYC-Daten sind sensitive: Portal-Owner-Tenant darf nur seine eigenen KYC-Status sehen, Plattform-Admin sieht alle (Rollen-Check)
  • Refund-Trigger ist privilegierte Action: Audit-Log mit Acting-User + Reason

Subagent Recommendations

  • Planning: Plan-Subagent mit Stripe-Connect-Docs als Input
  • Research: Explore-Subagent für Stripe-Connect-Embedded-Onboarding-Patterns (Best-Practices, bekannte Fallstricke bei destination-Validation)
  • Implementation: ein general-purpose-Subagent pro Step
  • Tests: separater general-purpose-Subagent für E2E (Stripe-Test-Mode benötigt sauberes Test-Account-Setup)
  • Verification: gsd-verifier für jede Phase (1/2/3) separat
  • Code-Review: gsd-code-reviewer nach Step 3 (Fee-Hardening) und nach Step 8 (final)

Staging-Deployment-Steps

  1. Branch agent/11-backlog-stripe-marketplace-ui pushen
  2. Stripe-Test-Mode-Account für Staging mit aktiviertem Connect provisionieren
  3. Test-Webhook-Endpoint registrieren (Stripe-CLI stripe listen --forward-to ...)
  4. Test-Portal-Owner-Tenant durch kompletten Onboarding-Flow schicken
  5. Test-Order mit Splits, Refund, Dispute durchspielen

Deviations from Plan

(Wird vom ausführenden Agent gefüllt.)

Progress Log

(Wird vom ausführenden Agent gefüllt.)