--- title: "Validierung des ersten Erfolgs" description: "Aktivierungs-Smoke-Test für Gründer: Sitzung nach der Registrierung, CRUD in Postgres, Tunnel bereit, optionaler Mitgliedschafts-Checkout über PaymentConductor (Migration / Onboarding)" locale: "de" --- # Validierung des ersten Erfolgs > **Success** > **Fertig, wenn:** `npm run dev` Seiten ausliefert, `GET /api/health` `healthy` meldet (oder du `AUTH_SECRET` korrigiert hast), eine Auth.js-Anmeldung eine Sitzung herstellt und ein authentifizierter CRUD-Weg funktioniert (Entitäten oder Opportunities). Tunnel `ready` und der Smoke-Test für Mitgliedschaften über PaymentConductor sind **erweitert**: Sie blockieren das Branding am ersten Tag nicht. > **Info** > Filtere mit **Gründer** / **Entwickler** in der Seitenleiste. Führe das **nach** der [Installation](/docs/getting-started/installation.md) und den [Migrationen](/docs/getting-started/migrations.md) aus. Die Kernprüfungen sind ein kurzer Durchgang im Browser. Zahlungen brauchen das PSP-Env + `004_payment_transactions`, bevor du den Checkout als grün betrachtest. **Erster Erfolg** bedeutet: Der eigene `server.ts` / die Next-App liefert Seiten aus, **Auth.js v5** kann eine Sitzung herstellen, **DatabaseService** liest und schreibt ohne Adapter-Abstürze, und die zentralen Marketplace-Routen laden. Am ersten Tag sind WayForPay, Stripe, PayPal, FCM oder eine Wallet-Verbindung **nicht** erforderlich. | Stufe | Was funktionieren muss | Gut genug, um… | |----------|----------------|-----------------| | **Kern** | Startseite + `/api/health` + Anmeldung über einen Anbieter + ein CRUD-Weg | Branding anpassen, Tester einladen | | **Erweitert** | `GET /api/tunnel/test` → `status: ready`; UI für Entitäten + Opportunities | Echtzeit / Discovery vorführen | | **Optionale Zahlung** | Mitgliedschaft starten → Weiterleitung durch PaymentConductor oder Abrechnung über Guthaben | Sandbox-Checkout / Probe eines Rollen-Upgrades | ## Empfohlener Weg Nutze das LegioX-MCP **`legiox-env-validator`** (oder frag den Agenten mit dem Prompt unten), **bevor** du UI-Fehlern nachjagst. Es meldet fehlende Env-Werte. Es ändert **keine** `.env`, startet keine Prozesse neu und ruft keine PSPs auf, bis du zustimmst. **Start-Prompt:** > Prüfe diesen Klon für den Smoke-Test des ersten Erfolgs: `AUTH_SECRET`, `DB_BACKEND_MODE` / Postgres-`DB_*` und optional `WAYFORPAY_*` / `STRIPE_*` / `PAYPAL_*`. Liste fehlende Variablen und die Checkliste Kern gegenüber Optionale Zahlung aus `/docs/getting-started/first-success` auf. Schreibe keine Secrets und starte den Server nicht neu, bis ich zustimme. **Checkliste der Eingaben** - Arbeitsbaum nach Installation + Migrationen - `.env.local` aus `env.local.template` (oder ein eingebundenes k8s-Secret) - Browser auf `http://localhost:3000` (oder deiner konfigurierten Site-URL) - Optional: Sandbox-Zugangsdaten für WayForPay / Stripe / PayPal ## Manueller Weg ### 1. Entwicklungsserver {`npm run dev`} Erwartet wird Next.js bereit unter `http://localhost:3000`. Das Paket-Skript führt `node --import tsx server.ts` aus. Mit `RING_DEPLOY_TARGET=self-hosted` kann der eigene Server natives WSS protokollieren. ### 2. Health {`curl -sS http://localhost:3000/api/health | jq . curl -I http://localhost:3000/api/health`} Geprüfte Struktur (`app/api/health/route.ts`): `status` ist `healthy` | `degraded` | `unhealthy` (nicht `"ok"`). `services.database` ist `postgresql` oder `firebase`. Fehlendes `AUTH_SECRET` → `degraded` und HTTP **503**. `HEAD` liefert **200**, wenn der Prozess läuft. ### 3. Startseite + Anmeldung 1. Öffne `/`: Erwartet wird HTTP **200**, kein leerer Bildschirm und kein Adapter-Absturz im Terminal. 2. Rufe `/login` auf (ein Sprachpräfix kann gelten: `/en/login`). 3. Schließe **einen** Anbieter aus `auth.ts` ab: Google OAuth, Apple, Ring Mailer (OTP / Magic Link / E-Mail + Passwort), Google One Tap oder Krypto-Wallet-Credentials. Der Standardbaum liefert GitHub/Discord **nicht** mit. 4. Prüfe die Sitzung: `/profile` zeigt die Benutzerdaten, und sie bleiben nach dem Neuladen erhalten. Optional: `GET /api/auth/session` mit den Browser-Cookies liefert `{ user: { id, email, role, … } }`. ### 4. Authentifiziertes CRUD `/api/entities` und `/api/opportunities` erfordern eine Sitzung: **401 ohne Cookies ist zu erwarten**. Nach der Anmeldung im Browser: 1. `/entities`: Liste und Erstellformular werden abgeschickt (ein Visitor kann beim Schreiben 403 erhalten; nutze ein Testkonto mit member/admin). 2. `/opportunities`: Die Liste lädt für deine Rolle. Optionale Prüfung in Postgres: {`psql "$DATABASE_URL" -c "SELECT COUNT(*) FROM users;"`} Nach der ersten Anmeldung ist ein Zählwert ≥ 1 zu erwarten. Eine Route `/api/test-db` gibt es **nicht**: nutze `psql` oder die authentifizierten APIs. ### 5. Tunnel-Bereitschaft (erweitert) {`curl -sS http://localhost:3000/api/tunnel/test | jq .status, .availableProviders`} Erwartet werden `"ready"` und eine Anbieterliste aus `lib/tunnel/config`. Live-SSE: Tab Network → `/api/tunnel/sse` nach der Anmeldung. Siehe [Tunnel-Protokoll](/docs/features/tunnel-protocol.md). ### 6. Smoke-Test für Mitgliedschaften über PaymentConductor (optional) Erst nachdem die [Migrationen](/docs/getting-started/migrations.md) `004_payment_transactions.sql` angewendet haben und du das Env des Zahlungsanbieters aus `env.local.template` gesetzt hast (`WAYFORPAY_*` und/oder `STRIPE_*` und/oder `PAYPAL_*`). 1. Melde dich als Nicht-Admin an, der ein Upgrade machen darf (`UPGRADEABLE_ROLES`, kein Kauf durch platform-admin). 2. Öffne `/membership` → wähle eine höhere Stufe und eine konfigurierte Rail (`card` → WayForPay/Stripe über PaymentConductor, `paypal` oder `credit_balance`, wenn die Wallet Guthaben hat). 3. Die Server Action `initiateMembershipPayment` (`app/_actions/membership-payment.ts`) ruft `PaymentConductor.createCheckout({ purpose: 'membership_upgrade', … })` auf (bei manchen Rails zuerst SubscriptionConductor). 4. Erwartet wird eine Weiterleitungs-URL / Form-Post-Felder zum PSP oder ein sofortiger Erfolgsweg für internes Guthaben. 5. Kanonische Webhooks (Callback-URLs für Produktion/Sandbox): `/api/payments/wayforpay/webhook`, `/api/payments/stripe/webhook`, `/api/payments/paypal/webhook` (`getWebhookUrl` in `lib/payments/payment.config.ts`). 6. Nach der Verarbeitung von Approved / `checkout.session.completed` / PayPal-Capture landet die UI auf `/membership/success` oder `/membership/failure`. Erkläre den Produktions-Checkout **nicht** für fertig, solange HMAC-/Signaturprüfung und Rücksprung-URLs nicht zu deiner öffentlichen Site-URL passen. Im Detail: [PaymentConductor](/docs/features/payment-conductor.md). ### For founders ## Warum das für deinen Klon wichtig ist Geh vor Demos für Stakeholder den **Happy Path eines Mitglieds** selbst durch: - **[Auf der Startseite landen](/docs/getting-started/installation.md)** — Kein leerer Bildschirm und kein Absturz des Datenbankadapters im Terminal. - **[Registrieren / anmelden](/docs/features/authentication.md)** — Google, Apple oder Ring Mailer, je nachdem, was du konfiguriert hast (SMTP oder Ethereal). - **[Eine Entität anlegen](/docs/features/entities.md)** — Belegt JSONB-Schreibzugriffe in Postgres und die Rollenprüfungen. - **[Mitgliedschafts-Checkout (optional)](/docs/features/payment-conductor.md)** — Sandbox-Gebühr → PaymentConductor → Webhook. Erst, wenn das Zahlungs-Env gesetzt ist. Authentifizierung + ein CRUD-Ablauf ohne Push-Benachrichtigungen oder Wallet ist trotzdem ein **gültiger Entwicklungsklon**. Binde FCM und PaymentConductor an, bevor du bezahlte Mitgliedschaften oder einen Shop-Checkout versprichst ([Umgebung](/docs/deployment/environment.md)). ### Wann du anhalten und korrigieren solltest - Wiederholte Verbindungsfehler zu Postgres → `DB_*` / `DB_BACKEND_MODE` in den [Voraussetzungen](/docs/getting-started/prerequisites.md). - Weiterleitungsschleife beim Login → `AUTH_SECRET` und OAuth-Weiterleitungs-URIs (`http://localhost:3000/api/auth/callback/google`). - 403 beim Speichern einer Entität → für **visitor** zu erwarten; melde dich als **member** an oder erhöhe die Rolle des Testkontos. - Fehler beim Starten der Mitgliedschaft wegen fehlender Händlerschlüssel → `WAYFORPAY_*` / Stripe / PayPal setzen und erneut versuchen. ### For developers ## Implementierungsübersicht | Thema | Geprüfter Pfad | |---------|----------------| | Health | `app/api/health/route.ts` | | Auth-Anbieter | `auth.ts` (Google, Apple, Ring-Mailer-Credentials, One Tap, Wallet) | | Mitgliedschaft starten | `app/_actions/membership-payment.ts` → `PaymentConductor.createCheckout` | | Conductor | `lib/payments/conductor/payment-conductor.ts` | | Webhooks | `app/api/payments/{wayforpay\|stripe\|paypal}/webhook/route.ts` | | Tunnel-Test | `app/api/tunnel/test/route.ts` (`status: 'ready'` bei Erfolg) | | Wallet-Guthaben (optional) | `GET /api/wallet/balance` → `{ balance }` oder **401** / **404** | | Skripte | `npm run type-check`, `npm run build` (der Build führt type-check aus) | ```mermaid flowchart LR Dev[npm run dev] --> Health[/api/health] Health --> Login[/login] Login --> PG[(PostgreSQL)] Login --> Ent[/entities CRUD] Login --> Opp[/opportunities] Login --> Tun[/api/tunnel/test] Login --> Mem[/membership] Mem --> PC[PaymentConductor] PC --> WH[/api/payments/.../webhook] ``` > **Warning** > Die Postgres-Erkennung der Health-Route nutzt `DATABASE_BACKEND=postgresql` oder `DB_HOST` / `POSTGRES_HOST`, nicht allein den String `DB_BACKEND_MODE`. Halte beide Variablengruppen mit `env.local.template` abgestimmt, damit `services.database` `postgresql` meldet, wenn du es erwartest. ## Zusammenfassung der Checkliste | Prüfung | Bestanden? | |-------|-------| | `npm run dev` startet ohne Absturz des Datenbankadapters | ☐ | | `GET /api/health` → `healthy` (oder `AUTH_SECRET` korrigiert) | ☐ | | Anmeldung über einen Auth.js-Anbieter funktioniert | ☐ | | Entität anlegen/auflisten **oder** Liste der Opportunities funktioniert in der UI | ☐ | | `GET /api/tunnel/test` → `status: ready` | ☐ | | Optional: Start der Mitgliedschaft liefert Weiterleitung / Erfolg über Guthaben | ☐ | ## Häufige Fragen ### Auswirkungen #### Funktioniert mein Klon ohne Zahlungen? Ja. Der erste Erfolg im Kern besteht aus Authentifizierung + Datenweg. PaymentConductor ist optional, bis du bezahlte Mitgliedschaften oder den Shop-Checkout vorführst. #### Bedeutet Tunnel `ready`, dass SSE live ist? Nein. `/api/tunnel/test` bestätigt Konfiguration und Anbietererkennung. Live-Streams brauchen einen angemeldeten Client, der `/api/tunnel/sse` (oder deinen konfigurierten Anbieter) aufruft. ### Migration #### Brauche ich `004_payment_transactions` für den Kern? Nein. Wende sie vor dem Smoke-Test für Optionale Zahlung an, damit das Ledger Mitgliedschafts- und Shop-Intents erfassen kann. #### Prototyp nur mit Firebase? `firebase-full` kann bei einem Prototyp Startseite + Authentifizierung bestehen, aber die Tiefe von PaymentConductor und die ERP-/News-Funktionen setzen Postgres als Primärdatenbank voraus (`k8s-postgres-fcm` / `supabase-fcm`). Siehe [Datenbankauswahl](/docs/customization/database-selection.md). ### Betrieb #### Health liefert 503 mit `degraded`: Ist die App ausgefallen? Der Prozess läuft. Ein fehlendes `AUTH_SECRET` (Postgres-Weg) oder fehlende kritische Firebase-Variablen verschlechtern den Status. Setze die Secrets, starte neu und wiederhole den curl. #### Wallet-Guthaben 404? `GET /api/wallet/balance` liefert **404**, wenn noch keine Wallet-Zeile existiert. Das ist kein Fehler im Kern. Lege die Wallet nach der Authentifizierung über die Wallet-Abläufe an oder lade sie auf. ## Verwandte Dokumentation - [getting-started/installation](/docs/getting-started/installation.md) — Voraussetzung: Installation und Env vor dieser Smoke-Checkliste. - [getting-started/migrations](/docs/getting-started/migrations.md) — Voraussetzung: Schema + 004_payment_transactions vor dem Smoke-Test von PaymentConductor. - [features/authentication](/docs/features/authentication.md) — Vertiefung: Auth.js-Anbieter und Sitzungsstruktur, sobald die Registrierung funktioniert. - [features/payment-conductor](/docs/features/payment-conductor.md) — Nächster Schritt: Rails, Ledger und Webhooks, nachdem der Start der Mitgliedschaft funktioniert. - [getting-started/troubleshooting](/docs/getting-started/troubleshooting.md) — Gleicher Ablauf: Korrekturen an Authentifizierung und Datenbank, wenn eine Zeile der Checkliste rot bleibt. - [getting-started/next-steps](/docs/getting-started/next-steps.md) — Nächster Schritt: Funktionen erkunden, sobald die Kernprüfungen grün sind.