diff --git a/docs/DEMO_SHOWCASE_GUIDE.md b/docs/DEMO_SHOWCASE_GUIDE.md index 7f6f385..faa2840 100644 --- a/docs/DEMO_SHOWCASE_GUIDE.md +++ b/docs/DEMO_SHOWCASE_GUIDE.md @@ -79,90 +79,103 @@ Use these pre-configured accounts (all passwords are set to **`password123`**) t 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 +### 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`** (Planner view). + 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 +### 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 (US-COM-004) +### 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`** (Finance Operations). + 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: Run Settlement Calculation & AI Anomaly Detection -* **Objective**: Trigger the external n8n settlement engine. +### 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. 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: + 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 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. +### 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`** (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. + 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 6: Commercial Approvals (US-COM-008) -* **Objective**: Perform commercial leader/manager sign-off. +### 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. 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`. + 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 7: Localized AI Audit Notes & Language Switcher -* **Objective**: Showcase collaborator access, localized AI audit notes, and printing stylesheets. +### 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 **`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. + 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 8: Executive Dashboard (US-COM-012) +### Step 9: Executive Dashboard (Executive View) * **Objective**: Showcase executive visual trends. +* **User**: **`director`** or **`analista`** * **Action**: - 1. Logout, then login as **`director`** or **`analista`**. + 1. Logout, then login as **`director`** (`password123`). 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. + 3. View the premium glassmorphic KPI cards and Recharts SVG charts comparing Bogota, Medellin, and Cartagena hotels. -### Step 9: System Audit Logs & JSON Diff (US-COM-011) +### 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`** (System Admin). + 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. diff --git a/docs/showcase/recruiter_guide_en.md b/docs/showcase/recruiter_guide_en.md index 4d24bd7..2ccad14 100644 --- a/docs/showcase/recruiter_guide_en.md +++ b/docs/showcase/recruiter_guide_en.md @@ -19,97 +19,68 @@ The system is built as a highly secure, multi-tenant enterprise app designed to ## 2. Core User Stories & Technical Solutions ### User Story 1: Strict Data Segregation (Row-Level Security) -> **As a** sales collaborator, -> **I want** to see only my own sales, goals, and commission settlements, -> **So that** I cannot view or tamper with other team members' financial information. * **The Solution**: PostgreSQL RLS policies enforce segregation directly in the database. When any query runs, the system dynamically sets the session variable `app.current_user_role` and `app.current_user_id`. Even if a user calls APIs directly or tries to bypass the UI, the database returns `0` rows for other users or hotels. * **Code Reference**: Check [rls_and_seed.sql](../../prisma/rls_and_seed.sql) to see the SQL policies, and [auth.ts](../../src/lib/auth.ts) to see how session contexts are injected. ### User Story 2: Plan Versioning & Rules Configuration -> **As an** administrator or commercial analyst, -> **I want** to create commission plans and rules, and ensure that editing active plans creates a new version instead of changing history, -> **So that** historical calculations remain auditable and unchanged. * **The Solution**: The system implements plan locking. When a plan is in `DRAFT`, rules can be edited. When it is marked `ACTIVE`, it becomes read-only. If an administrator tries to toggle or update an active plan, the system clones the plan, increments the `version` (e.g. `v1` -> `v2`), and sets the old plan's validity end date. * **Code Reference**: Check plan clone logic in [/api/plans/route.ts](../../src/app/api/plans/route.ts). ### User Story 3: Atomic Bulk Sales Import -> **As a** commercial leader, -> **I want** to import Excel files containing monthly sales results, -> **So that** sales are automatically processed and verified, returning clear validation errors if the file is inconsistent. * **The Solution**: Excel sheets are parsed and checked against strict validation constraints (non-existent users, negative amounts, invalid periods, incorrect hotel codes). The validation is **atomic**—if even one row fails, the entire transaction is rolled back. The UI presents an inconsistency panel highlighting exactly which cells failed. * **Code Reference**: View sheet parsing in [/api/sales/import/route.ts](../../src/app/api/sales/import/route.ts). ### User Story 4: Automated Calculations & Retroactive Clawbacks -> **As a** finance analyst, -> **I want** commission calculations to run automatically via n8n and adjust for returned or cancelled sales from previous months, -> **So that** payouts are correct and negative adjustments are deducted. * **The Solution**: The n8n calculation workflow triggers the settlement engine. The engine queries previous months' sales. If a sale was returned/cancelled, it applies a retroactive delta adjustment (clawback) to the current month's payout. * **Code Reference**: See settlement computations in [/api/settlements/calculate/route.ts](../../src/app/api/settlements/calculate/route.ts). ### User Story 5: Immutable Auditing Log -> **As an** external auditor, -> **I want** to see a complete history of all user logins, plan modifications, and approvals, -> **So that** I can verify that logs cannot be edited or deleted by anyone. * **The Solution**: The `audit_logs` table has database triggers that intercept and block all `UPDATE` and `DELETE` queries. The Admin dashboard features an interactive Audit Logs Explorer displaying side-by-side JSON diff panels showing what changed. * **Code Reference**: View audit logs logic in [/api/audit-logs/route.ts](../../src/app/api/audit-logs/route.ts). --- -## 3. Step-by-Step Exploration Guide +## 3. Step-by-Step Exploration Guide (All 10 Showcase Roles) You can access the walkthrough version of the app at: **`https://hotels-demo.gaboggamer.online`** -### Step A: The Collaborator Experience (Zero-Trust Boundaries & Multi-Hotel Segregation) -1. **Login** as the Medellin collaborator: - - **Username**: `colaborador_mde` - - **Password**: `password123` -2. **Observe**: The dashboard page loads. You can see your own metrics (sales amount, goals, achievement percentage) for `Estelar Medellin (EST-MDE)`. -3. **Verify Segregation**: Navigate to the **Historial** and **Metas** tabs. You will only see records associated with `colaborador_mde`. You cannot see any other collaborator's goals or payouts. -4. **Test Cross-Hotel Isolation**: - - Log out and log in as the Cartagena collaborator: - - **Username**: `colaborador_ctg` - - **Password**: `password123` - - **Observe**: You now only see data for `Estelar Cartagena (EST-CTG)`. The database restricts your session so that you have absolutely zero exposure to Medellin (`EST-MDE`) records, despite sharing the same collaborator role. -5. **Try to Bypass**: Notice there is no "Cargar Ventas" (Upload Sales) or "Planes" (Plans) link in the header. The UI actively hides admin-level controls. +### Step A: The Planner Experience (`director`) +1. **Login** as **`director`** (`password123`). +2. **Action**: Navigate to **Planes** (Plans). Create a new draft plan, add tiered rules, and toggle it to **ACTIVO**. Attempt to toggle it again; witness the automatic versioning cloning the plan to `v2` to protect historical calculations. +3. **Goal Assignment**: Go to the **Metas** (Goals) tab and assign a sales quota of `100000` to collaborator `colaborador_mde` for `2026-06`. -### Step B: The Regional Manager & Leader Experience (Approval Segregation) -1. **Log out** and **Login** as the Medellin Hotel Manager: - - **Username**: `gerente_mde` - - **Password**: `password123` -2. **Observe**: The manager sees dashboard metrics summarizing total sales for `Estelar Medellin (EST-MDE)`. -3. **Approval Segregation**: Navigate to the **Aprobaciones** (Approvals) tab. You will see pending settlements for June 2026. Note that you can only see collaborators belonging to `EST-MDE` (like `colaborador_mde`). -4. **Verify Cross-Hotel Isolation**: - - Log out and log in as the Cartagena Hotel Manager: - - **Username**: `gerente_ctg` - - **Password**: `password123` - - **Observe**: The dashboard and the **Aprobaciones** tab now show only data for `Estelar Cartagena (EST-CTG)`. You cannot view, approve, or reject settlements for Medellin or Bogota. -5. **Leader Level Separation**: - - Log out and log in as the Medellin Commercial Leader: - - **Username**: `lider_mde` - - **Password**: `password123` - - **Observe**: The commercial leader has read access to their hotel's records and can upload sales only for `EST-MDE`, but has zero access to Cartagena (`EST-CTG`) or Bogota (`EST-P93`) data. -6. **Action Flow**: Under a manager account, approve or reject a pending settlement. Approve transitions status to `APPROVED` and writes an immutable audit log. Reject requires entering a rejection reason (e.g. `"Falta validar soporte físico"`) and transitions status to `REJECTED`. +### Step B: The Global Finance Operations Experience (`analista`) +1. **Logout**, then login as **`analista`** (`password123`). +2. **Excel Ingestion**: Go to **Cargar Ventas** (Upload Sales). Drag and drop [demo_sales_data.xlsx](../../public/templates/demo_sales_data.xlsx). Notice it uploads successfully. Try uploading the same file again; it blocks the request due to duplicate idempotency keys. +3. **Calculation & Simulation**: Go to the **Simulación** tab. Execute the commission calculations for `2026-06`. Observe the calculated settlements with automatic AI-generated audit notes. -### Step C: The Administrator Experience (Plans & Auditing) -1. **Log out** and **Login** as the System Admin: - - **Username**: `admin` - - **Password**: `password123` -2. **Global View**: The Admin sees all metrics across all regions/hotels on the dashboard. -3. **Plan Versioning**: Navigate to the **Planes** tab. - - Click on **Nuevo Plan** to open the creation modal. - - Create a draft plan named `Plan Piloto Q3` with code `PLAN-Q3` and validity dates. - - Click the "Reglas" icon next to it and configure tiered commission brackets (e.g. 0% rate up to 90% achievement, 2% rate up to 100% achievement). - - Toggle the status to **ACTIVO**. - - Click toggle **AGAIN** on the active plan. You will see the version increment to `v2` and the old version status set to `INACTIVO`. -4. **Audit Logs Explorer**: Navigate to the **Auditoría** tab. - - Click on any log row (e.g. `APPROVE` or `CREATE`). - - The side-by-side JSON diff panel appears, displaying the precise changes made in that transaction. - - Try to delete or modify a log entry; the database returns an error, preventing tampering. +### Step C: The Regional Commercial Leader Experience (`lider_mde` vs `lider_ctg`) +1. **Logout**, then login as the Medellin Commercial Leader **`lider_mde`** (`password123`). +2. **Regional Ingestion Boundaries**: Go to **Cargar Ventas**. Attempt to upload a sales file containing Cartagena (`EST-CTG`) records. The system blocks the upload because a regional leader's scope is strictly bounded to their assigned hotel (`EST-MDE`). +3. **Logout**, then login as **`lider_ctg`** (`password123`). Upload a Cartagena sales file; notice it succeeds only for Cartagena. + +### Step D: The Collaborator Experience (`colaborador_mde` vs `colaborador_ctg`) +1. **Logout**, then login as the Medellin Collaborator **`colaborador_mde`** (`password123`). +2. **Personal Data Isolation**: Go to **Historial** and **Metas**. You can only see your own records for Medellin. +3. **Logout**, then login as the Cartagena Collaborator **`colaborador_ctg`** (`password123`). You only see Cartagena records. Complete data segregation is enforced. + +### Step E: The Regional Manager Experience (`gerente_mde` vs `gerente_ctg`) +1. **Logout**, then login as the Medellin Hotel Manager **`gerente_mde`** (`password123`). +2. **Approval Segregation**: Navigate to the **Aprobaciones** (Approvals) tab. You will see a list of pending settlements only for Medellin. Reject a settlement with reason: `"Falta validar soporte físico"`. +3. **Logout**, then login as the Cartagena Hotel Manager **`gerente_ctg`** (`password123`). You only see Cartagena settlements. Approve the settlement for `colaborador_ctg`. + +### Step F: The Read-Only Auditor Compliance Experience (`consulta`) +1. **Logout**, then login as **`consulta`** (`password123`). +2. **Read-Only Inspection**: Navigate through Plans, Goals, and the Dashboard. Notice that while you can view all data globally across all hotels, all editing, uploading, and approval buttons are completely disabled or hidden. + +### Step G: The System Administrator Experience (`admin`) +1. **Logout**, then login as **`admin`** (`password123`). +2. **Audit Explorer**: Navigate to the **Auditoría** tab. Select any log to inspect the side-by-side JSON diff. Note that sensitive values (e.g. passwords) are redacted as `[REDACTED]`. --- ## 4. Visual Aesthetics & Polish -When presenting this to a recruiter, be sure to highlight: +When presenting this, highlight: - **Glassmorphism**: Elegant card borders, subtle shadows, and dark translucent backdrops. - **Micro-animations**: Smooth hover transitions on tables, buttons, and form elements. - **Dynamic Charts**: Interactive charts that auto-adjust with filters, rendering region comparisons and historic performance trends. diff --git a/docs/showcase/recruiter_guide_es.md b/docs/showcase/recruiter_guide_es.md index 53f2604..0e644e6 100644 --- a/docs/showcase/recruiter_guide_es.md +++ b/docs/showcase/recruiter_guide_es.md @@ -10,8 +10,8 @@ El sistema está construido como una aplicación empresarial multi-inquilino alt ### Stack Tecnológico - **Framework**: Next.js (App Router, Turbopack) - **Base de Datos**: PostgreSQL con Prisma ORM -- **Seguridad**: Seguridad a Nivel de Fila (**Row-Level Security - RLS**) en la base de datos y validación criptográfica de firmas de webhooks -- **Automatización**: Flujos de trabajo de n8n para cálculos en segundo plano y auditoría de cumplimiento impulsada por IA +- **Seguridad**: Seguridad a Nivel de Fila (**Row-Level Security - RLS**) en la base de datos y validación de firmas de webhooks +- **Automatización**: Flujos de trabajo de n8n para cálculos en segundo plano y auditoría impulsada por IA - **Estilos**: CSS nativo (Vanilla CSS), configurado con un modo oscuro de alta fidelidad, glassmorphism y paneles adaptables --- @@ -19,98 +19,69 @@ El sistema está construido como una aplicación empresarial multi-inquilino alt ## 2. Historias de Usuario Principales y Soluciones Técnicas ### Historia de Usuario 1: Segregación Estricta de Datos (Row-Level Security) -> **Como** colaborador de ventas, -> **Quiero** ver únicamente mis propias ventas, metas y liquidaciones de comisiones, -> **Para que** no pueda ver ni alterar la información financiera de otros miembros del equipo. * **La Solución**: Las políticas de RLS de PostgreSQL imponen la segregación directamente en el motor de base de datos. Cuando se ejecuta cualquier consulta, el sistema establece dinámicamente la variable de sesión `app.current_user_role` y `app.current_user_id`. Incluso si un usuario realiza solicitudes directas a la API o intenta eludir la interfaz de usuario, la base de datos retorna `0` registros para otros usuarios u hoteles. * **Referencia de Código**: Revise [rls_and_seed.sql](../../prisma/rls_and_seed.sql) para ver las políticas SQL, y [auth.ts](../../src/lib/auth.ts) para ver cómo se inyectan los contextos de sesión. ### Historia de Usuario 2: Control de Versiones de Planes y Configuración de Reglas -> **Como** administrador o analista comercial, -> **Quiero** crear planes de compensación y reglas, y asegurar que la edición de planes activos genere una nueva versión en lugar de modificar el historial, -> **Para que** los cálculos históricos sigan siendo auditables e inalterados. * **La Solución**: El sistema implementa el bloqueo de planes. Cuando un plan está en estado `DRAFT` (Borrador), se pueden editar sus reglas. Cuando se marca como `ACTIVE` (Activo), pasa a ser de solo lectura. Si un administrador intenta alternar o actualizar un plan activo, el sistema clona el plan, incrementa el campo `version` (por ejemplo, `v1` -> `v2`) y establece la fecha de fin de validez del plan anterior. * **Referencia de Código**: Revise la lógica de clonación de planes en [/api/plans/route.ts](../../src/app/api/plans/route.ts). ### Historia de Usuario 3: Importación Masiva Atómica de Ventas -> **Como** líder comercial, -> **Quiero** importar archivos Excel con los resultados de ventas mensuales, -> **Para que** las ventas se procesen y validen automáticamente, retornando errores claros si el archivo presenta inconsistencias. * **La Solución**: Las hojas de Excel se procesan y validan contra restricciones estrictas (usuarios inexistentes, montos negativos, períodos inválidos, códigos de hotel incorrectos). La validación es **atómica**: si una sola fila falla, toda la transacción se revierte. La interfaz de usuario presenta un panel de inconsistencias que detalla con precisión qué celdas fallaron. * **Referencia de Código**: Vea el análisis de archivos en [/api/sales/import/route.ts](../../src/app/api/sales/import/route.ts). ### Historia de Usuario 4: Cálculos Automatizados y Deducciones Retroactivas (Clawbacks) -> **Como** analista de finanzas, -> **Quiero** que los cálculos de comisiones se ejecuten automáticamente mediante n8n y se ajusten por devoluciones o ventas canceladas de meses anteriores, -> **Para que** los pagos sean correctos y se deduzcan los saldos negativos correspondientes. * **La Solución**: El flujo de cálculo de n8n activa el motor de liquidación. El motor consulta las ventas de los meses anteriores. Si una venta fue devuelta o cancelada, aplica un ajuste de delta retroactivo (clawback) en la liquidación del mes en curso, restándolo del pago final. * **Referencia de Código**: Vea los cálculos de liquidaciones en [/api/settlements/calculate/route.ts](../../src/app/api/settlements/calculate/route.ts). ### Historia de Usuario 5: Registro de Auditoría Inmutable -> **Como** auditor externo, -> **Quiero** ver un historial completo de todos los inicios de sesión de usuario, modificaciones de planes y aprobaciones, -> **Para** verificar que nadie pueda editar ni eliminar los registros de auditoría. -* **La Solución**: La tabla `audit_logs` cuenta con reglas y disparadores de base de datos que interceptan y bloquean cualquier consulta de tipo `UPDATE` o `DELETE`. El panel de administración incluye un Explorador de Registros de Auditoría interactivo con un panel de comparación JSON en paralelo que muestra exactamente qué cambió. +* **La Solución**: La tabla `audit_logs` cuenta con disparadores de base de datos que interceptan y bloquean cualquier consulta de tipo `UPDATE` o `DELETE`. El panel de administración incluye un Explorador de Registros de Auditoría interactivo con un panel de comparación JSON en paralelo que muestra exactamente qué cambió. * **Referencia de Código**: Vea la lógica de los registros de auditoría en [/api/audit-logs/route.ts](../../src/app/api/audit-logs/route.ts). --- -## 3. Guía de Exploración Paso a Paso +## 3. Guía de Exploración Paso a Paso (Los 10 Roles de Demostración) Puede acceder a la versión de demostración de la aplicación en: **`https://hotels-demo.gaboggamer.online`** -### Paso A: La Experiencia del Colaborador (Límites de Seguridad RLS y Segregación entre Hoteles) -1. **Inicie sesión** como el colaborador de Medellín: - - **Usuario**: `colaborador_mde` - - **Contraseña**: `password123` -2. **Observe**: Se carga el panel. Puede ver sus propias métricas (monto de ventas, metas, porcentaje de logro) asociadas a `Estelar Medellín (EST-MDE)`. -3. **Verifique la Segregación**: Navegue a las pestañas **Historial** y **Metas**. Solo verá los registros asociados a `colaborador_mde`. No podrá ver las metas ni liquidaciones de ningún otro colaborador. -4. **Pruebe el Aislamiento entre Hoteles**: - - Cierre sesión e inicie sesión como el colaborador de Cartagena: - - **Usuario**: `colaborador_ctg` - - **Contraseña**: `password123` - - **Observe**: Ahora solo visualizará los datos de `Estelar Cartagena (EST-CTG)`. La base de datos restringe la sesión de tal forma que tiene exposición nula a los registros de Medellín (`EST-MDE`), a pesar de compartir el mismo rol de colaborador. -5. **Intente Eludir**: Note que no hay enlaces de "Cargar Ventas" ni de "Planes" en el encabezado. La interfaz de usuario oculta los controles reservados a roles de supervisión. +### Paso A: La Experiencia de Planificación (`director`) +1. **Inicie sesión** como **`director`** (`password123`). +2. **Acción**: Navegue a **Planes**. Cree un plan borrador, asigne reglas y active el plan. Intente modificarlo para ver el versionado automático que clona el plan a la versión `v2`. +3. **Asignar Metas**: Vaya a **Metas** y configure una cuota de ventas de `100000` para `colaborador_mde` para el período `2026-06`. -### Paso B: La Experiencia del Gerente y Líder de Hotel (Segregación de Aprobaciones) -1. **Cierre sesión** e **inicie sesión** como el Gerente del Hotel Medellín: - - **Usuario**: `gerente_mde` - - **Contraseña**: `password123` -2. **Observe**: El gerente visualiza las métricas agregadas correspondientes a las ventas totales de su hotel (`EST-MDE`). -3. **Segregación de Aprobación**: Navegue a la pestaña **Aprobaciones**. Verá un listado de liquidaciones pendientes para junio de 2026. Note que solo se muestran los colaboradores de su hotel (`EST-MDE`, como `colaborador_mde`). -4. **Verifique el Aislamiento entre Hoteles**: - - Cierre sesión e inicie sesión como el Gerente del Hotel Cartagena: - - **Usuario**: `gerente_ctg` - - **Contraseña**: `password123` - - **Observe**: El panel de control y la pestaña de **Aprobaciones** ahora muestran únicamente los datos de `Estelar Cartagena (EST-CTG)`. No es posible visualizar, aprobar ni rechazar liquidaciones de Medellín o Bogotá. -5. **Separación de Nivel de Líder**: - - Cierre sesión e inicie sesión como el Líder Comercial de Medellín: - - **Usuario**: `lider_mde` - - **Contraseña**: `password123` - - **Observe**: El líder comercial tiene acceso de lectura a los registros de su hotel y puede cargar ventas únicamente para `EST-MDE`, pero tiene acceso nulo a los datos de Cartagena (`EST-CTG`) o Bogotá (`EST-P93`). -6. **Flujo de Acción**: Bajo una cuenta de gerente, apruebe o rechace una liquidación pendiente. Aprobar cambia el estado a `APPROVED` y escribe un log de auditoría inmutable. Rechazar requiere ingresar un motivo de rechazo (ej. `"Falta validar soporte físico"`) y cambia el estado a `REJECTED`. +### Paso B: La Experiencia de Operaciones Financieras Globales (`analista`) +1. **Cierre sesión**, e inicie sesión como **`analista`** (`password123`). +2. **Carga de Excel**: Vaya a **Cargar Ventas**. Suba el archivo [demo_sales_data.xlsx](../../public/templates/demo_sales_data.xlsx). Intente volver a subir el mismo archivo y observe el bloqueo automático debido a la validación de clave de idempotencia. +3. **Simulación y Cálculo**: Vaya a **Simulación**. Ejecute las comisiones de `2026-06` sin el modo simulador para persistir. Observe las liquidaciones calculadas y las notas de auditoría generadas por IA. -### Paso C: La Experiencia del Administrador (Planes y Auditoría) -1. **Cierre sesión** e **inicie sesión** como Administrador del Sistema: - - **Usuario**: `admin` - - **Contraseña**: `password123` -2. **Vista Global**: El administrador visualiza métricas de todas las regiones/hoteles en su panel principal. -3. **Control de Versiones de Planes**: Navegue a la pestaña **Planes**. - - Haga clic en **Nuevo Plan** para abrir el formulario de creación. - - Cree un borrador de plan llamado `Plan Piloto Q3` con código `PLAN-Q3` y vigencias correspondientes. - - Haga clic en el ícono de "Reglas" a la derecha y configure los rangos de comisiones (ej. tasa de 0% hasta 90% de logro, tasa de 2% hasta 100% de logro). - - Cambie el estado a **ACTIVO**. - - Vuelva a hacer clic en el botón de alternancia **OTRA VEZ** en el plan activo. Verá que la versión se incrementa a `v2` y la versión anterior pasa a estado `INACTIVO`. -4. **Explorador de Auditoría**: Navegue a la pestaña **Auditoría**. - - Haga clic en cualquier fila de log (ej. `APPROVE` o `CREATE`). - - Aparecerá el panel de comparación JSON en paralelo, mostrando los cambios precisos de esa transacción. - - Intente modificar o borrar algún registro; el motor de base de datos devolverá un error, impidiendo la alteración del historial. +### Paso C: La Experiencia del Líder Comercial Regional (`lider_mde` vs `lider_ctg`) +1. **Cierre sesión**, e inicie sesión como el Líder de Medellín **`lider_mde`** (`password123`). +2. **Aislamiento de Carga de Archivos**: Vaya a **Cargar Ventas**. Intente subir un archivo con ventas del hotel de Cartagena (`EST-CTG`). El sistema bloqueará la acción porque el alcance de un líder está estrictamente restringido a su hotel asignado (`EST-MDE`). +3. **Cierre sesión**, e inicie sesión como **`lider_ctg`** (`password123`). Suba un archivo de Cartagena; el sistema le permitirá hacerlo con éxito solo para su hotel. + +### Paso D: La Experiencia del Colaborador (`colaborador_mde` vs `colaborador_ctg`) +1. **Cierre sesión**, e inicie sesión como el Colaborador de Medellín **`colaborador_mde`** (`password123`). +2. **Aislamiento de Datos Personales**: Vaya a **Historial** y **Metas**. Solo verá sus propios registros de Medellín. +3. **Cierre sesión**, e inicie sesión como el Colaborador de Cartagena **`colaborador_ctg`** (`password123`). Solo verá los registros de Cartagena. Se garantiza la segregación absoluta de la información. + +### Paso E: La Experiencia del Gerente de Hotel (`gerente_mde` vs `gerente_ctg`) +1. **Cierre sesión**, e inicie sesión como el Gerente de Medellín **`gerente_mde`** (`password123`). +2. **Segregación de Aprobaciones**: Vaya a **Aprobaciones**. Verá liquidaciones pendientes de Medellín. Rechace la liquidación con el motivo: `"Falta validar soporte físico"`. +3. **Cierre sesión**, e inicie sesión como el Gerente de Cartagena **`gerente_ctg`** (`password123`). Verá liquidaciones pendientes de Cartagena. Apruebe la liquidación de `colaborador_ctg`. + +### Paso F: La Experiencia de Cumplimiento de Auditoría (`consulta`) +1. **Cierre sesión**, e inicie sesión como **`consulta`** (`password123`). +2. **Auditoría de Solo Lectura**: Explore Planes, Metas y el Tablero. Verifique que puede inspeccionar todos los datos de todos los hoteles, pero todos los botones de creación, edición, carga y aprobación están ocultos o deshabilitados. + +### Paso G: La Experiencia de Administrador del Sistema (`admin`) +1. **Cierre sesión**, e inicie sesión como **`admin`** (`password123`). +2. **Explorador de Auditoría**: Vaya a **Auditoría**. Seleccione un registro y verifique la comparación de cambios en JSON, con datos confidenciales enmascarados como `[REDACTED]`. --- ## 4. Detalles Estéticos y Experiencia de Usuario -Al presentar este proyecto a un reclutador, recuerde destacar: +Al presentar este proyecto, recuerde destacar: - **Glassmorphism**: Bordes y sombras sutiles con fondos oscuros traslúcidos. - **Micro-animaciones**: Transiciones suaves al pasar el cursor por tablas, botones y formularios. - **Gráficos Dinámicos**: Gráficos interactivos que se ajustan con filtros, comparando regiones e históricos. -- **Selector de Idioma**: Alterna la interfaz y las observaciones de IA entre inglés y español al instante. \ No newline at end of file +- **Selector de Idioma**: Alterna la interfaz y las observaciones de IA entre inglés y español al instante.