comunidadhll/ai/tasks/done/TASK-POSTGRES-RCON-PHASE-1.md

---
id: TASK-POSTGRES-RCON-PHASE-1
title: Migrate RCON historical persistence phase 1
status: done
type: backend
team: Backend Senior
supporting_teams:
  - Arquitecto de Base de Datos
  - Frontend Senior
roadmap_item: foundation
priority: high
---

# TASK-POSTGRES-RCON-PHASE-1 - Migrate RCON historical persistence phase 1

## Goal

Move the lock-prone RCON historical pipeline to PostgreSQL in Docker while
keeping local SQLite fallback and fixing the requested match-detail and server
card frontend regressions.

## Context

AdminLog ingestion and materialization currently share SQLite files with
multiple services and materialization can fail with `database is locked`.
PostgreSQL must become authoritative for RCON capture, AdminLog events,
materialized matches, player stats and the detail/recent read model in the
advanced Docker flow. Scoreboard historical persistence may remain on SQLite in
this phase when it is used only as fallback or correlation source.

## Steps

1. Inspect the storage, read-model and frontend files named in the request.
2. Add a deterministic PostgreSQL schema and route the phase-1 RCON storage
   domains through it when `HLL_BACKEND_DATABASE_URL` is set.
3. Wire Compose diagnostics and required frontend fixes without expanding Elo,
   backend scope outside RCON persistence, or Comunidad Hispana #03 targets.
4. Validate the requested commands, document what remains SQLite-backed, and
   complete the task record.

## Files to Read First

- `ai/architecture-index.md`
- `ai/repo-context.md`
- `backend/app/config.py`
- `backend/app/rcon_admin_log_storage.py`
- `backend/app/rcon_admin_log_materialization.py`
- `frontend/assets/js/historico-partida.js`

## Expected Files to Modify

- `backend/app/config.py`
- `backend/app/postgres_rcon_storage.py`
- `backend/app/rcon_admin_log_storage.py`
- `backend/app/rcon_admin_log_materialization.py`
- `backend/app/rcon_historical_storage.py`
- `backend/app/rcon_scoreboard_correlation.py`
- `backend/app/storage_diagnostics.py`
- `backend/README.md`
- `backend/requirements.txt`
- `backend/.env.example`
- `docker-compose.yml`
- `frontend/assets/js/historico-partida.js`
- `frontend/assets/js/historico.js`
- `frontend/assets/js/historico-recent-live.js`
- `frontend/assets/js/main.js`
- `frontend/assets/css/historico-scoreboard-detail.css`
- `docs/decisions.md`
- `scripts/run-historical-ui-regression-tests.ps1`

## Constraints

- PostgreSQL is the Docker default for migrated RCON domains.
- SQLite remains only fallback or source material for domains not migrated in
  this phase.
- Do not add SQLite lock workarounds as the main solution.
- Keep external scoreboard URLs on the trusted scoreboard allowlist.
- Do not modify unrelated files or add runtime database artifacts.

## Validation

- `python -m compileall backend/app`
- `python -m app.storage_diagnostics`
- `node --check frontend/assets/js/main.js`
- `node --check frontend/assets/js/historico.js`
- `node --check frontend/assets/js/historico-recent-live.js`
- `node --check frontend/assets/js/historico-partida.js`
- `powershell -ExecutionPolicy Bypass -File scripts/run-rcon-data-pipeline-tests.ps1`
- `powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1`
- Requested Docker Compose and endpoint checks when local Docker/RCON
  credentials permit them.

## Outcome

Implemented phase-1 PostgreSQL delegation for RCON capture samples/windows,
AdminLog events/profile snapshots, materialized RCON matches/player stats, and
safe scoreboard candidate caching. Docker Compose now configures PostgreSQL as
the RCON storage backend for `backend`, `historical-runner` and
`rcon-historical-worker`; local code paths with explicit SQLite paths or no
database URL retain SQLite fallback behavior.

Frontend changes remove hover-driven player panel expansion in the internal
match detail table, keep the scoreboard link on the internal detail action area
only, and suppress pending-style region placeholders on server cards.

Validation completed:

- `python -m compileall backend/app`
- `python -m app.storage_diagnostics` from `backend/`
- `node --check frontend/assets/js/main.js`
- `node --check frontend/assets/js/historico.js`
- `node --check frontend/assets/js/historico-recent-live.js`
- `node --check frontend/assets/js/historico-partida.js`
- `powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1`
- `docker compose --profile advanced config --quiet`
- local fallback HTTP smoke for `/health`,
  `/api/historical/recent-matches`, and the requested known match detail URL
- direct known-match detail payload check confirmed safe URL
  `https://scoreboard.comunidadhll.es:5443/games/1562094`

`scripts/run-rcon-data-pipeline-tests.ps1` completed parser/storage and
unittest work, then exited nonzero when its optional Docker smoke step could
not reach the Docker Desktop Linux engine. The requested `docker compose
--profile advanced up ...` and `docker compose --profile advanced ps` checks
failed for the same local engine-unavailable reason, so container diagnostics,
container RCON commands and Docker-backed HTTP probes remain to rerun when
Docker is available. The Browser plugin is listed but its required JavaScript
control tool was not exposed in this session, so rendered interaction QA remains
manual or follow-up Browser verification.

Phase boundary documented in `docs/decisions.md` and diagnostics: live server
snapshot cache, public-scoreboard `historical_*` data/rankings, historical
snapshot files, player-event ledger and paused Elo/MMR storage remain SQLite or
file-backed in this phase.

## Change Budget

This phase intentionally exceeds the default change budget because PostgreSQL
wiring crosses schema initialization, Compose runtime, RCON storage domains,
diagnostics, docs, and the requested frontend regressions. Keep the migration
surface limited to the RCON path and leave remaining SQLite domains documented.