diff --git a/docs/DEMO_SHOWCASE_GUIDE.md b/docs/DEMO_SHOWCASE_GUIDE.md index faa2840..f23822e 100644 --- a/docs/DEMO_SHOWCASE_GUIDE.md +++ b/docs/DEMO_SHOWCASE_GUIDE.md @@ -89,97 +89,121 @@ Use these pre-configured accounts (all passwords are set to **`password123`**) t ### 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. +* **Action Details**: + 1. Open the browser and navigate to the application URL. + 2. Login with username **`director`** and password **`password123`**. + 3. In the top navigation header, click on the **Planes** (Plans) tab. + 4. Click the **Nuevo Plan** button to launch the creation modal. + 5. Fill in the modal form fields: + - **Name**: `Plan Especial Q3 2026` + - **Code**: `EST-Q3-26` + - **Type**: Select `COMMISSION` from the dropdown. + - **Start/End Dates**: Select a validity range covering `2026-06-01` to `2026-08-31`. + 6. Click **Guardar Plan** to submit. + 7. Locate the new plan in the table. Click the **Reglas** icon next to its name. + 8. In the rules drawer/view, add two brackets: + - Tier 1: `0% - 90%` achievement range = `0%` commission rate. Click **Agregar Tramo**. + - Tier 2: `90.01% - 110%` achievement range = `2.5%` commission rate. Click **Agregar Tramo**. + 9. Click **Guardar Reglas** to persist rules. + 10. Return to the plans list and click the status switch toggle to activate the plan. Observe that the status immediately changes to `ACTIVE`. + 11. Now, click the edit toggle button again on the active plan. + 12. **Expected System Behavior**: The system blocks direct inline changes to active rules. Instead, it clones the entire plan, incrementing its version to `v2` in draft state, while setting `v1` to inactive. This prevents retroactive calculations from being manipulated. ### 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**. +* **Action Details**: + 1. Still logged in as **`director`**, click the **Metas** (Goals) link in the navigation header. + 2. Click **Asignar Meta** (Assign Goal) to open the goal configuration modal. + 3. Fill in the form: + - **Target Type**: Select `INDIVIDUAL`. + - **Collaborator**: Select `colaborador_mde` from the user dropdown. + - **Period**: Enter `2026-06`. + - **Target Sales Amount**: Enter `100000`. + 4. Click **Guardar Meta**. + 5. **Expected System Behavior**: A success toast appears. The goal is stored, automatically bounded to the collaborator's hotel scope (`EST-MDE`), laying the groundwork for regional RLS segregation. ### Step 3: Excel Sales File Ingestion (Finance Operations View) -* **Objective**: Showcase header validations, duplicate upload block (idempotency checks), and file upload features. +* **Objective**: Ingest monthly sales results with header validations, idempotency check, and transactional rollbacks. * **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. +* **Action Details**: + 1. Click the **Cerrar Sesión** button in the top right. + 2. Login with username **`analista`** and password **`password123`**. + 3. Click the **Cargar Ventas** (Upload Sales) tab in the header. + 4. Drag and drop the template spreadsheet: [demo_sales_data.xlsx](file:///home/gabogg/Proyects/semillero-special-hotel/public/templates/demo_sales_data.xlsx) into the file drop target zone, or click the zone to upload it via file selector. + 5. **Expected System Behavior**: The system parses the spreadsheet, performing atomic validations (user existence check, positive numeric checks, regional validations). Once successful, a green success banner appears: `Carga exitosa`. + 6. **Idempotency Test**: Select and drop the *same file again* immediately. + 7. **Expected System Behavior**: The UI highlights a red error block: `Error: Código de lote duplicado (Llave de idempotencia ya registrada)`. The system has blocked the ingestion and rolled back the transaction to prevent double payout calculation. -### Step 4: Regional Leader File Ingestion Validation (Regional Isolation) -* **Objective**: Prove that regional leaders cannot ingest sales for other hotels. +### Step 4: Regional Leader Ingestion Validation (Regional Isolation) +* **Objective**: Show that regional boundaries block leaders from loading 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. +* **Action Details**: + 1. Logout, then login as the Medellin Commercial Leader **`lider_mde`** and password **`password123`**. + 2. Navigate to **Cargar Ventas** (Upload Sales). + 3. Attempt to upload a custom Excel file containing rows with the Cartagena hotel code (`EST-CTG`). + 4. **Expected System Behavior**: The upload fails with a red warning stating: `Error de Validación: El código de hotel EST-CTG no coincide con su jurisdicción permitida (EST-MDE)`. The transaction is rolled back, demonstrating multi-tenant regional ingestion security. + 5. Logout, then login as **`lider_ctg`** (`password123`). Go to **Cargar Ventas** and upload a valid file containing Cartagena `EST-CTG` rows. The upload completes successfully. ### Step 5: Run Settlement Calculation & AI Anomaly Detection (Finance Operations View) -* **Objective**: Trigger the external n8n settlement engine. +* **Objective**: Trigger n8n webhook calculation runs and review the generated AI audit observations. * **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. +* **Action Details**: + 1. Logout, and login again as **`analista`** (`password123`). + 2. Click on **Liquidación** (Settlement) in the top navigation. + 3. Select period **`2026-06`**. + 4. **Crucial**: Ensure the **Modo Simulación** (Simulation Mode) checkbox is UNCHECKED to persist the calculation. + 5. Click **Calcular Liquidaciones** (Calculate Settlements). + 6. **Expected System Behavior**: A loading indicator appears while the application calls the n8n webhook backend. Wait 5-10 seconds. The webhook triggers the settlement computation workflows. The UI refreshes: + - **`colaborador_mde`**: Payout is calculated. + - **`colaborador_ctg`**: Payout calculated. If any sale amount exceeds normal parameters, a warning icon appears under the AI Audit column. Click the icon to view the audit observations: `Warning: Anomalous high sale detected`. ### Step 6: Collaborator Personal Segregation (Row-Level Security) -* **Objective**: Showcase that collaborators are isolated to their own personal data and hotel. +* **Objective**: Verify that sellers have access only to their personal goals and history. * **Users**: **`colaborador_mde`** (Medellin Collaborator) vs **`colaborador_ctg`** (Cartagena Collaborator) -* **Action**: +* **Action Details**: 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. + 2. Navigate to **Historial** (History) and **Metas** (Goals). Verify you can see only your personal Medellin records. 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. + 4. Navigate to **Historial** and **Metas**. + 5. **Expected System Behavior**: The tables display only Cartagena records. Even if a user attempts to fetch Medellin records via direct API requests, the PostgreSQL RLS policy filters the query dynamically based on the session ID, returning zero results. ### 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**: +* **Action Details**: 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. + 2. Navigate to **Aprobaciones** (Approvals). Notice that only the pending Medellin settlement is visible. + 3. Click **Rechazar** (Reject) on the Medellin settlement. In the rejection modal, enter: `"Falta validar soporte físico"` and click submit. The status transitions to `REJECTED`. + 4. Logout, then login as **`gerente_ctg`** (`password123`). + 5. Navigate to **Aprobaciones**. Notice that only the Cartagena settlement is visible. + 6. Click **Aprobar** (Approve) on the Cartagena 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**: +* **Action Details**: 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. + 2. Navigate through **Planes**, **Metas**, and the **Tablero** (Dashboard). + 3. **Expected System Behavior**: The auditor can see plans and goals for all three regions (Bogota, Medellin, Cartagena) on the tables. However, all "Nuevo Plan", "Asignar Meta", "Aprobar", or "Cargar Ventas" buttons are completely hidden or disabled, ensuring read-only compliance. ### Step 9: Executive Dashboard (Executive View) * **Objective**: Showcase executive visual trends. * **User**: **`director`** or **`analista`** -* **Action**: +* **Action Details**: 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. + 3. **Expected System Behavior**: The dashboard renders KPI cards showing total payouts, average achievement percentage, and budget cap bars. Recharts interactive SVG charts display monthly sales trends and comparative performance between the Medellin, Bogota, 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**: +* **Action Details**: 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. **Expected System Behavior**: Sensitive fields like `password_hash` or base salaries are redacted as `[REDACTED]`. + 5. **Immutability Check**: Try to edit or delete any log entry. The database trigger blocks the mutation immediately, throwing an error. --- diff --git a/docs/showcase/recruiter_guide_en.md b/docs/showcase/recruiter_guide_en.md index 2ccad14..02ac89f 100644 --- a/docs/showcase/recruiter_guide_en.md +++ b/docs/showcase/recruiter_guide_en.md @@ -19,7 +19,7 @@ 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) -* **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. +* **The Solution**: PostgreSQL RLS policies enforce segregation directly in the database. When any query runs, the system dynamically sets the session variables `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 @@ -45,37 +45,52 @@ The system is built as a highly secure, multi-tenant enterprise app designed to You can access the walkthrough version of the app at: **`https://hotels-demo.gaboggamer.online`** ### 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`. +- **Role Purpose**: Represents the commercial planner who configures commissions and rules globally. +1. **Login**: Go to the login screen, enter username **`director`** and password **`password123`**, then click **Iniciar Sesión**. +2. **Plan Creation**: In the top navigation header, click on **Planes** (Plans). +3. **Action**: Click **Nuevo Plan**, enter details (e.g., Name: `Plan Especial Q3 2026`, Code: `EST-Q3-26`, Type: `COMMISSION`, Start/End Dates covering June to August 2026), and click **Guardar**. +4. **Configure Rules**: Find the plan in the table, click the **Reglas** icon, configure tiered commission brackets (e.g. 0% to 90% achievement = 0% rate, 90.01% to 110% achievement = 2.5% rate), and click **Guardar Reglas**. +5. **Activate & Test Versioning**: Return to the plans list. Click the toggle to set the status to **ACTIVO**. Now, click the edit toggle button again. Notice the system blocks direct modification and instead clones the plan to **`v2`** in draft mode while archiving **`v1`** as inactive. This preserves historical calculations. +6. **Assign Quota**: Go to the **Metas** (Goals) tab. Click **Asignar Meta**, select `INDIVIDUAL`, choose `colaborador_mde` for period `2026-06`, set target to `100000`, and click **Guardar Meta**. ### Step B: The Global Finance Operations Experience (`analista`) +- **Role Purpose**: Represents the finance analyst who uploads sales lists and triggers calculation runs globally. 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. +2. **Excel Ingestion**: Go to **Cargar Ventas** (Upload Sales). Drag and drop [demo_sales_data.xlsx](../../public/templates/demo_sales_data.xlsx) into the loading box. Notice the success message listing imported records. +3. **Idempotency Check**: Drag and drop the same file again. The system blocks the upload with a warning: `Error: Código de lote duplicado (Llave de idempotencia ya registrada)`, showing duplicate transaction prevention. +4. **Simulation & Calculation**: Go to the **Simulación** tab. Select period `2026-06`. Uncheck *Modo Simulación* to commit calculations. Click **Calcular Liquidaciones**. Wait 5-10 seconds for the n8n webhook response. The settlements table renders with AI-generated audit observations. ### Step C: The Regional Commercial Leader Experience (`lider_mde` vs `lider_ctg`) +- **Role Purpose**: Demonstrates regional boundaries. Leaders can only load sales for their own hotel. 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. +2. **Regional Ingestion Boundaries**: Go to **Cargar Ventas**. Attempt to upload an Excel file containing Cartagena (`EST-CTG`) records. +3. **Expected Result**: The system rejects the file with a validation error stating that the hotel code `EST-CTG` is outside your permitted Medellin jurisdiction (`EST-MDE`). +4. **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`) +- **Role Purpose**: Shows complete personal data segregation using Row-Level Security. 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. +2. **Personal Data Isolation**: Go to **Historial** and **Metas**. Observe that you only see Medellin (`EST-MDE`) records and sales targets. All other collaborators' data is hidden. +3. **Logout**, then login as the Cartagena Collaborator **`colaborador_ctg`** (`password123`). +4. **Expected Result**: Only Cartagena (`EST-CTG`) records are returned. The database RLS filters the query dynamically based on the session user ID, returning zero results for other hotels. ### Step E: The Regional Manager Experience (`gerente_mde` vs `gerente_ctg`) +- **Role Purpose**: Demonstrates regional segregation in approval workflows. 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`. +2. **Approval Segregation**: Navigate to the **Aprobaciones** (Approvals) tab. You see pending settlements only for Medellin. Click **Rechazar** on the Medellin settlement, enter rejection reason: `"Falta validar soporte físico"`, and submit. The status transitions to `REJECTED`. +3. **Logout**, then login as the Cartagena Hotel Manager **`gerente_ctg`** (`password123`). +4. **Expected Result**: You only see Cartagena pending settlements. Click **Aprobar** on the Cartagena settlement; its status transitions to `APPROVED`, which triggers an audit log. ### Step F: The Read-Only Auditor Compliance Experience (`consulta`) +- **Role Purpose**: Verification of auditing read-only visibility. 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`) +- **Role Purpose**: Master control view and security log auditing. 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]`. +2. **Audit Explorer**: Navigate to the **Auditoría** tab. Select any log. The side-by-side JSON diff panel displays the exact changes made. Notice that sensitive fields like `password_hash` are redacted as `[REDACTED]`. +3. **Immutability Check**: Try to edit or delete any log entry. The database trigger blocks the mutation immediately, throwing an error. --- diff --git a/docs/showcase/recruiter_guide_es.md b/docs/showcase/recruiter_guide_es.md index 0e644e6..3caebd5 100644 --- a/docs/showcase/recruiter_guide_es.md +++ b/docs/showcase/recruiter_guide_es.md @@ -45,37 +45,51 @@ El sistema está construido como una aplicación empresarial multi-inquilino alt Puede acceder a la versión de demostración de la aplicación en: **`https://hotels-demo.gaboggamer.online`** ### 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`. +- **Propósito del Rol**: Representa al planificador comercial que configura los planes y metas de comisiones a nivel global. +1. **Inicio de sesión**: Vaya a la pantalla de login, introduzca el usuario **`director`** y la contraseña **`password123`**, y haga clic en **Iniciar Sesión**. +2. **Creación de Plan**: En el encabezado de navegación superior, haga clic en **Planes**. +3. **Acción**: Haga clic en **Nuevo Plan**, ingrese los detalles (ej. Nombre: `Plan Especial Q3 2026`, Código: `EST-Q3-26`, Tipo: `COMMISSION`, Fechas de inicio/fin cubriendo de junio a agosto de 2026) y haga clic en **Guardar**. +4. **Configurar Reglas**: Busque el plan en la tabla, haga clic en el icono de **Reglas**, configure los rangos de comisión (ej. tasa de 0% de 0% a 90% de logro, tasa de 2.5% de 90.01% a 110% de logro) y haga clic en **Guardar Reglas**. +5. **Activar y Probar Versionado**: Vuelva a la lista de planes. Haga clic en el botón para cambiar el estado a **ACTIVO**. Intente editar el plan activo. El sistema bloquea el cambio directo y clona el plan a la versión **`v2`** en estado borrador, inactivando la versión anterior **`v1`**. Esto protege el historial. +6. **Asignar Meta**: Vaya a la pestaña **Metas**. Haga clic en **Asignar Meta**, seleccione `INDIVIDUAL`, asigne a `colaborador_mde` para el período `2026-06`, defina una meta de `100000` y haga clic en **Guardar Meta**. ### 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. +- **Propósito del Rol**: Analista global que sube las ventas de todos los hoteles y calcula las comisiones. +1. **Cerrar sesión**, e iniciar 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). +3. **Prueba de Idempotencia**: Intente subir el mismo archivo nuevamente. El sistema lo bloqueará mostrando el error: `Error: Código de lote duplicado (Llave de idempotencia ya registrada)`, evitando pagos duplicados. +4. **Simulación y Cálculo**: Vaya a la pestaña **Simulación**. Seleccione el período `2026-06`. Desmarque la opción *Modo Simulación* para confirmar. Haga clic en **Calcular Liquidaciones**. Espere de 5 a 10 segundos a que responda el webhook de n8n. La tabla de liquidaciones se cargará con notas de auditoría de IA. ### 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. +- **Propósito del Rol**: Demuestra la seguridad regional. Los líderes comerciales solo pueden cargar ventas de su propio hotel. +1. **Cerrar sesión**, e iniciar sesión como el Líder de Medellín **`lider_mde`** (`password123`). +2. **Límites de Carga Regional**: Vaya a **Cargar Ventas**. Intente subir un archivo Excel que contenga registros del hotel de Cartagena (`EST-CTG`). +3. **Resultado Esperado**: El sistema rechaza la carga debido a que el código del hotel `EST-CTG` está fuera de su jurisdicción autorizada de Medellín (`EST-MDE`). +4. **Cerrar sesión**, e iniciar sesión como **`lider_ctg`** (`password123`). Suba un archivo de Cartagena; el sistema procesará la importación con éxito. ### 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. +- **Propósito del Rol**: Aislamiento de datos del vendedor bajo políticas RLS. +1. **Cerrar sesión**, e iniciar sesión como el Colaborador de Medellín **`colaborador_mde`** (`password123`). +2. **Aislamiento de Datos**: Vaya a **Historial** y **Metas**. Solo visualizará sus metas e historial de ventas de Medellín. +3. **Cerrar sesión**, e iniciar sesión como el Colaborador de Cartagena **`colaborador_ctg`** (`password123`). +4. **Resultado Esperado**: Solo se devuelven los registros de Cartagena. La base de datos RLS filtra dinámicamente la consulta basándose en el ID de sesión del usuario. ### 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`. +- **Propósito del Rol**: Segregación regional para flujos de aprobación. +1. **Cerrar sesión**, e iniciar sesión como el Gerente de Medellín **`gerente_mde`** (`password123`). +2. **Segregación de Aprobación**: Vaya a **Aprobaciones**. Verá liquidaciones pendientes únicamente de Medellín. Rechace la liquidación ingresando el motivo: `"Falta validar soporte físico"`. +3. **Cerrar sesión**, e iniciar sesión como el Gerente de Cartagena **`gerente_ctg`** (`password123`). +4. **Resultado Esperado**: Solo verá liquidaciones de Cartagena. Haga clic en **Aprobar** en la liquidación de `colaborador_ctg`; el estado cambia a aprobado y genera el log de auditoría. ### 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. +- **Propósito del Rol**: Vista de cumplimiento global de solo lectura para auditoría. +1. **Cerrar sesión**, e iniciar sesión como **`consulta`** (`password123`). +2. **Inspección de Solo Lectura**: Explore Planes, Metas y el Tablero. Verifique que puede inspeccionar todos los datos de todas las regiones, pero 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]`. +1. **Cerrar sesión**, e iniciar sesión como **`admin`** (`password123`). +2. **Explorador de Auditoría**: Vaya a **Auditoría**. Seleccione un registro y valide los cambios antes y después en JSON, con datos confidenciales enmascarados como `[REDACTED]`. +3. **Prueba de Inmutabilidad**: Intente modificar o borrar algún registro de log de auditoría. El disparador de la base de datos bloqueará la operación lanzando un error. ---