semillero-INVIMA/analisis_modelo_invima.md

Analisis matematico y computacional del modelo de consulta INVIMA

1. Resumen tecnico del modelo real implementado

El sistema vigente implementa una plataforma de consulta sobre datos abiertos del INVIMA publicados en Socrata/datos.gov.co. La fuente se configura en backend/APIinvima.json, con base URL https://www.datos.gov.co/resource y ocho datasets: dispositivos, rs_nso, medicamentos, cum_vigentes, homeopaticos, fitoterapeuticos, suplementos y vacunas.

El flujo real es:

1. Extraccion: fetchInvimaDataset construye URLs SODA con $limit, $offset, $select, $where y $order, aplica token opcional, timeout, reintentos y backoff.
2. Normalizacion por dataset: invimaAdapters convierte columnas heterogeneas de cada dataset hacia un esquema comun. En este paso se limpian textos, se parsean fechas y se genera source_uid con SHA-1.
3. Persistencia: persistBatch guarda cada lote en dos estructuras: invima_api_raw, con el JSON crudo, e invima_api_catalog, con campos normalizados.
4. Clasificacion y enriquecimiento: normalizeCatalogRecord calcula categoria_canonica, categoria_slug y search_text.
5. Indexacion: ensureInvimaTables crea indices por dataset, categoria, estado, registro, expediente, modalidad, grupo, fechas, FTS en espanol y trigramas opcionales.
6. Consulta: getInvimaCatalog parsea filtros, ejecuta runCatalogQuery y usa to_tsvector/websearch_to_tsquery o ILIKE como respaldo.
7. Presentacion: Angular consulta /api/invima/catalogo, muestra tabla paginada y permite exportar CSV/XLSX por /api/invima/catalogo/export.

Los archivos historicos Productos.csv, products_comands.py, databasepg.js, comandos.txt y comandos en pgadmin4.txt pertenecen al flujo legacy de tabla productos. El README.md del backend indica que ese flujo fue eliminado del modelo vigente y reemplazado por el catalogo unico invima_api_catalog.

2. Variables principales del modelo

En el codigo, la variable independiente primaria no es solo "dispositivo medico"; es el conjunto de criterios de consulta enviado por el usuario:

c = (q, categorias, datasets, estados, modalidades, grupos, fechaVencDesde, fechaVencHasta, fechaExpDesde, fechaExpHasta, onlyVigentes, limit, offset)

Cuando q representa un producto o dispositivo medico, el producto puede tratarse como variable independiente conceptual:

x = producto

Sin embargo, el buscador real aplica q sobre search_text, registro_sanitario, expediente, producto, categoria_canonica y categoria_linea. Por tanto, q es una variable independiente textual general.

Variables dependientes implementadas en invima_api_catalog:

• Identificacion/fuente: source_dataset_key, source_dataset_id, source_uid, source_dataset_name.
• Clasificacion: categoria_linea, categoria_canonica, categoria_slug, grupo, modalidad.
• Registro/producto: expediente, registro_sanitario, producto, marca.
• Actor regulatorio/comercial: titular, rol_nombre, rol_tipo, ciudad_titular, pais_titular, fabricante, importador.
• Estado/tiempo: estado_registro, vigencia, fecha_expedicion, fecha_vencimiento.
• Campos especificos de medicamentos/tecnologias: principio_activo, forma_farmaceutica, presentacion_comercial, atc.
• Campos tecnicos: search_text, extra, fetched_at, updated_at.

Campos fundamentales para identificar un registro: source_dataset_key + source_uid como clave primaria, y como identificadores semanticos registro_sanitario, expediente, producto y source_dataset_key. Los campos complementarios son los atributos regulatorios, comerciales, de clasificacion y de vigencia.

3. Dominio formal de las variables

Sea R la relacion invima_api_catalog. Los dominios implementados pueden definirse asi:

D_{dataset} = \{source\_dataset\_key\}

D_{uid} = \{source\_uid\}

D_{producto} = \{producto \mid producto \in R\}

D_{registro} = \{registro\_sanitario \mid registro\_sanitario \in R\}

D_{expediente} = \{expediente \mid expediente \in R\}

D_{titular} = \{titular \mid titular \in R\}

