Fix player profile runtime PostgreSQL grouping
This commit is contained in:
devRaGonSa
@@ -0,0 +1,176 @@
|
||||
---
|
||||
id: TASK-200-fix-player-profile-runtime-postgres-grouping
|
||||
title: Fix player profile runtime PostgreSQL grouping
|
||||
status: done
|
||||
type: backend
|
||||
team: Backend Senior
|
||||
supporting_teams:
|
||||
- Arquitecto de Base de Datos
|
||||
- Arquitecto Python
|
||||
roadmap_item: foundation
|
||||
priority: high
|
||||
---
|
||||
|
||||
# TASK-200 - Fix player profile runtime PostgreSQL grouping
|
||||
|
||||
## Goal
|
||||
|
||||
Corregir el `500` de `/api/stats/players/{player_id}?server_id={server}` cuando el jugador no tiene fila en `player_period_stats` para el timeframe solicitado y la ruta cae al fallback runtime sobre PostgreSQL.
|
||||
|
||||
## Context
|
||||
|
||||
`TASK-199` introdujo `player_period_stats` y el endpoint público ya usa correctamente el read model cuando existe una fila para el jugador/scope/timeframe solicitado. El problema aparece cuando el read model no tiene fila para ese jugador en el timeframe pedido y la lectura cae a `_get_rcon_materialized_player_stats_runtime(...)`.
|
||||
|
||||
La causa raíz validada en producción es una query de `_fetch_player_stats(...)` en `backend/app/rcon_historical_player_stats.py` que usa una expresión equivalente a `COALESCE(MAX(stats.player_name), stats.player_id)` sin agregar ni agrupar `stats.player_id`. SQLite lo tolera, pero PostgreSQL lanza `psycopg.errors.GroupingError`, provocando un `500` para casos como `server_id=comunidad-hispana-01` cuando no hay fila `weekly` o `monthly` en `player_period_stats`.
|
||||
|
||||
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. Fix the runtime fallback query used by `_fetch_player_stats(...)` so it is valid in PostgreSQL.
|
||||
3. Preserve SQLite/local compatibility when the explicit local path is used.
|
||||
4. Keep `player_period_stats` as the preferred source whenever a row exists.
|
||||
5. Keep runtime fallback when the read model is missing, incomplete or unavailable.
|
||||
6. Ensure the no-read-model-row case returns the existing controlled contract instead of a `500`.
|
||||
7. Validate the affected player-profile, player-search and ranking snapshot paths.
|
||||
8. Document the root cause, affected SQL, new behavior and production validation path.
|
||||
|
||||
## Files to Read First
|
||||
|
||||
- `AGENTS.md`
|
||||
- `ai/repo-context.md`
|
||||
- `ai/architecture-index.md`
|
||||
- `backend/app/rcon_historical_player_stats.py`
|
||||
- `backend/app/payloads.py`
|
||||
- `backend/app/routes.py`
|
||||
- `backend/app/postgres_rcon_storage.py`
|
||||
- `scripts/run-stats-validation.ps1`
|
||||
- `docs/player-period-stats-read-model-plan.md`
|
||||
- `ai/tasks/done/TASK-199-add-player-period-stats-read-model.md`
|
||||
|
||||
## Expected Files to Modify
|
||||
|
||||
- `backend/app/rcon_historical_player_stats.py`
|
||||
- `scripts/run-stats-validation.ps1`
|
||||
- `ai/tasks/in-progress/TASK-200-fix-player-profile-runtime-postgres-grouping.md`
|
||||
|
||||
## Constraints
|
||||
|
||||
- Keep the change minimal and backend-only.
|
||||
- Do not execute `ai-platform run`.
|
||||
- Do not modify frontend.
|
||||
- Do not change design.
|
||||
- Do not touch images or assets.
|
||||
- Do not reactivate Elo/MMR.
|
||||
- Do not reintroduce Comunidad Hispana `#03`.
|
||||
- Do not mix automation changes into this task.
|
||||
- Do not change public contracts except to avoid the runtime `500`.
|
||||
- Keep `player_period_stats` as the preferred source when data exists.
|
||||
- Keep runtime fallback active when the read model has no row for the requested scope/window.
|
||||
- If runtime also has no rows for that scope/window, return the existing controlled empty/zero contract instead of throwing.
|
||||
- Do not break:
|
||||
- `/api/stats/players/search`
|
||||
- `/api/stats/players/{player_id}`
|
||||
- ranking snapshots
|
||||
- `refresh-player-search-index`
|
||||
- `refresh-player-period-stats`
|
||||
|
||||
## Validation
|
||||
|
||||
Before completing the task ensure:
|
||||
|
||||
- `python -m py_compile backend/app/rcon_historical_player_stats.py`
|
||||
- `powershell -ExecutionPolicy Bypass -File scripts/run-stats-validation.ps1`
|
||||
- `powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1`
|
||||
- local validation proves `_fetch_player_stats(...)` no longer emits PostgreSQL-invalid aggregate SQL
|
||||
- local validation proves the runtime fallback path does not throw when a server-specific read-model row is missing
|
||||
- local validation proves `player_period_stats` is still used when a row exists
|
||||
- local validation proves `player_search_index` still works
|
||||
- local validation proves ranking snapshots are not broken
|
||||
- validate these profile cases:
|
||||
- `/api/stats/players/76561197978442431`
|
||||
- `/api/stats/players/76561197978442431?server_id=all`
|
||||
- `/api/stats/players/76561197978442431?server_id=all-servers`
|
||||
- `/api/stats/players/76561197978442431?server_id=comunidad-hispana-02`
|
||||
- `/api/stats/players/76561197978442431?server_id=comunidad-hispana-01`
|
||||
- the last case must not return `500`
|
||||
- `git diff --name-only` matches the expected scope
|
||||
|
||||
## Outcome
|
||||
|
||||
Implemented:
|
||||
|
||||
- `backend/app/rcon_historical_player_stats.py`
|
||||
- fixed `_fetch_player_stats(...)` runtime aggregation SQL
|
||||
- removed the PostgreSQL-invalid expression `COALESCE(MAX(stats.player_name), stats.player_id)`
|
||||
- kept the player-name fallback in Python with `row["player_name"] or player_id`
|
||||
- `scripts/run-stats-validation.ps1`
|
||||
- added a SQL-shape regression check for `_fetch_player_stats(...)`
|
||||
- added a fixture with a `yearly-only-player` on `comunidad-hispana-01`
|
||||
- validated the server-specific fallback path when `player_period_stats` has no weekly/monthly row and runtime also has no rows in the requested window
|
||||
|
||||
Root cause of the `500`:
|
||||
|
||||
- when `/api/stats/players/{player_id}` could not serve `player_period_stats`, it fell back to `_get_rcon_materialized_player_stats_runtime(...)`
|
||||
- `_fetch_player_stats(...)` executed a grouped aggregate query that selected:
|
||||
- `COALESCE(MAX(stats.player_name), stats.player_id) AS player_name`
|
||||
- PostgreSQL rejects `stats.player_id` in that expression because it is neither aggregated nor part of `GROUP BY`
|
||||
- SQLite/local compatibility masked the issue because SQLite tolerates that aggregate shape
|
||||
|
||||
Concrete affected SQL shape:
|
||||
|
||||
- previous:
|
||||
- `SELECT COALESCE(MAX(stats.player_name), stats.player_id) AS player_name, ...`
|
||||
- new:
|
||||
- `SELECT MAX(stats.player_name) AS player_name, ...`
|
||||
- public fallback behavior stays intact because Python already normalizes the result with `str(row["player_name"] or player_id)`
|
||||
|
||||
Previous behavior:
|
||||
|
||||
- read-model hits returned `read_model=player-period-stats` and `fallback_used=false`
|
||||
- if the requested scope/timeframe had no player row and runtime fallback executed on PostgreSQL, the endpoint could raise `psycopg.errors.GroupingError`
|
||||
- the request then returned HTTP `500`
|
||||
|
||||
New behavior:
|
||||
|
||||
- `player_period_stats` remains the preferred source when a row exists
|
||||
- runtime fallback remains active when the read model is empty, incomplete or unavailable
|
||||
- PostgreSQL fallback SQL is now valid
|
||||
- if the requested scope/window has no runtime rows, the endpoint returns the existing controlled zero-value profile contract instead of throwing
|
||||
- no frontend, design, asset, Elo/MMR or Comunidad Hispana `#03` changes were made
|
||||
|
||||
Validations executed:
|
||||
|
||||
- `python -m py_compile backend/app/rcon_historical_player_stats.py`
|
||||
- `powershell -ExecutionPolicy Bypass -File scripts/run-stats-validation.ps1`
|
||||
- `powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1`
|
||||
|
||||
Validation notes:
|
||||
|
||||
- local import-based validation confirmed `_fetch_player_stats(...)` no longer emits the PostgreSQL-invalid aggregate shape
|
||||
- local fixture validation confirmed the server-specific missing-read-model fallback does not throw and returns a controlled response
|
||||
- `player_period_stats` still serves the profile path when rows exist
|
||||
- `player_search_index` and ranking snapshot validations still pass through `scripts/run-stats-validation.ps1`
|
||||
- live HTTP validation at `http://127.0.0.1:8000` could not run in this environment because the backend was not up; the script reported that explicitly and route-contract checks still passed via local Python imports
|
||||
- `git diff --name-only` included unrelated pre-existing changes in `ai/system-metrics.md` and `frontend/assets/img/weapons/black/*`; those files were not modified by this task
|
||||
|
||||
How to validate in production:
|
||||
|
||||
- call:
|
||||
- `/api/stats/players/76561197978442431`
|
||||
- `/api/stats/players/76561197978442431?server_id=all`
|
||||
- `/api/stats/players/76561197978442431?server_id=all-servers`
|
||||
- `/api/stats/players/76561197978442431?server_id=comunidad-hispana-02`
|
||||
- `/api/stats/players/76561197978442431?server_id=comunidad-hispana-01`
|
||||
- verify the first four still report:
|
||||
- `source.read_model = "player-period-stats"`
|
||||
- `source.fallback_used = false`
|
||||
- verify the last case no longer returns HTTP `500`
|
||||
- verify the last case returns a controlled stats payload with fallback metadata instead of a PostgreSQL grouping exception
|
||||
|
||||
## 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