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

Transaction Commands

This directory contains Discord slash commands for transaction management and roster legality checking.

Files

management.py

• Commands:
  • /mymoves - View user's pending and scheduled transactions
  • /legal - Check roster legality for current and next week
• Service Dependencies:
  • transaction_service (multiple methods for transaction retrieval)
  • roster_service (roster validation and retrieval)
  • team_service.get_teams_by_owner() and get_team_by_abbrev()

dropadd.py

• Commands:
  • /dropadd - Interactive transaction builder for single-team roster moves
  • /cleartransaction - Clear current transaction builder
• Service Dependencies:
  • transaction_builder (transaction creation and validation)
  • player_service.search_players() (player autocomplete)
  • team_service.get_teams_by_owner()

trade.py (NEW)

• Commands:
  • /trade initiate - Start a new multi-team trade
  • /trade add-team - Add additional teams to trade (3+ team trades)
  • /trade add-player - Add player exchanges between teams
  • /trade supplementary - Add internal organizational moves for roster legality
  • /trade view - View current trade status
  • /trade clear - Clear current trade
• Service Dependencies:
  • trade_builder (multi-team trade management)
  • player_service.search_players() (player autocomplete)
  • team_service.get_teams_by_owner(), get_team_by_abbrev(), and get_team()
• Channel Management:
  • Automatically creates private discussion channels for trades
  • Uses TradeChannelManager and TradeChannelTracker for channel lifecycle
  • Requires bot to have Manage Channels permission at server level

Key Features

Transaction Status Display (/mymoves)

• User Team Detection: Automatically finds user's team by Discord ID
• Transaction Categories:
  • Pending: Transactions awaiting processing
  • Frozen: Scheduled transactions ready for processing
  • Processed: Recently completed transactions
  • Cancelled: Optional display of cancelled transactions
• Status Visualization:
  • Status emojis for each transaction type
  • Week numbering and move descriptions
  • Transaction count summaries
• Smart Limiting: Shows recent transactions (last 5 pending, 3 frozen/processed, 2 cancelled)

Roster Legality Checking (/legal)

• Dual Roster Validation: Checks both current and next week rosters
• Flexible Team Selection:
  • Auto-detects user's team
  • Allows manual team specification via abbreviation
• Comprehensive Validation:
  • Player count verification (active roster + IL)
  • sWAR calculations and limits
  • League rule compliance checking
  • Error and warning categorization
• Parallel Processing: Roster retrieval and validation run concurrently

Multi-Team Trade System (/trade) (NEW)

• Trade Initiation: Start trades between multiple teams using proper Discord command groups
• Team Management: Add/remove teams to create complex multi-team trades (2+ teams supported)
• Player Exchanges: Add cross-team player movements with source and destination validation
• Supplementary Moves: Add internal organizational moves for roster legality compliance
• Interactive UI: Rich Discord embeds with validation feedback and trade status
• Real-time Validation: Live roster checking across all participating teams
• Authority Model: Major League team owners control all players in their organization (ML/MiL/IL)

Trade Command Workflow:

1. /trade initiate other_team:LAA - Start trade between your team and LAA
   • Creates a private discussion channel for the trade
   • Only you see the ephemeral response
2. /trade add-team other_team:BOS - Add BOS for 3-team trade
   • Updates are posted to the trade channel if executed elsewhere
   • Other team members can see the progress
3. /trade add-player player_name:"Mike Trout" destination_team:BOS - Exchange players
   • Trade embed updates posted to dedicated channel automatically
   • Keeps all participants informed of changes
4. /trade supplementary player_name:"Player X" destination:ml - Internal roster moves
   • Channel receives real-time updates
5. /trade view - Review complete trade with validation
   • Posts current state to trade channel if viewed elsewhere
6. Submit via interactive UI - Trade submission through Discord buttons

Channel Behavior:

• Commands executed in the trade channel: Only ephemeral response to user
• Commands executed outside trade channel: Ephemeral response to user + public post to trade channel
• This ensures all participating teams stay informed of trade progress

Autocomplete System:

• Team Initiation: Only Major League teams (ML team owners initiate trades)
• Player Destinations: All roster types (ML/MiL/IL) available for player placement
• Player Search: Prioritizes user's team players, supports fuzzy name matching
• Smart Filtering: Context-aware suggestions based on user permissions

Trade Channel Management (trade_channels.py, trade_channel_tracker.py):

• Automatic Channel Creation: Private discussion channels created when trades are initiated
• Channel Naming: Format trade-{team1}-{team2}-{short_id} (e.g., trade-wv-por-681f)
• Permission Management:
  • Channel hidden from @everyone
  • Only participating team roles can view/message
  • Bot has view and send message permissions
  • Created in "Transactions" category (if it exists)
• Channel Tracking: JSON-based persistence for cleanup and management
• Multi-Team Support: Channels automatically update when teams are added to trades
• Automatic Cleanup: Channels deleted when trades are cleared
• Smart Updates: When trade commands are executed outside the dedicated trade channel, the trade embed is automatically posted to the trade channel (non-ephemeral) for visibility

Bot Permission Requirements:

