# 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](../../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 > **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](../../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](../../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](../../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](../../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.