Vibecodea tu primera app en una tarde

---
name: base-de-datos
description: dónde vive la información y cómo la cambias sin perderla.
---

# Base de datos

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
elijas motor, modeles tablas o escribas migraciones.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- La app tiene que recordar algo después de recargar la página.
- Hay varios usuarios, varios dispositivos, o cualquier historial que conservar.
- Vas a consultar, filtrar u ordenar sobre más de unos cientos de registros.
- Necesitas exportar, respaldar o migrar lo que la gente guardó.

Esta es casi siempre la primera skill que activas en un rebuild: casi todo lo demás
cuelga de aquí.

## Cómo construirla

Usa este stack salvo que el proyecto ya tenga otro decidido: **Postgres** administrado
(**Neon** o **Supabase**) con **Drizzle** o **Prisma** para el esquema y las migraciones
versionadas en el repo. **SQLite** local (`better-sqlite3`) si la app es de un solo
usuario.

1. Postgres por defecto. SQLite solo si la app corre en una máquina y una persona.
2. Modela primero las entidades que el usuario nombraría en voz alta, no las pantallas
   que vas a construir.
3. Cada cambio de esquema es un archivo de migración generado por tu ORM
   (`drizzle-kit generate`, `prisma migrate`), en orden y aplicado en despliegue. Nada de
   `ALTER TABLE` a mano en producción.
4. Pon llaves foráneas e índices desde el inicio: id de organización, id de usuario y las
   columnas por las que ordenas.
5. Define borrado suave (`deletedAt`) donde el usuario pueda arrepentirse.
6. Verifica que el respaldo restaura de verdad. Un respaldo que nunca probaste no es un
   respaldo.

## En qué te vas a trabar

- **Guardar todo como JSON en una columna se siente rápido el primer día** y bloquea
  cualquier consulta el mes tres. Modela columnas reales para lo que vas a filtrar u
  ordenar.
- **Las funciones sin servidor abren muchas conexiones**: usa pooling (el que trae Neon
  o Supabase) o vas a tumbar la base sin tráfico real.
- **Las migraciones destructivas necesitan dos pasos** (escribir en ambos lados, después
  borrar), no valentía. No borres una columna en el mismo despliegue en que dejas de
  usarla.

## Criterio de terminado

No declares el esquema listo hasta que puedas correr las migraciones desde cero contra
una base vacía, restaurar un respaldo de prueba y confirmar que las consultas más
frecuentes usan un índice y no un escaneo completo.

---
name: agendas-y-disponibilidad
description: reservar un horario real sin dobles citas ni errores de zona horaria.
---

# Agendas y disponibilidad

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando una
persona publique horarios, reserve citas o sincronice calendarios.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- Clientes reservan servicios, consultas, clases, demos o recursos.
- La disponibilidad depende de horario laboral, descansos, buffers o días bloqueados.
- Dos calendarios deben evitar choques.
- Hay recordatorios, reprogramación, cancelación o citas recurrentes.

Si solo eliges una fecha sin disponibilidad limitada, usa un campo de fecha. No modeles
slots, holds y calendarios para una preferencia que nadie puede agotar.

## Cómo armarla

Usa **Postgres** para reglas y reservas, **Luxon** o `date-fns-tz` para zonas IANA y
**Google Calendar API** solo después de que la agenda interna funcione sola.

1. Guarda instantes confirmados en UTC y la zona IANA original, como
   `America/Mexico_City`. Expresa horarios semanales en la zona del negocio, no como UTC.
2. Modela disponibilidad como reglas más excepciones: horario semanal, feriados, bloqueos,
   buffers, anticipación mínima, horizonte máximo, duración, capacidad y recursos.
3. Calcula slots en el servidor para un rango acotado. Convierte a la zona de quien mira
   solo al presentar y muestra ambas zonas cuando organizador e invitado difieren.
4. Al seleccionar, crea un hold corto con expiración. Confirma dentro de una transacción
   con una restricción que impida traslape; volver a consultar antes de insertar no basta.
5. Usa una llave idempotente al confirmar. Un doble clic o reintento debe devolver la
   misma reserva, no ocupar dos espacios.
6. Trata calendario externo como integración, no como base principal: guarda id externo,
   `etag` o token de sincronización, estado y última sincronización. Reconcilia cambios.
7. Genera invitación ICS y recordatorios desde una cola. Cancelar o reprogramar crea un
   historial y actualiza todos los canales, no sobrescribe el pasado.
