Guía de Uso del CLI

Comandos detallados, flujos de trabajo y gestión de la base de datos de normas

Inicialización de Tablas

Si bien el sistema debe crear las tablas en la primera ejecución, puedes generarlas en todo momento utilizando el comando usando: 

python bcn_cli.py init

Gestión de Instituciones

Comandos principales para administrar las instituciones dentro del sistema, desde la carga inicial hasta la consulta de estadísticas. 

# Cargar instituciones desde CSV
python institution_cli.py load data/instituciones.csv

# Listar instituciones
python institution_cli.py list --limit 10

# Buscar institución por nombre
python institution_cli.py list --search "ministerio"

# Ver estadísticas de carga
python institution_cli.py stats

# Obtener detalles de una institución específica
python institution_cli.py get 17

Listar Normas

Permite visualizar las normas asociadas a una institución antes de proceder con la descarga o sincronización. 

# Listar normas de una institución (por ID)
python bcn_cli.py list 17

# Limitar resultados para vista rápida
python bcn_cli.py list 17 --limit 10

# Guardar el listado en un archivo JSON
python bcn_cli.py list 17 --output normas.json

Descargar Norma Específica

Herramientas para obtener el contenido de una norma individual en diferentes formatos. 

# Descargar en formato XML
python bcn_cli.py get 206396 --output_xml norma.xml

# Convertir y descargar en Markdown
python bcn_cli.py get 206396 --output_md norma.md

# Descargar XML completo (incluyendo texto y no solo metadatos)
python bcn_cli.py get 206396 --full --output_md norma.md

# Vista previa rápida en consola (sin guardar)
python bcn_cli.py get 206396

Sincronizar a Base de Datos

Gestiona la persistencia masiva de normas en la base de datos local, con soporte para caché y límites de prueba. 

# Sincronizar todas las normas de una institución
python bcn_cli.py sync 17

# Limitar cantidad (recomendado para pruebas iniciales)
python bcn_cli.py sync 17 --limit 10

# Forzar re-descarga ignorando el caché local
python bcn_cli.py sync 17 --force

# Ejemplo de flujo completo con límites y fuerza
python bcn_cli.py sync 17 --limit 5 --force

Consultas y Sistema

Búsqueda en Base de Datos 

# Búsqueda por palabra clave en normas descargadas
python bcn_cli.py search "medio ambiente"

# Limitar resultados de búsqueda
python bcn_cli.py search "cinematográfica" --limit 5

Estadísticas y Caché

# Ver estadísticas generales del sistema
python bcn_cli.py stats

# Ver errores recientes registrados
python bcn_cli.py stats --errors

# Ver estado del caché de descargas
python bcn_cli.py cache stats

# Limpiar caché (con confirmación)
python bcn_cli.py cache clear

Flujos de Trabajo Comunes

Workflow 1: Exploración Inicial

Para verificar qué normas están disponibles antes de procesarlas:

  1. Verificar ID de institución: python institution_cli.py list --search "FIA"
  2. Listar primeras 5 normas: python bcn_cli.py list 17 --limit 5
  3. Probar descarga de una: python bcn_cli.py get 206396 --output_md test.md

Workflow 2: Sincronización Masiva

Para poblar la base de datos local desde cero:

  1. Cargar maestros: python institution_cli.py load data/instituciones.csv
  2. Sincronizar lote inicial: python bcn_cli.py sync 17 --limit 20
  3. Verificar integridad: python bcn_cli.py stats

Formato de Datos

Para la carga masiva de instituciones, el archivo CSV debe seguir la siguiente estructura: 

institucion,id
Armada de Chile,1041
Asociación Chilena de Municipalidades,35
Centro de Energías Renovables,1046
Comisión Chilena de Energía Nuclear,45
  • id: Identificador numérico único de la BCN.
  • institucion: Nombre oficial de la entidad.

Si modificaste el archivo o perdiste el archivo, en el repositorio existe un respaldo.

Tips y Trucos

Testing Seguro

Usa siempre --limit cuando pruebes sincronizaciones nuevas para evitar bloqueos por parte del servidor de la BCN.

Mantenimiento

El caché de XML puede crecer rápidamente. Ejecuta cache clear periódicamente para liberar espacio.

Solución de Problemas

Error: Tabla X no existe

Solución: la CLI incluye el comando de init que se encarga de crear las tablas necesarias.

Error: "Institución no encontrada"

Solución: Asegúrate de haber cargado el CSV inicial o busca el nombre exacto con el comando list --search.

Error de conexión a PostgreSQL

Solución: Verifica que los contenedores de Docker estén activos con docker-compose ps.

Falla en la descarga de norma

Solución: Intenta limpiar el caché y forzar la descarga de nuevo con el flag --force.