Saltar a contenido

Runbook

Estado real vs. plan

Esta página describía el cron del sistema completo (post Fase 5). El código hoy tiene Fase 0, Fase 1 y Fase 2 completas (ver fases.md): ejecutar_ingesta, renormalizar, seed_fuentes, generar_reporte, evaluar_filtros, panel_calibracion. diff_proyectos, extraer_documentos, puntuar y check_debarment son ítems de fases posteriores — no existen como comandos todavía. Verificado contra inteligencia/management/commands/ el 2026-09-20.

Comandos de gestión disponibles

Todos se corren dentro del contenedor web: docker exec -it <container> python manage.py <comando>.

Comando Flags Qué hace
migrate --noinput Aplica migraciones de base de datos. Django estándar, corre solo al iniciar el contenedor (docker-entrypoint.sh)
collectstatic --noinput Junta archivos estáticos para Whitenoise. Django estándar, corre solo al iniciar el contenedor
createsuperuser — Crea usuario admin. Django estándar, no automatizado — correrlo a mano una vez por entorno
seed_fuentes ninguno Crea o actualiza (update_or_create) las 4 fuentes de Fase 1: BM Procnotices (carril A), BM Projects API (carril B), BID CKAN (carril A), TED EU (carril A)
ejecutar_ingesta --fuente-id=<id> (opcional) Descarga y normaliza avisos. Sin flag, corre sobre todas las fuentes con activo=True. Idempotente por fuente_id + id_nativo
renormalizar ninguno Re-ejecuta el normalizador sobre Aviso.crudo ya guardado, sin volver a descargar. No admite filtrar por fuente
generar_reporte --email=<dirección> (opcional), --telegram (opcional) Imprime a stdout hasta 10 Aviso sin decisión no_bid/ignorar, ordenados por escalón (no por fecha), con título, escalón, categoría, ⚠ marca de ventana corta, fecha límite, enlace (url_canonica) y extracto de texto_crudo. --email envía por SMTP (o consola si falta EMAIL_HOST_PASSWORD); --telegram envía al chat de TELEGRAM_CHAT_ID. Ambos flags se pueden combinar o usar solos
evaluar_filtros (Fase 2) ninguno Corre los filtros duros y de categoría (inteligencia/filtros.py) sobre avisos sin ninguna Decision todavía, y registra los descartes automáticos. Nunca toca un aviso que ya tiene decisión, manual o automática. Correr antes de generar_reporte
panel_calibracion (Fase 2) ninguno Imprime cuántos descartes automáticos hizo cada codigo_razon

generar_reporte no filtra por carril

Solo lee la tabla Aviso. El carril B (Projects API) escribe en Proyecto, no en Aviso, así que nunca aparece en el reporte — es lo que lo hace "silencioso" hoy, no un filtro explícito en el comando.

Operación normal (hoy)

Cuándo Qué corre
Diario 06:00 UTC ejecutar_ingesta para fuentes de cadencia diaria (carril A)
Diario 06:30 UTC evaluar_filtros
Lunes 06:00 UTC ejecutar_ingesta semanales (carril B, ingesta silenciosa)
Lunes 08:00 UTC generar_reporte
Jueves 08:00 UTC generar_reporte

Operación objetivo (Fase 4-5, no construido)

Cuándo Qué correría
Diario 07:00 UTC extraer_documentos, puntuar
Diario 07:30 UTC Evaluación de alertas por ventana corta
Lunes 06:00 UTC diff_proyectos

Por qué la ingesta es diaria y el reporte no

Si solo buscamos cuando reportamos, ampliamos la ventana y perdemos avisos cortos. Ingesta diaria, reporte dos veces por semana, alerta por evento.

El reporte salió vacío

Diagnóstico en orden:

  1. Revisar la tabla ingestas: ¿alguna fuente falló o devolvió cero?
  2. Si una fuente devolvió cero varias corridas seguidas → probablemente cambió su contrato. Correr los tests de normalizador contra un payload fresco
  3. Si todas devolvieron datos pero el reporte está vacío → los filtros duros están descartando de más. Revisar el panel de calibración

Silencio ≠ no hubo avisos

Es el modo de fallo más peligroso del sistema. Una fuente que devuelve cero silenciosamente parece funcionar. Por eso existe la alerta de ultimo_ok.

Una fuente cambió su contrato

  1. Capturar un payload fresco y guardarlo como fixture nuevo en tests/fixtures/<fuente>/<fecha>.json
  2. No borrar el fixture viejo. El histórico guardado en crudo tiene la forma antigua y el normalizador debe seguir manejándola
  3. Actualizar el normalizador para manejar ambas formas
  4. Correr renormalizar --fuente=<x> sobre el histórico
  5. Verificar que el conteo de registros no cambió inesperadamente

Ingesta manual / re-ingesta

python manage.py ejecutar_ingesta --fuente-id=<id>

Idempotente por fuente_id + id_nativo. Sin --fuente-id corre todas las fuentes activas.

No hay backfill por ventana de fechas todavía

ejecutar_ingesta no acepta --desde/--hasta. Descarga lo que el endpoint devuelva con los params fijos guardados en el registro Fuente (ver seed_fuentes.py). Un backfill real requiere editar esos params a mano o ampliarlos en código.

Ojo con las cuotas: SAM.gov e IATI tienen límites duros (fuentes aún no dadas de alta, ver fases.md Fase 6). Revisar la página de la fuente antes de ampliar rows.

Reprocesar tras mejorar un normalizador

python manage.py renormalizar

Sin argumentos: reprocesa todos los avisos con crudo guardado, no admite filtrar por --fuente. No vuelve a descargar.

puntuar (scoring LLM) es Fase 5, no existe todavía.

Pendiente en el próximo deploy: migrar y renormalizar

Fase 2 cambió el vocabulario de escalon (antes GPN/EOI/SPN, ahora los seis valores de la escalera de precursores) y agregó columnas nuevas a avisos y proyectos. Después de desplegar: 1. migrate (aplica la migración de columnas nuevas) 2. renormalizar (reescribe el escalon de los avisos ya guardados con el vocabulario nuevo — sin esto, los avisos ingeridos antes de este cambio quedan con GPN/EOI/SPN, que ya no aparece en ningún filtro ni en el orden del reporte) 3. evaluar_filtros (recién ahí hay avisos con las columnas nuevas pobladas)

Antes de firmar con un socio o prime

Comando pendiente de construir (Fase 3)

check_debarment no existe como comando de gestión. Hoy es una consulta SQL manual contra el dataset de sancionados del BID — ver docs/inteligencia/fuentes/bid.md. Un socio inhabilitado nos contamina en todo el sistema multilateral (inhabilitación cruzada Banco Mundial, BAD, BAfD y BERD). No saltarse este paso solo porque el comando no esté listo.

Revisión trimestral

  • Muestra manual de descartes automáticos: ¿los filtros duros se están equivocando en silencio?
  • Auditoría de recall: consultar adjudicaciones AR IV y contar cuántas de nuestro nicho el sistema nunca vio
  • Medir la mediana de días entre primera detección y fecha límite. Debe crecer
  • Revisar Pendientes de verificación: ¿qué se confirmó, qué sigue abierto?