D_{estado} = \{estado\_registro \mid estado\_registro \in R\}

D_{categoria} = \{categoria\_slug, categoria\_canonica, categoria\_linea \mid registros\ de\ R\}

D_{modalidad} = \{modalidad \mid modalidad \in R\}

D_{grupo} = \{grupo \mid grupo \in R\}

D_{fechaExp}, D_{fechaVenc} \subseteq Date

D_{texto} = vocabulario(search\_text)

El dominio de busqueda del sistema es el producto cartesiano restringido por registros existentes e indices de PostgreSQL:

D_c = D_{texto} \times \mathcal{P}(D_{categoria}) \times \mathcal{P}(D_{dataset}) \times \mathcal{P}(D_{estado}) \times \mathcal{P}(D_{modalidad}) \times \mathcal{P}(D_{grupo}) \times D_{fechaExp}^2 \times D_{fechaVenc}^2

4. Relacion entre datos

La relacion principal del modelo puede expresarse como:

R \subseteq D_{dataset} \times D_{uid} \times D_{categoria} \times D_{expediente} \times D_{registro} \times D_{producto} \times D_{titular} \times D_{estado} \times D_{fechaExp} \times D_{fechaVenc} \times D_{modalidad} \times D_{grupo} \times D_{marca} \times D_{principio} \times D_{forma} \times D_{presentacion} \times D_{atc} \times D_{rol} \times D_{ubicacion} \times D_{fabricante} \times D_{importador} \times D_{vigencia} \times D_{extra}

Esta formulacion representa correctamente la tabla invima_api_catalog, siempre que se entienda que algunos dominios son opcionales o nulos segun el dataset. La relacion cruda complementaria es:

R_{raw} \subseteq D_{dataset} \times D_{uid} \times JSONB \times D_{timestamp}

5. Ecuacion de consulta o filtrado

La consulta real combina seleccion, ordenamiento, ranking textual y paginacion:

S = \tau_{orden}\left(\sigma_{P_c}(R)\right)

Q(R,c,limit,offset) = \pi_{limit,offset}(S)

Donde P_c(r) es verdadero si se cumplen las condiciones generadas por buildCatalogWhere: texto libre, categorias, datasets, estados, modalidades, grupos, rangos de fechas y vigencia. Si q tiene al menos tres caracteres se usa:

to\_tsvector(search\_text) \@@ websearch\_to\_tsquery(q)

con respaldo por ILIKE en registro_sanitario, expediente, producto, categoria_canonica y categoria_linea. Esta formulacion se ajusta mejor que una simple seleccion, porque el codigo tambien calcula COUNT(*), ts_rank, ORDER BY, LIMIT y OFFSET.

6. Dependencia entre variable independiente y variables dependientes

Si el criterio independiente es un producto o dispositivo medico x \in D_{producto}, la salida es multivaluada:

g(x) = \{r \in R \mid producto(r) \sim x \lor search\_text(r) \sim x\}

La proyeccion de atributos dependientes es:

Y_x = \pi_{registro\_sanitario, expediente, titular, estado\_registro, categoria\_canonica, modalidad, grupo, fecha\_expedicion, fecha\_vencimiento, vigencia, fabricante, importador, source\_dataset\_name}(g(x))

No es una funcion uno a uno: un producto puede aparecer en varios datasets, registros, roles o titulares, y un registro puede generar varias filas si la fuente distingue roles o actores.

7. Ecuacion de transformacion de datos

El sistema si transforma datos antes de consultarlos. La forma general es:

f_d: R_{crudo,d} \rightarrow R_{catalogo}

Para cada fila cruda r_i de un dataset d:

t_i = I(S(C(M_d(N(L(r_i))))))

Donde:

• L: limpieza de texto (cleanText), eliminando vacios y texto "null".
• N: normalizacion de fechas (parseDateFlexible) y campos comunes.
• M_d: mapeo especifico por dataset (invimaAdapters).
• C: clasificacion canonica (normalizeCategory) y categoria_slug.
• S: construccion de search_text.
• I: integracion/upsert transaccional en invima_api_raw e invima_api_catalog.

La ecuacion representa el flujo real, con la salvedad de que no todos los datasets llenan todos los atributos.

8. Metricas recomendadas

Medibles con el codigo actual:

