# 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) * **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](../../prisma/rls_and_seed.sql) to see the SQL policies, and [auth.ts](../../src/lib/auth.ts) to see how session contexts are injected. ### User Story 2: Plan Versioning & Rules Configuration * **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](../../src/app/api/plans/route.ts). ### User Story 3: Atomic Bulk Sales Import * **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](../../src/app/api/sales/import/route.ts). ### User Story 4: Automated Calculations & Retroactive Clawbacks * **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](../../src/app/api/settlements/calculate/route.ts). ### User Story 5: Immutable Auditing Log * **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](../../src/app/api/audit-logs/route.ts). --- ## 3. Step-by-Step Exploration Guide (All 10 Showcase Roles) You can access the walkthrough version of the app at: **`https://hotels-demo.gaboggamer.online`** ### Step A: The Planner Experience (`director`) 1. **Login** as **`director`** (`password123`). 2. **Action**: Navigate to **Planes** (Plans). Create a new draft plan, add tiered rules, and toggle it to **ACTIVO**. Attempt to toggle it again; witness the automatic versioning cloning the plan to `v2` to protect historical calculations. 3. **Goal Assignment**: Go to the **Metas** (Goals) tab and assign a sales quota of `100000` to collaborator `colaborador_mde` for `2026-06`. ### Step B: The Global Finance Operations Experience (`analista`) 1. **Logout**, then login as **`analista`** (`password123`). 2. **Excel Ingestion**: Go to **Cargar Ventas** (Upload Sales). Drag and drop [demo_sales_data.xlsx](../../public/templates/demo_sales_data.xlsx). Notice it uploads successfully. Try uploading the same file again; it blocks the request due to duplicate idempotency keys. 3. **Calculation & Simulation**: Go to the **Simulación** tab. Execute the commission calculations for `2026-06`. Observe the calculated settlements with automatic AI-generated audit notes. ### Step C: The Regional Commercial Leader Experience (`lider_mde` vs `lider_ctg`) 1. **Logout**, then login as the Medellin Commercial Leader **`lider_mde`** (`password123`). 2. **Regional Ingestion Boundaries**: Go to **Cargar Ventas**. Attempt to upload a sales file containing Cartagena (`EST-CTG`) records. The system blocks the upload because a regional leader's scope is strictly bounded to their assigned hotel (`EST-MDE`). 3. **Logout**, then login as **`lider_ctg`** (`password123`). Upload a Cartagena sales file; notice it succeeds only for Cartagena. ### Step D: The Collaborator Experience (`colaborador_mde` vs `colaborador_ctg`) 1. **Logout**, then login as the Medellin Collaborator **`colaborador_mde`** (`password123`). 2. **Personal Data Isolation**: Go to **Historial** and **Metas**. You can only see your own records for Medellin. 3. **Logout**, then login as the Cartagena Collaborator **`colaborador_ctg`** (`password123`). You only see Cartagena records. Complete data segregation is enforced. ### Step E: The Regional Manager Experience (`gerente_mde` vs `gerente_ctg`) 1. **Logout**, then login as the Medellin Hotel Manager **`gerente_mde`** (`password123`). 2. **Approval Segregation**: Navigate to the **Aprobaciones** (Approvals) tab. You will see a list of pending settlements only for Medellin. Reject a settlement with reason: `"Falta validar soporte físico"`. 3. **Logout**, then login as the Cartagena Hotel Manager **`gerente_ctg`** (`password123`). You only see Cartagena settlements. Approve the settlement for `colaborador_ctg`. ### Step F: The Read-Only Auditor Compliance Experience (`consulta`) 1. **Logout**, then login as **`consulta`** (`password123`). 2. **Read-Only Inspection**: Navigate through Plans, Goals, and the Dashboard. Notice that while you can view all data globally across all hotels, all editing, uploading, and approval buttons are completely disabled or hidden. ### Step G: The System Administrator Experience (`admin`) 1. **Logout**, then login as **`admin`** (`password123`). 2. **Audit Explorer**: Navigate to the **Auditoría** tab. Select any log to inspect the side-by-side JSON diff. Note that sensitive values (e.g. passwords) are redacted as `[REDACTED]`. --- ## 4. Visual Aesthetics & Polish When presenting this, 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.