• Server-level Manage Channels - Required to create/delete trade channels
• Server-level Manage Permissions - Optional, for enhanced permission management
• Note: Bot should NOT have these permissions in channel-specific overwrites (causes Discord API error 50013)

Recent Fix (January 2025):

• Removed manage_channels and manage_permissions from bot's channel-specific overwrites
• Discord prohibits bots from granting themselves elevated permissions in channel overwrites
• Server-level permissions are sufficient for all channel management operations

Advanced Transaction Features

• Concurrent Data Fetching: Multiple transaction types retrieved in parallel
• Owner-Based Filtering: Transactions filtered by team ownership
• Status Tracking: Real-time transaction status with emoji indicators
• Team Integration: Team logos and colors in transaction displays

Architecture Notes

Permission Model

• Team Ownership: Commands use Discord user ID to determine team ownership
• Cross-Team Viewing: /legal allows checking other teams' roster status
• Access Control: Users can only view their own transactions via /mymoves

Data Processing

• Async Operations: Heavy use of asyncio.gather() for performance
• Error Resilience: Graceful handling of missing roster data
• Validation Pipeline: Multi-step roster validation with detailed feedback

Embed Structure

• Status-Based Coloring: Success (green) vs Error (red) color coding
• Information Hierarchy: Important information prioritized in embed layout
• Team Branding: Consistent use of team thumbnails and colors

Troubleshooting

Common Issues

1. User team not found:

   • Verify user has team ownership record in database
   • Check Discord user ID mapping to team ownership
   • Ensure current season team assignments are correct

2. Transaction data missing:

   • Verify transaction_service API endpoints are functional
   • Check transaction status filtering logic
   • Ensure transaction records exist for the team/season

3. Roster validation failing:

   • Check roster_service.get_current_roster() and get_next_roster() responses
   • Verify roster validation rules and logic
   • Ensure player data integrity in roster records

4. Legal command errors:

   • Verify team abbreviation exists in database
   • Check roster data availability for both current and next weeks
   • Ensure validation service handles edge cases properly

5. Trade channel creation fails (Fixed January 2025):

   • Error: Discord error: Missing Permissions. Code: 50013
   • Root Cause: Bot was trying to grant itself manage_channels and manage_permissions in channel-specific permission overwrites
   • Fix: Removed elevated permissions from channel overwrites (line 74-77 in trade_channels.py)
   • Verification: Bot only needs server-level Manage Channels permission
   • Channels now create successfully with basic bot permissions (view, send messages, read history)

6. AttributeError when adding players to trades (Fixed January 2025):

   • Error: 'TeamService' object has no attribute 'get_team_by_id'
   • Root Cause: Code was calling non-existent method team_service.get_team_by_id()
   • Fix: Changed to correct method name team_service.get_team() (line 201 in trade_builder.py)
   • Location: services/trade_builder.py and test mocks in tests/test_services_trade_builder.py
   • All 18 trade builder tests pass after fix

Service Dependencies

• services.transaction_service:
  • get_pending_transactions()
  • get_frozen_transactions()
  • get_processed_transactions()
  • get_team_transactions()
• services.roster_service:
  • get_current_roster()
  • get_next_roster()
  • validate_roster()
• services.team_service:
  • get_teams_by_owner()
  • get_team_by_abbrev()
  • get_teams_by_season() (trade autocomplete)
• services.trade_builder (NEW):
  • TradeBuilder class for multi-team transaction management
  • get_trade_builder() and clear_trade_builder() cache functions
  • TradeValidationResult for comprehensive trade validation
• services.player_service:
  • search_players() for autocomplete functionality

Core Dependencies

• utils.decorators.logged_command
• views.embeds.EmbedTemplate
• views.trade_embed (NEW): Trade-specific UI components
• utils.autocomplete (ENHANCED): Player and team autocomplete functions
• utils.team_utils (NEW): Shared team validation utilities
• constants.SBA_CURRENT_SEASON

Testing

Run tests with:

• python -m pytest tests/test_commands_transactions.py -v (management commands)
• python -m pytest tests/test_models_trade.py -v (NEW) (trade models)
• python -m pytest tests/test_services_trade_builder.py -v (NEW) (trade builder service)

Database Requirements

• Team ownership mapping (Discord user ID to team)
• Transaction records with status tracking
• Roster data for current and next weeks
• Player assignments and position information
• League rules and validation criteria

Recent Enhancements (NEW)

• ✅ Multi-Team Trade System: Complete /trade command group for 2+ team trades
• ✅ Enhanced Autocomplete: Major League team filtering and smart player suggestions
• ✅ Shared Utilities: Reusable team validation and autocomplete functions
• ✅ Comprehensive Testing: Factory-based tests for trade models and services
• ✅ Interactive Trade UI: Rich Discord embeds with real-time validation

Future Enhancements

• Trade Submission Integration: Connect trade system to transaction processing pipeline
• **Advanced transaction analytics and history
• Trade Approval Workflow: Multi-party trade approval system
• **Roster optimization suggestions
• **Automated roster validation alerts
• Trade History Tracking: Complete audit trail for multi-team trades

Security Considerations

• User authentication via Discord IDs
• Team ownership verification for sensitive operations
• Transaction privacy (users can only see their own transactions)
• Input validation for team abbreviations and parameters