feat: materialize rcon matches and backend detail data

ai/tasks/done/TASK-122-materialize-rcon-matches-from-adminlog-events.md

@@ -0,0 +1,100 @@
+---
+id: TASK-122
+title: Materialize RCON matches from AdminLog events
+status: done
+type: backend
+team: Backend Senior
+supporting_teams:
+  - Arquitecto de Base de Datos
+  - Arquitecto Python
+roadmap_item: rcon-full-data
+priority: high
+---
+
+# TASK-122 - Materialize RCON matches from AdminLog events
+
+## Goal
+
+Create a materialization layer that converts RCON AdminLog and useful session/gamestate data into durable RCON match records.
+
+## Background
+
+Recent matches need consistent RCON-first scores. AdminLog contains `MATCH START` and `MATCH ENDED` records, while session/gamestate capture can provide partial in-progress scores. A materialized read model should make this data reliable and idempotent before UI changes consume it.
+
+## Constraints
+
+- Do not delete or replace existing competitive-window logic.
+- No UI changes.
+- Do not reactivate Elo/MMR.
+- Do not reintroduce Comunidad Hispana #03.
+- Do not store secrets, runtime DB files or `backend/runtime`.
+- Preserve RCON as the source of truth; public scoreboard is optional enrichment/fallback only.
+
+## Allowed Changes
+
+- backend storage/model modules for materialized RCON matches
+- backend tests for materialization
+- small wiring needed to initialize/read the new table
+- 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`
+  - `ai/orchestrator/database-architect.md`
+  - `backend/app/rcon_admin_log_storage.py`
+  - `backend/app/rcon_admin_log_parser.py`
+  - `backend/app/rcon_historical_read_model.py`
+  - existing historical storage modules
+- Derive RCON matches from:
+  - `match_start`
+  - `match_end`
+  - session/gamestate samples where useful
+- Store materialized records in SQLite, using a table such as `rcon_materialized_matches`.
+- Include fields for `id`, `target_key`, `external_server_id`, `match_key` or `session_key`, `map_name`, `map_pretty_name`, `game_mode`, server/event start/end times, scores, winner, `confidence_mode`, `source_basis`, `created_at` and `updated_at`.
+- Make materialization idempotent.
+- Treat `MATCH ENDED` as authoritative result when present.
+- Treat session/gamestate scores as partial or in-progress when no `MATCH ENDED` exists.
+- Parse and test results including 5-0, 2-2 and 0-5.
+
+## Validation Commands
+
+- `python -m compileall backend/app`
+- `python -m pytest backend/tests/<new_or_relevant_materialized_match_tests>.py`
+
+## Manual Verification Steps
+
+- Confirm repeated materialization does not duplicate matches.
+- Confirm a sample `MATCH ENDED \`ST MARIE DU MONT Warfare\` ALLIED (5 - 0) AXIS` produces the expected score and winner.
+- Confirm existing competitive-window reads still work.
+- Confirm `/health` still works.
+- Confirm `git diff --name-only` matches the allowed scope.
+
+## Git Requirements
+
+- Create a dedicated branch for this task, for example `codex/task-122-rcon-match-materialization`.
+- Run relevant validation before committing.
+- Stage only intended files.
+- Commit the completed implementation.
+- Push the branch to origin.
+
+## Outcome
+
+Implemented `backend/app/rcon_admin_log_materialization.py` with idempotent SQLite tables for `rcon_materialized_matches` and the shared materialization command `python -m app.rcon_admin_log_materialization`. Match records are derived from AdminLog `match_start` and `match_end` events, with `MATCH ENDED` results stored as authoritative `admin-log-match-ended` rows. Session windows remain available as partial fallback without deleting the existing competitive-window code.
+
+The command also exposes `python -m app.rcon_admin_log_materialization status` for materialization diagnostics: materialized match count, matches with player stats, first/last server time by target and event counts by type.
+
+No server #03 target was reintroduced, Elo/MMR was not reactivated, and no runtime DB files were committed.
+
+## 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 Docker smoke: `docker compose up -d --build backend rcon-historical-worker`
+- Passed Docker materialization: `docker compose exec backend python -m app.rcon_admin_log_materialization` reported `matches_seen: 24`, `matches_materialized: 24`, `errors: []`.
+- Passed diagnostic command: `docker compose exec backend python -m app.rcon_admin_log_materialization status`.