math2-platform/README.md

Math2 Platform 🎓

Plataforma profesional de aprendizaje de matemáticas - Álgebra Lineal con IA

Sistema completo para estudiar álgebra lineal con ejercicios de nivel universitario, IA generativa para nuevos problemas, y renderizado LaTeX profesional.

---

🚀 Características Principales

📚 Contenido Académico

• ✅ 45 ejercicios universitarios organizados en 3 niveles:
  • 🟢 Básico (10): Vectores, operaciones fundamentales
  • 🟡 Intermedio (15): Productos, determinantes, sistemas
  • 🔴 Avanzado (20): Autovalores, diagonalización, SVD - nivel parcial
• ✅ SolutionSteps detallados con explicaciones paso a paso en LaTeX
• ✅ Sistema de hints con costos estratégicos
• ✅ Gamificación: Rankings, badges, streaks diarios

🤖 Inteligencia Artificial

• ✅ Generación automática de ejercicios via API (Z.ai/DashScope)
• ✅ Procesamiento de PDFs matemáticos
• ✅ Notificaciones Telegram para admins
• ✅ Validación de respuestas matemáticas

🎨 Frontend Profesional

• ✅ Renderizado LaTeX con react-katex + remark-math
• ✅ Next.js 14 con App Router
• ✅ TypeScript strict - código enterprise
• ✅ Tailwind CSS + shadcn/ui
• ✅ Responsive design

🛡️ Seguridad Enterprise

• ✅ JWT con refresh tokens y blacklist (Redis)
• ✅ Rate limiting multi-nivel
• ✅ XSS protection en fórmulas matemáticas
• ✅ Docker Secrets para credenciales
• ✅ SSL/TLS ready

🐳 Infraestructura

• ✅ Docker Compose - 9 servicios orquestados
• ✅ PostgreSQL 15 + Redis 7
• ✅ Nginx reverse proxy con SSL
• ✅ Workers background (PDF, ejercicios, notificaciones)
• ✅ Health checks en todos los servicios
• ✅ Zero-downtime deployment

---

📦 Stack Tecnológico

Frontend

• Framework: Next.js 14 (App Router)
• Lenguaje: TypeScript 5.3 (strict mode)
• Estilos: Tailwind CSS + shadcn/ui
• Estado: Zustand
• Testing: Vitest + React Testing Library
• Math: KaTeX, react-katex, remark-math

Backend

• Runtime: Node.js 20 LTS
• Framework: Express 4.x
• Lenguaje: TypeScript 5.3
• ORM: Prisma 5.x
• Base de datos: PostgreSQL 15
• Cache: Redis 7
• Testing: Vitest + Supertest
• AI: OpenAI API / DashScope

DevOps

• Docker: Multi-stage builds
• Orquestación: Docker Compose
• Proxy: Nginx 1.25
• SSL: Let's Encrypt (Certbot)
• Monitoreo: Prometheus + Grafana (listo)

---

🚀 Quick Start

Requisitos

• Docker 24.x + Docker Compose
• Node.js 20+ (desarrollo local)
• Git

1. Clonar Repositorio

git clone https://gitea.cbcren.online/renato97/math2-platform.git
cd math2-platform

2. Configurar Variables de Entorno

cp .env.example .env
# Editar .env con valores reales
nano .env

Variables críticas:

DB_PASSWORD=tu_password_segura
JWT_SECRET=tu_jwt_secret_32chars_minimo
AI_API_KEY=tu_api_key
TELEGRAM_BOT_TOKEN=tu_bot_token
TELEGRAM_ADMIN_CHAT_ID=tu_chat_id

3. Iniciar en Modo Producción

./scripts/start-production.sh

O manualmente:

docker-compose -f docker-compose.prod.yml --env-file .env up -d

4. Verificar Estado

./scripts/verify-production.sh

5. Acceder

• 🌐 Dashboard: http://localhost
• 🔧 API: http://localhost:3001
• 📊 Health: http://localhost:3001/health

