🎓 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
269
frontend/README.md
Normal file
269
frontend/README.md
Normal file
@@ -0,0 +1,269 @@
|
||||
# Math Platform - Frontend
|
||||
|
||||
Frontend de la plataforma de estudio de matemáticas con Next.js 14, TypeScript, shadcn/ui y KaTeX.
|
||||
|
||||
## Stack Tecnológico
|
||||
|
||||
- **Framework**: Next.js 14 (App Router)
|
||||
- **Lenguaje**: TypeScript 5.4
|
||||
- **UI Components**: shadcn/ui + Radix UI
|
||||
- **Styling**: TailwindCSS
|
||||
- **Math Rendering**: KaTeX + react-katex
|
||||
- **State Management**: Zustand
|
||||
- **HTTP Client**: Axios
|
||||
- **Validation**: Zod + react-hook-form
|
||||
|
||||
## Estructura del Proyecto
|
||||
|
||||
```
|
||||
frontend/
|
||||
├── src/
|
||||
│ ├── app/ # Next.js App Router
|
||||
│ │ ├── layout.tsx # Layout raíz
|
||||
│ │ ├── page.tsx # Home page
|
||||
│ │ └── globals.css # Estilos globales
|
||||
│ ├── components/ # Componentes React
|
||||
│ │ ├── ui/ # shadcn/ui components
|
||||
│ │ └── math/ # Componentes matemáticos (KaTeX)
|
||||
│ ├── lib/ # Utilidades
|
||||
│ │ ├── api.ts # Cliente API
|
||||
│ │ ├── utils.ts # Utilidades generales
|
||||
│ │ ├── validators.ts # Esquemas Zod
|
||||
│ │ └── constants.ts # Constantes de la app
|
||||
│ ├── store/ # Zustand stores
|
||||
│ │ ├── useAuthStore.ts # Auth state
|
||||
│ │ └── useModuleStore.ts # Module state
|
||||
│ ├── hooks/ # Custom React hooks
|
||||
│ │ └── useAuth.ts # Auth hook
|
||||
│ └── types/ # TypeScript definitions
|
||||
│ └── index.ts # Tipos globales
|
||||
├── public/ # Archivos estáticos
|
||||
├── package.json # Dependencias
|
||||
├── tsconfig.json # Config TypeScript
|
||||
├── tailwind.config.js # Config TailwindCSS
|
||||
├── next.config.js # Config Next.js
|
||||
└── .env.local # Variables de entorno
|
||||
```
|
||||
|
||||
## Instalación
|
||||
|
||||
1. **Instalar dependencias**:
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
2. **Configurar variables de entorno**:
|
||||
```bash
|
||||
cp .env.local.example .env.local
|
||||
```
|
||||
|
||||
Edita `.env.local` con tus configuraciones:
|
||||
```env
|
||||
NEXT_PUBLIC_API_URL=http://localhost:3001
|
||||
NEXT_PUBLIC_APP_NAME=Math Platform
|
||||
```
|
||||
|
||||
3. **Ejecutar en desarrollo**:
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
La aplicación estará disponible en [http://localhost:3000](http://localhost:3000)
|
||||
|
||||
## Comandos Disponibles
|
||||
|
||||
```bash
|
||||
npm run dev # Servidor de desarrollo
|
||||
npm run build # Build de producción
|
||||
npm run start # Servidor de producción
|
||||
npm run lint # Linting con ESLint
|
||||
npm run type-check # Verificación de tipos
|
||||
npm run format # Formateo con Prettier
|
||||
```
|
||||
|
||||
## Componentes Disponibles
|
||||
|
||||
### UI Components (shadcn/ui)
|
||||
- Button
|
||||
- Card
|
||||
- Input
|
||||
- Label
|
||||
- Dialog
|
||||
- Dropdown Menu
|
||||
- Select
|
||||
- Tabs
|
||||
- Toast
|
||||
- Progress
|
||||
- Avatar
|
||||
- Separator
|
||||
- Tooltip
|
||||
|
||||
### Math Components
|
||||
- `MathFormula` - Componente base para renderizar fórmulas LaTeX
|
||||
- `MathBlock` - Fórmulas en modo bloque (display)
|
||||
- `MathInline` - Fórmulas en línea
|
||||
- `MathText` - Texto mixto con fórmulas LaTeX
|
||||
|
||||
### Uso de Componentes Matemáticos
|
||||
|
||||
```tsx
|
||||
import { MathBlock, MathInline, MathText } from '@/components/math/MathFormula';
|
||||
|
||||
// Fórmula en bloque
|
||||
<MathBlock formula="\int_{0}^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}" />
|
||||
|
||||
// Fórmula en línea
|
||||
<MathInline formula="E = mc^2" />
|
||||
|
||||
// Texto mixto
|
||||
<MathText text="La ecuación $x^2 + y^2 = r^2$ describe un círculo" />
|
||||
```
|
||||
|
||||
## State Management
|
||||
|
||||
### Auth Store
|
||||
```typescript
|
||||
import { useAuthStore } from '@/store/useAuthStore';
|
||||
|
||||
const { user, isAuthenticated, login, logout } = useAuthStore();
|
||||
```
|
||||
|
||||
### Module Store
|
||||
```typescript
|
||||
import { useModuleStore } from '@/store/useModuleStore';
|
||||
|
||||
const { modules, currentModule, setModules } = useModuleStore();
|
||||
```
|
||||
|
||||
## Cliente API
|
||||
|
||||
```typescript
|
||||
import { api, apiEndpoints } from '@/lib/api';
|
||||
|
||||
// GET request
|
||||
const modules = await api.get(apiEndpoints.modules.list);
|
||||
|
||||
// POST request
|
||||
const result = await api.post(apiEndpoints.auth.login, { email, password });
|
||||
```
|
||||
|
||||
## Validación de Formularios
|
||||
|
||||
```typescript
|
||||
import { loginSchema } from '@/lib/validators';
|
||||
import { useForm } from 'react-hook-form';
|
||||
import { zodResolver } from '@hookform/resolvers/zod';
|
||||
|
||||
const form = useForm({
|
||||
resolver: zodResolver(loginSchema),
|
||||
defaultValues: {
|
||||
email: '',
|
||||
password: '',
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
## Estilos
|
||||
|
||||
### TailwindCSS Config
|
||||
|
||||
El proyecto usa TailwindCSS con configuración personalizada para colores y animaciones.
|
||||
|
||||
### CSS Personalizado
|
||||
|
||||
Estilos adicionales en `src/app/globals.css`:
|
||||
- Animaciones personalizadas
|
||||
- Estilos de scroll
|
||||
- Clases de utilidad
|
||||
- Estilos de impresión
|
||||
- Accesibilidad
|
||||
|
||||
## Tipos TypeScript
|
||||
|
||||
Todos los tipos están definidos en `src/types/index.ts`:
|
||||
- User, Module, Exercise
|
||||
- Progress, Achievement, Ranking
|
||||
- API Response types
|
||||
- Form types
|
||||
|
||||
## Rutas
|
||||
|
||||
```typescript
|
||||
import { ROUTES } from '@/lib/constants';
|
||||
|
||||
ROUTES.HOME // '/'
|
||||
ROUTES.LOGIN // '/auth/login'
|
||||
ROUTES.DASHBOARD // '/dashboard'
|
||||
ROUTES.MODULES // '/modules'
|
||||
ROUTES.EXERCISES // '/exercises'
|
||||
ROUTES.RANKING // '/ranking'
|
||||
```
|
||||
|
||||
## Logros (Achievements)
|
||||
|
||||
Los logros están predefinidos en `src/lib/constants.ts`:
|
||||
- **Ejercicios**: Primer Paso, En Marcha, Matemático Dedicado
|
||||
- **Módulos**: Primera Conquista, Maestro del Álgebra
|
||||
- **Rachas**: En Racha, Semana Perfecta
|
||||
- **Ranking**: Top 10, Podium, El Campeón
|
||||
- **Especiales**: Madrugador, Búho Nocturno
|
||||
|
||||
## Build de Producción
|
||||
|
||||
```bash
|
||||
# Crear build optimizado
|
||||
npm run build
|
||||
|
||||
# Analizar bundle
|
||||
npm run analyze
|
||||
|
||||
# Ejecutar producción
|
||||
npm start
|
||||
```
|
||||
|
||||
## Docker
|
||||
|
||||
Para usar con Docker, ver el archivo `Dockerfile.frontend` en el directorio `/docker` del proyecto principal.
|
||||
|
||||
## Variables de Entorno
|
||||
|
||||
| Variable | Descripción | Default |
|
||||
|----------|-------------|---------|
|
||||
| `NEXT_PUBLIC_API_URL` | URL de la API backend | `http://localhost:3001` |
|
||||
| `NEXT_PUBLIC_APP_NAME` | Nombre de la aplicación | `Math Platform` |
|
||||
| `NEXT_PUBLIC_API_TIMEOUT` | Timeout de API (ms) | `30000` |
|
||||
|
||||
## Scripts de Utilidad
|
||||
|
||||
```bash
|
||||
# Type checking
|
||||
npm run type-check
|
||||
|
||||
# Linting
|
||||
npm run lint
|
||||
|
||||
# Formateo
|
||||
npm run format
|
||||
|
||||
# Análisis de bundle
|
||||
npm run analyze
|
||||
```
|
||||
|
||||
## Convenciones de Código
|
||||
|
||||
- **TypeScript**: Strict mode enabled
|
||||
- **Componentes**: Functional con hooks
|
||||
- **Estilos**: TailwindCSS utility-first
|
||||
- **Nomenclatura**: camelCase para variables, PascalCase para componentes
|
||||
- **Imports**: Absolute imports con `@/` alias
|
||||
|
||||
## Soporte de Navegadores
|
||||
|
||||
- Chrome (última versión)
|
||||
- Firefox (última versión)
|
||||
- Safari (última versión)
|
||||
- Edge (última versión)
|
||||
|
||||
## Licencia
|
||||
|
||||
Proprietary - Math Platform Team
|
||||
Reference in New Issue
Block a user