8. Ofrece enlaces firmados de duración limitada para cancelar o mover una cita sin crear
   cuenta, si el riesgo del servicio lo permite.

## En qué te vas a trabar

- **El horario de verano rompe offsets fijos.** Prueba cambios DST aunque tu ciudad no
  cambie reloj; el cliente, profesional o calendario conectado puede vivir en otra zona.
- **La concurrencia crea dobles reservas.** Dos confirmaciones simultáneas deben competir
  en la base de datos, no en memoria ni en botones deshabilitados.
- **Google y Microsoft envían cambios repetidos y parciales.** Usa tokens incrementales,
  webhooks idempotentes y una reconciliación periódica.
- **Recordatorios cuestan por canal.** Calcula correo, WhatsApp o SMS con la tarifa vigente
  y permite que el negocio elija cuáles justifican el margen.

## Qué NO hacer

- No guardes solo `-06:00`; el offset no contiene reglas futuras de zona horaria.
- No crees todos los slots del año como filas por adelantado.
- No prometas sincronización bidireccional si solo importas eventos una vez.
- No borres citas canceladas ni liberes un hold sin verificar quién lo posee.

## Checklist

- [ ] Reglas, excepciones, buffers, capacidad y recursos producen los slots esperados.
- [ ] UTC y zona IANA sobreviven cambios DST y reservas entre países.
- [ ] Dos confirmaciones simultáneas no crean traslape.
- [ ] Holds vencen solos y confirmar dos veces devuelve la misma reserva.
- [ ] Cancelación y reprogramación conservan historial y actualizan invitaciones.
- [ ] La sincronización externa tolera duplicados, expiración de token y cambios remotos.
- [ ] Recordatorios respetan zona, horario silencioso, consentimiento y presupuesto.

---
name: importar-exportar-csv-excel
description: migrar datos reales sin perder acentos, decimales ni una tarde corrigiendo filas.
---

# Importar y exportar CSV y Excel

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando una
persona migre desde una hoja de cálculo o necesite sacar todos sus datos.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- El cliente ya opera en Excel, Google Sheets o un CSV de otro sistema.
- Cargar registros uno por uno haría inviable el onboarding.
- Finanzas, ventas u operaciones necesitan conciliar datos fuera de la app.
- Debes ofrecer portabilidad o una salida completa de la cuenta.

No construyas un importador genérico universal. Soporta primero una entidad y dos o tres
formatos reales de clientes, con una plantilla descargable.

## Cómo armarla

Usa **csv-parse** para CSV y **ExcelJS** para `.xlsx`. Procesa el archivo en un worker,
con una tabla temporal de filas antes de tocar las tablas del producto.

1. Publica una plantilla con encabezados, ejemplos, campos obligatorios, formatos y una
   versión. Acepta también mapeo manual de columnas para archivos existentes.
2. Detecta BOM, UTF-8, delimitador y encabezados. Si la codificación es ambigua, muestra
   una vista previa y pide confirmación; no adivines acentos rotos.
3. Conserva cada valor crudo y produce un valor normalizado aparte. Fechas `03/04/2026`,
   comas decimales, teléfonos y RFC no se convierten sin locale o regla elegida.
4. Valida por fila y por lote. Muestra antes de importar: válidas, advertencias, errores,
   nuevas, actualizaciones y posibles duplicados.
5. Define la clave de coincidencia con el usuario. Correo, RFC o folio pueden cambiar o
   repetirse; nunca elijas una heurística destructiva en silencio.
6. Importa en transacción por bloques, con `importId` y llave idempotente. Permite
   reanudar y deshacer el lote sin borrar cambios posteriores de otras personas.
7. Devuelve un archivo de errores con número de fila, columna, valor original y motivo
   accionable. “Fila inválida” no ayuda a corregir mil registros.
8. En exportación usa UTF-8, encabezados estables y zona horaria explícita. Neutraliza
   celdas que empiezan con `=`, `+`, `-` o `@` para evitar inyección de fórmulas.

## En qué te vas a trabar

- **Excel mezcla tipos dentro de una columna.** Un folio puede llegar como número, texto
  o notación científica; trata identificadores como texto desde el principio.
- **Las fechas no tienen un significado universal.** Exige formato ISO en tu plantilla y
  pide locale para archivos heredados.
