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

9.8 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
    • 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 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).