Sistema de Reservas - Prueba Técnica Senior Full-Stack

MVP funcional para la gestión de reservas de espacios comunes en una comunidad residencial (Pista de pádel, Piscina, Gimnasio).

✅ Estado del Proyecto

Sistema 100% Funcional

✅ Backend API REST operativo
✅ Frontend React funcional
✅ Base de datos MariaDB configurada
✅ 40/40 tests pasando (113 assertions)
✅ Docker Compose listo para docker-compose up --build

🚀 Quick Start

Requisitos Previos

Docker Desktop (con WSL Integration activada si estás en Windows)
Puertos disponibles: 8000 (backend), 5173 (frontend), 3306 (database)

⚠️ ¿Primera vez con Docker en Windows?

Si ves el error docker-compose could not be found:

👉 Lee: CONFIGURE_DOCKER.md - Configuración de Docker en WSL2

Levantar el Entorno

# 1. Construir y levantar todos los servicios
docker-compose up --build

# Los servicios estarán disponibles en:
# - Frontend: http://localhost:5173
# - Backend API: http://localhost:8000
# - Database: localhost:3306

Primera ejecución: Toma 5-10 minutos. El script automáticamente:

Crea la base de datos booking
Ejecuta las migraciones
Configura permisos
Inicia Nginx + PHP-FPM con Supervisor

Ejecutar Tests

# Ejecutar todos los tests (40 tests, 113 assertions)
docker-compose exec backend vendor/bin/phpunit

# Ver tests con detalles
docker-compose exec backend vendor/bin/phpunit --testdox

# Solo tests unitarios
docker-compose exec backend vendor/bin/phpunit tests/Unit

# Solo tests funcionales
docker-compose exec backend vendor/bin/phpunit tests/Functional

Probar la API Manualmente

# 1. Consultar disponibilidad de la pista de pádel
curl "http://localhost:8000/api/spaces/padel/availability?date=2025-10-15" | jq

# 2. Crear una reserva
curl -X POST http://localhost:8000/api/bookings \
  -H "Content-Type: application/json" \
  -d '{"space":"padel","date":"2025-10-15","hour":14}' | jq

# 3. Verificar que la hora 14:00 ahora está reservada
curl "http://localhost:8000/api/spaces/padel/availability?date=2025-10-15" | jq

# 4. Intentar reservar la misma hora (debe dar error 409 Conflict)
curl -X POST http://localhost:8000/api/bookings \
  -H "Content-Type: application/json" \
  -d '{"space":"padel","date":"2025-10-15","hour":14}' | jq

📋 Documentación Adicional

Guías de Usuario

QUICK_START.md - Guía de inicio rápido
CONFIGURE_DOCKER.md - Configuración de Docker en Windows/WSL2
TROUBLESHOOTING.md - Solución de problemas comunes encontrados durante el desarrollo

Documentación Técnica

Architecture Decision Records (ADRs) - ⭐ Decisiones arquitectónicas documentadas
- 🎯 Por qué React en lugar de Vue
- 🏗️ Por qué Arquitectura Hexagonal
- 💎 Por qué Value Objects
- 🔄 Por qué CQRS Light
- 🗄️ Por qué MariaDB
- 🛣️ Por qué routing manual
- 🧪 Metodología TDD
GUIA_IMPLEMENTACION.md - Guía completa paso a paso para replicar el proyecto desde cero con TDD

🏗️ Stack Tecnológico

Backend

PHP 8.2 con Symfony 5.4
Arquitectura Hexagonal (Ports & Adapters)
TDD (Test-Driven Development) - 40/40 tests ✅
CQRS Light (Command Query Responsibility Segregation)
Doctrine ORM con MariaDB 10.11
PHPUnit 9.6 para testing

Frontend

React 18 con TypeScript
Vite como build tool
Custom Hooks para lógica de negocio
CSS moderno con componentes reutilizables

Infraestructura

Docker con docker-compose
Nginx + PHP-FPM (gestionados con Supervisor)
MariaDB 10.11
Monorepo con backend y frontend

🎯 Características Implementadas

API REST

1. Consultar Disponibilidad

GET /api/spaces/{space}/availability?date=YYYY-MM-DD

Espacios válidos: padel, pool, gym

Respuesta (200 OK):

{
  "space": "padel",
  "date": "2025-10-15",
  "slots": [
    {"hour": "09:00", "status": "FREE"},
    {"hour": "10:00", "status": "FREE"},
    {"hour": "11:00", "status": "FREE"},
    ...
    {"hour": "20:00", "status": "FREE"}
  ]
}

2. Crear Reserva

POST /api/bookings
Content-Type: application/json