---

🧪 Desarrollo Local

Backend

cd backend
npm install
npx prisma migrate dev
npx prisma db seed
npm run dev

Frontend

cd frontend
npm install
npm run dev

Tests

# Backend
cd backend && npm test

# Frontend  
cd frontend && npm test

# E2E
npx playwright test

---

📊 Estado del Proyecto

Componente	Estado	Detalles
Tests	✅ 123/123	100% pasando
TypeScript	⚠️ ~29 errores	Core: 0 errores
Docker	✅ Listo	9 servicios
Seguridad	✅ OK	XSS, JWT, Rate limiting
Documentación	✅ 5 informes	2000+ líneas

---

📁 Estructura del Proyecto

math2-platform/
├── backend/              # API Node.js + Express
│   ├── src/
│   │   ├── modules/      # Módulos de negocio
│   │   ├── shared/       # Utils, middlewares
│   │   └── workers/      # Background jobs
│   ├── prisma/           # Schema + migrations
│   └── tests/            # Tests unitarios
├── frontend/             # Next.js 14
│   ├── src/
│   │   ├── app/          # App Router
│   │   ├── components/   # UI components
│   │   └── hooks/        # Custom hooks
│   └── tests/            # Component tests
├── docker/               # Dockerfiles
├── scripts/              # Deployment scripts
├── docs/                 # Documentación
└── shared/               # Tipos compartidos

---

🎓 Contenido Académico

Ejercicios Disponibles

Nivel Básico (10)

• Suma y resta de vectores
• Multiplicación por escalar
• Producto punto
• Norma de vectores
• Matrices básicas

Nivel Intermedio (15)

• Producto cruz 3D
• Determinantes 2×2 y 3×3
• Inversa de matrices
• Sistemas de ecuaciones
• Proyección ortogonal

Nivel Avanzado (20) - Parcial Universitario

• Autovalores y autovectores
• Diagonalización de matrices
• Matrices ortogonales
• Proceso Gram-Schmidt
• Descomposición SVD
• Formas cuadráticas
• Optimización en Rⁿ

---

🔒 Seguridad

Medidas Implementadas

• ✅ JWT con refresh tokens
• ✅ Rate limiting (Redis)
• ✅ XSS protection (KaTeX sanitizado)
• ✅ SQL injection prevention (Prisma)
• ✅ CORS configurado
• ✅ Headers de seguridad (HSTS, CSP)
• ✅ Password hashing (bcrypt)

Credenciales

⚠️ Nunca commitear archivos .env

# Asegurar que .env está en .gitignore
grep ".env" .gitignore

---

🤝 Contribución

1. Fork el repositorio
2. Crear branch: git checkout -b feature/nueva-funcionalidad
3. Commit: git commit -m 'feat: nueva funcionalidad'
4. Push: git push origin feature/nueva-funcionalidad
5. Crear Pull Request

Convenciones

• Commits: Conventional Commits
• Código: TypeScript strict
• Tests: >80% cobertura backend
• Docs: Actualizar README.md

---

📚 Documentación

Informes técnicos completos:

1. INFORME_FINAL_REMEDIACION.md - Sprint 1: Correcciones críticas
2. INFORME_SPRINT_2.md - Sprint 2: Regresiones eliminadas
3. INFORME_SPRINT_3.md - Sprint 3: TypeScript + Docker
4. INFORME_SPRINT_3B_LATEX.md - LaTeX + Ejercicios PRO
5. DEPLOYMENT_REPORT.md - Guía de deployment

---

📄 Licencia

MIT License - Ver LICENSE

---

👥 Autor

Renato - @renato97

Construido con ❤️ para estudiantes de álgebra lineal.

---

🙏 Agradecimientos

• OpenCode Multi-Agent System
• Kimi AI Assistant
• Prisma ORM
• Next.js Team
• KaTeX Project

---

¡Listo para comerse el parcial de álgebra lineal! 🎓🚀