# TASK-155 - Current match live player stats

Status: in-progress

## Goal

Investigate and implement live player/statistics rendering for the current-match page using the safest available data source.

## Background

The current-match page has an "Estadísticas en vivo" section, but it currently remains a placeholder:

> "Las estadísticas en vivo aparecerán cuando haya datos suficientes."

The user reports that players are not being shown.

Known context:

- `/api/current-match` exposes players and team player counts from RCON `getSession`, but those counts may be marked as `rcon-session-unverified`.
- Public scoreboard can show player population even when RCON `getSession` reports 0.
- AdminLog kill events already expose player names through normalized kill feed rows.
- Historical materialization already derives player stats from AdminLog data for completed matches.
- The current-match page should eventually show useful live player rows, but only if data is reliable enough.

## Scope

Investigate the available live player data sources and wire the current-match page to a safe current player statistics payload.

Allowed changes:

- `backend/app/routes.py`
- `backend/app/payloads.py`
- `backend/app/rcon_admin_log_storage.py`
- backend read-model/helper files if needed
- `frontend/assets/js/partida-actual.js`
- `frontend/partida-actual.html`
- `frontend/assets/css/historico.css` or relevant CSS
- focused backend tests

## Constraints - DO NOT BREAK

- Do not fabricate player stats.
- Do not show an empty/misleading table as if it were real data.
- Do not show RCON `getSession` `playerCount=0` as reliable if quality is `rcon-session-unverified`.
- Do not expose raw AdminLog lines.
- Do not expose admin-only/sensitive data.
- Do not break historical materialization.
- Do not break historical match detail stats.
- Do not query RCON directly from the frontend.
- Do not depend on server #03.
- Do not scrape the public scoreboard unless explicitly chosen and documented as a safe server-side fallback.
- Keep current public scoreboard URLs trusted and without `/games`.

## Files to inspect first

Read:

- `frontend/partida-actual.html`
- `frontend/assets/js/partida-actual.js`
- `backend/app/routes.py`
- `backend/app/payloads.py`
- `backend/app/rcon_admin_log_storage.py`
- focused tests and historical player stat materialization helpers related to current-match or AdminLog data

Inspect the existing RCON session payload, current kill feed freshness logic, open AdminLog match window support, and historical player stat aggregation before choosing a source.

## Required investigation before implementation

Perform RCA first and determine what live player data sources currently exist:

- RCON session payload
- any RCON player-list command/wrapper already available in the codebase
- AdminLog kill/death events
- existing historical player stat materialization
- current open AdminLog match window if available

Document the chosen source in the done task notes:

- what was available
- what was not available
- whether stats are complete, partial, or event-derived

## Implementation requirements

### 1. Backend endpoint

Add or extend a backend endpoint for current-match player stats.

Preferred route:

- `GET /api/current-match/players?server=...`

### 2. Supported servers

Support:

- `comunidad-hispana-01`
- `comunidad-hispana-02`

### 3. Unknown server values

- Return a safe 400/404 style response.
- Do not query arbitrary targets.

### 4. Data model

The endpoint should return:

- `server_slug`
- `server_name`
- `scope`
- `confidence`
- `source`
- `captured_at` or `updated_at`
- `items`: array of player rows

### 5. Player row fields

Include only fields that can be supported reliably:

- `player_name`
- `team` if known
- `kills` if known
- `deaths` if known
- `teamkills` if known
- `deaths_by_teamkill` if known
- `favorite_weapon` or `most_used_weapon` if known
- `last_seen_at` if known
- `confidence`/`source` if needed

### 6. AdminLog-derived data

If using AdminLog-derived data:

- Clearly mark scope/confidence as partial/event-derived.
- Only include players observed in recent/current match event windows.
- Do not imply this is the full server roster.
- Use a freshness threshold consistent with kill feed freshness logic.
- If no current/open event window exists, return empty items with a clear scope.

### 7. RCON player-list data

If a real RCON player-list command exists:

- Prefer it for live roster.
- Combine it with AdminLog-derived kills/deaths only when safe.
- Mark fields not supported by RCON as null.
- Do not block the endpoint indefinitely on RCON timeouts.

### 8. Frontend rendering

