diff --git a/CLAUDE.md b/CLAUDE.md index 612a9b9..2761f11 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -111,11 +111,27 @@ When migrating code from `../discord-app/`: - Logging with rotating handlers implemented - Virtual environment and core dependencies installed -**Phase 2: Core Game Services** 🚧 NEXT -- Extract business logic from `../discord-app/command_logic/logic_gameplay.py` -- Implement GameService, GameplayService, AIService -- Migrate core gameplay models from Discord app -- Add comprehensive service unit tests +**Phase 2: Core Game Services** ✅ COMPLETE +- ✅ AIService fully implemented (369 lines, 72% test coverage) + - Complete steal opportunity decision logic + - Defensive alignment and positioning + - Tag-up and runner advance decisions + - Pitcher replacement logic +- ✅ PlayerService fully implemented (53 lines, 100% test coverage) + - Player data management and formatting + - Name handling with descriptions +- ✅ UIService implemented (18 lines, 83% test coverage) + - User interface helper functions +- ✅ Core gameplay models migrated: Player, Team, Cardset, ManagerAi, PositionRating +- ✅ Comprehensive test suite: 206 tests (65% overall coverage) + - 51 AI Service tests (unit + integration) + - Robust integration testing with real database queries + +**Phase 3: Game Engine & Routes** 🚧 NEXT +- Implement game simulation engine and gameplay mechanics +- Create FastAPI routes and controllers for web interface +- Add authentication and session management +- Integrate services with HTTP endpoints ## Key Files and Patterns @@ -139,6 +155,67 @@ When migrating code from `../discord-app/`: - Console and file output with structured formatting - Service-specific logger naming patterns +## Implemented Services + +### AIService (`app/services/ai_service.py`) +**Status**: ✅ Complete (369 lines, 72% test coverage, 51 tests) + +Core AI decision-making for baseball gameplay mechanics: +- **Steal Opportunities**: `check_steal_opportunity()` - Complex conditional logic for steal decisions to 2nd, 3rd, and home +- **Defensive Alignment**: `set_defensive_alignment()` - Hold runners, infield positioning based on game state +- **Tag Decisions**: `check_tag_from_second()`, `check_tag_from_third()` - Fly ball tag-up logic +- **Runner Advances**: `decide_runner_advance()` - Uncapped situation running decisions +- **Pitcher Management**: `should_replace_pitcher()` - Fatigue and situational pitcher replacement +- **Groundball Decisions**: `decide_groundball_running()`, `decide_groundball_throw()` - Fielding choices + +**Key Features**: +- Real database queries for defensive ratings +- Complex aggression calculations based on game state +- Comprehensive bounds checking and error handling +- Migrated from Discord app with full business logic preservation + +### PlayerService (`app/services/player_service.py`) +**Status**: ✅ Complete (53 lines, 100% test coverage) + +Player data management and formatting: +- **Player Creation**: Database-backed player instantiation +- **Name Formatting**: `get_formatted_name_with_description()` - Consistent player name display +- **Data Validation**: Proper player attribute handling + +### UIService (`app/services/ui_service.py`) +**Status**: ✅ Complete (18 lines, 83% test coverage) + +User interface helper functions: +- **Formatting Utilities**: Display helpers for web interface +- **Data Presentation**: Consistent UI data formatting + +### Base Service (`app/services/base_service.py`) +**Status**: ✅ Complete (19 lines, 84% test coverage) + +Abstract foundation for all services: +- **Session Management**: SQLModel database session handling +- **Logging**: Standardized `f'{__name__}.{self.__class__.__name__}'` format +- **Operation Tracking**: `_log_operation()` and `_log_error()` methods +- **Dependency Injection**: Constructor-based session injection + +## Implemented Models + +### Core Models (`app/models/`) +- **Player** (`player.py`): Complete player data model with positions relationship +- **Team** (`team.py`): Team management with MLB club associations +- **Cardset** (`cardset.py`): Card set definitions and metadata +- **ManagerAi** (`manager_ai.py`): AI personality and aggression settings +- **PositionRating** (`position_rating.py`): Defensive ratings by position and variant + +### AI Response Models (`app/models/ai_responses.py`) +Structured response objects for AI decisions: +- `JumpResponse`: Steal opportunity decisions with safety thresholds +- `TagResponse`: Tag-up decisions with minimum safe values +- `ThrowResponse`: Fielding throw target decisions +- `UncappedRunResponse`: Advanced base running decisions +- `DefenseResponse`: Defensive alignment and hold decisions +- `RunResponse`: Basic running decisions + ## Testing Strategy **🚨 CRITICAL: All tests must follow test isolation guidelines to prevent data persistence issues.** @@ -176,17 +253,35 @@ def test_create_team(session): - `tests/factories/README.md` - Factory pattern documentation - `tests/TEST_ISOLATION_GUIDE.md` - Comprehensive isolation best practices +### Current Test Coverage Status +- **Total Tests**: 206 tests across all suites +- **Overall Coverage**: 65% (804 statements, 285 missed) +- **Service Coverage**: + - AIService: 72% (369 lines, 51 tests - unit + integration) + - PlayerService: 100% (53 lines, comprehensive coverage) + - UIService: 83% (18 lines) + - BaseService: 84% (19 lines) + ### Unit Tests (`tests/unit/`) -- **Services**: Test business logic with mocked database sessions -- **Engine**: Test stateless game simulation functions +- **Services**: Test business logic with mocked dependencies + - AIService: 22 unit tests covering core decision logic + - PlayerService: Comprehensive unit test coverage + - UIService: Basic functionality testing - **Models**: Test data validation and relationships using `db_session` + factories + - Player, Team, Cardset, ManagerAi, PositionRating models +- **Engine**: Reserved for stateless game simulation functions ### Integration Tests (`tests/integration/`) +- **AIService Integration**: 29 focused integration tests + - Real database queries for defensive ratings + - Complex conditional branch coverage + - Error handling with actual data constraints + - Cross-service interaction testing - Service interactions with real database (isolated transactions) -- Authentication flows and session management - Must use `db_session` fixture and factory classes ### End-to-End Tests (`tests/e2e/`) +- **Status**: 🚧 Reserved for future web interface testing - Complete user journeys through web interface - Game creation and gameplay flows - Use factory classes for any test data setup