Carga de Facturas (Node.js + Floci-AZ)

Proyecto de una API desarrollada en Node.js que permite cargar archivos a un emulador de Azure Blob Storage, encolar mensajes en Azure Queue Storage y registrar el estado inicial en SQL Server. Todo el entorno de Azure está emulado localmente mediante Floci-AZ, eliminando la necesidad de una suscripción real de Azure para el desarrollo.

Tecnologías utilizadas

• Runtime: Node.js (ES Modules)
• Framework: Express
• ORM: Sequelize (SQL Server)
• Emulación Azure: Floci-AZ
• SDKs: @azure/storage-blob, @azure/storage-queue
• Gestión de archivos: Multer (Memory Storage)

Requisitos Previos

• Docker & Docker Compose instalado.
• Node.js v20+ instalado.

Configuración del Entorno

Levantar la Infraestructura:

Crea el contenedor de Floci-AZ usando el siguiente comando:

docker run -d --name floci-az -p 4577:4577 -v /var/run/docker.sock:/var/run/docker.sock floci/floci-az:latest

Crea una docker network que permitirá conectar el contenedor de Floci-AZ con el contenedor de la base de datos SQL Server:

docker network create floci-network

Conecta el contenedor Floci-AZ a la red:

docker network connect floci-network floci-az

Conecta el contenedor SQL Server a la red:

docker network connect floci-network sql_server

Variables de Entorno:

Crea un archivo .env basado en el siguiente ejemplo:

PORT=3000

AZURE_STORAGE_CONNECTION_STRING="DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=fakedata...;BlobEndpoint=http://localhost:4577/devstoreaccount1;QueueEndpoint=http://localhost:4577/devstoreaccount1-queue;"
AZURE_BLOB_CONTAINER_NAME="uploads"
AZURE_QUEUE_NAME="file-processing-queue"

DB_SERVER=localhost
DB_PORT=1433
DB_DATABASE=MiBaseDatos
DB_USER=sa
DB_PASSWORD=TuPasswordSeguro123!

Instalar dependencias:

npm install

Ejecución

Para iniciar la API en modo desarrollo (con auto-recarga):

npm run dev

Al iniciar, la API realizará automáticamente:

• Conexión y sincronización de tablas en SQL Server.
• Creación del contenedor de blobs en Floci-AZ.
• Creación de la cola de mensajería en Floci-AZ.

Endpoints

Subir Archivo

• URL: POST /api/v1/uploads
• Cuerpo (form-data):
  • file: Archivo binario (Imagen, PDF, etc.)
  • description: Texto descriptivo (opcional)

Respuesta Exitosa (201):

{
  "success": true,
  "message": "Archivo recibido, persistido en BD y encolado.",
  "data": {
    "fileId": "uuid-generado",
    "blobUrl": "http://localhost:4577/...",
    "messageId": "id-de-la-cola"
  }
}

Estructura del Proyecto

src/
├── config/         # Configuraciones de Clientes Azure y DB
├── controllers/    # Manejo de peticiones HTTP
├── models/         # Definición de modelos de Sequelize
├── repositories/   # Acceso directo a datos (Storage/DB)
├── services/       # Lógica de negocio y orquestación
└── app.js          # Punto de entrada