diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 4f4d1aa..e5e6bb8 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -134,6 +134,8 @@ erDiagram decimal amount int sales_count string status "PENDING | PROCESSED" + string idempotency_key UK + string transaction_id int uploaded_by FK datetime created_at } @@ -141,18 +143,21 @@ erDiagram SETTLEMENTS { int id PK string period "YYYY-MM" - int plan_id FK + int plan_id FK "References specific version of the plan" int user_id FK decimal sales_amount decimal goal_amount decimal achievement_percentage decimal calculated_commission decimal calculated_bonus - decimal total_payout + decimal adjustment_amount "Clawback or adjustment delta" + decimal total_payout "calculated_commission + calculated_bonus + adjustment_amount" string status "SIMULATED | PENDING | APPROVED | REJECTED" int approved_by FK datetime approved_at string rejection_reason + int original_settlement_id FK "Self-references the settlement adjusted, if any" + string adjustment_notes datetime created_at } @@ -229,6 +234,18 @@ We define role-based access restrictions as follows: | **Consulta** | Read-only. | No mutations allowed. | | **Colaborador** | Consults own history & dashboard. | Restricted to `user_id`. | +### 5.1. PostgreSQL Row-Level Security (RLS) & Data Isolation +To ensure absolute segregation of sensitive compensation data, the database implements **Row-Level Security (RLS)**. RLS is enforced at the database layer (or via Prisma client middleware setting transaction context parameters), guaranteeing security even if application queries omit filters. + +* **Tenant Isolation Rules**: + * **Colaboradores**: Can only select rows from `SETTLEMENTS`, `SALES_RESULTS`, and `GOALS` where `user_id = current_setting('app.current_user_id')`. + * **Gerentes**: Can only select rows where `hotel_id = current_setting('app.current_hotel_id')`. + * **Líderes**: Can select rows within their assigned regions or teams (`region_id = current_setting('app.current_region_id')`). + * **Administradores / Analistas**: RLS is bypassed to allow system-wide computations and consolidated reporting. +* **Audit Trail Immutability**: + * The `AUDIT_LOGS` table has RLS policies that prevent `UPDATE` or `DELETE` actions for all users, including administrators. It is strictly write-only (`INSERT` operations only). + + --- ## 6. Dual-Environment Docker Deployment Model diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index b43b036..88e2843 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,6 +1,6 @@ # Project Roadmap & Implementation Plan -**Sistema de Remuneración Variable, Compensación y Comisiones - Hoteles Estelar** +**Variable Remuneration, Compensation, and Commissions System - Hoteles Estelar** --- @@ -8,41 +8,51 @@ This plan outlines the step-by-step path to construct, test, and host the platfo ## 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. +* [ ] Configure Vanilla CSS design tokens (variables, layout standards, light/dark themes). +* [ ] Define the PostgreSQL schemas in `schema.prisma` including: + * Temporal versioning fields for plans (`version`, `validity_start`, `validity_end`). + * Idempotency and transaction fields for sales imports. + * Adjustment and original reference keys for settlements. +* [ ] Configure **PostgreSQL Row-Level Security (RLS)** policies on the schema for user/hotel data isolation. * [ ] 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). +## Phase 2: Authentication & Security Core +* [ ] Implement secure JWT session cookie-based auth. +* [ ] Develop Prisma transaction middleware binding the active session's `user_id`, `hotel_id`, and `region_id` context to PostgreSQL settings to trigger RLS. +* [ ] Build a premium login interface with smooth CSS transition effects. * [ ] 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. +* [ ] Implement UI forms and API endpoints for **Plan Creation** (US-COM-001) with mandatory fields validation. +* [ ] Enforce **Plan Versioning logic**: Modifying an active plan marks it inactive and duplicates it with an incremented version ID. +* [ ] Implement **Calculation Rules config** (US-COM-002) allowing tiers, scales, and cap parameters. +* [ ] Implement **Goal assignment UI** (US-COM-003) for monthly/quarterly scopes. +* [ ] Write integration tests for plan versioning replication. ## 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. +* [ ] Create server-side Excel parser parsing sales sheets (US-COM-004) incorporating header-based **Idempotency key checks** to prevent duplicate uploads. +* [ ] Build file drag-and-drop loading screen featuring progress and validation UI. +* [ ] Set up n8n workflows for automated sales integrations (US-COM-005) with retry mechanisms and callback endpoints. ## 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). +* [ ] Build the Core Settlement calculation engine (US-COM-006) handling individual/team tiers and caps. +* [ ] Integrate **Retroactive Clawback/Adjustment logic**: Engine runs delta checks against past closed periods and creates adjusting line items for next payout. +* [ ] Build **n8n Webhook Test Branching**: Insert `IF` nodes checking for `/webhook-test` path segments to isolate test runs inside `TEST_DATABASE_URL`. +* [ ] Implement **Simulation module** UI (US-COM-007) displaying side-by-side comparative calculations. +* [ ] Build **Approvals workflow** panel (US-COM-008) for Commercial Leaders (Approve/Reject with mandatory reason). +* [ ] Set up email/notification hooks dispatching notifications (US-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. +* [ ] Build **Colaborador History dashboard** (US-COM-010) showing individual historical progress and PDFs. +* [ ] Configure `@explita/prisma-audit-log` client extension (US-COM-011) to log data modifications with sensitive data masking (passwords, base salaries). +* [ ] Set RLS block on the `AuditLog` table to make it strictly write-only (preventing edit/delete for all roles). +* [ ] Build premium **Financial Dashboard** (US-COM-012) using chart widgets (ranking, variables, trends). +* [ ] Implement **PDF / Excel exporter service** (US-COM-013) consolidating metrics by hotel/region. ## Phase 7: Deployment & Security Hardening -* [ ] Write Dockge-compatible `docker-compose.yml` for the Next.js container. +* [ ] Write `docker-compose.yml` defining the dual-service configuration (`app-prod` and `app-dev`) on different ports. +* [ ] Write environment variable validation and graceful exit code 0 script on `app-dev` startup. * [ ] Add `git.yourdomain.com` or a sub-subdomain block in the host Caddyfile. * [ ] Configure DNS resolution inside the WireGuard network. +* [ ] Implement log-stream redaction rules to prevent personal financial parameters from writing to server output. * [ ] Final end-to-end security audits.