From 261762030bcabd5bc5963a79ebaa466fac963cb9 Mon Sep 17 00:00:00 2001 From: gabogg Date: Thu, 11 Jun 2026 13:10:05 +0000 Subject: [PATCH] docs: add requirements, architecture, and roadmap design docs --- docs/ARCHITECTURE.md | 206 +++++++++++++++++++++++++++++++++++++++++++ docs/REQUIREMENTS.md | 192 ++++++++++++++++++++++++++++++++++++++++ docs/ROADMAP.md | 48 ++++++++++ 3 files changed, 446 insertions(+) create mode 100644 docs/ARCHITECTURE.md create mode 100644 docs/REQUIREMENTS.md create mode 100644 docs/ROADMAP.md diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..f4b2409 --- /dev/null +++ b/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`. | diff --git a/docs/REQUIREMENTS.md b/docs/REQUIREMENTS.md new file mode 100644 index 0000000..b70801c --- /dev/null +++ b/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. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 0000000..4614f33 --- /dev/null +++ b/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.