tlw-database-tool/docs/tippliga.md

tippliga — Domain Models & Operations

Core domain package with match, matchday, team, and league models plus operations for creating, updating, and managing the prediction league schedule. All extend TLWMatchesManagerBase or TLWMatchesCreatorBase.

Base Classes

BaseMatch (de.jeyp91.BaseMatch)

Abstract class with shared match state: team IDs, goals (home/guest/overtime/penalty), datetime, status, KO flag, show-table flag, and a COMPARISON enum (IDENTICAL, DIFFERENT, DIFFERENT_DATETIME, DIFFERENT_RESULT).

Status constants:

• STATUS_NOTSTARTED = 0
• STATUS_STARTED = 1
• STATUS_PROVISIONAL_RESULT_AVAILABLE = 2
• STATUS_FINISHED = 3
• STATUS_NOT_EVALUATED = 4

TLWMatchesCreatorBase

Abstract creator with TLWMatches list, getSQLInsertString() generating REPLACE INTO queries, getMatchesForMatchday(), and getNumberOfMatchdays().

TLWMatchesManagerBase

Shared helpers used by updaters:

• Date parsing from TLW (yyyy-MM-dd HH:mm:ss) and API-Football (yyyy-MM-dd'T'HH:mm:ss) formats
• getFirstMatchtimeTLW() / getFirstMatchtimeAPIFootball() — earliest match in a list
• getDaysDifference() — calendar day diff
• getMatchesStartingFromSecondDay() / getMatchesStartingFromSecondWeek() — filter helpers for delivery date computation
• getMatchingMatch() — matches an API match to a TLW match by home/guest team IDs

Domain Models

TLWMatch (extends BaseMatch)

Full match model mapped from phpbb_footb_matches table. Multiple constructors:

• From ResultSet (DB query)
• From APIFootballMatch + TeamIDMatcher (API sync)
• Manual constructors for creators
• Copy constructor

Key methods:

• getSQLQueryInsert() / getSQLQueryReplace() — generates SQL values
• updateMatch(APIFootballMatch) — updates teams, goals, datetime from API data
• isSameMatchPlaceholder() — matches placeholder config entries to existing matches

TLWMatchday

Mapped from phpbb_footb_matchdays. Fields: season, league, matchday, status, 3 delivery dates, matchday name, match count.

TLWTeam

Mapped from phpbb_footb_teams. Fields: season, league, team ID, name, short name, symbol, group ID, matchday.

TLWLeague

Mapped from phpbb_footb_leagues. Fields: season, league ID, league name, short name.

Operations

TLWMatchesCreatorFootball

Builds match schedule from API-Football data and JSON config. For each matchday config entry:

1. Resolves API matches via APIFootballMatchesProvider
2. Creates TLWMatch objects with team IDs matched via TeamIDMatcher
3. Fills remaining slots with placeholder matches (empty teams)

Handles deliveryDateMode: in "single" mode, matches beyond the first day get status = -1 to prevent early betting on later matches.

TLWMatchesCreatorTipperLeague

Creates matches for tipper-vs-tipper leagues (where tippers are "teams"). Reads pairing config from Tipper_Match_Pair_Config.json and tipper-team mapping from Tipper_Team_Config.json.

TLWMatchesCreatorTipperPokal

Creates single-matchday knockout tournament matches from a tipper list config. Each pair of tippers is one match with koMatch = 1 and showTable = false.

TLWMatchesUpdaterFootball

Compares current DB matches with latest API data and generates SQL UPDATE statements. Only operates on matchdays where the first match is still in the future. Updates:

• Team IDs (via TeamIDMatcher)
• Match datetimes
• Status flags (0 = current matchday, -1 = next-day match, -2 = later)
• show_table / ko_match flags

Also handles:

• addMissingMatches() — inserts API matches not yet in DB (finds placeholder slots by datetime/formula)
• addPlaceholderMatches() — adds config-defined placeholders for TBD matchups

TLWMatchesResultsUpdater

For finished matches, compares DB goals with API goals and pushes updates to the website via TippligaWebsiteConnector. Detects changes to:

• Full-time goals
• Overtime goals (for KO matches with betKOType = 2)
• Penalty → overtime mapping (for betKOType = 1 or 3)
• Status transitions from provisional to confirmed

TLWMatchdaysCreator

Computes delivery dates (betting deadlines) from match times. Supports two modes:

• "single": one deadline = first match time
• "multiple" (default): 3 deadlines — first match, first match of second day, first match of second week

Also handles additionalDeliveryDate config flags for special matchday events.

TLWMatchdaysUpdater

Compares original DB matchdays with recomputed deadlines and generates SQL UPDATEs and Google Calendar syncs. Only updates future matchdays (deadline in the past is skipped).

TLWTeamsCreator

Extracts unique team IDs from a list of matches and generates REPLACE INTO phpbb_footb_teams SQL, preserving group and matchday info from match data.

TLWTeamsUpdater

Detects teams referenced in matches but not yet present in the league's team table. Generates INSERT SQL to add them (copies team metadata from existing entries in other seasons/leagues).