Despliegue e infraestructura

1. Stack tecnológico

Componente	Tecnología
Framework	Next.js 15 (App Router)
Lenguaje	TypeScript 5+
UI	TailwindCSS 3+, Tailwind
Base de datos	PostgreSQL 16+
ORM	Prisma 5
Autenticación	JWT (12 h) + refresh token (7 días) en cookies httpOnly; bcrypt para contraseñas
Servidor	Node.js 20+ con PM2
Reverse proxy	Nginx con TLS 1.3
Despliegue	Dockploy (auto-deploy por rama)

2. Repositorio y ramas

Repositorio: https://github.com/ejd002/Loto.git
Rama de producción: Master-Plus — Docker/Dockploy escucha esta rama y despliega automáticamente al construir.
Las ramas main y master están deprecadas, no deben usarse.
El flujo de trabajo: trabajar en una rama de desarrollo, al estabilizar merge a Master-Plus para publicar.

3. Arquitectura desplegada

graph LR
    subgraph VPS
        NG[Nginx TLS 1.3] --> APP[Next.js (PM2/Docker)]
        APP --> PG[(PostgreSQL 16)]
        APP --> LO[Logs error]
    end
    GH[GitHub ejd002/Loto] -- "push a Master-Plus" --> Dockploy[Auto-deploy Dockploy]
    Dockploy --> APP

4. Variables de entorno (.env)

Variable	Descripción	Ejemplo
`DATABASE_URL`	Cadena de conexión a PostgreSQL (producción).	`postgresql://loto_app:CLAVE@localhost:5432/lotodb`
`JWT_SECRET`	Secreto para firmar los tokens. Cambiar a uno aleatorio largo en producción.	`cambiar-en-produccion`
`TZ`	Zona horaria del servidor (la operación usa UTC−5).	`America/Panama`

ENCRYPTION_KEY aparece en .env.example por compatibilidad, pero no se usa en el código actual (el cifrado de contraseñas es bcrypt).

5. Build y publicación

5.1 Vía Dockploy (producción, recomendada)

Dockploy escucha la rama Master-Plus y construye automáticamente el Dockerfile del repositorio:

pnpm install --frozen-lockfile
npx prisma generate
pnpm build
Al arrancar el contenedor se ejecuta npx prisma migrate deploy y luego pnpm start.

No es necesario ejecutar nada a mano: basta con fusionar los cambios a Master-Plus y Dockploy despliega.

5.2 Manual (alternativa sin Docker)

npm install
npx prisma migrate deploy     # aplica migraciones a producción
npx prisma db seed           # primer poblado (opcional, solo primera vez)
npm run build
pm2 start npm --name loto -- start

El seed crea el usuario administrador inicial y población base. Después de la primera vez no se repite.
Importante: no usar prisma migrate dev en producción (usa deploy).

6. Actualización de versión (release)

Trabajar los cambios en una rama de desarrollo.
Probar local contra datos de producción (script sync-from-prod).
Fusionar a Master-Plus en GitHub.
Dockploy detecta la rama y despliega; verificar el sitio y la versión visible en el pie del dashboard (formato AA.MM.DD.HH.MM UTC−5).

7. Monitoreo y registros

PM2: pm2 logs y pm2 status.
La tabla ErrorLog guarda los errores técnicos registrados por la aplicación (consulta con conexión a BD).
Certificado TLS: renovación automática manejada por el entorno (Dockploy/Nginx).

8. Excepciones y buenas prácticas

Nunca ejecutar dos prisma migrate deploy en paralelo.
Mantener la base de producción con solo lecturas externas (usuario loto_mcp de lectura únicamente, ver sincronización-bd).
No subir .env al repositorio (está en .gitignore junto a docs/ y scratch/).