Refactor item management system with future-proof modular architecture

[Copilot]

Overview

This PR completely refactors the item management system to address the need for "more thoughtful placement and implementation of the setup to be future proof (when other aspects needs to be developed)". The new architecture provides a solid foundation for future feature development while maintaining full backward compatibility.

Key Changes

🏗️ Modular Architecture

• ItemService: Centralized service for all item-related operations with clean separation of concerns
• ItemFactory: Template-based item creation using the factory pattern for consistency and extensibility
• InventoryManager: Handles character inventory, equipment slots, and effect aggregation
• ItemTemplate: Standardized item definitions with extensible properties

📊 Enhanced Database Models

• Extended SQLAlchemy Item model with JSON-based effects and properties for maximum flexibility
• Added equipment slots, quantity stacking, and equipment state tracking
• Enhanced Character model with comprehensive inventory management methods
• Proper database migrations for smooth upgrades

⚔️ Equipment System

• Slot-based equipment system (main hand, off hand, both hands, armor slots, etc.)
• Equipment validation with strength requirements and class restrictions
• Two-handed weapon logic and slot conflict detection
• Real-time effect calculation from equipped items

📦 Inventory Management

• Weight-based carrying capacity using D&D 5e rules (STR × 15 lbs)
• Category-based item organization (weapon, armor, gear, consumable, magic_item)
• Overload detection and inventory summaries
• Item effect aggregation and character stat modifications

Extensibility Examples

To demonstrate the future-proof nature of the new system, this PR includes two complete extension examples:

🏪 Shop System (item_extensions.py)

# Different shop types with intelligent inventory
shop_manager = ShopManager()
weapon_shop = shop_manager.get_shop("The Sharpened Blade")

# Complete buying/selling with price calculations
success, message, item_data = shop.buy_item('Longsword', 1)
character.add_item_from_template(item_data)

✨ Magic Item Creation

# Create magic items by extending base items
magic_sword = magic_item_creator.create_magic_weapon('Longsword', '+1 Weapon')
# Automatically handles effect stacking and value calculations

API Enhancements

New RESTful API endpoints enable rich client interactions:

• GET /api/items/available?category=weapon - Filtered item browsing
• POST /api/character/{id}/equip_item/{item_id} - Equipment management
• POST /api/shop/{name}/buy - Shop transactions
• POST /api/magic_items/create - Dynamic magic item creation

UI Improvements

• Enhanced character detail view with full inventory management
• Shop browsing interface demonstrating the extensible architecture
• Equipment/unequip functionality with real-time validation
• Carrying capacity visualization and overload warnings

Future-Proof Design

The new architecture enables easy addition of future features without modifying core code:

• Crafting System: Recipe system using existing ItemTemplates
• Item Durability: Equipment degradation through properties JSON
• Set Items: Conditional effects based on equipped item combinations
• Trading System: Player-to-player trading using the shop framework

Testing & Documentation

• Comprehensive test suite with 100% pass rate covering all new functionality
• Detailed technical documentation with usage examples and extension patterns
• Database migration scripts for safe production deployment
• Full backward compatibility ensuring existing characters continue to work

Performance Considerations

• Lazy loading of item templates and inventory managers
• Efficient JSON storage for flexible properties without schema changes
• Optimized database queries with proper SQLAlchemy relationships
• Memory-efficient factory pattern reducing object creation overhead

Before/After Comparison

Before: Monolithic item handling with hard-coded equipment lists and basic inventory

# Old way - rigid and hard to extend
character.add_item(name="Longsword", item_type="weapon", weight=3, value=15)

After: Modular, extensible system with rich functionality

# New way - flexible and future-proof
longsword = item_service.create_item('Longsword')
character.add_item_from_template(longsword)
success, message = character.equip_item(item.id)  # Automatic validation

This refactor transforms the item management from a basic feature into a robust, extensible foundation that can support any future D&D game mechanics while maintaining the simplicity developers expect.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.