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

177 lines
9.8 KiB
Markdown
Raw Blame History

# 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).
Reference in a new issue View git blame Copy permalink