docs: add requirements, architecture, and roadmap design docs

docs/ARCHITECTURE.md

@@ -0,0 +1,206 @@
+# Architecture and System Design
+
+**Sistema de Remuneración Variable, Compensación y Comisiones - Hoteles Estelar**
+
+---
+
+## 1. Technical Stack Selection
+
+To keep resource footprint low on the self-hosted VPS while providing a premium, modern user experience, we recommend a unified **Next.js Full-Stack App Router** architecture.
+
+* **Frontend**: Next.js App Router (React + TypeScript).
+* **Styling**: Vanilla CSS with a structured design system (CSS variables, dark/light theme tokens, premium layout aesthetics, smooth CSS micro-animations).
+* **Backend**: Next.js API Routes (Node.js runtime).
+* **ORM**: Prisma ORM (provides type-safe database queries and automated schema migrations).
+* **Database**: PostgreSQL (hosted on the existing `postgres` Docker stack).
+* **Excel Processing**: `xlsx` (SheetJS) for high-performance parser logic.
+* **Authentication**: NextAuth.js or custom lightweight JWT session cookies.
+* **Hosting**: Docker container integrated into the Dockge stack manager, reverse proxied by Caddy with split DNS resolving over WireGuard VPN for security-sensitive areas.
+
+---
+
+## 2. System Architecture
+
+```mermaid
+graph TD
+    User([Colaborador / Líder / Admin]) -->|HTTPS| Caddy[Caddy Reverse Proxy]
+    Caddy -->|Internal Network| NextJS[Next.js Full-Stack App]
+    
+    subgraph NextJS Container
+        UI[React Frontend / Vanilla CSS] <--> API[API Routes / Controllers]
+        Engine[Settlement Engine] <--> API
+        Parser[Excel Parser] <--> API
+    end
+
+    API -->|Prisma Client| DB[(PostgreSQL)]
+    Jobs[Integration CRON Jobs] -->|Fetch Sales| API
+    External[External PMS / ERP / CRM] -->|API Push / Pull| Jobs
+```
+
+---
+
+## 3. Database Schema Design (Entity-Relationship Diagram)
+
+```mermaid
+erDiagram
+    REGIONS ||--o{ HOTELS : contains
+    HOTELS ||--o{ USERS : houses
+    USERS ||--o{ GOALS : achieves
+    USERS ||--o{ SALES_RESULTS : generates
+    USERS ||--o{ SETTLEMENTS : receives
+    
+    COMPENSATION_PLANS ||--o{ CALCULATION_RULES : dictates
+    COMPENSATION_PLANS ||--o{ SETTLEMENTS : calculates
+    
+    USERS ||--o{ AUDIT_LOGS : executes
+    USERS ||--o{ NOTIFICATIONS : receives
+
+    REGIONS {
+        int id PK
+        string name
+        string code
+    }
+
+    HOTELS {
+        int id PK
+        string name
+        string code
+        int region_id FK
+        string status
+    }
+
+    USERS {
+        int id PK
+        string username
+        string email
+        string password_hash
+        string role "ADMIN | DIRECTOR | GERENTE | LIDER | ANALISTA | CONSULTA | COLABORADOR"
+        int hotel_id FK
+        string area
+        string status "ACTIVE | INACTIVE"
+        datetime created_at
+    }
+
+    COMPENSATION_PLANS {
+        int id PK
+        string name
+        string code UK
+        datetime validity_start
+        datetime validity_end
+        string type "PERCENTAGE | SCALE | CONDITIONAL | FIXED"
+        string formula "JSON or string representation"
+        decimal meta_amount
+        decimal percentage_rate
+        decimal max_cap
+        string status "DRAFT | ACTIVE | INACTIVE"
+        int version
+        int created_by FK
+        datetime created_at
+    }
+
+    CALCULATION_RULES {
+        int id PK
+        int plan_id FK
+        string type "TIER | BONUS"
+        decimal min_achievement "percentage"
+        decimal max_achievement "percentage"
+        decimal rate "multiplier or percentage"
+        decimal payout_amount "fixed payment"
+    }
+
+    GOALS {
+        int id PK
+        string target_type "INDIVIDUAL | TEAM | HOTEL"
+        int target_id "user_id, team_id, or hotel_id"
+        string period "YYYY-MM"
+        decimal amount
+        datetime created_at
+    }
+
+    SALES_RESULTS {
+        int id PK
+        string source "EXCEL | API"
+        int hotel_id FK
+        int user_id FK "colaborador"
+        string period "YYYY-MM"
+        decimal amount
+        int sales_count
+        string status "PENDING | PROCESSED"
+        int uploaded_by FK
+        datetime created_at
+    }
+
+    SETTLEMENTS {
+        int id PK
+        string period "YYYY-MM"
+        int plan_id FK
+        int user_id FK
+        decimal sales_amount
+        decimal goal_amount
+        decimal achievement_percentage
+        decimal calculated_commission
+        decimal calculated_bonus
+        decimal total_payout
+        string status "SIMULATED | PENDING | APPROVED | REJECTED"
+        int approved_by FK
+        datetime approved_at
+        string rejection_reason
+        datetime created_at
+    }
+
+    AUDIT_LOGS {
+        int id PK
+        int user_id FK
+        string action "CREATE | UPDATE | DELETE | APPROVE | REJECT | LOGIN"
+        string target_table
+        int target_id
+        json previous_value
+        json new_value
+        string ip_address
+        datetime created_at
+    }
+
+    NOTIFICATIONS {
+        int id PK
+        int user_id FK
+        string title
+        string message
+        string status "UNREAD | READ"
+        string type "EMAIL | PUSH"
+        datetime sent_at
+    }
+```
+
+---
+
+## 4. Key Business Logic: Settlement & Calculation Engine
+
+The engine computes commissions based on the formula:
+
+$$\text{Achievement \%} = \left( \frac{\text{Sales Amount}}{\text{Goal Amount}} \right) \times 100$$
+
+### Calculation Flow:
+1. **Fetch inputs**: Get sales results, goals, and matching active compensation plan for the collaborator for the period `YYYY-MM`.
+2. **Determine Achievement Level**: Check against the plan's `CALCULATION_RULES` (tiers).
+3. **Calculate Commission**:
+   - *Fixed Rate*: $\text{Sales} \times \text{percentage\_rate}$.
+   - *Tiers/Scales*: Apply rate corresponding to the achievement level tier.
+4. **Apply Caps**: If calculated commission exceeds the plan's `max_cap`, set it to `max_cap`.
+5. **Add Special Bonuses**: If the collaborator achieves certain thresholds (e.g., >100% meta), add the specific tier's fixed `payout_amount` as a bonus.
+6. **Generate Output**: Store as a `SETTLEMENT` entry in `SIMULATED` status.
+
+---
+
+## 5. Security & Access Control Model (RBAC)
+
+We define role-based access restrictions as follows:
+
+| Role | Access Level | Restrictions |
+| :--- | :--- | :--- |
+| **Administrador** | Full system write & read. | None. |
+| **Director Comercial** | Reads all dashboards & reports. Can configure metadata. | Cannot calculate or approve. |
+| **Gerente Hotel** | Reads data, sales, and settlements for their specific Hotel. | Restricted to `hotel_id`. |
+| **Líder Comercial** | Triggers simulations, views dashboards. Approves/Rejects settlements. | Restricted to their region/team. |
+| **Analista Financiero** | Reviews calculations. Exports consolidated PDF/Excel reports. | Cannot approve. |
+| **Consulta** | Read-only. | No mutations allowed. |
+| **Colaborador** | Consults own history & dashboard. | Restricted to `user_id`. |

