114 lines
4.1 KiB
Markdown
114 lines
4.1 KiB
Markdown
---
|
|
id: TASK-162
|
|
title: Add Stats player search endpoint (RCON materialized backend V1)
|
|
status: pending
|
|
type: backend
|
|
team: Backend Senior
|
|
supporting_teams: [Arquitecto de Base de Datos, Arquitecto Python]
|
|
roadmap_item: foundation
|
|
priority: medium
|
|
---
|
|
|
|
# TASK-162 - Add Stats player search endpoint (RCON materialized backend V1)
|
|
|
|
## Goal
|
|
|
|
Implement a backend V1 endpoint to support player search for the future Stats section:
|
|
`GET /api/stats/players/search?q=<query>`.
|
|
|
|
The endpoint must use existing RCON materialized tables and return search matches that include:
|
|
|
|
- `status`
|
|
- `query`
|
|
- `items`
|
|
- `player_id`
|
|
- `player_name`
|
|
- `matches_considered`
|
|
- `last_seen_at`
|
|
- optional `servers_seen` only if it can be added with low scope cost
|
|
|
|
No frontend work, no migrations, no yearly ranking, no Elo/MMR workarounds, no Comunidad Hispana #03 reactivation.
|
|
|
|
## Context
|
|
|
|
The repository already has a RCON materialized model (`rcon_match_player_stats` + `rcon_materialized_matches`) used by leaderboard reads.
|
|
The new endpoint is the first part of the Stats backend contract defined in `docs/stats-section-functional-plan.md`.
|
|
It should reuse existing routing/payload conventions in the current backend bootstrap.
|
|
|
|
## Steps
|
|
|
|
1. Inspect required files first (mandatory before implementation):
|
|
- `AGENTS.md`
|
|
- `ai/repo-context.md`
|
|
- `ai/architecture-index.md`
|
|
- `docs/stats-section-functional-plan.md`
|
|
- `backend/app/rcon_historical_leaderboards.py`
|
|
- `backend/app/main.py`
|
|
- `backend/app/rcon_admin_log_materialization.py` (for table/schema context)
|
|
2. Reuse the existing `routes.py` + `payloads.py` endpoint/payload pattern.
|
|
3. Implement one new endpoint: `GET /api/stats/players/search`.
|
|
4. Validate `q` parameter and optional `server` or `server_id` and `limit` handling using current project conventions.
|
|
5. Query existing RCON materialized tables with read-only logic (preferably `rcon_match_player_stats` joined with `rcon_materialized_matches`).
|
|
6. Keep response shape aligned with existing backend payload conventions.
|
|
7. Add a minimal, self-contained module if needed (preferably `backend/app/rcon_historical_player_stats.py`).
|
|
8. Run backend validation/checks and document outcome.
|
|
|
|
## Files to Read First
|
|
|
|
- `AGENTS.md`
|
|
- `ai/repo-context.md`
|
|
- `ai/architecture-index.md`
|
|
- `docs/stats-section-functional-plan.md`
|
|
- `backend/app/main.py`
|
|
- `backend/app/routes.py`
|
|
- `backend/app/payloads.py`
|
|
- `backend/app/rcon_historical_leaderboards.py`
|
|
- `backend/app/rcon_admin_log_materialization.py`
|
|
|
|
## Expected Files to Modify
|
|
|
|
- `backend/app/rcon_historical_player_stats.py` (new module preferred)
|
|
- `backend/app/payloads.py`
|
|
- `backend/app/routes.py`
|
|
- `backend/app/main.py` (solo si se detecta una dependencia de export explícita o import requerido)
|
|
|
|
## Constraints
|
|
|
|
- Keep the change small and verifiable.
|
|
- Keep frontend untouched.
|
|
- No migrations.
|
|
- No annual ranking implementation.
|
|
- No Elo/MMR reactivation.
|
|
- No Comunidad Hispana #03 behavior reintroduction.
|
|
- No historical worker changes.
|
|
- Do not modify `frontend/assets/js/partida-actual.js`.
|
|
- Do not create unnecessary abstractions beyond this endpoint.
|
|
- If `/ai/` is partially ignored by git-exclude, document traceability impact only.
|
|
|
|
## Validation
|
|
|
|
Before considering the task complete:
|
|
|
|
- Run `scripts/run-integration-tests.ps1`.
|
|
- Run relevant backend tests if they exist for stats/player or historical materialized reads.
|
|
- If no dedicated tests exist for this endpoint, run manual validation with `curl` or `Invoke-WebRequest`.
|
|
- Validate `git diff --name-only` and check that only expected files were changed.
|
|
- Move task to `ai/tasks/done` on completion, or to `ai/tasks/review` if human validation is required.
|
|
|
|
## Outcome (for worker)
|
|
|
|
Document:
|
|
|
|
- endpoint contract implemented and observed behavior
|
|
- SQL/search strategy used (scope, match logic, ordering, fallback behavior)
|
|
- validation command results
|
|
- whether `servers_seen` was included and why
|
|
- any schema/data limitations found
|
|
- any blocker from git tracking (`/ai/` ignore behavior) and impact on traceability if relevant
|
|
|
|
## Change Budget
|
|
|
|
- Prefer <5 modified files.
|
|
- Prefer <200 added/changed lines per file when feasible.
|
|
- Split into follow-up tasks if the scope starts expanding.
|