System Requirements Document for youssef-barber

1. Introduction

YOUSSEF BARBER es una barbería a domicilio que necesita una presencia web ultra moderna, premium y muy llamativa, cuyo objetivo principal es conseguir que los visitantes reserven una cita. La web debe transmitir de inmediato que se trata de un servicio de barbería profesional y moderno —nunca una plantilla genérica— y acompañar al visitante por un recorrido natural de conversión: CONOCER → VER TRABAJOS → VER SERVICIOS → PERSONALIZAR → RESERVAR.

El producto es una aplicación web completa y funcional (no una maqueta) construida con React/Next.js + Tailwind + Framer Motion, con backend y base de datos real para citas y reseñas, y un panel de administración privado con acceso seguro.

Audiencia:

• Cliente (visitante que reserva): persona que descubre la barbería, explora trabajos y servicios, personaliza su corte y reserva una cita a domicilio; también puede contactar por WhatsApp y dejar una reseña.
• Administrador: responsable del negocio que gestiona citas, horarios, clientes, servicios, precios, reseñas, fotografías y disponibilidad desde un panel privado.

2. System Overview

YOUSSEF BARBER se entrega como una aplicación web responsive con una Landing pública que presenta la marca, el eslogan TU CORTE. TU ESTILO. TU CASA., los servicios con precios, la galería de trabajos recientes, las reseñas de clientes, la sección de Instagram y la explicación visual del servicio a domicilio VOY HASTA TU CASA. Desde la Landing, el visitante accede al flujo de reserva por pasos, a la galería filtrable y a las reseñas, y dispone en todo momento de un botón flotante de WhatsApp y de un botón de reserva siempre accesible.

El sistema persiste citas y reseñas en una base de datos real. Las reseñas se moderan desde el panel de administración. El administrador accede mediante un Login seguro y gestiona desde el Panel de Administración las citas (aceptar/rechazar), los horarios y la disponibilidad (bloqueo de horarios), los clientes, los servicios y precios, las reseñas y las fotografías.

Actores:

• Cliente (visitante que reserva) — persona activa; navega, personaliza y reserva.
• Administrador — persona activa; gestiona el negocio desde el panel privado.
• WhatsApp — destino externo; recibe el mensaje preparado de solicitud de cita.
• Instagram — destino externo; recibe la visita desde el botón VER INSTAGRAM.

Exclusiones actuales (explícitas): no se implementan ahora pagos online, cupones, promociones, notificaciones, historial de clientes ni programa de fidelización; la web solo debe quedar preparada para añadirlos posteriormente.

2a. Product Interpretation and Delivery Boundary

La entrega es una aplicación web propia con UI personalizada. La Landing, el flujo de reserva, la galería y las reseñas son públicos y anónimos: el visitante puede conocer la barbería, ver trabajos, ver servicios, personalizar su corte y reservar sin crear cuenta. La reserva se identifica por los datos que el propio cliente introduce (nombre, teléfono, dirección), que quedan vinculados a la cita en la base de datos.

El panel de administración es privado y requiere acceso seguro del administrador mediante verificación de retorno en el Login. Solo el administrador accede al Panel de Administración, a Citas y a Reseñas Admin.

El trabajo de WhatsApp e Instagram se entrega a destinos externos (no son páginas propias): el botón flotante abre WhatsApp con un mensaje preparado para solicitar una cita, y el botón VER INSTAGRAM abre el perfil externo.

Frontera actual/futuro: todo lo descrito arriba es actual. Pagos online, cupones, promociones, notificaciones, historial de clientes y programa de fidelización quedan fuera del alcance actual y se documentan únicamente como preparación futura.

2b. Source Content Inventory

No aplica: no se ha suministrado ninguna directiva de referencia con content_source.

2c. Page Content and Component Coverage

Landing

