• Descripción
• Características
• Tecnologías
• Requisitos Previos
• Instalación
• Configuración
• Scripts Disponibles
• Estructura del Proyecto
• Características Principales
• Arquitectura
• Despliegue
• Documentación Adicional

Aplicación web desarrollada en React + TypeScript para la gestión integral de un taller mecánico y sus operaciones relacionadas con:

• Clientes y vehículos
• Citas, recepciones y seguimiento de servicios
• Facturación, proformas, cotizaciones y compras
• Inventario, bodegas y existencias
• Aseguradoras y trámites de seguros

El sistema se compone de:

• Landing pública para clientes finales (cotizaciones, citas y seguimiento).
• Panel administrativo protegido (/admin) para el personal del taller (gerencia, administración, recepción, etc.).

Construido con prácticas modernas, modularidad por dominio y un enfoque fuerte en seguridad y mantenibilidad.

• ✅ Solicitud de cotizaciones en línea.
• ✅ Programación de citas para servicios del taller.
• ✅ Seguimiento del estado de servicios / vehículos.
• ✅ Flujo de autenticación para clientes de landing.

• ✅ Dashboard / Home con visión general del taller.
• ✅ Perfil de usuario y gestión básica de cuenta.
• ✅ Gestión de clientes (alta, edición, detalle).
• ✅ Gestión de vehículos asociados a clientes.
• ✅ Recepciones y seguimiento de recepciones (estado de trabajos en curso).
• ✅ Facturas: creación, edición, detalle y búsqueda.
• ✅ Compras: registro y gestión de compras a proveedores.
• ✅ Proformas y generación de facturas desde proformas.
• ✅ Cotizaciones: detalle, edición y seguimiento.
• ✅ Aseguradoras y trámites de seguros.
• ✅ Productos / ítems con clasificación, unidades de medida y detalles.
• ✅ Impuestos, monedas y tipos de pago configurables.
• ✅ Bodegas y existencias por bodega, con restricciones por rol.

• ✅ Autenticación con verificación de sesión (checkAuthStatus).
• ✅ Rutas protegidas usando:
  • ProtectedRoute
  • NotAuthenticatedRoute
  • LandingProtectedRoute
  • RoleGuard
• ✅ Soporte de roles como gerente y superuser para módulos críticos (bodegas, existencias, administración, reportes, etc.).
• ✅ Manejo de errores de carga de chunks (useChunkErrorHandler) para despliegues seguros.

• ✅ Notificaciones con sonner.
• ✅ Diseño moderno con Tailwind CSS y animaciones (framer-motion, tailwindcss-animate).
• ✅ Componentes accesibles basados en Radix UI.
• ✅ Navegación SPA optimizada con React Router y code splitting (lazy loading).

• React 19.1.1 – Biblioteca de UI.
• TypeScript 5.8.x – Tipado estático.
• Vite 7.1.6 – Dev server y bundler.

• React Router 7.9.1 – Enrutamiento SPA.
• TanStack Query (React Query) 5.90.x – Estado del servidor y caché.
• Zustand 5.x – Estado global ligero (auth y otros stores).

• Tailwind CSS 3.4.17 – Utility-first CSS.
• tailwindcss-animate y tw-animate-css – Animaciones.
• Radix UI (@radix-ui/react-*) – Primitivas accesibles.
• Lucide React – Iconografía.
• cmdk – Componentes tipo command palette.

• React Hook Form 7.66.x – Manejo de formularios.
• DOMPurify – Sanitización de HTML.

• Axios – Cliente HTTP.
• Socket.IO Client – Comunicación en tiempo real (namespaces /admin y /cliente).
• date-fns – Utilidades de fechas.
• clsx, tailwind-merge y class-variance-authority – Utilidades para clases CSS.

• ESLint 9.x con reglas para React, hooks y TypeScript.
• TypeScript estricto.

• Node.js ≥ 18
• npm ≥ 9 (o cualquier otro gestor de paquetes si se adapta la configuración)
• Acceso a una API backend (idealmente NestJS) con soporte para:
  • HTTP REST (VITE_API_URL)
  • WebSockets / Socket.IO (VITE_SOCKET_URL, namespaces /admin y /cliente)

1. Clonar el repositorio

   git clone <URL_DEL_REPOSITORIO> cd ui-mts-web

2. Instalar dependencias

   npm install

3. Configurar variables de entorno

   • Crear un archivo .env.local (o .env) en la raíz del proyecto con al menos:

   VITE_API_URL=http://localhost:3000 VITE_SOCKET_URL=http://localhost:3000/admin # Opcional: cuando el cliente final está identificado VITE_CLIENTE_ID=

4. Iniciar el servidor de desarrollo

   npm run dev

   La aplicación estará disponible en http://localhost:5173 (por defecto).

