# 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](file:///home/gabogg/Proyects/semillero-special-hotel/prisma/rls_and_seed.sql) para ver las políticas SQL, y [auth.ts](file:///home/gabogg/Proyects/semillero-special-hotel/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](file:///home/gabogg/Proyects/semillero-special-hotel/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](file:///home/gabogg/Proyects/semillero-special-hotel/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](file:///home/gabogg/Proyects/semillero-special-hotel/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](file:///home/gabogg/Proyects/semillero-special-hotel/src/app/api/audit-logs/route.ts). --- ## 3. Guía de Exploración Paso a Paso Puede acceder a la versión de demostración de la aplicación en: **`https://hotels-demo.gaboggamer.online`** ### Paso A: La Experiencia del Colaborador (Límites de Seguridad RLS) 1. **Inicie sesión** como colaborador: - **Usuario**: `colab_mde_1` - **Contraseña**: `password123` 2. **Observe**: Se carga el panel del panel. Puede ver sus propias métricas (monto de ventas, metas, porcentaje de logro). 3. **Verifique la Segregación**: Navegue a las pestañas **Historial** y **Metas**. Solo verá los registros asociados a `colab_mde_1` del hotel `Estelar Medellín (EST-MDE)`. No podrá ver las metas ni liquidaciones de ningún otro colaborador. 4. **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 de Hotel (Flujo de Aprobación) 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. 3. **Segregación de Aprobación**: Navegue 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`). No puede visualizar ni aprobar liquidaciones de Bogotá o Cartagena. 4. **Aprobar una Liquidación**: Haga clic en "Aprobar" en una liquidación pendiente. Cambiará de estado de inmediato a `APPROVED` y registrará una entrada inmutable de auditoría. 5. **Rechazar con Motivo**: Haga clic en "Rechazar" en otra liquidación. El sistema le solicitará un motivo. Escriba `"Falta validar soporte físico"` y envíe. El estado cambiará 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 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.