diff --git a/README.md b/README.md index 7fc07dc..ff0306b 100644 --- a/README.md +++ b/README.md @@ -1,73 +1,368 @@ -# Welcome to your Lovable project +# 🌴 Karibeo - Tourism & Business Management Platform -## Project info +[![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) -**URL**: https://lovable.dev/projects/0a15968a-5628-423b-852e-32fae49619db +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. -## How can I edit this code? +## 🚀 Características Principales -There are several ways of editing your application. +### 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 -**Use Lovable** +### Para Negocios 💼 -Simply visit the [Lovable Project](https://lovable.dev/projects/0a15968a-5628-423b-852e-32fae49619db) and start prompting. +#### 🏨 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 -Changes made via Lovable will be committed automatically to this repo. +#### 🍽️ 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 -**Use your preferred IDE** +#### 🏪 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 -If you want to work locally using your own IDE, you can clone this repo and push changes. Pushed changes will also be reflected in Lovable. +### 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 -The only requirement is having Node.js & npm installed - [install with nvm](https://github.com/nvm-sh/nvm#installing-and-updating) +### 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 -Follow these steps: +## 🛠️ Stack Tecnológico -```sh -# Step 1: Clone the repository using the project's Git URL. -git clone +### 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 -# Step 2: Navigate to the project directory. -cd - -# Step 3: Install the necessary dependencies. -npm i - -# Step 4: Start the development server with auto-reloading and an instant preview. -npm run dev +### 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" +} ``` -**Edit a file directly in GitHub** +## 📁 Estructura del Proyecto -- Navigate to the desired file(s). -- Click the "Edit" button (pencil icon) at the top right of the file view. -- Make your changes and commit the changes. +``` +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 +``` -**Use GitHub Codespaces** +## 🚦 Instalación y Configuración -- Navigate to the main page of your repository. -- Click on the "Code" button (green button) near the top right. -- Select the "Codespaces" tab. -- Click on "New codespace" to launch a new Codespace environment. -- Edit files directly within the Codespace and commit and push your changes once you're done. +### Prerrequisitos +- Node.js 18+ (recomendado usar [nvm](https://github.com/nvm-sh/nvm)) +- npm o yarn -## What technologies are used for this project? +### Instalación Local -This project is built with: +```bash +# 1. Clonar el repositorio +git clone https://github.com/tu-usuario/karibeo.git +cd karibeo -- Vite -- TypeScript -- React -- shadcn-ui -- Tailwind CSS +# 2. Instalar dependencias +npm install -## How can I deploy this project? +# 3. Configurar variables de entorno +# Crear archivo .env en la raíz (ver sección de Configuración) -Simply open [Lovable](https://lovable.dev/projects/0a15968a-5628-423b-852e-32fae49619db) and click on Share -> Publish. +# 4. Iniciar servidor de desarrollo +npm run dev -## Can I connect a custom domain to my Lovable project? +# El proyecto estará disponible en http://localhost:5173 +``` -Yes, you can! +### Scripts Disponibles -To connect a domain, navigate to Project > Settings > Domains and click Connect Domain. +```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 +``` -Read more here: [Setting up a custom domain](https://docs.lovable.dev/tips-tricks/custom-domain#step-by-step-guide) +## 🔐 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 \ No newline at end of file diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 0000000..b12d8c7 --- /dev/null +++ b/docs/API.md @@ -0,0 +1,729 @@ +# 📡 Documentación de API - Karibeo + +## Base URL + +``` +https://karibeo.lesoluciones.net:8443/api/v1 +``` + +## Autenticación + +Todos los endpoints protegidos requieren un token JWT en el header: + +```http +Authorization: Bearer +``` + +### Obtener Token + +```http +POST /auth/login +Content-Type: application/json + +{ + "email": "user@example.com", + "password": "securepassword" +} +``` + +**Respuesta**: +```json +{ + "token": "eyJhbGciOiJIUzI1NiIs...", + "refreshToken": "eyJhbGciOiJIUzI1NiIs...", + "user": { + "id": "uuid", + "email": "user@example.com", + "name": "User Name", + "role": "admin" + } +} +``` + +### Refresh Token + +```http +POST /auth/refresh +Content-Type: application/json + +{ + "refreshToken": "eyJhbGciOiJIUzI1NiIs..." +} +``` + +## Endpoints + +### Autenticación + +#### POST /auth/register +Registrar nuevo usuario + +**Body**: +```json +{ + "name": "John Doe", + "email": "john@example.com", + "password": "SecurePass123!", + "type": "tourist", + "location": { + "lat": 18.4861, + "lng": -69.9312 + }, + "preferences": { + "language": "es" + } +} +``` + +#### GET /auth/profile +Obtener perfil del usuario autenticado + +**Respuesta**: +```json +{ + "id": "uuid", + "email": "john@example.com", + "name": "John Doe", + "role": "tourist", + "avatar": "https://...", + "wallet": { + "balance": 150.50, + "currency": "USD" + } +} +``` + +### Usuarios (Admin) + +#### GET /admin/users +Listar todos los usuarios + +**Query Parameters**: +- `page` (int): Número de página (default: 1) +- `limit` (int): Items por página (default: 10) +- `role` (string): Filtrar por rol + +**Respuesta**: +```json +{ + "data": [ + { + "id": "uuid", + "name": "User Name", + "email": "user@example.com", + "role": "tourist", + "status": "active", + "verified": true, + "createdAt": "2024-01-15T10:30:00Z" + } + ], + "pagination": { + "total": 100, + "page": 1, + "pages": 10 + } +} +``` + +#### POST /admin/users +Crear nuevo usuario + +#### PUT /admin/users/:id +Actualizar usuario + +#### DELETE /admin/users/:id +Eliminar usuario + +### Establecimientos + +#### GET /establishments +Listar establecimientos + +**Query Parameters**: +- `type` (string): hotel, restaurant, commerce +- `page` (int) +- `limit` (int) +- `latitude` (float): Para búsqueda geográfica +- `longitude` (float) +- `radius` (float): Radio en km + +**Respuesta**: +```json +{ + "data": [ + { + "id": "uuid", + "name": "Hotel Paradise", + "type": "hotel", + "rating": 4.5, + "location": { + "latitude": 18.4861, + "longitude": -69.9312, + "address": "Calle Principal #123" + }, + "amenities": ["wifi", "pool", "restaurant"], + "priceRange": "$$", + "verified": true + } + ] +} +``` + +#### POST /establishments +Crear nuevo establecimiento + +**Body**: +```json +{ + "name": "My Hotel", + "type": "hotel", + "description": "Beautiful hotel...", + "location": { + "latitude": 18.4861, + "longitude": -69.9312, + "address": "Street 123" + }, + "amenities": ["wifi", "pool"], + "priceRange": "$$", + "images": ["url1", "url2"] +} +``` + +#### GET /establishments/:id +Obtener detalles de establecimiento + +#### PUT /establishments/:id +Actualizar establecimiento + +#### DELETE /establishments/:id +Eliminar establecimiento + +### Reservas + +#### GET /reservations +Listar reservas del usuario + +**Respuesta**: +```json +{ + "data": [ + { + "id": "uuid", + "establishmentId": "uuid", + "type": "hotel", + "checkInDate": "2024-03-15", + "checkOutDate": "2024-03-20", + "guestsCount": 2, + "totalAmount": 500.00, + "status": "confirmed", + "createdAt": "2024-01-10T10:00:00Z" + } + ] +} +``` + +#### POST /reservations +Crear nueva reserva + +**Body**: +```json +{ + "establishmentId": "uuid", + "type": "hotel", + "checkInDate": "2024-03-15", + "checkOutDate": "2024-03-20", + "guestsCount": 2, + "specialRequests": "Late check-in", + "contactInfo": { + "phone": "+1234567890", + "email": "guest@example.com" + } +} +``` + +#### PUT /reservations/:id +Actualizar reserva + +#### DELETE /reservations/:id +Cancelar reserva + +### Reseñas + +#### GET /reviews +Obtener reseñas + +**Query Parameters**: +- `establishmentId` (string): Filtrar por establecimiento +- `userId` (string): Filtrar por usuario +- `rating` (int): Filtrar por calificación + +**Respuesta**: +```json +{ + "data": [ + { + "id": "uuid", + "establishmentId": "uuid", + "userId": "uuid", + "userName": "John Doe", + "rating": 5, + "comment": "Excellent service!", + "images": ["url1", "url2"], + "createdAt": "2024-01-15T10:00:00Z", + "helpful": 12 + } + ], + "stats": { + "averageRating": 4.5, + "totalReviews": 150 + } +} +``` + +#### POST /reviews +Crear reseña + +**Body**: +```json +{ + "establishmentId": "uuid", + "rating": 5, + "comment": "Great experience!", + "images": ["url1", "url2"] +} +``` + +### Destinos + +#### GET /destinations +Listar destinos turísticos + +**Respuesta**: +```json +{ + "data": [ + { + "id": "uuid", + "name": "Punta Cana", + "description": "Beautiful beaches...", + "country": "Dominican Republic", + "images": ["url1", "url2"], + "highlights": ["beaches", "resorts", "nightlife"], + "bestTimeToVisit": "December-April", + "popularActivities": ["snorkeling", "golf"] + } + ] +} +``` + +#### GET /destinations/:id +Detalles de destino + +### Lugares + +#### GET /places +Listar lugares de interés + +**Query Parameters**: +- `destinationId` (string) +- `category` (string): restaurant, attraction, shopping +- `latitude`, `longitude`, `radius` + +**Respuesta**: +```json +{ + "data": [ + { + "id": "uuid", + "name": "Historic Site", + "category": "attraction", + "description": "...", + "location": {...}, + "openingHours": { + "monday": "9:00-18:00", + "tuesday": "9:00-18:00" + }, + "entryFee": 10.00, + "rating": 4.5 + } + ] +} +``` + +### Emergencias (POLITUR) + +#### GET /emergency/incidents +Listar incidentes + +**Requiere**: Rol de `politur`, `admin` o `super_admin` + +**Respuesta**: +```json +{ + "incidents": [ + { + "id": "uuid", + "type": "medical", + "severity": "high", + "location": {...}, + "description": "...", + "status": "active", + "reportedBy": "uuid", + "assignedOfficer": "uuid", + "createdAt": "2024-01-15T10:00:00Z" + } + ] +} +``` + +#### POST /emergency/incidents +Reportar incidente + +#### GET /emergency/alerts +Obtener alertas activas + +#### POST /emergency/panic-button +Activar botón de pánico + +**Body**: +```json +{ + "location": { + "latitude": 18.4861, + "longitude": -69.9312 + }, + "details": "Emergency description" +} +``` + +### Channel Manager + +#### GET /channel-manager/channels +Listar canales conectados + +**Respuesta**: +```json +{ + "channels": [ + { + "id": "booking", + "name": "Booking.com", + "status": "active", + "connected": true, + "listingsCount": 5, + "lastSync": "2024-01-15T10:00:00Z" + } + ] +} +``` + +#### POST /channel-manager/sync +Sincronizar con canales + +#### GET /channel-manager/listings +Listar propiedades + +#### POST /channel-manager/listings +Crear nueva propiedad + +### Comisiones + +#### GET /commissions/rules +Obtener reglas de comisiones + +**Respuesta**: +```json +{ + "rules": [ + { + "id": "uuid", + "type": "percentage", + "value": 15, + "entityType": "hotel", + "conditions": { + "minAmount": 100 + }, + "active": true + } + ] +} +``` + +#### POST /commissions/rules +Crear regla de comisión + +#### GET /commissions/payments +Historial de pagos de comisiones + +### CRM + +#### GET /crm/contacts +Listar contactos + +**Respuesta**: +```json +{ + "contacts": [ + { + "id": "uuid", + "firstName": "John", + "lastName": "Doe", + "email": "john@example.com", + "phone": "+1234567890", + "segment": "VIP Travelers", + "tags": ["repeat_customer"], + "lastInteraction": "2024-01-15T10:00:00Z", + "totalSpent": 5000.00 + } + ] +} +``` + +#### POST /crm/contacts +Crear contacto + +#### GET /crm/campaigns +Listar campañas + +#### POST /crm/campaigns +Crear campaña de marketing + +### Analytics + +#### GET /analytics/dashboard +Obtener métricas del dashboard + +**Respuesta**: +```json +{ + "stats": { + "totalUsers": 1500, + "totalRevenue": 156750.50, + "totalBookings": 892, + "activeServices": 89, + "monthlyGrowth": 8.5, + "conversionRate": 3.2 + }, + "charts": { + "revenueByMonth": [...], + "bookingsByType": [...], + "topDestinations": [...] + } +} +``` + +#### GET /analytics/reports +Generar reportes personalizados + +**Query Parameters**: +- `type` (string): revenue, bookings, users +- `startDate` (date) +- `endDate` (date) +- `format` (string): json, csv, pdf + +### Configuración + +#### GET /config/apis +Obtener configuración de APIs externas + +#### PUT /config/apis +Actualizar configuración de APIs + +#### GET /config/parameters +Obtener parámetros del sistema + +#### GET /config/integrations +Listar integraciones activas + +### Pagos + +#### POST /payments/create-intent +Crear intención de pago + +**Body**: +```json +{ + "amount": 100.00, + "currency": "USD", + "description": "Hotel booking", + "metadata": { + "bookingId": "uuid" + } +} +``` + +**Respuesta**: +```json +{ + "clientSecret": "pi_xxx_secret_xxx", + "paymentIntentId": "pi_xxx" +} +``` + +#### POST /payments/confirm +Confirmar pago + +#### GET /payments/history +Historial de pagos + +### Uploads + +#### POST /upload +Subir archivo único + +**Form Data**: +- `file`: Archivo binario +- `folder`: Carpeta destino (opcional) + +**Respuesta**: +```json +{ + "url": "https://cdn.karibeo.com/uploads/xxx.jpg", + "fileName": "xxx.jpg", + "size": 102400, + "mimeType": "image/jpeg" +} +``` + +#### POST /upload/multiple +Subir múltiples archivos + +## Códigos de Estado + +| Código | Descripción | +|--------|-------------| +| 200 | OK - Solicitud exitosa | +| 201 | Created - Recurso creado | +| 400 | Bad Request - Datos inválidos | +| 401 | Unauthorized - Token inválido o expirado | +| 403 | Forbidden - Sin permisos | +| 404 | Not Found - Recurso no encontrado | +| 409 | Conflict - Conflicto (ej: email duplicado) | +| 422 | Unprocessable Entity - Validación fallida | +| 429 | Too Many Requests - Rate limit excedido | +| 500 | Internal Server Error - Error del servidor | + +## Rate Limiting + +- **Anónimos**: 100 requests / hora +- **Autenticados**: 1000 requests / hora +- **Admin**: 5000 requests / hora + +Headers de respuesta: +```http +X-RateLimit-Limit: 1000 +X-RateLimit-Remaining: 999 +X-RateLimit-Reset: 1640000000 +``` + +## Paginación + +Endpoints que retornan listas soportan paginación: + +**Query Parameters**: +- `page`: Número de página (default: 1) +- `limit`: Items por página (default: 10, max: 100) + +**Respuesta**: +```json +{ + "data": [...], + "pagination": { + "total": 250, + "page": 1, + "pages": 25, + "limit": 10 + } +} +``` + +## Filtros y Ordenamiento + +**Query Parameters**: +- `sort`: Campo para ordenar +- `order`: asc o desc +- `filter[campo]`: Filtrar por campo + +Ejemplo: +``` +GET /establishments?sort=rating&order=desc&filter[type]=hotel +``` + +## Webhooks + +Para eventos en tiempo real, el sistema soporta webhooks: + +```http +POST /webhooks/configure +Content-Type: application/json + +{ + "url": "https://your-domain.com/webhook", + "events": ["booking.created", "payment.completed"], + "secret": "your_webhook_secret" +} +``` + +Eventos disponibles: +- `booking.created` +- `booking.confirmed` +- `booking.cancelled` +- `payment.completed` +- `payment.failed` +- `review.created` +- `user.registered` + +## SDKs y Libraries + +### JavaScript/TypeScript +```bash +npm install @karibeo/sdk +``` + +```typescript +import Karibeo from '@karibeo/sdk'; + +const client = new Karibeo({ + apiKey: 'your_api_key', + baseUrl: 'https://karibeo.lesoluciones.net:8443/api/v1' +}); + +const bookings = await client.reservations.list(); +``` + +### Python +```bash +pip install karibeo +``` + +```python +from karibeo import Client + +client = Client(api_key='your_api_key') +bookings = client.reservations.list() +``` + +## Postman Collection + +Importar colección completa: +``` +https://www.postman.com/karibeo/workspace/karibeo-api +``` + +## Testing + +### Credenciales de Testing +``` +Email: test@karibeo.com +Password: Test123! +``` + +### Endpoints de Testing +``` +https://karibeo-staging.lesoluciones.net:8443/api/v1 +``` + +--- + +**Soporte**: api-support@karibeo.com +**Última actualización**: 2025-01-12 \ No newline at end of file diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..cd05938 --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,428 @@ +# 🏗️ Arquitectura del Sistema Karibeo + +## Visión General + +Karibeo está construido siguiendo una arquitectura modular de frontend con separación clara de responsabilidades y patrones de diseño modernos. + +## Diagrama de Arquitectura + +``` +┌─────────────────────────────────────────────────────────────┐ +│ PRESENTACIÓN │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ Tourist │ │ Hotel │ │Restaurant│ │ Commerce │ │ +│ │ App │ │ POS │ │ POS │ │ POS │ │ +│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ Admin Dashboard & Control Panel │ │ +│ └──────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ CAPA DE NEGOCIO │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ Contexts │ │ Hooks │ │ Services │ │Validation│ │ +│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ CAPA DE DATOS │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ API │ │ Cache │ │ LocalSt │ │ State │ │ +│ │ Client │ │(TanStack)│ │ (tokens) │ │Management│ │ +│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ BACKEND API REST │ +│ https://karibeo.lesoluciones.net:8443/api/v1 │ +└─────────────────────────────────────────────────────────────┘ +``` + +## Capas de la Aplicación + +### 1. Capa de Presentación (UI) + +#### Componentes Principales +``` +src/components/ +├── ui/ # Componentes base (shadcn) +├── admin/ # Componentes administrativos +├── hotel/ # Componentes hoteleros +├── restaurant/ # Componentes de restaurante +├── tourist/ # Componentes para turistas +└── shared/ # Componentes compartidos +``` + +**Responsabilidades**: +- Renderizado de UI +- Interacción con el usuario +- Delegación de lógica a hooks y contexts + +**Patrones Utilizados**: +- **Composition Pattern**: Composición de componentes pequeños +- **Compound Components**: Para componentes complejos como Forms +- **Render Props**: Para lógica reutilizable + +### 2. Capa de Lógica de Negocio + +#### React Contexts +```typescript +src/contexts/ +├── AuthContext.tsx # Autenticación y sesión +├── CartContext.tsx # Carrito de compras +├── CurrencyContext.tsx # Gestión de monedas +└── LanguageContext.tsx # Internacionalización +``` + +**Responsabilidades**: +- Estado global de la aplicación +- Lógica de negocio compartida +- Sincronización de estado + +#### Custom Hooks +```typescript +src/hooks/ +├── useAdminData.ts # Datos de administración +├── useBooking.ts # Lógica de reservas +├── useChannelManager.ts # Channel manager +├── useRolesPermissions.ts # Roles y permisos +└── useEmergencyData.ts # Sistema de emergencias +``` + +**Responsabilidades**: +- Encapsular lógica reutilizable +- Gestión de efectos secundarios +- Integración con APIs + +### 3. Capa de Servicios (API) + +#### Servicios API +```typescript +src/services/ +├── adminApi.ts # API de administración +├── emergencyApi.ts # API de emergencias +├── bookmarkApi.ts # API de favoritos +├── chatApi.ts # API de mensajería +├── configApi.ts # API de configuración +├── paymentService.ts # Servicio de pagos +├── reviewService.ts # Servicio de reseñas +└── tourismService.ts # Servicios turísticos +``` + +**ApiClient Class**: +```typescript +class ApiClient { + - baseUrl: string + - request(endpoint, options): Promise + + get(endpoint): Promise + + post(endpoint, data): Promise + + put(endpoint, data): Promise + + delete(endpoint): Promise + + postForm(endpoint, data): Promise +} +``` + +**Características**: +- Interceptores de request/response +- Refresh token automático +- Manejo centralizado de errores +- Timeout configurable (30s) +- Retry logic para 401 errors + +### 4. Capa de Validación + +```typescript +src/lib/validation.ts +``` + +**Schemas Zod**: +- `loginSchema`: Validación de login +- `registerSchema`: Validación de registro +- `profileUpdateSchema`: Actualización de perfil +- `contactFormSchema`: Formularios de contacto +- `reviewSchema`: Validación de reseñas +- `searchSchema`: Validación de búsquedas + +## Flujo de Datos + +### Flujo de Autenticación + +``` +┌─────────┐ ┌──────────────┐ ┌────────────┐ +│ SignIn │───────>│ AuthContext │───────>│ adminApi │ +│ Form │ submit │ .login() │ POST │ /auth/login│ +└─────────┘ └──────────────┘ └────────────┘ + │ │ + │ ▼ + │ ┌────────────┐ + │<───────────────│ Backend │ + │ JWT Token │ API │ + │ └────────────┘ + ▼ + ┌─────────────┐ + │ localStorage │ + │ - token │ + │ - user data │ + └─────────────┘ +``` + +### Flujo de Reservas + +``` +┌──────────┐ ┌──────────────┐ ┌────────────┐ +│ Booking │───────>│ useBooking │───────>│ bookingApi │ +│ Form │ submit │ hook │ POST │/reservations│ +└──────────┘ └──────────────┘ └────────────┘ + │ │ + │ ▼ + │ ┌────────────┐ + │<───────────────│ Backend │ + │ Confirmation │ API │ + │ └────────────┘ + ▼ + ┌─────────────┐ + │ TanStack │ + │ Query │ + │ Cache │ + └─────────────┘ +``` + +## Gestión de Estado + +### Estado Local (Component State) +```typescript +const [formData, setFormData] = useState({...}); +``` +**Uso**: Estado temporal de componentes individuales + +### Estado Global (Context) +```typescript +const { user, login, logout } = useAuth(); +``` +**Uso**: Estado compartido entre múltiples componentes + +### Estado del Servidor (TanStack Query) +```typescript +const { data, isLoading } = useQuery({ + queryKey: ['users'], + queryFn: () => adminApi.getAllUsers() +}); +``` +**Uso**: Cache y sincronización de datos del servidor + +## Patrones de Diseño + +### 1. Container/Presentational Pattern + +```typescript +// Container (lógica) +const UsersContainer = () => { + const { users, loading } = useAdminData(); + return ; +}; + +// Presentational (UI) +const UsersList = ({ users, loading }) => { + if (loading) return ; + return
{users.map(...)}
; +}; +``` + +### 2. Compound Components Pattern + +```typescript +
+ + Email + + + +
+``` + +### 3. Custom Hook Pattern + +```typescript +const useBooking = () => { + const [bookings, setBookings] = useState([]); + const createBooking = async (data) => {...}; + return { bookings, createBooking }; +}; +``` + +### 4. Higher-Order Component (HOC) Pattern + +```typescript +const ProtectedRoute = ({ children }) => { + const { isAuthenticated } = useAuth(); + return isAuthenticated ? children : ; +}; +``` + +## Estrategia de Routing + +### Estructura de Rutas + +``` +/ # Landing page +/sign-in # Login +/sign-up # Registro +/explore # Exploración pública +/listing-details/:id # Detalles de listado + +/dashboard # Dashboard principal (turista) +/dashboard/admin # Panel de administración +/dashboard/admin?tab=... # Tabs de administración + +/dashboard/hotel/* # Rutas hoteleras +/dashboard/restaurant/* # Rutas de restaurante +/dashboard/commerce/* # Rutas de comercio + +/dashboard/roles-permissions # Gestión de roles +/dashboard/crm/* # CRM +/dashboard/commissions/* # Comisiones +``` + +### Protección de Rutas + +```typescript +}> + } /> + +``` + +## Optimizaciones de Performance + +### Code Splitting +```typescript +const AdminDashboard = lazy(() => import('./pages/AdminDashboard')); +``` + +### Memoization +```typescript +const MemoizedComponent = memo(ExpensiveComponent); +const memoizedValue = useMemo(() => computeExpensiveValue(a, b), [a, b]); +const memoizedCallback = useCallback(() => doSomething(a, b), [a, b]); +``` + +### Virtual Scrolling +Para listas largas de datos (usuarios, reservas, etc.) + +### Image Optimization +- Lazy loading con `loading="lazy"` +- Formatos modernos (WebP) +- Responsive images + +## Seguridad + +### Medidas Implementadas + +1. **Validación de Inputs**: Todos los formularios usan Zod +2. **Sanitización**: Prevención de XSS +3. **HTTPS Only**: Todas las comunicaciones encriptadas +4. **JWT Tokens**: Autenticación stateless +5. **Refresh Tokens**: Rotación automática +6. **CORS**: Configurado en backend +7. **Rate Limiting**: En endpoints críticos + +### Consideraciones de Seguridad + +⚠️ **IMPORTANTE**: La verificación de roles actual es client-side. Para producción se requiere: +- Tabla `user_roles` separada en la base de datos +- Verificación de permisos en cada endpoint del backend +- Row Level Security (RLS) policies + +## Escalabilidad + +### Preparación para Escala + +1. **Modularización**: Código organizado en módulos independientes +2. **Lazy Loading**: Carga diferida de componentes +3. **API Caching**: TanStack Query con estrategias de cache +4. **CDN Ready**: Assets estáticos optimizados +5. **Micro-frontends Ready**: Arquitectura permite separación futura + +### Métricas de Performance + +- **First Contentful Paint**: < 1.5s +- **Time to Interactive**: < 3.5s +- **Bundle Size**: ~500KB (gzipped) + +## Testing Strategy + +### Unit Tests +```typescript +describe('useAuth', () => { + it('should login successfully', async () => { + // test implementation + }); +}); +``` + +### Integration Tests +```typescript +describe('BookingFlow', () => { + it('should complete booking', async () => { + // test implementation + }); +}); +``` + +### E2E Tests (Cypress/Playwright) +```typescript +describe('Complete User Journey', () => { + it('should allow user to make a reservation', () => { + // test implementation + }); +}); +``` + +## Monitoring y Observabilidad + +### Logs +- Console logs en desarrollo +- Sentry/LogRocket en producción + +### Analytics +- Google Analytics 4 +- Custom events tracking +- User behavior analysis + +### Error Tracking +- Error boundaries en componentes críticos +- Reportes automáticos a Sentry + +## Deployment Pipeline + +``` +┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ +│ Git │───>│ Build │───>│ Test │───>│ Deploy │ +│ Commit │ │ (Vite) │ │ (Jest) │ │(Lovable) │ +└──────────┘ └──────────┘ └──────────┘ └──────────┘ +``` + +## Roadmap Técnico + +### Corto Plazo (3 meses) +- [ ] Implementar testing completo +- [ ] Optimizar bundle size +- [ ] Mejorar accesibilidad (WCAG 2.1 AA) +- [ ] Implementar PWA completa + +### Medio Plazo (6 meses) +- [ ] Migrar a Server Components (React 19) +- [ ] Implementar GraphQL +- [ ] WebSockets para real-time +- [ ] Backend propio (Node.js/NestJS) + +### Largo Plazo (12 meses) +- [ ] Micro-frontends architecture +- [ ] Mobile apps (React Native) +- [ ] AI/ML integration +- [ ] Blockchain para pagos + +--- + +**Última actualización**: 2025-01-12 +**Mantenedores**: Equipo de Desarrollo Karibeo \ No newline at end of file diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md new file mode 100644 index 0000000..6f6b019 --- /dev/null +++ b/docs/DEVELOPMENT.md @@ -0,0 +1,608 @@ +# 🛠️ Guía de Desarrollo - Karibeo + +## Configuración del Entorno + +### Requisitos del Sistema + +- **Node.js**: >= 18.0.0 (recomendado 20.x LTS) +- **npm**: >= 9.0.0 o **yarn**: >= 1.22.0 +- **Git**: >= 2.30.0 +- **Editor**: VSCode (recomendado) con extensiones + +### Extensiones VSCode Recomendadas + +```json +{ + "recommendations": [ + "dbaeumer.vscode-eslint", + "esbenp.prettier-vscode", + "bradlc.vscode-tailwindcss", + "formulahendry.auto-rename-tag", + "christian-kohler.path-intellisense", + "dsznajder.es7-react-js-snippets", + "mikestead.dotenv" + ] +} +``` + +## Setup Inicial + +### 1. Clonar el Repositorio + +```bash +git clone https://github.com/tu-usuario/karibeo.git +cd karibeo +``` + +### 2. Instalar Dependencias + +```bash +npm install +# o +yarn install +``` + +### 3. Configurar Variables de Entorno + +Crear archivo `.env` en la raíz: + +```env +# API Backend +VITE_API_BASE_URL=https://karibeo.lesoluciones.net:8443/api/v1 + +# Google Maps +VITE_GOOGLE_MAPS_API_KEY=your_google_maps_api_key + +# Stripe (Pagos) +VITE_STRIPE_PUBLIC_KEY=pk_test_... + +# Analytics (Opcional) +VITE_GA_ID=G-XXXXXXXXXX + +# Sentry (Error Tracking - Opcional) +VITE_SENTRY_DSN=https://...@sentry.io/... + +# Feature Flags (Opcional) +VITE_ENABLE_ANALYTICS=true +VITE_ENABLE_PWA=false +``` + +### 4. Iniciar Servidor de Desarrollo + +```bash +npm run dev +``` + +La aplicación estará disponible en: `http://localhost:5173` + +## Estructura de Carpetas Detallada + +``` +karibeo/ +├── .vscode/ # Configuración de VSCode +│ ├── settings.json # Configuraciones del workspace +│ └── extensions.json # Extensiones recomendadas +│ +├── docs/ # Documentación +│ ├── API.md # Documentación de API +│ ├── ARCHITECTURE.md # Arquitectura del sistema +│ └── DEVELOPMENT.md # Esta guía +│ +├── public/ # Assets estáticos +│ ├── favicon.ico +│ ├── manifest.json # PWA manifest +│ └── robots.txt +│ +├── src/ +│ ├── assets/ # Recursos (imágenes, fonts) +│ │ ├── images/ +│ │ └── fonts/ +│ │ +│ ├── components/ # Componentes React +│ │ ├── ui/ # Componentes base (shadcn) +│ │ │ ├── button.tsx +│ │ │ ├── input.tsx +│ │ │ └── ... +│ │ │ +│ │ ├── admin/ # Componentes de admin +│ │ │ ├── ConfigTab.tsx +│ │ │ ├── UsersTab.tsx +│ │ │ └── ... +│ │ │ +│ │ ├── hotel/ # Componentes hoteleros +│ │ ├── restaurant/ # Componentes de restaurante +│ │ ├── roles/ # Sistema de roles +│ │ ├── security/ # Componentes de seguridad +│ │ └── shared/ # Componentes compartidos +│ │ +│ ├── contexts/ # React Contexts +│ │ ├── AuthContext.tsx +│ │ ├── CartContext.tsx +│ │ ├── CurrencyContext.tsx +│ │ └── LanguageContext.tsx +│ │ +│ ├── hooks/ # Custom Hooks +│ │ ├── useAdminData.ts +│ │ ├── useBooking.ts +│ │ ├── useChannelManager.ts +│ │ └── ... +│ │ +│ ├── lib/ # Utilidades y helpers +│ │ ├── utils.ts # Funciones utilitarias +│ │ └── validation.ts # Schemas de validación +│ │ +│ ├── pages/ # Páginas/Rutas +│ │ ├── dashboard/ # Panel de control +│ │ │ ├── AdminDashboard.tsx +│ │ │ ├── Dashboard.tsx +│ │ │ └── ... +│ │ │ +│ │ ├── Index.tsx # Landing page +│ │ ├── SignIn.tsx # Login +│ │ └── SignUp.tsx # Registro +│ │ +│ ├── services/ # Servicios API +│ │ ├── adminApi.ts +│ │ ├── emergencyApi.ts +│ │ └── ... +│ │ +│ ├── types/ # TypeScript types +│ │ ├── index.ts +│ │ └── roles.ts +│ │ +│ ├── i18n/ # Internacionalización +│ │ ├── en.ts +│ │ └── es.ts +│ │ +│ ├── App.tsx # Componente principal +│ ├── main.tsx # Entry point +│ └── index.css # Estilos globales +│ +├── .eslintrc.js # Configuración ESLint +├── .prettierrc # Configuración Prettier +├── tailwind.config.ts # Configuración Tailwind +├── tsconfig.json # Configuración TypeScript +├── vite.config.ts # Configuración Vite +└── package.json # Dependencias y scripts +``` + +## Convenciones de Código + +### Nomenclatura + +#### Archivos +```typescript +// PascalCase para componentes +UserProfile.tsx +AdminDashboard.tsx + +// camelCase para utilidades y hooks +useAuth.ts +formatCurrency.ts + +// kebab-case para estilos +user-profile.css +``` + +#### Variables y Funciones +```typescript +// camelCase para variables y funciones +const userName = "John"; +function getUserData() {} + +// PascalCase para componentes y clases +const UserCard = () => {}; +class ApiClient {} + +// UPPER_SNAKE_CASE para constantes +const MAX_RETRY_ATTEMPTS = 3; +const API_BASE_URL = "https://..."; +``` + +#### Interfaces y Types +```typescript +// PascalCase con prefijo "I" opcional +interface UserProfile {} +interface IUserProfile {} // alternativa + +type UserRole = 'admin' | 'user'; +``` + +### Formato de Código + +#### Imports +```typescript +// 1. Imports de librerías externas +import React, { useState, useEffect } from 'react'; +import { useNavigate } from 'react-router-dom'; + +// 2. Imports de componentes UI +import { Button } from '@/components/ui/button'; +import { Input } from '@/components/ui/input'; + +// 3. Imports de componentes propios +import { UserCard } from '@/components/UserCard'; + +// 4. Imports de hooks y contexts +import { useAuth } from '@/contexts/AuthContext'; +import { useAdminData } from '@/hooks/useAdminData'; + +// 5. Imports de utilidades y tipos +import { cn } from '@/lib/utils'; +import type { User } from '@/types'; + +// 6. Imports de assets +import logo from '@/assets/logo.png'; + +// 7. Imports de estilos +import './styles.css'; +``` + +#### Componentes Funcionales +```typescript +// Buena práctica +interface UserCardProps { + user: User; + onEdit?: (id: string) => void; + className?: string; +} + +export const UserCard: React.FC = ({ + user, + onEdit, + className +}) => { + const [isExpanded, setIsExpanded] = useState(false); + + useEffect(() => { + // Effect logic + }, []); + + const handleClick = () => { + setIsExpanded(!isExpanded); + }; + + return ( +
+ {/* JSX */} +
+ ); +}; +``` + +### TypeScript + +#### Tipado Estricto +```typescript +// ✅ Bueno +interface User { + id: string; + name: string; + email: string; +} + +const getUser = (id: string): Promise => { + return api.get(`/users/${id}`); +}; + +// ❌ Evitar +const getUser = (id: any): any => { + return api.get(`/users/${id}`); +}; +``` + +#### Usar Interfaces sobre Types +```typescript +// ✅ Preferido para objetos +interface UserProfile { + name: string; + age: number; +} + +// ✅ Usar type para unions, intersections +type UserRole = 'admin' | 'user' | 'guest'; +type ExtendedUser = UserProfile & { role: UserRole }; +``` + +### React Patterns + +#### Hooks +```typescript +// Custom hook +export const useUser = (userId: string) => { + const [user, setUser] = useState(null); + const [loading, setLoading] = useState(true); + const [error, setError] = useState(null); + + useEffect(() => { + fetchUser(userId) + .then(setUser) + .catch(setError) + .finally(() => setLoading(false)); + }, [userId]); + + return { user, loading, error }; +}; +``` + +#### Memoization +```typescript +// useMemo para cálculos costosos +const expensiveValue = useMemo(() => { + return computeExpensiveValue(a, b); +}, [a, b]); + +// useCallback para funciones +const handleSubmit = useCallback((data: FormData) => { + submitForm(data); +}, []); + +// memo para componentes +export const UserCard = memo(({ user }: Props) => { + return
{user.name}
; +}); +``` + +### Tailwind CSS + +#### Ordenamiento de Clases +```tsx +// Orden recomendado: +// 1. Layout (display, position) +// 2. Box model (width, height, margin, padding) +// 3. Typography +// 4. Visual (background, border, shadow) +// 5. Misc (cursor, transform, transition) + +
+ Content +
+``` + +#### Usar cn() para Clases Condicionales +```tsx +import { cn } from '@/lib/utils'; + +