# Live E2E Demonstration & Role Showcase Guide

**Variable Remuneration, Compensation, and Commissions System - Hoteles Estelar**

---

This guide outlines a comprehensive step-by-step E2E script for presenters. It showcases the application's role-based permissions, database Row-Level Security (RLS) isolation, multilingual language switcher, and n8n background workflow triggers.

---

## 1. System Role Permissions Matrix

The platform is designed with a strict Role-Based Access Control (RBAC) layer mapped to the following permissions:

| User Role | Navigation Access | Can Manage Plans? | Can Assign Goals? | Can Ingest Sales? | Can Run Settlement? | Can Approve/Reject? | Can View Audit Logs? |
| :--- | :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| **`admin`** | All tabs | Yes | Yes | Yes | Yes | Yes (Override) | Yes (diff panel) |
| **`director`** | Plans, Goals, Dashboard | Yes | Yes | No | No | No | No (403 Blocked) |
| **`analyst`** | Plans, Ingest, Calc, Dash | No | No | Yes | Yes | No | No (403 Blocked) |
| **`commercial_leader`** | Plans, Ingest, Approvals | No | No | Yes | No | Yes (Regional) | No (403 Blocked) |
| **`hotel_manager`** | Plans, Goals, Approvals | No | No | No | No | Yes (Regional) | No (403 Blocked) |
| **`auditor`** | Plans, Goals (Read-only) | No | No | No | No | No | No (403 Blocked) |
| **`collaborator`** | History (Personal only) | No | No | No | No | No | No (403 Blocked) |

---

## 2. Seeded Accounts & Credentials

Use these pre-configured accounts (all passwords are set to **`password123`**) to showcase different user views:

1. **System Admin (`admin`)**:
   - Username: `admin`
   - Email: `admin@estelar.com`
   - Hotel Scope: `Estelar Parque de la 93` (Global View)
   - Role: `admin`
2. **Planner / Executive View (`director`)**:
   - Username: `director`
   - Email: `director@estelar.com`
   - Hotel Scope: `Estelar Parque de la 93` (Global view for planning)
   - Role: `director`
3. **Finance Operations View (`analista`)**:
   - Username: `analista`
   - Email: `analista@estelar.com`
   - Hotel Scope: `Estelar Parque de la 93`
   - Role: `analyst`
4. **Hotel Managers (Regional Isolation)**:
   - **Medellin Manager**:
     - Username: `gerente_mde`
     - Email: `gerente.mde@estelar.com`
     - Hotel: `Estelar Medellin` (`EST-MDE`)
     - Role: `hotel_manager`
   - **Cartagena Manager**:
     - Username: `gerente_ctg`
     - Email: `gerente.ctg@estelar.com`
     - Hotel: `Estelar Cartagena` (`EST-CTG`)
     - Role: `hotel_manager`
5. **Commercial Leaders (Regional Isolation)**:
   - **Medellin Leader**:
     - Username: `lider_mde`
     - Email: `lider.mde@estelar.com`
     - Hotel: `Estelar Medellin` (`EST-MDE`)
     - Role: `commercial_leader`
   - **Cartagena Leader**:
     - Username: `lider_ctg`
     - Email: `lider.ctg@estelar.com`
     - Hotel: `Estelar Cartagena` (`EST-CTG`)
     - Role: `commercial_leader`
6. **Collaborators / Sellers (Personal Isolation)**:
   - **Medellin Collaborator**:
     - Username: `colaborador_mde`
     - Email: `colaborador.mde@estelar.com`
     - Hotel: `Estelar Medellin` (`EST-MDE`)
     - Role: `collaborator`
   - **Cartagena Collaborator**:
     - Username: `colaborador_ctg`
     - Email: `colaborador.ctg@estelar.com`
     - Hotel: `Estelar Cartagena` (`EST-CTG`)
     - Role: `collaborator`
7. **Auditor / Guest (`consulta`)**:
   - Username: `consulta`
   - Email: `consulta@estelar.com`
   - Role: `auditor`

---

## 3. Step-by-Step E2E Demo Walkthrough Script

### Step 1: Manage Compensation Plans & Rules
* **Objective**: Show how plans are created, configured, and automatically version-controlled when active.
* **Action**:
  1. Login as **`director`** (Planner view).
  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
* **Objective**: Define sales targets for sellers.
* **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)
* **Objective**: Showcase header validations, duplicate upload block (idempotency checks), and file upload features.
* **Action**:
  1. Logout, then login as **`analista`** (Finance Operations).
  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.
* **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:
     - **`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.
* **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.

### Step 6: Commercial Approvals (US-COM-008)
* **Objective**: Perform commercial leader/manager sign-off.
* **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`.

### Step 7: Localized AI Audit Notes & Language Switcher
* **Objective**: Showcase collaborator access, localized AI audit notes, and printing stylesheets.
* **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.

### Step 8: Executive Dashboard (US-COM-012)
* **Objective**: Showcase executive visual trends.
* **Action**:
  1. Logout, then login as **`director`** or **`analista`**.
  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.

### Step 9: System Audit Logs & JSON Diff (US-COM-011)
* **Objective**: Inspect security mutations and redaction details.
* **Action**:
  1. Logout, then login as **`admin`** (System Admin).
  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.
  5. If anyone tries to modify or delete logs, database RLS blocks them immediately.

---

## 4. Financial Reports Exporting (US-COM-013)

To test consolidations, run these API endpoints directly in your browser:
* **Consolidated Excel Sheet**: `/api/reports/export/excel?period=2026-06` (Downloads a multi-sheet spreadsheet).
* **Consolidated PDF HTML print view**: `/api/reports/export/pdf?period=2026-06` (Generates printable tabular views with signature sign-off lines).