• Numero de filas crudas: rawRows.
• Numero de filas normalizadas: catalogRows.
• Filas descargadas, persistidas y paginas por sincronizacion: fetched, persisted, pages.
• Datasets exitosos/fallidos durante sincronizacion.
• Conteo de categorias, datasets con datos, vigentes y vencidos.
• Total de resultados por consulta, limit y offset.
• Duracion aproximada de una sincronizacion por startedAt y finishedAt del job en memoria.

Requieren instrumentacion adicional:

• Tiempo promedio/maximo de respuesta por consulta.
• Historial persistente de consultas y tiempos.
• CPU, memoria, disponibilidad y throughput real del servidor.
• Precision, recall, falsos positivos y falsos negativos, porque requieren conjunto de verdad o evaluacion manual.
• Error absoluto entre registros esperados y obtenidos, porque requiere valor esperado externo.
• Repetibilidad estadistica de tiempos, porque hoy no se guarda serie historica de tiempos.

9. Ecuaciones de metricas

Tiempo promedio de respuesta:

T_{prom} = \frac{1}{n}\sum_{i=1}^{n}T_i

Tiempo maximo:

T_{max} = \max(T_i)

Throughput:

Th = \frac{N_{consultas}}{T_{total}}

Tasa de fallos:

TF = \frac{N_{fallos}}{N_{consultas}} \times 100

Porcentaje de consultas exitosas:

CE = \frac{N_{exitosas}}{N_{consultas}} \times 100

Error absoluto:

EA = |R_{esperado} - R_{obtenido}|

Error porcentual:

EP = \frac{|R_{esperado} - R_{obtenido}|}{R_{esperado}} \times 100

Precision:

Precision = \frac{VP}{VP + FP}

Recall:

Recall = \frac{VP}{VP + FN}

Repetibilidad temporal:

Rep = 1 - \frac{\sigma_T}{\mu_T}

Registros procesados por segundo en sincronizacion:

RPS = \frac{N_{persistidos}}{T_{sync}}

Disponibilidad:

A = \frac{T_{activo}}{T_{total}} \times 100

10. Archivos, funciones y endpoints importantes

• Fuente/configuracion: backend/APIinvima.json; backend/APIinvima.js (buildInvimaUrl, fetchInvimaDataset).
• Adaptacion y transformacion: backend/invima/adapters.js (cleanText, parseDateFlexible, buildUid, baseRecord, invimaAdapters).
• Tablas e indices: backend/invima/service.js (ensureInvimaTables); backend/comando.sql.
• Sincronizacion: backend/invima/service.js (syncOneDataset, syncInvimaDatasets, persistBatch); backend/invima/sync-job-manager.js.
• Busqueda/filtros: backend/invima/service.js (parseCatalogFilters, buildCatalogWhere, runCatalogQuery, getInvimaCatalog).
• Exportacion: backend/invima/service.js (getInvimaCatalogForExport, getInvimaCatalogForExportChunk, toCsv); backend/src/routes/invima.routes.js.
• Endpoints: GET /api/invima/datasets, GET /api/invima/categorias, GET /api/invima/filtros, GET /api/invima/sync/stats, GET /api/invima/sync/job, POST /api/invima/sync, GET /api/invima/catalogo, GET /api/invima/catalogo/export.
• Frontend de consulta: semillero/src/app/core/services/invima.service.ts; semillero/src/app/features/invima/catalog-page.component.ts.
• Frontend de sincronizacion: semillero/src/app/features/invima/sync-page.component.ts.
• Manejo de errores: backend/src/middlewares/error.middleware.js.
• Validaciones basicas: clampInt, parseListParam, parseCatalogFilters, requireAuth.

No se encontro instrumentacion persistente de logs de consulta, tiempos por endpoint o metricas de CPU/memoria. Los logs existentes son console.warn, console.error y mensajes de arranque.

11. Texto academico en tercera persona

La plataforma implementa un modelo computacional de integracion y consulta de datos abiertos del INVIMA basado en una arquitectura de extraccion, normalizacion, almacenamiento e interrogacion sobre PostgreSQL. Los datos se obtienen desde datasets publicados en la API Socrata de datos.gov.co, configurados mediante identificadores de recurso. Cada conjunto de datos posee una estructura original potencialmente diferente, por lo cual el sistema aplica adaptadores especificos que transforman las filas crudas en un esquema comun de catalogo.

