comunidadhll/ai/tasks/done/TASK-218-design-player-active-seconds-for-real-kpm.md

id, title, status, type, team, supporting_teams, roadmap_item, priority

id	title	status	type	team	supporting_teams	roadmap_item	priority
TASK-218	Design player active seconds for real KPM	done	documentation	Arquitecto de Base de Datos	Backend Senior Arquitecto Python	foundation	high

TASK-218 - Design player active seconds for real KPM

Goal

Analizar y disenar como calcular KPM real en HLL Vietnam sin implementar cambios funcionales todavia.

KPM real se define como:

kills / minutos_jugados_reales

No debe confundirse con kills_per_match, Kills/partida ni kills divididas por duracion completa de partida cuando el jugador no estuvo toda la partida.

Context

TASK-216 confirmo que hoy no existe tiempo jugado real por jugador materializado para ranking publico.

Campos encontrados:

• rcon_player_profile_snapshots.play_time: texto de perfil, no normalizado y no por jugador/partida.
• rcon_match_player_stats.first_seen_server_time y last_seen_server_time: presencia observada por eventos dentro de partida.
• rcon_materialized_matches.started_at, ended_at, started_server_time y ended_server_time: duracion de partida, no tiempo por jugador.

TASK-217 dejo kills_per_match como Kills/partida y no implemento KPM real.

Esta task produce un diseno tecnico accionable para crear player_active_seconds o rcon_match_player_presence en tasks futuras, sin modificar codigo funcional ni esquema real.

Preserve the current product identity: Spanish-speaking HLL Vietnam community, military/Vietnam/tactical/sober visual direction and controlled repository evolution.

Steps

1. Revisar fuentes de AdminLog, materializacion, read models y snapshots.
2. Evaluar eventos disponibles para presencia real o observada.
3. Clasificar calidad de datos: exact, observed, estimated, unknown.
4. Proponer opciones de modelo de datos.
5. Recomendar una estrategia de backfill y propagacion a read models.
6. Documentar plan de implementacion dividido en tasks.
7. Validar que solo se crearon documentos.

Files to Read First

• AGENTS.md
• ai/repo-context.md
• ai/architecture-index.md
• backend/app/rcon_admin_log_storage.py
• backend/app/rcon_admin_log_materialization.py
• backend/app/rcon_admin_log_parser.py

Tambien se revisaron:

• backend/app/postgres_rcon_storage.py
• backend/app/rcon_historical_player_stats.py
• backend/app/rcon_historical_leaderboards.py
• backend/app/rcon_annual_rankings.py
• backend/app/historical_runner.py
• backend/app/payloads.py
• docs/PERFORMANCE_PUBLIC_QUERY_AUDIT.md
• ai/tasks/done/TASK-216-clean-ranking-ui-and-fix-kpm-metric.md
• ai/tasks/done/TASK-217-add-annual-ranking-snapshots-for-supported-metrics.md

Expected Files to Modify

• docs/REAL_KPM_PLAYER_ACTIVE_SECONDS_DESIGN.md
• ai/tasks/done/TASK-218-design-player-active-seconds-for-real-kpm.md

Constraints

• Keep the change minimal.
• Preserve HLL Vietnam project identity.
• Do not introduce unnecessary frameworks or dependencies.
• Do not implement backend functionality.
• Do not change endpoints.
• Do not change frontend.
• Do not change backend functional code.
• Do not change real schema yet.
• No ejecutar ai-platform run.
• No hacer push.
• No tocar frontend/assets/img/weapons/.
• No tocar SVGs.
• No modificar imagenes fisicas.
• No tocar ai/system-metrics.md.
• No reactivar Elo/MMR.
• No reintroducir Comunidad Hispana #03.
• No incluir cambios previos no relacionados.

Validation

Before completing the task ensure:

• git status --short --untracked-files=all
• git diff --name-only
• Confirmar que solo se crean/modifican:
  • docs/REAL_KPM_PLAYER_ACTIVE_SECONDS_DESIGN.md
  • ai/tasks/done/TASK-218-design-player-active-seconds-for-real-kpm.md

Outcome

Archivos creados:

• docs/REAL_KPM_PLAYER_ACTIVE_SECONDS_DESIGN.md
• ai/tasks/done/TASK-218-design-player-active-seconds-for-real-kpm.md

Conclusion:

• No se puede calcular KPM real publico hoy.
• La fuente recomendada para player_active_seconds es AdminLog con connected/disconnected cuando sea posible y ventana observada por eventos como fallback etiquetado.
• El modelo recomendado es Opcion C:
  • crear rcon_match_player_presence como detalle auditable por jugador/partida;
  • denormalizar player_active_seconds y playtime_quality en rcon_match_player_stats para agregaciones rapidas.
• KPM futuro debe calcularse en generacion de read models/snapshots como kills / (player_active_seconds / 60), nunca en frontend y nunca usando kills_per_match.

Plan de implementacion propuesto:

1. TASK-219-create-rcon-match-player-presence-schema
2. TASK-220-materialize-player-presence-from-adminlog
3. TASK-221-backfill-player-active-seconds
4. TASK-222-denormalize-player-active-seconds-into-match-stats
5. TASK-223-extend-player-period-stats-with-kpm
6. TASK-224-add-kpm-ranking-snapshots
7. TASK-225-expose-real-kpm-in-api-payloads
8. TASK-226-show-real-kpm-in-ranking-ui
9. TASK-227-validate-kpm-quality-and-performance

Riesgos principales:

• Cobertura incompleta de eventos connected/disconnected.
• Presencia observada por eventos puede subestimar tiempo activo.
• Duracion completa de partida no representa tiempo por jugador y debe quedar estimated.
• Mezclar calidades sin metadata haria KPM enganoso.
• Backfill masivo puede competir con lecturas publicas si no se agenda bien.

Validacion ejecutada:

• git status --short --untracked-files=all
• git diff --name-only

Confirmacion de exclusiones:

• No se ejecuto ai-platform run.
• No se hizo push.
• No se tocaron assets de armas.
• No se tocaron SVGs.
• No se modificaron imagenes fisicas.
• No se toco ai/system-metrics.md.
• No se reactivo Elo/MMR.
• No se reintrodujo Comunidad Hispana #03.
• No se modifico frontend.
• No se modifico backend funcional.
• No se modificaron tests.
• No se modifico esquema real.
• No se incluyeron cambios previos no relacionados.

Change Budget

• Archivos modificados por esta task: 2.
• Sin cambios funcionales.