El proyecto utiliza alias de paths configurados en tsconfig.json, por ejemplo:

import { AppLayout } from '@/shared/components/layouts/AppLayout';

El alias @ apunta a ./src.

# Desarrollo npm run dev # Inicia el servidor de desarrollo con HMR # Producción npm run build # Compila el proyecto para producción (TypeScript + Vite) npm run preview # Sirve el build de producción localmente # Calidad de código npm run lint # Ejecuta ESLint sobre el código del proyecto

ui-mts-web/ ├── public/ # Archivos estáticos (imágenes, sitemap, robots, sonidos) ├── src/ │ ├── admin/ # Páginas y componentes de administración │ │ ├── components/ │ │ └── pages/ │ ├── auth/ # Autenticación, acciones y store │ ├── landing/ # Landing pública (cotización, cita, seguimiento) │ │ ├── components/ │ │ ├── pages/ │ │ └── store/ & types/ │ ├── clientes/ # Módulo de clientes │ ├── vehiculo/ # Módulo de vehículos │ ├── cita/ # Citas y motivos de cita │ ├── recepcion/ # Recepciones │ ├── recepcion-seguimiento/ # Seguimiento de recepciones │ ├── facturas/ # Facturación │ ├── compra/ # Compras a proveedores │ ├── proforma/ # Proformas │ ├── cotizacion/ # Cotizaciones │ ├── aseguradora/ # Aseguradoras │ ├── tramite-seguro/ # Trámites de seguro │ ├── items/ # Productos / ítems │ ├── clasificacion-item/ # Clasificaciones de ítems │ ├── unidad-medida/ # Unidades de medida │ ├── tiposPago/ # Tipos de pago │ ├── moneda/ # Monedas │ ├── impuesto/ # Impuestos │ ├── bodega/ # Bodegas │ ├── existencia-bodega/ # Existencias por bodega │ ├── shared/ # Componentes, hooks y utilidades compartidas │ │ ├── api/ │ │ ├── components/ │ │ ├── config/ │ │ ├── hooks/ │ │ ├── lib/ │ │ ├── store/ │ │ ├── types/ │ │ └── utils/ │ ├── router/ │ │ └── app.router.tsx # Definición global de rutas │ ├── TallerApp.tsx # Componente raíz de la aplicación │ ├── main.tsx # Punto de entrada React │ ├── app.css / index.css # Estilos base │ └── vite-env.d.ts # Tipos de Vite ├── netlify.toml # Configuración de despliegue (Netlify) ├── package.json ├── tsconfig*.json # Configuración TypeScript ├── tailwind.config.ts # Configuración Tailwind └── vite.config.ts # Configuración Vite

Cada módulo (facturas, compra, clientes, vehiculo, cita, items, bodega, etc.) sigue una estructura coherente:

• actions/: llamadas a la API y lógica de negocio (capa de servicios).
• api/: configuración del cliente HTTP específico del módulo.
• hook/ o hooks/: hooks personalizados para consumo en componentes.
• pages/: páginas principales del módulo.
• ui/: componentes UI específicos del dominio.
• types/: interfaces y tipos TypeScript del módulo.

• Formularios construidos con React Hook Form.
• Validaciones en tiempo real y manejo de errores de usuario.
• Integración con notificaciones (sonner) para feedback inmediato.

• Uso intensivo de React Query para:
  • Caché de peticiones.
  • Refetch automático.
  • Manejo de estados de carga y error.

El proyecto sigue una arquitectura modular por dominio funcional:

módulo/ ├── actions/ # Llamadas a API (servicios) ├── api/ # Cliente HTTP del módulo ├── hook(s)/ # Hooks de negocio ├── pages/ # Vistas / páginas ├── ui/ # Componentes de interfaz └── types/ # Tipos e interfaces

Componente → Hook → Action → API → Backend ↓ React Query Cache

• src/router/app.router.tsx define:
  • Rutas de landing (/, /seguimiento, /cotizacion, /cita…).
  • Rutas de auth (/auth, /login, /register).
  • Panel /admin con rutas hijas por módulo.
  • Redirecciones desde rutas cortas (/facturas/*, /clientes/*, etc.) al panel admin.
  • Protección de rutas mediante ProtectedRoute, LandingProtectedRoute, NotAuthenticatedRoute y RoleGuard.

1. Generar build de producción

   npm run build

2. Servir la carpeta dist en un servidor estático (Netlify, Vercel, Nginx, etc.).

El archivo netlify.toml ya incluye configuración para despliegue como SPA (manejo de rutas y redirecciones).

• Mantener la estructura modular existente por dominio.
• Seguir las convenciones de nombres y patrón actions/api/hook/pages/ui/types.
• Ejecutar npm run lint antes de subir cambios.