T4-Minicore: Sistema de Cálculo de Comisiones por Ventas (MVC + RBAC)

Plataforma web empresarial para el registro transaccional de ventas y liquidación escalonada de comisiones comerciales.
Construida bajo el patrón arquitectónico Modelo-Vista-Controlador (MVC) desacoplado con Control de Acceso Basado en Roles (RBAC).

---

📑 Tabla de Contenidos

1. ✨ Características Destacadas
2. 🔑 Credenciales de Acceso y Roles
3. 🏛️ Arquitectura MVC Desacoplada
4. 🔄 Flujo Operativo y Matriz RBAC
5. 📱 Diseño Adaptativo (Responsive Service)
6. 🛠️ Tecnologías Utilizadas (Tech Stack)
7. 📁 Estructura del Repositorio
8. 🚀 Instalación y Puesta en Marcha
9. 🌐 Matriz de Endpoints REST API
10. 👩‍💻 Autora y Contacto

---

✨ Características Destacadas

• 👑 Panel Exclusivo de Administración (/admin):
  • Gestión de Vendedores: alta, consulta, modificación y baja de personal de ventas.
  • Reglas Escalonadas de Comisión: definición dinámica de metas de venta y porcentajes de incentivo aplicados.
  • Reporte Consolidado Global: auditoría por rango de fechas que calcula el total vendido y la comisión devengada por cada asesor comercial.
• 💼 Portal Personal del Vendedor (/portal-vendedor):
  • Registro Seguro de Ventas: registro de transacciones con monto y fecha; el backend asigna automáticamente la autoría a partir del token JWT del vendedor autenticado.
  • Cálculo de Comisión en Tiempo Real: consulta de monto acumulado vendido, porcentaje alcanzado en las escalas y comisión neta ganada en el periodo.
  • Historial Transaccional: auditoría de ventas individuales registradas por el usuario en sesión.
• 🛡️ Seguridad de Doble Capa (Client & Server RBAC):
  • En cliente: guards funcionales de Angular (authGuard, adminGuard, vendedorGuard).
  • En servidor: filtros antes de acción (require_admin, require_admin_or_vendedor) y aislamiento a nivel de consulta en base de datos.
• 📱 Adaptabilidad Móvil y Tema Claro (Light Theme):
  • Interfaz responsiva con diseño limpio, tablas completas en escritorio y tarjetas de inspección rápida en dispositivos móviles gracias a Angular CDK Layout.

---

🔑 Credenciales de Acceso y Roles

El sistema cuenta con usuarios de prueba sembrados en la base de datos con contraseñas encriptadas mediante Bcrypt:

---

🏛️ Arquitectura MVC Desacoplada

La solución aplica el patrón Modelo-Vista-Controlador de manera estricta y desacoplada:

flowchart LR
    subgraph ViewLayer["👁️ VISTA (Angular SPA - Light Theme)"]
        LoginUI["Login (/login)"]
        AdminUI["Panel Admin (/admin)"]
        SellerUI["Portal Vendedor (/portal-vendedor)"]
    end

    subgraph ControllerLayer["🎮 CONTROLADOR (Lucky Actions)"]
        AuthAction["Api::SignIns::Create"]
        VendAction["Api::Vendedor::* (require_admin)"]
        ReglaAction["Api::Regla::* (require_admin)"]
        VentaAction["Api::Ventas::* (RBAC Guard)"]
    end

    subgraph ModelLayer["🧠 MODELO (Avram ORM & PostgreSQL)"]
        UserModel["User & UserToken"]
        VendModel["Vendedor (has_many Ventas)"]
        ReglaModel["Regla (Escalones)"]
        VentaModel["Venta (belongs_to Vendedor)"]
    end

    ViewLayer <-->|Peticiones HTTP REST + JWT| ControllerLayer
    ControllerLayer <-->|Consultas Seguras & Serializers| ModelLayer

---

