102 lines
9.4 KiB
Markdown
102 lines
9.4 KiB
Markdown
# 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.
|