124 lines
8.9 KiB
Markdown
124 lines
8.9 KiB
Markdown
# 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.)_
|