Add player-season hitting ingestion

[Mattsface]

Why

Issue #46 established the first intentionally small Player-data ingestion slice before Player analytics are added. This PR implements that slice without introducing league-wide player discovery, stint persistence, player game logs, or UI work.

What

• add players persistence for stable MLB player identity
• add player_season_hitting persistence keyed by (player_id, season)
• persist raw season hitting counting stats only; BA/OBP/SLG/OPS remain derived
• add explicit one-player/one-season ingestion via scripts/import_player_season.py
• normalize player identity from Mlb.get_person(...)
• normalize season hitting from Mlb.get_player_stats(..., stats=["season"], groups=["hitting"])
• handle traded players correctly by selecting the unique full-season aggregate split when multiple team splits are present
• never fall back to splits[0] for multi-split seasons
• reject missing required season fields instead of coercing None to zero
• keep MLB network I/O outside the database transaction
• persist player identity and season hitting atomically and idempotently
• reuse one MLB client for the logical import lifecycle
• add Alembic migration, repository support, typed schemas, service errors, CLI handling, and deterministic offline tests

Trade / stint semantics

This slice intentionally stores one full-season aggregate per player-season and no team_id on player_season_hitting.

For a single-team season, the sole split is used. For a traded player, multiple splits must contain exactly one aggregate with team is None; that aggregate is persisted and team-specific stints are ignored. Ambiguous multi-split responses fail instead of being guessed.

Validation

The branch was smoke-tested against live MLB data for a normal single-team player-season and a traded-player season, including an idempotent rerun. The implementation also includes offline coverage for normalization, aggregate selection, missing data, persistence, idempotency, updates, rollback behavior, CLI handling, and transaction/network boundaries.

Scope exclusions

Not included here:

• league-wide player discovery
• player game logs
• player pitching ingestion
• team-stint persistence
• Player UI/search
• new charts
• PostgreSQL or async SQLAlchemy work
• generic ingestion framework work

Closes #46

[Mattsface]

@claude

[claude]

Claude finished @Mattsface's task in 1m 50s —— View job

---

Claude's review

• Read repository CLAUDE.md for repo-specific guidelines (none present)
• Review the PR diff (git diff origin/main...HEAD)
• Provide code review feedback

The trigger comment (@claude) didn't include a specific ask, so I reviewed the PR as a whole.

This is a well-scoped, carefully implemented slice. The MLB-network-outside-transaction boundary, the atomic identity+hitting upsert, the aggregate-split selection logic (refusing to guess with splits[0]), the bool-is-not-int guard in _normalize_season_hitting_split, and the check constraints mirrored 1:1 between the ORM models and the Alembic migration are all solid. Test coverage across schemas, service, repositories, ingestion, and migrations is thorough.

One real gap I found:

CLI script doesn't actually reuse one MLB client, despite that being a stated goal — app/services/player_season_ingestion.py:34-35 calls get_player_identity(player_id, client=client) and get_player_season_hitting(player_id, season, client=client), forwarding whatever client was passed in, and the service layer + TrackingClient test (tests/test_player_season_ingestion.py) do verify reuse when a client is explicitly passed. But scripts/import_player_season.py never constructs an Mlb() client and never passes one to ingest_player_season(...) (scripts/import_player_season.py:85-89), so in the actual CLI entry point client stays None all the way down, and get_player_identity/get_player_season_hitting each open and close their own Mlb() context manager. The "reuse one MLB client for the logical import lifecycle" claim in the PR description isn't realized for the one code path a user actually runs.

Suggested fix: open one Mlb() in main() (or in ingest_player_season itself, wrapping both calls in a single with Mlb() as client: when the caller didn't supply one) and pass it through.

Fix this →

Everything else — models, repositories, schemas, the migration, and scope adherence to the exclusions list in the PR description — looks correct and consistent with the codebase's existing patterns (e.g. _is_missing_team_game_table / upsert_team_season conventions reused faithfully for players).

Note: I was not able to run the test suite or linters in this environment (Bash execution required approval that wasn't available), so this review is based on static reading of the diff rather than a green test run.
· Branch: milestone-issue-46-player-season-hitting-ingestion