--- title: "Validación del primer éxito" description: "Prueba rápida de activación para fundadores: sesión de registro, CRUD en Postgres, túnel listo y checkout opcional de membresía con PaymentConductor (migración / onboarding)" locale: "es" --- # Validación del primer éxito > **Success** > **Está hecho cuando:** `npm run dev` sirve páginas, `GET /api/health` devuelve `healthy` (o ya corregiste `AUTH_SECRET`), un inicio de sesión de Auth.js crea una sesión y funciona un camino CRUD autenticado (entidades u oportunidades). El túnel en `ready` y la prueba de membresía con PaymentConductor son **ampliados**: no bloquean la personalización de marca del primer día. > **Info** > Filtra con **Fundador** / **Desarrollador** en la barra lateral. Ejecuta esto **después** de la [Instalación](/docs/getting-started/installation.md) y las [Migraciones](/docs/getting-started/migrations.md). Las comprobaciones básicas son una pasada corta por el navegador. Los pagos necesitan el env del PSP + `004_payment_transactions` antes de dar el checkout por bueno. **Primer éxito** significa que el `server.ts` propio / la app Next sirve páginas, **Auth.js v5** puede crear una sesión, **DatabaseService** lee y escribe sin fallos del adaptador y las rutas principales del marketplace cargan. **No** exige WayForPay, Stripe, PayPal, FCM ni conexión de billetera el primer día. | Nivel | Qué debe funcionar | Suficiente para… | |----------|----------------|-----------------| | **Básico** | Página de inicio + `/api/health` + inicio de sesión con un proveedor + un camino CRUD | Personalizar la marca, invitar a testers | | **Ampliado** | `GET /api/tunnel/test` → `status: ready`; UI de entidades + oportunidades | Demostrar tiempo real / descubrimiento | | **Pago opcional** | Inicio de membresía → redirección de PaymentConductor o liquidación con crédito | Checkout en sandbox / ensayo de mejora de rol | ## Camino recomendado Usa el MCP de LegioX **`legiox-env-validator`** (o pide al agente con el prompt de abajo) **antes** de perseguir fallos de la UI. Informa de las variables de env que faltan. **No** modifica `.env`, no reinicia procesos ni llama a los PSP hasta que lo apruebes. **Prompt inicial:** > Valida este clon para la prueba de primer éxito: `AUTH_SECRET`, `DB_BACKEND_MODE` / `DB_*` de Postgres y, opcionalmente, `WAYFORPAY_*` / `STRIPE_*` / `PAYPAL_*`. Enumera las variables que faltan y la lista Básico frente a Pago opcional de `/docs/getting-started/first-success`. No escribas secretos ni reinicies el servidor hasta que yo lo apruebe. **Lista de entradas** - Árbol de trabajo después de la instalación + migraciones - `.env.local` a partir de `env.local.template` (o un secreto montado de k8s) - Navegador en `http://localhost:3000` (o la URL del sitio que hayas configurado) - Opcional: credenciales de sandbox de WayForPay / Stripe / PayPal ## Camino manual ### 1. Servidor de desarrollo {`npm run dev`} Espera Next.js listo en `http://localhost:3000`. El script del paquete ejecuta `node --import tsx server.ts`. Con `RING_DEPLOY_TARGET=self-hosted`, el servidor propio puede registrar WSS nativo en el log. ### 2. Salud {`curl -sS http://localhost:3000/api/health | jq . curl -I http://localhost:3000/api/health`} Forma verificada (`app/api/health/route.ts`): `status` es `healthy` | `degraded` | `unhealthy` (no `"ok"`). `services.database` es `postgresql` o `firebase`. Si falta `AUTH_SECRET` → `degraded` y HTTP **503**. `HEAD` devuelve **200** cuando el proceso está en marcha. ### 3. Página de inicio + inicio de sesión 1. Abre `/`: espera HTTP **200**, sin pantalla en blanco ni fallo del adaptador en la terminal. 2. Visita `/login` (puede aplicarse un prefijo de idioma: `/en/login`). 3. Completa **un** proveedor de `auth.ts`: Google OAuth, Apple, Ring Mailer (OTP / enlace mágico / correo + contraseña), Google One Tap o credenciales de billetera cripto. El árbol predeterminado **no** incluye GitHub/Discord. 4. Confirma la sesión: `/profile` muestra los datos del usuario y se mantiene al recargar. Opcional: `GET /api/auth/session` con las cookies del navegador devuelve `{ user: { id, email, role, … } }`. ### 4. CRUD autenticado `/api/entities` y `/api/opportunities` requieren sesión: **un 401 sin cookies es lo esperado**. Después de iniciar sesión en el navegador: 1. `/entities`: la lista carga y el formulario de creación se envía (un visitante puede recibir 403 al escribir; usa una cuenta de prueba member/admin). 2. `/opportunities`: la lista carga para tu rol. Comprobación opcional en Postgres: {`psql "$DATABASE_URL" -c "SELECT COUNT(*) FROM users;"`} Espera un recuento ≥ 1 después del primer inicio de sesión. **No** existe la ruta `/api/test-db`: usa `psql` o las API autenticadas. ### 5. Disponibilidad del túnel (ampliado) {`curl -sS http://localhost:3000/api/tunnel/test | jq .status, .availableProviders`} Espera `"ready"` y una lista de proveedores de `lib/tunnel/config`. SSE en vivo: pestaña Network → `/api/tunnel/sse` después de iniciar sesión. Consulta [Protocolo del túnel](/docs/features/tunnel-protocol.md). ### 6. Prueba de membresía con PaymentConductor (opcional) Solo después de que las [Migraciones](/docs/getting-started/migrations.md) hayan aplicado `004_payment_transactions.sql` y hayas definido el env del procesador a partir de `env.local.template` (`WAYFORPAY_*`, y/o `STRIPE_*`, y/o `PAYPAL_*`). 1. Inicia sesión como usuario no administrador que pueda mejorar de rol (`UPGRADEABLE_ROLES`, no la compra de platform-admin). 2. Abre `/membership` → elige un nivel superior y un rail configurado (`card` → WayForPay/Stripe mediante PaymentConductor, `paypal`, o `credit_balance` si la billetera tiene saldo). 3. La Server Action `initiateMembershipPayment` (`app/_actions/membership-payment.ts`) llama a `PaymentConductor.createCheckout({ purpose: 'membership_upgrade', … })` (o primero a SubscriptionConductor para algunos rails). 4. Espera una URL de redirección / campos de form-post hacia el PSP, o un camino de éxito inmediato para el crédito interno. 5. Webhooks canónicos (URL de callback de producción/sandbox): `/api/payments/wayforpay/webhook`, `/api/payments/stripe/webhook`, `/api/payments/paypal/webhook` (`getWebhookUrl` en `lib/payments/payment.config.ts`). 6. Después de procesar Approved / `checkout.session.completed` / la captura de PayPal, la UI llega a `/membership/success` o `/membership/failure`. **No** des el checkout de producción por válido hasta que la verificación HMAC/de firma y las URL de retorno coincidan con la URL pública de tu sitio. En detalle: [PaymentConductor](/docs/features/payment-conductor.md). ### For founders ## Por qué importa para tu clon Antes de hacer demos a las partes interesadas, recorre tú mismo el **camino feliz del miembro**: - **[Llegar a la página de inicio](/docs/getting-started/installation.md)** — Sin pantalla en blanco ni fallo del adaptador de base de datos en la terminal. - **[Registrarse / iniciar sesión](/docs/features/authentication.md)** — Google, Apple o Ring Mailer, el que hayas configurado (SMTP o Ethereal). - **[Crear una entidad](/docs/features/entities.md)** — Demuestra las escrituras JSONB en Postgres y los controles por rol. - **[Checkout de membresía (opcional)](/docs/features/payment-conductor.md)** — Cuota de sandbox → PaymentConductor → webhook. Solo cuando el env de pagos esté definido. Autenticación + un flujo CRUD sin notificaciones push ni billetera sigue siendo un **clon de desarrollo válido**. Conecta FCM y PaymentConductor antes de prometer membresía de pago o checkout de tienda ([Entorno](/docs/deployment/environment.md)). ### Cuándo parar y corregir - Fallos repetidos de conexión a Postgres → `DB_*` / `DB_BACKEND_MODE` en [Requisitos previos](/docs/getting-started/prerequisites.md). - Bucle de redirección en el inicio de sesión → `AUTH_SECRET` y URI de redirección de OAuth (`http://localhost:3000/api/auth/callback/google`). - 403 al guardar una entidad → es lo esperado para **visitor**; inicia sesión como **member** o sube el rol de la cuenta de prueba. - Errores al iniciar la membresía por falta de claves del comercio → define `WAYFORPAY_*` / Stripe / PayPal antes de reintentar. ### For developers ## Mapa de implementación | Aspecto | Ruta verificada | |---------|----------------| | Salud | `app/api/health/route.ts` | | Proveedores de autenticación | `auth.ts` (Google, Apple, credenciales de Ring Mailer, One Tap, billetera) | | Inicio de membresía | `app/_actions/membership-payment.ts` → `PaymentConductor.createCheckout` | | Conductor | `lib/payments/conductor/payment-conductor.ts` | | Webhooks | `app/api/payments/{wayforpay\|stripe\|paypal}/webhook/route.ts` | | Prueba del túnel | `app/api/tunnel/test/route.ts` (`status: 'ready'` si tiene éxito) | | Saldo de la billetera (opcional) | `GET /api/wallet/balance` → `{ balance }` o **401** / **404** | | Scripts | `npm run type-check`, `npm run build` (la build ejecuta type-check) | ```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** > La detección de Postgres de la ruta de salud usa `DATABASE_BACKEND=postgresql` o `DB_HOST` / `POSTGRES_HOST`, no solo la cadena `DB_BACKEND_MODE`. Mantén ambas familias alineadas con `env.local.template` para que `services.database` indique `postgresql` cuando lo esperas. ## Resumen de la lista | Comprobación | ¿Superada? | |-------|-------| | `npm run dev` arranca sin fallo del adaptador de base de datos | ☐ | | `GET /api/health` → `healthy` (o `AUTH_SECRET` corregido) | ☐ | | El inicio de sesión se completa con un proveedor de Auth.js | ☐ | | Crear/listar entidades **o** la lista de oportunidades funciona en la UI | ☐ | | `GET /api/tunnel/test` → `status: ready` | ☐ | | Opcional: el inicio de membresía devuelve redirección / éxito con crédito | ☐ | ## Preguntas frecuentes ### Impacto #### ¿Funcionará mi clon sin pagos? Sí. El primer éxito básico es autenticación + camino de datos. PaymentConductor es opcional hasta que hagas una demo de membresía de pago o del checkout de la tienda. #### ¿Un túnel en `ready` significa que SSE está en vivo? No. `/api/tunnel/test` confirma la configuración y la detección del proveedor. Los streams en vivo necesitan un cliente con sesión iniciada que llame a `/api/tunnel/sse` (o al proveedor que hayas configurado). ### Migración #### ¿Necesito `004_payment_transactions` para el nivel Básico? No. Aplícala antes de la prueba de Pago opcional para que el libro contable pueda registrar las intenciones de membresía / tienda. #### ¿Prototipo solo con Firebase? `firebase-full` puede superar la página de inicio + autenticación en un prototipo, pero la profundidad de PaymentConductor y las funciones de ERP/noticias esperan Postgres como base principal (`k8s-postgres-fcm` / `supabase-fcm`). Consulta [Selección de base de datos](/docs/customization/database-selection.md). ### Operación #### La salud devuelve 503 con `degraded`: ¿la app está caída? El proceso está en marcha. La falta de `AUTH_SECRET` (camino Postgres) o de variables críticas de Firebase degrada el estado. Define los secretos, reinicia y vuelve a lanzar el curl. #### ¿Saldo de la billetera 404? `GET /api/wallet/balance` devuelve **404** cuando aún no existe una fila de billetera. No es un fallo del nivel Básico. Crea o recarga la billetera mediante los flujos de billetera después de autenticarte. ## Documentación relacionada - [getting-started/installation](/docs/getting-started/installation.md) — Requisito previo: instalación y env antes de esta lista de prueba. - [getting-started/migrations](/docs/getting-started/migrations.md) — Requisito previo: esquema + 004_payment_transactions antes de la prueba de PaymentConductor. - [features/authentication](/docs/features/authentication.md) — En detalle: proveedores de Auth.js y forma de la sesión cuando el registro ya funciona. - [features/payment-conductor](/docs/features/payment-conductor.md) — Siguiente paso: rails, libro contable y webhooks cuando el inicio de membresía funcione. - [getting-started/troubleshooting](/docs/getting-started/troubleshooting.md) — Mismo flujo: correcciones de autenticación y base de datos cuando una fila de la lista sigue en rojo. - [getting-started/next-steps](/docs/getting-started/next-steps.md) — Siguiente paso: exploración de funciones cuando las comprobaciones básicas estén en verde.