docs: add recruiter showcase guides in English and Spanish

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.

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.