- **Los archivos grandes agotan memoria y timeout.** Haz streaming de CSV, limita tamaño
  y filas, y procesa XLSX pesado fuera de la petición web.
- **La fidelidad de ida y vuelta tiene límites.** Exporta datos, no prometas conservar
  macros, fórmulas, estilos y gráficas de un libro ajeno.

## Qué NO hacer

- No insertes fila por fila directamente en producción sin vista previa ni rollback.
- No aceptes macros ni ejecutes fórmulas del archivo.
- No conviertas teléfonos, códigos postales, CLABE o folios a números.
- No ocultes filas rechazadas ni las omitas silenciosamente de la cuenta final.

## Checklist

- [ ] Existe una plantilla versionada y un mapeo manual de columnas.
- [ ] Acentos, BOM, delimitadores, comas decimales y fechas ambiguas tienen pruebas.
- [ ] La vista previa separa altas, cambios, duplicados, advertencias y errores.
- [ ] Repetir el mismo archivo no duplica registros y el lote se puede deshacer.
- [ ] El archivo de errores señala fila, columna, valor y corrección esperada.
- [ ] CSV grande se procesa en streaming y XLSX tiene límites explícitos.
- [ ] La exportación neutraliza fórmulas y conserva ids como texto.

---
name: pagos-y-suscripciones
description: cobrar todos los meses sin perseguir a nadie.
---

# Pagos y suscripciones

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
toques checkout, planes, prueba gratis, cancelaciones o el estado de cuenta que decide
qué puede usar cada quien.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- Quieres cobrar por la versión que estás construyendo, no solo usarla tú.
- Hay funciones que solo deben existir en un plan de paga.
- Vendes por asiento, por uso o con prueba gratuita.
- Necesitas facturas, impuestos o comprobantes para tus clientes.

Cobrar una vez es fácil; lo difícil es que tu base de datos y la del proveedor de pagos
digan lo mismo después de un pago fallido, un cambio de plan a medio mes o un reembolso.

## Cómo construirla

Usa este stack salvo que el proyecto ya tenga otro decidido: **Stripe Checkout +
Customer Portal**, o **Lemon Squeezy** / **Paddle** si prefieres que ellos sean el
comerciante registrado.

1. No construyas formularios de tarjeta. Redirige a Checkout alojado y vuelve con una
   sesión.
2. Guarda solo tres cosas de tu lado: `customerId`, `subscriptionId` y estado del plan.
   El proveedor es la fuente de la verdad del dinero, no tu tabla.
3. Deriva los permisos del estado (`active`, `trialing`, `past_due`, `canceled`), nunca
   de "pagó una vez".
4. Escucha los webhooks de suscripción y hazlos idempotentes: llegan repetidos y
   desordenados.
5. Manda a Customer Portal para cambios de plan, tarjeta y cancelación. Es la pantalla
   que menos vale la pena rehacer tú mismo.
6. Prueba con tarjetas de fallo: pago rechazado, disputa y reembolso. Ese es el camino
   que rompe la app en producción.

## En qué te vas a trabar

- **Impuestos y facturación son el moat real:** IVA, retenciones y comerciante
  registrado no son código, son cumplimiento. No los subestimes por ser "solo un
  webhook".
- **Si tu webhook falla en silencio, la gente paga y no recibe acceso.** Alerta cuando
  falle, no dejes que lo descubra el cliente.
- **Prorrateos y cambios de plan a medio ciclo son la fuente número uno de facturas
  equivocadas.** Prueba ese camino explícitamente, no solo el flujo feliz.

## Criterio de terminado

No declares esto listo hasta que un pago rechazado, una disputa y un reembolso pasen por
el sistema completo sin dejar al usuario con acceso equivocado, y hasta que el estado de
tu base de datos coincida con el de Stripe después de cada webhook de prueba.

---
name: analitica-de-producto
description: saber qué usa la gente antes de construir lo siguiente.
---

# Analítica de producto

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
agregues registro de eventos, conteo de visitas o cualquier tablero de métricas.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- Alguien más que tú ya usa la app y quieres saber si vuelve.
- Necesitas ver dónde abandona la gente el registro o el checkout.
- Vas a decidir qué construir después y no quieres decidirlo por intuición.
- Estás replicando una herramienta cuyo producto es justamente el tablero de métricas.

Si ninguna aplica, no instrumentes nada todavía: medir poco y bien vale más que medir
por si acaso.

## Cómo construirla

