Fix PostgreSQL ranking snapshot schema
This commit is contained in:
devRaGonSa
126
ai/tasks/done/TASK-192-fix-postgres-ranking-snapshot-schema.md
Normal file
126
ai/tasks/done/TASK-192-fix-postgres-ranking-snapshot-schema.md
Normal file
@@ -0,0 +1,126 @@
|
||||
---
|
||||
id: TASK-192-fix-postgres-ranking-snapshot-schema
|
||||
title: Fix PostgreSQL ranking snapshot schema
|
||||
status: done
|
||||
type: backend
|
||||
team: Backend Senior
|
||||
supporting_teams:
|
||||
- Arquitecto de Base de Datos
|
||||
- Arquitecto Python
|
||||
roadmap_item: foundation
|
||||
priority: high
|
||||
---
|
||||
|
||||
# TASK-192 - Fix PostgreSQL ranking snapshot schema
|
||||
|
||||
## Goal
|
||||
|
||||
Apply a backend hotfix so weekly and monthly ranking snapshot storage initializes correctly in PostgreSQL without executing SQLite-only schema syntax.
|
||||
|
||||
## Context
|
||||
|
||||
Production `GET /api/ranking?timeframe=weekly&metric=kills&limit=20` currently fails because `backend/app/rcon_historical_leaderboards.py` executes SQLite DDL with `AUTOINCREMENT` through `psycopg`. HLL Vietnam operational storage must stay in PostgreSQL, including ranking snapshots, and this fix must preserve the current annual snapshot path and avoid any SQLite expansion for this functionality.
|
||||
|
||||
Preserve the current product identity: Spanish-speaking HLL Vietnam community, military/Vietnam/tactical/sober visual direction and controlled repository evolution.
|
||||
|
||||
## Steps
|
||||
|
||||
1. Inspect the listed files first.
|
||||
2. Create the PostgreSQL-compatible ranking snapshot schema following the existing backend storage pattern.
|
||||
3. Keep annual snapshot storage intact and scoped to `rcon_annual_ranking_snapshots`.
|
||||
4. Validate the backend path and document the root cause, fix and production verification steps.
|
||||
|
||||
## Files to Read First
|
||||
|
||||
- `AGENTS.md`
|
||||
- `ai/repo-context.md`
|
||||
- `ai/architecture-index.md`
|
||||
- `backend/app/rcon_historical_leaderboards.py`
|
||||
- `backend/app/postgres_rcon_storage.py`
|
||||
- `backend/app/rcon_admin_log_materialization.py`
|
||||
- `backend/app/rcon_annual_rankings.py`
|
||||
- `backend/app/payloads.py`
|
||||
- `backend/app/routes.py`
|
||||
- `scripts/run-stats-validation.ps1`
|
||||
- `ai/tasks/done/TASK-191-serve-ranking-from-snapshots-with-runtime-fallback.md`
|
||||
|
||||
## Expected Files to Modify
|
||||
|
||||
- `backend/app/rcon_historical_leaderboards.py`
|
||||
- `backend/app/postgres_rcon_storage.py`, solo si el patrón del proyecto lo requiere
|
||||
- `scripts/run-stats-validation.ps1`, solo si se añade validación de regresión
|
||||
- `ai/tasks/done/TASK-192-fix-postgres-ranking-snapshot-schema.md`
|
||||
|
||||
## Constraints
|
||||
|
||||
- Keep the change minimal.
|
||||
- Preserve HLL Vietnam project identity.
|
||||
- Do not introduce unnecessary frameworks or dependencies.
|
||||
- Do not create or depend on a separate SQLite database for ranking snapshots.
|
||||
- Do not expand legacy SQLite compatibility routes for this functionality beyond what already exists.
|
||||
- Do not modify frontend, visual logic, Elo/MMR or Comunidad Hispana #03 handling.
|
||||
- Keep annual ranking on `rcon_annual_ranking_snapshots`.
|
||||
- Do not overwrite repository-specific context with generic platform template text.
|
||||
|
||||
## Validation
|
||||
|
||||
Before completing the task ensure:
|
||||
|
||||
- `node --check frontend/assets/js/ranking.js`
|
||||
- `node --check frontend/assets/js/stats.js`
|
||||
- `powershell -ExecutionPolicy Bypass -File scripts/run-stats-validation.ps1`
|
||||
- `powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1`
|
||||
- local validation proves `initialize_ranking_snapshot_storage` does not contain or execute `AUTOINCREMENT` on the PostgreSQL path
|
||||
- local validation proves PostgreSQL schema defines `ranking_snapshots` and `ranking_snapshot_items` with PostgreSQL-compatible syntax
|
||||
- `/api/ranking?timeframe=weekly&metric=kills&limit=20` no longer fails because of table creation
|
||||
- `/api/ranking?timeframe=annual&metric=kills&limit=20&year=2026` keeps working
|
||||
- `git diff --name-only` matches the expected scope
|
||||
|
||||
If local PostgreSQL is unavailable, document that in Outcome and validate by code inspection plus existing scripts.
|
||||
|
||||
## Outcome
|
||||
|
||||
- Root cause:
|
||||
- `backend/app/rcon_historical_leaderboards.py` defined `ranking_snapshots` / `ranking_snapshot_items` with SQLite syntax and executed that same DDL through `psycopg` on the PostgreSQL path.
|
||||
- Production failure matched the SQLite-only token exactly: `AUTOINCREMENT`.
|
||||
- Confirmation:
|
||||
- The failing path was `build_global_ranking_payload` -> `get_latest_ranking_snapshot` -> `initialize_ranking_snapshot_storage`.
|
||||
- The hotfix removes PostgreSQL execution of the SQLite snapshot DDL and routes PostgreSQL initialization through the central PostgreSQL schema initializer.
|
||||
- Applied change:
|
||||
- Kept the SQLite snapshot schema local to the SQLite path in `backend/app/rcon_historical_leaderboards.py`.
|
||||
- Added PostgreSQL-compatible `ranking_snapshots` and `ranking_snapshot_items` tables plus indexes to `backend/app/postgres_rcon_storage.py`.
|
||||
- Used `BIGSERIAL` primary keys and PostgreSQL-compatible `BIGINT`, `DOUBLE PRECISION`, `TIMESTAMPTZ`, foreign keys and index syntax.
|
||||
- Added regression validation in `scripts/run-stats-validation.ps1` to prove the PostgreSQL path does not depend on `AUTOINCREMENT` and that it delegates to `initialize_postgres_rcon_storage`.
|
||||
- Expected PostgreSQL tables:
|
||||
- `ranking_snapshots`
|
||||
- `ranking_snapshot_items`
|
||||
- Annual ranking remains on:
|
||||
- `rcon_annual_ranking_snapshots`
|
||||
- `rcon_annual_ranking_snapshot_items`
|
||||
- Validations executed:
|
||||
- `node --check frontend/assets/js/ranking.js`
|
||||
- `node --check frontend/assets/js/stats.js`
|
||||
- `powershell -ExecutionPolicy Bypass -File scripts/run-stats-validation.ps1`
|
||||
- `powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1`
|
||||
- Local regression validation now proves:
|
||||
- PostgreSQL schema text contains `ranking_snapshots` and `ranking_snapshot_items`
|
||||
- PostgreSQL schema text does not contain `AUTOINCREMENT`
|
||||
- `initialize_ranking_snapshot_storage()` delegates to PostgreSQL schema initialization on the PostgreSQL path
|
||||
- `/api/ranking?timeframe=annual&year=2026&server_id=all&metric=kills&limit=20` still resolves
|
||||
- Environment note:
|
||||
- Local backend HTTP at `http://127.0.0.1:8000` was not available during validation.
|
||||
- Validation therefore completed by local Python imports, route resolution and existing scripts, which passed.
|
||||
- How to validate in production:
|
||||
- Deploy the backend hotfix.
|
||||
- Confirm PostgreSQL contains `ranking_snapshots` and `ranking_snapshot_items`.
|
||||
- Request:
|
||||
- `/api/ranking?timeframe=weekly&metric=kills&limit=20`
|
||||
- `/api/ranking?timeframe=monthly&metric=kills&limit=20`
|
||||
- `/api/ranking?timeframe=annual&metric=kills&limit=20&year=2026`
|
||||
- Verify weekly/monthly no longer fail during table initialization and annual remains unchanged.
|
||||
|
||||
## 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