math2-platform/frontend/README.md

# 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