# 🌴 Karibeo - Tourism & Business Management Platform [![React](https://img.shields.io/badge/React-18.3.1-blue.svg)](https://reactjs.org/) [![TypeScript](https://img.shields.io/badge/TypeScript-5.5.3-blue.svg)](https://www.typescriptlang.org/) [![Tailwind CSS](https://img.shields.io/badge/Tailwind-3.4.1-38bdf8.svg)](https://tailwindcss.com/) [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) Karibeo es una plataforma integral de gestión turística y comercial diseñada para conectar turistas con servicios locales mientras proporciona herramientas empresariales avanzadas para hoteles, restaurantes y comercios. ## 🚀 Características Principales ### Para Turistas 🧳 - **Exploración Interactiva**: Descubre destinos, lugares y experiencias únicas - **Reservas Integradas**: Sistema completo de reservas para hoteles, restaurantes y tours - **Geolocalización Avanzada**: Encuentra servicios cercanos con mapas interactivos - **Billetera Digital**: Gestión de pagos y transacciones seguras - **Reseñas y Valoraciones**: Sistema completo de reviews y puntuaciones - **Asistente IA**: Asistente flotante con inteligencia artificial para ayuda personalizada ### Para Negocios 💼 #### 🏨 Gestión Hotelera - Sistema de reservas y check-in/check-out - Gestión de habitaciones e inventario - Room service y amenidades - Control de acceso sin llaves (keyless entry) - Gestión de personal y turnos #### 🍽️ Sistema POS Restaurante - Terminal de punto de venta completa - Gestión de pedidos y cocina - Sistema de mesas y reservaciones - Gestión de menú dinámico - Control de inventario - Facturación y cuentas #### 🏪 Gestión de Comercio - Tienda virtual integrada - Terminal POS para ventas - Gestión de inventario y productos - Control de clientes y fidelización - Sistema de caja y reportes - Gestión de personal ### Panel de Administración 👨‍💼 - **Dashboard Ejecutivo**: Métricas en tiempo real y KPIs - **Gestión de Usuarios**: Control completo de usuarios y perfiles - **Sistema de Roles y Permisos**: Gestión granular por entidad (Admin, Hotel, Restaurante, Comercio) - **CRM Integrado**: Gestión de contactos, campañas y analytics - **Channel Manager**: Sincronización multi-canal (Booking, Airbnb, Expedia) - **Sistema de Comisiones**: Reglas automatizadas y tracking - **Configuración Global**: APIs, pagos, integraciones - **Security Center**: Monitoreo y auditoría de seguridad - **Analytics Avanzado**: Reportes y visualización de datos ### Módulos Especiales 🌟 - **POLITUR**: Sistema de emergencias y seguridad turística - **Guías Turísticos**: Creación y gestión de itinerarios personalizados - **Sostenibilidad**: Tracking de impacto ambiental y certificaciones - **Gestión de Vehículos**: Control de flotas y mantenimiento ## 🛠️ Stack Tecnológico ### Frontend - **Framework**: React 18.3.1 + TypeScript - **Build Tool**: Vite 6.2.0 - **Styling**: Tailwind CSS + shadcn/ui components - **State Management**: React Context + TanStack Query - **Routing**: React Router DOM 7.8.2 - **Forms**: React Hook Form + Zod validation - **Maps**: Google Maps API - **Charts**: Recharts + ApexCharts ### Dependencias Clave ```json { "@tanstack/react-query": "^5.83.0", "@googlemaps/js-api-loader": "^1.16.10", "react-hook-form": "^7.61.1", "zod": "^3.25.76", "recharts": "^3.1.2", "lucide-react": "^0.462.0" } ``` ## 📁 Estructura del Proyecto ``` karibeo/ ├── src/ │ ├── components/ # Componentes reutilizables │ │ ├── admin/ # Componentes de administración │ │ ├── hotel/ # Componentes hoteleros │ │ ├── restaurant/ # Componentes de restaurante │ │ ├── roles/ # Sistema de roles │ │ ├── security/ # Componentes de seguridad │ │ └── ui/ # Componentes UI base (shadcn) │ ├── contexts/ # React Contexts │ │ ├── AuthContext.tsx │ │ ├── CartContext.tsx │ │ └── CurrencyContext.tsx │ ├── hooks/ # Custom React Hooks │ │ ├── useAdminData.ts │ │ ├── useBooking.ts │ │ └── useRolesPermissions.ts │ ├── pages/ # Páginas/Rutas │ │ ├── dashboard/ # Panel de control │ │ ├── SignIn.tsx │ │ └── SignUp.tsx │ ├── services/ # Servicios API │ │ ├── adminApi.ts │ │ ├── emergencyApi.ts │ │ └── paymentService.ts │ ├── types/ # Definiciones TypeScript │ ├── lib/ # Utilidades │ │ ├── utils.ts │ │ └── validation.ts # Schemas de validación Zod │ ├── i18n/ # Internacionalización │ └── App.tsx # Componente principal ├── public/ # Assets estáticos ├── tailwind.config.ts # Configuración Tailwind ├── tsconfig.json # Configuración TypeScript └── vite.config.ts # Configuración Vite ``` ## 🚦 Instalación y Configuración ### Prerrequisitos - Node.js 18+ (recomendado usar [nvm](https://github.com/nvm-sh/nvm)) - npm o yarn ### Instalación Local ```bash # 1. Clonar el repositorio git clone https://github.com/tu-usuario/karibeo.git cd karibeo # 2. Instalar dependencias npm install # 3. Configurar variables de entorno # Crear archivo .env en la raíz (ver sección de Configuración) # 4. Iniciar servidor de desarrollo npm run dev # El proyecto estará disponible en http://localhost:5173 ``` ### Scripts Disponibles ```bash npm run dev # Servidor de desarrollo npm run build # Build de producción npm run preview # Preview del build npm run lint # Linting con ESLint ``` ## 🔐 Autenticación y Seguridad ### Sistema de Autenticación - Login mediante email/password con validación robusta - Tokens JWT con refresh token automático - Soporte para OAuth (Google, Apple) - Sesiones persistentes en localStorage ### Validación de Inputs Todos los formularios utilizan **Zod** para validación: ```typescript // Ejemplo de schema de validación const loginSchema = z.object({ email: z.string().email().max(255), password: z.string().min(8).max(128) }); ``` ### Roles y Permisos Sistema granular de permisos por entidad: - **Admin**: Gestión global del sistema - **Hotel**: Permisos específicos para hoteles - **Restaurant**: Permisos para restaurantes - **Commerce**: Permisos para comercios ## 🌍 Internacionalización Soporte multi-idioma con contexto dedicado: - Español (ES) - Por defecto - Inglés (EN) - Fácilmente extensible a más idiomas ```typescript // Uso del contexto de idioma const { t, language, changeLanguage } = useLanguage();