Replace the static "Estadísticas en vivo" placeholder with dynamic rendering.

If items exist:

- Show a compact table or cards with player stats.
- Sort by kills descending, then deaths ascending, then name.
- Indicate if stats are partial.

If items are empty, show:

- "Todavía no hay estadísticas fiables de jugadores para esta partida."

If data is partial, show:

- "Estadísticas parciales derivadas de eventos recientes."

### 9. Frontend polling

- Poll player stats with the current-match page refresh cycle or a safe separate interval.
- Avoid overlapping requests.
- Do not flicker table rows on every poll.
- Avoid duplicate player rows.

### 10. Tests

Add focused backend tests for:

- unsupported server rejection
- empty current stats response
- AdminLog-derived player aggregation if used
- stale event filtering
- no raw AdminLog exposure
- stable sorting
- partial confidence metadata

## Validation

Run:

- `python -m compileall backend/app`
- focused backend tests if available
- `node --check frontend/assets/js/partida-actual.js`

## Manual verification checklist

- Call `Invoke-RestMethod "http://localhost:8000/api/current-match/players?server=comunidad-hispana-01" | ConvertTo-Json -Depth 20`.
- Call `Invoke-RestMethod "http://localhost:8000/api/current-match/players?server=comunidad-hispana-02" | ConvertTo-Json -Depth 20`.
- Verify unsupported server values are rejected safely.
- Open `http://localhost:8080/partida-actual.html?server=comunidad-hispana-01`.
- Open `http://localhost:8080/partida-actual.html?server=comunidad-hispana-02`.
- Verify the "Estadísticas en vivo" section no longer remains permanently empty when current reliable/partial player data exists.
- Verify the UI clearly says when stats are partial or unavailable.
- Verify no fake players are shown.
- Verify no raw AdminLog lines are shown.
- Verify existing historical detail stats still work.

## Expected outcome

The current-match page can show live or partial player statistics when supported by reliable/current data, and otherwise shows a clear honest empty state.

## AI Platform lifecycle

After implementation and validation:

- Move this task according to the lifecycle defined in `AGENTS.md`.
- Do not mark unrelated tasks as done automatically.

## Outcome

### RCA and source choice

- `RCON getSession` remains available for the current-match header but its current player count is explicitly marked `rcon-session-unverified`.
- No dedicated RCON player-list wrapper or route exists in the current `rcon_client` implementation.
- AdminLog kill events already expose safe normalized player names, teams, weapons and current-match window/freshness handling through the kill-feed read model.
- The historical AdminLog materializer derives player combat stats from the same kind of kill events for closed matches.
- Chosen source: current/fresh normalized AdminLog kill rows. The new current-match player projection is intentionally `event-derived-partial`, not a complete live roster.

### Change summary

- Added `GET /api/current-match/players?server=...` for trusted active current-match servers only.
- Added a safe AdminLog-derived player aggregator with kills, deaths, teamkills, teamkill deaths, team, last-seen timestamp and favorite weapon when observed.
- Kept stale fallback filtering aligned with the current kill feed and kept raw AdminLog messages out of the payload.
- Replaced the static current-match player placeholder with a polled partial-stat table and an honest empty state.

### Validation

- Ran `python -m compileall backend/app`.
- Ran `node --check frontend/assets/js/partida-actual.js`.
- Attempted `python -m pytest backend/tests/test_current_match_payload.py backend/tests/test_rcon_admin_log_storage.py`; the active Python environment does not have `pytest` installed.
- Ran a direct Python smoke harness for trusted/unsupported route resolution, AdminLog aggregation, teamkill handling, stale filtering and raw-log exclusion.
- Ran `scripts/run-historical-ui-regression-tests.ps1`.
- Ran `git diff --check` and `git diff --name-only`.
- Task-specific changed product files are `backend/app/routes.py`, `backend/app/payloads.py`, `backend/app/rcon_admin_log_storage.py`, `backend/tests/test_current_match_payload.py` and `frontend/assets/js/partida-actual.js`. The current worktree also contains `frontend/assets/css/historico.css` from completed `TASK-154`.
- Rendered Browser QA remains to be repeated when the Browser automation entry point is exposed in-session.