Cleanup code and prepare for AI usage

2026-07-27 21:24:35 +02:00
parent b0110e1bc8
commit 04dca24513
33 changed files with 579 additions and 468 deletions
@@ -0,0 +1,39 @@
+# apifootball — API-Football Integration
+
+Fetches, caches, and serves match data from [API-Football](https://www.api-football.com/). Raw JSON is cached in S3 to avoid repeated API calls.
+
+## Classes
+
+### APIFootballUpdater
+HTTP client that fetches raw JSON from API-Football and writes to S3.
+
+- `updateAllFixtures(season)` — fetches all leagues' fixtures
+- `updateAllRounds(season)` — fetches all leagues' round metadata
+- `getRawData(requestPath, season, league)` — calls API-Football with rate-limit retry
+- `getLeagues()` — reads league IDs from `Ligen_v3.json` resource
+
+Handles the Tippliga↔API-Football season offset: for most leagues, Tippliga season N corresponds to API-Football season N-1 (except World Cup `league=1` and Euro `league=4`).
+
+### APIFootballConnector
+Singleton that reads cached S3 JSON and resolves API data into `APIFootballMatch` objects.
+
+- `getMatchDataByLeagueAndMatchday(league, matchday)` — all matches for a matchday
+- `getMatchDataByLeagueAndMatchID(league, id)` — single match by API fixture ID
+- `getMatchdays(leagueId)` — round metadata from S3
+- `getTeamsForLeague(season, league)` — live team list from API
+
+### APIFootballMatch
+Extends `BaseMatch`. Parses a raw API-Football JSON fixture object.
+
+Parses: fixture ID, league ID, team IDs + names, round string, datetime, status, fulltime/extratime/penalty scores.
+
+Key method: `getMatchdayFromRoundString(season, round, leagueId)` — converts API round names (e.g. `"Regular Season - 1"`) to Tippliga matchday numbers. Falls back to the rounds JSON for non-regular-season formats.
+
+### APIFootballMatchesProvider
+High-level resolver that reads matchday config (from the JSON config file) and returns flat `APIFootballMatch` lists.
+
+Supports two config entry types:
+- `AllMatchesOfMatchday` — fetch all matches for a given API league+matchday
+- `SingleMatch` — fetch a specific match by API league+fixture ID
+
+Honors `showTable` and `ko` flags from config.