app-padel/docs/roadmap/FASE-02.md

# Fase 2: Gestión de Jugadores y Perfiles

## Estado: ✅ COMPLETADA

### ✅ Tareas completadas:

#### 2.1.1: Perfil Completo
- [x] Datos personales extendidos (ciudad, fecha nacimiento)
- [x] Datos de juego (años jugando, mano, posición)
- [x] Estadísticas de partidos (jugados, ganados, perdidos)
- [x] Biografía y foto de perfil

#### 2.1.2: Sistema de Niveles
- [x] Escala de niveles con descripciones (BEGINNER a PROFESSIONAL)
- [x] Modelo LevelHistory para tracking de cambios
- [x] Validación de nivel por administradores
- [x] Historial de cambios de nivel

#### 2.2.1: Sistema de Amigos/Grupos
- [x] Enviar/recibir solicitudes de amistad
- [x] Estados: PENDING, ACCEPTED, REJECTED, BLOCKED
- [x] Crear grupos de jugadores
- [x] Roles en grupos: ADMIN, MEMBER
- [x] Invitar jugadores a grupo
- [x] Reserva grupal (para fases posteriores)

#### 2.2.2: Reservas Recurrentes
- [x] Configurar fijo semanal (mismo día/hora)
- [x] Modelo RecurringBooking
- [x] Generación automática de reservas desde recurrentes
- [x] Cancelación de series recurrentes

#### 2.3.1: Historial de Actividad
- [x] Modelo MatchResult para resultados de partidos
- [x] Registro de partidos jugados (2v2)
- [x] Sistema de confirmación de resultados (2+ jugadores)
- [x] Estadísticas de asistencia

#### 2.3.2: Ranking Interno
- [x] Sistema de puntos (Victoria=10, Derrota=2, Participación=1)
- [x] Bonus por ganar a nivel superior (+5 pts)
- [x] Multiplicadores por nivel de jugador
- [x] Tabla de clasificación visible
- [x] Filtros por período (mensual, anual, global)
- [x] Modelo UserStats para estadísticas agregadas

---

## 📊 Resumen de Implementación

### Modelos de Base de Datos

| Modelo | Descripción |
|--------|-------------|
| User | Extendido con city, birthDate, yearsPlaying, matchesPlayed/Won/Lost, totalPoints |
| LevelHistory | Tracking de cambios de nivel |
| Friend | Solicitudes de amistad con estados |
| Group | Grupos de jugadores |
| GroupMember | Miembros de grupos con roles |
| RecurringBooking | Reservas recurrentes semanales |
| MatchResult | Resultados de partidos 2v2 |
| UserStats | Estadísticas agregadas por período |

### Nuevos Endpoints

#### Perfiles
```
GET    /api/v1/users/me              - Mi perfil
PUT    /api/v1/users/me              - Actualizar perfil
GET    /api/v1/users/search          - Buscar usuarios
GET    /api/v1/users/:id             - Ver perfil público
PUT    /api/v1/users/:id/level       - Cambiar nivel (admin)
GET    /api/v1/users/:id/level-history - Historial de niveles
```

#### Amigos
```
POST   /api/v1/friends/request       - Enviar solicitud
PUT    /api/v1/friends/:id/accept    - Aceptar solicitud
PUT    /api/v1/friends/:id/reject    - Rechazar solicitud
GET    /api/v1/friends               - Mis amigos
GET    /api/v1/friends/pending       - Solicitudes pendientes
DELETE /api/v1/friends/:id           - Eliminar amigo
```

#### Grupos
```
POST   /api/v1/groups                - Crear grupo
GET    /api/v1/groups                - Mis grupos
GET    /api/v1/groups/:id            - Ver grupo
PUT    /api/v1/groups/:id            - Actualizar grupo
DELETE /api/v1/groups/:id            - Eliminar grupo
POST   /api/v1/groups/:id/members    - Agregar miembro
DELETE /api/v1/groups/:id/members/:userId - Eliminar miembro
```

#### Reservas Recurrentes
```
POST   /api/v1/recurring             - Crear recurrente
GET    /api/v1/recurring             - Mis recurrentes
DELETE /api/v1/recurring/:id         - Cancelar recurrente
POST   /api/v1/recurring/:id/generate - Generar reservas
```

#### Partidos
```
POST   /api/v1/matches               - Registrar partido
GET    /api/v1/matches/my-matches    - Mis partidos
GET    /api/v1/matches/:id           - Ver partido
PUT    /api/v1/matches/:id/confirm   - Confirmar resultado
```

#### Ranking y Estadísticas
```
GET    /api/v1/ranking               - Ranking general
GET    /api/v1/ranking/me            - Mi posición
GET    /api/v1/ranking/top           - Top jugadores
GET    /api/v1/stats/my-stats        - Mis estadísticas
GET    /api/v1/stats/users/:id       - Stats de usuario
GET    /api/v1/stats/courts/:id      - Stats de cancha
GET    /api/v1/stats/global          - Stats globales
```

### Sistema de Puntos

| Concepto | Puntos |
|----------|--------|
| Victoria | 10 |
| Derrota | 2 |
| Participación | 1 |
| Ganar a superior | +5 |

**Multiplicadores por nivel:**
- BEGINNER: 1.0x
- ELEMENTARY: 1.1x
- INTERMEDIATE: 1.2x
- ADVANCED: 1.3x
- COMPETITION: 1.5x
- PROFESSIONAL: 2.0x

### Rangos

| Puntos | Título |
|--------|--------|
| 0-99 | Bronce |
| 100-299 | Plata |
| 300-599 | Oro |
| 600-999 | Platino |
| 1000+ | Diamante |

---

## 🚀 Cómo probar

```bash
cd backend
npm run dev
```

### Credenciales de prueba

| Email | Password | Nivel |
|-------|----------|-------|
| admin@padel.com | admin123 | ADMIN |
| user@padel.com | user123 | INTERMEDIATE |
| carlos@padel.com | 123456 | ADVANCED |
| ana@padel.com | 123456 | INTERMEDIATE |
| pedro@padel.com | 123456 | BEGINNER |
| maria@padel.com | 123456 | COMPETITION |

---

## 📁 Archivos creados en esta fase

```
backend/src/
├── services/
│   ├── user.service.ts         # Perfiles y búsqueda
│   ├── friend.service.ts       # Sistema de amigos
│   ├── group.service.ts        # Grupos de jugadores
│   ├── recurring.service.ts    # Reservas recurrentes
│   ├── match.service.ts        # Registro de partidos
│   ├── ranking.service.ts      # Cálculo de ranking
│   └── stats.service.ts        # Estadísticas
├── controllers/
│   ├── user.controller.ts
│   ├── friend.controller.ts
│   ├── group.controller.ts
│   ├── recurring.controller.ts
│   ├── match.controller.ts
│   ├── ranking.controller.ts
│   └── stats.controller.ts
├── routes/
│   ├── user.routes.ts
│   ├── friend.routes.ts
│   ├── group.routes.ts
│   ├── recurring.routes.ts
│   ├── match.routes.ts
│   ├── ranking.routes.ts
│   └── stats.routes.ts
├── validators/
│   ├── user.validator.ts
│   └── social.validator.ts
└── utils/
    └── ranking.ts              # Cálculo de puntos y rangos
```

---

*Completada el: 2026-01-31*