🔄 Flujo Operativo y Matriz RBAC

sequenceDiagram
    autonumber
    actor Vendedor
    participant Web as Angular Frontend
    participant API as Lucky API Controller
    participant DB as PostgreSQL (Avram)

    Vendedor->>Web: Ingresa credenciales (vendedor@t4-minicore.com)
    Web->>API: POST /api/sign_ins
    API->>DB: Valida hash Bcrypt y recupera rol regular + vendedor_id (3)
    API-->>Web: Retorna JWT con claims { role: "Regular", vendedor_id: 3 }
    Web->>Web: Guarda token y redirige a /portal-vendedor (vendedorGuard OK)

    Vendedor->>Web: Registra venta (monto: $1,500, fecha: hoy)
    Web->>API: POST /api/ventas (Bearer Token)
    API->>API: Detecta rol regular: inyecta automáticamente vendedor_id = 3
    API->>DB: Guarda venta vinculada al vendedor #3
    API-->>Web: 201 Created (VentaSerializer)

    Vendedor->>Web: Consulta comisiones del periodo
    Web->>API: GET /api/ventas?reporte=true
    API->>DB: Consulta ventas exclusivas del vendedor #3 y reglas activas
    API->>API: Calcula escalón alcanzado (ej. total >= $1,000 -> 5%)
    API-->>Web: 200 OK con { total_vendido, porcentaje_comision, comision_calculada }
    Web-->>Vendedor: Renderiza tarjetas de métricas e historial

---

📱 Diseño Adaptativo (Responsive Service)

La aplicación utiliza un servicio centralizado reactivo basado en @angular/cdk/layout:

// src/app/core/services/responsive.service.ts
@Injectable({ providedIn: 'root' })
export class ResponsiveService {
  private breakpointObserver = inject(BreakpointObserver);
  private screenWidth = toSignal(
    this.breakpointObserver.observe([
      '(max-width: 600px)',
      '(min-width: 601px) and (max-width: 1000px)',
      '(min-width: 1001px)'
    ])
  );

  isMobile = computed(() => !!this.screenWidth()?.breakpoints['(max-width: 600px)']);
  isTablet = computed(() => !!this.screenWidth()?.breakpoints['(min-width: 601px) and (max-width: 1000px)']);
  isDesktop = computed(() => !!this.screenWidth()?.breakpoints['(min-width: 1001px)']);
}

• Modo Escritorio (isDesktop): Tablas de datos completas, paneles en dos columnas y controles alineados horizontalmente.
• Modo Móvil (isMobile): Conversión automática a tarjetas compactas individuales (.cards-list), formularios apilados verticalmente y botones de acción accesibles.

---

🛠️ Tecnologías Utilizadas (Tech Stack)

Backend

• Crystal Language: Lenguaje compilado fuertemente tipado con rendimiento cercano a C.
• Lucky Framework v1.5: Framework MVC rápido y seguro contra errores en tiempo de compilación.
• Avram ORM: Manejo de entidades, migraciones y consultas SQL seguras.
• Authentic: Hashing seguro de contraseñas con Bcrypt y generación de JWT.

Frontend

