# Variables de Entorno para Deployment en Producción

## Math2 Platform - Production Environment Variables

Este documento lista **TODAS** las variables de entorno necesarias para ejecutar Math2 Platform en modo producción local.

---

## 🔴 CRÍTICAS - Obligatorias

Estas variables **DEBEN** estar configuradas antes de iniciar el deployment.

### Base de Datos

| Variable | Descripción | Ejemplo | Requerida |
|----------|-------------|---------|-----------|
| `DATABASE_URL` | URL de conexión a PostgreSQL | `postgresql://mathuser:securepass@localhost:5432/mathdb` | ✅ Si |
| `DB_USER` | Usuario de PostgreSQL | `mathuser` | ✅ No (default: mathuser) |
| `DB_PASSWORD` | Contraseña de PostgreSQL | `SecureP@ssw0rd123!` | ✅ Si |
| `DB_NAME` | Nombre de la base de datos | `mathdb` | ✅ No (default: mathdb) |

> **Nota**: Si `DATABASE_URL` está definida, `DB_USER`, `DB_PASSWORD` y `DB_NAME` son opcionales para Docker Compose.

### Seguridad

| Variable | Descripción | Ejemplo | Requerida |
|----------|-------------|---------|-----------|
| `JWT_SECRET` | Clave secreta para tokens JWT (mín. 32 chars) | `your-super-secret-jwt-key-min-32-chars!` | ✅ Si |
| `REDIS_PASSWORD` | Contraseña para Redis | `redis_secure_pass_2024` | ✅ Si |
| `SESSION_SECRET` | Clave para sesiones | `session-secret-min-32-chars-long` | ✅ No (default: generado) |

---

## 🟡 IMPORTANTES - Recomendadas

Estas variables deberían configurarse para un funcionamiento óptimo.

### Inteligencia Artificial (AI/LLM)

| Variable | Descripción | Ejemplo | Default |
|----------|-------------|---------|---------|
| `AI_API_BASE_URL` | URL base de la API de AI | `https://coding-intl.dashscope.aliyuncs.com/v1` | - |
| `AI_API_KEY` | API Key para servicio de AI | `sk-xxxxxxxxxxxxxxxx` | - |
| `AI_MODEL` | Modelo de AI a utilizar | `MiniMax-M2.5` | `MiniMax-M2.5` |
| `AI_MAX_TOKENS` | Máximo de tokens por request | `2000` | `2000` |
| `AI_TEMPERATURE` | Temperatura para generación | `0.7` | `0.7` |

> **Nota**: Sin estas variables, el sistema funcionará pero sin capacidad de generar ejercicios con AI.

### Telegram (Notificaciones)

| Variable | Descripción | Ejemplo | Default |
|----------|-------------|---------|---------|
| `TELEGRAM_BOT_TOKEN` | Token del bot de Telegram | `123456789:ABCdefGHIjklMNOpqrSTU` | - |
| `TELEGRAM_ADMIN_CHAT_ID` | Chat ID del administrador | `123456789` | - |
| `TELEGRAM_NOTIFICATIONS_ENABLED` | Habilitar notificaciones | `true` | `true` |

> **Nota**: Sin estas variables, las notificaciones por Telegram no funcionarán.

### CORS y URLs

| Variable | Descripción | Ejemplo Producción | Default |
|----------|-------------|-------------------|---------|
| `CORS_ORIGIN` | Origen permitido para CORS | `https://tudominio.com` | `http://localhost:3000` |
| `FRONTEND_URL` | URL del frontend | `https://tudominio.com` | `http://localhost:3000` |
| `BACKEND_URL` | URL del backend | `https://api.tudominio.com` | `http://localhost:3001` |
| `NEXT_PUBLIC_API_URL` | URL pública de API para frontend | `/api` | `/api` |

---

## 🟢 OPCIONALES - Configuración Avanzada

### Rate Limiting

