major-domo-v2/commands/league/README.md

# League Commands

This directory contains Discord slash commands related to league-wide information and statistics.

## Files

### `info.py`
- **Command**: `/league`
- **Description**: Display current league status and information
- **Functionality**: Shows current season/week, phase (regular season/playoffs/offseason), transaction status, trade deadlines, and league configuration
- **Service Dependencies**: `league_service.get_current_state()`
- **Key Features**:
  - Dynamic phase detection (offseason, playoffs, regular season)
  - Transaction freeze status
  - Trade deadline and playoff schedule information
  - Draft pick trading status

### `standings.py`
- **Commands**:
  - `/standings` - Display league standings by division
  - `/playoff-picture` - Show current playoff picture and wild card race
- **Parameters**:
  - `season`: Optional season number (defaults to current)
  - `division`: Optional division filter for standings
- **Service Dependencies**: `standings_service`
- **Key Features**:
  - Division-based standings display
  - Games behind calculations
  - Recent form statistics (home record, last 8 games, current streak)
  - Playoff cutoff visualization
  - Wild card race tracking

### `schedule.py`
- **Commands**:
  - `/schedule` - Display game schedules
  - `/results` - Show recent game results
- **Parameters**:
  - `season`: Optional season number (defaults to current)
  - `week`: Optional specific week filter
  - `team`: Optional team abbreviation filter
- **Service Dependencies**: `schedule_service`
- **Key Features**:
  - Weekly schedule views
  - Team-specific schedule filtering
  - Series grouping and summary
  - Recent/upcoming game overview
  - Game completion tracking

### `submit_scorecard.py`
- **Command**: `/submit-scorecard`
- **Description**: Submit Google Sheets scorecards with game results and play-by-play data
- **Parameters**:
  - `sheet_url`: Full URL to the Google Sheets scorecard
- **Required Role**: `Season 12 Players`
- **Service Dependencies**:
  - `SheetsService` - Google Sheets data extraction
  - `game_service` - Game CRUD operations
  - `play_service` - Play-by-play data management
  - `decision_service` - Pitching decision management
  - `standings_service` - Standings recalculation
  - `league_service` - Current state retrieval
  - `team_service` - Team lookup
  - `player_service` - Player lookup for results display
- **Key Features**:
  - **Scorecard Validation**: Checks sheet access and version compatibility
  - **Permission Control**: Only GMs of playing teams can submit
  - **Duplicate Detection**: Identifies already-played games with confirmation dialog
  - **Transaction Rollback**: Full rollback support at 3 states:
    - `PLAYS_POSTED`: Deletes plays on error
    - `GAME_PATCHED`: Wipes game and deletes plays on error
    - `COMPLETE`: All data committed successfully
  - **Data Extraction**: Reads 68 fields from Playtable, 14 fields from Pitcherstats, box score, and game metadata
  - **Results Display**: Rich embed with box score, pitching decisions, and top 3 key plays by WPA
  - **Automated Standings**: Triggers standings recalculation after successful submission
  - **News Channel Posting**: Automatically posts results to configured channel

**Workflow (14 Phases)**:
1. Validate scorecard access and version
2. Extract game metadata from Setup tab
3. Lookup teams and match managers
4. Check user permissions (must be GM of one team or bot owner)
5. Check for duplicate games (with confirmation if found)
6. Find scheduled game in database
7. Read play-by-play data (up to 297 plays)
8. Submit plays to database
9. Read box score
10. Update game with scores and managers
11. Read pitching decisions (up to 27 pitchers)
12. Submit decisions to database
13. Create and post results embed to news channel
14. Recalculate league standings

**Error Handling**:
- User-friendly error messages for common issues
- Graceful rollback on validation errors
- API error parsing for actionable feedback
- Non-critical errors (key plays, standings) don't fail submission

**Configuration**:
- `sheets_credentials_path` (in config.py): Path to Google service account credentials JSON (set via `SHEETS_CREDENTIALS_PATH` env var)
- `SBA_NETWORK_NEWS_CHANNEL`: Channel name for results posting
- `SBA_PLAYERS_ROLE_NAME`: Role required to submit scorecards

## Architecture Notes

### Decorator Usage
All commands use the `@logged_command` decorator pattern:
- Eliminates boilerplate logging code
- Provides consistent error handling
- Automatic request tracing and timing

### Error Handling
- Graceful fallbacks for missing data
- User-friendly error messages
- Ephemeral responses for errors

### Embed Structure
- Uses `EmbedTemplate` for consistent styling
- Color coding based on context (success/error/info)
- Rich formatting with team logos and thumbnails

## Troubleshooting

### Common Issues

1. **No league data available**: Check `league_service.get_current_state()` API endpoint
2. **Standings not loading**: Verify `standings_service.get_standings_by_division()` returns valid data
3. **Schedule commands failing**: Ensure `schedule_service` methods are properly handling season/week parameters

### Dependencies
- `services.league_service`
- `services.standings_service`
- `services.schedule_service`
- `services.sheets_service` (NEW) - Google Sheets integration
- `services.game_service` (NEW) - Game management
- `services.play_service` (NEW) - Play-by-play data
- `services.decision_service` (NEW) - Pitching decisions
- `services.team_service`
- `services.player_service`
- `utils.decorators.logged_command`
- `utils.discord_helpers` (NEW) - Channel and message utilities
- `utils.team_utils`
- `views.embeds.EmbedTemplate`
- `views.confirmations.ConfirmationView` (NEW) - Reusable confirmation dialog
- `constants.SBA_CURRENT_SEASON`
- `config.BotConfig.sheets_credentials_path` (NEW) - Google Sheets credentials path
- `constants.SBA_NETWORK_NEWS_CHANNEL` (NEW)
- `constants.SBA_PLAYERS_ROLE_NAME` (NEW)

### Testing
Run tests with: `python -m pytest tests/test_commands_league.py -v`