docs/REQUIREMENTS.md

@@ -0,0 +1,192 @@
+# Requerimientos y Historias de Usuario
+
+**Sistema de Remuneración Variable, Compensación y Comisiones - Hoteles Estelar**
+
+---
+
+## Objetivo General
+Implementar una plataforma centralizada para la administración, cálculo, validación y seguimiento de remuneración variable, compensaciones e incentivos comerciales, reemplazando el manejo manual actual realizado en archivos Excel y permitiendo automatizar el proceso de liquidación, aprobación y trazabilidad.
+
+---
+
+## Alcance Funcional
+El sistema se compone de 7 características principales (Features) divididas en 14 Historias de Usuario (HU).
+
+### FEATURE 1 — Administración de Planes de Compensación
+
+#### HU-COM-001 — Crear plan de compensación
+* **Como:** Administrador del sistema
+* **Quiero:** Crear planes de compensación y comisiones
+* **Para:** Definir las reglas de remuneración variable.
+* **Descripción:**
+  El sistema deberá permitir configurar planes asociados a:
+  * Hoteles
+  * Regiones
+  * Equipos comerciales
+  * Cargos
+  * Campañas
+  * Temporadas
+  * Unidades de negocio
+* **Criterios de Aceptación:**
+  * **Escenario 1 (Creación exitosa):** Dado que el administrador ingresa al módulo de compensación, cuando selecciona "Crear plan" y diligencia los campos requeridos, entonces el sistema debe almacenar el plan correctamente.
+  * **Escenario 2 (Validación de obligatoriedad):** Dado que existen campos obligatorios, cuando el usuario intenta guardar sin completarlos, entonces el sistema debe mostrar mensajes de validación.
+* **Campos sugeridos:**
+  * Nombre del plan, Código, Vigencia, Tipo de compensación, Área, Cargo, Hotel, Región, Tipo de cálculo, Fórmula, Meta, Porcentaje, Topes máximos, Estado.
+* **Operaciones (Sub-features):**
+  * Crear plan, Editar plan, Duplicar plan, Versionamiento, Inactivar plan.
+
+#### HU-COM-002 — Configurar reglas de cálculo
+* **Como:** Administrador
+* **Quiero:** Parametrizar reglas de negocio
+* **Para:** Automatizar liquidaciones de comisiones e incentivos.
+* **Descripción:**
+  El sistema deberá soportar:
+  * Cálculos porcentuales
+  * Escalas y Rangos
+  * Cumplimiento de metas
+  * Comisiones fijas y variables
+  * Bonos especiales
+* **Criterios de Aceptación:**
+  * **Escenario 1 (Configuración de fórmula):** Dado que existe un plan de compensación, cuando el usuario define las reglas, entonces el sistema debe almacenar la configuración.
+  * **Escenario 2 (Validación de topes):** Dado que existe un tope máximo definido, cuando el cálculo supera el límite, entonces el sistema debe aplicar el tope configurado.
+* **Operaciones (Sub-features):**
+  * Fórmulas dinámicas, Escalas de comisión, Topes máximos, Reglas condicionales, Bonificaciones especiales.
+
+#### HU-COM-003 — Configurar metas comerciales
+* **Como:** Administrador
+* **Quiero:** Configurar metas comerciales
+* **Para:** Medir cumplimiento para cálculo de variables.
+* **Criterios de Aceptación:**
+  * **Escenario 1 (Configurar meta):** Dado que existe un colaborador o equipo, cuando el usuario asigna metas, entonces el sistema debe almacenarlas por periodo.
+* **Operaciones (Sub-features):**
+  * Metas mensuales, trimestrales, por hotel, por equipo, individuales.
+
+---
+
+### FEATURE 2 — Carga e Integración de Información
+
+#### HU-COM-004 — Importar resultados comerciales desde Excel
+* **Como:** Usuario
+* **Quiero:** Importar resultados comerciales desde Excel
+* **Para:** Evitar procesos manuales.
+* **Criterios de Aceptación:**
+  * **Escenario 1 (Importación válida):** Dado que el usuario carga un archivo válido, cuando el sistema procesa la información, entonces debe actualizar resultados automáticamente.
+  * **Escenario 2 (Archivo inválido):** Dado que el archivo contiene errores, cuando el sistema procesa el archivo, entonces debe mostrar inconsistencias.
+* **Operaciones (Sub-features):**
+  * Importación XLSX/CSV, Validación de columnas, Plantillas de carga.
+
+#### HU-COM-005 — Integración automática con sistemas externos
+* **Como:** Administrador
+* **Quiero:** Integrar automáticamente información de ventas
+* **Para:** Automatizar el cálculo de comisiones.
+* **Descripción:**
+  El sistema deberá integrarse con:
+  * ERP, PMS hotelero, CRM, Sistemas financieros, Plataformas de reservas, Revenue Management.
+* **Criterios de Aceptación:**
+  * **Escenario 1 (Integración exitosa):** Dado que existe una integración configurada, cuando el proceso automático se ejecuta, entonces el sistema debe actualizar la información automáticamente.
+  * **Escenario 2 (Error de integración):** Dado que existe una falla, cuando el proceso no finaliza correctamente, entonces el sistema debe registrar logs y notificar al administrador.
+* **Operaciones (Sub-features):**
+  * Integraciones API, Jobs automáticos, Logs, Reintentos automáticos.
+
+---
+
+### FEATURE 3 — Liquidación Automática
+
+#### HU-COM-006 — Calcular comisiones automáticamente
+* **Como:** Sistema
+* **Quiero:** Calcular automáticamente las comisiones
+* **Para:** Reducir errores manuales.
+* **Criterios de Aceptación:**
+  * **Escenario 1 (Cálculo individual):** Dado que existen ventas registradas, cuando el sistema ejecuta la liquidación, entonces debe calcular automáticamente: Comisión individual, Cumplimiento, Bono e Incentivo.
+  * **Escenario 2 (Cálculo grupal):** Dado que existen reglas grupales, cuando el sistema procesa el cálculo, entonces debe generar comisión grupal automáticamente.
+* **Operaciones (Sub-features):**
+  * Motor de cálculo, Liquidación automática, Cálculos masivos, Simulación de pagos.
+
+#### HU-COM-007 — Simular liquidación antes de aprobar
+* **Como:** Líder Comercial
+* **Quiero:** Simular liquidaciones
+* **Para:** Validar resultados antes de aprobar pagos.
+* **Criterios de Aceptación:**
+  * **Escenario 1 (Simulación):** Dado que existe un periodo de liquidación, cuando el usuario ejecuta simulación, entonces el sistema debe mostrar resultados preliminares.
+* **Operaciones (Sub-features):**
+  * Simulación, Validación previa, Comparativos, Ajustes antes de cierre.
+
+---
+
+### FEATURE 4 — Aprobaciones y Flujo de Validación
+
+#### HU-COM-008 — Aprobar liquidaciones
+* **Como:** Líder Comercial
+* **Quiero:** Aprobar o rechazar liquidaciones
+* **Para:** Validar pagos variables.
+* **Criterios de Aceptación:**
+  * **Escenario 1 (Aprobar):** Dado que existe una liquidación generada, cuando el líder revisa la información, entonces puede aprobarla.
+  * **Escenario 2 (Rechazar):** Dado que existen inconsistencias, cuando el líder rechaza la liquidación, entonces debe registrar observaciones obligatorias.
+* **Operaciones (Sub-features):**
+  * Flujo de aprobación, Observaciones, Rechazos, Reenvío de liquidación.
+
+#### HU-COM-009 — Notificar aprobación o rechazo
+* **Como:** Sistema
+* **Quiero:** Notificar resultados de aprobación
+* **Para:** Informar a los responsables.
+* **Criterios de Aceptación:**
+  * **Escenario 1 (Notificación de aprobación):** Dado que la liquidación fue aprobada, cuando finaliza el proceso, entonces el sistema debe enviar notificación automática.
+* **Operaciones (Sub-features):**
+  * Correos automáticos, Notificaciones push, Historial de notificaciones.
+
+---
+
+### FEATURE 5 — Consulta y Trazabilidad
+
+#### HU-COM-010 — Consultar histórico de comisiones
+* **Como:** Colaborador
+* **Quiero:** Consultar mi histórico de pagos variables
+* **Para:** Validar liquidaciones realizadas.
+* **Criterios de Aceptación:**
+  * **Escenario 1 (Consulta histórica):** Dado que existen periodos liquidados, cuando el usuario consulta la información, entonces el sistema debe mostrar: Periodo, Meta, Resultado, Comisión, Estado.
+* **Operaciones (Sub-features):**
+  * Histórico de pagos, Filtros, Descarga PDF, Consulta por periodos.
+
+#### HU-COM-011 — Registrar trazabilidad y auditoría
+* **Como:** Sistema
+* **Quiero:** Registrar cambios y aprobaciones
+* **Para:** Mantener trazabilidad histórica.
+* **Criterios de Aceptación:**
+  * **Escenario 1 (Registro automático):** Dado que un usuario modifica reglas o liquidaciones, cuando guarda cambios, entonces el sistema debe registrar: Usuario, Fecha, Hora, Acción, Valor anterior, Valor nuevo.
+* **Operaciones (Sub-features):**
+  * Auditoría, Logs, Histórico, Bitácora.
+
+---
+
+### FEATURE 6 — Reportes y Analítica
+
+#### HU-COM-012 — Visualizar dashboard de compensación
+* **Como:** Director Comercial
+* **Quiero:** Visualizar dashboards de compensación
+* **Para:** Analizar desempeño y costos variables.
+* **Criterios de Aceptación:**
+  * **Escenario 1 (Dashboard ejecutivo):** Dado que existen liquidaciones generadas, cuando el usuario consulta el dashboard, entonces el sistema debe mostrar: Comisiones pagadas, Cumplimiento, Ranking comercial, Costos variables, Tendencias.
+* **Operaciones (Sub-features):**
+  * Dashboards, KPIs financieros, Tendencias, Comparativos.
+
+#### HU-COM-013 — Exportar reportes financieros
+* **Como:** Usuario Financiero
+* **Quiero:** Exportar reportes
+* **Para:** Realizar análisis presupuestal y operativo.
+* **Criterios de Aceptación:**
+  * **Escenario 1 (Exportación):** Dado que existen resultados liquidados, cuando el usuario selecciona exportar, entonces el sistema debe generar: PDF, Excel, Consolidados por hotel, Consolidados por región.
+* **Operaciones (Sub-features):**
+  * Exportación PDF, Exportación Excel, Reportes consolidados, Programación automática de reportes.
+
+---
+
+### FEATURE 7 — Seguridad y Permisos
+
+#### HU-COM-014 — Gestionar roles y permisos
+* **Como:** Administrador
+* **Quiero:** Gestionar roles y accesos
+* **Para:** Proteger información sensible.
+* **Roles sugeridos:**
+  * Administrador, Director Comercial, Gerente Hotel, Líder Comercial, Analista Financiero, Consulta.
+* **Operaciones (Sub-features):**
+  * Roles, Permisos, Restricción por hotel, Restricción por región, Restricción por área.

