# Guía de Demostración para Reclutadores: Sistema de Remuneración Variable de Hoteles Estelar

Bienvenido a la guía de exploración para el **Sistema de Remuneración Variable y Comisiones de Hoteles Estelar**. Este documento describe cómo un desarrollador o reclutador puede explorar el sistema, comprender cómo se resuelven las historias de usuario críticas de nivel empresarial y verificar el diseño y la arquitectura de nivel de producción.

---

## 1. Descripción General del Proyecto y Stack Tecnológico
El sistema está construido como una aplicación empresarial multi-inquilino altamente segura, diseñada para calcular, gestionar y auditar las comisiones de ventas comerciales para la franquicia de Hoteles Estelar.

### Stack Tecnológico
- **Framework**: Next.js (App Router, Turbopack)
- **Base de Datos**: PostgreSQL con Prisma ORM
- **Seguridad**: Seguridad a Nivel de Fila (**Row-Level Security - RLS**) en la base de datos y validación de firmas de webhooks
- **Automatización**: Flujos de trabajo de n8n para cálculos en segundo plano y auditoría impulsada por IA
- **Estilos**: CSS nativo (Vanilla CSS), configurado con un modo oscuro de alta fidelidad, glassmorphism y paneles adaptables

---

## 2. Historias de Usuario Principales y Soluciones Técnicas

### Historia de Usuario 1: Segregación Estricta de Datos (Row-Level Security)
* **La Solución**: Las políticas de RLS de PostgreSQL imponen la segregación directamente en el motor de base de datos. Cuando se ejecuta cualquier consulta, el sistema establece dinámicamente la variable de sesión `app.current_user_role` y `app.current_user_id`. Incluso si un usuario realiza solicitudes directas a la API o intenta eludir la interfaz de usuario, la base de datos retorna `0` registros para otros usuarios u hoteles.
* **Referencia de Código**: Revise [rls_and_seed.sql](../../prisma/rls_and_seed.sql) para ver las políticas SQL, y [auth.ts](../../src/lib/auth.ts) para ver cómo se inyectan los contextos de sesión.

### Historia de Usuario 2: Control de Versiones de Planes y Configuración de Reglas
* **La Solución**: El sistema implementa el bloqueo de planes. Cuando un plan está en estado `DRAFT` (Borrador), se pueden editar sus reglas. Cuando se marca como `ACTIVE` (Activo), pasa a ser de solo lectura. Si un administrador intenta alternar o actualizar un plan activo, el sistema clona el plan, incrementa el campo `version` (por ejemplo, `v1` -> `v2`) y establece la fecha de fin de validez del plan anterior.
* **Referencia de Código**: Revise la lógica de clonación de planes en [/api/plans/route.ts](../../src/app/api/plans/route.ts).

### Historia de Usuario 3: Importación Masiva Atómica de Ventas
* **La Solución**: Las hojas de Excel se procesan y validan contra restricciones estrictas (usuarios inexistentes, montos negativos, períodos inválidos, códigos de hotel incorrectos). La validación es **atómica**: si una sola fila falla, toda la transacción se revierte. La interfaz de usuario presenta un panel de inconsistencias que detalla con precisión qué celdas fallaron.
* **Referencia de Código**: Vea el análisis de archivos en [/api/sales/import/route.ts](../../src/app/api/sales/import/route.ts).

### Historia de Usuario 4: Cálculos Automatizados y Deducciones Retroactivas (Clawbacks)
* **La Solución**: El flujo de cálculo de n8n activa el motor de liquidación. El motor consulta las ventas de los meses anteriores. Si una venta fue devuelta o cancelada, aplica un ajuste de delta retroactivo (clawback) en la liquidación del mes en curso, restándolo del pago final.
* **Referencia de Código**: Vea los cálculos de liquidaciones en [/api/settlements/calculate/route.ts](../../src/app/api/settlements/calculate/route.ts).

### Historia de Usuario 5: Registro de Auditoría Inmutable
* **La Solución**: La tabla `audit_logs` cuenta con disparadores de base de datos que interceptan y bloquean cualquier consulta de tipo `UPDATE` o `DELETE`. El panel de administración incluye un Explorador de Registros de Auditoría interactivo con un panel de comparación JSON en paralelo que muestra exactamente qué cambió.
* **Referencia de Código**: Vea la lógica de los registros de auditoría en [/api/audit-logs/route.ts](../../src/app/api/audit-logs/route.ts).

---

## 3. Guía de Exploración Paso a Paso (Los 10 Roles de Demostración)

Puede acceder a la versión de demostración de la aplicación en: **`https://hotels-demo.gaboggamer.online`**

### Paso A: La Experiencia de Planificación (`director`)
- **Propósito del Rol**: Representa al planificador comercial que configura los planes y metas de comisiones a nivel global.
1. **Inicio de sesión**: Vaya a la pantalla de login, introduzca el usuario **`director`** y la contraseña **`password123`**, y haga clic en **Iniciar Sesión**.
2. **Creación de Plan**: En el encabezado de navegación superior, haga clic en **Planes**.
3. **Acción**: Haga clic en **Nuevo Plan**, ingrese los detalles (ej. Nombre: `Plan Especial Q3 2026`, Código: `EST-Q3-26`, Tipo: `COMMISSION`, Fechas de inicio/fin cubriendo de junio a agosto de 2026) y haga clic en **Guardar**.
4. **Configurar Reglas**: Busque el plan en la tabla, haga clic en el icono de **Reglas**, configure los rangos de comisión (ej. tasa de 0% de 0% a 90% de logro, tasa de 2.5% de 90.01% a 110% de logro) y haga clic en **Guardar Reglas**.
5. **Activar y Probar Versionado**: Vuelva a la lista de planes. Haga clic en el botón para cambiar el estado a **ACTIVO**. Intente editar el plan activo. El sistema bloquea el cambio directo y clona el plan a la versión **`v2`** en estado borrador, inactivando la versión anterior **`v1`**. Esto protege el historial.
6. **Asignar Meta**: Vaya a la pestaña **Metas**. Haga clic en **Asignar Meta**, seleccione `INDIVIDUAL`, asigne a `colaborador_mde` para el período `2026-06`, defina una meta de `100000` y haga clic en **Guardar Meta**.

