> ## Documentation Index
> Fetch the complete documentation index at: https://alan-ramirez-dev.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 🏦 Introducción al Motor Transaccional

> API Motor Transaccional - Núcleo de Inversiones (Backend)

¡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

<CardGroup cols={2}>
  <Card title="Concurrencia ACID" icon="lock">
    Implementación estricta de aislamiento transaccional a nivel de persistencia mediante bloqueo pesimista, anulando por completo las Race Conditions.
  </Card>

  <Card title="Aritmética de Precisión" icon="calculator">
    Uso absoluto de la clase `BigDecimal` complementado con políticas de redondeo bancario (`RoundingMode.HALF_UP`), mitigando fallos de punto flotante.
  </Card>

  <Card title="Validación en Perímetro" icon="shield-check">
    Centralización y saneamiento de Payloads mediante Jakarta Validation en la capa HTTP (`@Valid`), capturando fallos con un interceptor global (`@ControllerAdvice`).
  </Card>

  <Card title="Infraestructura Segura" icon="docker">
    Pipeline de empaquetado *Multi-stage* basado en Alpine Linux (JRE), con inyección nativa de banderas de afinación JVM y aislamiento de privilegios.
  </Card>
</CardGroup>

## 🛠️ 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`.

```bash theme={null}
# 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      |