docs/ROADMAP.md

@@ -0,0 +1,48 @@
+# Project Roadmap & Implementation Plan
+
+**Sistema de Remuneración Variable, Compensación y Comisiones - Hoteles Estelar**
+
+---
+
+This plan outlines the step-by-step path to construct, test, and host the platform securely.
+
+## Phase 1: Foundation & Database Configuration
+* [ ] Initialize Next.js app with TypeScript and `npx` in the repository root.
+* [ ] Configure Vanilla CSS design tokens (variables, animations, grids/flex layouts, themes).
+* [ ] Set up Prisma ORM and define the PostgreSQL schemas (`schema.prisma`) matching the ER diagram.
+* [ ] Verify container network connectivity between the Next.js app and the existing PostgreSQL Docker service.
+* [ ] Execute initial database migration to seed basic structural tables (Regions, Hotels, Roles).
+
+## Phase 2: Authentication & RBAC Core
+* [ ] Implement secure JWT session cookieless/cookie-based auth.
+* [ ] Build a premium login interface with smooth CSS transition effects (no browser default controls).
+* [ ] Develop route guards and API middleware verifying user roles (RBAC authorization validation).
+
+## Phase 3: Compensation Configuration (Feature 1)
+* [ ] Implement UI forms and API endpoints for **Plan Creation** (HU-COM-001) with mandatory fields validation.
+* [ ] Implement **Calculation Rules config** (HU-COM-002) allowing tiers, multipliers, and cap inputs.
+* [ ] Implement **Goal assignment UI** (HU-COM-003) for monthly/quarterly scopes.
+* [ ] Write comprehensive unit tests for versioning and duplicating plans.
+
+## Phase 4: Data Import & Integrations (Feature 2)
+* [ ] Create server-side Excel parser parsing sales sheets (HU-COM-004) with validation log feedbacks.
+* [ ] Build file drag-and-drop loading screen featuring progress UI.
+* [ ] Outline mock API connections for external ERP/PMS services (HU-COM-005) with auto-retry and logs.
+
+## Phase 5: Settlement Engine & Approvals (Features 3 & 4)
+* [ ] Build the Core Settlement calculation engine (HU-COM-006) handling individual/team tiers and caps.
+* [ ] Implement **Simulation module** UI (HU-COM-007) displaying side-by-side comparative calculations.
+* [ ] Build **Approvals workflow** panel (HU-COM-008) for Commercial Leaders (Approve/Reject with mandatory reason).
+* [ ] Set up email/notification hooks dispatching notifications (HU-COM-009).
+
+## Phase 6: History, Auditing & Analytics (Features 5 & 6)
+* [ ] Build **Colaborador History dashboard** (HU-COM-010) showing individual historical progress and PDFs.
+* [ ] Wire up **Audit Logs trigger** (HU-COM-011) tracking every modification to rules/settlements.
+* [ ] Build premium **Financial Dashboard** (HU-COM-012) using chart widgets (ranking, variables, trends).
+* [ ] Implement **PDF / Excel exporter service** (HU-COM-013) consolidating metrics by hotel/region.
+
+## Phase 7: Deployment & Security Hardening
+* [ ] Write Dockge-compatible `docker-compose.yml` for the Next.js container.
+* [ ] Add `git.gaboggamer.online` or a sub-subdomain block in `/home/gabogg/docker/caddy/Caddyfile`.
+* [ ] Configure DNS resolution inside the WireGuard network.
+* [ ] Final end-to-end security audits.