CLAUDE: Phase 3.5 Planning - Code Polish & Statistics System
Completed comprehensive planning for Phase 3.5 with focus on production readiness through materialized views approach for statistics. Planning Documents Created: - STAT_SYSTEM_ANALYSIS.md: Analysis of existing major-domo schema * Reviewed legacy BattingStat/PitchingStat tables (deprecated) * Analyzed existing /plays/batting and /plays/pitching endpoints * Evaluated 3 approaches (legacy port, modern, hybrid) - STAT_SYSTEM_MATERIALIZED_VIEWS.md: Recommended approach * PostgreSQL materialized views (following major-domo pattern) * Add stat fields to plays table (18 new columns) * 3 views: batting_game_stats, pitching_game_stats, game_stats * PlayStatCalculator service (~150 lines vs 400+ for StatTracker) * 80% less code, single source of truth, always consistent - phase-3.5-polish-stats.md: Complete implementation plan * Task 1: Game Statistics System (materialized views) * Task 2: Authorization Framework (WebSocket security) * Task 3: Uncapped Hit Decision Trees * Task 4: Code Cleanup (remove TODOs, integrate features) * Task 5: Integration Test Infrastructure * Estimated: 16-24 hours (2-3 days) NEXT_SESSION.md Updates: - Phase 3.5 ready to begin (0% → implementation phase) - Complete task breakdown with acceptance criteria - Materialized view approach detailed - Commit strategy for 3 separate commits - Files to review before starting Implementation Status Updates: - Phase 3: 100% Complete (688 tests passing) - Phase 3F: Substitution system fully tested - Phase 3.5: Planning complete, ready for implementation - Updated component status table with Phase 3 completion Key Decisions: - Use materialized views (not separate stat tables) - Add stat fields to plays table - Refresh views after game completion + on-demand - Use legacy field names (pa, ab, run, hit) for compatibility - Skip experimental fields (bphr, xba, etc.) for MVP Benefits of Materialized Views: - 80% less code (~400 lines → ~150 lines) - Single source of truth (plays table) - Always consistent (stats derived, not tracked) - Follows existing major-domo pattern - PostgreSQL optimized (indexed, cached) Next Steps: 1. Implement PlayStatCalculator (map PlayOutcome → stats) 2. Add stat fields to plays table (migration 004) 3. Create materialized views (migration 005) 4. Create BoxScoreService (query views) 5. Refresh logic after game completion 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Cal Corum
parent
0ebe72c09d
commit
b5677d0c55
@ -27,14 +27,24 @@
|
||||
- Database persistence layer
|
||||
- State recovery mechanism
|
||||
|
||||
#### Phase 3: Complete Game Features (Weeks 7-9)
|
||||
#### Phase 3: Complete Game Features (Weeks 7-9) - ✅ COMPLETE
|
||||
- [03 - Gameplay Features](./03-gameplay-features.md)
|
||||
- All strategic decision types
|
||||
- Substitution system
|
||||
- Pitching changes
|
||||
- Complete result charts (both leagues)
|
||||
- AI opponent integration
|
||||
- Async game mode support
|
||||
- ✅ All strategic decision types
|
||||
- ✅ Substitution system (SubstitutionRules, SubstitutionManager)
|
||||
- ✅ Pitching changes (included in substitution system)
|
||||
- ✅ Complete result charts (both leagues)
|
||||
- ✅ X-Check system (position ratings, defense tables, Redis caching)
|
||||
- ✅ GameState refactoring (consistent player references)
|
||||
- 🔲 AI opponent integration (deferred to Phase 4+)
|
||||
- 🔲 Async game mode support (deferred to Phase 4+)
|
||||
|
||||
#### Phase 3.5: Code Polish & Stat Tracking (2-3 days) - ⏳ IN PROGRESS
|
||||
- [phase-3.5-polish-stats](./phase-3.5-polish-stats.md)
|
||||
- Game statistics system (StatTracker, box scores)
|
||||
- Authorization framework (AuthService, WebSocket auth)
|
||||
- Uncapped hit decision trees
|
||||
- Code cleanup (remove TODOs, integrate handedness, SPD test)
|
||||
- Integration test infrastructure improvements
|
||||
|
||||
#### Phase 4: Spectator & Polish (Weeks 10-11)
|
||||
- [04 - Spectator & Polish](./04-spectator-polish.md)
|
||||
@ -81,12 +91,17 @@
|
||||
| WebSocket Manual Mode | ✅ Complete | 2 | roll_dice, submit_manual_outcome events |
|
||||
| Terminal Client | ✅ Complete | 2 | Full REPL with manual outcome testing |
|
||||
| Comprehensive Docs | ✅ Complete | 2 | 8,799 lines of CLAUDE.md across all subdirectories |
|
||||
| Substitutions | 🔲 Not Started | 3 | Lineup model supports, logic pending |
|
||||
| Pitching Changes | 🔲 Not Started | 3 | Fatigue tracking planned |
|
||||
| AI Opponent | 🟡 Stub | 3 | Basic stub exists, needs implementation |
|
||||
| X-Check System | ✅ Complete | 3A-D | Position ratings, defense tables, error charts, Redis caching |
|
||||
| GameState Refactoring | ✅ Complete | 3E | Consistent player references (all LineupPlayerState objects) |
|
||||
| Substitutions | ✅ Complete | 3F | SubstitutionRules, SubstitutionManager, WebSocket events (688 tests) |
|
||||
| **Game Statistics** | 🔲 Not Started | 3.5 | StatTracker, box scores, player/team stats |
|
||||
| **Authorization Framework** | 🔲 Not Started | 3.5 | AuthService, WebSocket auth checks |
|
||||
| **Code Polish** | 🔲 Not Started | 3.5 | Uncapped hits, cleanup TODOs |
|
||||
| Pitching Changes | ✅ Complete | 3F | Included in substitution system |
|
||||
| AI Opponent | 🟡 Stub | 4+ | Basic stub exists, needs implementation |
|
||||
| Spectator Mode | 🔲 Not Started | 4 | - |
|
||||
| UI Polish | 🔲 Not Started | 4 | - |
|
||||
| Testing Suite | ✅ Complete | 2 | ~540 tests passing (Phase 2 complete) |
|
||||
| Testing Suite | ✅ Complete | 3 | 688 tests passing (100% unit test coverage) |
|
||||
| Deployment | 🔲 Not Started | 5 | - |
|
||||
|
||||
## Quick Start
|
||||
@ -190,13 +205,31 @@ Track important decisions and open questions here as implementation progresses.
|
||||
- ManualOutcomeSubmission refactored to use PlayOutcome enum
|
||||
- All tests updated and passing (~540 total tests)
|
||||
- Phase 2 merged to main via PR #1
|
||||
- **2025-11-03**: Created `implementation-phase-3` branch - Ready for Week 8
|
||||
- **2025-11-03**: Created `implement-phase-3` branch - Ready for Phase 3
|
||||
- **2025-11-04**: Phase 3A-E Complete - X-Check system + GameState refactoring
|
||||
- Position ratings integration with PD API
|
||||
- Redis caching (760x speedup: 0.274s → 0.000361s)
|
||||
- Defense tables and error charts
|
||||
- GameState refactoring (consistent LineupPlayerState references)
|
||||
- Terminal client X-Check testing support
|
||||
- 679 tests passing
|
||||
- **2025-11-06**: **PHASE 3 COMPLETE** - Substitution system fully tested
|
||||
- SubstitutionRules validation (345 lines, 31 tests)
|
||||
- SubstitutionManager orchestration (552 lines, 10 integration tests)
|
||||
- WebSocket events (4 handlers: pinch hitter, defensive replacement, pitching change, get lineup)
|
||||
- 688 tests passing (100% unit test coverage)
|
||||
- All core gameplay features implemented
|
||||
- **2025-11-06**: **PHASE 3.5 PLANNING** - Code polish and stat tracking
|
||||
- Identified 40+ TODO comments in codebase
|
||||
- Stat tracking is natural next step (play resolution complete)
|
||||
- Authorization framework needed for production
|
||||
- Created comprehensive Phase 3.5 plan (5 major components)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-11-03
|
||||
**Phase**: Phase 3 - Complete Game Features (Ready to Begin)
|
||||
**Current Branch**: `implementation-phase-3`
|
||||
**Current Work**: Updating documentation to reflect Phase 2 completion
|
||||
**Next Session**: Week 8 - Player substitutions and pitching changes
|
||||
**Next Milestone**: Week 8 completion - Substitution system + pitching management
|
||||
**Last Updated**: 2025-11-06
|
||||
**Phase**: Phase 3.5 - Code Polish & Stat Tracking (Ready to Begin)
|
||||
**Current Branch**: `implement-phase-3`
|
||||
**Current Work**: Planning complete for Phase 3.5
|
||||
**Next Session**: Phase 3.5 Task 1 - Game Statistics System
|
||||
**Next Milestone**: Phase 3.5 completion - Production-ready codebase with stats and security
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
505
.claude/implementation/STAT_SYSTEM_ANALYSIS.md
Normal file
505
.claude/implementation/STAT_SYSTEM_ANALYSIS.md
Normal file
@ -0,0 +1,505 @@
|
||||
# Statistics System Analysis - Existing vs Proposed
|
||||
|
||||
**Date**: 2025-11-06
|
||||
**Context**: Phase 3.5 planning - game statistics tracking
|
||||
|
||||
---
|
||||
|
||||
## Existing Schema (major-domo/database)
|
||||
|
||||
### Current Tables (Peewee/SQLite)
|
||||
|
||||
#### 1. **Result** - Game-level results
|
||||
```python
|
||||
class Result(BaseModel):
|
||||
week = IntegerField()
|
||||
game = IntegerField()
|
||||
awayteam = ForeignKeyField(Team)
|
||||
hometeam = ForeignKeyField(Team)
|
||||
awayscore = IntegerField()
|
||||
homescore = IntegerField()
|
||||
season = IntegerField()
|
||||
scorecard_url = CharField(null=True)
|
||||
```
|
||||
|
||||
**Purpose**: Tracks final game scores and results
|
||||
**Scope**: High-level game outcomes only (no inning-by-inning breakdown)
|
||||
|
||||
---
|
||||
|
||||
#### 2. **BattingStat** - Per-game batting statistics
|
||||
```python
|
||||
class BattingStat(BaseModel):
|
||||
player = ForeignKeyField(Player)
|
||||
team = ForeignKeyField(Team)
|
||||
pos = CharField() # Position
|
||||
|
||||
# Standard batting stats
|
||||
pa = IntegerField() # Plate appearances
|
||||
ab = IntegerField() # At bats
|
||||
run = IntegerField() # Runs scored
|
||||
hit = IntegerField() # Hits
|
||||
rbi = IntegerField() # RBIs
|
||||
double = IntegerField()
|
||||
triple = IntegerField()
|
||||
hr = IntegerField() # Home runs
|
||||
bb = IntegerField() # Walks
|
||||
so = IntegerField() # Strikeouts
|
||||
hbp = IntegerField() # Hit by pitch
|
||||
sac = IntegerField() # Sacrifices
|
||||
ibb = IntegerField() # Intentional walks
|
||||
gidp = IntegerField() # Ground into double play
|
||||
|
||||
# Baserunning stats
|
||||
sb = IntegerField() # Stolen bases
|
||||
cs = IntegerField() # Caught stealing
|
||||
|
||||
# Batter-pitcher matchup stats (unclear what these are)
|
||||
bphr = IntegerField()
|
||||
bpfo = IntegerField()
|
||||
bp1b = IntegerField()
|
||||
bplo = IntegerField()
|
||||
|
||||
# X-Check related? (commented out in queries)
|
||||
xba = IntegerField()
|
||||
xbt = IntegerField()
|
||||
xch = IntegerField()
|
||||
xhit = IntegerField()
|
||||
|
||||
# Fielding stats (also tracked here)
|
||||
error = IntegerField()
|
||||
pb = IntegerField() # Passed balls (catcher)
|
||||
sbc = IntegerField() # Stolen base chances (catcher)
|
||||
csc = IntegerField() # Caught stealing by catcher
|
||||
roba = IntegerField() # (unknown - commented out)
|
||||
robs = IntegerField() # (unknown - commented out)
|
||||
raa = IntegerField() # (unknown - commented out)
|
||||
rto = IntegerField() # (unknown - commented out)
|
||||
|
||||
# Game context
|
||||
week = IntegerField()
|
||||
game = IntegerField()
|
||||
season = IntegerField()
|
||||
```
|
||||
|
||||
**Purpose**: Complete batting stats per player per game
|
||||
**Key Features**:
|
||||
- Very comprehensive (40+ fields!)
|
||||
- Includes fielding stats (errors, passed balls, caught stealing)
|
||||
- Has unknown/experimental fields (xba, xbt, roba, etc.)
|
||||
- Designed for per-game granularity
|
||||
|
||||
---
|
||||
|
||||
#### 3. **PitchingStat** - Per-game pitching statistics
|
||||
```python
|
||||
class PitchingStat(BaseModel):
|
||||
player = ForeignKeyField(Player)
|
||||
team = ForeignKeyField(Team)
|
||||
|
||||
# Standard pitching stats
|
||||
ip = FloatField() # Innings pitched (5.1 = 5 1/3 innings)
|
||||
hit = FloatField() # Hits allowed
|
||||
run = FloatField() # Runs allowed
|
||||
erun = FloatField() # Earned runs allowed
|
||||
so = FloatField() # Strikeouts
|
||||
bb = FloatField() # Walks
|
||||
hbp = FloatField() # Hit batters
|
||||
wp = FloatField() # Wild pitches
|
||||
balk = FloatField() # Balks
|
||||
hr = FloatField() # Home runs allowed
|
||||
|
||||
# Relief pitcher stats
|
||||
ir = FloatField() # Inherited runners
|
||||
irs = FloatField() # Inherited runners scored
|
||||
|
||||
# Game results
|
||||
gs = FloatField() # Games started
|
||||
win = FloatField() # Wins
|
||||
loss = FloatField() # Losses
|
||||
hold = FloatField() # Holds
|
||||
sv = FloatField() # Saves
|
||||
bsv = FloatField() # Blown saves
|
||||
|
||||
# Game context
|
||||
week = IntegerField()
|
||||
game = IntegerField()
|
||||
season = IntegerField()
|
||||
```
|
||||
|
||||
**Purpose**: Complete pitching stats per player per game
|
||||
**Key Features**:
|
||||
- Standard pitching metrics
|
||||
- Relief pitcher tracking (inherited runners)
|
||||
- Win/loss/save tracking
|
||||
- Uses FloatField for most stats (fractional values)
|
||||
|
||||
---
|
||||
|
||||
## New Web App Architecture (FastAPI/PostgreSQL)
|
||||
|
||||
### Current Database (SQLAlchemy)
|
||||
|
||||
We already have these tables:
|
||||
- `games` - Game metadata (game_id, league_id, teams, status)
|
||||
- `lineups` - Player lineup entries (with substitution support)
|
||||
- `plays` - Individual play records (play_result, dice_rolls, etc.)
|
||||
|
||||
### Gap Analysis
|
||||
|
||||
**What we DON'T have:**
|
||||
1. ❌ Per-game player statistics aggregation
|
||||
2. ❌ Team-level game statistics
|
||||
3. ❌ Linescore (runs per inning) storage
|
||||
4. ❌ Easy box score retrieval
|
||||
|
||||
**What we DO have:**
|
||||
- ✅ All raw play data (we can reconstruct stats from plays)
|
||||
- ✅ Player lineup tracking
|
||||
- ✅ Game metadata
|
||||
|
||||
---
|
||||
|
||||
## Options for Phase 3.5
|
||||
|
||||
### Option 1: Adapt Existing Schema (RECOMMENDED)
|
||||
|
||||
**Approach**: Create SQLAlchemy versions of existing tables with modern improvements
|
||||
|
||||
**New Tables**:
|
||||
|
||||
```python
|
||||
# Option 1A: Direct port with minimal changes
|
||||
class PlayerGameStats(Base):
|
||||
"""
|
||||
Mirrors BattingStat/PitchingStat but combines both.
|
||||
Uses existing field names for compatibility.
|
||||
"""
|
||||
__tablename__ = "player_game_stats"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
game_id = Column(UUID, ForeignKey("games.id"), nullable=False)
|
||||
lineup_id = Column(Integer, ForeignKey("lineups.id"), nullable=False)
|
||||
|
||||
# Standard batting (from BattingStat)
|
||||
pa = Column(Integer, default=0)
|
||||
ab = Column(Integer, default=0)
|
||||
run = Column(Integer, default=0) # Note: 'run' not 'runs'
|
||||
hit = Column(Integer, default=0) # Note: 'hit' not 'hits'
|
||||
rbi = Column(Integer, default=0)
|
||||
double = Column(Integer, default=0)
|
||||
triple = Column(Integer, default=0)
|
||||
hr = Column(Integer, default=0)
|
||||
bb = Column(Integer, default=0)
|
||||
so = Column(Integer, default=0)
|
||||
hbp = Column(Integer, default=0)
|
||||
sac = Column(Integer, default=0)
|
||||
sb = Column(Integer, default=0)
|
||||
cs = Column(Integer, default=0)
|
||||
|
||||
# Pitching stats (from PitchingStat)
|
||||
ip = Column(Float, default=0.0)
|
||||
# ... (all pitching fields)
|
||||
|
||||
# Fielding (if needed)
|
||||
error = Column(Integer, default=0)
|
||||
pb = Column(Integer, default=0)
|
||||
|
||||
class GameStats(Base):
|
||||
"""
|
||||
Mirrors Result table but adds linescore and more detail.
|
||||
"""
|
||||
__tablename__ = "game_stats"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
game_id = Column(UUID, ForeignKey("games.id"), unique=True)
|
||||
|
||||
# Team totals
|
||||
home_runs = Column(Integer, default=0)
|
||||
away_runs = Column(Integer, default=0)
|
||||
home_hits = Column(Integer, default=0)
|
||||
away_hits = Column(Integer, default=0)
|
||||
home_errors = Column(Integer, default=0)
|
||||
away_errors = Column(Integer, default=0)
|
||||
|
||||
# NEW: Linescore (not in legacy schema)
|
||||
home_linescore = Column(JSON) # [0, 1, 0, 3, ...]
|
||||
away_linescore = Column(JSON) # [1, 0, 2, 0, ...]
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
- ✅ Familiar field names for migration
|
||||
- ✅ Can reuse existing query patterns
|
||||
- ✅ Easy to submit to legacy REST API
|
||||
- ✅ Compatible with existing league tooling
|
||||
|
||||
**Drawbacks**:
|
||||
- ⚠️ Some weird field names ('run' vs 'runs', 'hit' vs 'hits')
|
||||
- ⚠️ Lots of fields we may not use (bphr, bpfo, xba, etc.)
|
||||
|
||||
---
|
||||
|
||||
### Option 2: Modern Schema from Scratch
|
||||
|
||||
**Approach**: Design clean schema optimized for web app
|
||||
|
||||
**New Tables**:
|
||||
|
||||
```python
|
||||
class PlayerGameStats(Base):
|
||||
"""Modern schema with clear naming."""
|
||||
__tablename__ = "player_game_stats"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
game_id = Column(UUID, ForeignKey("games.id"), nullable=False)
|
||||
lineup_id = Column(Integer, ForeignKey("lineups.id"), nullable=False)
|
||||
|
||||
# Batting (clearer names)
|
||||
plate_appearances = Column(Integer, default=0) # Not 'pa'
|
||||
at_bats = Column(Integer, default=0) # Not 'ab'
|
||||
runs = Column(Integer, default=0) # Not 'run'
|
||||
hits = Column(Integer, default=0) # Not 'hit'
|
||||
rbis = Column(Integer, default=0) # Not 'rbi'
|
||||
# ... etc
|
||||
|
||||
# Pitching
|
||||
innings_pitched = Column(Float, default=0.0) # Not 'ip'
|
||||
batters_faced = Column(Integer, default=0) # NEW field!
|
||||
# ... etc
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
- ✅ Clean, readable field names
|
||||
- ✅ Only fields we actually use
|
||||
- ✅ Modern best practices
|
||||
|
||||
**Drawbacks**:
|
||||
- ❌ Need field mapping for legacy API submission
|
||||
- ❌ Different from existing league patterns
|
||||
- ❌ More work to integrate with existing tooling
|
||||
|
||||
---
|
||||
|
||||
### Option 3: Hybrid Approach (RECOMMENDED)
|
||||
|
||||
**Approach**: Use existing field names but omit unused experimental fields
|
||||
|
||||
**New Tables**:
|
||||
|
||||
```python
|
||||
class PlayerGameStats(Base):
|
||||
"""
|
||||
Hybrid: existing field names for core stats,
|
||||
skip experimental/unused fields.
|
||||
"""
|
||||
__tablename__ = "player_game_stats"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
game_id = Column(UUID, ForeignKey("games.id"), nullable=False)
|
||||
lineup_id = Column(Integer, ForeignKey("lineups.id"), nullable=False)
|
||||
|
||||
# Batting - use legacy names for core stats
|
||||
pa = Column(Integer, default=0)
|
||||
ab = Column(Integer, default=0)
|
||||
run = Column(Integer, default=0)
|
||||
hit = Column(Integer, default=0)
|
||||
rbi = Column(Integer, default=0)
|
||||
double = Column(Integer, default=0)
|
||||
triple = Column(Integer, default=0)
|
||||
hr = Column(Integer, default=0)
|
||||
bb = Column(Integer, default=0)
|
||||
so = Column(Integer, default=0)
|
||||
hbp = Column(Integer, default=0)
|
||||
sb = Column(Integer, default=0)
|
||||
cs = Column(Integer, default=0)
|
||||
|
||||
# Pitching - use legacy names
|
||||
ip = Column(Float, default=0.0)
|
||||
# hits_allowed = Column(Integer, default=0) # 'hit' field reused?
|
||||
runs_allowed = Column(Integer, default=0)
|
||||
earned_runs = Column(Integer, default=0)
|
||||
walks_allowed = Column(Integer, default=0)
|
||||
strikeouts_pitched = Column(Integer, default=0)
|
||||
# ... etc
|
||||
|
||||
# SKIP: bphr, bpfo, bp1b, bplo (unclear purpose)
|
||||
# SKIP: xba, xbt, xch, xhit (commented out in queries anyway)
|
||||
# SKIP: roba, robs, raa, rto (unknown, commented out)
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
- ✅ Familiar core field names
|
||||
- ✅ Cleaner (no experimental cruft)
|
||||
- ✅ Easy legacy API submission
|
||||
- ✅ Room to add new fields as needed
|
||||
|
||||
**Drawbacks**:
|
||||
- ⚠️ Still has some odd naming ('run' vs 'runs')
|
||||
|
||||
---
|
||||
|
||||
## Questions for Discussion
|
||||
|
||||
### 1. **Field Naming Convention**
|
||||
- Should we use legacy names (`pa`, `ab`, `run`, `hit`) for compatibility?
|
||||
- Or modernize (`plate_appearances`, `at_bats`, `runs`, `hits`) for clarity?
|
||||
- **Recommendation**: Hybrid - legacy names for core stats, modern for new fields
|
||||
|
||||
### 2. **Experimental Fields**
|
||||
- What are `bphr`, `bpfo`, `bp1b`, `bplo`? (batter-pitcher matchup stats?)
|
||||
- What are `xba`, `xbt`, `xch`, `xhit`? (X-Check related?)
|
||||
- Do we need these or can we skip?
|
||||
- **Recommendation**: Skip for Phase 3.5 MVP, add later if needed
|
||||
|
||||
### 3. **Pitching Stats Field Overlap**
|
||||
- Legacy schema uses `hit` for both batting hits and pitching hits allowed
|
||||
- How do we handle this in a combined table?
|
||||
- **Options**:
|
||||
- A) Separate `batting_hit` and `pitching_hit` columns
|
||||
- B) Reuse `hit` field (batting or pitching based on position)
|
||||
- C) Separate BattingGameStats and PitchingGameStats tables
|
||||
- **Recommendation**: Option C - separate tables for clarity
|
||||
|
||||
### 4. **Linescore Storage**
|
||||
- Legacy has no linescore (runs by inning)
|
||||
- We need this for box score display
|
||||
- JSON array format: `[0, 1, 0, 3, ...]` per team?
|
||||
- **Recommendation**: Add to GameStats table as JSON
|
||||
|
||||
### 5. **Integration with Legacy API**
|
||||
- Do we need to submit stats to existing league REST API?
|
||||
- If yes, what format does it expect?
|
||||
- Can we provide a mapping layer?
|
||||
- **Recommendation**: Yes, create mapping function for API submission
|
||||
|
||||
### 6. **Stat Calculation Approach**
|
||||
- **Option A**: Real-time updates (update stats after each play)
|
||||
- **Option B**: Post-game aggregation (calculate from plays table)
|
||||
- **Option C**: Hybrid (real-time updates + verification from plays)
|
||||
- **Recommendation**: Option A (real-time) for performance, with Option B as backup/verification
|
||||
|
||||
---
|
||||
|
||||
## Proposed Schema (Final Recommendation)
|
||||
|
||||
### Recommended Approach: Hybrid with Separate Tables
|
||||
|
||||
```python
|
||||
class GameStats(Base):
|
||||
"""Game-level statistics and linescore."""
|
||||
__tablename__ = "game_stats"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
game_id = Column(UUID, ForeignKey("games.id"), unique=True)
|
||||
created_at = Column(DateTime, default=func.now())
|
||||
|
||||
# Team totals
|
||||
home_runs = Column(Integer, default=0)
|
||||
away_runs = Column(Integer, default=0)
|
||||
home_hits = Column(Integer, default=0)
|
||||
away_hits = Column(Integer, default=0)
|
||||
home_errors = Column(Integer, default=0)
|
||||
away_errors = Column(Integer, default=0)
|
||||
|
||||
# Linescore (NEW - not in legacy)
|
||||
home_linescore = Column(JSON) # [0, 1, 0, 3, ...]
|
||||
away_linescore = Column(JSON) # [1, 0, 2, 0, ...]
|
||||
|
||||
|
||||
class BattingGameStats(Base):
|
||||
"""Batting statistics per player per game."""
|
||||
__tablename__ = "batting_game_stats"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
game_id = Column(UUID, ForeignKey("games.id"), nullable=False)
|
||||
lineup_id = Column(Integer, ForeignKey("lineups.id"), nullable=False)
|
||||
|
||||
# Use legacy field names for compatibility
|
||||
pa = Column(Integer, default=0)
|
||||
ab = Column(Integer, default=0)
|
||||
run = Column(Integer, default=0)
|
||||
hit = Column(Integer, default=0)
|
||||
rbi = Column(Integer, default=0)
|
||||
double = Column(Integer, default=0)
|
||||
triple = Column(Integer, default=0)
|
||||
hr = Column(Integer, default=0)
|
||||
bb = Column(Integer, default=0)
|
||||
so = Column(Integer, default=0)
|
||||
hbp = Column(Integer, default=0)
|
||||
sac = Column(Integer, default=0)
|
||||
sb = Column(Integer, default=0)
|
||||
cs = Column(Integer, default=0)
|
||||
gidp = Column(Integer, default=0)
|
||||
|
||||
__table_args__ = (
|
||||
Index('idx_batting_game_stats_game', 'game_id'),
|
||||
Index('idx_batting_game_stats_lineup', 'lineup_id'),
|
||||
)
|
||||
|
||||
|
||||
class PitchingGameStats(Base):
|
||||
"""Pitching statistics per player per game."""
|
||||
__tablename__ = "pitching_game_stats"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
game_id = Column(UUID, ForeignKey("games.id"), nullable=False)
|
||||
lineup_id = Column(Integer, ForeignKey("lineups.id"), nullable=False)
|
||||
|
||||
# Use legacy field names for compatibility
|
||||
ip = Column(Float, default=0.0)
|
||||
hit = Column(Integer, default=0) # Hits allowed
|
||||
run = Column(Integer, default=0) # Runs allowed
|
||||
erun = Column(Integer, default=0) # Earned runs (legacy: 'erun')
|
||||
so = Column(Integer, default=0) # Strikeouts
|
||||
bb = Column(Integer, default=0) # Walks
|
||||
hbp = Column(Integer, default=0) # Hit batters
|
||||
hr = Column(Integer, default=0) # Home runs allowed
|
||||
wp = Column(Integer, default=0) # Wild pitches
|
||||
|
||||
# NEW: Batters faced (not in legacy, but useful)
|
||||
batters_faced = Column(Integer, default=0)
|
||||
|
||||
__table_args__ = (
|
||||
Index('idx_pitching_game_stats_game', 'game_id'),
|
||||
Index('idx_pitching_game_stats_lineup', 'lineup_id'),
|
||||
)
|
||||
```
|
||||
|
||||
**Why Separate Tables?**
|
||||
1. Clearer intent (batting vs pitching)
|
||||
2. No field name conflicts (`hit` means different things)
|
||||
3. Easier queries (no need to filter by position)
|
||||
4. Better indexing (separate indexes per table)
|
||||
5. Matches real-world mental model (batters bat, pitchers pitch)
|
||||
|
||||
---
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
1. **Dual Position Players** (e.g., Shohei Ohtani):
|
||||
- Two records: one in BattingGameStats, one in PitchingGameStats
|
||||
- Both reference same lineup_id
|
||||
- Aggregated separately
|
||||
|
||||
2. **Legacy API Submission**:
|
||||
- Create mapping function: `web_stats_to_legacy_format()`
|
||||
- Convert our stats to legacy BattingStat/PitchingStat format
|
||||
- Submit to existing REST API endpoints
|
||||
|
||||
3. **Stat Tracker Service**:
|
||||
- Maintains in-memory cache for current games
|
||||
- Async writes to database
|
||||
- Provides `get_box_score()` method with formatted output
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
**Please advise on**:
|
||||
1. ✅ Approve hybrid approach with separate batting/pitching tables?
|
||||
2. ✅ Use legacy field names for core stats?
|
||||
3. ✅ Skip experimental fields (bphr, xba, etc.) for now?
|
||||
4. ✅ Add linescore to GameStats?
|
||||
5. ✅ Plan for legacy API submission?
|
||||
|
||||
Once approved, I'll update `phase-3.5-polish-stats.md` with the corrected schema.
|
||||
696
.claude/implementation/STAT_SYSTEM_MATERIALIZED_VIEWS.md
Normal file
696
.claude/implementation/STAT_SYSTEM_MATERIALIZED_VIEWS.md
Normal file
@ -0,0 +1,696 @@
|
||||
# Statistics System: Materialized Views Approach
|
||||
|
||||
**Date**: 2025-11-06
|
||||
**Approach**: PostgreSQL Materialized Views (following legacy API pattern)
|
||||
|
||||
---
|
||||
|
||||
## Why Materialized Views?
|
||||
|
||||
### Legacy API Pattern
|
||||
The existing major-domo API already does this:
|
||||
- **`/plays/batting`** - Aggregates plays on-the-fly with SQL SUM/COUNT
|
||||
- **`/plays/pitching`** - Aggregates plays on-the-fly with SQL SUM/COUNT
|
||||
- **BattingStat/PitchingStat tables** - Deprecated in favor of play aggregation
|
||||
|
||||
### Benefits
|
||||
1. ✅ **Single source of truth**: Plays table is the only data we write
|
||||
2. ✅ **No stat tracking code**: PostgreSQL does the aggregation
|
||||
3. ✅ **Always consistent**: Stats are derived, not stored separately
|
||||
4. ✅ **Fast queries**: Materialized views are indexed and cached
|
||||
5. ✅ **Refresh on demand**: Update views when needed (after games, on schedule)
|
||||
6. ✅ **No sync issues**: Can't have play/stat mismatches
|
||||
|
||||
### Drawbacks
|
||||
- ⚠️ **Refresh required**: Views must be refreshed to show latest data
|
||||
- ⚠️ **PostgreSQL specific**: Can't easily port to other databases
|
||||
- ⚠️ **Migration complexity**: Need to manage view schema changes
|
||||
|
||||
**Verdict**: Benefits far outweigh drawbacks for this use case
|
||||
|
||||
---
|
||||
|
||||
## Proposed Schema
|
||||
|
||||
### Existing Tables (Already Have)
|
||||
|
||||
```sql
|
||||
-- We already have these in the web app
|
||||
CREATE TABLE games (
|
||||
id UUID PRIMARY KEY,
|
||||
league_id VARCHAR(50),
|
||||
home_team_id INT,
|
||||
away_team_id INT,
|
||||
status VARCHAR(20),
|
||||
current_inning INT,
|
||||
current_half VARCHAR(3),
|
||||
home_score INT,
|
||||
away_score INT,
|
||||
-- ... other game fields
|
||||
);
|
||||
|
||||
CREATE TABLE lineups (
|
||||
id SERIAL PRIMARY KEY,
|
||||
game_id UUID REFERENCES games(id),
|
||||
card_id INT, -- Player card ID
|
||||
team_id INT,
|
||||
position VARCHAR(3),
|
||||
batting_order INT,
|
||||
is_active BOOLEAN,
|
||||
is_starter BOOLEAN,
|
||||
-- ... other lineup fields
|
||||
);
|
||||
|
||||
CREATE TABLE plays (
|
||||
id SERIAL PRIMARY KEY,
|
||||
game_id UUID REFERENCES games(id),
|
||||
play_num INT,
|
||||
inning INT,
|
||||
half VARCHAR(3),
|
||||
batter_lineup_id INT REFERENCES lineups(id),
|
||||
pitcher_lineup_id INT REFERENCES lineups(id),
|
||||
play_result VARCHAR(50), -- PlayOutcome enum value
|
||||
-- ... other play fields (runners, outs, scores, etc.)
|
||||
);
|
||||
```
|
||||
|
||||
**Need to add to Plays table** (currently missing):
|
||||
|
||||
```sql
|
||||
ALTER TABLE plays ADD COLUMN IF NOT EXISTS pa INT DEFAULT 0; -- Plate appearance (0 or 1)
|
||||
ALTER TABLE plays ADD COLUMN IF NOT EXISTS ab INT DEFAULT 0; -- At bat (0 or 1)
|
||||
ALTER TABLE plays ADD COLUMN IF NOT EXISTS hit INT DEFAULT 0; -- Hit (0 or 1)
|
||||
ALTER TABLE plays ADD COLUMN IF NOT EXISTS run INT DEFAULT 0; -- Runs scored this play
|
||||
ALTER TABLE plays ADD COLUMN IF NOT EXISTS rbi INT DEFAULT 0; -- RBIs this play
|
||||
ALTER TABLE plays ADD COLUMN IF NOT EXISTS double INT DEFAULT 0; -- Double (0 or 1)
|
||||
ALTER TABLE plays ADD COLUMN IF NOT EXISTS triple INT DEFAULT 0; -- Triple (0 or 1)
|
||||
ALTER TABLE plays ADD COLUMN IF NOT EXISTS hr INT DEFAULT 0; -- Home run (0 or 1)
|
||||
ALTER TABLE plays ADD COLUMN IF NOT EXISTS bb INT DEFAULT 0; -- Walk (0 or 1)
|
||||
ALTER TABLE plays ADD COLUMN IF NOT EXISTS so INT DEFAULT 0; -- Strikeout (0 or 1)
|
||||
ALTER TABLE plays ADD COLUMN IF NOT EXISTS hbp INT DEFAULT 0; -- Hit by pitch (0 or 1)
|
||||
ALTER TABLE plays ADD COLUMN IF NOT EXISTS sac INT DEFAULT 0; -- Sacrifice (0 or 1)
|
||||
ALTER TABLE plays ADD COLUMN IF NOT EXISTS sb INT DEFAULT 0; -- Stolen base (0 or 1)
|
||||
ALTER TABLE plays ADD COLUMN IF NOT EXISTS cs INT DEFAULT 0; -- Caught stealing (0 or 1)
|
||||
ALTER TABLE plays ADD COLUMN IF NOT EXISTS gidp INT DEFAULT 0; -- Ground into DP (0 or 1)
|
||||
ALTER TABLE plays ADD COLUMN IF NOT EXISTS error INT DEFAULT 0; -- Error this play
|
||||
ALTER TABLE plays ADD COLUMN IF NOT EXISTS wp INT DEFAULT 0; -- Wild pitch (0 or 1)
|
||||
ALTER TABLE plays ADD COLUMN IF NOT EXISTS pb INT DEFAULT 0; -- Passed ball (0 or 1)
|
||||
ALTER TABLE plays ADD COLUMN IF NOT EXISTS outs_recorded INT DEFAULT 0; -- Outs recorded this play
|
||||
```
|
||||
|
||||
**Why add stat fields to plays?**
|
||||
- Each play records the statistical events that occurred
|
||||
- Makes aggregation queries simple and fast
|
||||
- Matches legacy StratPlay model exactly
|
||||
- Can be calculated from PlayOutcome when play is recorded
|
||||
|
||||
---
|
||||
|
||||
### New Materialized Views
|
||||
|
||||
#### 1. Batting Stats by Player-Game
|
||||
|
||||
```sql
|
||||
CREATE MATERIALIZED VIEW batting_game_stats AS
|
||||
SELECT
|
||||
l.game_id,
|
||||
l.id AS lineup_id,
|
||||
l.card_id AS player_card_id,
|
||||
l.team_id,
|
||||
|
||||
-- Aggregate batting stats
|
||||
COUNT(*) FILTER (WHERE p.pa = 1) AS pa,
|
||||
COUNT(*) FILTER (WHERE p.ab = 1) AS ab,
|
||||
SUM(p.run) AS run,
|
||||
SUM(p.hit) AS hit,
|
||||
SUM(p.rbi) AS rbi,
|
||||
SUM(p.double) AS double,
|
||||
SUM(p.triple) AS triple,
|
||||
SUM(p.hr) AS hr,
|
||||
SUM(p.bb) AS bb,
|
||||
SUM(p.so) AS so,
|
||||
SUM(p.hbp) AS hbp,
|
||||
SUM(p.sac) AS sac,
|
||||
SUM(p.sb) AS sb,
|
||||
SUM(p.cs) AS cs,
|
||||
SUM(p.gidp) AS gidp
|
||||
|
||||
FROM lineups l
|
||||
JOIN plays p ON p.batter_lineup_id = l.id
|
||||
WHERE l.is_active = TRUE OR l.is_starter = TRUE -- Include all who played
|
||||
GROUP BY l.game_id, l.id, l.card_id, l.team_id;
|
||||
|
||||
-- Indexes for fast lookups
|
||||
CREATE UNIQUE INDEX idx_batting_game_stats_lineup ON batting_game_stats(lineup_id);
|
||||
CREATE INDEX idx_batting_game_stats_game ON batting_game_stats(game_id);
|
||||
CREATE INDEX idx_batting_game_stats_player ON batting_game_stats(player_card_id);
|
||||
```
|
||||
|
||||
**Usage**: `SELECT * FROM batting_game_stats WHERE game_id = ?`
|
||||
|
||||
---
|
||||
|
||||
#### 2. Pitching Stats by Player-Game
|
||||
|
||||
```sql
|
||||
CREATE MATERIALIZED VIEW pitching_game_stats AS
|
||||
SELECT
|
||||
l.game_id,
|
||||
l.id AS lineup_id,
|
||||
l.card_id AS player_card_id,
|
||||
l.team_id,
|
||||
|
||||
-- Aggregate pitching stats
|
||||
COUNT(*) FILTER (WHERE p.pa = 1) AS batters_faced,
|
||||
SUM(p.hit) AS hit_allowed,
|
||||
SUM(p.run) AS run_allowed,
|
||||
-- TODO: Calculate earned runs (need error tracking)
|
||||
SUM(p.run) AS erun, -- Placeholder: all runs as earned for now
|
||||
SUM(p.bb) AS bb,
|
||||
SUM(p.so) AS so,
|
||||
SUM(p.hbp) AS hbp,
|
||||
SUM(p.hr) AS hr_allowed,
|
||||
SUM(p.wp) AS wp,
|
||||
|
||||
-- Calculate innings pitched from outs
|
||||
-- IP = outs / 3.0 (e.g., 16 outs = 5.1 IP)
|
||||
(SUM(p.outs_recorded)::float / 3.0) AS ip
|
||||
|
||||
FROM lineups l
|
||||
JOIN plays p ON p.pitcher_lineup_id = l.id
|
||||
WHERE l.position = 'P' AND (l.is_active = TRUE OR l.is_starter = TRUE)
|
||||
GROUP BY l.game_id, l.id, l.card_id, l.team_id;
|
||||
|
||||
-- Indexes
|
||||
CREATE UNIQUE INDEX idx_pitching_game_stats_lineup ON pitching_game_stats(lineup_id);
|
||||
CREATE INDEX idx_pitching_game_stats_game ON pitching_game_stats(game_id);
|
||||
CREATE INDEX idx_pitching_game_stats_player ON pitching_game_stats(player_card_id);
|
||||
```
|
||||
|
||||
**Usage**: `SELECT * FROM pitching_game_stats WHERE game_id = ?`
|
||||
|
||||
---
|
||||
|
||||
#### 3. Team Game Stats (Summary + Linescore)
|
||||
|
||||
For box scores, we need team-level aggregates and linescore (runs by inning):
|
||||
|
||||
```sql
|
||||
CREATE MATERIALIZED VIEW game_stats AS
|
||||
WITH inning_scores AS (
|
||||
-- Calculate runs scored per team per inning
|
||||
SELECT
|
||||
game_id,
|
||||
inning,
|
||||
half,
|
||||
SUM(run) AS runs_scored
|
||||
FROM plays
|
||||
GROUP BY game_id, inning, half
|
||||
),
|
||||
linescores AS (
|
||||
-- Build linescore JSON arrays
|
||||
SELECT
|
||||
game_id,
|
||||
json_agg(runs_scored ORDER BY inning) FILTER (WHERE half = 'top') AS away_linescore,
|
||||
json_agg(runs_scored ORDER BY inning) FILTER (WHERE half = 'bot') AS home_linescore
|
||||
FROM inning_scores
|
||||
GROUP BY game_id
|
||||
),
|
||||
batting_totals AS (
|
||||
-- Team batting totals
|
||||
SELECT
|
||||
game_id,
|
||||
l.team_id,
|
||||
SUM(p.hit) AS hits,
|
||||
SUM(p.error) AS errors
|
||||
FROM plays p
|
||||
JOIN lineups l ON p.batter_lineup_id = l.id
|
||||
GROUP BY game_id, l.team_id
|
||||
)
|
||||
SELECT
|
||||
g.id AS game_id,
|
||||
g.home_score AS home_runs,
|
||||
g.away_score AS away_runs,
|
||||
|
||||
-- Linescore
|
||||
COALESCE(ls.home_linescore, '[]'::json) AS home_linescore,
|
||||
COALESCE(ls.away_linescore, '[]'::json) AS away_linescore,
|
||||
|
||||
-- Home team totals
|
||||
MAX(bth.hits) AS home_hits,
|
||||
MAX(bth.errors) AS home_errors,
|
||||
|
||||
-- Away team totals
|
||||
MAX(bta.hits) AS away_hits,
|
||||
MAX(bta.errors) AS away_errors
|
||||
|
||||
FROM games g
|
||||
LEFT JOIN linescores ls ON g.id = ls.game_id
|
||||
LEFT JOIN batting_totals bth ON g.id = bth.game_id AND bth.team_id = g.home_team_id
|
||||
LEFT JOIN batting_totals bta ON g.id = bta.game_id AND bta.team_id = g.away_team_id
|
||||
GROUP BY g.id, ls.home_linescore, ls.away_linescore;
|
||||
|
||||
-- Index
|
||||
CREATE UNIQUE INDEX idx_game_stats_game ON game_stats(game_id);
|
||||
```
|
||||
|
||||
**Usage**: `SELECT * FROM game_stats WHERE game_id = ?`
|
||||
|
||||
**Linescore Format**: `[0, 1, 0, 3, 0, 0, 2, 1, 0]` (9 innings)
|
||||
|
||||
---
|
||||
|
||||
## Implementation Strategy
|
||||
|
||||
### Phase 3.5 Changes
|
||||
|
||||
#### 1. Add Stat Fields to Plays Table (Migration)
|
||||
|
||||
**File**: `backend/alembic/versions/004_add_play_stat_fields.py`
|
||||
|
||||
```python
|
||||
"""Add statistical fields to plays table.
|
||||
|
||||
Revision ID: 004
|
||||
Revises: 003
|
||||
"""
|
||||
|
||||
def upgrade():
|
||||
# Add batting stat fields
|
||||
op.add_column('plays', sa.Column('pa', sa.Integer(), default=0))
|
||||
op.add_column('plays', sa.Column('ab', sa.Integer(), default=0))
|
||||
op.add_column('plays', sa.Column('hit', sa.Integer(), default=0))
|
||||
op.add_column('plays', sa.Column('run', sa.Integer(), default=0))
|
||||
op.add_column('plays', sa.Column('rbi', sa.Integer(), default=0))
|
||||
op.add_column('plays', sa.Column('double', sa.Integer(), default=0))
|
||||
op.add_column('plays', sa.Column('triple', sa.Integer(), default=0))
|
||||
op.add_column('plays', sa.Column('hr', sa.Integer(), default=0))
|
||||
op.add_column('plays', sa.Column('bb', sa.Integer(), default=0))
|
||||
op.add_column('plays', sa.Column('so', sa.Integer(), default=0))
|
||||
op.add_column('plays', sa.Column('hbp', sa.Integer(), default=0))
|
||||
op.add_column('plays', sa.Column('sac', sa.Integer(), default=0))
|
||||
op.add_column('plays', sa.Column('sb', sa.Integer(), default=0))
|
||||
op.add_column('plays', sa.Column('cs', sa.Integer(), default=0))
|
||||
op.add_column('plays', sa.Column('gidp', sa.Integer(), default=0))
|
||||
op.add_column('plays', sa.Column('error', sa.Integer(), default=0))
|
||||
op.add_column('plays', sa.Column('wp', sa.Integer(), default=0))
|
||||
op.add_column('plays', sa.Column('pb', sa.Integer(), default=0))
|
||||
op.add_column('plays', sa.Column('outs_recorded', sa.Integer(), default=0))
|
||||
|
||||
def downgrade():
|
||||
# Remove all stat columns
|
||||
op.drop_column('plays', 'pa')
|
||||
# ... etc
|
||||
```
|
||||
|
||||
#### 2. Update Play Model
|
||||
|
||||
**File**: `backend/app/models/db_models.py`
|
||||
|
||||
```python
|
||||
class Play(Base):
|
||||
__tablename__ = "plays"
|
||||
|
||||
# Existing fields
|
||||
id = Column(Integer, primary_key=True)
|
||||
game_id = Column(UUID, ForeignKey("games.id"))
|
||||
# ... etc
|
||||
|
||||
# NEW: Statistical fields (added in migration 004)
|
||||
pa = Column(Integer, default=0)
|
||||
ab = Column(Integer, default=0)
|
||||
hit = Column(Integer, default=0)
|
||||
run = Column(Integer, default=0)
|
||||
rbi = Column(Integer, default=0)
|
||||
double = Column(Integer, default=0)
|
||||
triple = Column(Integer, default=0)
|
||||
hr = Column(Integer, default=0)
|
||||
bb = Column(Integer, default=0)
|
||||
so = Column(Integer, default=0)
|
||||
hbp = Column(Integer, default=0)
|
||||
sac = Column(Integer, default=0)
|
||||
sb = Column(Integer, default=0)
|
||||
cs = Column(Integer, default=0)
|
||||
gidp = Column(Integer, default=0)
|
||||
error = Column(Integer, default=0)
|
||||
wp = Column(Integer, default=0)
|
||||
pb = Column(Integer, default=0)
|
||||
outs_recorded = Column(Integer, default=0)
|
||||
```
|
||||
|
||||
#### 3. Create Stat Calculator
|
||||
|
||||
**File**: `backend/app/services/play_stat_calculator.py` (NEW)
|
||||
|
||||
```python
|
||||
"""
|
||||
Calculate statistical fields from PlayOutcome.
|
||||
|
||||
Called when recording a play to populate stat fields.
|
||||
"""
|
||||
from app.config.play_outcome import PlayOutcome
|
||||
from app.models.game_models import PlayResult, GameState
|
||||
|
||||
class PlayStatCalculator:
|
||||
"""
|
||||
Converts play outcome to statistical fields for database.
|
||||
"""
|
||||
|
||||
@staticmethod
|
||||
def calculate_stats(
|
||||
outcome: PlayOutcome,
|
||||
result: PlayResult,
|
||||
state_before: GameState,
|
||||
state_after: GameState
|
||||
) -> dict:
|
||||
"""
|
||||
Calculate all stat fields for a play.
|
||||
|
||||
Returns:
|
||||
dict with stat fields (pa, ab, hit, run, etc.)
|
||||
"""
|
||||
stats = {
|
||||
'pa': 0, 'ab': 0, 'hit': 0, 'run': 0, 'rbi': 0,
|
||||
'double': 0, 'triple': 0, 'hr': 0, 'bb': 0, 'so': 0,
|
||||
'hbp': 0, 'sac': 0, 'sb': 0, 'cs': 0, 'gidp': 0,
|
||||
'error': 0, 'wp': 0, 'pb': 0, 'outs_recorded': 0
|
||||
}
|
||||
|
||||
# Plate appearance (almost always 1, except...)
|
||||
if outcome not in [PlayOutcome.STOLEN_BASE_SUCCESS,
|
||||
PlayOutcome.CAUGHT_STEALING,
|
||||
PlayOutcome.WILD_PITCH,
|
||||
PlayOutcome.PASSED_BALL]:
|
||||
stats['pa'] = 1
|
||||
|
||||
# At bat (PA minus walks, HBP, sac)
|
||||
if stats['pa'] == 1 and outcome not in [
|
||||
PlayOutcome.WALK, PlayOutcome.HBP, PlayOutcome.SACRIFICE
|
||||
]:
|
||||
stats['ab'] = 1
|
||||
|
||||
# Hits
|
||||
if outcome in PlayOutcome.get_hit_outcomes():
|
||||
stats['hit'] = 1
|
||||
|
||||
if outcome in PlayOutcome.get_double_outcomes():
|
||||
stats['double'] = 1
|
||||
elif outcome in PlayOutcome.get_triple_outcomes():
|
||||
stats['triple'] = 1
|
||||
elif outcome in PlayOutcome.get_homerun_outcomes():
|
||||
stats['hr'] = 1
|
||||
|
||||
# Other outcomes
|
||||
if outcome == PlayOutcome.WALK:
|
||||
stats['bb'] = 1
|
||||
elif outcome == PlayOutcome.STRIKEOUT:
|
||||
stats['so'] = 1
|
||||
elif outcome == PlayOutcome.HBP:
|
||||
stats['hbp'] = 1
|
||||
elif outcome == PlayOutcome.SACRIFICE:
|
||||
stats['sac'] = 1
|
||||
elif outcome == PlayOutcome.STOLEN_BASE_SUCCESS:
|
||||
stats['sb'] = 1
|
||||
elif outcome == PlayOutcome.CAUGHT_STEALING:
|
||||
stats['cs'] = 1
|
||||
elif outcome in [PlayOutcome.GROUNDBALL_GDP]:
|
||||
stats['gidp'] = 1
|
||||
elif outcome == PlayOutcome.WILD_PITCH:
|
||||
stats['wp'] = 1
|
||||
elif outcome == PlayOutcome.PASSED_BALL:
|
||||
stats['pb'] = 1
|
||||
|
||||
# Calculate runs and RBIs from state change
|
||||
stats['run'] = state_after.home_score - state_before.home_score
|
||||
if state_after.away_score > state_before.away_score:
|
||||
stats['run'] = state_after.away_score - state_before.away_score
|
||||
|
||||
# RBI logic (runs scored minus errors)
|
||||
if not result.error_occurred:
|
||||
stats['rbi'] = stats['run']
|
||||
|
||||
# Outs recorded
|
||||
stats['outs_recorded'] = state_after.outs - state_before.outs
|
||||
|
||||
return stats
|
||||
```
|
||||
|
||||
#### 4. Update GameEngine to Calculate Stats
|
||||
|
||||
**File**: `backend/app/core/game_engine.py`
|
||||
|
||||
```python
|
||||
from app.services.play_stat_calculator import PlayStatCalculator
|
||||
|
||||
class GameEngine:
|
||||
async def record_play(
|
||||
self,
|
||||
game_id: UUID,
|
||||
outcome: PlayOutcome,
|
||||
...
|
||||
) -> PlayResult:
|
||||
"""Record play and calculate stats."""
|
||||
|
||||
state_before = self.state_manager.get_state(game_id)
|
||||
|
||||
# Resolve play (existing logic)
|
||||
result = self._resolve_play(...)
|
||||
|
||||
state_after = self.state_manager.get_state(game_id)
|
||||
|
||||
# NEW: Calculate stat fields
|
||||
stats = PlayStatCalculator.calculate_stats(
|
||||
outcome, result, state_before, state_after
|
||||
)
|
||||
|
||||
# Save play to database with stats
|
||||
await self.db_ops.create_play(
|
||||
game_id=game_id,
|
||||
play_num=state_after.play_count,
|
||||
inning=state_after.current_inning,
|
||||
half=state_after.current_half,
|
||||
batter_lineup_id=state_before.current_batter.lineup_id,
|
||||
pitcher_lineup_id=state_before.current_pitcher.lineup_id,
|
||||
play_result=outcome.value,
|
||||
# NEW: Add stat fields
|
||||
**stats
|
||||
)
|
||||
|
||||
return result
|
||||
```
|
||||
|
||||
#### 5. Create Materialized Views (Migration)
|
||||
|
||||
**File**: `backend/alembic/versions/005_create_stat_views.py`
|
||||
|
||||
```python
|
||||
"""Create materialized views for statistics.
|
||||
|
||||
Revision ID: 005
|
||||
Revises: 004
|
||||
"""
|
||||
|
||||
def upgrade():
|
||||
# Create batting_game_stats view
|
||||
op.execute("""
|
||||
CREATE MATERIALIZED VIEW batting_game_stats AS
|
||||
SELECT
|
||||
l.game_id,
|
||||
l.id AS lineup_id,
|
||||
l.card_id AS player_card_id,
|
||||
l.team_id,
|
||||
COUNT(*) FILTER (WHERE p.pa = 1) AS pa,
|
||||
COUNT(*) FILTER (WHERE p.ab = 1) AS ab,
|
||||
SUM(p.run) AS run,
|
||||
SUM(p.hit) AS hit,
|
||||
SUM(p.rbi) AS rbi,
|
||||
SUM(p.double) AS double,
|
||||
SUM(p.triple) AS triple,
|
||||
SUM(p.hr) AS hr,
|
||||
SUM(p.bb) AS bb,
|
||||
SUM(p.so) AS so,
|
||||
SUM(p.hbp) AS hbp,
|
||||
SUM(p.sac) AS sac,
|
||||
SUM(p.sb) AS sb,
|
||||
SUM(p.cs) AS cs,
|
||||
SUM(p.gidp) AS gidp
|
||||
FROM lineups l
|
||||
JOIN plays p ON p.batter_lineup_id = l.id
|
||||
GROUP BY l.game_id, l.id, l.card_id, l.team_id
|
||||
""")
|
||||
|
||||
op.execute("""
|
||||
CREATE UNIQUE INDEX idx_batting_game_stats_lineup
|
||||
ON batting_game_stats(lineup_id)
|
||||
""")
|
||||
|
||||
# Create pitching_game_stats view
|
||||
op.execute("""
|
||||
CREATE MATERIALIZED VIEW pitching_game_stats AS
|
||||
... (full SQL from above)
|
||||
""")
|
||||
|
||||
# Create game_stats view
|
||||
op.execute("""
|
||||
CREATE MATERIALIZED VIEW game_stats AS
|
||||
... (full SQL from above)
|
||||
""")
|
||||
|
||||
def downgrade():
|
||||
op.execute("DROP MATERIALIZED VIEW IF EXISTS batting_game_stats")
|
||||
op.execute("DROP MATERIALIZED VIEW IF EXISTS pitching_game_stats")
|
||||
op.execute("DROP MATERIALIZED VIEW IF EXISTS game_stats")
|
||||
```
|
||||
|
||||
#### 6. Create View Refresh Service
|
||||
|
||||
**File**: `backend/app/services/stat_view_refresher.py` (NEW)
|
||||
|
||||
```python
|
||||
"""
|
||||
Service to refresh materialized views.
|
||||
"""
|
||||
from sqlalchemy import text
|
||||
from app.database.database import async_session
|
||||
|
||||
class StatViewRefresher:
|
||||
"""Manages refreshing of statistical materialized views."""
|
||||
|
||||
@staticmethod
|
||||
async def refresh_game_stats(game_id: UUID) -> None:
|
||||
"""
|
||||
Refresh stats for a specific game (partial refresh).
|
||||
|
||||
Note: PostgreSQL doesn't support partial refresh of materialized views.
|
||||
We'd need to implement this with regular views or partitioning.
|
||||
For now, refresh all views after game completion.
|
||||
"""
|
||||
await StatViewRefresher.refresh_all()
|
||||
|
||||
@staticmethod
|
||||
async def refresh_all() -> None:
|
||||
"""Refresh all statistical views."""
|
||||
async with async_session() as session:
|
||||
await session.execute(text("REFRESH MATERIALIZED VIEW CONCURRENTLY batting_game_stats"))
|
||||
await session.execute(text("REFRESH MATERIALIZED VIEW CONCURRENTLY pitching_game_stats"))
|
||||
await session.execute(text("REFRESH MATERIALIZED VIEW CONCURRENTLY game_stats"))
|
||||
await session.commit()
|
||||
```
|
||||
|
||||
#### 7. Box Score Retrieval
|
||||
|
||||
**File**: `backend/app/services/box_score_service.py` (NEW)
|
||||
|
||||
```python
|
||||
"""
|
||||
Service to retrieve formatted box scores.
|
||||
"""
|
||||
from sqlalchemy import text
|
||||
from app.database.database import async_session
|
||||
|
||||
class BoxScoreService:
|
||||
"""Retrieves box score data from materialized views."""
|
||||
|
||||
@staticmethod
|
||||
async def get_box_score(game_id: UUID) -> dict:
|
||||
"""
|
||||
Get complete box score for a game.
|
||||
|
||||
Returns dict with:
|
||||
- game_stats: Team totals and linescore
|
||||
- batting_stats: List of batting lines
|
||||
- pitching_stats: List of pitching lines
|
||||
"""
|
||||
async with async_session() as session:
|
||||
# Get game stats
|
||||
game_query = text("""
|
||||
SELECT * FROM game_stats WHERE game_id = :game_id
|
||||
""")
|
||||
game_result = await session.execute(game_query, {"game_id": str(game_id)})
|
||||
game_stats = game_result.fetchone()._asdict() if game_result else {}
|
||||
|
||||
# Get batting stats
|
||||
batting_query = text("""
|
||||
SELECT * FROM batting_game_stats WHERE game_id = :game_id
|
||||
ORDER BY lineup_id
|
||||
""")
|
||||
batting_result = await session.execute(batting_query, {"game_id": str(game_id)})
|
||||
batting_stats = [row._asdict() for row in batting_result]
|
||||
|
||||
# Get pitching stats
|
||||
pitching_query = text("""
|
||||
SELECT * FROM pitching_game_stats WHERE game_id = :game_id
|
||||
ORDER BY lineup_id
|
||||
""")
|
||||
pitching_result = await session.execute(pitching_query, {"game_id": str(game_id)})
|
||||
pitching_stats = [row._asdict() for row in pitching_result]
|
||||
|
||||
return {
|
||||
'game_stats': game_stats,
|
||||
'batting_stats': batting_stats,
|
||||
'pitching_stats': pitching_stats
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Refresh Strategy
|
||||
|
||||
### When to Refresh Views?
|
||||
|
||||
**Option 1: After Each Play** (Real-time)
|
||||
- Pros: Always up-to-date
|
||||
- Cons: Performance impact, too frequent
|
||||
|
||||
**Option 2: After Game Completion** (Recommended for MVP)
|
||||
- Pros: Good balance of freshness and performance
|
||||
- Cons: Stats not visible until game ends
|
||||
|
||||
**Option 3: On Demand** (Terminal client)
|
||||
- Pros: User controls refresh
|
||||
- Cons: Stale data between refreshes
|
||||
|
||||
**Option 4: Scheduled** (Every 5 minutes)
|
||||
- Pros: Predictable, low impact
|
||||
- Cons: 5-minute staleness
|
||||
|
||||
**Recommended**: Option 2 (game completion) + Option 3 (on-demand for testing)
|
||||
|
||||
---
|
||||
|
||||
## Benefits of This Approach
|
||||
|
||||
1. **No Stat Tracker Needed**: Eliminated ~400 lines of stat tracking code
|
||||
2. **Single Source of Truth**: Plays table is the only data we write
|
||||
3. **Consistency Guaranteed**: Stats are always derived from plays
|
||||
4. **Simple Logic**: PlayStatCalculator is straightforward field mapping
|
||||
5. **SQL Optimized**: PostgreSQL handles aggregation efficiently
|
||||
6. **Flexible Queries**: Can create any stat aggregation we want with new views
|
||||
7. **Audit Trail**: Play-by-play history is complete record
|
||||
|
||||
---
|
||||
|
||||
## Migration Path
|
||||
|
||||
1. Add stat fields to plays table (migration 004)
|
||||
2. Update Play model
|
||||
3. Create PlayStatCalculator
|
||||
4. Modify GameEngine to populate stat fields when recording plays
|
||||
5. Create materialized views (migration 005)
|
||||
6. Create BoxScoreService to query views
|
||||
7. Add refresh logic (after game completion)
|
||||
8. Update terminal client to show box scores
|
||||
|
||||
**Estimated Time**: 4-5 hours (much less than original 6-8 hours!)
|
||||
|
||||
---
|
||||
|
||||
## Questions for Approval
|
||||
|
||||
1. ✅ Approve materialized view approach (vs separate stat tables)?
|
||||
2. ✅ Add stat fields to plays table?
|
||||
3. ✅ Refresh strategy: after game completion + on-demand?
|
||||
4. ✅ Use legacy field names (pa, ab, run, hit) for compatibility?
|
||||
5. ✅ Skip experimental fields (bphr, xba, etc.) for Phase 3.5?
|
||||
|
||||
Once approved, I'll update `phase-3.5-polish-stats.md` with this approach.
|
||||
851
.claude/implementation/phase-3.5-polish-stats.md
Normal file
851
.claude/implementation/phase-3.5-polish-stats.md
Normal file
@ -0,0 +1,851 @@
|
||||
# Phase 3.5: Code Polish & Stat Tracking
|
||||
|
||||
**Duration**: 2-3 days
|
||||
**Status**: Not Started
|
||||
**Prerequisites**: Phase 3 Complete (100% ✅)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Phase 3.5 is a polish and enhancement phase that cleans up technical debt (TODOs), implements game stat tracking, and prepares the codebase for Phase 4 (Spectator & Polish). This phase focuses on production readiness by addressing deferred items and implementing the stat tracking system needed for game history views.
|
||||
|
||||
## Key Objectives
|
||||
|
||||
By end of Phase 3.5, you should have:
|
||||
- ✅ All critical TODOs resolved or documented
|
||||
- ✅ Authorization framework implemented for WebSocket handlers
|
||||
- ✅ Full game stat tracking (box scores, player stats)
|
||||
- ✅ Uncapped hit decision trees implemented
|
||||
- ✅ Code cleanup and refactoring complete
|
||||
- ✅ Integration test infrastructure improved
|
||||
- ✅ 100% test coverage maintained
|
||||
|
||||
---
|
||||
|
||||
## Major Components
|
||||
|
||||
### 1. Game Statistics System (Priority: HIGH)
|
||||
|
||||
**Rationale**: With play resolution complete, stat tracking is a natural next step. Stats are needed for:
|
||||
- Completed games view (PRD requirement)
|
||||
- Box score display (terminal client has placeholder)
|
||||
- League REST API submission (PRD line 297)
|
||||
- Player performance analysis
|
||||
|
||||
**Scope**:
|
||||
|
||||
#### A. Database Models (NEW)
|
||||
**File**: `backend/app/models/db_models.py`
|
||||
|
||||
Add stat tracking tables:
|
||||
```python
|
||||
class GameStats(Base):
|
||||
"""Aggregate game statistics."""
|
||||
__tablename__ = "game_stats"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
game_id = Column(UUID, ForeignKey("games.id"), nullable=False, unique=True)
|
||||
created_at = Column(DateTime, default=func.now())
|
||||
|
||||
# Team stats
|
||||
home_runs = Column(Integer, default=0)
|
||||
away_runs = Column(Integer, default=0)
|
||||
home_hits = Column(Integer, default=0)
|
||||
away_hits = Column(Integer, default=0)
|
||||
home_errors = Column(Integer, default=0)
|
||||
away_errors = Column(Integer, default=0)
|
||||
|
||||
# Linescore (JSON array of inning scores)
|
||||
home_linescore = Column(JSON) # [0, 1, 0, 3, ...]
|
||||
away_linescore = Column(JSON) # [1, 0, 2, 0, ...]
|
||||
|
||||
|
||||
class PlayerGameStats(Base):
|
||||
"""Individual player statistics for a game."""
|
||||
__tablename__ = "player_game_stats"
|
||||
|
||||
id = Column(Integer, primary_key=True)
|
||||
game_id = Column(UUID, ForeignKey("games.id"), nullable=False)
|
||||
lineup_id = Column(Integer, ForeignKey("lineups.id"), nullable=False)
|
||||
card_id = Column(Integer, nullable=False)
|
||||
team_id = Column(Integer, nullable=False)
|
||||
|
||||
# Batting stats
|
||||
plate_appearances = Column(Integer, default=0)
|
||||
at_bats = Column(Integer, default=0)
|
||||
hits = Column(Integer, default=0)
|
||||
doubles = Column(Integer, default=0)
|
||||
triples = Column(Integer, default=0)
|
||||
home_runs = Column(Integer, default=0)
|
||||
rbis = Column(Integer, default=0)
|
||||
walks = Column(Integer, default=0)
|
||||
strikeouts = Column(Integer, default=0)
|
||||
stolen_bases = Column(Integer, default=0)
|
||||
caught_stealing = Column(Integer, default=0)
|
||||
|
||||
# Pitching stats (if pitcher)
|
||||
innings_pitched = Column(Float, default=0.0) # 5.1 = 5 1/3 innings
|
||||
pitches_thrown = Column(Integer, default=0)
|
||||
batters_faced = Column(Integer, default=0)
|
||||
hits_allowed = Column(Integer, default=0)
|
||||
runs_allowed = Column(Integer, default=0)
|
||||
earned_runs = Column(Integer, default=0)
|
||||
walks_allowed = Column(Integer, default=0)
|
||||
strikeouts_pitched = Column(Integer, default=0)
|
||||
home_runs_allowed = Column(Integer, default=0)
|
||||
|
||||
# Fielding stats (future - Phase 4+)
|
||||
putouts = Column(Integer, default=0)
|
||||
assists = Column(Integer, default=0)
|
||||
errors = Column(Integer, default=0)
|
||||
|
||||
__table_args__ = (
|
||||
Index('idx_player_game_stats_game', 'game_id'),
|
||||
Index('idx_player_game_stats_lineup', 'lineup_id'),
|
||||
)
|
||||
```
|
||||
|
||||
#### B. Stat Tracker Service (NEW)
|
||||
**File**: `backend/app/services/stat_tracker.py` (~400 lines)
|
||||
|
||||
```python
|
||||
"""
|
||||
Real-time game statistics tracking service.
|
||||
|
||||
Listens to play outcomes and updates player/game stats in real-time.
|
||||
"""
|
||||
from dataclasses import dataclass
|
||||
from typing import Dict, Optional
|
||||
from app.models.game_models import GameState, PlayResult
|
||||
from app.models.db_models import PlayerGameStats, GameStats
|
||||
from app.database.operations import DatabaseOperations
|
||||
from app.config.play_outcome import PlayOutcome
|
||||
|
||||
class StatTracker:
|
||||
"""
|
||||
Tracks statistics in real-time as plays are resolved.
|
||||
|
||||
Pattern:
|
||||
1. GameEngine resolves play → PlayResult
|
||||
2. StatTracker.record_play(play_result) → update stats
|
||||
3. Async write to database
|
||||
4. Update in-memory cache for quick retrieval
|
||||
"""
|
||||
|
||||
def __init__(self, db_ops: DatabaseOperations):
|
||||
self.db_ops = db_ops
|
||||
self._cache: Dict[UUID, GameStatsCache] = {}
|
||||
|
||||
async def record_play(
|
||||
self,
|
||||
game_id: UUID,
|
||||
play_result: PlayResult,
|
||||
state_before: GameState,
|
||||
state_after: GameState
|
||||
) -> None:
|
||||
"""
|
||||
Record statistics from a completed play.
|
||||
|
||||
Updates both batter and pitcher stats based on outcome.
|
||||
"""
|
||||
# Extract who was involved
|
||||
batter = state_before.current_batter
|
||||
pitcher = state_before.current_pitcher
|
||||
|
||||
# Update batter stats
|
||||
await self._update_batter_stats(
|
||||
game_id=game_id,
|
||||
batter_lineup_id=batter.lineup_id,
|
||||
outcome=play_result.outcome,
|
||||
runs_scored=self._calculate_rbis(state_before, state_after)
|
||||
)
|
||||
|
||||
# Update pitcher stats
|
||||
await self._update_pitcher_stats(
|
||||
game_id=game_id,
|
||||
pitcher_lineup_id=pitcher.lineup_id,
|
||||
outcome=play_result.outcome,
|
||||
runs_allowed=state_after.home_score - state_before.home_score
|
||||
)
|
||||
|
||||
# Update game totals
|
||||
await self._update_game_stats(game_id, state_after)
|
||||
|
||||
async def get_box_score(self, game_id: UUID) -> BoxScore:
|
||||
"""
|
||||
Get complete box score for a game.
|
||||
|
||||
Returns:
|
||||
BoxScore with team totals and player lines
|
||||
"""
|
||||
# Check cache first
|
||||
if game_id in self._cache:
|
||||
return self._cache[game_id].to_box_score()
|
||||
|
||||
# Load from database
|
||||
game_stats = await self.db_ops.get_game_stats(game_id)
|
||||
player_stats = await self.db_ops.get_player_game_stats(game_id)
|
||||
|
||||
return BoxScore(
|
||||
game_stats=game_stats,
|
||||
player_stats=player_stats
|
||||
)
|
||||
|
||||
async def get_player_stats(
|
||||
self,
|
||||
game_id: UUID,
|
||||
lineup_id: int
|
||||
) -> Optional[PlayerGameStats]:
|
||||
"""Get stats for a specific player in a game."""
|
||||
return await self.db_ops.get_player_game_stats_by_lineup(
|
||||
game_id=game_id,
|
||||
lineup_id=lineup_id
|
||||
)
|
||||
|
||||
# Private helper methods
|
||||
def _calculate_rbis(
|
||||
self,
|
||||
before: GameState,
|
||||
after: GameState
|
||||
) -> int:
|
||||
"""Calculate RBIs from state change."""
|
||||
runs_scored = after.home_score - before.home_score
|
||||
# Don't count RBI on errors
|
||||
if after.last_play_had_error:
|
||||
return 0
|
||||
return runs_scored
|
||||
|
||||
def _is_at_bat(self, outcome: PlayOutcome) -> bool:
|
||||
"""Determine if outcome counts as an at-bat (vs plate appearance)."""
|
||||
# Walks, HBP, sacrifice don't count as AB
|
||||
if outcome in [PlayOutcome.WALK, PlayOutcome.HBP]:
|
||||
return False
|
||||
return True
|
||||
|
||||
def _calculate_innings_pitched(self, outs_recorded: int) -> float:
|
||||
"""Convert outs to innings (3 outs = 1.0 inning)."""
|
||||
full_innings = outs_recorded // 3
|
||||
partial_outs = outs_recorded % 3
|
||||
return float(full_innings) + (partial_outs / 10.0)
|
||||
```
|
||||
|
||||
#### C. Database Operations (EXTEND)
|
||||
**File**: `backend/app/database/operations.py`
|
||||
|
||||
Add methods:
|
||||
```python
|
||||
# In DatabaseOperations class
|
||||
|
||||
async def create_game_stats(self, game_id: UUID) -> None:
|
||||
"""Initialize game stats record."""
|
||||
|
||||
async def update_player_batting_stats(
|
||||
self,
|
||||
game_id: UUID,
|
||||
lineup_id: int,
|
||||
**stat_updates
|
||||
) -> None:
|
||||
"""Update batting stats for a player."""
|
||||
|
||||
async def update_player_pitching_stats(
|
||||
self,
|
||||
game_id: UUID,
|
||||
lineup_id: int,
|
||||
**stat_updates
|
||||
) -> None:
|
||||
"""Update pitching stats for a player."""
|
||||
|
||||
async def get_game_stats(self, game_id: UUID) -> Optional[GameStats]:
|
||||
"""Get aggregate game statistics."""
|
||||
|
||||
async def get_player_game_stats(self, game_id: UUID) -> list[PlayerGameStats]:
|
||||
"""Get all player stats for a game."""
|
||||
|
||||
async def get_box_score_data(self, game_id: UUID) -> dict:
|
||||
"""Get formatted box score data for display."""
|
||||
```
|
||||
|
||||
#### D. GameEngine Integration (MODIFY)
|
||||
**File**: `backend/app/core/game_engine.py`
|
||||
|
||||
Integrate stat tracking:
|
||||
```python
|
||||
class GameEngine:
|
||||
def __init__(self, db_ops: DatabaseOperations):
|
||||
self.db_ops = db_ops
|
||||
self.stat_tracker = StatTracker(db_ops) # NEW
|
||||
# ... existing code
|
||||
|
||||
async def resolve_play(
|
||||
self,
|
||||
game_id: UUID,
|
||||
outcome: PlayOutcome
|
||||
) -> PlayResult:
|
||||
"""Resolve play and track stats."""
|
||||
state_before = self.state_manager.get_state(game_id)
|
||||
|
||||
# Existing resolution logic
|
||||
result = await self._resolve_play_internal(game_id, outcome)
|
||||
|
||||
state_after = self.state_manager.get_state(game_id)
|
||||
|
||||
# NEW: Track statistics
|
||||
await self.stat_tracker.record_play(
|
||||
game_id=game_id,
|
||||
play_result=result,
|
||||
state_before=state_before,
|
||||
state_after=state_after
|
||||
)
|
||||
|
||||
return result
|
||||
```
|
||||
|
||||
#### E. Terminal Client Enhancement (MODIFY)
|
||||
**File**: `backend/terminal_client/commands.py`
|
||||
|
||||
Replace placeholder box_score with real implementation:
|
||||
```python
|
||||
async def show_box_score(game_id: UUID, db_ops: DatabaseOperations) -> None:
|
||||
"""Display full box score with player stats."""
|
||||
stat_tracker = StatTracker(db_ops)
|
||||
box_score = await stat_tracker.get_box_score(game_id)
|
||||
|
||||
# Format and display
|
||||
display.print_box_score(box_score)
|
||||
```
|
||||
|
||||
#### F. WebSocket Event (NEW)
|
||||
**File**: `backend/app/websocket/handlers.py`
|
||||
|
||||
Add event to retrieve stats:
|
||||
```python
|
||||
@sio.event
|
||||
async def get_box_score(sid, data):
|
||||
"""
|
||||
Get box score for a game.
|
||||
|
||||
Data:
|
||||
- game_id: UUID
|
||||
|
||||
Returns:
|
||||
- event: 'box_score_data'
|
||||
- data: {game_stats, player_stats, linescore}
|
||||
"""
|
||||
try:
|
||||
game_id = UUID(data['game_id'])
|
||||
|
||||
stat_tracker = StatTracker(db_ops)
|
||||
box_score = await stat_tracker.get_box_score(game_id)
|
||||
|
||||
await sio.emit('box_score_data', {
|
||||
'game_id': str(game_id),
|
||||
'box_score': box_score.to_dict()
|
||||
}, room=sid)
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"Error getting box score: {e}", exc_info=True)
|
||||
await sio.emit('error', {'message': str(e)}, room=sid)
|
||||
```
|
||||
|
||||
**Estimated Time**: 6-8 hours
|
||||
|
||||
**Tests Required**:
|
||||
- Unit tests for StatTracker (~15 tests)
|
||||
- Integration tests for stat updates (5 tests)
|
||||
- Terminal client box_score display test
|
||||
|
||||
---
|
||||
|
||||
### 2. Authorization Framework (Priority: HIGH)
|
||||
|
||||
**Current State**: 15+ TODO comments for authorization checks in WebSocket handlers
|
||||
|
||||
**Goal**: Implement centralized authorization service for WebSocket events
|
||||
|
||||
**Scope**:
|
||||
|
||||
#### A. Authorization Service (NEW)
|
||||
**File**: `backend/app/services/auth_service.py` (~300 lines)
|
||||
|
||||
```python
|
||||
"""
|
||||
Authorization service for WebSocket events.
|
||||
|
||||
Validates that users have permission to perform actions.
|
||||
"""
|
||||
from typing import Optional
|
||||
from uuid import UUID
|
||||
from app.models.db_models import Game, Lineup
|
||||
from app.database.operations import DatabaseOperations
|
||||
|
||||
class AuthorizationError(Exception):
|
||||
"""Raised when user is not authorized."""
|
||||
pass
|
||||
|
||||
class AuthService:
|
||||
"""
|
||||
Centralized authorization for game actions.
|
||||
"""
|
||||
|
||||
def __init__(self, db_ops: DatabaseOperations):
|
||||
self.db_ops = db_ops
|
||||
|
||||
async def verify_game_access(
|
||||
self,
|
||||
user_id: str,
|
||||
game_id: UUID
|
||||
) -> bool:
|
||||
"""
|
||||
Verify user has access to view game.
|
||||
|
||||
Returns True if:
|
||||
- User is a participant (home or away GM)
|
||||
- Game is public and user is logged in
|
||||
- User is a spectator (future)
|
||||
"""
|
||||
game = await self.db_ops.get_game(game_id)
|
||||
if not game:
|
||||
raise AuthorizationError(f"Game {game_id} not found")
|
||||
|
||||
# Check if user is participant
|
||||
if game.home_gm_id == user_id or game.away_gm_id == user_id:
|
||||
return True
|
||||
|
||||
# Check if game is public (spectator access)
|
||||
if game.visibility == 'public':
|
||||
return True
|
||||
|
||||
return False
|
||||
|
||||
async def verify_team_control(
|
||||
self,
|
||||
user_id: str,
|
||||
game_id: UUID,
|
||||
team_id: int
|
||||
) -> bool:
|
||||
"""
|
||||
Verify user controls the specified team.
|
||||
|
||||
Required for: substitutions, defensive decisions
|
||||
"""
|
||||
game = await self.db_ops.get_game(game_id)
|
||||
if not game:
|
||||
raise AuthorizationError(f"Game {game_id} not found")
|
||||
|
||||
# Map team_id to GM
|
||||
if team_id == game.home_team_id:
|
||||
return user_id == game.home_gm_id
|
||||
elif team_id == game.away_team_id:
|
||||
return user_id == game.away_gm_id
|
||||
|
||||
return False
|
||||
|
||||
async def verify_active_batter(
|
||||
self,
|
||||
user_id: str,
|
||||
game_id: UUID
|
||||
) -> bool:
|
||||
"""
|
||||
Verify user is the active batter's GM.
|
||||
|
||||
Required for: offensive decisions, manual outcome submission
|
||||
"""
|
||||
from app.core.state_manager import state_manager
|
||||
|
||||
state = state_manager.get_state(game_id)
|
||||
if not state:
|
||||
raise AuthorizationError(f"Game state not found: {game_id}")
|
||||
|
||||
# Determine which team is batting
|
||||
batting_team_id = (
|
||||
state.away_team_id if state.current_half == 'top'
|
||||
else state.home_team_id
|
||||
)
|
||||
|
||||
return await self.verify_team_control(user_id, game_id, batting_team_id)
|
||||
|
||||
async def verify_game_participant(
|
||||
self,
|
||||
user_id: str,
|
||||
game_id: UUID
|
||||
) -> bool:
|
||||
"""
|
||||
Verify user is a participant (home or away GM).
|
||||
|
||||
Required for: rolling dice, making decisions
|
||||
"""
|
||||
game = await self.db_ops.get_game(game_id)
|
||||
if not game:
|
||||
raise AuthorizationError(f"Game {game_id} not found")
|
||||
|
||||
return user_id in [game.home_gm_id, game.away_gm_id]
|
||||
```
|
||||
|
||||
#### B. WebSocket Handler Integration (MODIFY)
|
||||
**File**: `backend/app/websocket/handlers.py`
|
||||
|
||||
Replace all TODO comments with actual auth checks:
|
||||
|
||||
```python
|
||||
# Example: roll_dice handler
|
||||
@sio.event
|
||||
async def roll_dice(sid, data):
|
||||
"""Roll dice for play resolution."""
|
||||
try:
|
||||
game_id = UUID(data['game_id'])
|
||||
|
||||
# Get user_id from session
|
||||
user_id = await get_user_from_session(sid)
|
||||
|
||||
# REPLACE TODO with actual check
|
||||
if not await auth_service.verify_game_participant(user_id, game_id):
|
||||
await sio.emit('error', {
|
||||
'message': 'Unauthorized: You are not a participant in this game',
|
||||
'code': 'NOT_PARTICIPANT'
|
||||
}, room=sid)
|
||||
return
|
||||
|
||||
# ... rest of handler
|
||||
```
|
||||
|
||||
**Files to Update**:
|
||||
- `backend/app/websocket/handlers.py` - Add auth checks to all handlers
|
||||
- `backend/app/api/routes/auth.py` - Implement session → user_id lookup
|
||||
- `backend/app/websocket/CLAUDE.md` - Update documentation
|
||||
|
||||
**Estimated Time**: 4-5 hours
|
||||
|
||||
**Tests Required**:
|
||||
- Unit tests for AuthService (~12 tests)
|
||||
- Integration tests for WebSocket auth (8 tests)
|
||||
|
||||
---
|
||||
|
||||
### 3. Uncapped Hit Decision Trees (Priority: MEDIUM)
|
||||
|
||||
**Current State**: 2 TODO comments in `play_resolver.py` for uncapped hit logic
|
||||
|
||||
**Goal**: Implement full decision tree for uncapped hits (1B+, 2B+)
|
||||
|
||||
**Reference**: PRD lines on hit location and advancement
|
||||
|
||||
**Scope**:
|
||||
|
||||
#### A. Uncapped Hit Resolution (MODIFY)
|
||||
**File**: `backend/app/core/play_resolver.py`
|
||||
|
||||
Replace TODO placeholders:
|
||||
```python
|
||||
def _resolve_uncapped_single(
|
||||
self,
|
||||
metadata: dict,
|
||||
runners: dict
|
||||
) -> PlayOutcome:
|
||||
"""
|
||||
Resolve 1B+ (uncapped single) using hit location.
|
||||
|
||||
Decision tree:
|
||||
- Hit to LF/CF/RF → runner advancement varies
|
||||
- Hit to IF → different advancement rules
|
||||
"""
|
||||
location = metadata.get('hit_location', 'OF')
|
||||
|
||||
# Implement full decision tree
|
||||
if location in ['LF', 'CF', 'RF']:
|
||||
# Outfield single logic
|
||||
return self._resolve_outfield_single(location, runners)
|
||||
else:
|
||||
# Infield single logic (rare)
|
||||
return PlayOutcome.SINGLE_1
|
||||
|
||||
def _resolve_uncapped_double(
|
||||
self,
|
||||
metadata: dict,
|
||||
runners: dict
|
||||
) -> PlayOutcome:
|
||||
"""
|
||||
Resolve 2B+ (uncapped double) using hit location.
|
||||
|
||||
Decision tree:
|
||||
- Hit down the line → more advancement
|
||||
- Hit to gap → standard advancement
|
||||
"""
|
||||
location = metadata.get('hit_location', 'LF-CF')
|
||||
|
||||
# Implement full decision tree
|
||||
# ...
|
||||
```
|
||||
|
||||
**Estimated Time**: 3-4 hours
|
||||
|
||||
**Tests Required**:
|
||||
- Unit tests for uncapped hit logic (~8 tests)
|
||||
|
||||
---
|
||||
|
||||
### 4. Code Cleanup & Refactoring (Priority: MEDIUM)
|
||||
|
||||
**Goal**: Remove obsolete code, clean up config fields, implement deferred features
|
||||
|
||||
**Scope**:
|
||||
|
||||
#### A. Config Field Cleanup (MODIFY)
|
||||
**File**: `backend/app/config/base_config.py`
|
||||
|
||||
Remove marked TODO fields:
|
||||
```python
|
||||
# REMOVE these fields (not used, basic baseball rules)
|
||||
strikes_for_out: int = Field(default=3) # TODO: remove - unneeded
|
||||
balls_for_walk: int = Field(default=4) # TODO: remove - unneeded
|
||||
```
|
||||
|
||||
**Rationale**: These are hardcoded in rule logic and don't vary by league
|
||||
|
||||
#### B. Batter Handedness Integration (MODIFY)
|
||||
**File**: `backend/app/core/play_resolver.py`
|
||||
|
||||
Replace hardcoded handedness:
|
||||
```python
|
||||
# Currently:
|
||||
batter_handedness = 'R' # TODO: player model
|
||||
|
||||
# Change to:
|
||||
batter_handedness = batter.handedness # From player model
|
||||
```
|
||||
|
||||
**Dependency**: Requires `handedness` field on player models
|
||||
|
||||
#### C. SPD Test Implementation (MODIFY)
|
||||
**File**: `backend/app/core/x_check_advancement_tables.py`
|
||||
|
||||
Implement actual SPD test instead of default fail:
|
||||
```python
|
||||
# Currently:
|
||||
def _run_speed_test(batter_speed: int) -> bool:
|
||||
"""Test if batter has enough speed."""
|
||||
# TODO: batter speed rating
|
||||
return False # Default to G3 fail
|
||||
|
||||
# Change to:
|
||||
def _run_speed_test(batter_speed: int) -> bool:
|
||||
"""
|
||||
Test if batter beats throw.
|
||||
|
||||
Speed ratings: 1-20 (1=slow, 20=fast)
|
||||
Threshold: 11+ = beats throw
|
||||
"""
|
||||
return batter_speed >= 11
|
||||
```
|
||||
|
||||
#### D. Relief Pitcher (RP) Logic in X-Check (MODIFY)
|
||||
**File**: `backend/app/core/x_check_advancement_tables.py`
|
||||
|
||||
Replace placeholder RP logic:
|
||||
```python
|
||||
# Currently uses E1 as placeholder for RP position
|
||||
'RP': 1, # TODO: Actual RP logic (using E1 for now)
|
||||
|
||||
# Implement proper RP fielding position
|
||||
# RP should use pitcher (1) fielding tables
|
||||
```
|
||||
|
||||
**Estimated Time**: 2-3 hours total for all cleanup
|
||||
|
||||
**Tests Required**:
|
||||
- Update existing tests for config changes
|
||||
- Add tests for handedness integration
|
||||
- Add tests for SPD test logic
|
||||
|
||||
---
|
||||
|
||||
### 5. Integration Test Infrastructure (Priority: LOW)
|
||||
|
||||
**Current State**: TODO in `tests/CLAUDE.md` for integration test refactor
|
||||
|
||||
**Goal**: Improve integration test reliability and database session handling
|
||||
|
||||
**Scope**:
|
||||
|
||||
#### A. Test Database Fixtures (IMPROVE)
|
||||
**File**: `backend/tests/conftest.py`
|
||||
|
||||
Add better fixtures for integration tests:
|
||||
```python
|
||||
@pytest.fixture
|
||||
async def test_game_with_stats(db_session):
|
||||
"""Create a test game with pre-populated stats."""
|
||||
# Useful for stat tracker tests
|
||||
pass
|
||||
|
||||
@pytest.fixture
|
||||
async def test_game_with_substitutions(db_session):
|
||||
"""Create a test game with substitution history."""
|
||||
# Useful for lineup tests
|
||||
pass
|
||||
```
|
||||
|
||||
#### B. Async Session Management (IMPROVE)
|
||||
**File**: `backend/tests/integration/conftest.py`
|
||||
|
||||
Better async session handling to avoid connection pool issues
|
||||
|
||||
**Estimated Time**: 2-3 hours
|
||||
|
||||
---
|
||||
|
||||
## Implementation Order
|
||||
|
||||
### Week 1 (Days 1-2): Stats & Auth
|
||||
1. **Day 1 Morning**: Stat database models + migration
|
||||
2. **Day 1 Afternoon**: StatTracker service implementation
|
||||
3. **Day 2 Morning**: AuthService implementation
|
||||
4. **Day 2 Afternoon**: WebSocket auth integration
|
||||
|
||||
### Week 2 (Day 3): Cleanup & Testing
|
||||
5. **Day 3 Morning**: Uncapped hit logic + code cleanup
|
||||
6. **Day 3 Afternoon**: Testing & documentation
|
||||
|
||||
---
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Unit Tests
|
||||
- StatTracker: 15 tests (stat calculation, caching, RBI logic)
|
||||
- AuthService: 12 tests (all authorization paths)
|
||||
- Uncapped hits: 8 tests (decision tree coverage)
|
||||
- **Target**: 35+ new tests
|
||||
|
||||
### Integration Tests
|
||||
- Stat tracking end-to-end: 5 tests
|
||||
- WebSocket auth checks: 8 tests
|
||||
- Box score retrieval: 3 tests
|
||||
- **Target**: 16+ new tests
|
||||
|
||||
### Manual Testing
|
||||
- Terminal client box_score command
|
||||
- Play full game and verify stats
|
||||
- Test auth rejections with different users
|
||||
|
||||
---
|
||||
|
||||
## Database Migration
|
||||
|
||||
**Migration File**: `backend/alembic/versions/004_add_game_stats.py`
|
||||
|
||||
```python
|
||||
"""Add game statistics tables.
|
||||
|
||||
Revision ID: 004
|
||||
Revises: 003
|
||||
Create Date: 2025-11-06
|
||||
"""
|
||||
|
||||
def upgrade():
|
||||
# Create game_stats table
|
||||
op.create_table(
|
||||
'game_stats',
|
||||
sa.Column('id', sa.Integer(), primary_key=True),
|
||||
sa.Column('game_id', sa.UUID(), nullable=False, unique=True),
|
||||
# ... all stat columns
|
||||
)
|
||||
|
||||
# Create player_game_stats table
|
||||
op.create_table(
|
||||
'player_game_stats',
|
||||
sa.Column('id', sa.Integer(), primary_key=True),
|
||||
sa.Column('game_id', sa.UUID(), nullable=False),
|
||||
# ... all stat columns
|
||||
)
|
||||
|
||||
# Create indexes
|
||||
op.create_index('idx_player_game_stats_game', 'player_game_stats', ['game_id'])
|
||||
|
||||
def downgrade():
|
||||
op.drop_table('player_game_stats')
|
||||
op.drop_table('game_stats')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
**Phase 3.5 Complete** when:
|
||||
- ✅ Full box score available for any game
|
||||
- ✅ All WebSocket handlers have auth checks (zero TODO comments)
|
||||
- ✅ Uncapped hit decision trees implemented
|
||||
- ✅ Code cleanup complete (config fields removed, handedness integrated)
|
||||
- ✅ 720+ total tests passing (688 + 35+ new tests)
|
||||
- ✅ All integration tests reliable and passing
|
||||
- ✅ Documentation updated
|
||||
|
||||
---
|
||||
|
||||
## Deliverable
|
||||
|
||||
A production-ready codebase with:
|
||||
- Complete game statistics system
|
||||
- Robust authorization framework
|
||||
- All Phase 3 TODOs resolved
|
||||
- Enhanced code quality and test coverage
|
||||
- Ready for Phase 4 (Spectator & Polish)
|
||||
|
||||
---
|
||||
|
||||
## Files to Create/Modify
|
||||
|
||||
### New Files (4):
|
||||
1. `backend/app/services/stat_tracker.py` (~400 lines)
|
||||
2. `backend/app/services/auth_service.py` (~300 lines)
|
||||
3. `backend/alembic/versions/004_add_game_stats.py` (~100 lines)
|
||||
4. `backend/tests/unit/services/test_stat_tracker.py` (~250 lines)
|
||||
|
||||
### Modified Files (8):
|
||||
1. `backend/app/models/db_models.py` (+150 lines - stat tables)
|
||||
2. `backend/app/database/operations.py` (+120 lines - stat operations)
|
||||
3. `backend/app/core/game_engine.py` (+30 lines - stat integration)
|
||||
4. `backend/app/core/play_resolver.py` (+80 lines - uncapped hits, handedness)
|
||||
5. `backend/app/core/x_check_advancement_tables.py` (+40 lines - SPD, RP logic)
|
||||
6. `backend/app/config/base_config.py` (-5 lines - remove unused fields)
|
||||
7. `backend/app/websocket/handlers.py` (+150 lines - auth checks)
|
||||
8. `backend/terminal_client/commands.py` (+50 lines - real box_score)
|
||||
|
||||
### Test Files (5):
|
||||
1. `backend/tests/unit/services/test_stat_tracker.py` (NEW - 15 tests)
|
||||
2. `backend/tests/unit/services/test_auth_service.py` (NEW - 12 tests)
|
||||
3. `backend/tests/integration/test_stat_tracking.py` (NEW - 5 tests)
|
||||
4. `backend/tests/integration/test_websocket_auth.py` (NEW - 8 tests)
|
||||
5. `backend/tests/unit/core/test_play_resolver.py` (MODIFY - +8 tests)
|
||||
|
||||
**Total Lines of Code**: ~1,400 new lines + ~500 modified lines
|
||||
|
||||
---
|
||||
|
||||
## Blockers & Risks
|
||||
|
||||
### Potential Blockers
|
||||
1. **Player Model Handedness**: Need to add `handedness` field to player models
|
||||
2. **User Session Management**: Need Discord OAuth user_id from WebSocket sessions
|
||||
3. **Database Migration**: Need to run migration on existing games
|
||||
|
||||
### Mitigation
|
||||
1. Add handedness to SbaPlayer/PdPlayer models (quick fix)
|
||||
2. Implement basic session store (Redis or in-memory for MVP)
|
||||
3. Migration only adds new tables, doesn't modify existing data
|
||||
|
||||
---
|
||||
|
||||
## Next Phase
|
||||
|
||||
After Phase 3.5 completion → **Phase 4: Spectator Mode & Polish**
|
||||
- Spectator view implementation
|
||||
- UI/UX refinements
|
||||
- Performance optimization
|
||||
- Accessibility improvements
|
||||
|
||||
---
|
||||
|
||||
**Status**: Not Started
|
||||
**Estimated Duration**: 2-3 days (16-24 hours of work)
|
||||
**Priority**: High (production readiness)
|
||||
**Blocking**: No (can proceed to Phase 4 in parallel if needed)
|
||||
Loading…
Reference in New Issue
Block a user