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 institution_cli.py 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 list 42 --limit 20

3. Sincronizar un subset inicial

   python bcn_cli.py 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 search "medio ambiente"

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

# Filtrar por institución específica
python bcn_cli.py search "salud pública" --institucion 17

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 sync 42

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

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

python bcn_cli.py sync 42 --force

Sincronizar múltiples instituciones

Por ahora no hay un comando batch nativo, pero puedes usar un script de shell:

bash

# Sincronizar varias instituciones en secuencia
for id in 17 42 89 134; do
  echo "Sincronizando institución $id..."
  python bcn_cli.py sync $id
done

Python

import subprocess

instituciones = [17, 42, 89, 134]

for id in instituciones:
    print(f"Sincronizando institución {id}...")
    subprocess.run(["python", "bcn_cli.py", "sync", str(id)])

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.