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 Flagcommerce.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.mdindirekt, 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.destinationzum eingeloggten Portal-Owner-Tenant gehört) - Splits-Editor: Plattform-Admin setzt globale + per-Plan
application_fee_percentoderapplication_fee_amount(in basis points), Portal-Owner sieht effective Earnings pro Transaktion in Echtzeit-Preview - Hardening:
application_fee_amountwird serverseitig aus Plan-Konfiguration berechnet, niemals vom Client gesetzt (heute hardcoded0, 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
- Connect-Module-Skeleton + Feature-Flag —
app/modules/commerce-connect/, Feature-Flagcommerce.connect_enabled. Commit:11-backlog/stripe-marketplace-ui: scaffold connect module - Embedded-Onboarding-UI — Connect-Account erstellen (Server-Action), Embedded-Onboarding-Component mounten, Status-Polling. Commit:
11-backlog/stripe-marketplace-ui: connect onboarding wizard - Splits-Editor + Server-side Fee-Calculation — Settings-UI für Splits, Server berechnet
application_fee_amountaus Plan-Config, alte hardcoded0ersetzt. Commit:11-backlog/stripe-marketplace-ui: splits editor + fee hardening - Payouts-Dashboard — Balance + Payout-Liste via Stripe API, CSV-Export. Commit:
11-backlog/stripe-marketplace-ui: payouts dashboard - 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 - Refund-Flow — UI + Server-Action + Webhook-Handling für
charge.refunded. Commit:11-backlog/stripe-marketplace-ui: refund flow - Dispute-Flow — Webhook-Handler für
charge.dispute.*, Evidence-Upload, Status-Tracking. Commit:11-backlog/stripe-marketplace-ui: dispute flow - 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_amountwird serverseitig aus Plan-Config berechnet (kein hardcoded0mehr), 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_enabledschaltet alle Connect-UIs ab; bestehende Connect-Accounts bleiben in Stripe gültig - Splits-Editor-Wert kann auf
0zurü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_payoutTables; Drop-Reihenfolge in der Migration-Down dokumentiert
Security Notes
- destination-Validation ist sicherheitskritisch — ohne Cross-Check könnte Tenant-A bei Checkout
destinationauf Connect-Account von Tenant-B setzen und dessen Earnings stehlen. Server-Validation Pflicht application_fee_amountdarf 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-verifierfür jede Phase (1/2/3) separat - Code-Review:
gsd-code-reviewernach Step 3 (Fee-Hardening) und nach Step 8 (final)
Staging-Deployment-Steps
- Branch
agent/11-backlog-stripe-marketplace-uipushen - Stripe-Test-Mode-Account für Staging mit aktiviertem Connect provisionieren
- Test-Webhook-Endpoint registrieren (Stripe-CLI
stripe listen --forward-to ...) - Test-Portal-Owner-Tenant durch kompletten Onboarding-Flow schicken
- 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.)