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

7.3 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 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 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)

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