Sistema Ágil de Gestión y Control para Barberos y Salones de Estética
Optimizado para barberos independientes dominicanos: rápido, táctil, con cálculo en Pesos Dominicanos (RD$), gestión de cola de turnos, control de fiados y balance de caja diario.
- Visión y Propósito
- Arquitectura y Principios SOLID
- Módulos y Funcionalidades
- Estructura del Código
- Instalación y Desarrollo Local
- Despliegue en Producción (Render.com)
- Licencia
BarberControl nació para solucionar los problemas reales de los barberos que trabajan de forma autónoma o en locales de alto flujo:
- ❌ Sin fricciones: Agregar un cliente o turno toma menos de 5 segundos. No se obliga a pedir teléfono ni datos innecesarios.
- 🇩🇴 Adaptado a República Dominicana: Todos los importes se manejan en Pesos Dominicanos (
RD$) con desglose de cobro en Efectivo o Transferencia bancaria. - ⚡ Modo Móvil Primero (PWA-Ready): Botones táctiles de gran tamaño, transiciones suaves y visibilidad óptima desde el teléfono del barbero colocado en el espejo o estación de trabajo.
- 🔒 Persistencia Segura: Backend Node.js ligero que almacena citas, servicios y fiados de forma atómica en disco sin requerir configuraciones de bases de datos pesadas.
El código de BarberControl fue refactorizado siguiendo rigurosamente los principios de diseño de software SOLID para garantizar mantenibilidad, desacoplamiento y facilidad de pruebas:
| Principio | Aplicación en BarberControl | Archivos Clave |
|---|---|---|
| S - Single Responsibility Principle (Responsabilidad Única) | Cada módulo tiene una única razón para cambiar. Los cálculos financieros, la derivación de clientes y el almacenamiento de datos están completamente aislados del estado de la interfaz de usuario. | • cajaCalculator.ts• clienteService.ts• httpAgendaStorage.ts |
| O - Open/Closed Principle (Abierto/Cerrado) | La capa de almacenamiento está abierta a la extensión pero cerrada a la modificación. Se pueden añadir nuevos motores de persistencia (Supabase, Firebase, LocalStorage, SQLite) implementando IAgendaStorage sin modificar el AgendaContext ni las vistas. |
• storage.interface.ts |
| L - Liskov Substitution Principle (Sustitución de Liskov) | Cualquier implementación que cumpla el contrato IAgendaStorage puede intercambiarse transparentemente (por ejemplo, HttpAgendaStorage en producción o un MockAgendaStorage en tests unitarios) sin alterar el comportamiento del sistema. |
• storage.interface.ts• httpAgendaStorage.ts |
| I - Interface Segregation Principle (Segregación de Interfaces) | En lugar de una interfaz monolítica gigante en el contexto, las operaciones y estados se segregan por dominios específicos: citas, servicios, fiados, analíticas de caja y navegación. Los componentes solo dependen de las interfaces que necesitan. | • types/index.ts( ICitasOperations, IServiciosOperations, IFiadosOperations, ICajaAnalytics, INavegacionState) |
| D - Dependency Inversion Principle (Inversión de Dependencias) | El estado global (AgendaContext) no depende de una implementación concreta de red (fetch directo o axios), sino de la abstracción IAgendaStorage. La dependencia se inyecta con un valor por defecto o mediante parámetros configurables. |
• AgendaContext.tsx |
- Alternancia ágil entre modo Turnos (orden de llegada para el día a día) y Citas Programadas (con hora asignada).
- Estados de cita claros:
Pendiente,En ProcesoyCompletada. - Finalización de cita con un solo clic especificando método de pago: Efectivo o Transferencia.
- Opción instantánea de enviar a la Libreta de Fiados si el cliente paga luego.
- Resumen automático de ingresos brutos del día en
RD$. - Desglose separado: Total Efectivo vs. Total Transferencia.
- Conteo de cortes y servicios completados hoy.
- Balance vivo de deudas pendientes por cobrar.
- Registro transparente de clientes con saldo pendiente.
- Historial de fecha y corte realizado.
- Acciones rápidas:
- Abonar deuda: Registrar un pago parcial reduciendo el monto pendiente.
- Saldar cuenta: Marcar la deuda como completamente pagada y enviar el cobro directamente a la caja del día.
- Tarifas preconfiguradas para cortes dominicanos:
- Corte Clásico (
RD$ 350) - Corte + Barba / Perfilado (
RD$ 500) - Barba Express (
RD$ 200) - Lavado + Peinado (
RD$ 250) - Tinte / Color (
RD$ 700) - Paquete Completo VIP (
RD$ 850)
- Corte Clásico (
- Creación, edición y eliminación de servicios y precios en cualquier momento.
barbercontrol/
├── server.js # Servidor backend Express (API /api/agenda y estáticos dist/)
├── data/
│ └── agenda-db.json # Base de datos JSON limpia para producción
├── src/
│ ├── components/ # Componentes modulares y reutilizables
│ │ ├── Header.tsx # Barra superior con fecha y estado del servidor
│ │ ├── Navigation.tsx # Barra de navegación táctil inferior/superior
│ │ ├── NuevaCitaModal.tsx # Modal ágil para registrar cliente y corte
│ │ └── CobrarModal.tsx # Modal de cobro rápido (Efectivo/Transferencia/Fiado)
│ ├── context/
│ │ └── AgendaContext.tsx # Orquestador del estado inyectando IAgendaStorage (DIP)
│ ├── services/ # Servicios desacoplados (SRP, OCP, LSP)
│ │ ├── storage.interface.ts # Contrato abstracto IAgendaStorage
│ │ ├── httpAgendaStorage.ts # Implementación cliente HTTP
│ │ ├── cajaCalculator.ts # Motor puro de cálculo financiero y métricas
│ │ └── clienteService.ts # Motor de extracción de clientes frecuentes
│ ├── types/
│ │ └── index.ts # Interfaces segregadas (ISP) y modelos de dominio
│ ├── utils/
│ │ └── formatters.ts # Formateador oficial de moneda RD$ y fechas
│ ├── views/ # Vistas principales de la aplicación
│ │ ├── AgendaView.tsx # Vista de turnos y citas del día
│ │ ├── CajaView.tsx # Vista de ingresos y métricas de caja
│ │ ├── FiadosView.tsx # Vista de la libreta de deudas
│ │ └── ServiciosView.tsx # Vista de tarifas y catálogo
│ ├── App.tsx # Componente raíz
│ └── main.tsx # Punto de entrada Vite/React
├── render.yaml # Especificación de Infraestructura como Código para Render
├── package.json # Dependencias y scripts de compilación
├── tsconfig.json # Configuración estricta de TypeScript
└── vite.config.ts # Configuración de empaquetado Vite
- Node.js 18.x o superior
- npm 9.x o superior
-
Clonar el repositorio:
git clone https://github.com/RaldyXs/barbercontrol.git cd barbercontrol -
Instalar dependencias:
npm install
-
Modo Desarrollo (Frontend Vite con recarga rápida):
npm run dev
Abre http://localhost:5173 en tu navegador.
-
Compilar para Producción:
npm run build
-
Iniciar Servidor Completo (Producción Local):
npm start
Abre http://localhost:3000. El backend servirá tanto la API de datos como el frontend compilado.
El proyecto está preparado para desplegarse de forma 100% gratuita y continua en Render:
- Entra a dashboard.render.com e inicia sesión.
- Haz clic en el botón azul "New +" y selecciona "Web Service".
- Elige la opción "Build and deploy from a Git repository" y haz clic en Next.
- Conecta tu cuenta de GitHub y selecciona el repositorio:
RaldyXs/barbercontrol - Configura los siguientes campos:
- Name:
barbercontrol(o el nombre que prefieras) - Region: La más cercana (ej. Ohio, US East)
- Branch:
main - Root Directory: (dejar en blanco)
- Runtime:
Node - Build Command:
npm install && npm run build - Start Command:
npm start - Instance Type:
Free
- Name:
- Haz clic en "Deploy Web Service".
Render compilará la aplicación y en pocos minutos te entregará una URL permanente con certificado SSL gratuito (ejemplo: https://barbercontrol.onrender.com).
Este proyecto es de código abierto bajo la licencia MIT. Siéntete libre de utilizarlo y personalizarlo para cualquier barbería o salón.