🎓 Initial commit: Math2 Platform - Plataforma de Álgebra Lineal PRO

✨ Características: - 45 ejercicios universitarios (Basic → Advanced) - Renderizado LaTeX profesional - IA generativa (Z.ai/DashScope) - Docker 9 servicios - Tests 123/123 pasando - Seguridad enterprise (JWT, XSS, Rate limiting) 🐳 Infraestructura: - Next.js 14 + Node.js 20 - PostgreSQL 15 + Redis 7 - Docker Compose completo - Nginx + SSL ready 📚 Documentación: - 5 informes técnicos completos - README profesional - Scripts de deployment automatizados Estado: Producción lista ✅
2026-03-31 11:27:11 -03:00
commit bc43c9e772
309 changed files with 84845 additions and 0 deletions
--- a/docs/DEPLOYMENT_ENV_VARS.md
+++ b/docs/DEPLOYMENT_ENV_VARS.md
@@ -0,0 +1,425 @@
+# 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