Risk Control System - MVP

📋 Descripción General

Sistema de control de riesgos para operaciones financieras que evalúa trades en tiempo real utilizando un enfoque basado en eventos. El sistema detecta patrones de riesgo y ejecuta acciones configurables cuando se violan las reglas establecidas.

🏗️ Arquitectura

• Backend: Laravel 12.x con PHP 8.2
• Frontend: Next.js 16 con React 19 y Tailwind CSS 4
• Base de datos: MySQL 8.0
• Contenedores: Docker Compose

🎯 Enfoque de Evaluación

Se implementó evaluación por evento con las siguientes características:

• Al cerrar un trade (cambio de status a 'closed'), se dispara el evento TradeClosed
• El listener EvaluateRiskOnTradeClosed evalúa todas las reglas activas contra el trade
• Ventajas:
  • Evaluación en tiempo real
  • Bajo overhead computacional
  • Respuesta inmediata a violaciones

📊 Estructura de Reglas

1. Short Trade Duration: Detecta trades cerrados demasiado rápido (parámetro: min_duration_seconds)
2. Volume Consistency: Detecta volúmenes anómalos comparados con el historial (parámetro: deviation_threshold)

🚀 Cómo Ejecutar

Requisitos Previos

• Docker Desktop instalado y ejecutándose
• PowerShell 7 (recomendado para Windows)

Pasos de Ejecución

1. Asegurar que Docker Desktop esté ejecutándose
2. Ejecutar .\start.ps1 en PowerShell
3. Acceder a los servicios:
   • Frontend: http://localhost:3000
   • Backend API: http://localhost:8000/api
   • phpMyAdmin: http://localhost:8080

📦 Estructura del Proyecto

risk-control-system/
├── backend/                  # API Laravel
│   ├── app/
│   │   ├── Events/           # Eventos del sistema (TradeClosed)
│   │   ├── Http/Controllers/ # Controladores API
│   │   ├── Listeners/        # Listeners de eventos
│   │   ├── Models/           # Modelos Eloquent (6 entidades)
│   │   ├── Providers/        # Proveedores de servicios
│   │   ├── Rules/            # Reglas de riesgo
│   │   └── Services/         # Servicios de negocio
│   ├── database/
│   │   ├── factories/        # Factories para testing
│   │   ├── migrations/       # Migraciones de BD
│   │   └── seeders/          # Seeders de datos
│   ├── routes/               # Rutas API
│   └── tests/                # Pruebas automatizadas
├── frontend/                 # Aplicación Next.js
│   ├── components/ui/        # 16 componentes UI reutilizables
│   ├── lib/                  # Cliente API (Axios)
│   ├── pages/                # Páginas de la aplicación
│   │   ├── incidents/        # Gestión de incidencias
│   │   ├── risk-rules/       # CRUD de reglas de riesgo
│   │   └── trades/           # Listado de operaciones
│   └── styles/               # Estilos globales
├── docker-compose.yml        # Configuración Docker
├── Dockerfile.backend        # Imagen Docker backend
├── Dockerfile.frontend       # Imagen Docker frontend
├── MANUAL_DE_USUARIO.md      # Manual de usuario
└── start.ps1                 # Script de inicio

🔧 Entidades del Modelo de Dominio

1. Account: Cuentas de trading (status, trading_status)
2. Trade: Operaciones financieras (tipo, volumen, precios, tiempos)
3. RiskRule: Reglas de riesgo configurables (tipo, severidad, parámetros)
4. RuleExecution: Ejecuciones/incidencias de reglas violadas
5. Action: Acciones a ejecutar cuando se violan reglas
6. User: Usuarios del sistema

🎛️ Configuración

Variables de Entorno

El proyecto utiliza variables de entorno centralizadas en:

• backend/.env - Configuración del backend (base de datos, aplicación)
• Los servicios Docker (mysql, phpmyadmin, backend) comparten estas variables

Configuración de Reglas

Las reglas de riesgo se pueden configurar a través de la interfaz web en:

• http://localhost:3000/risk-rules

🔍 Endpoints API

Reglas de Riesgo

• GET /api/risk-rules - Listado de reglas
• POST /api/risk-rules - Crear nueva regla
• GET /api/risk-rules/{id} - Obtener regla específica
• PUT /api/risk-rules/{id} - Actualizar regla
• DELETE /api/risk-rules/{id} - Eliminar regla
• POST /api/risk-rules/{id}/actions - Asociar acción a regla
• DELETE /api/risk-rules/{id}/actions/{actionId} - Desasociar acción

Acciones

• GET /api/actions - Listado de acciones disponibles
• GET /api/actions/{id} - Obtener acción específica

Incidencias (Rule Executions)