### Paso B: La Experiencia de Operaciones Financieras Globales (`analista`)
- **Propósito del Rol**: Analista global que sube las ventas de todos los hoteles y calcula las comisiones.
1. **Cerrar sesión**, e iniciar sesión como **`analista`** (`password123`).
2. **Carga de Excel**: Vaya a **Cargar Ventas**. Suba el archivo [demo_sales_data.xlsx](../../public/templates/demo_sales_data.xlsx).
3. **Prueba de Idempotencia**: Intente subir el mismo archivo nuevamente. El sistema lo bloqueará mostrando el error: `Error: Código de lote duplicado (Llave de idempotencia ya registrada)`, evitando pagos duplicados.
4. **Simulación y Cálculo**: Vaya a la pestaña **Simulación**. Seleccione el período `2026-06`. Desmarque la opción *Modo Simulación* para confirmar. Haga clic en **Calcular Liquidaciones**. Espere de 5 a 10 segundos a que responda el webhook de n8n. La tabla de liquidaciones se cargará con notas de auditoría de IA.

### Paso C: La Experiencia del Líder Comercial Regional (`lider_mde` vs `lider_ctg`)
- **Propósito del Rol**: Demuestra la seguridad regional. Los líderes comerciales solo pueden cargar ventas de su propio hotel.
1. **Cerrar sesión**, e iniciar sesión como el Líder de Medellín **`lider_mde`** (`password123`).
2. **Límites de Carga Regional**: Vaya a **Cargar Ventas**. Intente subir un archivo Excel que contenga registros del hotel de Cartagena (`EST-CTG`).
3. **Resultado Esperado**: El sistema rechaza la carga debido a que el código del hotel `EST-CTG` está fuera de su jurisdicción autorizada de Medellín (`EST-MDE`).
4. **Cerrar sesión**, e iniciar sesión como **`lider_ctg`** (`password123`). Suba un archivo de Cartagena; el sistema procesará la importación con éxito.

### Paso D: La Experiencia del Colaborador (`colaborador_mde` vs `colaborador_ctg`)
- **Propósito del Rol**: Aislamiento de datos del vendedor bajo políticas RLS.
1. **Cerrar sesión**, e iniciar sesión como el Colaborador de Medellín **`colaborador_mde`** (`password123`).
2. **Aislamiento de Datos**: Vaya a **Historial** y **Metas**. Solo visualizará sus metas e historial de ventas de Medellín.
3. **Cerrar sesión**, e iniciar sesión como el Colaborador de Cartagena **`colaborador_ctg`** (`password123`).
4. **Resultado Esperado**: Solo se devuelven los registros de Cartagena. La base de datos RLS filtra dinámicamente la consulta basándose en el ID de sesión del usuario.

### Paso E: La Experiencia del Gerente de Hotel (`gerente_mde` vs `gerente_ctg`)
- **Propósito del Rol**: Segregación regional para flujos de aprobación.
1. **Cerrar sesión**, e iniciar sesión como el Gerente de Medellín **`gerente_mde`** (`password123`).
2. **Segregación de Aprobación**: Vaya a **Aprobaciones**. Verá liquidaciones pendientes únicamente de Medellín. Rechace la liquidación ingresando el motivo: `"Falta validar soporte físico"`.
3. **Cerrar sesión**, e iniciar sesión como el Gerente de Cartagena **`gerente_ctg`** (`password123`).
4. **Resultado Esperado**: Solo verá liquidaciones de Cartagena. Haga clic en **Aprobar** en la liquidación de `colaborador_ctg`; el estado cambia a aprobado y genera el log de auditoría.

### Paso F: La Experiencia de Cumplimiento de Auditoría (`consulta`)
- **Propósito del Rol**: Vista de cumplimiento global de solo lectura para auditoría.
1. **Cerrar sesión**, e iniciar sesión como **`consulta`** (`password123`).
2. **Inspección de Solo Lectura**: Explore Planes, Metas y el Tablero. Verifique que puede inspeccionar todos los datos de todas las regiones, pero los botones de creación, edición, carga y aprobación están ocultos o deshabilitados.

### Paso G: La Experiencia de Administrador del Sistema (`admin`)
1. **Cerrar sesión**, e iniciar sesión como **`admin`** (`password123`).
2. **Explorador de Auditoría**: Vaya a **Auditoría**. Seleccione un registro y valide los cambios antes y después en JSON, con datos confidenciales enmascarados como `[REDACTED]`.
3. **Prueba de Inmutabilidad**: Intente modificar o borrar algún registro de log de auditoría. El disparador de la base de datos bloqueará la operación lanzando un error.

---

## 4. Detalles Estéticos y Experiencia de Usuario
Al presentar este proyecto, recuerde destacar:
- **Glassmorphism**: Bordes y sombras sutiles con fondos oscuros traslúcidos.
- **Micro-animaciones**: Transiciones suaves al pasar el cursor por tablas, botones y formularios.
- **Gráficos Dinámicos**: Gráficos interactivos que se ajustan con filtros, comparando regiones e históricos.
- **Selector de Idioma**: Alterna la interfaz y las observaciones de IA entre inglés y español al instante.