| Variable | Descripción | Default |
|----------|-------------|---------|
| `RATE_LIMIT_WINDOW_MS` | Ventana de tiempo para rate limiting | `900000` (15 min) |
| `RATE_LIMIT_MAX_REQUESTS` | Máximo de requests por ventana | `100` |
| `STRICT_RATE_LIMIT_MAX` | Límite estricto para endpoints sensibles | `5` |
| `AUTH_RATE_LIMIT_WINDOW_MS` | Ventana para auth endpoints | `900000` |
| `AUTH_RATE_LIMIT_MAX` | Máximo para auth endpoints | `20` |

### Configuración de JWT

| Variable | Descripción | Default |
|----------|-------------|---------|
| `JWT_EXPIRES_IN` | Tiempo de expiración del JWT | `15m` |
| `JWT_REFRESH_EXPIRES_IN` | Tiempo de expiración del refresh token | `30d` |

### Redis

| Variable | Descripción | Default |
|----------|-------------|---------|
| `REDIS_HOST` | Host de Redis | `localhost` (dev) / `redis` (docker) |
| `REDIS_PORT` | Puerto de Redis | `6379` |
| `REDIS_DB` | Base de datos Redis | `0` |

### Archivos y Uploads

| Variable | Descripción | Default |
|----------|-------------|---------|
| `MAX_FILE_SIZE_MB` | Tamaño máximo de archivo (MB) | `10` |
| `UPLOAD_DIR` | Directorio de uploads | `./uploads` |
| `PDF_PROCESSING_DIR` | Directorio para PDFs | `./uploads/pdfs` |

### Procesamiento de PDFs

| Variable | Descripción | Default |
|----------|-------------|---------|
| `PDF_CONCURRENCY` | Concurrencia de procesamiento | `3` |
| `PDF_TIMEOUT_MS` | Timeout para procesamiento | `300000` (5 min) |
| `PDF_QUALITY` | Calidad de procesamiento | `medium` |

### Workers

| Variable | Descripción | Default |
|----------|-------------|---------|
| `WORKER_CONCURRENCY` | Concurrencia de workers | `3` |
| `WORKER_MAX_JOBS_PER_WORKER` | Máximo de jobs por worker | `10` |
| `WORKER_STUCK_TOKENS_THRESHOLD` | Umbral para detectar stuck | `10000` |
| `WORKER_STUCK_INTERVAL` | Intervalo de revisión stuck | `5000` |

### Logging

| Variable | Descripción | Default |
|----------|-------------|---------|
| `LOG_LEVEL` | Nivel de logging | `info` (prod) / `debug` (dev) |
| `LOG_DIR` | Directorio de logs | `./logs` |
| `ENABLE_QUERY_LOGGING` | Log de queries SQL | `false` (prod) |

### Cache

| Variable | Descripción | Default |
|----------|-------------|---------|
| `CACHE_TTL_SECONDS` | TTL del caché (segundos) | `3600` (1 hora) |
| `ENABLE_CACHE` | Habilitar caché | `true` |

### Sesiones

| Variable | Descripción | Default |
|----------|-------------|---------|
| `SESSION_MAX_AGE_MS` | Duración de sesión (ms) | `86400000` (24 horas) |

### Notificaciones

| Variable | Descripción | Default |
|----------|-------------|---------|
| `NOTIFICATION_RETRY_ATTEMPTS` | Intentos de reintento | `3` |
| `NOTIFICATION_RETRY_DELAY_MS` | Delay entre reintentos | `1000` |
| `DAILY_SUMMARY_ENABLED` | Resumen diario habilitado | `true` |
| `DAILY_SUMMARY_TIME` | Hora del resumen | `00:00` |

### Ranking y Logros

| Variable | Descripción | Default |
|----------|-------------|---------|
| `RANKING_UPDATE_INTERVAL_MS` | Intervalo de actualización ranking | `60000` (1 min) |
| `RANKING_CACHE_TTL_SECONDS` | TTL del caché de ranking | `300` (5 min) |
| `LEADERBOARD_SIZE` | Tamaño del leaderboard | `100` |
| `ACHIEVEMENT_CHECK_INTERVAL_MS` | Intervalo de check de logros | `30000` (30 seg) |
| `BADGE_AUTO_AWARD` | Auto-asignar badges | `true` |

### Monitoreo

