docs: integrate gap analysis constraints into architecture and roadmap specifications
This commit is contained in:
parent
fea880fadc
commit
a7dbc00bfc
2 changed files with 52 additions and 25 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue