59 lines
3.1 KiB
Markdown
59 lines
3.1 KiB
Markdown
---
|
|
title: "Card Evolution Phase 1a — Schema & Data Foundation (dev branch)"
|
|
description: "Phase 1a implementation details for Card Evolution on paper-dynasty-database card-evolution branch: 5 work packages, Peewee models, migration, seed data, season stats service"
|
|
type: context
|
|
domain: paper-dynasty
|
|
tags: [paper-dynasty, evolution, database, peewee, migration, development]
|
|
---
|
|
|
|
# Card Evolution Phase 1a — Schema & Data Foundation
|
|
|
|
**Status:** Merged into `card-evolution` dev branch (PR #104, 2026-03-18)
|
|
**NOT deployed to production** — sitting on long-lived `card-evolution` branch on paper-dynasty-database repo.
|
|
**Project plan:** `card-creation/docs/prd-evolution/PHASE1_PROJECT_PLAN.md`
|
|
|
|
## What was implemented (5 work packages, 25+ tests)
|
|
|
|
### WP-01: Evolution Peewee Models
|
|
- 4 new models in `app/db_engine.py`: `EvolutionTrack`, `EvolutionCardState`, `EvolutionTierBoost`, `EvolutionCosmetic`
|
|
- Uses `ModelIndex` + `add_index()` for composite unique constraints
|
|
- Follows existing BaseModel pattern in the monolithic db_engine.py
|
|
|
|
### WP-02: PlayerSeasonStats Model
|
|
- 25 stat columns (14 batting + 11 pitching), all `IntegerField(default=0)`
|
|
- FK to `StratGame` for `last_game` tracking (double-count prevention)
|
|
- 3 indexes: unique (player, team, season) + 2 query indexes
|
|
|
|
### WP-03: Track Seed Data
|
|
- `app/seed/evolution_tracks.json` — 3 tracks (Batter, SP, RP) with formulas and thresholds
|
|
- `app/seed/evolution_tracks.py` — idempotent `seed_evolution_tracks()` using get_or_create + update on rerun
|
|
- Uses `logging.getLogger(__name__)` (not print)
|
|
|
|
### WP-04: SQL Migration
|
|
- `migrations/2026-03-17_add_evolution_tables.sql` — 5 new tables + 3 ALTER TABLE columns
|
|
- `IF NOT EXISTS` pattern, `BEGIN/COMMIT` wrapping
|
|
- **Critical fix:** FK references use `player(player_id)` not `player(id)` — Player PK is `player_id`
|
|
|
|
### WP-05: Season Stats Service
|
|
- `app/services/season_stats.py` — `update_season_stats(game_id)` entry point
|
|
- Dual-backend upsert: PostgreSQL `ON CONFLICT ... DO UPDATE EXCLUDED` / SQLite `get_or_create` + field addition
|
|
- Aggregates StratPlay rows into batting/pitching groups, merges Decision records
|
|
- Double-count prevention via `last_game` check
|
|
|
|
## Test infrastructure
|
|
- `conftest.py` updated with all 5 new models in `_TEST_MODELS` and shared fixtures (`track`, extended `player`, `team`)
|
|
- `ruff.toml` added with F403/F405 ignore for peewee star imports in db_engine.py
|
|
- Tests use `DATABASE_TYPE=postgresql` env var + SQLite rebind pattern
|
|
|
|
## Key technical decisions
|
|
- **Player PK is `player_id`**, not `id` — all FKs must reference `player(player_id)`
|
|
- **Career-scoped tiers** — permanent once earned, progress accumulates across seasons
|
|
- **No retroactive backfill** — evolution launches fresh at Season 11, all T0
|
|
- **Single metric per track** with escalating thresholds (no multi-milestone tiers)
|
|
|
|
## What's next: Phase 1b — API & Evaluation Engine
|
|
- WP-07: Card State API endpoints (issue #72)
|
|
- WP-08: Evaluate endpoint / formula engine (issue #73)
|
|
- WP-10: Pack opening hook — evolution_card_state init (issue #75)
|
|
- WP-07 and WP-08 can be parallelized
|