🎓 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 ✅
This commit is contained in:
Renato
316
README.md
Normal file
316
README.md
Normal file
@@ -0,0 +1,316 @@
|
||||
# Math2 Platform 🎓
|
||||
|
||||
[](https://gitea.cbcren.online/renato97/math2-platform)
|
||||
[](https://gitea.cbcren.online/renato97/math2-platform)
|
||||
[](https://gitea.cbcren.online/renato97/math2-platform)
|
||||
[](https://gitea.cbcren.online/renato97/math2-platform)
|
||||
[](LICENSE)
|
||||
|
||||
**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
|
||||
|
||||
```bash
|
||||
git clone https://gitea.cbcren.online/renato97/math2-platform.git
|
||||
cd math2-platform
|
||||
```
|
||||
|
||||
### 2. Configurar Variables de Entorno
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# Editar .env con valores reales
|
||||
nano .env
|
||||
```
|
||||
|
||||
**Variables críticas:**
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
./scripts/start-production.sh
|
||||
```
|
||||
|
||||
O manualmente:
|
||||
```bash
|
||||
docker-compose -f docker-compose.prod.yml --env-file .env up -d
|
||||
```
|
||||
|
||||
### 4. Verificar Estado
|
||||
|
||||
```bash
|
||||
./scripts/verify-production.sh
|
||||
```
|
||||
|
||||
### 5. Acceder
|
||||
|
||||
- 🌐 **Dashboard**: http://localhost
|
||||
- 🔧 **API**: http://localhost:3001
|
||||
- 📊 **Health**: http://localhost:3001/health
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Desarrollo Local
|
||||
|
||||
### Backend
|
||||
```bash
|
||||
cd backend
|
||||
npm install
|
||||
npx prisma migrate dev
|
||||
npx prisma db seed
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### Frontend
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### Tests
|
||||
```bash
|
||||
# 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**
|
||||
```bash
|
||||
# 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](LICENSE)
|
||||
|
||||
---
|
||||
|
||||
## 👥 Autor
|
||||
|
||||
**Renato** - [@renato97](https://gitea.cbcren.online/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! 🎓🚀**
|
||||
Reference in New Issue
Block a user