> ## 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 Generador de Reportes

> API Reportería - Generador Dinámico de Reportes CSV/PDF (Backend)

¡Te doy la bienvenida a la documentación del segundo microservicio del proyecto. El Generador Dinámico de Reportes (CSV/PDF) de mi Portafolio!

Este proyecto actúa como un microservicio *stateless* de alta precisión. Está optimizado para ingerir cargas útiles de datos (JSON) y transformarlas dinámicamente en reportes financieros (CSV y PDF), minimizando el impacto de I/O en la infraestructura.

## 🚀 Características y Arquitectura Backend

<CardGroup cols={2}>
  <Card title="Patrón Estrategia" icon="chess-knight">
    Desacoplamiento absoluto en el controlador principal mediante expresiones `match` de PHP 8. La lógica de renderizado se delega a contratos estandarizados (`ReportStrategy`).
  </Card>

  <Card title="Memoria Stateless" icon="cpu">
    Uso de flujos de memoria cruda (`php://temp`) para compilar archivos binarios pesados (CSVs) directamente en la RAM, evitando la escritura en disco físico.
  </Card>

  <Card title="Seguridad Perimetral" icon="shield-check">
    Middlewares de *Rate Limiting* (Throttle) que bloquean peticiones masivas (DoS) limitando el consumo por IP en las rutas `/api/v1/`.
  </Card>

  <Card title="Sincronización Timezone" icon="clock">
    El motor captura y adapta dinámicamente la zona horaria del cliente, garantizando consistencia temporal en metadatos y estampados.
  </Card>

  <Card title="Sanitización Defensiva" icon="eraser">
    Intercepción y normalización de datos. Los estados no reconocidos se aíslan bajo clasificadores por defecto para proteger las métricas (KPIs).
  </Card>

  <Card title="Testing Automatizado" icon="flask-conical">
    Cobertura de la integridad matemática y validación de flujos de exportación mediante el framework **Pest**.
  </Card>
</CardGroup>

## 🛠️ Stack Tecnológico

| Tecnología  | Versión | Propósito en el proyecto                                     |
| :---------- | :------ | :----------------------------------------------------------- |
| **Laravel** | `^13.0` | Framework base operando en modo API REST                     |
| **PHP**     | `^8.3`  | Lenguaje de servidor (tipado estricto y match expressions)   |
| **Dompdf**  | `^3.0`  | Motor de renderizado para compilar plantillas HTML/CSS a PDF |
| **Pest**    | `^3.0`  | Framework de pruebas para validación de artefactos           |

## 💻 Comandos de Desarrollo

Instrucciones para levantar el entorno localmente (asumiendo que el puerto `8000` está libre).

```bash theme={null}
# Instalar dependencias
composer install

# Configurar variables de entorno
cp .env.example .env

# Iniciar servidor local
php artisan serve --port=8000

# Ejecutar suite de pruebas
php artisan test
```

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

El microservicio expone rutas ligeras diseñadas para la comunicación inter-servicios o llamadas asíncronas desde el frontend.

### 🩺 Health Check (`/api/v1`)

| Método | Endpoint | Descripción                         | Respuesta       |
| :----- | :------- | :---------------------------------- | :-------------- |
| `GET`  | `/ping`  | Valida la disponibilidad del motor. | `200 OK` (JSON) |

### 🖨️ Renderizado de Artefactos (`/api/v1/reportes`)

| Método | Endpoint   | Descripción                                                             | Payload Requerido                             | Restricciones                    |
| :----- | :--------- | :---------------------------------------------------------------------- | :-------------------------------------------- | :------------------------------- |
| `POST` | `/generar` | Compila el documento solicitado y devuelve el archivo binario (`Blob`). | JSON con `formato`, `timezone` y `data.items` | Máx. 10 peticiones/minuto por IP |

***