El modelo distingue dos niveles de almacenamiento. El primero conserva la representacion cruda de la fuente en formato JSONB, permitiendo trazabilidad frente al origen. El segundo corresponde a una relacion normalizada denominada invima_api_catalog, en la cual se integran atributos comunes como registro sanitario, expediente, producto, titular, estado del registro, fechas, modalidad, grupo, categoria, fabricante, importador y vigencia. Esta relacion constituye el dominio principal de consulta.

Formalmente, el catalogo puede representarse como una relacion R definida sobre dominios de producto, registro, titular, estado, categoria, fechas y fuente. El proceso de consulta corresponde a una operacion de seleccion parametrizada por criterios introducidos por el usuario. Dichos criterios incluyen texto libre, categorias, datasets, estados, modalidades, grupos, rangos de fechas y vigencia. La seleccion se complementa con ordenamiento, ranking textual y paginacion, por lo que la consulta puede expresarse como Q(R,c,limit,offset)=\pi_{limit,offset}(\tau_{orden}(\sigma_{P_c}(R))).

Cuando el usuario introduce un nombre de producto o dispositivo medico, este actua como variable independiente de busqueda. El resultado no es un valor unico, sino un conjunto de registros relacionados que contienen variables dependientes tales como registro sanitario, expediente, titular, estado, categoria, fechas de expedicion y vencimiento, modalidad, grupo, fabricante, importador, fuente y vigencia. Por tanto, la dependencia puede modelarse como una funcion multivaluada g(x), donde x representa el producto consultado y g(x) retorna el subconjunto de filas del catalogo asociadas al criterio.

La transformacion de datos puede formalizarse como f_d: R_{crudo,d} \rightarrow R_{catalogo}. Para cada fila cruda, el sistema ejecuta limpieza textual, normalizacion de fechas, mapeo de columnas segun el dataset, clasificacion canonica, construccion de texto de busqueda e integracion transaccional en la base de datos. Esta formulacion refleja el comportamiento real del codigo y permite describir la plataforma como un modelo reproducible de consulta de datos abiertos, con trazabilidad desde la fuente original hasta la respuesta presentada al usuario.

Para evaluar el modelo se recomienda medir tiempo de respuesta, throughput, tasa de fallos, cantidad de registros procesados por segundo, cantidad de resultados por consulta, consistencia ante consultas repetidas, precision y recall. El codigo actual permite medir conteos de registros, avance de sincronizacion, datasets fallidos, paginas procesadas, vigentes, vencidos y total de resultados. No obstante, las metricas de rendimiento temporal, consumo de recursos, precision y recall requieren instrumentacion adicional y, en algunos casos, conjuntos de referencia validados.

12. Resultados actuales medidos en la base local

Fecha de medicion: 2026-07-07. Ultima actualizacion registrada en los datos: 2026-07-01 01:05:22 UTC.

Volumen y clasificacion

• Registros procesados y normalizados en invima_api_catalog: 1 407 694.
• Registros crudos preservados en invima_api_raw: 1 407 694.
• Datasets con datos: 8.
• Categorias canonicas por categoria_slug: 21.
• Etiquetas de categoria visibles por categoria_canonica: 28.
• Registros vigentes: 751 208.
• Registros vencidos: 632 435.
• Estados distintos: 48.
• Modalidades distintas: 48.
• Grupos regulatorios distintos: 16.

Distribucion por dataset

Dataset	Registros
rs_nso	1 085 799
dispositivos	189 604
cum_vigentes	66 501
medicamentos	54 047
suplementos	6 091
homeopaticos	3 477
fitoterapeuticos	2 127
vacunas	48

Dispositivos y equipos medicos

Para el dataset dispositivos, el sistema contiene 189 604 registros consultables. El campo grupo organiza esos registros en cuatro grupos regulatorios:

Grupo	Registros
MEDICO QUIRURGICOS	91 826
REACTIVO DIAGNOSTICO	68 529
REACTIVOS IN VITRO	29 219
ODONTOLOGICOS	30

Estados principales en dispositivos:

