🌴 Karibeo - Tourism & Business Management Platform

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

{
  "@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)
• npm o yarn

Instalación Local

# 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

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:

// 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

// Uso del contexto de idioma
const { t, language, changeLanguage } = useLanguage();
<h1>{t('welcome')}</h1>

💰 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

POST /auth/login
POST /auth/register
POST /auth/refresh
GET  /auth/profile

Usuarios

GET    /admin/users
POST   /admin/users
PUT    /admin/users/:id
DELETE /admin/users/:id

Reservas

GET    /reservations
POST   /reservations
PUT    /reservations/:id
DELETE /reservations/:id

Establecimientos

GET  /establishments
POST /establishments
GET  /establishments/:id

🧪 Testing

# Ejecutar tests
npm run test

# Coverage
npm run test:coverage

📦 Deployment

Build de Producción

npm run build

Los archivos se generarán en /dist

Deploy en Lovable

1. Ir a Lovable Project
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

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 para más detalles.

🆘 Soporte

• Documentación: docs.karibeo.com
• Issues: GitHub Issues
• Email: soporte@karibeo.com
• Discord: Comunidad Karibeo

🙏 Agradecimientos

• shadcn/ui por los componentes UI
• Lucide por los iconos
• 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