comunidadhll/docs/historical-coverage-report.md

Historical Coverage Report

Validation Date

• 2026-03-21

Scope

Estado real de la cobertura historica persistida localmente en backend/data/hll_vietnam_dev.sqlite3 tras ejecutar el bootstrap CRCON con el flujo reforzado de backend/app/historical_ingestion.py.

Commands Used

Desde backend/:

python -m app.historical_ingestion bootstrap --max-pages 3 --detail-workers 16

Verificacion puntual previa de idempotencia sobre la primera pagina ya importada:

python -m app.historical_ingestion bootstrap --max-pages 1 --detail-workers 8

Esa reejecucion devolvio matches_inserted: 0 y solo matches_updated para los matches ya persistidos, confirmando el comportamiento idempotente en el tramo reimportado.

Source Depth Discovered

La propia API CRCON reporto en pagina 1:

• comunidad-hispana-01: 23029 matches historicos disponibles
• comunidad-hispana-02: 18221 matches historicos disponibles

Esto confirma que la fuente publica tiene un archivo mucho mas profundo que la semana movil usada por la UI y que un bootstrap completo real es una operacion larga incluso con paralelismo.

Persisted Coverage After Bootstrap Validation

comunidad-hispana-01

• matches importados: 150
• jugadores unicos: 3986
• filas de estadisticas por jugador: 12650
• primera partida persistida: 2026-03-04T22:11:18Z
• ultima partida persistida: 2026-03-20T21:41:18Z
• rango cubierto: 15.98 dias

comunidad-hispana-02

• matches importados: 150
• jugadores unicos: 4468
• filas de estadisticas por jugador: 12665
• primera partida persistida: 2026-03-01T16:59:10Z
• ultima partida persistida: 2026-03-20T21:14:21Z
• rango cubierto: 19.18 dias

Interpretation

• La base persistida ya supera claramente la ventana semanal en ambos servidores, por lo que la UI historica ya puede distinguir entre "ranking de ultimos 7 dias" y "cobertura total importada" sin fingir que ambos conceptos son lo mismo.
• El historico local sigue siendo parcial respecto al total reportado por la fuente. Lo importado hoy es suficiente para seguir con semantica y revisiones de UI, pero no representa aun el archivo completo disponible en CRCON.

Source Limits Observed

• Bajo replays repetidos del mismo bootstrap, la fuente CRCON devolvio errores 502 Bad Gateway intermitentes en get_public_info y get_map_scoreboard.
• Con --detail-workers 16 la carga validada fue estable para 3 paginas por servidor. Con concurrencia mas alta se observaron payloads no validos con mas frecuencia.

Operational Conclusion

• El bootstrap queda reanudable por checkpoint persistido en historical_backfill_progress; si no se pasa --start-page, una nueva sesion continua desde next_page.
• Cada pagina completada actualiza por servidor:
  • last_completed_page
  • next_page
  • discovered_total_matches
  • discovered_total_pages
  • last_run
• La estrategia operativa razonable para completar todo el archivo es ejecutar varias sesiones consecutivas con el mismo comando hasta que archive_exhausted pase a true.
• --start-page se conserva solo como override manual cuando haga falta reprocesar un tramo concreto.
• Mientras no se complete todo el archivo, cualquier UI o API debe mostrar la cobertura importada como cobertura real disponible y no como historico total del servidor.