{
  "space": "padel",
  "date": "2025-10-15",
  "hour": 14
}

Respuesta (201 Created):

{
  "id": "2b8ccc12-3844-4a96-b6e4-7142f33fad9c",
  "space": "padel",
  "date": "2025-10-15",
  "hour": "14:00",
  "status": "RESERVED"
}

Error - Hora ya reservada (409 Conflict):

{
  "error": "The slot is already reserved"
}

Validaciones Implementadas

Espacios Válidos

padel - Pista de pádel
pool - Piscina
gym - Gimnasio

Horarios

Horas válidas: 9:00 a 20:00 (12 franjas horarias)
Reservas por hora completa

Reglas de Negocio

❌ No se pueden hacer dos reservas para el mismo espacio, fecha y hora
✅ Validación de formato de fecha (YYYY-MM-DD)
✅ Validación de espacios permitidos
✅ Validación de horarios permitidos

🏛️ Arquitectura Hexagonal

backend/src/Booking/
├── Domain/                    # 🎯 Núcleo del negocio (independiente de framework)
│   ├── Entity/
│   │   └── Booking.php       # Entidad principal (Aggregate Root)
│   ├── ValueObject/          # Objetos de valor inmutables con validaciones
│   │   ├── Space.php         # Espacios válidos: padel, pool, gym
│   │   ├── BookingDate.php   # Fechas con formato validado
│   │   ├── TimeSlot.php      # Horarios 9-20
│   │   └── BookingStatus.php # Estados: FREE, RESERVED
│   └── Repository/
│       └── BookingRepositoryInterface.php  # Puerto de salida
│
├── Application/               # 📋 Casos de uso (CQRS Light)
│   ├── Command/              # Comandos de escritura
│   │   ├── CreateBookingCommand.php
│   │   └── CreateBookingCommandHandler.php
│   └── Query/                # Queries de lectura
│       ├── GetAvailabilityQuery.php
│       ├── GetAvailabilityQueryHandler.php
│       ├── AvailabilityResponse.php
│       └── TimeSlotAvailability.php
│
└── Infrastructure/            # 🔌 Adaptadores (framework y BD)
    ├── Controller/           # Puerto de entrada (API REST)
    │   └── BookingController.php
    └── Persistence/          # Puerto de salida (implementación)
        └── DoctrineBookingRepository.php

Ventajas de esta Arquitectura

Independencia de Framework: El dominio no depende de Symfony
Testabilidad: Cada capa se puede testear independientemente (40 tests ✅)
Mantenibilidad: Código organizado con responsabilidades claras
Escalabilidad: Fácil agregar nuevos casos de uso
SOLID: Cumple los 5 principios de diseño OO
Flexibilidad: Se puede cambiar BD o framework sin tocar el dominio

Patrones Implementados

Value Objects: Inmutables con validaciones en el constructor
Repository Pattern: Abstracción del acceso a datos
CQRS Light: Separación de Commands (escritura) y Queries (lectura)
Dependency Injection: Vía constructor en todos los servicios
Aggregate Root: Booking como raíz del agregado

🧪 Estrategia de Testing: TDD Estricto

Este proyecto fue desarrollado siguiendo Test-Driven Development al 100%:

Ciclo Red-Green-Refactor

🔴 Red: Escribir test que falla
🟢 Green: Código mínimo para pasar el test
🔵 Refactor: Mejorar el código manteniendo tests verdes

Orden de Implementación (TDD)

Value Objects (con tests primero) → Space, TimeSlot, BookingDate, BookingStatus
Entities (con tests primero) → Booking
Application Layer (con tests primero) → Query/Command Handlers
Infrastructure Layer → Repository + Controller + Tests funcionales
Frontend → Componentes React con integración API

Resultados de Tests

PHPUnit 9.6.29 by Sebastian Bergmann and contributors.

OK (40 tests, 113 assertions)

Time: 00:02.828, Memory: 22.00 MB

Distribución de Tests

Tests Unitarios (37 tests)

Domain Layer (13 tests):

SpaceTest: 6 tests - Validación de espacios válidos
TimeSlotTest: 6 tests - Validación de franjas horarias
BookingDateTest: 3 tests - Validación de fechas
BookingStatusTest: 3 tests - Estados de reserva
BookingTest: 4 tests - Lógica de la entidad

Application Layer (24 tests):

GetAvailabilityQueryHandlerTest: 12 tests - Caso de uso de disponibilidad
CreateBookingCommandHandlerTest: 12 tests - Caso de uso de crear reserva

Tests Funcionales (3 tests)

