Document stats frontend integration plan

docs/stats-frontend-integration-plan.md

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