87 lines
8.3 KiB
Markdown
87 lines
8.3 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 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`)
|
|
1. **Inicie sesión** como **`director`** (`password123`).
|
|
2. **Acción**: Navegue a **Planes**. Cree un plan borrador, asigne reglas y active el plan. Intente modificarlo para ver el versionado automático que clona el plan a la versión `v2`.
|
|
3. **Asignar Metas**: Vaya a **Metas** y configure una cuota de ventas de `100000` para `colaborador_mde` para el período `2026-06`.
|
|
|
|
### Paso B: La Experiencia de Operaciones Financieras Globales (`analista`)
|
|
1. **Cierre sesión**, e inicie 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). Intente volver a subir el mismo archivo y observe el bloqueo automático debido a la validación de clave de idempotencia.
|
|
3. **Simulación y Cálculo**: Vaya a **Simulación**. Ejecute las comisiones de `2026-06` sin el modo simulador para persistir. Observe las liquidaciones calculadas y las notas de auditoría generadas por IA.
|
|
|
|
### Paso C: La Experiencia del Líder Comercial Regional (`lider_mde` vs `lider_ctg`)
|
|
1. **Cierre sesión**, e inicie sesión como el Líder de Medellín **`lider_mde`** (`password123`).
|
|
2. **Aislamiento de Carga de Archivos**: Vaya a **Cargar Ventas**. Intente subir un archivo con ventas del hotel de Cartagena (`EST-CTG`). El sistema bloqueará la acción porque el alcance de un líder está estrictamente restringido a su hotel asignado (`EST-MDE`).
|
|
3. **Cierre sesión**, e inicie sesión como **`lider_ctg`** (`password123`). Suba un archivo de Cartagena; el sistema le permitirá hacerlo con éxito solo para su hotel.
|
|
|
|
### Paso D: La Experiencia del Colaborador (`colaborador_mde` vs `colaborador_ctg`)
|
|
1. **Cierre sesión**, e inicie sesión como el Colaborador de Medellín **`colaborador_mde`** (`password123`).
|
|
2. **Aislamiento de Datos Personales**: Vaya a **Historial** y **Metas**. Solo verá sus propios registros de Medellín.
|
|
3. **Cierre sesión**, e inicie sesión como el Colaborador de Cartagena **`colaborador_ctg`** (`password123`). Solo verá los registros de Cartagena. Se garantiza la segregación absoluta de la información.
|
|
|
|
### Paso E: La Experiencia del Gerente de Hotel (`gerente_mde` vs `gerente_ctg`)
|
|
1. **Cierre sesión**, e inicie sesión como el Gerente de Medellín **`gerente_mde`** (`password123`).
|
|
2. **Segregación de Aprobaciones**: Vaya a **Aprobaciones**. Verá liquidaciones pendientes de Medellín. Rechace la liquidación con el motivo: `"Falta validar soporte físico"`.
|
|
3. **Cierre sesión**, e inicie sesión como el Gerente de Cartagena **`gerente_ctg`** (`password123`). Verá liquidaciones pendientes de Cartagena. Apruebe la liquidación de `colaborador_ctg`.
|
|
|
|
### Paso F: La Experiencia de Cumplimiento de Auditoría (`consulta`)
|
|
1. **Cierre sesión**, e inicie sesión como **`consulta`** (`password123`).
|
|
2. **Auditoría de Solo Lectura**: Explore Planes, Metas y el Tablero. Verifique que puede inspeccionar todos los datos de todos los hoteles, pero todos 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. **Cierre sesión**, e inicie sesión como **`admin`** (`password123`).
|
|
2. **Explorador de Auditoría**: Vaya a **Auditoría**. Seleccione un registro y verifique la comparación de cambios en JSON, con datos confidenciales enmascarados como `[REDACTED]`.
|
|
|
|
---
|
|
|
|
## 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.
|