• Angular v22: Framework empresarial SPA.
• Angular Signals: Gestión de estado reactivo y granular.
• Angular CDK Layout: Detección de breakpoints para comportamiento responsivo.
• Angular Router & Guards: Control de navegación perimetral.
• CSS3 Simple (Light Theme): Paleta moderna basada en blanco (#ffffff), grises suaves (#f8fafc, #e2e8f0) y verde azulado corporativo (#0d9488).

Base de Datos

• PostgreSQL: Motor relacional con integridad referencial y claves foráneas.

---

📁 Estructura del Repositorio

t4-minicore/
├── t4-minicore-api/                     # ⚙️ Backend en Lucky Framework (Crystal)
│   ├── config/                          # Configuración de base de datos, cookies y tokens
│   ├── db/
│   │   ├── migrations/                  # Migraciones estructurales (Users, Vendedores, Ventas, Reglas)
│   │   └── seed/                        # Semillas con datos iniciales (sample_data.cr)
│   └── src/
│       ├── actions/                     # 🎮 Controladores
│       │   ├── api_action.cr            # Control base con require_admin y require_vendedor
│       │   └── api/
│       │       ├── sign_ins/create.cr   # Endpoint de autenticación (JWT)
│       │       ├── vendedor/            # CRUD REST de vendedores (Solo Admin)
│       │       ├── regla/               # CRUD REST de reglas de comisión (Solo Admin)
│       │       ├── ventas/              # Registro y reporte de comisiones (Admin y Vendedor)
│       │       └── users/               # CRUD de usuarios del sistema
│       ├── models/                      # 🧠 Modelos Avram
│       │   ├── user.cr                  # Usuario con rol y vendedor_id foráneo
│       │   ├── vendedor.cr              # Entidad vendedor vinculada a ventas y usuario
│       │   ├── venta.cr                 # Registro de transacción comercial
│       │   └── regla.cr                 # Escalones de monto mínimo y porcentaje
│       ├── operations/                  # Operaciones de guardado y validaciones
│       └── serializers/                 # Serializadores JSON (ComisionSerializer, VendedorSerializer, etc.)
│
├── t4-minicore-web/                      # 🎨 Frontend en Angular 22 (SPA)
│   └── src/app/
│       ├── core/
│       │   ├── guards/                  # Protecciones de ruta (authGuard, adminGuard, vendedorGuard)
│       │   ├── interceptors/            # Inyección de Bearer Token en peticiones HTTP
│       │   └── services/                # AuthService, ComisionesService, VendedorService, ReglaService, ResponsiveService
│       ├── pages/                       # Vistas de la aplicación
│       │   ├── login/                   # Inicio de sesión con redirección por rol
│       │   ├── admin/                   # Panel de administración (vendedores, reglas y reporte global)
│       │   ├── portal-vendedor/         # Portal del vendedor (registrar venta y mis comisiones)
│       │   └── users/                   # Gestión de usuarios
│       └── shared/models/               # Modelos e interfaces TypeScript
│
└── README.md                            # Documentación integral del sistema

---

🚀 Instalación y Puesta en Marcha

Prerrequisitos

• Crystal >= 1.10.0 y Lucky CLI
• Node.js >= 18.x y npm
• PostgreSQL >= 14.x en ejecución local

---

Paso 1: Clonar el Repositorio

git clone git@github.com:SaraChiriboga/t4-minicore.git
cd t4-minicore

---

Paso 2: Configurar y Levantar el Backend (t4-minicore-api)

1. Ingresar a la carpeta de la API:

   cd t4-minicore-api
   

2. Instalar dependencias de Crystal:

   shards install
   

3. Configurar variables de base de datos en .env (si es necesario):

   DB_HOST=localhost
   DB_PORT=5432
   DB_USER=lucky
   DB_PASSWORD=lucky
   

4. Crear la base de datos y correr las migraciones:

   lucky db.create
   lucky db.migrate
   

5. Cargar las semillas de prueba (vendedores, ventas, reglas y usuarios de acceso):

   crystal run db/seed/sample_data.cr
   

6. Iniciar el servidor API (puerto 3000):

   lucky dev
   # o directamente:
   crystal run src/t4_minicore_api.cr
   

---

Paso 3: Configurar y Levantar el Frontend (t4-minicore-web)

1. Abrir una nueva terminal y navegar a la carpeta web:

   cd t4-minicore-web
   

2. Instalar dependencias de Node:

   npm install
   

3. Compilar y levantar la aplicación de desarrollo:

   ng serve
   

4. Ingresar desde el navegador web:

   http://localhost:4200
   

---

🌐 Matriz de Endpoints REST API

---

👩‍💻 Autora y Contacto