• Información y estado: nombre YOUSSEF BARBER, eslogan TU CORTE. TU ESTILO. TU CASA., texto secundario Cortes profesionales a domicilio. Fades, clásicos y cortes personalizados., servicios con precios, trabajos recientes, reseñas, Instagram, servicio a domicilio y CTAs.
• Acciones principales: 🔥 RESERVAR CITA (destacado visualmente), \xf0\x9f\x92\xac WHATSAPP, botón reservar en cada tarjeta de servicio, ⭐ DEJAR MI RESEÑA, VER INSTAGRAM, CTAs de conversión.
• Acciones de soporte: navegación por secciones, apertura del menú hamburguesa animado en móvil, filtrado de galería, apertura de fotografía en pantalla grande.
• Entidades de dominio: Servicio (nombre, precio, descripción, imagen/icono), Fotografía (categoría), Reseña (estrellas, nombre, comentario, fecha), Cita (referencia al flujo de reserva).
• Responsabilidades de componentes:
  • Hero principal: titular a escala de cartel, eslogan, texto secundario, dos botones grandes, imagen grande de barbería/cortes y fondo cinematográfico con iluminación y movimiento sutil.
  • Sección de servicios: cuatro tarjetas premium — CORTE CLÁSICO 10 €, FADE / DEGRADADO 12 €, CORTE PERSONALIZADO 12 €, CORTE + BARBA 15 € — cada una con imagen o icono, nombre, precio, descripción, botón reservar y animación hover.
  • Sección de reseñas LO QUE DICEN NUESTROS CLIENTES: tarjetas con\x20\xe2\xad\x90⭐⭐⭐⭐, nombre del cliente, comentario y fecha, con animaciones al aparecer; botón ⭐ DEJAR MI RESEÑA y formulario de nombre, estrellas y comentario.
  • Sección de galería TRABAJOS RECIENTES: fotografías de cortes con categorías Todos | Fades | Clásicos | Personalizados | Barba; al pulsar una fotografía se abre en pantalla grande con transición y se cierra con animación suave.
  • Sección de Instagram: fotografías y botón VER INSTAGRAM.
  • Sección VOY HASTA TU CASA: explicación visual del flujo\x20\xf0\x9f\x93\x8d Elige tu ubicación →\x20\xf0\x9f\x93\x85 Elige tu horario →\x20\xe2\x9c\x82️ Elige tu corte →\x20\xf0\x9f\x8f\xa0 Yo voy hasta ti.
  • CTAs de conversión: ¿LISTO PARA CAMBIAR DE LOOK?, RESERVA TU CITA AHORA, TU PRÓXIMO CORTE ESTÁ A UN CLIC.
  • Botón flotante de WhatsApp: siempre visible; al pasar el cursor muestra ¿Necesitas ayuda? Escríbeme; al pulsarlo abre WhatsApp con mensaje preparado para solicitar una cita.
  • Cabecera y navegación móvil: menú hamburguesa animado y botón de reservar siempre accesible.
• Estados: carga con animación de entrada y aparición suave del logo; vacío de reseñas o galería con mensaje neutro; éxito al enviar reseña (confirmación de recepción pendiente de moderación); error de envío con reintento; recuperación conservando los datos introducidos.

Reservar

• Información y estado: pasos Servicio → Fecha → Personalización → Datos → Confirmación con barra de progreso; resumen de la reserva antes de confirmar.
• Acciones principales: elegir servicio; elegir fecha; elegir hora disponible; introducir nombre; introducir teléfono; introducir dirección; personalizar el corte; revisar el resumen; confirmar.
• Acciones de soporte: avanzar y retroceder entre pasos, corregir datos, reintentar en caso de error.
• Entidades de dominio: Servicio, Fecha, Hora disponible, Datos del cliente (nombre, teléfono, dirección), Personalización del corte, Cita.
• Responsabilidades de componentes:
  • Barra de progreso con los cinco pasos nombrados.
  • Selector de servicio con los cuatro servicios y precios.
  • Selector de fecha y selector de hora disponible (horas ofrecidas según la disponibilidad configurada por el administrador).
  • Sección DISEÑA TU CORTE: selección de Fade bajo, Fade medio, Fade alto, Taper, Clásico, Corte personalizado, Con diseño, Sin diseño, Con barba, Sin barba, más el campo ¿Cómo quieres tu corte? para escribir instrucciones.
  • Formulario de datos: nombre, teléfono, dirección.
  • Resumen y confirmación con animación de confirmación al reservar.
• Estados: carga de horas disponibles; vacío cuando no hay horas para la fecha elegida; éxito con animación de confirmación; error de validación o de guardado con recuperación sin perder lo introducido.

Galería

