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

Fase 2: Gestión de Jugadores y Perfiles

Estado: ✅ COMPLETADA

✅ Tareas completadas:

2.1.1: Perfil Completo

• Datos personales extendidos (ciudad, fecha nacimiento)
• Datos de juego (años jugando, mano, posición)
• Estadísticas de partidos (jugados, ganados, perdidos)
• Biografía y foto de perfil

2.1.2: Sistema de Niveles

• Escala de niveles con descripciones (BEGINNER a PROFESSIONAL)
• Modelo LevelHistory para tracking de cambios
• Validación de nivel por administradores
• Historial de cambios de nivel

2.2.1: Sistema de Amigos/Grupos

• Enviar/recibir solicitudes de amistad
• Estados: PENDING, ACCEPTED, REJECTED, BLOCKED
• Crear grupos de jugadores
• Roles en grupos: ADMIN, MEMBER
• Invitar jugadores a grupo
• Reserva grupal (para fases posteriores)

2.2.2: Reservas Recurrentes

• Configurar fijo semanal (mismo día/hora)
• Modelo RecurringBooking
• Generación automática de reservas desde recurrentes
• Cancelación de series recurrentes

2.3.1: Historial de Actividad

• Modelo MatchResult para resultados de partidos
• Registro de partidos jugados (2v2)
• Sistema de confirmación de resultados (2+ jugadores)
• Estadísticas de asistencia

2.3.2: Ranking Interno

• Sistema de puntos (Victoria=10, Derrota=2, Participación=1)
• Bonus por ganar a nivel superior (+5 pts)
• Multiplicadores por nivel de jugador
• Tabla de clasificación visible
• Filtros por período (mensual, anual, global)
• 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

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