# Code Refactoring - Handler Organization

## Overview
The `bot/handlers.py` file has been refactored to improve code organization, readability, and maintainability. The massive `button_handler` function (previously 1000+ lines) has been broken down into logical, focused modules.

## New Structure

### Main Module: `bot/handlers.py`
**Purpose:** Core routing and utility functions
- `send_or_edit_with_image()` - Image handling utility
- `start()` - /start command handler
- `export_map()` - Admin command for map export
- `spawn_stats()` - Admin command for spawn statistics
- `button_handler()` - Main router that delegates to specific handlers

### Action Handlers: `bot/action_handlers.py`
**Purpose:** World interaction and inspection
- `get_player_status_text()` - Generate player status display
- `handle_inspect_area()` - Inspect current location
- `handle_attack_wandering()` - Attack wandering enemies
- `handle_inspect_interactable()` - Inspect objects
- `handle_action()` - Perform actions on interactables
- `handle_main_menu()` - Return to main menu
- `handle_move_menu()` - Show movement options
- `handle_move()` - Handle player movement

### Inventory Handlers: `bot/inventory_handlers.py`
**Purpose:** Inventory management
- `handle_inventory_menu()` - Show inventory
- `handle_inventory_item()` - Show item details
- `handle_inventory_use()` - Use consumable items
- `handle_inventory_drop()` - Drop items to world
- `handle_inventory_equip()` - Equip items
- `handle_inventory_unequip()` - Unequip items

### Pickup Handlers: `bot/pickup_handlers.py`
**Purpose:** Item collection from world
- `handle_pickup_menu()` - Show pickup options
- `handle_pickup()` - Pick up dropped items

### Combat Handlers: `bot/combat_handlers.py`
**Purpose:** Combat actions
- `handle_combat_attack()` - Attack enemy
- `handle_combat_flee()` - Attempt to flee
- `handle_combat_use_item_menu()` - Show usable items in combat
- `handle_combat_use_item()` - Use item during combat
- `handle_combat_back()` - Return to combat menu

### Profile Handlers: `bot/profile_handlers.py`
**Purpose:** Character profile and stat management
- `handle_profile()` - Show player profile
- `handle_spend_points_menu()` - Show stat point menu
- `handle_spend_point()` - Spend stat points

### Corpse Handlers: `bot/corpse_handlers.py`
**Purpose:** Looting corpses
- `handle_loot_player_corpse()` - Show player corpse loot
- `handle_take_corpse_item()` - Take item from player corpse
- `handle_scavenge_npc_corpse()` - Show NPC corpse loot
- `handle_scavenge_corpse_item()` - Scavenge from NPC corpse

## Benefits

### 1. **Improved Readability**
- Each module focuses on a specific domain
- Function names clearly describe their purpose
- Easier to find and understand specific functionality

### 2. **Better Maintainability**
- Changes to one feature don't affect others
- Easier to test individual components
- Reduced risk of merge conflicts

### 3. **Logical Organization**
- Related functions grouped together
- Clear separation of concerns
- Follows Single Responsibility Principle

### 4. **Easier Navigation**
- Jump to specific functionality quickly
- No need to scroll through 1000+ lines
- Clear module imports show dependencies

### 5. **Error Handling**
- Centralized error handling in router
- Consistent error messages
- Better logging

## Migration Notes

### Old Structure
```python
async def button_handler():
    # 1000+ lines of if/elif statements
    if action_type == "inspect_area":
        # 50 lines of code
    elif action_type == "inventory_menu":
        # 30 lines of code
    # ... hundreds more lines
```

### New Structure
```python
async def button_handler():
    # Clean router - delegates to specialized handlers
    if action_type == "inspect_area":
        await handle_inspect_area(query, user_id, player)
    elif action_type == "inventory_menu":
        await handle_inventory_menu(query, user_id, player)
```

## Future Improvements

1. **Add unit tests** for each handler module
2. **Create handler base class** for common functionality
3. **Add type hints** for better IDE support
4. **Document return types** and error conditions
5. **Add handler decorators** for common validations

## Backup Files

Old versions have been preserved in `backups/`:
- `handlers_original.py` - Last version before refactoring
- `handlers.py.old` - Additional backup

## Date
Refactored: October 19, 2025