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_en.md

9.4 KiB
Raw Blame History

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 variables 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 to see the SQL policies, and 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.

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.

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.

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.

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)

  • Role Purpose: Represents the commercial planner who configures commissions and rules globally.
  1. Login: Go to the login screen, enter username director and password password123, then click Iniciar Sesión.
  2. Plan Creation: In the top navigation header, click on Planes (Plans).
  3. Action: Click Nuevo Plan, enter details (e.g., Name: Plan Especial Q3 2026, Code: EST-Q3-26, Type: COMMISSION, Start/End Dates covering June to August 2026), and click Guardar.
  4. Configure Rules: Find the plan in the table, click the Reglas icon, configure tiered commission brackets (e.g. 0% to 90% achievement = 0% rate, 90.01% to 110% achievement = 2.5% rate), and click Guardar Reglas.
  5. Activate & Test Versioning: Return to the plans list. Click the toggle to set the status to ACTIVO. Now, click the edit toggle button again. Notice the system blocks direct modification and instead clones the plan to v2 in draft mode while archiving v1 as inactive. This preserves historical calculations.
  6. Assign Quota: Go to the Metas (Goals) tab. Click Asignar Meta, select INDIVIDUAL, choose colaborador_mde for period 2026-06, set target to 100000, and click Guardar Meta.

Step B: The Global Finance Operations Experience (analista)

  • Role Purpose: Represents the finance analyst who uploads sales lists and triggers calculation runs globally.
  1. Logout, then login as analista (password123).
  2. Excel Ingestion: Go to Cargar Ventas (Upload Sales). Drag and drop demo_sales_data.xlsx into the loading box. Notice the success message listing imported records.
  3. Idempotency Check: Drag and drop the same file again. The system blocks the upload with a warning: Error: Código de lote duplicado (Llave de idempotencia ya registrada), showing duplicate transaction prevention.
  4. Simulation & Calculation: Go to the Simulación tab. Select period 2026-06. Uncheck Modo Simulación to commit calculations. Click Calcular Liquidaciones. Wait 5-10 seconds for the n8n webhook response. The settlements table renders with AI-generated audit observations.

Step C: The Regional Commercial Leader Experience (lider_mde vs lider_ctg)

  • Role Purpose: Demonstrates regional boundaries. Leaders can only load sales for their own hotel.
  1. Logout, then login as the Medellin Commercial Leader lider_mde (password123).
  2. Regional Ingestion Boundaries: Go to Cargar Ventas. Attempt to upload an Excel file containing Cartagena (EST-CTG) records.
  3. Expected Result: The system rejects the file with a validation error stating that the hotel code EST-CTG is outside your permitted Medellin jurisdiction (EST-MDE).
  4. 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)

  • Role Purpose: Shows complete personal data segregation using Row-Level Security.
  1. Logout, then login as the Medellin Collaborator colaborador_mde (password123).
  2. Personal Data Isolation: Go to Historial and Metas. Observe that you only see Medellin (EST-MDE) records and sales targets. All other collaborators' data is hidden.
  3. Logout, then login as the Cartagena Collaborator colaborador_ctg (password123).
  4. Expected Result: Only Cartagena (EST-CTG) records are returned. The database RLS filters the query dynamically based on the session user ID, returning zero results for other hotels.

Step E: The Regional Manager Experience (gerente_mde vs gerente_ctg)

  • Role Purpose: Demonstrates regional segregation in approval workflows.
  1. Logout, then login as the Medellin Hotel Manager gerente_mde (password123).
  2. Approval Segregation: Navigate to the Aprobaciones (Approvals) tab. You see pending settlements only for Medellin. Click Rechazar on the Medellin settlement, enter rejection reason: "Falta validar soporte físico", and submit. The status transitions to REJECTED.
  3. Logout, then login as the Cartagena Hotel Manager gerente_ctg (password123).
  4. Expected Result: You only see Cartagena pending settlements. Click Aprobar on the Cartagena settlement; its status transitions to APPROVED, which triggers an audit log.

Step F: The Read-Only Auditor Compliance Experience (consulta)

  • Role Purpose: Verification of auditing read-only visibility.
  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)

  • Role Purpose: Master control view and security log auditing.
  1. Logout, then login as admin (password123).
  2. Audit Explorer: Navigate to the Auditoría tab. Select any log. The side-by-side JSON diff panel displays the exact changes made. Notice that sensitive fields like password_hash are redacted as [REDACTED].
  3. Immutability Check: Try to edit or delete any log entry. The database trigger blocks the mutation immediately, throwing an error.

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.