comunidadhll/ai/tasks/done/TASK-124-add-internal-rcon-match-detail-api.md

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

id	title	status	type	team	supporting_teams	roadmap_item	priority
TASK-124	Add internal RCON match detail API	done	backend	Backend Senior	Arquitecto Python Frontend Senior	rcon-full-data	high

TASK-124 - Add internal RCON match detail API

Goal

Expose internal match detail data from materialized RCON matches and player stats.

Background

frontend/historico-partida.html needs a reliable internal backend payload when an external scoreboard link is unavailable or not safely correlated. The API should be RCON-first and graceful for partial or old data.

Constraints

• No UI changes in this task.
• Preserve existing query params and fallback behavior.
• If no materialized RCON detail exists, return a controlled empty or partial payload, not a 500.
• Do not reactivate Elo/MMR.
• Do not reintroduce Comunidad Hispana #03.
• Do not store secrets, runtime DB files or backend/runtime.
• Public scoreboard URL is optional enrichment only.

Allowed Changes

• backend/app/routes.py or existing route modules
• backend read-model modules for historical match detail
• backend tests for response builder/read model
• this task file when moving it through the workflow

Implementation Requirements

• Work from a dedicated branch for this task.
• Read first:
  • AGENTS.md
  • ai/architecture-index.md
  • ai/repo-context.md
  • ai/orchestrator/backend-senior.md
  • backend/app/routes.py
  • backend/app/rcon_historical_read_model.py
  • materialized match/player stats code from TASK-122 and TASK-123
  • frontend/historico-partida.html
  • frontend/assets/js/historico-partida.js
• Extend or add /api/historical/matches/detail?server=...&match=....
• Prefer an existing endpoint if present and do not break current query params.
• Response should include server, match id, map, game mode, start/end, duration, result, winner, confidence/source basis, optional external match_url, player rows and timeline/event summary.
• Player rows should include display name, team, kills, deaths, teamkills, K/D, top weapons, most killed and death-by summary.
• Keep old data fallbacks controlled and backwards-compatible.

Validation Commands

• python -m compileall backend/app
• python -m pytest backend/tests/<new_or_relevant_match_detail_api_tests>.py
• docker compose up -d --build backend
• Invoke-WebRequest "http://localhost:8000/api/historical/matches/detail?server=<server>&match=<match>"
• Invoke-WebRequest "http://localhost:8000/health"

Manual Verification Steps

• Confirm known materialized match detail returns the expected summary and players.
• Confirm missing materialized data returns a controlled partial payload.
• Confirm /health still works.
• Confirm no server #03, Elo/MMR or secrets were introduced.
• Confirm git diff --name-only matches the allowed scope.

Git Requirements

• Create a dedicated branch for this task, for example codex/task-124-rcon-match-detail-api.
• Run relevant validation before committing.
• Stage only intended files.
• Commit the completed implementation.
• Push the branch to origin.

Outcome

Extended the existing RCON historical read model behind /api/historical/matches/detail?server=...&match=... to prefer materialized RCON AdminLog match detail when available, while preserving the existing competitive-window and public-scoreboard fallback behavior.

Materialized detail payloads now include server, match id, map, game mode, start/end, duration, result, winner, confidence/source basis, safe optional match_url, player rows and timeline event counts. Player rows expose display names and derived summaries only, not raw player IDs.

Missing materialized detail remains controlled: the endpoint falls back to the existing paths and returns found: false instead of raising a 500 when no detail is available.

Validation Result

• Passed: python -m compileall backend/app
• Pytest was not installed in the local Python environment.
• Passed deterministic fallback: $env:PYTHONPATH='backend'; python -m unittest backend.tests.test_rcon_materialization_pipeline backend.tests.test_scoreboard_match_links
• Passed API smoke: Invoke-WebRequest "http://localhost:8000/health".
• Passed API detail check: Invoke-WebRequest "http://localhost:8000/api/historical/matches/detail?server=comunidad-hispana-02&match=comunidad-hispana-02:1779108337:1779111786:stmariedumontwarfare" returned found: true, result_source: admin-log-match-ended, players and timeline counts.