🏦 Introducción al Motor Transaccional

¡Te doy la bienvenida a la documentación del primer microservicio del proyecto. El Motor Transaccional de Inversiones de mi Portafolio! Este proyecto actúa como una API RESTful de alta precisión y rendimiento optimizada para simular procesos operativos de plataformas Fintech. Está diseñado para gestionar la inyección de capitales, consultas de portafolio y conversión atómica de activos de pesos mexicanos (MXN) a dólares digitales (USDC), garantizando la consistencia de los datos bajo escenarios de alta concurrencia.

🚀 Características y Arquitectura Backend

Concurrencia ACID

Implementación estricta de aislamiento transaccional a nivel de persistencia mediante bloqueo pesimista, anulando por completo las Race Conditions.

Aritmética de Precisión

Uso absoluto de la clase BigDecimal complementado con políticas de redondeo bancario (RoundingMode.HALF_UP), mitigando fallos de punto flotante.

Validación en Perímetro

Centralización y saneamiento de Payloads mediante Jakarta Validation en la capa HTTP (@Valid), capturando fallos con un interceptor global (@ControllerAdvice).

Infraestructura Segura

Pipeline de empaquetado Multi-stage basado en Alpine Linux (JRE), con inyección nativa de banderas de afinación JVM y aislamiento de privilegios.

🛠️ Stack Tecnológico

Tecnología	Versión	Propósito en el proyecto
Spring Boot	`^3.5.14`	Framework base, Inversión de Control (IoC) y controladores RESTful
Java	`21`	Lenguaje principal con tipado estricto y records
Spring Data JPA	`^3.5.11`	Abstracción de datos, ORM con Hibernate 6 y control de bloqueos
PostgreSQL	`16`	Motor relacional de base de datos
Jakarta Validation	`^3.0`	Validación de contratos de datos y restricciones monetarias

💻 Comandos de Desarrollo

El backend requiere que el puerto 8080 esté disponible y que la base de datos local opere en el puerto 5433.

# Inicializa el contenedor aislado de PostgreSQL con volumen persistente
docker-compose up -d

# Compila el código, descarga dependencias y genera el ejecutable (.jar)
mvn clean package

# Inicia la aplicación web embebida en el servidor Tomcat local
mvn spring-boot:run

📡 Documentación de la API

Todas las respuestas con códigos de error de negocio o validación HTTP 400 devuelven la estructura estandarizada: {"error": "Detalle del fallo"}.

💼 Cuentas y Consultas (`/api/v1/portafolios`)

Método	Endpoint	Descripción	Acceso / Payload
`POST`	`/inicializar/{usuarioId}`	Registra e inicializa un nuevo portafolio financiero en cero (para demo).	Público / Ninguno
`GET`	`/{usuarioId}`	Obtiene los saldos actuales detallados de la cuenta en MXN y USDC.	Público / Solo Lectura

💱 Mutaciones Financieras (`/api/v1/portafolios/{usuarioId}`)

Método	Endpoint	Descripción	Payload Requerido	Restricciones / Validaciones
`PUT`	`/inyeccion`	Ejecuta la adición y fondeo seguro de capital en pesos al balance.	JSON con `monto`	`@NotNull`, `@Positive` (Monto > 0)
`PUT`	`/comprar-usdc`	Realiza el Swap atómico de saldo MXN para adquirir dólares cripto.	JSON con `montoMxn` y `tipoCambio`	Fondos Suficientes, `@Positive`
`PUT`	`/reiniciar`	Operación idempotente que restablece los saldos a cero (Modo Demo).	Ninguno	Restablece el balance completo

HUB Principal

Motor Transaccional

Generador de Reportes

Pipeline de Ingesta Masiva

Gestión de Identidad y Acceso

🚀 Características y Arquitectura Backend

Concurrencia ACID

Aritmética de Precisión

Validación en Perímetro

Infraestructura Segura

🛠️ Stack Tecnológico

💻 Comandos de Desarrollo

📡 Documentación de la API

💼 Cuentas y Consultas (`/api/v1/portafolios`)

💱 Mutaciones Financieras (`/api/v1/portafolios/{usuarioId}`)

​🚀 Características y Arquitectura Backend

Concurrencia ACID

Aritmética de Precisión

Validación en Perímetro

Infraestructura Segura

​🛠️ Stack Tecnológico

​💻 Comandos de Desarrollo

​📡 Documentación de la API

​💼 Cuentas y Consultas (/api/v1/portafolios)

​💱 Mutaciones Financieras (/api/v1/portafolios/{usuarioId})

🚀 Características y Arquitectura Backend

🛠️ Stack Tecnológico

💻 Comandos de Desarrollo

📡 Documentación de la API

💼 Cuentas y Consultas (`/api/v1/portafolios`)

💱 Mutaciones Financieras (`/api/v1/portafolios/{usuarioId}`)