127 lines
3.6 KiB
Markdown
127 lines
3.6 KiB
Markdown
# Player Search Read Model
|
|
|
|
## Objective
|
|
|
|
Define the first dedicated read model for player search so `/api/stats/players/search` does not aggregate large RCON historical tables on every public request.
|
|
|
|
## Table
|
|
|
|
Primary table:
|
|
|
|
- `player_search_index`
|
|
|
|
Operational scope:
|
|
|
|
- PostgreSQL is the default operational store
|
|
- SQLite remains available only as explicit local compatibility for validation and isolated maintenance runs
|
|
|
|
Read-model nature:
|
|
|
|
- this table is regenerable
|
|
- it is not the canonical source of truth
|
|
- canonical historical data remains in `rcon_materialized_matches` and `rcon_match_player_stats`
|
|
|
|
## Stored Fields
|
|
|
|
Each row stores one player projection for one public search scope:
|
|
|
|
- `server_id`
|
|
- `player_id`
|
|
- `player_name`
|
|
- `normalized_player_name`
|
|
- `first_seen_at`
|
|
- `last_seen_at`
|
|
- `servers_seen`
|
|
- `matches_current_year`
|
|
- `kills_current_year`
|
|
- `deaths_current_year`
|
|
- `teamkills_current_year`
|
|
- `updated_at`
|
|
|
|
Current scope rows:
|
|
|
|
- `all-servers`
|
|
- `comunidad-hispana-01`
|
|
- `comunidad-hispana-02`
|
|
|
|
Why `server_id` exists:
|
|
|
|
- the public search endpoint already supports `server_id`
|
|
- keeping one row per scope preserves the existing frontend contract without recalculating large runtime aggregates for server-filtered searches
|
|
|
|
## Refresh Command
|
|
|
|
Manual command:
|
|
|
|
```bash
|
|
python -m app.rcon_historical_player_stats refresh-player-search-index
|
|
```
|
|
|
|
SQLite-only local override:
|
|
|
|
```bash
|
|
python -m app.rcon_historical_player_stats refresh-player-search-index --sqlite-path backend/data/hll_vietnam_dev.sqlite3
|
|
```
|
|
|
|
Refresh policy:
|
|
|
|
- rebuild from materialized RCON/AdminLog tables
|
|
- replace rows scope by scope
|
|
- aggregate only the current UTC year
|
|
- keep the latest current-year player name
|
|
- store accent-insensitive normalized names in Python
|
|
|
|
## Public Read Path
|
|
|
|
Priority for `/api/stats/players/search`:
|
|
|
|
1. use `player_search_index` when the requested scope has rows
|
|
2. return read-model results directly, including empty query results when the index is populated but the query does not match
|
|
3. fall back to runtime aggregation only when:
|
|
- the read model table is unavailable
|
|
- the requested scope has no rows yet
|
|
- a controlled read error occurs
|
|
|
|
Returned compatibility:
|
|
|
|
- the payload still returns `player_id`
|
|
- the payload still returns `player_name`
|
|
- the payload still returns `matches_considered`
|
|
- the payload still returns `last_seen_at`
|
|
- the payload still returns `servers_seen`
|
|
|
|
`matches_considered` remains compatible by mapping from `matches_current_year`.
|
|
|
|
## PostgreSQL Notes
|
|
|
|
No extra PostgreSQL extensions are required.
|
|
|
|
Specifically:
|
|
|
|
- no `pg_trgm`
|
|
- no custom text-search extension
|
|
|
|
Search tolerance is implemented with:
|
|
|
|
- normalized lowercase names
|
|
- accent stripping in Python
|
|
- indexed scope + normalized-name reads
|
|
- runtime fallback preserved as a safety net
|
|
|
|
## Current Limitations
|
|
|
|
- this read model is focused on player search only, not personal profile totals
|
|
- counts are current-year only by design
|
|
- historical players with no activity in the current UTC year are not intentionally prioritized in this first model
|
|
- profile and personal stats still use runtime aggregation over materialized tables
|
|
|
|
## Production Validation
|
|
|
|
Recommended checks after refresh:
|
|
|
|
- run `python -m app.rcon_historical_player_stats refresh-player-search-index`
|
|
- confirm the command reports rows for `all-servers`, `comunidad-hispana-01` and `comunidad-hispana-02`
|
|
- call `/api/stats/players/search?q=<known-player>&limit=5`
|
|
- verify response metadata reports `read_model=player-search-index`
|
|
- verify fallback metadata only appears when the read model is empty or unavailable
|