Refactor: Analyze project documentation
This commit is contained in:
gpt-engineer-app[bot]
387
README.md
387
README.md
@@ -1,73 +1,368 @@
|
|||||||
# Welcome to your Lovable project
|
# 🌴 Karibeo - Tourism & Business Management Platform
|
||||||
|
|
||||||
## Project info
|
[](https://reactjs.org/)
|
||||||
|
[](https://www.typescriptlang.org/)
|
||||||
|
[](https://tailwindcss.com/)
|
||||||
|
[](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
|
### Frontend
|
||||||
# Step 1: Clone the repository using the project's Git URL.
|
- **Framework**: React 18.3.1 + TypeScript
|
||||||
git clone <YOUR_GIT_URL>
|
- **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.
|
### Dependencias Clave
|
||||||
cd <YOUR_PROJECT_NAME>
|
```json
|
||||||
|
{
|
||||||
# Step 3: Install the necessary dependencies.
|
"@tanstack/react-query": "^5.83.0",
|
||||||
npm i
|
"@googlemaps/js-api-loader": "^1.16.10",
|
||||||
|
"react-hook-form": "^7.61.1",
|
||||||
# Step 4: Start the development server with auto-reloading and an instant preview.
|
"zod": "^3.25.76",
|
||||||
npm run dev
|
"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.
|
karibeo/
|
||||||
- Make your changes and commit the changes.
|
├── 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.
|
### Prerrequisitos
|
||||||
- Click on the "Code" button (green button) near the top right.
|
- Node.js 18+ (recomendado usar [nvm](https://github.com/nvm-sh/nvm))
|
||||||
- Select the "Codespaces" tab.
|
- npm o yarn
|
||||||
- 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.
|
|
||||||
|
|
||||||
## 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
|
# 2. Instalar dependencias
|
||||||
- TypeScript
|
npm install
|
||||||
- React
|
|
||||||
- shadcn-ui
|
|
||||||
- Tailwind CSS
|
|
||||||
|
|
||||||
## 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();
|
||||||
|
<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
|
||||||
729
docs/API.md
Normal file
729
docs/API.md
Normal file
@@ -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 <token>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 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
|
||||||
428
docs/ARCHITECTURE.md
Normal file
428
docs/ARCHITECTURE.md
Normal file
@@ -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<T>(endpoint, options): Promise<T>
|
||||||
|
+ get<T>(endpoint): Promise<T>
|
||||||
|
+ post<T>(endpoint, data): Promise<T>
|
||||||
|
+ put<T>(endpoint, data): Promise<T>
|
||||||
|
+ delete<T>(endpoint): Promise<T>
|
||||||
|
+ postForm<T>(endpoint, data): Promise<T>
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**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 <UsersList users={users} loading={loading} />;
|
||||||
|
};
|
||||||
|
|
||||||
|
// Presentational (UI)
|
||||||
|
const UsersList = ({ users, loading }) => {
|
||||||
|
if (loading) return <Spinner />;
|
||||||
|
return <div>{users.map(...)}</div>;
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Compound Components Pattern
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
<Form>
|
||||||
|
<Form.Field name="email">
|
||||||
|
<Form.Label>Email</Form.Label>
|
||||||
|
<Form.Input type="email" />
|
||||||
|
<Form.Error />
|
||||||
|
</Form.Field>
|
||||||
|
</Form>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 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 : <Navigate to="/login" />;
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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
|
||||||
|
<Route element={<ProtectedRoute />}>
|
||||||
|
<Route path="/dashboard" element={<Dashboard />} />
|
||||||
|
</Route>
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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
|
||||||
608
docs/DEVELOPMENT.md
Normal file
608
docs/DEVELOPMENT.md
Normal file
@@ -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<UserCardProps> = ({
|
||||||
|
user,
|
||||||
|
onEdit,
|
||||||
|
className
|
||||||
|
}) => {
|
||||||
|
const [isExpanded, setIsExpanded] = useState(false);
|
||||||
|
|
||||||
|
useEffect(() => {
|
||||||
|
// Effect logic
|
||||||
|
}, []);
|
||||||
|
|
||||||
|
const handleClick = () => {
|
||||||
|
setIsExpanded(!isExpanded);
|
||||||
|
};
|
||||||
|
|
||||||
|
return (
|
||||||
|
<div className={cn("card", className)}>
|
||||||
|
{/* JSX */}
|
||||||
|
</div>
|
||||||
|
);
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
### TypeScript
|
||||||
|
|
||||||
|
#### Tipado Estricto
|
||||||
|
```typescript
|
||||||
|
// ✅ Bueno
|
||||||
|
interface User {
|
||||||
|
id: string;
|
||||||
|
name: string;
|
||||||
|
email: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
const getUser = (id: string): Promise<User> => {
|
||||||
|
return api.get<User>(`/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<User | null>(null);
|
||||||
|
const [loading, setLoading] = useState(true);
|
||||||
|
const [error, setError] = useState<Error | null>(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 <div>{user.name}</div>;
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### 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)
|
||||||
|
|
||||||
|
<div className="
|
||||||
|
flex items-center justify-between
|
||||||
|
w-full h-20 p-4
|
||||||
|
text-lg font-semibold
|
||||||
|
bg-white border border-gray-200 rounded-lg shadow-md
|
||||||
|
hover:shadow-lg transition-shadow
|
||||||
|
">
|
||||||
|
Content
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Usar cn() para Clases Condicionales
|
||||||
|
```tsx
|
||||||
|
import { cn } from '@/lib/utils';
|
||||||
|
|
||||||
|
<Button
|
||||||
|
className={cn(
|
||||||
|
"base-class",
|
||||||
|
isActive && "active-class",
|
||||||
|
isDisabled && "disabled-class",
|
||||||
|
customClass
|
||||||
|
)}
|
||||||
|
/>
|
||||||
|
```
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
### Jest + React Testing Library
|
||||||
|
|
||||||
|
#### Setup
|
||||||
|
```bash
|
||||||
|
npm install --save-dev @testing-library/react @testing-library/jest-dom jest
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Escribir Tests
|
||||||
|
```typescript
|
||||||
|
// UserCard.test.tsx
|
||||||
|
import { render, screen, fireEvent } from '@testing-library/react';
|
||||||
|
import { UserCard } from './UserCard';
|
||||||
|
|
||||||
|
describe('UserCard', () => {
|
||||||
|
const mockUser = {
|
||||||
|
id: '1',
|
||||||
|
name: 'John Doe',
|
||||||
|
email: 'john@example.com'
|
||||||
|
};
|
||||||
|
|
||||||
|
it('renders user information', () => {
|
||||||
|
render(<UserCard user={mockUser} />);
|
||||||
|
expect(screen.getByText('John Doe')).toBeInTheDocument();
|
||||||
|
});
|
||||||
|
|
||||||
|
it('calls onEdit when edit button is clicked', () => {
|
||||||
|
const onEdit = jest.fn();
|
||||||
|
render(<UserCard user={mockUser} onEdit={onEdit} />);
|
||||||
|
|
||||||
|
fireEvent.click(screen.getByRole('button', { name: /edit/i }));
|
||||||
|
expect(onEdit).toHaveBeenCalledWith('1');
|
||||||
|
});
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Ejecutar Tests
|
||||||
|
```bash
|
||||||
|
npm run test # Ejecutar todos los tests
|
||||||
|
npm run test:watch # Watch mode
|
||||||
|
npm run test:coverage # Con coverage
|
||||||
|
```
|
||||||
|
|
||||||
|
## Debugging
|
||||||
|
|
||||||
|
### React Developer Tools
|
||||||
|
Instalar extensión de navegador: React Developer Tools
|
||||||
|
|
||||||
|
### VSCode Debugging
|
||||||
|
Crear `.vscode/launch.json`:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"version": "0.2.0",
|
||||||
|
"configurations": [
|
||||||
|
{
|
||||||
|
"type": "chrome",
|
||||||
|
"request": "launch",
|
||||||
|
"name": "Launch Chrome",
|
||||||
|
"url": "http://localhost:5173",
|
||||||
|
"webRoot": "${workspaceFolder}/src"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Console Logs Útiles
|
||||||
|
```typescript
|
||||||
|
// Debug con contexto
|
||||||
|
console.log('🔍 User data:', user);
|
||||||
|
console.error('❌ Error:', error);
|
||||||
|
console.warn('⚠️ Warning:', warning);
|
||||||
|
|
||||||
|
// Grupos
|
||||||
|
console.group('API Request');
|
||||||
|
console.log('URL:', url);
|
||||||
|
console.log('Method:', method);
|
||||||
|
console.groupEnd();
|
||||||
|
|
||||||
|
// Tiempo de ejecución
|
||||||
|
console.time('fetchData');
|
||||||
|
await fetchData();
|
||||||
|
console.timeEnd('fetchData');
|
||||||
|
```
|
||||||
|
|
||||||
|
## Performance
|
||||||
|
|
||||||
|
### Optimizaciones
|
||||||
|
|
||||||
|
#### Code Splitting
|
||||||
|
```typescript
|
||||||
|
// Lazy loading de componentes
|
||||||
|
const AdminDashboard = lazy(() => import('./pages/AdminDashboard'));
|
||||||
|
|
||||||
|
<Suspense fallback={<LoadingSpinner />}>
|
||||||
|
<AdminDashboard />
|
||||||
|
</Suspense>
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Bundle Analysis
|
||||||
|
```bash
|
||||||
|
npm run build
|
||||||
|
npm run analyze
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Lighthouse CI
|
||||||
|
```bash
|
||||||
|
npm install -g @lhci/cli
|
||||||
|
lhci autorun
|
||||||
|
```
|
||||||
|
|
||||||
|
## Git Workflow
|
||||||
|
|
||||||
|
### Branches
|
||||||
|
```
|
||||||
|
main # Producción
|
||||||
|
develop # Desarrollo
|
||||||
|
feature/xxx # Nuevas características
|
||||||
|
bugfix/xxx # Corrección de bugs
|
||||||
|
hotfix/xxx # Hotfixes urgentes
|
||||||
|
```
|
||||||
|
|
||||||
|
### Commits
|
||||||
|
Usar convención de commits semánticos:
|
||||||
|
```bash
|
||||||
|
feat: add user authentication
|
||||||
|
fix: resolve booking calculation bug
|
||||||
|
docs: update API documentation
|
||||||
|
style: format code with prettier
|
||||||
|
refactor: reorganize admin components
|
||||||
|
test: add tests for UserCard component
|
||||||
|
chore: update dependencies
|
||||||
|
```
|
||||||
|
|
||||||
|
### Pull Requests
|
||||||
|
1. Crear branch desde `develop`
|
||||||
|
2. Hacer cambios y commits
|
||||||
|
3. Push al repositorio remoto
|
||||||
|
4. Crear PR hacia `develop`
|
||||||
|
5. Code review
|
||||||
|
6. Merge después de aprobación
|
||||||
|
|
||||||
|
## Build y Deploy
|
||||||
|
|
||||||
|
### Build Local
|
||||||
|
```bash
|
||||||
|
npm run build
|
||||||
|
```
|
||||||
|
|
||||||
|
Archivos generados en `/dist`
|
||||||
|
|
||||||
|
### Preview Build
|
||||||
|
```bash
|
||||||
|
npm run preview
|
||||||
|
```
|
||||||
|
|
||||||
|
### Deploy a Lovable
|
||||||
|
1. Commit y push cambios
|
||||||
|
2. Ir a proyecto en Lovable
|
||||||
|
3. Cambios se sincronizarán automáticamente
|
||||||
|
|
||||||
|
### Deploy Manual
|
||||||
|
```bash
|
||||||
|
# Vercel
|
||||||
|
vercel deploy
|
||||||
|
|
||||||
|
# Netlify
|
||||||
|
netlify deploy --prod
|
||||||
|
|
||||||
|
# AWS S3
|
||||||
|
aws s3 sync dist/ s3://your-bucket/
|
||||||
|
```
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Problemas Comunes
|
||||||
|
|
||||||
|
#### Puerto 5173 en uso
|
||||||
|
```bash
|
||||||
|
# Cambiar puerto en vite.config.ts
|
||||||
|
export default defineConfig({
|
||||||
|
server: {
|
||||||
|
port: 3000
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Problemas con node_modules
|
||||||
|
```bash
|
||||||
|
rm -rf node_modules package-lock.json
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Errores de TypeScript
|
||||||
|
```bash
|
||||||
|
# Limpiar cache
|
||||||
|
rm -rf node_modules/.vite
|
||||||
|
npm run dev
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Build falla
|
||||||
|
```bash
|
||||||
|
# Verificar errores
|
||||||
|
npm run build 2>&1 | tee build.log
|
||||||
|
|
||||||
|
# Limpiar y rebuild
|
||||||
|
rm -rf dist
|
||||||
|
npm run build
|
||||||
|
```
|
||||||
|
|
||||||
|
## Resources
|
||||||
|
|
||||||
|
### Documentación Oficial
|
||||||
|
- [React](https://react.dev/)
|
||||||
|
- [TypeScript](https://www.typescriptlang.org/docs/)
|
||||||
|
- [Vite](https://vitejs.dev/)
|
||||||
|
- [Tailwind CSS](https://tailwindcss.com/docs)
|
||||||
|
- [shadcn/ui](https://ui.shadcn.com/)
|
||||||
|
|
||||||
|
### Comunidad
|
||||||
|
- [Karibeo Discord](#)
|
||||||
|
- [GitHub Discussions](#)
|
||||||
|
- [Stack Overflow](https://stackoverflow.com/questions/tagged/karibeo)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Última actualización**: 2025-01-12
|
||||||
588
docs/USER-GUIDE.md
Normal file
588
docs/USER-GUIDE.md
Normal file
@@ -0,0 +1,588 @@
|
|||||||
|
# 📖 Guía de Usuario - Karibeo
|
||||||
|
|
||||||
|
## Introducción
|
||||||
|
|
||||||
|
Bienvenido a Karibeo, tu plataforma integral para gestión turística y comercial. Esta guía te ayudará a aprovechar al máximo todas las funcionalidades del sistema.
|
||||||
|
|
||||||
|
## Índice
|
||||||
|
|
||||||
|
1. [Primeros Pasos](#primeros-pasos)
|
||||||
|
2. [Para Turistas](#para-turistas)
|
||||||
|
3. [Para Hoteles](#para-hoteles)
|
||||||
|
4. [Para Restaurantes](#para-restaurantes)
|
||||||
|
5. [Para Comercios](#para-comercios)
|
||||||
|
6. [Panel de Administración](#panel-de-administración)
|
||||||
|
7. [Preguntas Frecuentes](#preguntas-frecuentes)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Primeros Pasos
|
||||||
|
|
||||||
|
### Registro de Cuenta
|
||||||
|
|
||||||
|
1. **Acceder a la Plataforma**
|
||||||
|
- Visita [karibeo.com](https://karibeo.com)
|
||||||
|
- Click en "Registrarse" en la esquina superior derecha
|
||||||
|
|
||||||
|
2. **Completar Formulario**
|
||||||
|
- Nombre completo
|
||||||
|
- Email válido
|
||||||
|
- Contraseña segura (mínimo 8 caracteres, incluir mayúsculas, minúsculas y números)
|
||||||
|
- Tipo de cuenta: Turista o Comercio
|
||||||
|
|
||||||
|
3. **Verificar Email**
|
||||||
|
- Revisa tu bandeja de entrada
|
||||||
|
- Click en el enlace de verificación
|
||||||
|
- Tu cuenta estará activa
|
||||||
|
|
||||||
|
### Iniciar Sesión
|
||||||
|
|
||||||
|
1. Click en "Iniciar Sesión"
|
||||||
|
2. Ingresa tu email y contraseña
|
||||||
|
3. Opcional: Marca "Recordarme" para mantener la sesión
|
||||||
|
|
||||||
|
### Recuperar Contraseña
|
||||||
|
|
||||||
|
1. En la página de login, click en "Olvidé mi contraseña"
|
||||||
|
2. Ingresa tu email
|
||||||
|
3. Revisa tu correo y sigue las instrucciones
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Para Turistas
|
||||||
|
|
||||||
|
### Explorar Destinos
|
||||||
|
|
||||||
|
#### Buscar Destinos
|
||||||
|
1. Desde la página principal, usa el buscador
|
||||||
|
2. Filtra por:
|
||||||
|
- País/Región
|
||||||
|
- Tipo de actividad
|
||||||
|
- Rango de precios
|
||||||
|
- Calificación
|
||||||
|
|
||||||
|
#### Ver Detalles
|
||||||
|
- Click en cualquier destino para ver:
|
||||||
|
- Descripción completa
|
||||||
|
- Galería de fotos
|
||||||
|
- Actividades populares
|
||||||
|
- Mejor época para visitar
|
||||||
|
- Reseñas de otros viajeros
|
||||||
|
|
||||||
|
### Hacer Reservas
|
||||||
|
|
||||||
|
#### Hoteles
|
||||||
|
1. **Buscar Hotel**
|
||||||
|
- Ingresa ciudad o nombre del hotel
|
||||||
|
- Selecciona fechas (check-in / check-out)
|
||||||
|
- Número de huéspedes
|
||||||
|
|
||||||
|
2. **Comparar Opciones**
|
||||||
|
- Ver precios y disponibilidad
|
||||||
|
- Comparar amenidades
|
||||||
|
- Leer reseñas
|
||||||
|
|
||||||
|
3. **Reservar**
|
||||||
|
- Selecciona tipo de habitación
|
||||||
|
- Ingresa datos de contacto
|
||||||
|
- Solicitudes especiales (opcional)
|
||||||
|
- Proceder al pago
|
||||||
|
|
||||||
|
#### Restaurantes
|
||||||
|
1. **Buscar Restaurante**
|
||||||
|
- Por ubicación o nombre
|
||||||
|
- Filtrar por tipo de cocina
|
||||||
|
- Ver menús y precios
|
||||||
|
|
||||||
|
2. **Hacer Reserva**
|
||||||
|
- Selecciona fecha y hora
|
||||||
|
- Número de comensales
|
||||||
|
- Preferencias especiales
|
||||||
|
|
||||||
|
### Gestionar Reservas
|
||||||
|
|
||||||
|
Accede a "Mi Dashboard" → "Reservas"
|
||||||
|
|
||||||
|
#### Ver Reservas
|
||||||
|
- Todas tus reservas en un solo lugar
|
||||||
|
- Estado: Confirmada, Pendiente, Completada
|
||||||
|
- Detalles completos de cada reserva
|
||||||
|
|
||||||
|
#### Modificar Reserva
|
||||||
|
- Click en la reserva
|
||||||
|
- "Modificar" → Cambiar fechas o detalles
|
||||||
|
- Confirmar cambios
|
||||||
|
|
||||||
|
#### Cancelar Reserva
|
||||||
|
- Ver política de cancelación
|
||||||
|
- Solicitar cancelación
|
||||||
|
- Reembolso según políticas
|
||||||
|
|
||||||
|
### Billetera Digital
|
||||||
|
|
||||||
|
#### Cargar Saldo
|
||||||
|
1. Ve a "Billetera"
|
||||||
|
2. "Agregar Fondos"
|
||||||
|
3. Ingresa monto
|
||||||
|
4. Selecciona método de pago
|
||||||
|
5. Confirmar transacción
|
||||||
|
|
||||||
|
#### Ver Transacciones
|
||||||
|
- Historial completo
|
||||||
|
- Exportar a PDF/Excel
|
||||||
|
- Filtrar por fecha o tipo
|
||||||
|
|
||||||
|
### Reseñas
|
||||||
|
|
||||||
|
#### Escribir Reseña
|
||||||
|
1. Ve a "Mis Reservas" → Reservas completadas
|
||||||
|
2. Click en "Escribir Reseña"
|
||||||
|
3. Calificación (1-5 estrellas)
|
||||||
|
4. Comentario detallado
|
||||||
|
5. Subir fotos (opcional)
|
||||||
|
6. Publicar
|
||||||
|
|
||||||
|
#### Gestionar Reseñas
|
||||||
|
- Ver tus reseñas publicadas
|
||||||
|
- Editar o eliminar reseñas
|
||||||
|
- Respuestas de negocios
|
||||||
|
|
||||||
|
### Mapa Interactivo
|
||||||
|
|
||||||
|
#### Usar el Mapa
|
||||||
|
- Activar geolocalización
|
||||||
|
- Ver servicios cercanos
|
||||||
|
- Filtrar por categoría
|
||||||
|
- Obtener direcciones
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Para Hoteles
|
||||||
|
|
||||||
|
### Dashboard Hotelero
|
||||||
|
|
||||||
|
Accede a "Dashboard" → "Hotel Management"
|
||||||
|
|
||||||
|
### Gestión de Habitaciones
|
||||||
|
|
||||||
|
#### Agregar Nueva Habitación
|
||||||
|
1. "Habitaciones" → "Agregar"
|
||||||
|
2. Completar información:
|
||||||
|
- Tipo de habitación (Sencilla, Doble, Suite)
|
||||||
|
- Precio por noche
|
||||||
|
- Capacidad
|
||||||
|
- Amenidades
|
||||||
|
- Fotos de alta calidad
|
||||||
|
3. Guardar
|
||||||
|
|
||||||
|
#### Gestionar Inventario
|
||||||
|
- Ver disponibilidad en calendario
|
||||||
|
- Bloquear fechas (mantenimiento, eventos)
|
||||||
|
- Ajustar precios por temporada
|
||||||
|
|
||||||
|
### Sistema de Reservas
|
||||||
|
|
||||||
|
#### Ver Reservas
|
||||||
|
- Calendario de reservas
|
||||||
|
- Lista detallada
|
||||||
|
- Filtrar por estado o fecha
|
||||||
|
|
||||||
|
#### Procesar Reserva
|
||||||
|
1. Nueva reserva aparece como "Pendiente"
|
||||||
|
2. Revisar detalles
|
||||||
|
3. Confirmar o rechazar
|
||||||
|
4. Notificación automática al cliente
|
||||||
|
|
||||||
|
#### Check-in / Check-out
|
||||||
|
1. Buscar reserva por nombre o ID
|
||||||
|
2. Verificar identidad del huésped
|
||||||
|
3. Procesar check-in
|
||||||
|
4. Al finalizar estadía: Check-out
|
||||||
|
5. Solicitar reseña
|
||||||
|
|
||||||
|
### Room Service
|
||||||
|
|
||||||
|
#### Gestionar Pedidos
|
||||||
|
1. Ver pedidos activos
|
||||||
|
2. Estado: Recibido → En preparación → Entregado
|
||||||
|
3. Asignar a personal
|
||||||
|
4. Marcar como completado
|
||||||
|
|
||||||
|
### Gestión de Personal
|
||||||
|
|
||||||
|
#### Agregar Empleado
|
||||||
|
1. "Personal" → "Agregar"
|
||||||
|
2. Datos del empleado
|
||||||
|
3. Asignar rol y permisos
|
||||||
|
4. Turnos de trabajo
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Para Restaurantes
|
||||||
|
|
||||||
|
### Dashboard Restaurante
|
||||||
|
|
||||||
|
Accede a "Dashboard" → "Restaurant POS"
|
||||||
|
|
||||||
|
### Terminal POS
|
||||||
|
|
||||||
|
#### Crear Orden
|
||||||
|
1. Seleccionar mesa o llevar
|
||||||
|
2. Agregar items del menú
|
||||||
|
3. Aplicar descuentos (si aplica)
|
||||||
|
4. Enviar a cocina
|
||||||
|
|
||||||
|
#### Procesar Pago
|
||||||
|
1. Revisar total
|
||||||
|
2. Seleccionar método: Efectivo, Tarjeta, Digital
|
||||||
|
3. Procesar pago
|
||||||
|
4. Imprimir/enviar recibo
|
||||||
|
|
||||||
|
### Gestión de Menú
|
||||||
|
|
||||||
|
#### Agregar Platillo
|
||||||
|
1. "Menú" → "Agregar Item"
|
||||||
|
2. Información:
|
||||||
|
- Nombre
|
||||||
|
- Descripción
|
||||||
|
- Precio
|
||||||
|
- Categoría
|
||||||
|
- Foto
|
||||||
|
- Alérgenos
|
||||||
|
3. Guardar
|
||||||
|
|
||||||
|
#### Organizar Menú
|
||||||
|
- Crear categorías (Entradas, Platos Fuertes, Postres)
|
||||||
|
- Reordenar items
|
||||||
|
- Marcar items no disponibles temporalmente
|
||||||
|
|
||||||
|
### Gestión de Mesas
|
||||||
|
|
||||||
|
#### Configurar Mesas
|
||||||
|
1. "Mesas" → "Configurar"
|
||||||
|
2. Número de mesa
|
||||||
|
3. Capacidad
|
||||||
|
4. Ubicación (Interior/Terraza)
|
||||||
|
|
||||||
|
#### Estado de Mesas
|
||||||
|
- Disponible (verde)
|
||||||
|
- Ocupada (rojo)
|
||||||
|
- Reservada (amarillo)
|
||||||
|
- En limpieza (gris)
|
||||||
|
|
||||||
|
### Sistema de Cocina
|
||||||
|
|
||||||
|
#### Vista de Cocina
|
||||||
|
1. Órdenes llegan automáticamente
|
||||||
|
2. Estados:
|
||||||
|
- Pendiente
|
||||||
|
- En preparación
|
||||||
|
- Lista para servir
|
||||||
|
- Entregada
|
||||||
|
|
||||||
|
#### Gestionar Tiempos
|
||||||
|
- Ver tiempo desde que se ordenó
|
||||||
|
- Alertas de órdenes tardías
|
||||||
|
- Priorizar órdenes
|
||||||
|
|
||||||
|
### Reservaciones
|
||||||
|
|
||||||
|
#### Ver Reservaciones
|
||||||
|
- Calendario de reservas
|
||||||
|
- Lista del día
|
||||||
|
- Detalles de cada reserva
|
||||||
|
|
||||||
|
#### Gestionar Reservación
|
||||||
|
- Confirmar/Modificar
|
||||||
|
- Asignar mesa
|
||||||
|
- Notas especiales
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Para Comercios
|
||||||
|
|
||||||
|
### Dashboard Comercio
|
||||||
|
|
||||||
|
Accede a "Dashboard" → "Commerce"
|
||||||
|
|
||||||
|
### Mi Tienda
|
||||||
|
|
||||||
|
#### Configurar Tienda
|
||||||
|
1. "Mi Tienda" → "Configuración"
|
||||||
|
2. Información básica:
|
||||||
|
- Nombre del negocio
|
||||||
|
- Logo
|
||||||
|
- Descripción
|
||||||
|
- Horarios
|
||||||
|
- Ubicación
|
||||||
|
|
||||||
|
#### Personalizar
|
||||||
|
- Colores de marca
|
||||||
|
- Banner principal
|
||||||
|
- Secciones destacadas
|
||||||
|
|
||||||
|
### Gestión de Productos
|
||||||
|
|
||||||
|
#### Agregar Producto
|
||||||
|
1. "Inventario" → "Nuevo Producto"
|
||||||
|
2. Información:
|
||||||
|
- Nombre
|
||||||
|
- SKU/Código
|
||||||
|
- Descripción
|
||||||
|
- Precio
|
||||||
|
- Stock inicial
|
||||||
|
- Categoría
|
||||||
|
- Imágenes
|
||||||
|
3. Publicar
|
||||||
|
|
||||||
|
#### Gestionar Stock
|
||||||
|
- Ver niveles de inventario
|
||||||
|
- Alertas de stock bajo
|
||||||
|
- Actualizar cantidades
|
||||||
|
- Historial de movimientos
|
||||||
|
|
||||||
|
### Terminal POS
|
||||||
|
|
||||||
|
#### Proceso de Venta
|
||||||
|
1. Buscar productos por nombre o escanear código
|
||||||
|
2. Agregar al carrito
|
||||||
|
3. Ajustar cantidades
|
||||||
|
4. Aplicar descuentos
|
||||||
|
5. Procesar pago
|
||||||
|
6. Imprimir ticket
|
||||||
|
|
||||||
|
### Clientes
|
||||||
|
|
||||||
|
#### Base de Datos de Clientes
|
||||||
|
- Lista de clientes registrados
|
||||||
|
- Historial de compras
|
||||||
|
- Datos de contacto
|
||||||
|
|
||||||
|
#### Programa de Fidelidad
|
||||||
|
- Puntos acumulados
|
||||||
|
- Niveles de membresía
|
||||||
|
- Promociones exclusivas
|
||||||
|
|
||||||
|
### Reportes
|
||||||
|
|
||||||
|
#### Ver Reportes
|
||||||
|
1. "Reportes" → Seleccionar tipo
|
||||||
|
2. Opciones:
|
||||||
|
- Ventas por día/mes
|
||||||
|
- Productos más vendidos
|
||||||
|
- Análisis de clientes
|
||||||
|
- Inventario
|
||||||
|
3. Exportar a PDF/Excel
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Panel de Administración
|
||||||
|
|
||||||
|
### Acceso
|
||||||
|
|
||||||
|
Solo para usuarios con rol de Administrador o Super Admin.
|
||||||
|
|
||||||
|
### Dashboard Ejecutivo
|
||||||
|
|
||||||
|
#### Métricas Principales
|
||||||
|
- Total de usuarios
|
||||||
|
- Ingresos totales
|
||||||
|
- Reservas activas
|
||||||
|
- Servicios registrados
|
||||||
|
- Crecimiento mensual
|
||||||
|
|
||||||
|
#### Gráficos y Analytics
|
||||||
|
- Ingresos por mes
|
||||||
|
- Reservas por tipo
|
||||||
|
- Usuarios activos
|
||||||
|
- Destinos populares
|
||||||
|
|
||||||
|
### Gestión de Usuarios
|
||||||
|
|
||||||
|
#### Ver Usuarios
|
||||||
|
1. "Admin Panel" → "Usuarios"
|
||||||
|
2. Lista completa con filtros
|
||||||
|
3. Buscar por nombre, email, rol
|
||||||
|
|
||||||
|
#### Acciones
|
||||||
|
- Crear nuevo usuario
|
||||||
|
- Editar perfil
|
||||||
|
- Cambiar rol
|
||||||
|
- Suspender/Activar cuenta
|
||||||
|
- Eliminar usuario
|
||||||
|
|
||||||
|
### Roles y Permisos
|
||||||
|
|
||||||
|
#### Gestionar Roles
|
||||||
|
1. "Admin Panel" → "Usuarios" → "Roles & Permisos"
|
||||||
|
2. Ver roles por entidad:
|
||||||
|
- Admin
|
||||||
|
- Hotel
|
||||||
|
- Restaurant
|
||||||
|
- Commerce
|
||||||
|
|
||||||
|
#### Crear Rol Personalizado
|
||||||
|
1. "Crear Rol"
|
||||||
|
2. Nombre y descripción
|
||||||
|
3. Seleccionar permisos específicos
|
||||||
|
4. Asignar a usuarios
|
||||||
|
|
||||||
|
### Gestión de Contenido
|
||||||
|
|
||||||
|
#### Destinos
|
||||||
|
- Agregar/Editar destinos
|
||||||
|
- Información turística
|
||||||
|
- Puntos de interés
|
||||||
|
- Guías
|
||||||
|
|
||||||
|
#### Lugares
|
||||||
|
- Restaurantes
|
||||||
|
- Atracciones
|
||||||
|
- Shopping
|
||||||
|
- Servicios
|
||||||
|
|
||||||
|
### CRM
|
||||||
|
|
||||||
|
#### Gestión de Contactos
|
||||||
|
- Base de datos de clientes
|
||||||
|
- Segmentación
|
||||||
|
- Tags y categorías
|
||||||
|
- Historial de interacciones
|
||||||
|
|
||||||
|
#### Campañas de Marketing
|
||||||
|
1. "CRM" → "Campañas"
|
||||||
|
2. Crear nueva campaña
|
||||||
|
3. Seleccionar segmento
|
||||||
|
4. Diseñar mensaje
|
||||||
|
5. Programar envío
|
||||||
|
6. Ver resultados
|
||||||
|
|
||||||
|
### Channel Manager
|
||||||
|
|
||||||
|
#### Canales Conectados
|
||||||
|
- Booking.com
|
||||||
|
- Airbnb
|
||||||
|
- Expedia
|
||||||
|
- Otros OTAs
|
||||||
|
|
||||||
|
#### Sincronización
|
||||||
|
- Ver estado de sincronización
|
||||||
|
- Sincronizar manualmente
|
||||||
|
- Resolver conflictos
|
||||||
|
- Ver reservas por canal
|
||||||
|
|
||||||
|
### Sistema de Comisiones
|
||||||
|
|
||||||
|
#### Configurar Reglas
|
||||||
|
1. "Comisiones" → "Reglas"
|
||||||
|
2. Crear nueva regla
|
||||||
|
3. Definir:
|
||||||
|
- Tipo (porcentaje o fijo)
|
||||||
|
- Entidad (hotel, restaurant)
|
||||||
|
- Condiciones
|
||||||
|
4. Activar
|
||||||
|
|
||||||
|
#### Ver Pagos
|
||||||
|
- Historial de comisiones
|
||||||
|
- Comisiones pendientes
|
||||||
|
- Procesar pagos
|
||||||
|
- Exportar reportes
|
||||||
|
|
||||||
|
### Configuración Global
|
||||||
|
|
||||||
|
#### APIs Externas
|
||||||
|
- Google Maps API
|
||||||
|
- Stripe/PayPal
|
||||||
|
- Servicios de email
|
||||||
|
- Analytics
|
||||||
|
|
||||||
|
#### Integraciones
|
||||||
|
- Ver integraciones activas
|
||||||
|
- Configurar webhooks
|
||||||
|
- Logs de integración
|
||||||
|
|
||||||
|
#### Parámetros del Sistema
|
||||||
|
- Monedas disponibles
|
||||||
|
- Idiomas soportados
|
||||||
|
- Configuraciones generales
|
||||||
|
|
||||||
|
### Security Center
|
||||||
|
|
||||||
|
#### Monitoreo
|
||||||
|
- Intentos de login fallidos
|
||||||
|
- Actividad sospechosa
|
||||||
|
- Accesos no autorizados
|
||||||
|
|
||||||
|
#### Auditoría
|
||||||
|
- Logs de sistema
|
||||||
|
- Cambios en configuración
|
||||||
|
- Acciones de usuarios
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Preguntas Frecuentes
|
||||||
|
|
||||||
|
### General
|
||||||
|
|
||||||
|
**¿Karibeo es gratis?**
|
||||||
|
Karibeo ofrece planes gratuitos y de pago según el tipo de usuario. Los turistas pueden usar la plataforma sin costo. Los negocios tienen planes según sus necesidades.
|
||||||
|
|
||||||
|
**¿En qué países está disponible?**
|
||||||
|
Actualmente, Karibeo opera principalmente en el Caribe y América Latina, con expansión continua.
|
||||||
|
|
||||||
|
**¿Cómo contacto soporte?**
|
||||||
|
- Email: soporte@karibeo.com
|
||||||
|
- Chat en vivo: Disponible 24/7
|
||||||
|
- Teléfono: +1-809-555-KARIB
|
||||||
|
|
||||||
|
### Pagos
|
||||||
|
|
||||||
|
**¿Qué métodos de pago aceptan?**
|
||||||
|
- Tarjetas de crédito/débito (Visa, Mastercard, AmEx)
|
||||||
|
- PayPal
|
||||||
|
- Transferencias bancarias
|
||||||
|
- Billetera digital Karibeo
|
||||||
|
|
||||||
|
**¿Los pagos son seguros?**
|
||||||
|
Sí, usamos encriptación SSL y cumplimos con estándares PCI DSS para proteger tu información.
|
||||||
|
|
||||||
|
**¿Cuándo se procesa el reembolso?**
|
||||||
|
Según la política del establecimiento, generalmente de 5-10 días hábiles.
|
||||||
|
|
||||||
|
### Reservas
|
||||||
|
|
||||||
|
**¿Puedo modificar mi reserva?**
|
||||||
|
Sí, según disponibilidad y política del establecimiento. Ve a "Mis Reservas" y selecciona "Modificar".
|
||||||
|
|
||||||
|
**¿Qué pasa si cancelo?**
|
||||||
|
Las políticas de cancelación varían. Revisa los términos antes de reservar. Algunas reservas ofrecen cancelación gratuita.
|
||||||
|
|
||||||
|
**¿Cómo sé si mi reserva fue confirmada?**
|
||||||
|
Recibirás una confirmación por email y notificación en la app. También puedes verificar en "Mis Reservas".
|
||||||
|
|
||||||
|
### Técnico
|
||||||
|
|
||||||
|
**¿Hay app móvil?**
|
||||||
|
Actualmente, Karibeo es una aplicación web responsive que funciona en todos los dispositivos. App móvil nativa próximamente.
|
||||||
|
|
||||||
|
**¿Funciona sin internet?**
|
||||||
|
Algunas funciones básicas están disponibles offline, pero se requiere conexión para reservas y pagos.
|
||||||
|
|
||||||
|
**Mi cuenta está bloqueada, ¿qué hago?**
|
||||||
|
Contacta a soporte@karibeo.com con tu información para desbloquearla.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Recursos Adicionales
|
||||||
|
|
||||||
|
- **Video Tutoriales**: [youtube.com/karibeo](https://youtube.com/karibeo)
|
||||||
|
- **Blog**: [blog.karibeo.com](https://blog.karibeo.com)
|
||||||
|
- **Centro de Ayuda**: [help.karibeo.com](https://help.karibeo.com)
|
||||||
|
- **Comunidad**: [community.karibeo.com](https://community.karibeo.com)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**¿Necesitas más ayuda?**
|
||||||
|
Contacta a nuestro equipo de soporte en cualquier momento.
|
||||||
|
|
||||||
|
**Última actualización**: 2025-01-12
|
||||||
Reference in New Issue
Block a user