semillero-special-hotel/docs/ROADMAP.md

Project Roadmap & Implementation Plan

Variable Remuneration, Compensation, and Commissions System - 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, 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 & 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 (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 (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 (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 (US-COM-010) showing individual historical progress and PDFs.
• Configure central audit logging (US-COM-011) to log data modifications with sensitive data masking.
• 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 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.

Phase 8: Internationalization (i18n) Support

• Create JSON translation files for English and Spanish under src/lib/i18n/dictionaries/.
• Implement client-side LocaleContext and active language switcher dropdown in the Header.
• Update Next.js UI views to use t(key) translation wrapper function.
• Extend prisma/schema.prisma to add flaggedReason (Json) and aiAuditNotes (Json) bilingual columns.
• Modify /api/sales/batch-save and /api/n8n/save-settlements routes to parse and store the localized JSON structures.
• Integrate LangChain LLM Translation Nodes in n8n anomaly detection and compliance workflows.
• Extend E2E test suites (test-n8n-real, test-phase4-ui, test-phase5-ui) to validate localized JSON database queries and bilingual UI page rendering.