Document historical match KPM analysis
This commit is contained in:
devRaGonSa
@@ -0,0 +1,88 @@
|
||||
---
|
||||
id: TASK-239
|
||||
title: Analyze kills per minute column for historical match detail
|
||||
status: done
|
||||
type: research
|
||||
team: Analista
|
||||
supporting_teams:
|
||||
- Frontend Senior
|
||||
- Backend Senior
|
||||
roadmap_item: foundation
|
||||
priority: medium
|
||||
---
|
||||
|
||||
# TASK-239 - Analyze kills per minute column for historical match detail
|
||||
|
||||
## Goal
|
||||
|
||||
Determine whether a `Kills por minuto` column can be added honestly to the historical match detail page without reintroducing false KPM.
|
||||
|
||||
## Files Read First
|
||||
|
||||
- `docs/REAL_KPM_PLAYER_ACTIVE_SECONDS_DESIGN.md`
|
||||
- `frontend/assets/js/historico-partida.js`
|
||||
- `backend/app/payloads.py`
|
||||
- `backend/app/rcon_historical_read_model.py`
|
||||
- `backend/app/rcon_historical_player_stats.py`
|
||||
|
||||
## Findings
|
||||
|
||||
1. `historico-partida.js` currently shows only:
|
||||
- player name
|
||||
- team
|
||||
- kills
|
||||
- deaths
|
||||
- teamkills
|
||||
- KD
|
||||
2. The historical match detail payload comes from `build_historical_match_detail_payload()` and `get_rcon_historical_match_detail()`.
|
||||
3. The current match detail data includes:
|
||||
- match duration
|
||||
- match start/end
|
||||
- player kills/deaths/teamkills
|
||||
- `top_weapons`, `most_killed`, `death_by`
|
||||
4. The current detail payload does not expose:
|
||||
- `player_active_seconds`
|
||||
- `play_time`
|
||||
- per-player presence intervals
|
||||
- any trustworthy per-player played-minutes field
|
||||
5. The existing design document already states that real KPM is blocked until `player_active_seconds` exists as a real materialized field.
|
||||
|
||||
## Conclusion
|
||||
|
||||
Do not implement `Kills por minuto` now.
|
||||
|
||||
The repository still lacks a trustworthy player-level time-played field for historical match detail. Using match duration would only produce `kills por minuto de partida`, not real player KPM, and that was explicitly ruled out.
|
||||
|
||||
## Honest Alternatives
|
||||
|
||||
Possible future options:
|
||||
|
||||
1. Real KPM:
|
||||
- only after `player_active_seconds` is materialized per player and per match
|
||||
2. Explicitly different metric:
|
||||
- `Kills/min partida`
|
||||
- only if product explicitly wants that weaker metric and labels it as match-duration-based
|
||||
|
||||
## Implementation Recommendation
|
||||
|
||||
Current recommendation: do not add the column yet.
|
||||
|
||||
Required before implementation:
|
||||
|
||||
1. Backend field such as `player_active_seconds`
|
||||
2. Payload exposure for that field in historical match detail
|
||||
3. Clear UI distinction between:
|
||||
- real KPM
|
||||
- kills per match
|
||||
- any match-duration-derived metric
|
||||
|
||||
## Validation
|
||||
|
||||
- Analysis only
|
||||
- No frontend implementation changed for this task
|
||||
- No backend code changed
|
||||
- No API contract changed
|
||||
|
||||
## Outcome
|
||||
|
||||
The task confirms that real `Kills por minuto` cannot be implemented safely today and should remain out of the UI until the data model supports it.
|
||||
95
docs/HISTORICAL_MATCH_KILLS_PER_MINUTE_ANALYSIS.md
Normal file
95
docs/HISTORICAL_MATCH_KILLS_PER_MINUTE_ANALYSIS.md
Normal file
@@ -0,0 +1,95 @@
|
||||
# Historical Match Kills Per Minute Analysis
|
||||
|
||||
## Scope
|
||||
|
||||
This analysis covers the player table inside `historico-partida.html` for historical match detail.
|
||||
|
||||
## Question
|
||||
|
||||
Can the UI add a `Kills por minuto` column now without reintroducing false KPM?
|
||||
|
||||
## Short Answer
|
||||
|
||||
No.
|
||||
|
||||
## Why It Cannot Be Implemented Honestly Yet
|
||||
|
||||
The current historical match detail payload exposes player combat totals and match-level timing, but it does not expose a trustworthy player-level active time.
|
||||
|
||||
Available today:
|
||||
|
||||
- per player:
|
||||
- `kills`
|
||||
- `deaths`
|
||||
- `teamkills`
|
||||
- `kd_ratio` or enough data to derive it
|
||||
- `top_weapons`
|
||||
- `most_killed`
|
||||
- `death_by`
|
||||
- per match:
|
||||
- `duration_seconds`
|
||||
- `started_at`
|
||||
- `ended_at`
|
||||
|
||||
Missing for real KPM:
|
||||
|
||||
- `player_active_seconds`
|
||||
- real played minutes per player
|
||||
- presence intervals
|
||||
- a quality flag that tells whether playtime is exact, observed, estimated or unknown
|
||||
|
||||
## Data Review
|
||||
|
||||
`build_historical_match_detail_payload()` serves `item` from the RCON historical read model when available.
|
||||
|
||||
`historico-partida.js` currently renders the player table with:
|
||||
|
||||
- `Jugador`
|
||||
- `Equipo`
|
||||
- `Kills`
|
||||
- `Muertes`
|
||||
- `TK`
|
||||
- `KD`
|
||||
|
||||
There is no frontend or payload field for honest KPM.
|
||||
|
||||
## Important Constraint
|
||||
|
||||
Real KPM must mean:
|
||||
|
||||
```text
|
||||
kills / (player_active_seconds / 60)
|
||||
```
|
||||
|
||||
It must not mean:
|
||||
|
||||
```text
|
||||
kills / match_duration_minutes
|
||||
```
|
||||
|
||||
unless the product intentionally introduces a different metric with a clearly different label.
|
||||
|
||||
## Existing Design Reference
|
||||
|
||||
`docs/REAL_KPM_PLAYER_ACTIVE_SECONDS_DESIGN.md` already documents the correct long-term direction:
|
||||
|
||||
- materialize `player_active_seconds`
|
||||
- carry a playtime quality classification
|
||||
- compute KPM in backend read models and snapshots
|
||||
- never compute real KPM in frontend JavaScript
|
||||
|
||||
## Recommendation
|
||||
|
||||
Do not add the column now.
|
||||
|
||||
Safe next step:
|
||||
|
||||
1. Add real `player_active_seconds` to the historical player detail model.
|
||||
2. Expose it in the match detail payload.
|
||||
3. Add `Kills por minuto` only when backed by that field.
|
||||
|
||||
Optional weaker alternative, only with explicit product approval:
|
||||
|
||||
- `Kills/min partida`
|
||||
- clearly labeled as match-duration-based
|
||||
- never presented as player KPM
|
||||
Reference in New Issue
Block a user