comunidadhll/ai/tasks/done/TASK-195-fix-ranking-snapshot-generator-postgres-default.md

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

id	title	status	type	team	supporting_teams	roadmap_item	priority
TASK-195-fix-ranking-snapshot-generator-postgres-default	Fix ranking snapshot generator PostgreSQL default	done	backend	Backend Senior	Arquitecto de Base de Datos Arquitecto Python	foundation	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.