comunidadhll/ai/tasks/done/TASK-229-fix-legacy-historical-summary-and-recent-matches-timeouts.md

id, title, status, type, team, supporting_teams, roadmap_item, priority

id	title	status	type	team	supporting_teams	roadmap_item	priority
TASK-229	Fix legacy historical summary and recent matches timeouts	done	backend	Backend Senior		foundation	high

TASK-229 - Fix legacy historical summary and recent matches timeouts

Goal

Corregir los endpoints historicos legacy agregados que seguian agotando el timeout de 30 s en produccion:

• GET /api/historical/server-summary?server=all-servers
• GET /api/historical/recent-matches?server=all-servers&limit=20

Context

La auditoria posterior a TASK-228 confirmo que /api/servers, /api/servers/latest y /api/servers/history ya respondian correctamente, pero dos probes legacy de historico.html legacy seguian bloqueando:

• historical-server-summary-all-servers: timeout 30024 ms.
• historical-recent-matches-all-servers: timeout 30045 ms.

No se debian tocar /api/servers, /api/current-match/kills ni /api/current-match/players.

Files Read First

• ai/architecture-index.md
• ai/repo-context.md
• ai/orchestrator/backend-senior.md
• scripts/audit_public_requests.py
• backend/app/routes.py
• backend/app/payloads.py
• backend/app/historical_storage.py
• backend/app/postgres_display_storage.py
• backend/tests/test_historical_snapshot_refresh.py

Call Chain Analysis

Cadena de auditoria:

1. scripts/audit_public_requests.py genera historical-server-summary-all-servers como GET /api/historical/server-summary?server=all-servers.
2. El mismo script genera historical-recent-matches-all-servers como GET /api/historical/recent-matches?server=all-servers&limit=20.
3. backend/app/routes.py mapea esas rutas a build_historical_server_summary_payload() y build_recent_historical_matches_payload().
4. Los builders legacy intentaban usar el read model historico RCON y, si no cubria la peticion, caian a storage legacy publico.
5. Para server=all-servers, el fallback ejecutaba agregaciones globales:
   • SQLite: list_historical_server_summaries() llama a _build_all_servers_summary() y esta recalcula conteos globales sobre tablas historicas.
   • PostgreSQL: list_scoreboard_server_summaries(server_slug=all-servers) inicializa display storage y agrega tablas migradas de public-scoreboard.
   • Recent matches puede completar desde list_recent_historical_matches(), tambien sobre storage legacy.
6. Los endpoints snapshot equivalentes (/api/historical/snapshots/server-summary y /api/historical/snapshots/recent-matches) ya respondian rapido porque solo leen snapshots precomputados con politica read-only-fast-path.

Root Cause

Los endpoints legacy agregados para all-servers conservaban fallback runtime hacia CRCON/PostgreSQL display storage. En produccion, cuando el read model RCON no cubria la respuesta o necesitaba completar datos, el request publico entraba en agregaciones globales y/o inicializacion de storage, agotando el timeout de 30 s.

Changes

• backend/app/payloads.py
  • build_recent_historical_matches_payload(server_slug="all-servers") pasa a delegar en build_recent_historical_matches_snapshot_payload().
  • build_historical_server_summary_payload(server_slug="all-servers") pasa a delegar en build_historical_server_summary_snapshot_payload().
  • Ambos wrappers conservan context legacy y campos basicos (items, limit, server_slug, summary_basis) pero exponen source: historical-precomputed-snapshots y legacy_endpoint_policy: snapshot-read-only-fast-path.
  • Si no existe snapshot, responden JSON controlado con snapshot missing y lista vacia, sin read model RCON ni fallback runtime pesado.
• backend/tests/test_historical_snapshot_refresh.py
  • Cubre que los dos endpoints legacy all-servers usan snapshots.
  • Verifica que no llaman a get_rcon_historical_read_model().
  • Verifica que no llaman a list_recent_historical_matches() ni list_historical_server_summaries().
• docs/FULL_APPLICATION_REQUEST_AUDIT.md
  • Documenta el estado post-fix de TASK-229.
• docs/PERFORMANCE_PUBLIC_QUERY_AUDIT.md
  • Actualiza la politica de los endpoints legacy agregados.

Validation

Validaciones ejecutadas:

python -m compileall backend/app
cd backend
python -m unittest tests.test_historical_snapshot_refresh
python -m unittest tests.test_current_match_payload tests.test_rcon_admin_log_storage tests.test_historical_snapshot_refresh

Resultados:

• python -m compileall backend/app: OK.
• cd backend; python -m unittest tests.test_historical_snapshot_refresh: OK, 15 tests.
• cd backend; python -m unittest tests.test_current_match_payload tests.test_rcon_admin_log_storage tests.test_historical_snapshot_refresh: OK, 22 tests.

Auditoria de produccion pendiente tras redeploy:

python .\scripts\audit_public_requests.py --base-url https://comunidadhll.devzamode.es --timeout 30 --filter servers --output tmp\task229_servers_recheck_after.json

Outcome

Los endpoints legacy agregados dejan de ejecutar read model RCON o fallback runtime pesado en lectura publica y quedan como wrappers read-only sobre snapshots precomputados. El contrato se mantiene compatible de forma razonable: HTTP 200, status: ok, data.items y metadata de snapshot/fallback.

No se cambiaron hosts, puertos, 27001, variables de entorno ni configuracion de servidores. No se tocaron frontend, assets, SVGs, imagenes fisicas, ai/system-metrics.md ni tmp/.

Change Budget

• Archivos de codigo modificados: 2.
• Documentacion actualizada: 3 archivos.
• No se creo arquitectura nueva; solo se redirigio el path legacy agregado a read models/snapshots ya existentes.