comunidadhll/ai/tasks/done/TASK-231-fix-historical-recent-matches-single-server-timeouts.md

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

id	title	status	type	team	supporting_teams	roadmap_item	priority
TASK-231	Fix historical recent matches single server timeouts	done	backend	Backend Senior		foundation	high

TASK-231 - Fix historical recent matches single server timeouts

Goal

Corregir los dos CRITICAL restantes de la auditoria publica global:

• GET /api/historical/recent-matches?server=comunidad-hispana-01&limit=20
• GET /api/historical/recent-matches?server=comunidad-hispana-02&limit=20

Context

Tras TASK-230, la auditoria completa mostro:

• launched: 195
• OK: 78
• WARNING: 115
• CRITICAL: 2

Los dos CRITICAL restantes eran:

• historical-recent-matches-comunidad-hispana-01: timeout 30032.24 ms.
• historical-recent-matches-comunidad-hispana-02: timeout 30027.15 ms.

Los snapshots equivalentes y el legacy agregado ya respondian rapido:

• snapshot-recent-matches-comunidad-hispana-01: 77.50 ms.
• snapshot-recent-matches-comunidad-hispana-02: 51.11 ms.
• historical-recent-matches-all-servers: 50.66 ms.
• snapshot-recent-matches-all-servers: 63.33 ms.

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/rcon_historical_read_model.py
• backend/app/rcon_admin_log_materialization.py
• backend/tests/test_historical_snapshot_refresh.py

Call Chain Analysis

Cadena de auditoria:

1. scripts/audit_public_requests.py genera:
   • historical-recent-matches-comunidad-hispana-01 como GET /api/historical/recent-matches?server=comunidad-hispana-01&limit=20.
   • historical-recent-matches-comunidad-hispana-02 como GET /api/historical/recent-matches?server=comunidad-hispana-02&limit=20.
2. backend/app/routes.py mapea /api/historical/recent-matches a build_recent_historical_matches_payload(limit=..., server_slug=...).
3. Tras TASK-229, solo server=all-servers usaba snapshot fast-path.
4. CH01 y CH02 seguian entrando en get_rcon_historical_read_model().list_recent_activity(...).
5. El read model llama a list_rcon_historical_recent_activity(), que intenta primero list_materialized_rcon_matches(target_key=..., only_ended=True, limit=...).
6. Si RCON no cubria o necesitaba completar items, el builder podia entrar tambien en list_recent_historical_matches() como fallback legacy CRCON/PostgreSQL display.
7. Los snapshots equivalentes ya respondian rapido porque leen snapshots precomputados y respetan el limit.

Root Cause

El fast-path de TASK-229 para recent-matches estaba limitado a server=all-servers. Los scopes por servidor seguian usando el camino runtime RCON/materialized y podian caer al fallback legacy de scoreboard, ambos fuera del contrato de lectura publica rapida. En produccion, CH01 y CH02 agotaban los 30 s en ese path.

Changes

• backend/app/payloads.py
  • build_recent_historical_matches_payload() usa snapshot fast-path para cualquier server_slug explicito, no solo all-servers.
  • Se extrajo _build_recent_historical_matches_legacy_snapshot_payload() para conservar context, limit, server_slug, items, historical_data_source, coverage_basis y legacy_endpoint_policy.
  • Si no hay snapshot, devuelve JSON controlado con items: [] y metadata de snapshot missing, sin RCON live, sin scoreboard externo y sin fallback runtime pesado.
• backend/tests/test_historical_snapshot_refresh.py
  • Cubre que comunidad-hispana-01 no llama a get_rcon_historical_read_model() ni a list_recent_historical_matches().
  • Cubre que comunidad-hispana-02 usa el mismo fast-path.
  • Mantiene cobertura de all-servers.
  • Mantiene cobertura del fast-path de server-summary de TASK-230.
• docs/FULL_APPLICATION_REQUEST_AUDIT.md
  • Documenta el estado post-fix de TASK-231.
• docs/PERFORMANCE_PUBLIC_QUERY_AUDIT.md
  • Actualiza la politica de /api/historical/recent-matches?server=<scope> como wrapper legacy sobre snapshot read-only.

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, 19 tests.
• cd backend; python -m unittest tests.test_current_match_payload tests.test_rcon_admin_log_storage tests.test_historical_snapshot_refresh: OK, 26 tests.

Auditoria de produccion pendiente tras redeploy:

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

Outcome

Los endpoints legacy recent-matches por servidor quedan alineados con los snapshots rapidos que ya consume historico.html. CH01, CH02 y all-servers evitan RCON live, scoreboard externo, inicializaciones de storage y fallbacks runtime pesados en lectura publica.

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.
• Sin cambios en frontend ni configuracion.