| Variable | Descripción | Default |
|----------|-------------|---------|
| `HEALTH_CHECK_INTERVAL_MS` | Intervalo de health checks | `30000` (30 seg) |
| `ENABLE_METRICS` | Habilitar métricas Prometheus | `true` |
| `METRICS_PORT` | Puerto para métricas | `9090` |

### Feature Flags

| Variable | Descripción | Default |
|----------|-------------|---------|
| `ENABLE_REGISTRATION` | Habilitar registro de usuarios | `true` |
| `ENABLE_AI_GENERATION` | Habilitar generación con AI | `true` |
| `ENABLE_PDF_PROCESSING` | Habilitar procesamiento de PDFs | `true` |
| `ENABLE_TELEGRAM_NOTIFICATIONS` | Habilitar notificaciones Telegram | `true` |
| `ENABLE_RANKING_SYSTEM` | Habilitar sistema de ranking | `true` |
| `ENABLE_ACHIEVEMENTS` | Habilitar sistema de logros | `true` |
| `MAINTENANCE_MODE` | Modo mantenimiento | `false` |

### Configuración de Docker

| Variable | Descripción | Default |
|----------|-------------|---------|
| `VERSION` | Versión de las imágenes Docker | `1.0.0` |
| `COMPOSE_PROJECT_NAME` | Nombre del proyecto Docker | `math2` |

---

## 📋 Plantilla .env para Producción

```bash
# ============================================
# MATH2 PLATFORM - PRODUCTION ENVIRONMENT
# ============================================
# Copiar a .env y configurar valores reales
# NUNCA commitear este archivo con valores reales
# ============================================

# ============================================
# CRÍTICAS - Obligatorias
# ============================================
DB_PASSWORD=CHANGE_THIS_TO_STRONG_PASSWORD
REDIS_PASSWORD=CHANGE_THIS_TO_STRONG_PASSWORD
JWT_SECRET=CHANGE_THIS_TO_MIN_32_CHARS_SECRET_KEY

# ============================================
# BASE DE DATOS
# ============================================
DATABASE_URL=postgresql://mathuser:${DB_PASSWORD}@postgres:5432/mathdb
DB_USER=mathuser
DB_NAME=mathdb

# ============================================
# REDIS
# ============================================
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_DB=0

# ============================================
# AI / LLM (MiniMax-M2.5 - DashScope)
# ============================================
AI_API_BASE_URL=https://coding-intl.dashscope.aliyuncs.com/v1
AI_API_KEY=your-dashscope-api-key-here
AI_MODEL=MiniMax-M2.5
AI_MAX_TOKENS=2000
AI_TEMPERATURE=0.7

# ============================================
# TELEGRAM
# ============================================
TELEGRAM_BOT_TOKEN=your-telegram-bot-token-here
TELEGRAM_ADMIN_CHAT_ID=your-admin-chat-id-here
TELEGRAM_NOTIFICATIONS_ENABLED=true

# ============================================
# SEGURIDAD
# ============================================
JWT_EXPIRES_IN=15m
JWT_REFRESH_EXPIRES_IN=30d
SESSION_SECRET=CHANGE_THIS_SESSION_SECRET_MIN_32_CHARS

# ============================================
# CORS Y URLs
# ============================================
NODE_ENV=production
PORT=3001
BACKEND_URL=http://localhost:3001
FRONTEND_URL=http://localhost
CORS_ORIGIN=http://localhost
NEXT_PUBLIC_API_URL=/api
NEXT_PUBLIC_APP_NAME=Plataforma de Álgebra Lineal

# ============================================
# RATE LIMITING
# ============================================
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100
STRICT_RATE_LIMIT_MAX=5
AUTH_RATE_LIMIT_WINDOW_MS=900000
AUTH_RATE_LIMIT_MAX=20

# ============================================
# UPLOADS
# ============================================
MAX_FILE_SIZE_MB=10
UPLOAD_DIR=./uploads
PDF_PROCESSING_DIR=./uploads/pdfs

# ============================================
# PDF
# ============================================
PDF_CONCURRENCY=3
PDF_TIMEOUT_MS=300000
PDF_QUALITY=medium

# ============================================
# WORKERS
# ============================================
WORKER_CONCURRENCY=3
WORKER_MAX_JOBS_PER_WORKER=10
WORKER_STUCK_TOKENS_THRESHOLD=10000
WORKER_STUCK_INTERVAL=5000

# ============================================
# LOGGING
# ============================================
LOG_LEVEL=info
LOG_DIR=./logs
ENABLE_QUERY_LOGGING=false

# ============================================
# CACHE
# ============================================
CACHE_TTL_SECONDS=3600
ENABLE_CACHE=true

# ============================================
# SESSION
# ============================================
SESSION_MAX_AGE_MS=86400000

# ============================================
# NOTIFICACIONES
# ============================================
NOTIFICATION_RETRY_ATTEMPTS=3
NOTIFICATION_RETRY_DELAY_MS=1000
DAILY_SUMMARY_ENABLED=true
DAILY_SUMMARY_TIME=00:00

# ============================================
# RANKING
# ============================================
RANKING_UPDATE_INTERVAL_MS=60000
RANKING_CACHE_TTL_SECONDS=300
LEADERBOARD_SIZE=100

# ============================================
# LOGROS
# ============================================
ACHIEVEMENT_CHECK_INTERVAL_MS=30000
BADGE_AUTO_AWARD=true

# ============================================
# MONITOREO
# ============================================
HEALTH_CHECK_INTERVAL_MS=30000
ENABLE_METRICS=true
METRICS_PORT=9090

# ============================================
# FEATURE FLAGS
# ============================================
ENABLE_REGISTRATION=true
ENABLE_AI_GENERATION=true
ENABLE_PDF_PROCESSING=true
ENABLE_TELEGRAM_NOTIFICATIONS=true
ENABLE_RANKING_SYSTEM=true
ENABLE_ACHIEVEMENTS=true
MAINTENANCE_MODE=false

# ============================================
# DOCKER
# ============================================
VERSION=1.0.0
COMPOSE_PROJECT_NAME=math2
```

