Document stats frontend integration plan
This commit is contained in:
devRaGonSa
@@ -0,0 +1,92 @@
|
|||||||
|
---
|
||||||
|
id: TASK-164
|
||||||
|
title: Design stats frontend integration plan
|
||||||
|
status: done
|
||||||
|
type: frontend
|
||||||
|
team: Frontend Senior
|
||||||
|
supporting_teams: []
|
||||||
|
roadmap_item: foundation
|
||||||
|
priority: medium
|
||||||
|
---
|
||||||
|
|
||||||
|
# TASK-164 - Design stats frontend integration plan
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
Define how the future Stats section will be integrated in the frontend before implementing it.
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
The backend already exposes the stats query contract used by this plan:
|
||||||
|
|
||||||
|
- `GET /api/stats/players/search?q=<query>`
|
||||||
|
- `GET /api/stats/players/{player_id}`
|
||||||
|
|
||||||
|
This task is documentation only. No backend or implementation changes.
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
1. Read all files listed in `Files to Read First` from the workspace first.
|
||||||
|
2. Define an integration strategy that preserves current navigation and behavior of Inicio / Historico / Partida actual.
|
||||||
|
3. Describe V1 components, endpoint usage and UI state transitions.
|
||||||
|
4. Propose minimal visual reuse from existing styles and assets.
|
||||||
|
5. Define future implementation files and order.
|
||||||
|
6. Record any known limitations and an open follow up recommendation.
|
||||||
|
|
||||||
|
## Files to Read First
|
||||||
|
|
||||||
|
- `AGENTS.md`
|
||||||
|
- `ai/repo-context.md`
|
||||||
|
- `ai/architecture-index.md`
|
||||||
|
- `docs/stats-section-functional-plan.md`
|
||||||
|
- `frontend/index.html`
|
||||||
|
- `frontend/historico.html`
|
||||||
|
- `frontend/assets/css/styles.css`
|
||||||
|
- `frontend/assets/js/main.js`
|
||||||
|
- `backend/app/routes.py`
|
||||||
|
- `backend/app/payloads.py`
|
||||||
|
|
||||||
|
## Expected Files to Modify
|
||||||
|
|
||||||
|
- `docs/stats-frontend-integration-plan.md`
|
||||||
|
- `ai/tasks/done/TASK-164-design-stats-frontend-integration-plan.md`
|
||||||
|
|
||||||
|
## Constraints
|
||||||
|
|
||||||
|
- Keep current repo structure intact.
|
||||||
|
- Do not implement any frontend behavior now.
|
||||||
|
- Do not modify backend.
|
||||||
|
- No migrations.
|
||||||
|
- No ranking anual.
|
||||||
|
- No Elo/MMR reactivation.
|
||||||
|
- No Comunidad Hispana #03 reintro.
|
||||||
|
- Do not touch `frontend/assets/js/partida-actual.js`.
|
||||||
|
- Do not touch `frontend/assets/img/clans/bxb.png`.
|
||||||
|
- Do not add frameworks.
|
||||||
|
- Keep change size minimal and verified.
|
||||||
|
|
||||||
|
## Validation
|
||||||
|
|
||||||
|
- Confirm only documentation and task file were created/modified.
|
||||||
|
- Run `git diff --name-only`.
|
||||||
|
- Record that no automated tests are applicable for this docs-only task.
|
||||||
|
|
||||||
|
## Outcome (for worker)
|
||||||
|
|
||||||
|
- Outcome:
|
||||||
|
- Archivos creados/modificados:
|
||||||
|
- `docs/stats-frontend-integration-plan.md`
|
||||||
|
- `ai/tasks/done/TASK-164-design-stats-frontend-integration-plan.md`
|
||||||
|
- Movimiento de `ai/tasks/pending/TASK-164-design-stats-frontend-integration-plan.md` a `ai/tasks/done/...`.
|
||||||
|
- Validación realizada:
|
||||||
|
- `git status --short --untracked-files=all` verificado.
|
||||||
|
- `git diff --name-only` verificado.
|
||||||
|
- Confirmado que `docs/stats-frontend-integration-plan.md` existe y contiene el plan solicitado.
|
||||||
|
- Al ser una task documental:
|
||||||
|
- No se ejecutan tests automáticos.
|
||||||
|
- No aplica validación funcional automatizada.
|
||||||
|
- Restricciones verificadas:
|
||||||
|
- No se tocaron archivos de backend.
|
||||||
|
- No se implementó frontend.
|
||||||
|
- No se tocaron `frontend/assets/js/partida-actual.js`.
|
||||||
|
- No se tocó `frontend/assets/img/clans/bxb.png`.
|
||||||
123
docs/stats-frontend-integration-plan.md
Normal file
123
docs/stats-frontend-integration-plan.md
Normal file
@@ -0,0 +1,123 @@
|
|||||||
|
# Plan de integracion de Stats en frontend
|
||||||
|
|
||||||
|
## 1. Pagina prevista
|
||||||
|
|
||||||
|
- Pantalla objetivo: `frontend/stats.html` (nueva).
|
||||||
|
- Objetivo V1: pagina ligera, statically-safe, con componentes para:
|
||||||
|
- buscador
|
||||||
|
- resultados
|
||||||
|
- panel de stats personales
|
||||||
|
- resumen semanal
|
||||||
|
- resumen mensual
|
||||||
|
- bloque futuro de ranking anual top 20 (placeholder)
|
||||||
|
|
||||||
|
## 2. Navegacion
|
||||||
|
|
||||||
|
El cambio no debe romper Inicio, Historico ni Partida actual.
|
||||||
|
|
||||||
|
- Mantener `frontend/index.html` con su estructura actual.
|
||||||
|
- Cambios de navegacion propuestos:
|
||||||
|
- Añadir un link `Stats` en el bloque de acciones del hero:
|
||||||
|
- `href="./stats.html"`
|
||||||
|
- texto: `Stats`
|
||||||
|
- estilo reutilizando `.secondary-button` o variante especifica en CSS si se requiere.
|
||||||
|
- En `frontend/historico.html`:
|
||||||
|
- añadir boton de regreso a Inicio si no existe.
|
||||||
|
- opcionalmente incluir acceso rapido a `stats.html` en el header.
|
||||||
|
- En `partida-actual.html` (futuro, si usa una plantilla):
|
||||||
|
- no modificar por ahora.
|
||||||
|
- Regla de compatibilidad:
|
||||||
|
- No alterar rutas de `historico.html` ni de `partida-actual.html`.
|
||||||
|
- Mantener rutas existentes (`./historico.html`, `./index.html`) intactas.
|
||||||
|
|
||||||
|
## 3. Componentes V1
|
||||||
|
|
||||||
|
- Buscador de jugador
|
||||||
|
- Input para texto libre.
|
||||||
|
- Boton de ejecucion.
|
||||||
|
- Debounce/submit manual para evitar ruido.
|
||||||
|
- Query query param `q`.
|
||||||
|
- Lista de resultados
|
||||||
|
- Mostrar por fila:
|
||||||
|
- `player_name`
|
||||||
|
- `player_id` (texto de soporte)
|
||||||
|
- `matches_considered`
|
||||||
|
- `last_seen_at`
|
||||||
|
- `servers_seen` (solo si se integra en payload final).
|
||||||
|
- Cada fila habilita seleccion de jugador.
|
||||||
|
- Panel de estadisticas personales
|
||||||
|
- Estado base despues de seleccionar jugador:
|
||||||
|
- nombre y player_id
|
||||||
|
- server/scope visible.
|
||||||
|
- Datos por `GET /api/stats/players/{player_id}?timeframe=...&server_id=...`.
|
||||||
|
- Resumen semanal
|
||||||
|
- Render a partir de `data.weekly_ranking` y `data` para la misma ventana.
|
||||||
|
- Resumen mensual
|
||||||
|
- Render a partir de `data.monthly_ranking` y datos de ventana.
|
||||||
|
- Bloque anual futuro
|
||||||
|
- Reservado en layout con estado:
|
||||||
|
- `Proximo: ranking anual top 20`.
|
||||||
|
- Sin llamada ni dependencia now.
|
||||||
|
|
||||||
|
## 4. Endpoints usados
|
||||||
|
|
||||||
|
- `GET /api/stats/players/search?q=<query>`
|
||||||
|
- `q` obligatorio.
|
||||||
|
- parametros recomendados V1:
|
||||||
|
- `server_id` opcional (`all-servers` como default).
|
||||||
|
- `limit` opcional.
|
||||||
|
- `GET /api/stats/players/{player_id}`
|
||||||
|
- para semana: `timeframe=weekly`.
|
||||||
|
- para mes: `timeframe=monthly`.
|
||||||
|
- para cambios de scope: `server_id=all-servers|comunidad-hispana-01|comunidad-hispana-02`.
|
||||||
|
|
||||||
|
## 5. Estados de UI
|
||||||
|
|
||||||
|
- Loading
|
||||||
|
- Skeleton o placeholder en buscador y lista de resultados.
|
||||||
|
- Mensaje breve en paneles de resumen con estado neutro.
|
||||||
|
- Error
|
||||||
|
- Mensaje tactico y silencioso en consola.
|
||||||
|
- Mantener contenido previo visible.
|
||||||
|
- Sin resultados
|
||||||
|
- estado vacio: `No se encontraron jugadores para esta busqueda`.
|
||||||
|
- Jugador sin stats
|
||||||
|
- si `matches_considered == 0`:
|
||||||
|
- mostrar `Sin actividad registrada en el periodo`.
|
||||||
|
- Backend no disponible
|
||||||
|
- banner no intrusivo de estado.
|
||||||
|
- no bloquear el resto de la pagina.
|
||||||
|
|
||||||
|
## 6. Identidad visual
|
||||||
|
|
||||||
|
- Mantener estilo militar / Vietnam / tactico / sobrio:
|
||||||
|
- variables CSS existentes en `frontend/assets/css/styles.css`.
|
||||||
|
- paleta actual.
|
||||||
|
- tarjetas y borders similares a `panel`, `clan-card`, `server-card`.
|
||||||
|
- No introducir frameworks.
|
||||||
|
- Preferir reutilizacion:
|
||||||
|
- `hero`, `panel`, `status-chip`, `secondary-button` y utilidades de layout existentes.
|
||||||
|
- Agregar estilos nuevos solo en `styles.css` si la combinacion base no cubre el layout.
|
||||||
|
|
||||||
|
## 7. Archivos esperados para implementacion futura
|
||||||
|
|
||||||
|
- `frontend/stats.html`
|
||||||
|
- `frontend/assets/js/stats.js`
|
||||||
|
- `frontend/assets/css/styles.css` (solo si necesario para grid, estados, card o tabla simple)
|
||||||
|
- `frontend/index.html` y/o `frontend/historico.html` para navegacion a Stats, sin tocar la logica de secciones actuales.
|
||||||
|
|
||||||
|
## Alcance de validacion
|
||||||
|
|
||||||
|
Esta task es un plan y no requiere pruebas automaticas.
|
||||||
|
|
||||||
|
- Verificar por dif:
|
||||||
|
- solo `ai/tasks/pending/TASK-164-design-stats-frontend-integration-plan.md`
|
||||||
|
- `docs/stats-frontend-integration-plan.md`
|
||||||
|
- Revisar que el plan respete las restricciones:
|
||||||
|
- sin cambios backend
|
||||||
|
- sin implementacion
|
||||||
|
- sin ranking anual
|
||||||
|
- sin elo/mmr
|
||||||
|
- sin comunidad hispana #03
|
||||||
|
- Preparar siguiente task: implementacion de `frontend/stats.html` y `frontend/assets/js/stats.js` usando endpoints V1.
|
||||||
|
|
||||||
Reference in New Issue
Block a user