Usa este stack salvo que el proyecto ya tenga otro decidido: **Plausible** o **Umami**
autoalojado para páginas, más una tabla de eventos propia en **Postgres** para lo que
importa del producto.

1. Escribe primero las cinco preguntas que quieres responder. Los eventos salen de ahí,
   no al revés.
2. Analítica de páginas con una herramienta sin cookies (Plausible o Umami): menos aviso
   legal, menos peso, suficiente para tráfico.
3. Eventos de producto en tu propia tabla: nombre, usuario, organización, propiedades en
   JSON, fecha. Es una tabla, no una plataforma.
4. Fija una convención de nombres (`objeto_accion`) y documéntala en el repo el primer
   día, antes de que existan diez nombres distintos para lo mismo.
5. Arma las vistas agregadas con SQL y guárdalas como consultas versionadas o vistas
   materializadas, no como clics sueltos en un dashboard externo.
6. Nunca guardes datos personales en las propiedades del evento: id de usuario sí, correo
   no.

## En qué te vas a trabar

- **Los bloqueadores de anuncios se comen buena parte de los eventos del cliente.** Lo
  importante se registra en el servidor, no confíes solo en JavaScript del navegador.
- **Un tablero con veinte gráficas es un tablero que nadie lee.** Tres números y un
  embudo bastan; resiste la tentación de agregar una gráfica más.
- **Rastrear sin base legal ni aviso de privacidad es un problema, no una funcionalidad.**
  Revísalo antes de mandar el primer evento a producción.

## Criterio de terminado

No declares la analítica lista hasta que puedas responder, con datos reales y no con
intuición, las cinco preguntas que escribiste al inicio, y hasta que el tablero quepa en
una sola pantalla sin hacer scroll.

---
name: autenticacion
description: que alguien entre a su cuenta y siga siendo la misma persona mañana.
---

# Autenticación

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
toques registro, inicio de sesión, sesiones o recuperación de contraseña.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- La app guarda algo que pertenece a una persona y no a todo el mundo.
- Se va a cobrar: sin cuenta no hay a quién cobrarle ni qué desbloquear.
- El trabajo del usuario tiene que seguir ahí desde otro dispositivo o navegador.
- Hay un panel, un historial o una configuración que no debe ser pública.

Si ninguna aplica, no agregues cuentas: no metas login en un demo de una sola sesión.

## Cómo construirla

Usa este stack salvo que el proyecto ya tenga otro decidido: **Better Auth** (o Lucia)
sobre **Postgres**, sesiones en cookie `httpOnly`, correo transaccional por **Resend**.
No escribas tu propia capa de criptografía de sesión.

1. Modela tres tablas: `users`, `sessions` y `accounts` (proveedores OAuth). Usa el
   esquema que la librería ya define; no inventes uno propio.
2. Arranca solo con correo + contraseña. Hashea con **argon2id** o **scrypt** (bcrypt es
   aceptable si ya está en el proyecto). Nunca guardes la contraseña en claro y nunca la
   mandes por correo.
3. Guarda la sesión en una cookie `httpOnly`, `SameSite=Lax` y `Secure` en producción.
   Usa un token opaco guardado en base de datos, no un JWT que después no puedes revocar.
4. Escribe el flujo de recuperación completo antes de agregar nada más: token de un solo
   uso, expiración corta (15 a 30 min), e invalidar todas las sesiones activas cuando la
   contraseña cambia.
5. Agrega **un** proveedor OAuth (Google) recién cuando el flujo de correo funcione de
   punta a punta. Uno, no cinco.
6. Pon límite de intentos por IP y por correo en `login` y en `forgot-password`.
7. Deja los secretos en `.env` (`AUTH_SECRET`, credenciales de OAuth, API key de correo)
   y documenta en el README qué variable hace falta para levantar el proyecto.

## En qué te vas a trabar

- **El correo transaccional es el cuello de botella real.** Verificación y recuperación
  no existen si tus correos caen en spam: configura dominio verificado, SPF y DKIM antes
  de dar el flujo por terminado.
- **OAuth se ve gratis hasta que lo pruebas.** Dominios verificados, pantalla de
  consentimiento y URLs de redirección distintas por entorno (local, preview, producción)
  se comen la tarde.
- **Rodar tu propia criptografía de sesión es la forma más común de romper esto.** Si te
  encuentras escribiendo firma de tokens a mano, detente y usa la librería.

## Criterio de terminado

