368 lines
10 KiB
Markdown
368 lines
10 KiB
Markdown
# 🌴 Karibeo - Tourism & Business Management Platform
|
|
|
|
[](https://reactjs.org/)
|
|
[](https://www.typescriptlang.org/)
|
|
[](https://tailwindcss.com/)
|
|
[](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();
|
|
<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
|
|
```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 |