• Información y estado: fotografías de cortes organizadas por categoría Todos | Fades | Clásicos | Personalizados | Barba.
• Acciones principales: filtrar por categoría; abrir una fotografía en pantalla grande; cerrar con animación suave.
• Acciones de soporte: navegación entre fotografías dentro de la vista ampliada.
• Entidades de dominio: Fotografía (imagen, categoría).
• Responsabilidades de componentes: mosaico de fotografías, pestañas de categoría, visor a pantalla grande con transición de apertura y cierre animado.
• Estados: carga con aparición progresiva; vacío por categoría sin fotografías; éxito al abrir y cerrar el visor; error de carga de imagen con marcador de reserva.

Reseñas

• Información y estado: sección LO QUE DICEN NUESTROS CLIENTES con tarjetas de\x20\xe2\xad\x90⭐⭐⭐⭐, nombre del cliente, comentario y fecha.
• Acciones principales: ⭐ DEJAR MI RESEÑA; enviar nombre, estrellas y comentario.
• Acciones de soporte: leer reseñas publicadas; reintentar el envío si falla.
• Entidades de dominio: Reseña (nombre, estrellas, comentario, fecha, estado de moderación).
• Responsabilidades de componentes: listado de tarjetas con animaciones al aparecer y estrellas animadas suavemente; formulario de envío de reseña.
• Estados: carga con animación de entrada de tarjetas; vacío sin reseñas publicadas; éxito con confirmación de envío; error de envío con reintento.

Login

• Información y estado: acceso seguro del administrador al panel privado.
• Acciones principales: verificar la identidad del administrador para entrar al panel.
• Acciones de soporte: reintentar tras credenciales incorrectas.
• Entidades de dominio: Credencial de administrador, Sesión.
• Responsabilidades de componentes: formulario de acceso y verificación de retorno.
• Estados: carga durante la verificación; éxito con redirección al Panel de Administración; error con mensaje claro y posibilidad de reintento.

Panel de Administración

• Información y estado: resumen del estado del negocio y accesos a las áreas de gestión: citas, horarios, clientes, servicios, precios, reseñas, fotografías y disponibilidad.
• Acciones principales: navegar a Citas y a Reseñas Admin; gestionar horarios, clientes, servicios, precios, fotografías y disponibilidad.
• Acciones de soporte: cerrar sesión.
• Entidades de dominio: Cita, Horario, Cliente, Servicio, Precio, Reseña, Fotografía, Disponibilidad.
• Responsabilidades de componentes: rejilla densa tipo panel de instrumentos con filas regladas y estados por color de señal; accesos a cada área de gestión.
• Estados: carga de datos del panel; vacío por área sin registros; éxito tras cada actualización; error de carga o guardado con reintento.

Citas

• Información y estado: listado de citas con sus datos (servicio, fecha, hora, cliente, dirección, personalización) y su estado.
• Acciones principales: aceptar cita; rechazar cita; bloquear horarios.
• Acciones de soporte: consultar el detalle de una cita; filtrar por estado.
• Entidades de dominio: Cita, Horario bloqueado, Cliente.
• Responsabilidades de componentes: tabla de citas con acciones por fila; control de bloqueo de horarios.
• Estados: carga del listado; vacío sin citas; éxito al aceptar, rechazar o bloquear con actualización visible del estado; error con reintento.

Reseñas Admin

• Información y estado: reseñas guardadas en la base de datos con nombre, estrellas, comentario, fecha y estado de moderación.
• Acciones principales: moderar reseñas (aprobar o rechazar su publicación).
• Acciones de soporte: revisar el contenido completo de cada reseña.
• Entidades de dominio: Reseña (estado de moderación).
• Responsabilidades de componentes: listado de reseñas con controles de moderación.
• Estados: carga del listado; vacío sin reseñas pendientes; éxito al moderar con actualización del estado; error con reintento.

3. Functional Requirements

FR-01 — Web premium ultra moderna (explicit). As a Cliente (visitante que reserva) I should entrar en una web de YOUSSEF BARBER que se perciba inmediatamente como una barbería profesional y moderna, con eslogan TU CORTE. TU ESTILO. TU CASA. y objetivo principal de reservar una cita, so that confíe en el servicio y avance hacia la reserva. Resultado observable: la Landing carga con identidad de marca completa y el recorrido CONOCER → VER TRABAJOS → VER SERVICIOS → PERSONALIZAR → RESERVAR es navegable. Acceso: público y anónimo. Fallo/recuperación: si un bloque no carga, se muestra su estado de error sin bloquear el resto. Continuación: el visitante puede iniciar la reserva desde cualquier CTA.

