Servicios Node.js

Servicio: json-block-list

Información General

Propósito: API para consulta y comparación de bloques contra el catálogo Lean BIM. Actúa como intermediario para validar nuevos modelos antes de su carga, y parsear archivos XML de IFC.
Tecnología: Node.js 18+ / Express v4.x
Puerto: 3060 (default)
Módulo npm: json-block-list

Propósito de Negocio

Antes de cargar un nuevo modelo IFC, el coordinador BIM puede: - Comparar los bloques del nuevo modelo contra el catálogo existente - Identificar bloques nuevos, modificados, o sin código - Parsear archivos XML generados desde IFC para pre-validar bloques

Endpoints Expuestos

Path	Descripción
`GET /`	Metadata del servicio y listado de endpoints
`GET /health`	Health check
`GET /viewer`	Interfaz web de visualización (sirve `index.html`)
`GET /api/blocks/catalog`	Catálogo completo de bloques del proyecto
`GET /api/blocks/descriptions`	Solo descripciones de bloques
`GET /api/blocks/by-label`	Bloques de una etiqueta específica
`POST /api/blocks/compare`	Compara array de bloques contra catálogo en BD
`POST /api/blocks/compare-xml`	Parsea XML de IFC y compara contra catálogo

Base de Datos

Motor: MongoDB
Driver: MongoDB nativo v6.x (no Mongoose)
Conexión: Lazy (conecta al primer request)
URI: Configurada en variable de entorno MONGO_URI (contiene credenciales por defecto — migrar a env var protegida)

Colecciones Usadas

Colección	Base de Datos	Descripción
`leanbim_blocks`	`{projectCode}`	Catálogo de bloques Lean BIM
`labels`	`{projectCode}`	Etiquetas para búsqueda por label

Variables de Entorno

Variable	Descripción
`PORT`	Puerto HTTP (default: `3060`)
`HOST`	Host de escucha (default: `0.0.0.0`)
`DEFAULT_PROJECT_CODE`	Código de proyecto por defecto (default: `"0001V"`)
`MONGO_URI`	URI de MongoDB (sensible)
`PARSER_URL`	URL del servicio de parseo XML externo

Categorización de Comparación

POST /api/blocks/compare categoriza cada bloque entrante:

Categoría	Condición
`existing`	Mismo `code` y misma `description` en catálogo
`updatedDescription`	Mismo `code`, diferente `description`
`newBlocks`	El `code` no existe en el catálogo
`withoutCode`	Bloque sin campo `code` definido

La respuesta incluye un summary estadístico con totales por categoría.

Normalización de Texto

Para comparación robusta, todos los textos se normalizan:

function normalizeText(str) {
  return str
    .normalize('NFD')          // descompone caracteres acentuados
    .replace(/[̀-ͯ]/g, '')  // elimina diacríticos
    .toUpperCase()             // convierte a mayúsculas
    .trim()                    // elimina espacios extremos
    .replace(/\s+/g, ' ')     // colapsa espacios múltiples
}

Esto permite hacer match: "muro hormigón" === "MURO HORMIGON".

Flujo de compare-xml

Cliente sube archivo XML (extraído de IFC) vía multipart
Multer captura el archivo en memoria (máx 10 MB)
POST a PARSER_URL (servicio externo) con el XML
El parser retorna JSON: { blocks: [{code, description}] }
Se ejecuta la comparación estándar con el catálogo
Retorna categorización completa + summary

Dependencias NPM

Paquete	Versión	Uso
`express`	4.21.2	Framework HTTP
`mongodb`	6.16.0	Driver MongoDB nativo
`multer`	1.4.5-lts.1	Manejo de multipart/form-data
`axios`	1.9.0	Llamada a PARSER_URL externo
`cors`	2.8.5	CORS middleware
`form-data`	4.0.1	Constructor de multipart para axios

Rol en Casos de Uso

Caso de Uso	Rol
CU-11: Comparación de Bloques	Servicio principal