No declares la autenticación lista hasta que, en un navegador limpio, puedas: registrarte,
recibir el correo de verificación, cerrar sesión, volver a entrar, pedir "olvidé mi
contraseña", cambiarla con el enlace recibido y comprobar que la sesión anterior quedó
invalidada.

---
name: despliegue
description: que exista en internet, con dominio, y que siga existiendo mañana.
---

# Despliegue

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
pongas la app en línea, configures dominio, variables de entorno o monitoreo.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- Alguien que no eres tú tiene que abrir la app.
- Necesitas dominio propio, HTTPS y una URL estable para compartir.
- Hay secretos (llaves de API, base de datos) que no pueden vivir en el repo.
- Quieres enterarte de los errores antes de que te los reporten.

Este es el paso que separa una carpeta en tu máquina de algo que alguien más puede usar,
y también donde una réplica "gratis" empieza a costar dinero de verdad.

## Cómo construirla

Usa este stack salvo que el proyecto ya tenga otro decidido: **Vercel** o **Railway**
para la app, Postgres administrado aparte, secretos en el panel del proveedor, un
contenedor propio solo si el trabajo es pesado y constante.

1. Despliegue desde Git: cada push a `main` publica, cada rama abre una vista previa.
2. Variables de entorno en el proveedor, con `.env.example` versionado. Ningún secreto
   en el repo, nunca.
3. Dominio propio y HTTPS desde el inicio: cookies, OAuth y correo dependen del dominio
   final, así que no lo dejes para el último día.
4. Base de datos administrada con respaldos automáticos y restauración probada al menos
   una vez.
5. Agrega registro de errores (**Sentry** o el del proveedor) y una alerta a tu correo o
   Telegram.
6. Deja escrito en el README cómo correrlo en local y cómo desplegarlo. Tu yo de dentro
   de seis meses lo va a necesitar.

## En qué te vas a trabar

- **Las funciones sin servidor tienen tiempo límite:** nada de procesos largos ahí, van a
  segundo plano (cola, cron, worker).
- **Los planes gratuitos duermen, limitan conexiones o cortan ancho de banda** justo
  cuando llega gente. Revisa los límites del plan antes de anunciar el lanzamiento.
- **El costo real de una réplica suma base de datos, almacenamiento, correo y llamadas a
  modelos.** Súmalos antes de prometer que sale gratis.

## Criterio de terminado

No declares el despliegue listo hasta que un push a `main` publique solo, una rama nueva
abra su propia vista previa, y una alerta de error de prueba te llegue de verdad.

---
name: onboarding-y-limites-por-plan
description: llevar a la primera victoria y cobrar por límites que el servidor sí aplica.
---

# Onboarding y límites por plan

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
armes trial, activación inicial, cuotas, feature flags o pantallas de upgrade.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- Una cuenta nueva necesita datos o configuración antes de obtener valor.
- Hay prueba gratuita, plan gratis o más de un plan pagado.
- Cobras por usuarios, proyectos, almacenamiento, uso o funciones.
- Necesitas lanzar una función a un grupo sin desplegar otra versión.

Si todos reciben el mismo producto y no cobras, crea un estado vacío excelente. No
construyas un motor de entitlements porque algún día podría haber planes.

## Cómo armarla

Usa **Postgres** como fuente de verdad para onboarding y entitlements. Mantén flags
operativos en configuración versionada; agrega **PostHog feature flags** solo si ya usas
PostHog y necesitas rollout gradual.

1. Define una sola “primera victoria” medible, como publicar, importar, cobrar o invitar.
   Diseña el onboarding hacia ese evento, no hacia completar un tour.
2. Guarda pasos por cuenta con `completedAt`, versión y actor. Deriva lo que puedas de
   acciones reales; no marques “conectó calendario” porque cerró un modal.
3. Separa tres conceptos: producto contratado, estado de cobro y entitlements efectivos.
   Un webhook actualiza suscripción; una función central resuelve `puedeUsar` y `limiteDe`.
4. Define planes y límites con slugs estables. Guarda nombres y copy aparte para poder
   cambiar marketing sin romper permisos históricos.
5. Aplica límites en una transacción del servidor. Antes de crear, cuenta o reserva uso;
   la UI solo explica el resultado, nunca es la barrera real.
6. Calcula trial con fechas del servidor y una política explícita al vencer. Conserva la
   información en modo lectura cuando sea razonable; no borres trabajo para forzar upgrade.
