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

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

  • Propósito del Rol: Representa al planificador comercial que configura los planes y metas de comisiones a nivel global.
  1. Inicio de sesión: Vaya a la pantalla de login, introduzca el usuario director y la contraseña password123, y haga clic en Iniciar Sesión.
  2. Creación de Plan: En el encabezado de navegación superior, haga clic en Planes.
  3. Acción: Haga clic en Nuevo Plan, ingrese los detalles (ej. Nombre: Plan Especial Q3 2026, Código: EST-Q3-26, Tipo: COMMISSION, Fechas de inicio/fin cubriendo de junio a agosto de 2026) y haga clic en Guardar.
  4. Configurar Reglas: Busque el plan en la tabla, haga clic en el icono de Reglas, configure los rangos de comisión (ej. tasa de 0% de 0% a 90% de logro, tasa de 2.5% de 90.01% a 110% de logro) y haga clic en Guardar Reglas.
  5. Activar y Probar Versionado: Vuelva a la lista de planes. Haga clic en el botón para cambiar el estado a ACTIVO. Intente editar el plan activo. El sistema bloquea el cambio directo y clona el plan a la versión v2 en estado borrador, inactivando la versión anterior v1. Esto protege el historial.
  6. Asignar Meta: Vaya a la pestaña Metas. Haga clic en Asignar Meta, seleccione INDIVIDUAL, asigne a colaborador_mde para el período 2026-06, defina una meta de 100000 y haga clic en Guardar Meta.

Paso B: La Experiencia de Operaciones Financieras Globales (analista)

  • Propósito del Rol: Analista global que sube las ventas de todos los hoteles y calcula las comisiones.
  1. Cerrar sesión, e iniciar sesión como analista (password123).
  2. Carga de Excel: Vaya a Cargar Ventas. Suba el archivo demo_sales_data.xlsx.
  3. Prueba de Idempotencia: Intente subir el mismo archivo nuevamente. El sistema lo bloqueará mostrando el error: Error: Código de lote duplicado (Llave de idempotencia ya registrada), evitando pagos duplicados.
  4. Simulación y Cálculo: Vaya a la pestaña Simulación. Seleccione el período 2026-06. Desmarque la opción Modo Simulación para confirmar. Haga clic en Calcular Liquidaciones. Espere de 5 a 10 segundos a que responda el webhook de n8n. La tabla de liquidaciones se cargará con notas de auditoría de IA.

Paso C: La Experiencia del Líder Comercial Regional (lider_mde vs lider_ctg)

  • Propósito del Rol: Demuestra la seguridad regional. Los líderes comerciales solo pueden cargar ventas de su propio hotel.
  1. Cerrar sesión, e iniciar sesión como el Líder de Medellín lider_mde (password123).
  2. Límites de Carga Regional: Vaya a Cargar Ventas. Intente subir un archivo Excel que contenga registros del hotel de Cartagena (EST-CTG).
  3. Resultado Esperado: El sistema rechaza la carga debido a que el código del hotel EST-CTG está fuera de su jurisdicción autorizada de Medellín (EST-MDE).
  4. Cerrar sesión, e iniciar sesión como lider_ctg (password123). Suba un archivo de Cartagena; el sistema procesará la importación con éxito.

Paso D: La Experiencia del Colaborador (colaborador_mde vs colaborador_ctg)

  • Propósito del Rol: Aislamiento de datos del vendedor bajo políticas RLS.
  1. Cerrar sesión, e iniciar sesión como el Colaborador de Medellín colaborador_mde (password123).
  2. Aislamiento de Datos: Vaya a Historial y Metas. Solo visualizará sus metas e historial de ventas de Medellín.
  3. Cerrar sesión, e iniciar sesión como el Colaborador de Cartagena colaborador_ctg (password123).
  4. Resultado Esperado: Solo se devuelven los registros de Cartagena. La base de datos RLS filtra dinámicamente la consulta basándose en el ID de sesión del usuario.

Paso E: La Experiencia del Gerente de Hotel (gerente_mde vs gerente_ctg)

  • Propósito del Rol: Segregación regional para flujos de aprobación.
  1. Cerrar sesión, e iniciar sesión como el Gerente de Medellín gerente_mde (password123).
  2. Segregación de Aprobación: Vaya a Aprobaciones. Verá liquidaciones pendientes únicamente de Medellín. Rechace la liquidación ingresando el motivo: "Falta validar soporte físico".
  3. Cerrar sesión, e iniciar sesión como el Gerente de Cartagena gerente_ctg (password123).
  4. Resultado Esperado: Solo verá liquidaciones de Cartagena. Haga clic en Aprobar en la liquidación de colaborador_ctg; el estado cambia a aprobado y genera el log de auditoría.

Paso F: La Experiencia de Cumplimiento de Auditoría (consulta)

  • Propósito del Rol: Vista de cumplimiento global de solo lectura para auditoría.
  1. Cerrar sesión, e iniciar sesión como consulta (password123).
  2. Inspección de Solo Lectura: Explore Planes, Metas y el Tablero. Verifique que puede inspeccionar todos los datos de todas las regiones, pero 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. Cerrar sesión, e iniciar sesión como admin (password123).
  2. Explorador de Auditoría: Vaya a Auditoría. Seleccione un registro y valide los cambios antes y después en JSON, con datos confidenciales enmascarados como [REDACTED].
  3. Prueba de Inmutabilidad: Intente modificar o borrar algún registro de log de auditoría. El disparador de la base de datos bloqueará la operación lanzando un error.

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.