gabogg/semillero-special-hotel
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
semillero-special-hotel/docs/showcase/recruiter_guide_es.md

8.3 KiB
Raw Blame History

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 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

  • 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

  • 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)

  • 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

  • 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.

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. 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.