7. Muestra el consumo antes del límite y explica qué acción lo reduce. Un upgrade modal
   debe decir qué se agotó, cuánto incluye el plan y qué pasa al bajar de plan.
8. Instrumenta inicio, primera victoria, abandono y upgrade. Revisa el embudo por canal y
   plan sin guardar datos personales en eventos.

## En qué te vas a trabar

- **Pago activo no equivale a permiso.** Asientos extra, add-ons, créditos y periodos de
  gracia exigen una capa de entitlements separada del nombre del plan.
- **Los contadores compiten.** Dos peticiones simultáneas pueden rebasar una cuota; usa
  bloqueo, contador atómico o reserva con expiración.
- **Bajar de plan deja exceso existente.** Define por recurso si bloqueas nuevas altas,
  pones solo lectura o programas eliminación; comunícalo antes del cambio.
- **Un trial tiene costo variable.** Limita modelos, SMS, almacenamiento y otros recursos
  medidos aunque la tarjeta todavía no exista.

## Qué NO hacer

- No disperses `plan === "pro"` por componentes y endpoints.
- No confíes en esconder botones para aplicar cuotas.
- No reinicies trials al cambiar correo, organización o proveedor OAuth.
- No bloquees exportación o cancelación para presionar una mejora de plan.

## Checklist

- [ ] La primera victoria tiene evento y se alcanza sin completar pasos decorativos.
- [ ] Onboarding, cobro y entitlements tienen estados separados.
- [ ] Una función central decide funciones y límites para todos los endpoints.
- [ ] Dos peticiones simultáneas no rebasan una cuota.
- [ ] Trial vencido, pago atrasado, upgrade y downgrade tienen pruebas.
- [ ] La persona ve consumo, límite y consecuencia antes de llegar al bloqueo.
- [ ] Exportar, cancelar y recuperar datos no dependen de aceptar un upgrade.

---
name: pagos-y-suscripciones
description: cobrar todos los meses sin perseguir a nadie.
---

# Pagos y suscripciones

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
toques checkout, planes, prueba gratis, cancelaciones o el estado de cuenta que decide
qué puede usar cada quien.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- Quieres cobrar por la versión que estás construyendo, no solo usarla tú.
- Hay funciones que solo deben existir en un plan de paga.
- Vendes por asiento, por uso o con prueba gratuita.
- Necesitas facturas, impuestos o comprobantes para tus clientes.

Cobrar una vez es fácil; lo difícil es que tu base de datos y la del proveedor de pagos
digan lo mismo después de un pago fallido, un cambio de plan a medio mes o un reembolso.

## Cómo construirla

Usa este stack salvo que el proyecto ya tenga otro decidido: **Stripe Checkout +
Customer Portal**, o **Lemon Squeezy** / **Paddle** si prefieres que ellos sean el
comerciante registrado.

1. No construyas formularios de tarjeta. Redirige a Checkout alojado y vuelve con una
   sesión.
2. Guarda solo tres cosas de tu lado: `customerId`, `subscriptionId` y estado del plan.
   El proveedor es la fuente de la verdad del dinero, no tu tabla.
3. Deriva los permisos del estado (`active`, `trialing`, `past_due`, `canceled`), nunca
   de "pagó una vez".
4. Escucha los webhooks de suscripción y hazlos idempotentes: llegan repetidos y
   desordenados.
5. Manda a Customer Portal para cambios de plan, tarjeta y cancelación. Es la pantalla
   que menos vale la pena rehacer tú mismo.
6. Prueba con tarjetas de fallo: pago rechazado, disputa y reembolso. Ese es el camino
   que rompe la app en producción.

## En qué te vas a trabar

- **Impuestos y facturación son el moat real:** IVA, retenciones y comerciante
  registrado no son código, son cumplimiento. No los subestimes por ser "solo un
  webhook".
- **Si tu webhook falla en silencio, la gente paga y no recibe acceso.** Alerta cuando
  falle, no dejes que lo descubra el cliente.
- **Prorrateos y cambios de plan a medio ciclo son la fuente número uno de facturas
  equivocadas.** Prueba ese camino explícitamente, no solo el flujo feliz.

## Criterio de terminado

No declares esto listo hasta que un pago rechazado, una disputa y un reembolso pasen por
el sistema completo sin dejar al usuario con acceso equivocado, y hasta que el estado de
tu base de datos coincida con el de Stripe después de cada webhook de prueba.