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

10 KiB
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
    • 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 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).