Validierung des ersten Erfolgs

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.

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

Zusammenfassung der Checkliste

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.

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

Validierung des ersten Erfolgs

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.

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

Zusammenfassung der Checkliste

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.

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

Validierung des ersten Erfolgs

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.

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

Zusammenfassung der Checkliste

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.

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

1. 1

   1. Entwicklungsserver

   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. 2

   2. 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. 3

   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. 4

   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:

   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. 5

   5. Tunnel-Bereitschaft (erweitert)

   Erwartet werden "ready" und eine Anbieterliste aus lib/tunnel/config. Live-SSE: Tab Network → /api/tunnel/sse nach der Anmeldung. Siehe Tunnel-Protokoll.

6. 6

   6. Smoke-Test für Mitgliedschaften über PaymentConductor (optional)

   Erst nachdem die Migrationen 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.

Wann du anhalten und korrigieren solltest

• Wiederholte Verbindungsfehler zu Postgres → DB_* / DB_BACKEND_MODE in den Voraussetzungen.
• 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.

Gleicher Ablauf: Korrekturen an Authentifizierung und Datenbank, wenn eine Zeile der Checkliste rot bleibt.

1. 1

   1. Entwicklungsserver

   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. 2

   2. 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. 3

   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. 4

   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:

   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. 5

   5. Tunnel-Bereitschaft (erweitert)

   Erwartet werden "ready" und eine Anbieterliste aus lib/tunnel/config. Live-SSE: Tab Network → /api/tunnel/sse nach der Anmeldung. Siehe Tunnel-Protokoll.

6. 6

   6. Smoke-Test für Mitgliedschaften über PaymentConductor (optional)

   Erst nachdem die Migrationen 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.

Wann du anhalten und korrigieren solltest

• Wiederholte Verbindungsfehler zu Postgres → DB_* / DB_BACKEND_MODE in den Voraussetzungen.
• 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.

Gleicher Ablauf: Korrekturen an Authentifizierung und Datenbank, wenn eine Zeile der Checkliste rot bleibt.

1. 1

   1. Entwicklungsserver

   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. 2

   2. 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. 3

   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. 4

   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:

   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. 5

   5. Tunnel-Bereitschaft (erweitert)

   Erwartet werden "ready" und eine Anbieterliste aus lib/tunnel/config. Live-SSE: Tab Network → /api/tunnel/sse nach der Anmeldung. Siehe Tunnel-Protokoll.

6. 6

   6. Smoke-Test für Mitgliedschaften über PaymentConductor (optional)

   Erst nachdem die Migrationen 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.

Wann du anhalten und korrigieren solltest

• Wiederholte Verbindungsfehler zu Postgres → DB_* / DB_BACKEND_MODE in den Voraussetzungen.
• 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.

Gleicher Ablauf: Korrekturen an Authentifizierung und Datenbank, wenn eine Zeile der Checkliste rot bleibt.