gabogg/semillero-special-hotel
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: expand showcase and recruiter guides to demonstrate all 10 user accounts

Browse source
This commit is contained in:
Luis Gabriel Ramos Robles 2026-06-14 01:21:35 +00:00
parent c2da4d0eaf
commit 39b9dfb38d
3 changed files with 123 additions and 168 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

97
docs/DEMO_SHOWCASE_GUIDE.md
View file

@ -79,90 +79,103 @@ Use these pre-configured accounts (all passwords are set to **`password123`**) t
7. **Auditor / Guest (`consulta`)**:
- Username: `consulta`
- Email: `consulta@estelar.com`
- Hotel Scope: `Estelar Parque de la 93` (Global View)
- Role: `auditor`
---
## 3. Step-by-Step E2E Demo Walkthrough Script
### Step 1: Manage Compensation Plans & Rules
### Step 1: Manage Compensation Plans & Rules (Planner View)
* **Objective**: Show how plans are created, configured, and automatically version-controlled when active.
* **User**: **`director`** (Planner / Executive View)
* **Action**:
1. Login as **`director`** (Planner view).
1. Login as **`director`** (`password123`).
2. Navigate to **Commission Plans** (Planes de Comisión).
3. Click **Nuevo Plan**, enter details (e.g. Plan name, code, type), and click **Guardar Plan**.
4. Find the plan, click **Configurar Reglas**, add a tier (e.g. 0% to 120% achievement = 2% commission rate), and save.
5. Click **Activar** on the plan. Notice status changes to `ACTIVE` (Activo).
6. Click **Inactivar (Versión)** to edit the active plan. Notice that the system *preserves the original plan version 1 history* and automatically clones a new version record (`Version: 2`) in draft mode! This showcases strict version auditing.
### Step 2: Assign Quotas and Goals
### Step 2: Assign Quotas and Goals (Planner View)
* **Objective**: Define sales targets for sellers.
* **User**: **`director`** (Planner / Executive View)
* **Action**:
1. Still logged in as **`director`**, navigate to **Commercial Goals** (Metas Comerciales).
2. Select target type `INDIVIDUAL`, pick `colaborador_mde`, enter period `2026-06`, set the target amount to `100000`, and click **Guardar Meta**.
### Step 3: Excel Sales File Ingestion (US-COM-004)
### Step 3: Excel Sales File Ingestion (Finance Operations View)
* **Objective**: Showcase header validations, duplicate upload block (idempotency checks), and file upload features.
* **User**: **`analista`** (Finance Operations View)
* **Action**:
1. Logout, then login as **`analista`** (Finance Operations).
1. Logout, then login as **`analista`** (`password123`).
2. Navigate to **Ingest Sales** (Cargar Ventas).
3. Drag and drop the generated demo spreadsheet: [demo_sales_data.xlsx](file:///home/gabogg/Proyects/semillero-special-hotel/public/templates/demo_sales_data.xlsx) into the loading box, or select it manually.
4. Notice the upload progress screen. Once n8n finishes background parsing, the status turns green: `Carga exitosa`.
5. Attempt to drag-and-drop the *same file again*. The system immediately alerts: `Error: Llave de idempotencia duplicada. Este lote ya ha sido procesado.` showing protection against double-payments.
### Step 4: Run Settlement Calculation & AI Anomaly Detection
* **Objective**: Trigger the external n8n settlement engine.
### Step 4: Regional Leader File Ingestion Validation (Regional Isolation)
* **Objective**: Prove that regional leaders cannot ingest sales for other hotels.
* **User**: **`lider_mde`** (Medellin Commercial Leader)
* **Action**:
1. Navigate to **Simulation** (Simulación) as `analista`.
2. Enter Period `2026-06`. Uncheck *Simulator Mode* to commit records to the database.
3. Click **Calculate**.
4. The page queries n8n. Wait 5-10 seconds. The webhook invokes the calculate-settlement nodes.
5. The results table renders:
1. Logout, then login as **`lider_mde`** (`password123`).
2. Navigate to **Ingest Sales** (Cargar Ventas).
3. Attempt to upload a sales file containing Cartagena (`EST-CTG`) records.
4. Observe the system error showing that the upload is rejected because the leader's regional boundary is strictly restricted to Medellin (`EST-MDE`).
5. Logout, then login as **`lider_ctg`** (`password123`). Upload a Cartagena sales file; notice it succeeds only for Cartagena.
### Step 5: Run Settlement Calculation & AI Anomaly Detection (Finance Operations View)
* **Objective**: Trigger the external n8n settlement engine.
* **User**: **`analista`** (Finance Operations View)
* **Action**:
1. Logout, then login as **`analista`** (`password123`).
2. Navigate to **Simulation** (Simulación).
3. Enter Period `2026-06`. Uncheck *Simulator Mode* to commit records to the database.
4. Click **Calculate**.
5. The page queries n8n. Wait 5-10 seconds. The webhook invokes the calculate-settlement nodes.
6. The results table renders:
- **`colaborador_mde`**: standard commission calculated, audit state marked as `Audited`.
- **`colaborador_ctg`**: standard commission calculated for the Cartagena region.
### Step 5: Row-Level Security Isolation (The Core Tenant Segregation)
* **Objective**: Showcase that users in the same roles but working in different hotels cannot cross-access data.
### Step 6: Collaborator Personal Segregation (Row-Level Security)
* **Objective**: Showcase that collaborators are isolated to their own personal data and hotel.
* **Users**: **`colaborador_mde`** (Medellin Collaborator) vs **`colaborador_ctg`** (Cartagena Collaborator)
* **Action**:
1. Logout, then login as **`colaborador_mde`** (Medellin Collaborator).
2. Navigate to **History** (Historial) and **Goals** (Metas).
3. Notice you *only* see Medellin (`EST-MDE`) sales/goals.
4. Logout, then login as **`colaborador_ctg`** (Cartagena Collaborator).
5. Navigate to **History** and **Goals**. Notice you *only* see Cartagena (`EST-CTG`) sales/goals. Medellin records are completely invisible.
6. Logout, then login as **`gerente_mde`** (Medellin Manager).
7. Navigate to **Approvals** (Aprobaciones). You only see pending settlements for `colaborador_mde` (Medellin).
8. Logout, then login as **`gerente_ctg`** (Cartagena Manager).
9. Navigate to **Approvals**. You only see pending settlements for `colaborador_ctg` (Cartagena). You cannot see or approve Medellin records. This demonstrates robust multi-hotel security at the database row level.
1. Logout, then login as **`colaborador_mde`** (`password123`).
2. Navigate to **History** (Historial) and **Goals** (Metas). Notice you *only* see Medellin (`EST-MDE`) sales/goals.
3. Logout, then login as **`colaborador_ctg`** (`password123`).
4. Navigate to **History** and **Goals**. Notice you *only* see Cartagena (`EST-CTG`) sales/goals. Medellin records are completely invisible. This demonstrates robust personal multi-hotel security at the database row level.
### Step 6: Commercial Approvals (US-COM-008)
* **Objective**: Perform commercial leader/manager sign-off.
### Step 7: Regional Manager Approvals (Regional Segregation)
* **Objective**: Perform commercial leader/manager sign-off with regional isolation.
* **Users**: **`gerente_mde`** (Medellin Manager) vs **`gerente_ctg`** (Cartagena Manager)
* **Action**:
1. Under `gerente_ctg` (Cartagena Manager), click **Approve** on the settlement. The status changes to `APPROVED` and generates an audit log.
2. Logout, then login as `gerente_mde` (Medellin Manager). Click **Reject** on the Medellin settlement, and provide a reason: `"Falta validar soporte físico"`. The status transitions to `REJECTED`.
1. Logout, then login as **`gerente_mde`** (`password123`).
2. Navigate to **Approvals** (Aprobaciones). Notice you only see pending settlements for Medellin. Click **Reject** on the Medellin settlement, and provide a reason: `"Falta validar soporte físico"`. The status transitions to `REJECTED`.
3. Logout, then login as **`gerente_ctg`** (`password123`).
4. Navigate to **Approvals**. Notice you only see pending settlements for Cartagena. Click **Approve** on the settlement. The status changes to `APPROVED` and generates an audit log.
### Step 7: Localized AI Audit Notes & Language Switcher
* **Objective**: Showcase collaborator access, localized AI audit notes, and printing stylesheets.
### Step 8: Read-Only Auditor Compliance (Read-only Compliance View)
* **Objective**: Verify that auditors can view all data globally but cannot edit or approve anything.
* **User**: **`consulta`** (Auditor / Guest)
* **Action**:
1. Logout, then login as **`colaborador_ctg`** (Collaborator/Seller).
2. Navigate to **History** (Historial).
3. Find the approved record for `2026-06`, and click **Ver Notas** under the AI Audit column.
4. The localized notes panel expands: `Nota de auditoría en Español: Todo correcto.` (or warning notes).
5. Go to the top-right header language dropdown, select **EN**.
6. Instantly, the UI text translates, and the AI audit note updates dynamically: `Audit note in English: All correct.`
7. Click **Download PDF** (Descargar PDF). Notice that the browser print dialog mounts a clean, page-break optimized stylesheet with no navigation bar, specifically designed for paper filing.
1. Logout, then login as **`consulta`** (`password123`).
2. Navigate through Plans, Goals, and the Dashboard. Verify you can view all data globally across all hotels.
3. Notice that all editing, uploading, and approval buttons are completely disabled or hidden.
### Step 8: Executive Dashboard (US-COM-012)
### Step 9: Executive Dashboard (Executive View)
* **Objective**: Showcase executive visual trends.
* **User**: **`director`** or **`analista`**
* **Action**:
1. Logout, then login as **`director`** or **`analista`**.
1. Logout, then login as **`director`** (`password123`).
2. Navigate to **Dashboard** (Tablero).
3. View the premium glassmorphic KPI cards: Total paid commissions, average achievement rate progress circle, and budget utilization bar.
4. View the Recharts SVG line-area charts showing the monthly payout trends vs budget caps, and the comparison bar chart comparing Bogota, Medellin, and Cartagena hotels.
3. View the premium glassmorphic KPI cards and Recharts SVG charts comparing Bogota, Medellin, and Cartagena hotels.
### Step 9: System Audit Logs & JSON Diff (US-COM-011)
### Step 10: System Audit Logs & JSON Diff (System Admin View)
* **Objective**: Inspect security mutations and redaction details.
* **User**: **`admin`** (System Admin View)
* **Action**:
1. Logout, then login as **`admin`** (System Admin).
1. Logout, then login as **`admin`** (`password123`).
2. Navigate to **Audit Logs** (Auditoría).
3. Select any log row. The side-by-side JSON panel displays the exact snapshot of the database fields before and after the action.
4. Security audit: Notice that password hashes or base salaries are redacted as `[REDACTED]`, keeping user credentials private.

93
docs/showcase/recruiter_guide_en.md
View file

@ -19,97 +19,68 @@ The system is built as a highly secure, multi-tenant enterprise app designed to
## 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
## 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 Collaborator Experience (Zero-Trust Boundaries & Multi-Hotel Segregation)
1. **Login** as the Medellin collaborator:
- **Username**: `colaborador_mde`
- **Password**: `password123`
2. **Observe**: The dashboard page loads. You can see your own metrics (sales amount, goals, achievement percentage) for `Estelar Medellin (EST-MDE)`.
3. **Verify Segregation**: Navigate to the **Historial** and **Metas** tabs. You will only see records associated with `colaborador_mde`. You cannot see any other collaborator's goals or payouts.
4. **Test Cross-Hotel Isolation**:
- Log out and log in as the Cartagena collaborator:
- **Username**: `colaborador_ctg`
- **Password**: `password123`
- **Observe**: You now only see data for `Estelar Cartagena (EST-CTG)`. The database restricts your session so that you have absolutely zero exposure to Medellin (`EST-MDE`) records, despite sharing the same collaborator role.
5. **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 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 Regional Manager & Leader Experience (Approval Segregation)
1. **Log out** and **Login** as the Medellin Hotel Manager:
- **Username**: `gerente_mde`
- **Password**: `password123`
2. **Observe**: The manager sees dashboard metrics summarizing total sales for `Estelar Medellin (EST-MDE)`.
3. **Approval Segregation**: Navigate to the **Aprobaciones** (Approvals) tab. You will see pending settlements for June 2026. Note that you can only see collaborators belonging to `EST-MDE` (like `colaborador_mde`).
4. **Verify Cross-Hotel Isolation**:
- Log out and log in as the Cartagena Hotel Manager:
- **Username**: `gerente_ctg`
- **Password**: `password123`
- **Observe**: The dashboard and the **Aprobaciones** tab now show only data for `Estelar Cartagena (EST-CTG)`. You cannot view, approve, or reject settlements for Medellin or Bogota.
5. **Leader Level Separation**:
- Log out and log in as the Medellin Commercial Leader:
- **Username**: `lider_mde`
- **Password**: `password123`
- **Observe**: The commercial leader has read access to their hotel's records and can upload sales only for `EST-MDE`, but has zero access to Cartagena (`EST-CTG`) or Bogota (`EST-P93`) data.
6. **Action Flow**: Under a manager account, approve or reject a pending settlement. Approve transitions status to `APPROVED` and writes an immutable audit log. Reject requires entering a rejection reason (e.g. `"Falta validar soporte físico"`) and transitions status to `REJECTED`.
### 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 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/hotels 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.
### 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 to a recruiter, be sure to highlight:
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.

101
docs/showcase/recruiter_guide_es.md
View file

@ -10,8 +10,8 @@ El sistema está construido como una aplicación empresarial multi-inquilino alt
### 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
- **Seguridad**: Seguridad a Nivel de Fila (**Row-Level Security - RLS**) en la base de datos y validación de firmas de webhooks
- **Automatización**: Flujos de trabajo de n8n para cálculos en segundo plano y auditoría impulsada por IA
- **Estilos**: CSS nativo (Vanilla CSS), configurado con un modo oscuro de alta fidelidad, glassmorphism y paneles adaptables
---
@ -19,98 +19,69 @@ El sistema está construido como una aplicación empresarial multi-inquilino alt
## 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](../../prisma/rls_and_seed.sql) para ver las políticas SQL, y [auth.ts](../../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](../../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](../../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](../../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ó.
* **La Solución**: La tabla `audit_logs` cuenta con 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](../../src/app/api/audit-logs/route.ts).
---
## 3. Guía de Exploración Paso a Paso
## 3. Guía de Exploración Paso a Paso (Los 10 Roles de Demostración)
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 y Segregación entre Hoteles)
1. **Inicie sesión** como el colaborador de Medellín:
- **Usuario**: `colaborador_mde`
- **Contraseña**: `password123`
2. **Observe**: Se carga el panel. Puede ver sus propias métricas (monto de ventas, metas, porcentaje de logro) asociadas a `Estelar Medellín (EST-MDE)`.
3. **Verifique la Segregación**: Navegue a las pestañas **Historial** y **Metas**. Solo verá los registros asociados a `colaborador_mde`. No podrá ver las metas ni liquidaciones de ningún otro colaborador.
4. **Pruebe el Aislamiento entre Hoteles**:
- Cierre sesión e inicie sesión como el colaborador de Cartagena:
- **Usuario**: `colaborador_ctg`
- **Contraseña**: `password123`
- **Observe**: Ahora solo visualizará los datos de `Estelar Cartagena (EST-CTG)`. La base de datos restringe la sesión de tal forma que tiene exposición nula a los registros de Medellín (`EST-MDE`), a pesar de compartir el mismo rol de colaborador.
5. **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 A: La Experiencia de Planificación (`director`)
1. **Inicie sesión** como **`director`** (`password123`).
2. **Acción**: Navegue a **Planes**. Cree un plan borrador, asigne reglas y active el plan. Intente modificarlo para ver el versionado automático que clona el plan a la versión `v2`.
3. **Asignar Metas**: Vaya a **Metas** y configure una cuota de ventas de `100000` para `colaborador_mde` para el período `2026-06`.
### Paso B: La Experiencia del Gerente y Líder de Hotel (Segregación de Aprobaciones)
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 (`EST-MDE`).
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`, como `colaborador_mde`).
4. **Verifique el Aislamiento entre Hoteles**:
- Cierre sesión e inicie sesión como el Gerente del Hotel Cartagena:
- **Usuario**: `gerente_ctg`
- **Contraseña**: `password123`
- **Observe**: El panel de control y la pestaña de **Aprobaciones** ahora muestran únicamente los datos de `Estelar Cartagena (EST-CTG)`. No es posible visualizar, aprobar ni rechazar liquidaciones de Medellín o Bogotá.
5. **Separación de Nivel de Líder**:
- Cierre sesión e inicie sesión como el Líder Comercial de Medellín:
- **Usuario**: `lider_mde`
- **Contraseña**: `password123`
- **Observe**: El líder comercial tiene acceso de lectura a los registros de su hotel y puede cargar ventas únicamente para `EST-MDE`, pero tiene acceso nulo a los datos de Cartagena (`EST-CTG`) o Bogotá (`EST-P93`).
6. **Flujo de Acción**: Bajo una cuenta de gerente, apruebe o rechace una liquidación pendiente. Aprobar cambia el estado a `APPROVED` y escribe un log de auditoría inmutable. Rechazar requiere ingresar un motivo de rechazo (ej. `"Falta validar soporte físico"`) y cambia el estado a `REJECTED`.
### Paso B: La Experiencia de Operaciones Financieras Globales (`analista`)
1. **Cierre sesión**, e inicie sesión como **`analista`** (`password123`).
2. **Carga de Excel**: Vaya a **Cargar Ventas**. Suba el archivo [demo_sales_data.xlsx](../../public/templates/demo_sales_data.xlsx). Intente volver a subir el mismo archivo y observe el bloqueo automático debido a la validación de clave de idempotencia.
3. **Simulación y Cálculo**: Vaya a **Simulación**. Ejecute las comisiones de `2026-06` sin el modo simulador para persistir. Observe las liquidaciones calculadas y las notas de auditoría generadas por IA.
### 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/hoteles 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.
### Paso C: La Experiencia del Líder Comercial Regional (`lider_mde` vs `lider_ctg`)
1. **Cierre sesión**, e inicie sesión como el Líder de Medellín **`lider_mde`** (`password123`).
2. **Aislamiento de Carga de Archivos**: Vaya a **Cargar Ventas**. Intente subir un archivo con ventas del hotel de Cartagena (`EST-CTG`). El sistema bloqueará la acción porque el alcance de un líder está estrictamente restringido a su hotel asignado (`EST-MDE`).
3. **Cierre sesión**, e inicie sesión como **`lider_ctg`** (`password123`). Suba un archivo de Cartagena; el sistema le permitirá hacerlo con éxito solo para su hotel.
### Paso D: La Experiencia del Colaborador (`colaborador_mde` vs `colaborador_ctg`)
1. **Cierre sesión**, e inicie sesión como el Colaborador de Medellín **`colaborador_mde`** (`password123`).
2. **Aislamiento de Datos Personales**: Vaya a **Historial** y **Metas**. Solo verá sus propios registros de Medellín.
3. **Cierre sesión**, e inicie sesión como el Colaborador de Cartagena **`colaborador_ctg`** (`password123`). Solo verá los registros de Cartagena. Se garantiza la segregación absoluta de la información.
### Paso E: La Experiencia del Gerente de Hotel (`gerente_mde` vs `gerente_ctg`)
1. **Cierre sesión**, e inicie sesión como el Gerente de Medellín **`gerente_mde`** (`password123`).
2. **Segregación de Aprobaciones**: Vaya a **Aprobaciones**. Verá liquidaciones pendientes de Medellín. Rechace la liquidación con el motivo: `"Falta validar soporte físico"`.
3. **Cierre sesión**, e inicie sesión como el Gerente de Cartagena **`gerente_ctg`** (`password123`). Verá liquidaciones pendientes de Cartagena. Apruebe la liquidación de `colaborador_ctg`.
### Paso F: La Experiencia de Cumplimiento de Auditoría (`consulta`)
1. **Cierre sesión**, e inicie sesión como **`consulta`** (`password123`).
2. **Auditoría de Solo Lectura**: Explore Planes, Metas y el Tablero. Verifique que puede inspeccionar todos los datos de todos los hoteles, pero todos los botones de creación, edición, carga y aprobación están ocultos o deshabilitados.
### Paso G: La Experiencia de Administrador del Sistema (`admin`)
1. **Cierre sesión**, e inicie sesión como **`admin`** (`password123`).
2. **Explorador de Auditoría**: Vaya a **Auditoría**. Seleccione un registro y verifique la comparación de cambios en JSON, con datos confidenciales enmascarados como `[REDACTED]`.
---
## 4. Detalles Estéticos y Experiencia de Usuario
Al presentar este proyecto a un reclutador, recuerde destacar:
Al presentar este proyecto, 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.
- **Selector de Idioma**: Alterna la interfaz y las observaciones de IA entre inglés y español al instante.