> ## 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 Pipeline ETL

> API Logiflow ETL - Motor de Ingesta Masiva Asíncrono (Backend)

¡Te doy la bienvenida a la documentación del tercer microservicio del proyecto. El Pipeline ETL de Ingesta Masvia Asíncrono de mi Portafolio!

Este proyecto funciona como un microservicio asíncrono de alto rendimiento, diseñado para la extracción, transformación y carga masiva de bitácoras de telemetría logística. Resuelve el desafío arquitectónico de procesar decenas de miles de registros simultáneamente sin bloquear o entorpecer la interfaz de usuario, protegiendo al mismo tiempo la base de datos frente a ataques y archivos corruptos.

## 🚀 Características y Arquitectura Backend

<CardGroup cols={2}>
  <Card title="Hilos Virtuales (Loom)" icon="microchip">
    Delegación del trabajo I/O pesado a un `TaskExecutorAdapter` nativo de Java 21, liberando la conexión HTTP instantáneamente (`202 Accepted`).
  </Card>

  <Card title="Bulk Inserts JDBC" icon="database">
    Sinergia entre Spring Batch (`chunk(500)`), Hibernate (`allocationSize=500`) y el driver de PostgreSQL para inserciones masivas.
  </Card>

  <Card title="Defensa Multicapa (WAF)" icon="shield-half">
    Aislamiento `@Transactional` y WAF simulado contra inyección SQL. Uso de `AtomicBoolean` para bloquear ataques de concurrencia (TOCTOU).
  </Card>

  <Card title="Resiliencia Fault-Tolerant" icon="truck">
    Políticas de omisión (`SkipPolicy`). Los registros corruptos o vacíos se aíslan y descartan silenciosamente sin abortar el lote completo.
  </Card>

  <Card title="Infraestructura Segura" icon="docker">
    Despliegue Multi-stage en Alpine Linux, operando bajo un usuario `spring` (no-root) y persistencia de datos mediante volúmenes.
  </Card>
</CardGroup>

## 🛠️ Stack Tecnológico

| Tecnología       | Versión | Propósito en el proyecto                                     |
| :--------------- | :------ | :----------------------------------------------------------- |
| **Spring Boot**  | `^3.x`  | Orquestación, controladores RESTful asíncronos e IoC         |
| **Java**         | `21`    | Lenguaje principal (Hilos Virtuales y Records)               |
| **Spring Batch** | `^5.x`  | ETL para lectura de archivos (NIO) y procesamiento en Chunks |
| **PostgreSQL**   | `17`    | Almacén relacional con capacidades de escritura por lotes    |
| **Docker**       | `v2`    | Contenerización y despliegue del entorno de red local        |

## 💻 Comandos de Desarrollo

La API expone sus servicios en el puerto `8081` y requiere PostgreSQL en el puerto `5435`.

```bash theme={null}
# Inicializa PostgreSQL con volumen persistente
docker-compose up -d

# Compila y genera el artefacto ejecutable (.jar)
mvn clean package -DskipTests

# Inicia la aplicación localmente
mvn spring-boot:run
```

## 📡 Documentación de la API (Endpoints)

La API opera bajo la ruta base `/api/v1/etl`. Las respuestas fallidas retornan una estructura estándar `{"error": "Motivo del fallo"}`.

### 🏭 Motor de Ingesta y Consulta

| Método | Endpoint   | Descripción                                                                | Payload Requerido     |
| :----- | :--------- | :------------------------------------------------------------------------- | :-------------------- |
| `POST` | `/upload`  | Inicia la ingesta asíncrona del archivo en disco e inicia el Hilo Virtual. | `MultipartFile` (CSV) |
| `GET`  | `/status`  | Método de *Polling* para consultar el avance del Job Batch en tiempo real. | Ninguno               |
| `GET`  | `/preview` | Retorna los 5 registros logísticos más recientes basados en el índice.     | Ninguno               |

### 📟 Consola Interactiva y Soporte

| Método   | Endpoint | Descripción                                                                 | Payload Requerido |
| :------- | :------- | :-------------------------------------------------------------------------- | :---------------- |
| `POST`   | `/query` | Motor SQL directo para evaluación en la terminal interactiva del dashboard. | JSON con `query`  |
| `DELETE` | `/reset` | Purga total (Modo Demo). Limpia las tablas y los metadatos de Spring Batch. | Ninguno           |