# 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`
   - 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 (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`** (`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 (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 (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`** (`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: 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. 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 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`** (`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 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. 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 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 **`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 9: Executive Dashboard (Executive View)
* **Objective**: Showcase executive visual trends.
* **User**: **`director`** or **`analista`**
* **Action**:
  1. Logout, then login as **`director`** (`password123`).
  2. Navigate to **Dashboard** (Tablero).
  3. View the premium glassmorphic KPI cards and Recharts SVG charts comparing Bogota, Medellin, and Cartagena hotels.

### 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`** (`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.
  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).