BookingControllerTest: 3 tests end-to-end de la API
- testGetAvailabilityReturnsAllSlotsAsFree
- testCreateBookingSuccessfully
- testCreateBookingReturnsConflictWhenSlotAlreadyReserved

Principios de Testing

✅ Arrange-Act-Assert: Estructura clara en todos los tests
✅ Mocks: Para aislar dependencias externas (Repository)
✅ Fast Tests: Tests unitarios ejecutan en milisegundos
✅ Descriptive Names: Los nombres documentan el comportamiento
✅ One Assertion per Test: Foco en un comportamiento específico

📊 Modelo de Dominio

Entidad: Booking (Aggregate Root)

class Booking
{
    private string $id;              // UUID
    private Space $space;            // Value Object
    private BookingDate $date;       // Value Object
    private TimeSlot $timeSlot;      // Value Object
    private BookingStatus $status;   // Value Object
}

Value Objects

Value Object	Valores Permitidos	Validación
Space	`padel`, `pool`, `gym`	Throw exception si inválido
TimeSlot	`9` a `20` (horas)	Throw exception si fuera de rango
BookingDate	Formato `Y-m-d`	Validación con DateTime
BookingStatus	`FREE`, `RESERVED`	Enum-like inmutable

Reglas de Negocio

✅ Las franjas horarias son de 1 hora (9:00-20:00) = 12 franjas por día
✅ No se puede reservar una franja ya reservada (retorna 409 Conflict)
✅ Los espacios válidos están predefinidos (padel, pool, gym)
✅ Solo se permiten reservas en el horario establecido (9-20)

🎨 Frontend - Características

Componentes React

src/
├── components/
│   ├── SpaceSelector.tsx    # Selector de espacio (padel/pool/gym)
│   ├── DatePicker.tsx       # Selector de fecha
│   ├── TimeSlotGrid.tsx     # Grid de 12 horarios (9:00-20:00)
│   └── TimeSlotCard.tsx     # Card individual con estado FREE/RESERVED
├── hooks/
│   ├── useAvailability.ts   # Hook para cargar disponibilidad
│   └── useBookings.ts       # Hook para crear reservas
├── services/
│   └── bookingService.ts    # Cliente API REST
└── types/
    └── booking.types.ts     # TypeScript interfaces

Características UX

✅ Indicadores de carga mientras se consulta la API
✅ Mensajes de error claros y descriptivos
✅ Feedback visual inmediato al crear reserva
✅ Diseño responsive
✅ Colores diferenciados:
- 🟢 Verde = FREE (disponible)
- 🔴 Rojo = RESERVED (ocupado)
✅ Actualización automática de disponibilidad tras reservar

🔧 Comandos Útiles

Backend

# Acceder al contenedor
docker-compose exec backend bash

# Ejecutar tests
docker-compose exec backend vendor/bin/phpunit

# Ver rutas de la API
docker-compose exec backend php bin/console debug:router

# Limpiar caché
docker-compose exec backend php bin/console cache:clear

# Ejecutar migraciones
docker-compose exec backend php bin/console doctrine:migrations:migrate

# Crear nueva migración
docker-compose exec backend php bin/console doctrine:migrations:generate

# Ver logs
docker-compose logs -f backend

Base de Datos

# Acceder a MySQL/MariaDB
docker-compose exec database mysql -u booking_user -pbooking_pass booking

# Ver tablas
docker-compose exec database mysql -u booking_user -pbooking_pass booking -e "SHOW TABLES"

# Ver reservas actuales
docker-compose exec database mysql -u booking_user -pbooking_pass booking -e "SELECT * FROM bookings"

# Crear base de datos de tests (si no existe)
docker-compose exec database mysql -u root -proot -e "CREATE DATABASE IF NOT EXISTS booking_test"
docker-compose exec database mysql -u root -proot -e "GRANT ALL PRIVILEGES ON booking_test.* TO 'booking_user'@'%'"

Frontend

# Acceder al contenedor
docker-compose exec frontend sh

# Reinstalar dependencias
docker-compose exec frontend npm install

# Ver logs
docker-compose logs -f frontend

🐛 Troubleshooting

Error: "docker-compose: command not found"

Solución: Configura Docker Desktop WSL Integration 👉 Ver CONFIGURE_DOCKER.md

Error: "Connection reset by peer" al hacer curl

Causa: Backend aún está iniciando Solución: Espera 30 segundos y vuelve a intentar

Error: Tests fallan con "booking_test database not found"

Solución:

docker-compose exec database mysql -u root -proot -e "CREATE DATABASE IF NOT EXISTS booking_test"
docker-compose exec backend php bin/console doctrine:migrations:migrate --env=test --no-interaction

Error 500 en la API

Solución:

# Ver logs detallados
docker-compose logs backend | tail -50

# Limpiar caché
docker-compose exec backend php bin/console cache:clear

👉 Más soluciones en TROUBLESHOOTING.md

📁 Estructura del Proyecto

try1/
├── docker-compose.yml           # Orquestación de 3 servicios
├── README.md                    # Este archivo
├── GUIA_IMPLEMENTACION.md      # Guía paso a paso con TDD
├── TROUBLESHOOTING.md          # Solución de problemas
│
├── backend/                     # Backend PHP/Symfony
│   ├── Dockerfile              # PHP 8.2 + Nginx + Supervisor
│   ├── composer.json           # Dependencias PHP
│   ├── phpunit.xml.dist        # Configuración PHPUnit
│   ├── docker/
│   │   └── start.sh           # Script de inicio automático
│   ├── config/
│   │   ├── packages/          # Configuración Doctrine, Framework
│   │   ├── routes.yaml        # Rutas manuales (sin attributes)
│   │   └── services.yaml      # Definición de servicios DI
│   ├── migrations/
│   │   └── Version20251009000000.php  # Migración: tabla bookings
│   ├── public/
│   │   └── index.php         # Entry point Symfony
│   ├── src/
│   │   ├── Kernel.php
│   │   └── Booking/          # Bounded Context (Hexagonal)
│   │       ├── Domain/
│   │       ├── Application/
│   │       └── Infrastructure/
│   └── tests/
│       ├── Unit/             # 37 tests unitarios
│       └── Functional/       # 3 tests funcionales
│
└── frontend/                  # Frontend React + TypeScript
    ├── Dockerfile            # Node 18 + Vite
    ├── package.json          # Dependencias npm
    ├── tsconfig.json         # Configuración TypeScript
    ├── vite.config.ts        # Configuración Vite
    ├── index.html
    └── src/
        ├── main.tsx          # Entry point React
        ├── App.tsx           # Componente principal
        ├── components/       # Componentes reutilizables
        ├── hooks/            # Custom Hooks (useAvailability, useBookings)
        ├── services/         # API REST client
        └── types/            # TypeScript interfaces

🚧 Decisiones Técnicas y Trade-offs

💡 Todas las decisiones arquitectónicas están documentadas en Architecture Decision Records (ADRs)

Resumen de Decisiones Clave

Decisión	Justificación	Detalle
React vs Vue 3	Mayor experiencia, Custom Hooks, mejor demostración de habilidades	ADR-001
Arquitectura Hexagonal	Testabilidad, independencia del framework, SOLID	ADR-002
Value Objects	Encapsulación, validación, inmutabilidad	ADR-003
CQRS Light	Separación read/write, claridad, escalabilidad	ADR-004
MariaDB vs SQLite	Compatibilidad Doctrine, mejor para tests	ADR-005
Routing YAML	Configuración explícita, sin complejidad	ADR-006
TDD Estricto	Calidad del código, diseño guiado por tests	ADR-007

Trade-offs Principales

Más archivos, mejor organización:

🔴 Más archivos a navegar (10+ vs 3 en MVC tradicional)
🟢 Cada archivo tiene responsabilidad única y clara
🟢 Testabilidad independiente

React en lugar de Vue:

🔴 No cumple especificación literal (Vue 3 solicitado)
🟢 Código de mayor calidad por experiencia
🟢 Cláusula de flexibilidad permite tecnologías análogas

MariaDB en Docker:

🔴 Requiere contenedor adicional (~200MB)
🟢 Cero problemas de compatibilidad
🟢 Entorno cercano a producción

🎯 Próximos Pasos (Mejoras Futuras)

Corto Plazo (1-2 días)

Autenticación básica con JWT
Cancelar reservas - Endpoint DELETE /api/bookings/{id}
Ver mis reservas - Endpoint GET /api/bookings?user={id}
Tests frontend - Jest + React Testing Library
API Documentation - OpenAPI/Swagger

Medio Plazo (1 semana)

Sistema de usuarios con roles (admin, user)
Límites por usuario - Máximo X reservas por día/semana
Notificaciones - Email al confirmar reserva
UI mejorada - Tailwind CSS o Material-UI
CI/CD Pipeline - GitHub Actions para tests automáticos
Docker optimizado - Multi-stage builds
Gestión de espacios - CRUD completo (actualmente hardcoded)

Largo Plazo (Escalabilidad)

