✅ FASE 1 COMPLETADA: Fundamentos y Core del Backend

- API REST completa con Node.js + Express + TypeScript - Autenticación JWT con roles (Player/Admin) - CRUD completo de canchas - Sistema de reservas con validaciones - Base de datos SQLite con Prisma ORM - Notificaciones por email (Nodemailer) - Seed de datos de prueba - Documentación de arquitectura Endpoints implementados: - Auth: register, login, refresh, me - Courts: CRUD + disponibilidad - Bookings: CRUD + confirmación/cancelación Credenciales de prueba: - admin@padel.com / admin123 - user@padel.com / user123
2026-01-31 08:11:53 +00:00
parent a83f4f39e9
commit b558372810
35 changed files with 7428 additions and 10 deletions
--- a/docs/arquitectura/STACK.md
+++ b/docs/arquitectura/STACK.md
@@ -0,0 +1,165 @@
+# Stack Tecnológico - App Canchas de Pádel
+
+## 🏗️ Arquitectura General
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      CLIENTES                               │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
+│  │   Web App    │  │  Mobile App  │  │  Admin Panel │      │
+│  │   (React)    │  │(React Native)│  │   (React)    │      │
+│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
+└─────────┼─────────────────┼─────────────────┼──────────────┘
+          │                 │                 │
+          └─────────────────┴─────────────────┘
+                            │
+                    ┌───────▼───────┐
+                    │  API Gateway  │
+                    │   (Nginx)     │
+                    └───────┬───────┘
+                            │
+          ┌─────────────────┼─────────────────┐
+          │                 │                 │
+   ┌──────▼──────┐  ┌──────▼──────┐  ┌──────▼──────┐
+   │   Backend   │  │   Backend   │  │   Backend   │
+   │   (Node.js) │  │   (Node.js) │  │   (Node.js) │
+   │   API REST  │  │   API REST  │  │   API REST  │
+   └──────┬──────┘  └──────┬──────┘  └──────┬──────┘
+          │                 │                 │
+          └─────────────────┴─────────────────┘
+                            │
+                    ┌───────▼───────┐
+                    │  PostgreSQL   │
+                    │   (Primary)   │
+                    └───────┬───────┘
+                            │
+              ┌─────────────┼─────────────┐
+              │             │             │
+       ┌──────▼──┐   ┌──────▼──┐   ┌──────▼──┐
+       │  Redis  │   │MinIO/S3 │   │Mailhog/│
+       │ (Cache) │   │(Files)  │   │SendGrid│
+       └─────────┘   └─────────┘   └────────┘
+```
+
+---
+
+## 📦 Stack por Componente
+
+### Backend
+| Tecnología | Versión | Uso |
+|------------|---------|-----|
+| Node.js | 20.x LTS | Runtime |
+| Express.js | 4.x | Framework HTTP |
+| TypeScript | 5.x | Tipado estático |
+| Prisma | 5.x | ORM y migraciones |
+| Zod | 3.x | Validación de schemas |
+| JWT | 9.x | Autenticación |
+| bcrypt | 5.x | Hash de passwords |
+| cors | 2.x | Cross-origin |
+| helmet | 7.x | Seguridad HTTP |
+| morgan | 1.x | Logging HTTP |
+| winston | 3.x | Logging app |
+| nodemailer | 6.x | Envío de emails |
+| dotenv | 16.x | Variables de entorno |
+
+### Base de Datos
+| Tecnología | Uso |
+|------------|-----|
+| PostgreSQL 16 | Base de datos principal |
+| Redis | Cache y sesiones |
+
+### Frontend Web
+| Tecnología | Versión | Uso |
+|------------|---------|-----|
+| React | 18.x | UI Library |
+| TypeScript | 5.x | Tipado estático |
+| Vite | 5.x | Build tool |
+| React Router | 6.x | Routing |
+| TanStack Query | 5.x | Data fetching |
+| Axios | 1.x | HTTP client |
+| TailwindCSS | 3.x | Estilos |
+| HeadlessUI | 1.x | Componentes accesibles |
+| React Hook Form | 7.x | Formularios |
+| Zod | 3.x | Validación |
+| date-fns | 3.x | Manejo de fechas |
+
+---
+
+## 📁 Estructura de Carpetas
+
+```
+backend/                    # API REST Node.js + Express
+├── src/
+│   ├── config/            # Configuración (DB, email, etc)
+│   ├── controllers/       # Controladores HTTP
+│   ├── middleware/        # Middlewares (auth, error, etc)
+│   ├── routes/            # Definición de rutas
+│   ├── services/          # Lógica de negocio
+│   ├── utils/             # Utilidades
+│   ├── validators/        # Schemas Zod
+│   └── index.ts           # Entry point
+├── prisma/
+│   └── schema.prisma      # Schema de BD
+├── tests/
+├── Dockerfile
+└── package.json
+```
+
+---
+
+## 🔐 Seguridad
+
+- **JWT** para autenticación stateless
+- **bcrypt** con salt rounds 12 para passwords
+- **Helmet** para headers de seguridad HTTP
+- **CORS** configurado por dominio
+- **Rate limiting** en endpoints sensibles
+- **Validación** de todos los inputs con Zod
+- **SQL Injection** protegido por Prisma ORM
+
+---
+
+## 🔌 API Endpoints (Versión 1)
+
+### Autenticación
+```
+POST   /api/v1/auth/register      # Registro
+POST   /api/v1/auth/login         # Login
+POST   /api/v1/auth/logout        # Logout
+POST   /api/v1/auth/refresh       # Refresh token
+POST   /api/v1/auth/forgot-password
+POST   /api/v1/auth/reset-password
+GET    /api/v1/auth/me            # Perfil actual
+```
+
+### Usuarios
+```
+GET    /api/v1/users              # Listar usuarios
+GET    /api/v1/users/:id          # Ver usuario
+PUT    /api/v1/users/:id          # Actualizar usuario
+DELETE /api/v1/users/:id          # Eliminar usuario (admin)
+```
+
+### Canchas
+```
+GET    /api/v1/courts             # Listar canchas
+GET    /api/v1/courts/:id         # Ver cancha
+POST   /api/v1/courts             # Crear cancha (admin)
+PUT    /api/v1/courts/:id         # Actualizar cancha (admin)
+DELETE /api/v1/courts/:id         # Eliminar cancha (admin)
+GET    /api/v1/courts/:id/availability  # Ver disponibilidad
+```
+
+### Reservas
+```
+GET    /api/v1/bookings           # Mis reservas
+GET    /api/v1/bookings/:id       # Ver reserva
+POST   /api/v1/bookings           # Crear reserva
+PUT    /api/v1/bookings/:id       # Modificar reserva
+DELETE /api/v1/bookings/:id       # Cancelar reserva
+```
+
+---
+
+*Definido el: 2026-01-31*
+*Fase: 1 - Fundamentos*
--- a/docs/roadmap/FASE-01.md
+++ b/docs/roadmap/FASE-01.md
@@ -1,15 +1,182 @@
 # Fase 1: Fundamentos y Core

-## Estado: 🚧 En progreso
+## Estado: ✅ COMPLETADA

-### Tareas completadas:
- [ ] 1.1.1 Definición de Arquitectura
- [ ] 1.1.2 Setup Infraestructura
- [ ] 1.2.1 Sistema de Autenticación
- [ ] 1.2.2 Gestión de Roles
- [ ] 1.3.1 Gestión de Canchas
- [ ] 1.3.2 Sistema de Reservas Core
- [ ] 1.3.3 Notificaciones Básicas
+### ✅ Tareas completadas:

-### Notas de la fase:
+#### 1.1.1 Definición de Arquitectura
+- [x] Stack tecnológico definido (Node.js + Express + TypeScript + Prisma + SQLite)
+- [x] Diagrama de arquitectura creado
+- [x] Estructura de base de datos diseñada
+- [x] Documento de requisitos técnicos

+#### 1.1.2 Setup de Infraestructura
+- [x] Repositorios Git configurados
+- [x] Entorno de desarrollo configurado
+- [x] Dependencias instaladas
+- [x] Configuración TypeScript
+- [x] ESLint configurado
+
+#### 1.2.1 Sistema de Autenticación
+- [x] Registro de usuarios con validación
+- [x] Login con JWT
+- [x] Refresh token
+- [x] Logout
+- [x] Middleware de autenticación
+- [x] Hash de contraseñas con bcrypt
+
+#### 1.2.2 Gestión de Roles
+- [x] Rol Jugador
+- [x] Rol Administrador
+- [x] Middleware de permisos (authorize)
+- [x] Protección de rutas por rol
+
+#### 1.3.1 Gestión de Canchas
+- [x] CRUD completo de canchas
+- [x] Configuración de horarios
+- [x] Estados de cancha (activa/inactiva)
+- [x] Tipos de cancha (Panorámica, Exterior, Cubierta)
+- [x] Consulta de disponibilidad por fecha
+
+#### 1.3.2 Sistema de Reservas Core
+- [x] Crear reserva con validaciones
+- [x] Validación de disponibilidad en tiempo real
+- [x] Verificación de horarios de cancha
+- [x] Prevención de reservas duplicadas
+- [x] Cancelación de reservas
+- [x] Confirmación de reservas (admin)
+- [x] Listado de reservas por usuario
+- [x] Listado de todas las reservas (admin)
+
+#### 1.3.3 Notificaciones Básicas
+- [x] Servicio de email configurado (Nodemailer)
+- [x] Email de bienvenida al registrar
+- [x] Email de confirmación de reserva
+- [x] Email de cancelación de reserva
+- [x] Template básico de emails
+
+---
+
+## 📊 Resumen de Implementación
+
+### Backend API
+- **URL Base**: `http://localhost:3000/api/v1`
+- **Tecnologías**: Node.js 20, Express, TypeScript, Prisma, SQLite
+- **Autenticación**: JWT con refresh tokens
+- **Validación**: Zod schemas
+
+### Endpoints implementados:
+
+| Método | Ruta | Descripción |
+|--------|------|-------------|
+| POST | /auth/register | Registro de usuarios |
+| POST | /auth/login | Login |
+| GET | /auth/me | Perfil del usuario |
+| POST | /auth/refresh | Refresh token |
+| GET | /courts | Listar canchas |
+| GET | /courts/:id | Ver cancha |
+| POST | /courts | Crear cancha (admin) |
+| PUT | /courts/:id | Actualizar cancha (admin) |
+| DELETE | /courts/:id | Eliminar cancha (admin) |
+| GET | /courts/:id/availability | Disponibilidad |
+| POST | /bookings | Crear reserva |
+| GET | /bookings | Listar reservas (admin) |
+| GET | /bookings/my-bookings | Mis reservas |
+| GET | /bookings/:id | Ver reserva |
+| PUT | /bookings/:id | Actualizar reserva |
+| DELETE | /bookings/:id | Cancelar reserva |
+| PUT | /bookings/:id/confirm | Confirmar reserva (admin) |
+
+### Base de Datos
+- **Provider**: SQLite (desarrollo) / PostgreSQL (producción)
+- **ORM**: Prisma
+- **Entidades**: User, Court, CourtSchedule, Booking
+
+### Credenciales de prueba:
+```
+Admin: admin@padel.com / admin123
+User:  user@padel.com / user123
+```
+
+---
+
+## 🚀 Cómo ejecutar
+
+```bash
+# Instalar dependencias
+cd backend
+npm install
+
+# Configurar variables de entorno
+cp .env.example .env
+
+# Generar cliente Prisma
+npx prisma generate
+
+# Ejecutar migraciones
+npx prisma migrate dev
+
+# Seed de datos
+npx tsx prisma/seed.ts
+
+# Iniciar servidor
+npm run dev
+```
+
+---
+
+## 📁 Archivos creados en esta fase
+
+```
+backend/
+├── src/
+│   ├── config/
+│   │   ├── index.ts
+│   │   ├── database.ts
+│   │   └── logger.ts
+│   ├── controllers/
+│   │   ├── auth.controller.ts
+│   │   ├── court.controller.ts
+│   │   └── booking.controller.ts
+│   ├── middleware/
+│   │   ├── auth.ts
+│   │   ├── errorHandler.ts
+│   │   └── validate.ts
+│   ├── routes/
+│   │   ├── auth.routes.ts
+│   │   ├── court.routes.ts
+│   │   ├── booking.routes.ts
+│   │   └── index.ts
+│   ├── services/
+│   │   ├── auth.service.ts
+│   │   ├── court.service.ts
+│   │   ├── booking.service.ts
+│   │   └── email.service.ts
+│   ├── utils/
+│   │   ├── jwt.ts
+│   │   ├── password.ts
+│   │   └── constants.ts
+│   ├── validators/
+│   │   └── auth.validator.ts
+│   └── index.ts
+├── prisma/
+│   ├── schema.prisma
+│   └── seed.ts
+├── package.json
+├── tsconfig.json
+└── .env
+```
+
+---
+
+## 📝 Notas
+
+- La Fase 1 está completa y lista para usar
+- El backend está funcional con todas las operaciones CRUD
+- Se incluyen datos de prueba (seed)
+- Los emails funcionan en modo simulado en desarrollo
+- Para producción, configurar SMTP en variables de entorno
+
+---
+
+*Completada el: 2026-01-31*