# 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.)_