FR-02 — Estilo visual premium (explicit). As a Cliente (visitante que reserva) I should ver un estilo premium, moderno, urbano, elegante, masculino y futurista pero limpio, inspirado en webs de barberías de alta gama, con paleta negro/negro carbón, blanco, gris oscuro y detalles dorados o metálicos, tipografías grandes y llamativas en los títulos, e iluminación, partículas sutiles, sombras, gradientes y profundidad sin sobrecargar, so that la percepción sea de alta gama. Resultado observable: la interfaz aplica la paleta y la jerarquía tipográfica descritas. Acceso: público. Fallo/recuperación: si un efecto no puede renderizarse, la interfaz mantiene legibilidad y contraste. Continuación: el visitante sigue navegando sin degradación funcional.

FR-03 — Animaciones profesionales y fluidas (explicit). As a Cliente (visitante que reserva) I should experimentar animación de entrada al cargar la página, aparición suave del logo, títulos con efecto de aparición, hover y microanimaciones en botones, tarjetas de servicios que se elevan al pasar el cursor, zoom suave en imágenes, animaciones al hacer scroll, secciones que aparecen progresivamente, contadores animados, transiciones suaves entre secciones, brillo alrededor de botones importantes, partículas sutiles de fondo, animaciones suaves en las estrellas de las reseñas, transición al abrir el formulario de reserva y animación de confirmación al reservar, so that la experiencia resulte profesional y fluida. Resultado observable: cada animación listada se ejecuta de forma rápida y suave. Acceso: público. Fallo/recuperación: si el rendimiento se degrada, las animaciones se reducen sin romper la interfaz. Continuación: la navegación y la reserva permanecen operativas.

FR-04 — Hero principal espectacular (explicit). As a Cliente (visitante que reserva) I should ver en la primera pantalla YOUSSEF BARBER, TU CORTE. TU ESTILO. TU CASA., el texto secundario Cortes profesionales a domicilio. Fades, clásicos y cortes personalizados., dos botones grandes 🔥 RESERVAR CITA (destacado visualmente) y \xf0\x9f\x92\xac WHATSAPP, una imagen grande relacionada con barbería/cortes y un fondo cinematográfico con iluminación y movimiento sutil, so that la primera impresión sea espectacular. Resultado observable: el hero muestra todos los elementos y el contenido aparece con una animación elegante al entrar. Acceso: público. Fallo/recuperación: si la imagen no carga, se mantiene el fondo cinematográfico y los botones. Continuación: 🔥 RESERVAR CITA lleva al flujo de reserva y \xf0\x9f\x92\xac WHATSAPP abre WhatsApp.

FR-05 — Tarjetas de servicios premium (explicit). As a Cliente (visitante que reserva) I should ver tarjetas premium de CORTE CLÁSICO 10 €, FADE / DEGRADADO 12 €, CORTE PERSONALIZADO 12 € y CORTE + BARBA 15 €, cada una con imagen o icono, nombre, precio, descripción, botón reservar y animación hover que hace reaccionar visualmente la tarjeta, so that conozca la oferta y pueda reservar desde la tarjeta. Resultado observable: las cuatro tarjetas muestran sus datos exactos y reaccionan al cursor. Acceso: público. Fallo/recuperación: si falta la imagen o icono, se muestra un marcador sin perder nombre, precio ni descripción. Continuación: el botón reservar inicia el flujo con el servicio preseleccionado.

FR-06 — Sistema de reservas por pasos (explicit). As a Cliente (visitante que reserva) I should elegir servicio, elegir fecha, elegir hora disponible, introducir nombre, introducir teléfono, introducir dirección, personalizar mi corte, revisar el resumen y confirmar, con animaciones entre cada paso y una barra de progreso Servicio → Fecha → Personalización → Datos → Confirmación, so that complete mi reserva a domicilio. Resultado observable: la cita queda registrada en la base de datos y se muestra la animación de confirmación. Acceso: público y anónimo. Fallo/recuperación: ante error de validación o de guardado, se indica el problema y se conservan los datos introducidos para reintentar. Continuación: tras confirmar, el cliente ve el resumen confirmado y puede volver a la Landing.