Event Sourcing - Auditoría completa de todas las reservas
CQRS completo - Bases de datos separadas para read/write
Cache distribuido - Redis para queries de disponibilidad
Mensajería asíncrona - RabbitMQ para notificaciones
Microservicios - Separar Espacios, Usuarios, Reservas
Observabilidad - Logs estructurados, métricas (Prometheus), tracing

🌟 Highlights del Proyecto

Code Quality

✅ Principios SOLID aplicados en todo el código
✅ Clean Code: Nombres descriptivos, métodos pequeños
✅ DRY: No hay código duplicado
✅ KISS: Soluciones simples y directas
✅ YAGNI: Solo implementado lo necesario

Testing

✅ 40/40 tests pasando (100% success rate)
✅ TDD estricto: Tests escritos antes que el código
✅ Fast tests: Suite completa ejecuta en ~3 segundos
✅ Tests como documentación: Nombres descriptivos

Architecture

✅ Hexagonal/Ports & Adapters: Dominio independiente
✅ CQRS Light: Commands y Queries separados
✅ Domain-Driven Design: Value Objects, Entities, Aggregates
✅ Dependency Injection: Inversión de dependencias
✅ Repository Pattern: Abstracción de persistencia

👨‍💻 Autor

Desarrollado como prueba técnica para posición de Senior Full-Stack Developer.

Tiempo de Desarrollo

Backend: ~6 horas (incluyendo TDD, arquitectura, debugging)
Frontend: ~2 horas (React + TypeScript + integración)
Docker: ~2 horas (configuración, troubleshooting)
Tests: Desarrollados incrementalmente con TDD
Documentación: ~1 hora

Total: ~11 horas

Metodología Aplicada

✅ Test-Driven Development (TDD)
✅ Clean Architecture (Hexagonal)
✅ Domain-Driven Design (DDD)
✅ SOLID Principles
✅ Continuous Integration (tests automatizados)

📄 Licencia

MIT License - Ver archivo LICENSE para más detalles.

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
backend		backend
docs/adr		docs/adr
frontend		frontend
.gitignore		.gitignore
CONFIGURE_DOCKER.md		CONFIGURE_DOCKER.md
GUIA_IMPLEMENTACION.md		GUIA_IMPLEMENTACION.md
LEEME_PRIMERO.md		LEEME_PRIMERO.md
QUICK_START.md		QUICK_START.md
README.md		README.md
SETUP_WINDOWS.md		SETUP_WINDOWS.md
SETUP_WITHOUT_DOCKER.md		SETUP_WITHOUT_DOCKER.md
TROUBLESHOOTING.md		TROUBLESHOOTING.md
VERIFY_DATABASE.md		VERIFY_DATABASE.md
docker-compose.yml		docker-compose.yml

Folders and files

Latest commit

History

Repository files navigation

Sistema de Reservas - Prueba Técnica Senior Full-Stack

✅ Estado del Proyecto

🚀 Quick Start

Requisitos Previos

⚠️ ¿Primera vez con Docker en Windows?

Levantar el Entorno

Ejecutar Tests

Probar la API Manualmente

📋 Documentación Adicional

Guías de Usuario

Documentación Técnica

🏗️ Stack Tecnológico

Backend

Frontend

Infraestructura

🎯 Características Implementadas

API REST

1. Consultar Disponibilidad

2. Crear Reserva

Validaciones Implementadas

Espacios Válidos

Horarios

Reglas de Negocio

🏛️ Arquitectura Hexagonal

Ventajas de esta Arquitectura

Patrones Implementados

🧪 Estrategia de Testing: TDD Estricto

Ciclo Red-Green-Refactor

Orden de Implementación (TDD)

Resultados de Tests

Distribución de Tests

Tests Unitarios (37 tests)

Tests Funcionales (3 tests)

Principios de Testing

📊 Modelo de Dominio

Entidad: Booking (Aggregate Root)

Value Objects

Reglas de Negocio

🎨 Frontend - Características

Componentes React

Características UX

🔧 Comandos Útiles

Backend

Base de Datos

Frontend

🐛 Troubleshooting

Error: "docker-compose: command not found"

Error: "Connection reset by peer" al hacer curl

Error: Tests fallan con "booking_test database not found"

Error 500 en la API

📁 Estructura del Proyecto

🚧 Decisiones Técnicas y Trade-offs

Resumen de Decisiones Clave

Trade-offs Principales

🎯 Próximos Pasos (Mejoras Futuras)

Corto Plazo (1-2 días)

Medio Plazo (1 semana)

Largo Plazo (Escalabilidad)

🌟 Highlights del Proyecto

Code Quality

Testing

Architecture

👨‍💻 Autor

Tiempo de Desarrollo

Metodología Aplicada

📄 Licencia

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Packages