Estado	Registros
Vigente	125 117
Vencido	47 482
Cancelado	5 926
Perdida Fuerza Ejec	4 530
En Estudio	2 596

Demora de consultas SQL

Las demoras se midieron con EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) sobre PostgreSQL local. Los tiempos incluyen planeacion y ejecucion de SQL, no latencia HTTP ni renderizado Angular.

Consulta SQL representativa	Planeacion	Ejecucion	Total SQL
COUNT(*) total de invima_api_catalog	8.20 ms	187.55 ms	195.75 ms
Catalogo general paginado, LIMIT 25	52.88 ms	6 160.19 ms	6 213.06 ms
Conteo de dispositivos	0.12 ms	149.81 ms	149.94 ms
Conteo de dispositivos vigentes	6.41 ms	287.12 ms	293.53 ms
Filtro dispositivos vigentes, LIMIT 25	1.66 ms	375.79 ms	377.45 ms
Busqueda textual real del backend para marcapasos, LIMIT 25	82.85 ms	40 427.49 ms	40 510.33 ms
Conteo de busqueda textual real para marcapasos	0.27 ms	37 825.12 ms	37 825.38 ms

Como runCatalogQuery ejecuta primero COUNT(*) y despues la consulta paginada, una busqueda textual como marcapasos puede tardar aproximadamente 78.34 s solo en SQL si se suman conteo y pagina de resultados. En contraste, una consulta filtrada por dataset y vigencia en dispositivos tarda aproximadamente 0.67 s en SQL al sumar conteo y pagina.

Tambien se midio la busqueda FTS pura, sin los OR ILIKE adicionales del backend:

Consulta FTS pura	Resultados	Tiempo observado
marcapasos	420	92.98 ms
vacuna	612	7.27 ms

Esto muestra que el indice FTS funciona de forma eficiente, pero la condicion real del backend combina FTS con varios ILIKE, lo que puede producir exploraciones mas costosas.

SQL base usado para los conteos

SELECT
  COUNT(*)::bigint AS catalog_rows,
  COUNT(DISTINCT source_dataset_key)::int AS datasets_with_data,
  COUNT(DISTINCT categoria_slug)::int AS categories,
  COUNT(*) FILTER (
    WHERE (COALESCE(estado_registro, '') ILIKE '%vigente%'
       OR COALESCE(vigencia, '') ILIKE '%vigente%')
      AND COALESCE(estado_registro, '') NOT ILIKE '%no vigente%'
      AND COALESCE(vigencia, '') NOT ILIKE '%no vigente%'
  )::bigint AS vigentes,
  COUNT(*) FILTER (
    WHERE COALESCE(estado_registro, '') ILIKE '%vencido%'
       OR COALESCE(vigencia, '') ILIKE '%vencido%'
  )::bigint AS vencidos,
  MAX(updated_at) AS max_updated_at
FROM invima_api_catalog;

SELECT grupo, COUNT(*)::bigint AS total
FROM invima_api_catalog
WHERE source_dataset_key = 'dispositivos'
  AND grupo IS NOT NULL
  AND grupo <> ''
GROUP BY grupo
ORDER BY total DESC;

Parrafo de resultados actualizado

Como resultado de la medicion actual, el modelo computacional consolido 1 407 694 registros procesados y normalizados en la tabla invima_api_catalog, manteniendo igual numero de registros crudos en invima_api_raw para trazabilidad con la fuente original. Para el conjunto de dispositivos medicos y otras tecnologias, integro 189 604 registros consultables, distribuidos en cuatro grupos regulatorios principales: medico quirurgicos, reactivo diagnostico, reactivos in vitro y odontologicos. En el catalogo general, el sistema clasifico 751 208 registros vigentes y 632 435 registros vencidos, organizados en 21 categorias canonicas y ocho datasets oficiales. Las pruebas SQL mostraron tiempos de consulta de 195.75 ms para el conteo total del catalogo, 377.45 ms para recuperar una pagina de dispositivos vigentes y 40.51 s para una busqueda textual completa con las condiciones reales del backend. Estos resultados evidencian la capacidad del modelo para estructurar grandes volumenes de datos regulatorios y tambien muestran que la busqueda textual combinada con condiciones ILIKE requiere optimizacion adicional para mejorar el rendimiento.