semillero-special-hotel/docs/showcase/recruiter_guide_es.md

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 para ver las políticas SQL, y 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.

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.

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.

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.

---

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.