8e543de2b2
2 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
Cal Corum
|
e147ab17f1 |
CLAUDE: Phase 3F - Substitution System WebSocket Events
Implemented complete WebSocket integration for real-time player substitutions.
System is now 80% complete - only tests remain.
## WebSocket Events Implemented (600 lines)
### Event Handlers (backend/app/websocket/handlers.py):
1. request_pinch_hitter - Pinch hitter substitution
- Validates: game_id, player_out_lineup_id, player_in_card_id, team_id
- Executes: SubstitutionManager.pinch_hit()
- Broadcasts: player_substituted (all clients), substitution_confirmed (requester)
- Error codes: MISSING_FIELD, INVALID_FORMAT, NOT_CURRENT_BATTER, etc.
2. request_defensive_replacement - Defensive replacement
- Additional field: new_position (P, C, 1B, 2B, 3B, SS, LF, CF, RF)
- Executes: SubstitutionManager.defensive_replace()
- Same broadcast pattern as pinch hitter
3. request_pitching_change - Pitching change
- Validates minimum batters faced (handled in SubstitutionManager)
- Executes: SubstitutionManager.change_pitcher()
- Broadcasts new pitcher to all clients
4. get_lineup - Get active lineup for team
- Returns: lineup_data with all active players
- Uses: StateManager cache (O(1)) or database fallback
- Purpose: UI refresh after substitutions
### Event Pattern (follows existing handlers):
- Validate inputs (UUID format, required fields, game exists)
- Create SubstitutionManager instance with DatabaseOperations
- Execute substitution (validate → DB → state)
- Broadcast player_substituted to game room
- Send substitution_confirmed to requester
- Error handling with specific error codes
### Events Emitted:
- player_substituted (broadcast) - Includes: type, lineup IDs, position, batting_order
- substitution_confirmed (requester) - Success confirmation with new_lineup_id
- substitution_error (requester) - Validation error with error code
- lineup_data (requester) - Active lineup response
- error (requester) - Generic error
## Documentation Updates (350 lines)
### backend/app/websocket/CLAUDE.md:
- Complete handler documentation with examples
- Event data structures and response formats
- Error code reference (MISSING_FIELD, INVALID_FORMAT, NOT_CURRENT_BATTER, etc.)
- Client integration examples (JavaScript)
- Complete workflow diagrams
- Updated event summary table (+8 events)
- Updated Common Imports section
### .claude/implementation/ updates:
- NEXT_SESSION.md: Marked Task 1 complete, updated to 80% done
- SUBSTITUTION_SYSTEM_SUMMARY.md: Added WebSocket section, updated status
- GAMESTATE_REFACTOR_PLAN.md: Marked complete
- PHASE_3_OVERVIEW.md: Updated all phases to reflect completion
- phase-3e-COMPLETED.md: Created comprehensive completion doc
## Architecture
### DB-First Pattern (maintained):
```
Client Request → WebSocket Handler
↓
SubstitutionManager
├─ SubstitutionRules.validate_*()
├─ DatabaseOperations.create_substitution() (DB first!)
├─ StateManager.update_lineup_cache()
└─ Update GameState if applicable
↓
Success Responses
├─ player_substituted (broadcast to room)
└─ substitution_confirmed (to requester)
```
### Error Handling:
- Three-tier: ValidationError, GameValidationError, Exception
- Specific error codes for each failure type
- User-friendly error messages
- Comprehensive logging at each step
## Status Update
**Phase 3F Substitution System**: 80% Complete
- ✅ Core logic (SubstitutionRules, SubstitutionManager) - 1,027 lines
- ✅ Database operations (create_substitution, get_eligible_substitutes)
- ✅ WebSocket events (4 handlers) - 600 lines
- ✅ Documentation (350 lines)
- ⏳ Unit tests (20% remaining) - ~300 lines needed
- ⏳ Integration tests - ~400 lines needed
**Phase 3 Overall**: ~97% Complete
- Phase 3A-D (X-Check Core): 100%
- Phase 3E (GameState, Ratings, Redis, Testing): 100%
- Phase 3F (Substitutions): 80%
## Files Modified
backend/app/websocket/handlers.py (+600 lines)
backend/app/websocket/CLAUDE.md (+350 lines)
.claude/implementation/NEXT_SESSION.md (updated progress)
.claude/implementation/SUBSTITUTION_SYSTEM_SUMMARY.md (added WebSocket section)
.claude/implementation/GAMESTATE_REFACTOR_PLAN.md (marked complete)
.claude/implementation/PHASE_3_OVERVIEW.md (updated all phases)
.claude/implementation/phase-3e-COMPLETED.md (new file, 400+ lines)
## Next Steps
Remaining work (2-3 hours):
1. Unit tests for SubstitutionRules (~300 lines)
- 15+ pinch hitter tests
- 12+ defensive replacement tests
- 10+ pitching change tests
2. Integration tests for SubstitutionManager (~400 lines)
- Full DB + state sync flow
- State recovery verification
- Error handling and rollback
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
|
||
|
Cal Corum
|
76e24ab22b |
CLAUDE: Refactor ManualOutcomeSubmission to use PlayOutcome enum + comprehensive documentation
## Refactoring - Changed `ManualOutcomeSubmission.outcome` from `str` to `PlayOutcome` enum type - Removed custom validator (Pydantic handles enum validation automatically) - Added direct import of PlayOutcome (no circular dependency due to TYPE_CHECKING guard) - Updated tests to use enum values while maintaining backward compatibility Benefits: - Better type safety with IDE autocomplete - Cleaner code (removed 15 lines of validator boilerplate) - Backward compatible (Pydantic auto-converts strings to enum) - Access to helper methods (is_hit(), is_out(), etc.) Files modified: - app/models/game_models.py: Enum type + import - tests/unit/config/test_result_charts.py: Updated 7 tests + added compatibility test ## Documentation Created comprehensive CLAUDE.md files for all backend/app/ subdirectories to help future AI agents quickly understand and work with the code. Added 8,799 lines of documentation covering: - api/ (906 lines): FastAPI routes, health checks, auth patterns - config/ (906 lines): League configs, PlayOutcome enum, result charts - core/ (1,288 lines): GameEngine, StateManager, PlayResolver, dice system - data/ (937 lines): API clients (planned), caching layer - database/ (945 lines): Async sessions, operations, recovery - models/ (1,270 lines): Pydantic/SQLAlchemy models, polymorphic patterns - utils/ (959 lines): Logging, JWT auth, security - websocket/ (1,588 lines): Socket.io handlers, real-time events - tests/ (475 lines): Testing patterns and structure Each CLAUDE.md includes: - Purpose & architecture overview - Key components with detailed explanations - Patterns & conventions - Integration points - Common tasks (step-by-step guides) - Troubleshooting with solutions - Working code examples - Testing guidance Total changes: +9,294 lines / -24 lines Tests: All passing (62/62 model tests, 7/7 ManualOutcomeSubmission tests) |