---

## 🔒 Seguridad

### Checklist de Seguridad para Producción

- [ ] `JWT_SECRET` tiene al menos 32 caracteres aleatorios
- [ ] `REDIS_PASSWORD` es fuerte y única
- [ ] `DB_PASSWORD` es fuerte y única
- [ ] No hay credenciales hardcodeadas en el código
- [ ] El archivo `.env` está en `.gitignore`
- [ ] Variables sensibles no aparecen en logs
- [ ] SSL/TLS está configurado para tráfico HTTPS

### Generar Secretos Fuertes

```bash
# JWT_SECRET (32+ chars)
openssl rand -base64 48

# Redis Password
openssl rand -base64 24

# DB Password
openssl rand -base64 24

# Session Secret
openssl rand -base64 48
```

---

## 🚀 Deployment

### Pasos para Deployment Local en Producción

1. **Copiar y configurar variables**:
   ```bash
   cp .env.example .env
   nano .env  # Editar con valores reales
   ```

2. **Verificar variables**:
   ```bash
   ./scripts/verify-production.sh
   ```

3. **Iniciar en modo producción**:
   ```bash
   ./scripts/start-production.sh
   ```

### Troubleshooting

| Problema | Causa Probable | Solución |
|----------|----------------|----------|
| `DATABASE_URL not set` | Variables no cargadas | Ejecutar `source .env` antes |
| `Redis connection failed` | Contraseña incorrecta | Verificar `REDIS_PASSWORD` |
| `JWT verification failed` | Secreto incorrecto | Verificar `JWT_SECRET` |
| `AI generation failed` | API Key inválida | Verificar `AI_API_KEY` |

---

## 📚 Referencias

- [DEPLOYMENT.md](./DEPLOYMENT.md) - Guía completa de deployment
- [SECURITY.md](./SECURITY.md) - Guía de seguridad
- [ARCHITECTURE.md](./ARCHITECTURE.md) - Arquitectura del sistema

---

**Última actualización:** Marzo 2026  
**Versión:** 1.0.0  
**Mantenido por:** DevOps Team