Add annual ranking snapshot runbook
This commit is contained in:
devRaGonSa
202
docs/annual-ranking-snapshot-runbook.md
Normal file
202
docs/annual-ranking-snapshot-runbook.md
Normal file
@@ -0,0 +1,202 @@
|
||||
# Runbook: annual ranking snapshot top 20 (Stats)
|
||||
|
||||
Objetivo: operar el ranking anual top 20 de `Stats` de forma reproducible, usando snapshots precomputados para no recalcular anualmente por cada request.
|
||||
|
||||
## 1) Propósito del snapshot anual top 20
|
||||
|
||||
El snapshot anual proporciona la tabla de posiciones de jugadores para el bloque de ranking anual de `Stats` con impacto bajo en latencia y costo de consulta.
|
||||
|
||||
Objetivos del diseño:
|
||||
|
||||
- entregar `top 20` de la temporada por métrica (V1: `kills`);
|
||||
- consumir un resultado estable desde API pública sin recalcular toda la historia anual en cada request;
|
||||
- permitir validación operativa clara de si el ranking está disponible o no;
|
||||
- soportar regeneración controlada por proceso de mantenimiento.
|
||||
|
||||
## 2) Fuente de datos
|
||||
|
||||
La fuente oficial para este ranking es materializada RCON:
|
||||
|
||||
- `rcon_materialized_matches`
|
||||
- `rcon_match_player_stats`
|
||||
|
||||
Filtro principal:
|
||||
|
||||
- `matches.source_basis = admin-log-match-ended`
|
||||
|
||||
Reglas clave de cálculo:
|
||||
|
||||
- ventanas por año (`YYYY-01-01T00:00:00Z` a `YYYY+1-01-01T00:00:00Z`);
|
||||
- acumulado de `kills`, `deaths`, `teamkills` por `player_id`;
|
||||
- orden por `metric_value` desc, `matches_considered` desc, `player_name` asc;
|
||||
- sólo posiciones con actividad válida y `player_name` no vacío.
|
||||
|
||||
## 3) Endpoint consumidor
|
||||
|
||||
Desde Stats se consume:
|
||||
|
||||
- `GET /api/stats/rankings/annual?year=<year>&server_id=<server-or-all>&metric=kills&limit=20`
|
||||
|
||||
En V1:
|
||||
|
||||
- `metric` soporta solo `kills`;
|
||||
- `server_id` acepta `all` o identificador de servidor.
|
||||
|
||||
## 4) Como generar snapshot anual
|
||||
|
||||
La generación se hace fuera de la API (job/comando) para precomputar:
|
||||
|
||||
1. Definir año objetivo `year`.
|
||||
2. Definir alcance `server_id` (`all` para global o servidor específico).
|
||||
3. Ejecutar generador de snapshot anual con la configuración necesaria.
|
||||
4. Generador:
|
||||
- elimina snapshot previo del mismo `(year, server_id, metric)` si existe;
|
||||
- recalcula top-k desde datos materializados RCON;
|
||||
- guarda cabecera + items del ranking en tablas snapshots;
|
||||
- persiste metadatos (`generated_at`, ventana y conteo fuente).
|
||||
|
||||
### Comando recomendado (si el entorno lo habilita)
|
||||
|
||||
```bash
|
||||
python -m app.rcon_annual_rankings generate --year 2026 --server-key all --metric kills --limit 20
|
||||
```
|
||||
|
||||
Notas:
|
||||
|
||||
- El comando puede fallar si la capa de datos local no está inicializada;
|
||||
- en entornos manuales, validar entorno y ruta de DB antes de ejecutar;
|
||||
- si no hay datos, se puede generar un snapshot vacío (ready con `items=[]`).
|
||||
|
||||
## 5) Como regenerarlo
|
||||
|
||||
Regenerar cuando:
|
||||
|
||||
- cambie la cobertura de datos anual;
|
||||
- se detecte snapshot incompleto;
|
||||
- se requiera refrescar fecha `generated_at`.
|
||||
|
||||
Procedimiento:
|
||||
|
||||
1. Ejecutar nuevamente el generador con el mismo `year` y `server_id`;
|
||||
2. Aceptar reemplazo seguro del snapshot existente;
|
||||
3. Validar que el snapshot nuevo refleje el recuento de partidas fuente actualizado.
|
||||
|
||||
Recomendación:
|
||||
|
||||
- programar recálculo en ventanas de mantenimiento (idealmente cierre anual o rutina periódica definida por operaciones).
|
||||
|
||||
## 6) Como validar que existe un snapshot
|
||||
|
||||
Verificación local (reconstruir estado esperable):
|
||||
|
||||
1. Consultar API de ranking anual del año objetivo.
|
||||
2. Revisar `snapshot_status` en respuesta:
|
||||
- `ready`: existe snapshot;
|
||||
- `missing`: no existe snapshot.
|
||||
3. Verificar `generated_at`, `window_start`, `window_end`, `source_matches_count`.
|
||||
|
||||
Se considera snapshot existente si API responde `snapshot_status="ready"`.
|
||||
|
||||
## 7) Como validar desde API
|
||||
|
||||
Usar llamadas directas a backend para validar estado y contenido:
|
||||
|
||||
- `GET /api/stats/rankings/annual?year=2026&server_id=all&metric=kills&limit=20`
|
||||
- `GET /api/stats/rankings/annual?year=1999&server_id=all&metric=kills&limit=20`
|
||||
- `GET /api/stats/rankings/annual?year=2026&server_id=all&metric=deaths&limit=20`
|
||||
|
||||
Checklist:
|
||||
|
||||
- HTTP 200 esperado para parámetros válidos de V1.
|
||||
- `status` debe ser `"ok"` con estructura de data consistente.
|
||||
- en V1 con `metric` no soportada, esperar error de request (400) sin recomputar ranking.
|
||||
|
||||
## 8) Como validar desde frontend Stats
|
||||
|
||||
Desde `frontend/stats.html`:
|
||||
|
||||
1. Abrir la pestaña `Stats`.
|
||||
2. Ejecutar consulta anual usando `year`.
|
||||
3. Confirmar:
|
||||
- estado de mensaje de carga/success/empty/error;
|
||||
- render de filas cuando haya items;
|
||||
- texto explícito cuando el snapshot está `missing`;
|
||||
- texto explícito cuando el snapshot existe pero no tiene items.
|
||||
4. Confirmar que no rompe bloque semanal/mensual ni búsqueda cuando el anual no está disponible.
|
||||
5. Si endpoint retorna métricas inválidas, validar estado de warning en UI y que no cambia el resto del flujo.
|
||||
|
||||
## 9) Casos esperados
|
||||
|
||||
### 9.1 `snapshot_status=ready` con items
|
||||
|
||||
Respuesta típica:
|
||||
|
||||
- `status: "ok"`
|
||||
- `data.snapshot_status: "ready"`
|
||||
- `data.items` con ranking ordenado.
|
||||
|
||||
Debe mostrarse top 20 con campos mínimos:
|
||||
|
||||
- `ranking_position`
|
||||
- `player_name`
|
||||
- `metric_value`
|
||||
- `matches_considered`
|
||||
- `kills`
|
||||
- `deaths`
|
||||
- `teamkills`
|
||||
- `kd_ratio`
|
||||
|
||||
### 9.2 `snapshot_status=ready` sin items
|
||||
|
||||
Respuesta típica:
|
||||
|
||||
- `snapshot_status: "ready"`
|
||||
- `items: []`
|
||||
- `generated_at` puede estar presente
|
||||
|
||||
Debe renderizar estado "snapshot ready vacío" y no tratarlo como error de sistema.
|
||||
|
||||
### 9.3 `snapshot_status=missing`
|
||||
|
||||
Respuesta típica:
|
||||
|
||||
- `snapshot_status: "missing"`
|
||||
- `items: []`
|
||||
|
||||
Debe mostrar estado informativo claro de que el ranking no fue generado aún.
|
||||
|
||||
### 9.4 Métrica no soportada
|
||||
|
||||
Respuesta típica:
|
||||
|
||||
- error request (400) con mensaje de métrica inválida/no soportada.
|
||||
|
||||
La UI/backend no debe intentar recalcular ni degradar a comportamiento inesperado.
|
||||
|
||||
## 10) Advertencias operativas
|
||||
|
||||
- No reactivar Elo/MMR ni lógica dependiente en este bloque.
|
||||
- No reintroducir `Comunidad Hispana #03` como alcance normal.
|
||||
- No usar scoreboard público como fuente primaria si RCON materializado está disponible.
|
||||
- No recalcular ranking anual completo en cada request público; siempre leer snapshot.
|
||||
- No tocar `frontend/assets/js/partida-actual.js` ni `frontend/assets/img/clans/bxb.png` en este runbook.
|
||||
|
||||
## Checklist de operación
|
||||
|
||||
- [ ] Definir año/servidor/limite.
|
||||
- [ ] Ejecutar generación o regeneración.
|
||||
- [ ] Confirmar respuesta de API por año objetivo.
|
||||
- [ ] Confirmar estado en UI de Stats.
|
||||
- [ ] Registrar fecha/hora de generación y responsable.
|
||||
- [ ] Si faltan datos esperados, revisar pipeline RCON materializado.
|
||||
|
||||
## Validación de la task
|
||||
|
||||
- `docs/annual-ranking-snapshot-runbook.md` creado.
|
||||
- Cambios esperados únicamente de documentación.
|
||||
- No se aplican tests automáticos (task de documentación-only); se documenta explícitamente.
|
||||
|
||||
## Próximos pasos recomendados
|
||||
|
||||
- Si el bloque muestra estados esperados y refrescos, conectar este runbook con operación de mantenimiento programada.
|
||||
- Mantener la misma política de fuentes en futuros reportes o automatizaciones de jobs.
|
||||
Reference in New Issue
Block a user