Fix ranking snapshot generator PostgreSQL default
This commit is contained in:
devRaGonSa
@@ -0,0 +1,134 @@
|
||||
---
|
||||
id: TASK-195-fix-ranking-snapshot-generator-postgres-default
|
||||
title: Fix ranking snapshot generator PostgreSQL default
|
||||
status: done
|
||||
type: backend
|
||||
team: Backend Senior
|
||||
supporting_teams:
|
||||
- Arquitecto de Base de Datos
|
||||
- Arquitecto Python
|
||||
roadmap_item: foundation
|
||||
priority: high
|
||||
---
|
||||
|
||||
# TASK-195 - Fix ranking snapshot generator PostgreSQL default
|
||||
|
||||
## Goal
|
||||
|
||||
Correct the weekly/monthly ranking snapshot CLI so production generation uses PostgreSQL by default, matching the operational `/api/ranking` read path.
|
||||
|
||||
## Context
|
||||
|
||||
`TASK-194` added a manual weekly/monthly snapshot generator, but the CLI currently passes `db_path=get_storage_path()` into `generate_ranking_snapshot(...)`. In this repository, `use_postgres_rcon_storage(...)` only enables PostgreSQL when `explicit_sqlite_path is None` and `HLL_BACKEND_DATABASE_URL` exists, so the current CLI forces SQLite while `/api/ranking` reads PostgreSQL.
|
||||
|
||||
This causes operational commands to generate `ready` snapshots with `item_count=0` and `source_matches_count=0` in SQLite even when runtime fallback over PostgreSQL returns ranking players.
|
||||
|
||||
Preserve the current product identity: Spanish-speaking HLL Vietnam community, military/Vietnam/tactical/sober visual direction and controlled repository evolution.
|
||||
|
||||
## Steps
|
||||
|
||||
1. Read the listed files first.
|
||||
2. Change the ranking snapshot CLI to use PostgreSQL by default in operational mode.
|
||||
3. Keep SQLite available only as an explicit local-development override if needed.
|
||||
4. Validate the CLI default path, repository scripts and documentation.
|
||||
5. Document root cause, fix and production validation steps.
|
||||
|
||||
## Files to Read First
|
||||
|
||||
- `AGENTS.md`
|
||||
- `ai/repo-context.md`
|
||||
- `ai/architecture-index.md`
|
||||
- `backend/app/config.py`
|
||||
- `backend/app/rcon_historical_leaderboards.py`
|
||||
- `backend/app/postgres_rcon_storage.py`
|
||||
- `scripts/run-stats-validation.ps1`
|
||||
- `docs/ranking-snapshot-read-model-plan.md`
|
||||
- `ai/tasks/done/TASK-194-add-weekly-monthly-ranking-snapshot-generator.md`
|
||||
|
||||
## Expected Files to Modify
|
||||
|
||||
- `backend/app/rcon_historical_leaderboards.py`
|
||||
- `scripts/run-stats-validation.ps1`
|
||||
- `docs/ranking-snapshot-read-model-plan.md`
|
||||
- `ai/tasks/done/TASK-195-fix-ranking-snapshot-generator-postgres-default.md`
|
||||
|
||||
## Constraints
|
||||
|
||||
- Keep the change minimal.
|
||||
- Do not modify frontend, assets or design.
|
||||
- Do not change public endpoint behavior beyond the intended generator hotfix.
|
||||
- Keep annual ranking behavior unchanged.
|
||||
- Do not reactivate Elo/MMR.
|
||||
- Do not reintroduce Comunidad Hispana #03.
|
||||
- Keep PostgreSQL as the operational default and SQLite only as an explicit local-development mode.
|
||||
|
||||
## Validation
|
||||
|
||||
Before completing the task ensure:
|
||||
|
||||
- `powershell -ExecutionPolicy Bypass -File scripts/run-stats-validation.ps1`
|
||||
- `powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1`
|
||||
- local import or parser validation proves the CLI no longer passes `get_storage_path()` by default
|
||||
- local validation proves `generate_ranking_snapshot(..., db_path=None)` uses PostgreSQL when `HLL_BACKEND_DATABASE_URL` is configured
|
||||
- `git diff --name-only` matches the expected scope
|
||||
|
||||
## Outcome
|
||||
|
||||
Root cause:
|
||||
|
||||
- the manual CLI in `backend/app/rcon_historical_leaderboards.py` called `generate_ranking_snapshot(..., db_path=get_storage_path())`
|
||||
- that forced `explicit_sqlite_path != None`
|
||||
- `use_postgres_rcon_storage(...)` therefore disabled PostgreSQL even when `HLL_BACKEND_DATABASE_URL` was configured
|
||||
- operational `/api/ranking` reads PostgreSQL, so the generator and the public ranking endpoint diverged onto different storage backends
|
||||
|
||||
Applied change:
|
||||
|
||||
- `backend/app/rcon_historical_leaderboards.py`
|
||||
- removed the default CLI path that forced SQLite
|
||||
- changed the operational default to `db_path=None`
|
||||
- added explicit `--sqlite-path <path>` override for local development only
|
||||
- `scripts/run-stats-validation.ps1`
|
||||
- now validates that the CLI default passes `db_path=None`
|
||||
- now validates that PostgreSQL selection activates when `HLL_BACKEND_DATABASE_URL` is configured and no explicit SQLite path is provided
|
||||
- `docs/ranking-snapshot-read-model-plan.md`
|
||||
- now documents PostgreSQL as the operational default
|
||||
- now documents `--sqlite-path` as an explicit local override only
|
||||
|
||||
Previous vs new behavior:
|
||||
|
||||
- before:
|
||||
- `python -m app.rcon_historical_leaderboards generate-ranking-snapshot ...`
|
||||
- forced SQLite by default
|
||||
- could generate empty snapshots operationally while `/api/ranking` fallback over PostgreSQL still returned players
|
||||
- now:
|
||||
- the same command uses PostgreSQL by default when `HLL_BACKEND_DATABASE_URL` is configured
|
||||
- SQLite is used only when the operator passes `--sqlite-path`
|
||||
|
||||
Validation executed:
|
||||
|
||||
- `powershell -ExecutionPolicy Bypass -File scripts/run-stats-validation.ps1`
|
||||
- `powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1`
|
||||
|
||||
Validation notes:
|
||||
|
||||
- live backend HTTP at `http://127.0.0.1:8000` was not available in this environment
|
||||
- route and CLI validation completed through local Python imports and repository validation scripts
|
||||
- no local PostgreSQL instance was required because the validation proved backend selection by inspection and monkeypatched connection-path checks
|
||||
|
||||
Final recommended Docker command:
|
||||
|
||||
- `docker compose exec backend python -m app.rcon_historical_leaderboards generate-ranking-snapshot --timeframe weekly --server-key all --metric kills --limit 20`
|
||||
|
||||
How to validate in production:
|
||||
|
||||
1. run the Docker command above in the production backend container
|
||||
2. query PostgreSQL `ranking_snapshots` for the selected `(timeframe, server_id, metric, window_start, window_end)`
|
||||
3. confirm `item_count > 0` and `source_matches_count > 0` for covered windows
|
||||
4. call `/api/ranking?timeframe=weekly&server_id=all&metric=kills&limit=20`
|
||||
5. confirm `snapshot_status=ready` and `fallback_used=false`
|
||||
|
||||
## Change Budget
|
||||
|
||||
- Prefer fewer than 5 modified files.
|
||||
- Prefer changes under 200 lines when feasible.
|
||||
- Split the work into follow-up tasks if limits are exceeded.
|
||||
Reference in New Issue
Block a user