# 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 criptogrÃ¡fica de firmas de webhooks
- **AutomatizaciÃ³n**: Flujos de trabajo de n8n para cÃ¡lculos en segundo plano y auditorÃ­a de cumplimiento 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)
> **Como** colaborador de ventas,  
> **Quiero** ver Ãºnicamente mis propias ventas, metas y liquidaciones de comisiones,  
> **Para que** no pueda ver ni alterar la informaciÃ³n financiera de otros miembros del equipo.
* **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
> **Como** administrador o analista comercial,  
> **Quiero** crear planes de compensaciÃ³n y reglas, y asegurar que la ediciÃ³n de planes activos genere una nueva versiÃ³n en lugar de modificar el historial,  
> **Para que** los cÃ¡lculos histÃ³ricos sigan siendo auditables e inalterados.
* **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
> **Como** lÃ­der comercial,  
> **Quiero** importar archivos Excel con los resultados de ventas mensuales,  
> **Para que** las ventas se procesen y validen automÃ¡ticamente, retornando errores claros si el archivo presenta inconsistencias.
* **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)
> **Como** analista de finanzas,  
> **Quiero** que los cÃ¡lculos de comisiones se ejecuten automÃ¡ticamente mediante n8n y se ajusten por devoluciones o ventas canceladas de meses anteriores,  
> **Para que** los pagos sean correctos y se deduzcan los saldos negativos correspondientes.
* **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
> **Como** auditor externo,  
> **Quiero** ver un historial completo de todos los inicios de sesiÃ³n de usuario, modificaciones de planes y aprobaciones,  
> **Para** verificar que nadie pueda editar ni eliminar los registros de auditorÃ­a.
* **La SoluciÃ³n**: La tabla `audit_logs` cuenta con reglas y 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

Puede acceder a la versiÃ### Paso A: La Experiencia del Colaborador (LÃ­mites de Seguridad RLS y SegregaciÃ³n entre Hoteles)
1. **Inicie sesiÃ³n** como el colaborador de MedellÃ­n:
   - **Usuario**: `colaborador_mde`
   - **ContraseÃ±a**: `password123`
2. **Observe**: Se carga el panel. Puede ver sus propias mÃ©tricas (monto de ventas, metas, porcentaje de logro) asociadas a `Estelar MedellÃ­n (EST-MDE)`.
3. **Verifique la SegregaciÃ³n**: Navegue a las pestaÃ±as **Historial** y **Metas**. Solo verÃ¡ los registros asociados a `colaborador_mde`. No podrÃ¡ ver las metas ni liquidaciones de ningÃºn otro colaborador.
4. **Pruebe el Aislamiento entre Hoteles**:
   - Cierre sesiÃ³n e inicie sesiÃ³n como el colaborador de Cartagena:
     - **Usuario**: `colaborador_ctg`
     - **ContraseÃ±a**: `password123`
   - **Observe**: Ahora solo visualizarÃ¡ los datos de `Estelar Cartagena (EST-CTG)`. La base de datos restringe la sesiÃ³n de tal forma que tiene exposiciÃ³n nula a los registros de MedellÃ­n (`EST-MDE`), a pesar de compartir el mismo rol de colaborador.
5. **Intente Eludir**: Note que no hay enlaces de "Cargar Ventas" ni de "Planes" en el encabezado. La interfaz de usuario oculta los controles reservados a roles de supervisiÃ³n.

### Paso B: La Experiencia del Gerente y LÃ­der de Hotel (SegregaciÃ³n de Aprobaciones)
1. **Cierre sesiÃ³n** e **inicie sesiÃ³n** como el Gerente del Hotel MedellÃ­n:
   - **Usuario**: `gerente_mde`
   - **ContraseÃ±a**: `password123`
2. **Observe**: El gerente visualiza las mÃ©tricas agregadas correspondientes a las ventas totales de su hotel (`EST-MDE`).
3. **SegregaciÃ³n de AprobaciÃ³n**: Navigate a la pestaÃ±a **Aprobaciones**. VerÃ¡ un listado de liquidaciones pendientes para junio de 2026. Note que solo se muestran los colaboradores de su hotel (`EST-MDE`, como `colaborador_mde`).
4. **Verifique el Aislamiento entre Hoteles**:
   - Cierre sesiÃ³n e inicie sesiÃ³n como el Gerente del Hotel Cartagena:
     - **Usuario**: `gerente_ctg`
     - **ContraseÃ±a**: `password123`
   - **Observe**: El panel de control y la pestaÃ±a de **Aprobaciones** ahora muestran Ãºnicamente los datos de `Estelar Cartagena (EST-CTG)`. No es posible visualizar, aprobar ni rechazar liquidaciones de MedellÃ­n o BogotÃ¡.
5. **SeparaciÃ³n de Nivel de LÃ­der**:
   - Cierre sesiÃ³n e inicie sesiÃ³n como el LÃ­der Comercial de MedellÃ­n:
     - **Usuario**: `lider_mde`
     - **ContraseÃ±a**: `password123`
   - **Observe**: El lÃ­der comercial tiene acceso de lectura a los registros de su hotel y puede cargar ventas Ãºnicamente para `EST-MDE`, pero tiene acceso nulo a los datos de Cartagena (`EST-CTG`) o BogotÃ¡ (`EST-P93`).
6. **Flujo de AcciÃ³n**: Bajo una cuenta de gerente, apruebe o rechace una liquidaciÃ³n pendiente. Aprobar cambia el estado a `APPROVED` y escribe un log de auditorÃ­a inmutable. Rechazar requiere ingresar un motivo de rechazo (ej. `"Falta validar soporte fÃ­sico"`) y cambia el estado a `REJECTED`.

### Paso C: La Experiencia del Administrador (Planes y AuditorÃ­a)
1. **Cierre sesiÃ³n** e **inicie sesiÃ³n** como Administrador del Sistema:
   - **Usuario**: `admin`
   - **ContraseÃ±a**: `password123`
2. **Vista Global**: El administrador visualiza mÃ©tricas de todas las regiones/hoteles en su panel principal.
3. **Control de Versiones de Planes**: Navegue a la pestaÃ±a **Planes**.
   - Haga clic en **Nuevo Plan** para abrir el formulario de creaciÃ³n.
   - Cree un borrador de plan llamado `Plan Piloto Q3` con cÃ³digo `PLAN-Q3` y vigencias correspondientes.
   - Haga clic en el Ã­cono de "Reglas" a la derecha y configure los rangos de comisiones (ej. tasa de 0% hasta 90% de logro, tasa de 2% hasta 100% de logro).
   - Cambie el estado a **ACTIVO**.
   - Vuelva a hacer clic en el botÃ³n de alternancia **OTRA VEZ** en el plan activo. VerÃ¡ que la versiÃ³n se incrementa a `v2` y la versiÃ³n anterior pasa a estado `INACTIVO`.
4. **Explorador de AuditorÃ­a**: Navegue a la pestaÃ±a **AuditorÃ­a**.
   - Haga clic en cualquier fila de log (ej. `APPROVE` o `CREATE`).
   - AparecerÃ¡ el panel de comparaciÃ³n JSON en paralelo, mostrando los cambios precisos de esa transacciÃ³n.
   - Intente modificar o borrar algÃºn registro; el motor de base de datos devolverÃ¡ un error, impidiendo la alteraciÃ³n del historial.

---

## 4. Detalles EstÃ©ticos y Experiencia de Usuario
Al presentar este proyecto a un reclutador, 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.