• GET /api/rule-executions - Listado de incidencias
• POST /api/rule-executions/{id}/resolve - Resolver incidencia

Operaciones (Trades)

• GET /api/trades - Listado de trades (con filtros)
• GET /api/accounts/{id}/trades - Trades por cuenta

Estado de Riesgo

• GET /api/accounts/{id}/risk-status - Estado de riesgo de una cuenta

📈 Tipos de Severidad

• Hard: Violaciones críticas que ejecutan acciones inmediatamente
• Soft: Advertencias que acumulan incidentes antes de ejecutar acciones (configurable con incidents_before_action)

🛠️ Acciones Configurables

El sistema soporta 4 tipos de acciones:

Acción	Descripción
email_notification	Enviar notificación por correo electrónico al usuario afectado
slack_notification	Enviar alerta al canal de Slack del equipo de riesgos
disable_account	Deshabilitar completamente la cuenta del usuario
disable_trading	Suspender la capacidad de operar (trading) de la cuenta

📊 Frontend - Páginas y Funcionalidades

Panel de Control (Dashboard)

• Vista general del sistema
• Métricas de riesgo
• Accesos rápidos a todas las secciones

Gestión de Reglas de Riesgo

• Listado: Ver todas las reglas con su estado y acciones
• Crear: Formulario para nuevas reglas con parámetros dinámicos
• Editar: Modificar reglas existentes
• Eliminar: Remover reglas del sistema

Gestión de Incidencias

• Listado de violaciones de reglas
• Filtros por cuenta y regla
• Vista detallada de cada incidencia
• Función de resolución de incidentes

Gestión de Operaciones (Trades)

• Listado completo de todas las operaciones
• Filtros por cuenta, tipo y estado
• Vista detallada con duración y ganancia/pérdida
• Cálculo automático de métricas

Componentes UI Reutilizables

El frontend incluye 16 componentes UI:

• Alert, Badge, Button, Card
• Form, Input, Select
• LoadingContext, Modal, Navbar
• ProgressBar, Skeleton, Spinner
• Table, Tooltip

🧪 Pruebas

El proyecto incluye pruebas automatizadas:

• Tests de Servicios: RiskEvaluationServiceTest.php
• Tests de Features: Pruebas de integración
• Tests Unitarios: Pruebas de modelos y componentes

Ejecución:

# Backend
cd backend
php artisan test

🔮 Próximos Pasos (si fuera producción)

1. Autenticación: Implementar Laravel Sanctum para autenticación JWT
2. Procesamiento Asíncrono: Agregar colas para acciones asíncronas
3. Notificaciones Reales: Integración con Email, Slack, Webhooks
4. Dashboard Avanzado: Métricas en tiempo real con gráficos
5. Escalabilidad: Configuración de balanceo de carga y caché
6. Seguridad: Implementación de rate limiting y protección CSRF

✅ Verificación Final del MVP

Requerimientos Cumplidos

• ✅ Modelo de dominio completo (6 entidades)
• ✅ Dos reglas de riesgo configurables con parámetros
• ✅ Tipos de severidad (Hard/Soft) con umbrales configurables
• ✅ 4 acciones mockeables asociables a reglas
• ✅ Evaluación por evento (al cerrar trade)
• ✅ API RESTful completa con todos los endpoints
• ✅ Frontend completo (CRUD reglas, gestión de incidencias, listado de trades)
• ✅ Entorno Docker funcional con script de inicio

Características Adicionales

• Arquitectura basada en eventos (Event Sourcing)
• Evaluación en tiempo real
• Bajo acoplamiento entre componentes
• Fácil extensibilidad para nuevas reglas
• Interfaz de usuario responsive con Tailwind CSS 4
• Sistema de componentes UI reutilizables
• Animaciones con Framer Motion
• Manual de usuario incluido

📚 Documentación Adicional

• Manual de Usuario - Guía completa para usuarios finales
• Documentación de Laravel
• Documentación de Next.js
• Documentación de Docker

🤝 Contribución

Este proyecto sigue las mejores prácticas de desarrollo:

• Code style con ESLint y Prettier
• Patrones de diseño modernos (Events, Services, Repositories)
• Separación de responsabilidades (Controllers, Services, Models)
• Código limpio y mantenible
• Componentes UI reutilizables

📝 Notas Técnicas

• El sistema está diseñado para ser fácilmente extensible
• Las reglas de riesgo pueden ser añadidas sin modificar el núcleo (implementar RiskRuleInterface)
• La arquitectura permite escalabilidad horizontal
• Los parámetros de reglas se almacenan como JSON para flexibilidad
• Las acciones son mockeables y pueden implementarse realmente sin cambios estructurales