Guía de uso

Esta guía cubre los flujos de trabajo más comunes. Si buscas la referencia completa de comandos ve a CLI Reference.

Flujo básico: descargar normas de una institución

El flujo estándar para empezar a trabajar con una institución nueva:

1. Buscar la institución por nombre

   python bcn_cli.py instituciones list --search "contraloria"

   Ejemplo de salida:

   ID    Nombre
   ----  ------------------------------------------
   42    Contraloría General de la República

2. Ver las normas disponibles sin descargar

   python bcn_cli.py normas list 42 --limit 20

3. Sincronizar un subset inicial

   python bcn_cli.py normas sync 42 --limit 50

4. Verificar con stats

   python bcn_cli.py stats

Búsqueda full-text

La búsqueda usa PostgreSQL FTS con diccionario español, lo que significa que busca por raíces de palabras, no solo texto exacto.

# Busca "ambiental", "ambientales", "medioambiente", etc.
python bcn_cli.py normas search "medio ambiente"

# Limitar resultados
python bcn_cli.py normas search "decreto supremo" --limit 5

Tip

La búsqueda solo encuentra normas que ya están en tu base de datos local. Sincroniza primero las instituciones que te interesan.

Sincronización incremental

BCN Extractor detecta cambios automáticamente via hash MD5. Si corres sync dos veces sobre la misma institución, la segunda vez solo actualiza las normas que cambiaron:

# Primera vez: descarga todo
python bcn_cli.py normas sync 42

# Segunda vez: solo actualiza lo que cambió (mucho más rápido)
python bcn_cli.py normas sync 42

Para forzar la re-descarga de todo aunque no haya cambios detectados:

python bcn_cli.py normas sync 42 --force

Sincronizar múltiples instituciones con el Scheduler

El Scheduler permite programar la sincronización automática de cualquier conjunto de instituciones como un proceso independiente en background, sin bloquear la terminal.

# Iniciar el scheduler para las instituciones 17, 42 y 1041
python bcn_cli.py scheduler start --inst 17,42,1041

# Con horario específico (2:00 AM UTC, solo días de semana)
python bcn_cli.py scheduler start --inst 17,42 --hora 2 --minuto 0 --dia mon-fri

# Ver estado
python bcn_cli.py scheduler status

# Ver jobs y su último resultado
python bcn_cli.py scheduler list

# Agregar una institución sin reiniciar el scheduler
python bcn_cli.py scheduler add 89 --hora 3

# Detener
python bcn_cli.py scheduler stop

Los logs se escriben en logs/scheduler.log y el estado de cada ejecución queda en la tabla scheduler_jobs.

Tip

Si solo necesitas sincronizar unas pocas instituciones de forma puntual, puedes encadenar comandos en shell directamente:

for id in 17 42 89; do
  python bcn_cli.py normas sync $id
done

---

Análisis NLP

El pipeline NLP es una etapa opcional que corre después del sync. Extrae referencias entre normas, entidades nombradas (organismos, personas, lugares) y obligaciones con sus plazos.

Analizar una institución completa

# Analizar todas las normas ya sincronizadas de una institución
python bcn_cli.py nlp analizar-institucion 17

# Limitar el batch para empezar
python bcn_cli.py nlp analizar-institucion 17 --limit 50

# Re-analizar normas que ya tienen análisis
python bcn_cli.py nlp analizar-institucion 17 --forzar

Consultar los resultados

# Referencias normativas que cita la norma (y su estado de resolución)
python bcn_cli.py nlp referencias 206396

# Grafo inverso: quién cita a esta norma
# (disponible en la TUI, tab "Citado por")

# Entidades nombradas, filtradas por tipo
python bcn_cli.py nlp entidades 206396 --tipo organismo

# Obligaciones detectadas
python bcn_cli.py nlp obligaciones 206396 --con-plazo

Resolver referencias pendientes

A medida que sincronizas más instituciones, las referencias que apuntaban a normas aún no descargadas se pueden vincular:

python bcn_cli.py nlp resolver

Ver el análisis en la TUI

El tab NLP de la TUI muestra el análisis completo de la norma seleccionada, organizado en cuatro sub-tabs: Referencias, Citado por, Entidades y Obligaciones. Se actualiza automáticamente al cambiar de norma en el tab principal.

Note

El análisis NLP usa el XML ya cacheado por el sync. No genera tráfico adicional a la BCN. Si una norma no tiene XML en caché, se omite del batch con una advertencia.

---

Usar la REST API

Levanta el servidor:

fastapi dev api/main.py

# o con uvicorn para producción:
uvicorn api.main:app --host 0.0.0.0 --port 8000

Luego puedes consultar la API directamente:

# Listar normas (paginado)
curl "http://localhost:8000/normas/?limit=10&offset=0"

# Buscar
curl "http://localhost:8000/normas/buscar/medio%20ambiente"

# Norma específica (live desde BCN)
curl http://localhost:8000/normas/1234567

# Normas de una institución (desde DB)
curl "http://localhost:8000/instituciones/17/normas?limit=20"

# Filtrar por estado
curl "http://localhost:8000/normas/estado/vigente"

# Filtrar por rango de fechas
curl "http://localhost:8000/normas/rango?start_date=2023-01-01&end_date=2023-12-31"

La documentación interactiva está en http://localhost:8000/docs.

Ver los logs de operaciones

Cada descarga y sincronización queda registrada en la tabla descargas. Puedes consultarla directo en PostgreSQL:

-- Últimas 20 operaciones
SELECT id_norma, tipo_descarga, estado, fecha_intento, error_mensaje
FROM descargas
ORDER BY fecha_intento DESC
LIMIT 20;

-- Solo errores
SELECT * FROM descargas
WHERE estado = 'error'
ORDER BY fecha_intento DESC;

O conéctate con cualquier cliente PostgreSQL (TablePlus, DBeaver, psql) usando las credenciales de tu .env.

Acceder a los archivos XML y Markdown

Las normas descargadas se guardan en disco además de en la base de datos:

Tipo	Ruta
XML original	data/xml/<id_norma>.xml
Markdown generado	data/md/<id_norma>.md
Logs	data/logs/
Caché	data/cache/

Los archivos XML son el respaldo auditable — si el parser cambia en el futuro, puedes re-procesar sin volver a descargar desde la BCN.