diff --git a/ai/tasks/done/TASK-239-analyze-kills-per-minute-column-for-historical-match-detail.md b/ai/tasks/done/TASK-239-analyze-kills-per-minute-column-for-historical-match-detail.md new file mode 100644 index 0000000..d73ba22 --- /dev/null +++ b/ai/tasks/done/TASK-239-analyze-kills-per-minute-column-for-historical-match-detail.md @@ -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. diff --git a/docs/HISTORICAL_MATCH_KILLS_PER_MINUTE_ANALYSIS.md b/docs/HISTORICAL_MATCH_KILLS_PER_MINUTE_ANALYSIS.md new file mode 100644 index 0000000..abbe408 --- /dev/null +++ b/docs/HISTORICAL_MATCH_KILLS_PER_MINUTE_ANALYSIS.md @@ -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