{t('welcome')}

``` ## 💰 Sistema de Pagos Integración con múltiples pasarelas: - Stripe - PayPal - Pagos locales Gestión de: - Billetera digital integrada - Transacciones seguras - Historial y facturas - Sistema de comisiones automatizado ## 📊 Analytics y Reportes ### Métricas Disponibles - KPIs en tiempo real - Reportes financieros - Analytics de usuarios - Tasa de conversión - Ocupación y reservas - Ventas y rendimiento ### Visualizaciones - Gráficos de línea y barra - Mapas de calor - Tablas interactivas - Exportación a PDF/Excel ## 🗺️ Integración de Mapas Google Maps integrado para: - Geolocalización de servicios - Geofences y alertas - Navegación en tiempo real - Tracking de vehículos - Puntos de interés (POI) ## 📱 Responsive Design Diseño completamente responsive: - Mobile-first approach - Breakpoints: sm, md, lg, xl, 2xl - Touch-friendly interfaces - PWA capabilities ## 🔌 API Endpoints ### Base URL ``` https://karibeo.lesoluciones.net:8443/api/v1 ``` ### Endpoints Principales #### Autenticación ```typescript POST /auth/login POST /auth/register POST /auth/refresh GET /auth/profile ``` #### Usuarios ```typescript GET /admin/users POST /admin/users PUT /admin/users/:id DELETE /admin/users/:id ``` #### Reservas ```typescript GET /reservations POST /reservations PUT /reservations/:id DELETE /reservations/:id ``` #### Establecimientos ```typescript GET /establishments POST /establishments GET /establishments/:id ``` ## 🧪 Testing ```bash # Ejecutar tests npm run test # Coverage npm run test:coverage ``` ## 📦 Deployment ### Build de Producción ```bash npm run build ``` Los archivos se generarán en `/dist` ### Deploy en Lovable 1. Ir a [Lovable Project](https://lovable.dev/projects/0a15968a-5628-423b-852e-32fae49619db) 2. Click en **Share → Publish** 3. Configurar dominio personalizado (opcional) ### Deploy en Otros Servicios - **Vercel**: `vercel deploy` - **Netlify**: Conectar repositorio GitHub - **AWS S3**: Subir carpeta `/dist` ## 🔧 Configuración Avanzada ### Variables de Entorno ```env VITE_API_BASE_URL=https://karibeo.lesoluciones.net:8443/api/v1 VITE_GOOGLE_MAPS_API_KEY=tu_api_key VITE_STRIPE_PUBLIC_KEY=tu_stripe_key ``` ### Tailwind Design Tokens Sistema de diseño centralizado en `index.css`: - Variables CSS personalizadas - Tema claro/oscuro - Gradientes y sombras - Animaciones ## 🤝 Contribución ### Workflow 1. Fork el proyecto 2. Crear feature branch (`git checkout -b feature/AmazingFeature`) 3. Commit cambios (`git commit -m 'Add: AmazingFeature'`) 4. Push al branch (`git push origin feature/AmazingFeature`) 5. Abrir Pull Request ### Convenciones de Código - **TypeScript** estricto - **ESLint** para linting - **Prettier** para formateo - Commits semánticos (feat, fix, docs, style, refactor, test, chore) ## 📄 Licencia Este proyecto está bajo la licencia MIT. Ver archivo [LICENSE](LICENSE) para más detalles. ## 🆘 Soporte - **Documentación**: [docs.karibeo.com](https://docs.karibeo.com) - **Issues**: [GitHub Issues](https://github.com/tu-usuario/karibeo/issues) - **Email**: soporte@karibeo.com - **Discord**: [Comunidad Karibeo](https://discord.gg/karibeo) ## 🙏 Agradecimientos - [shadcn/ui](https://ui.shadcn.com/) por los componentes UI - [Lucide](https://lucide.dev/) por los iconos - [React Icons](https://react-icons.github.io/react-icons/) por iconos adicionales - Comunidad de código abierto --- **Desarrollado con ❤️ para la industria turística del Caribe** **Versión**: 1.0.0 **Última actualización**: 2025-01-12