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:
- Revisar la tabla
ingestas: ¿alguna fuente falló o devolvió cero? - Si una fuente devolvió cero varias corridas seguidas → probablemente cambió su contrato. Correr los tests de normalizador contra un payload fresco
- 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¶
- Capturar un payload fresco y guardarlo como fixture nuevo en
tests/fixtures/<fuente>/<fecha>.json - No borrar el fixture viejo. El histórico guardado en
crudotiene la forma antigua y el normalizador debe seguir manejándola - Actualizar el normalizador para manejar ambas formas
- Correr
renormalizar --fuente=<x>sobre el histórico - 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?