FR-07 — Horas disponibles según disponibilidad del administrador (required_inference). As a Cliente (visitante que reserva) I should elegir una hora disponible ofrecida según la disponibilidad configurada por el administrador, so that solo pueda reservar en franjas realmente ofertables. Resultado observable: el selector de hora muestra únicamente horas disponibles para la fecha elegida. Acceso: público. Fallo/recuperación: si no hay horas para la fecha, se muestra estado vacío y se invita a elegir otra fecha. Continuación: al elegir hora, el flujo avanza al paso de personalización.

FR-08 — Sección DISEÑA TU CORTE (explicit). As a Cliente (visitante que reserva) I should seleccionar Fade bajo, Fade medio, Fade alto, Taper, Clásico, Corte personalizado, Con diseño, Sin diseño, Con barba, Sin barba y escribir instrucciones en el campo ¿Cómo quieres tu corte?, so that mi corte quede especificado con precisión. Resultado observable: las selecciones y las instrucciones quedan asociadas a la reserva y visibles en el resumen. Acceso: público. Fallo/recuperación: si no se selecciona nada, se permite continuar con la personalización vacía o se solicita confirmación. Continuación: el flujo avanza al paso de datos.

FR-09 — Sección de reseñas (explicit). As a Cliente (visitante que reserva) I should ver la sección LO QUE DICEN NUESTROS CLIENTES con tarjetas de\x20\xe2\xad\x90⭐⭐⭐⭐, nombre del cliente, comentario y fecha, con animaciones al aparecer, so that conozca la opinión de otros clientes. Resultado observable: las tarjetas se muestran con sus datos y animación de entrada. Acceso: público. Fallo/recuperación: si no hay reseñas publicadas, se muestra un estado vacío neutro. Continuación: el visitante puede dejar su propia reseña.

FR-10 — Envío de reseña (explicit). As a Cliente (visitante que reserva) I should pulsar ⭐ DEJAR MI RESEÑA y enviar nombre, estrellas y comentario, so that mi opinión quede registrada. Resultado observable: la reseña se guarda en la base de datos y queda pendiente de moderación. Acceso: público. Fallo/recuperación: si el envío falla, se muestra error y se permite reintentar sin perder lo escrito. Continuación: el visitante recibe confirmación de envío.

FR-11 — Moderación de reseñas (explicit). As a Administrador I should moderar desde el panel de administración las reseñas guardadas en la base de datos, so that solo se publiquen las apropiadas. Resultado observable: el estado de moderación de cada reseña cambia y se refleja en la sección pública. Acceso: restringido al administrador autenticado. Fallo/recuperación: si la moderación falla, se muestra error y se permite reintentar. Continuación: el administrador continúa moderando el resto.

FR-12 — Galería TRABAJOS RECIENTES (explicit). As a Cliente (visitante que reserva) I should ver la galería TRABAJOS RECIENTES con fotografías de cortes y categorías Todos | Fades | Clásicos | Personalizados | Barba, so that evalúe la calidad del trabajo. Resultado observable: las fotografías se muestran filtradas por la categoría activa. Acceso: público. Fallo/recuperación: si una imagen no carga, se muestra un marcador sin romper el mosaico. Continuación: el visitante puede abrir una fotografía o pasar a reservar.

FR-13 — Visor de fotografía a pantalla grande (explicit). As a Cliente (visitante que reserva) I should pulsar una fotografía para abrirla en pantalla grande con transición y cerrarla con una animación suave, so that la examine en detalle. Resultado observable: la fotografía se amplía con transición y se cierra con animación suave. Acceso: público. Fallo/recuperación: si la imagen ampliada falla, se cierra el visor y se vuelve a la galería. Continuación: el visitante sigue explorando la galería.

FR-14 — CTAs de conversión (explicit). As a Cliente (visitante que reserva) I should encontrar a lo largo de la página varios CTA como ¿LISTO PARA CAMBIAR DE LOOK?, RESERVA TU CITA AHORA y TU PRÓXIMO CORTE ESTÁ A UN CLIC., so that el flujo me conduzca naturalmente a reservar. Resultado observable: cada CTA es visible y conduce al flujo de reserva. Acceso: público. Fallo/recuperación: