--- 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.