Beauty Salon - Sistema de Gestión de Reservas

🚧 Estado del Proyecto: En desarrollo activo (WIP). Enfocado en arquitectura escalable, optimización de ocupación y patrones de diseño modernos.

📋 Descripción General

Este proyecto es una solución integral para la gestión y reserva de turnos, diseñada bajo una arquitectura desacoplada (Headless). El sistema ofrece una experiencia de usuario nativa mediante una PWA, respaldada por una API robusta que no solo gestiona datos, sino que optimiza el tiempo del negocio.

El núcleo del sistema utiliza un algoritmo de disponibilidad personalizado ("Edge Filling Strategy") que maximiza la ocupación del salón y elimina los "tiempos muertos" mediante estrategias de compactación de agenda, ofreciendo turnos de manera inteligente en función de los huecos existentes.

🛠 Tech Stack

Backend (API REST)

• Core: PHP 8.3 + Symfony 7.4 (LTS).
• API Framework: API Platform (JSON-LD / Hydra).
• Auth: LexikJWTAuthenticationBundle (JWT).
• ORM: Doctrine.
• Database: MySQL.
• Metodología: RAD & Schema-Driven Development.

Frontend (Cliente Web & PWA)

• Framework: SvelteKit (Svelte 5 + Runes).
• Lenguaje: TypeScript (Strict Mode).
• Estilos: Tailwind CSS.
• State Management: TanStack Query (Svelte Query) para caché y sincronización server-state.
• Http Client: Patrón de Servicio Base Abstracto (AbstractApiService) con inyección de JWT.

🏗 Arquitectura y Lógica de Negocio

El proyecto implementa una Arquitectura de "Tres Reinos" diseñada para maximizar la conversión de clientes y separar responsabilidades:

1. Estructura de Rutas (The Three Kingdoms)

• Marketing (/): Landing page optimizada para SEO (SSG). Su objetivo es la carga instantánea para captar tráfico orgánico.
• App Cliente (/app): El producto central. Una PWA (Progressive Web App) que ofrece una experiencia nativa instalable, sin la fricción de las App Stores.
• Backoffice (/admin): Panel de gestión administrativa robusto y seguro (CSR protegido).

2. Modelo de Datos: Separación de Responsabilidades

El sistema distingue estrictamente entre el acceso al sistema y el recurso operativo:

• Entidad User: Maneja credenciales, roles (ROLE_USER, ROLE_EMPLOYEE, ROLE_ADMIN) y seguridad.
• Entidad Employee: Representa al profesional. Contiene horarios laborales (WorkSchedule), especialidades y biografía.
• Relación: One-to-One. Un usuario puede "ser" un empleado, pero los datos no se mezclan.

3. Motor de Disponibilidad: "Edge Filling Strategy"

A diferencia de los calendarios tradicionales, este sistema utiliza un algoritmo de compactación de agenda:

• Detección de Gaps: Calcula los huecos libres restando las reservas existentes a la jornada laboral.
• Estrategia de Bordes: Solo ofrece el Primer y el Último horario posible de cada hueco.
• Objetivo: Forzar reservas contiguas para evitar la fragmentación del horario (efecto "Queso Gruyère") y maximizar la rentabilidad.

4. Resolución de Conflictos: "Obstacle Merging"

Para evitar doble reserva por parte del cliente:

1. Se fusionan las reservas del Empleado y las reservas del Cliente en una sola lista de "Obstáculos" (Single Pass).
2. El algoritmo de Puntero recorre la línea de tiempo saltando estos obstáculos fusionados.
3. Beneficio: Genera bordes de disponibilidad personalizados y dinámicos alrededor de la vida del cliente.

🚀 Instalación en Local

# Clonar el repositorio
git clone https://github.com/HernandezDev/beauty-salon
cd beauty-salon

# Backend Setup
cd backend
composer install
cp .env.example .env
php bin/console doctrine:database:create
php bin/console doctrine:migrations:migrate
# php bin/console doctrine:fixtures:load # (datos de prueba WIP)
# Iniciar el servidor de desarrollo
symfony server:start

# Frontend Setup
cd ../frontend
npm install
# generar la inteface de API Platform
npm run generate-api
# Iniciar la PWA en modo desarrollo
npm run dev
# Acceder a la PWA en http://localhost:5173

🗺 Roadmap

✅ Fase 1: Definición y Configuración (Completado)

• Definición de Arquitectura y Stack Tecnológico.
• Configuración de API Platform y Base de Datos.
• Implementación de Servicios Base en Frontend (TypeScript).

🚧 Fase 2: Cimientos y Datos (En Progreso)

• Backend: Definición de Entidades Core (Service, Employee, WorkSchedule, Booking).
• Backend: Sistema de Fixtures Avanzado con zenstruck/foundry (Generación de escenarios de prueba con horarios reales).
• Seguridad: Implementación de make:user y configuración de JWT (login_check).
• Frontend: Integración de TanStack Query y Cliente HTTP con Interceptor de Token.

⚙️ Fase 3: Lógica del Motor (Core)

• Implementación del Availability Provider:
  • Algoritmo de Puntero (Cursor Tracking) para detección de Gaps.
  • Lógica de "Edge Filling" (Cálculo de Start/End del hueco).
  • Fusión de Obstáculos (Cliente + Empleado).
• Implementación de BookingProcessor con validaciones de concurrencia.
• Endpoint /api/my-schedule para la vista operativa del empleado.
• ( aprender State Providers State Processors)

📱 Fase 4: Experiencia de Usuario (MVP)

• UI de Selección de Servicios y Profesionales.
• Visualización del Calendario Inteligente (Solo sugerencias optimizadas).
• Panel de "Mi Agenda" en la PWA para empleados.
• Configuración de PWA (Manifest, Service Workers básicos).

🔮 Ideas Futuras (v1.1)

🚀 Upselling Contextual (Smart Chaining)

Aprovechar el motor de bordes para ofrecer servicios adicionales inmediatamente después de una reserva confirmada:

• Back-fill: "¿Vienes a las 11:00? Hazte la barba antes, a las 10:45".
• Forward-fill: "¿Terminas a las 11:30? Ana tiene libre para manicura en ese exacto momento".

Desarrollado por Hernandez Rivas Josué - 2025