Document historical match KPM analysis

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.

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