diff --git a/docs/showcase/recruiter_guide_en.md b/docs/showcase/recruiter_guide_en.md new file mode 100644 index 0000000..39f376d --- /dev/null +++ b/docs/showcase/recruiter_guide_en.md @@ -0,0 +1,102 @@ +# Recruiter Showcase Guide: Hoteles Estelar Variable Remuneration System + +Welcome to the walkthrough guide for the **Hoteles Estelar Variable Remuneration & Commissions System**. This document outlines how a developer or recruiter can explore the system, understand how it resolves critical enterprise user stories, and verify its production-grade design and architecture. + +--- + +## 1. Project Overview & Tech Stack +The system is built as a highly secure, multi-tenant enterprise app designed to calculate, manage, and audit commercial sales commissions for the Hoteles Estelar franchise. + +### Technology Stack +- **Framework**: Next.js (App Router, Turbopack) +- **Database**: PostgreSQL with Prisma ORM +- **Security**: Database-level **Row-Level Security (RLS)** and cryptographic webhook signature validation +- **Automation**: n8n workflows for background calculations and AI-driven compliance auditing +- **Styling**: Vanilla CSS, configured with a high-fidelity dark mode, glassmorphism, and responsive dashboards + +--- + +## 2. Core User Stories & Technical Solutions + +### User Story 1: Strict Data Segregation (Row-Level Security) +> **As a** sales collaborator, +> **I want** to see only my own sales, goals, and commission settlements, +> **So that** I cannot view or tamper with other team members' financial information. +* **The Solution**: PostgreSQL RLS policies enforce segregation directly in the database. When any query runs, the system dynamically sets the session variable `app.current_user_role` and `app.current_user_id`. Even if a user calls APIs directly or tries to bypass the UI, the database returns `0` rows for other users or hotels. +* **Code Reference**: Check [rls_and_seed.sql](file:///home/gabogg/Proyects/semillero-special-hotel/prisma/rls_and_seed.sql) to see the SQL policies, and [auth.ts](file:///home/gabogg/Proyects/semillero-special-hotel/src/lib/auth.ts) to see how session contexts are injected. + +### User Story 2: Plan Versioning & Rules Configuration +> **As an** administrator or commercial analyst, +> **I want** to create commission plans and rules, and ensure that editing active plans creates a new version instead of changing history, +> **So that** historical calculations remain auditable and unchanged. +* **The Solution**: The system implements plan locking. When a plan is in `DRAFT`, rules can be edited. When it is marked `ACTIVE`, it becomes read-only. If an administrator tries to toggle or update an active plan, the system clones the plan, increments the `version` (e.g. `v1` -> `v2`), and sets the old plan's validity end date. +* **Code Reference**: Check plan clone logic in [/api/plans/route.ts](file:///home/gabogg/Proyects/semillero-special-hotel/src/app/api/plans/route.ts). + +### User Story 3: Atomic Bulk Sales Import +> **As a** commercial leader, +> **I want** to import Excel files containing monthly sales results, +> **So that** sales are automatically processed and verified, returning clear validation errors if the file is inconsistent. +* **The Solution**: Excel sheets are parsed and checked against strict validation constraints (non-existent users, negative amounts, invalid periods, incorrect hotel codes). The validation is **atomic**—if even one row fails, the entire transaction is rolled back. The UI presents an inconsistency panel highlighting exactly which cells failed. +* **Code Reference**: View sheet parsing in [/api/sales/import/route.ts](file:///home/gabogg/Proyects/semillero-special-hotel/src/app/api/sales/import/route.ts). + +### User Story 4: Automated Calculations & Retroactive Clawbacks +> **As a** finance analyst, +> **I want** commission calculations to run automatically via n8n and adjust for returned or cancelled sales from previous months, +> **So that** payouts are correct and negative adjustments are deducted. +* **The Solution**: The n8n calculation workflow triggers the settlement engine. The engine queries previous months' sales. If a sale was returned/cancelled, it applies a retroactive delta adjustment (clawback) to the current month's payout. +* **Code Reference**: See settlement computations in [/api/settlements/calculate/route.ts](file:///home/gabogg/Proyects/semillero-special-hotel/src/app/api/settlements/calculate/route.ts). + +### User Story 5: Immutable Auditing Log +> **As an** external auditor, +> **I want** to see a complete history of all user logins, plan modifications, and approvals, +> **So that** I can verify that logs cannot be edited or deleted by anyone. +* **The Solution**: The `audit_logs` table has database triggers that intercept and block all `UPDATE` and `DELETE` queries. The Admin dashboard features an interactive Audit Logs Explorer displaying side-by-side JSON diff panels showing what changed. +* **Code Reference**: View audit logs logic in [/api/audit-logs/route.ts](file:///home/gabogg/Proyects/semillero-special-hotel/src/app/api/audit-logs/route.ts). + +--- + +## 3. Step-by-Step Exploration Guide + +You can access the walkthrough version of the app at: **`https://hotels-demo.gaboggamer.online`** + +### Step A: The Collaborator Experience (Zero-Trust Boundaries) +1. **Login** as a collaborator: + - **Username**: `colab_mde_1` + - **Password**: `password123` +2. **Observe**: The dashboard page loads. You can see your own metrics (sales amount, goals, achievement percentage). +3. **Check Segregation**: Navigate to the **Historial** and **Metas** tabs. You will only see records associated with `colab_mde_1` at `Estelar Medellin (EST-MDE)`. You cannot see any other collaborator's goals or payouts. +4. **Try to Bypass**: Notice there is no "Cargar Ventas" (Upload Sales) or "Planes" (Plans) link in the header. The UI actively hides admin-level controls. + +### Step B: The Regional Manager Experience (Approval Flow) +1. **Log out** and **Login** as the Antioquia Hotel Manager: + - **Username**: `gerente_mde` + - **Password**: `password123` +2. **Observe**: The manager sees dashboard metrics summarizing their hotel's total sales. +3. **Approval Segregation**: Navigate to the **Aprobaciones** (Approvals) tab. You will see a list of pending settlements for June 2026. Note that you can only see collaborators belonging to your hotel (`EST-MDE`). You cannot see or approve settlements for Bogota or Cartagena. +4. **Approve a Settlement**: Click "Aprobar" on a pending settlement. It will immediately transition to `APPROVED` and write an immutable audit log entry. +5. **Reject with Reason**: Click "Rechazar" on another settlement. The UI prompts you for a rejection reason. Enter `"Falta validar soporte físico"` and submit. The status transitions to `REJECTED`. + +### Step C: The Administrator Experience (Plans & Auditing) +1. **Log out** and **Login** as the System Admin: + - **Username**: `admin` + - **Password**: `password123` +2. **Global View**: The Admin sees all metrics across all regions on the dashboard. +3. **Plan Versioning**: Navigate to the **Planes** tab. + - Click on **Nuevo Plan** to open the creation modal. + - Create a draft plan named `Plan Piloto Q3` with code `PLAN-Q3` and validity dates. + - Click the "Reglas" icon next to it and configure tiered commission brackets (e.g. 0% rate up to 90% achievement, 2% rate up to 100% achievement). + - Toggle the status to **ACTIVO**. + - Click toggle **AGAIN** on the active plan. You will see the version increment to `v2` and the old version status set to `INACTIVO`. +4. **Audit Logs Explorer**: Navigate to the **Auditoría** tab. + - Click on any log row (e.g. `APPROVE` or `CREATE`). + - The side-by-side JSON diff panel appears, displaying the precise changes made in that transaction. + - Try to delete or modify a log entry; the database returns an error, preventing tampering. + +--- + +## 4. Visual Aesthetics & Polish +When presenting this to a recruiter, be sure to highlight: +- **Glassmorphism**: Elegant card borders, subtle shadows, and dark translucent backdrops. +- **Micro-animations**: Smooth hover transitions on tables, buttons, and form elements. +- **Dynamic Charts**: Interactive charts that auto-adjust with filters, rendering region comparisons and historic performance trends. +- **Language Switcher**: Dynamically switches the UI and AI-generated text between English and Spanish. diff --git a/docs/showcase/recruiter_guide_es.md b/docs/showcase/recruiter_guide_es.md new file mode 100644 index 0000000..70b3914 --- /dev/null +++ b/docs/showcase/recruiter_guide_es.md @@ -0,0 +1,102 @@ +# 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.