feat(api): add ItemRarity enum to item system

- Add ItemRarity enum with 5 tiers (common, uncommon, rare, epic, legendary)
- Add rarity field to Item dataclass with COMMON default
- Update Item serialization (to_dict/from_dict) for rarity
- Export ItemRarity from models package
- Add 24 comprehensive unit tests for Item and ItemRarity

Part of Phase 4 Week 2: Inventory & Equipment System (Task 2.1)

api/app/models/__init__.py

@@ -9,6 +9,7 @@ from app.models.enums import (
     EffectType,
     DamageType,
     ItemType,
+    ItemRarity,
     StatType,
     AbilityType,
     CombatStatus,
@@ -53,6 +54,7 @@ __all__ = [
     "EffectType",
     "DamageType",
     "ItemType",
+    "ItemRarity",
     "StatType",
     "AbilityType",
     "CombatStatus",

api/app/models/enums.py

@@ -40,6 +40,16 @@ class ItemType(Enum):
     QUEST_ITEM = "quest_item"   # Story-related, non-tradeable
 
 
+class ItemRarity(Enum):
+    """Item rarity tiers affecting drop rates, value, and visual styling."""
+
+    COMMON = "common"           # White/gray - basic items
+    UNCOMMON = "uncommon"       # Green - slightly better
+    RARE = "rare"               # Blue - noticeably better
+    EPIC = "epic"               # Purple - powerful items
+    LEGENDARY = "legendary"     # Orange/gold - best items
+
+
 class StatType(Enum):
     """Character attribute types."""
 

api/app/models/items.py

@@ -8,7 +8,7 @@ including weapons, armor, consumables, and quest items.
 from dataclasses import dataclass, field, asdict
 from typing import Dict, Any, List, Optional
 
-from app.models.enums import ItemType, DamageType
+from app.models.enums import ItemType, ItemRarity, DamageType
 from app.models.effects import Effect
 
 
@@ -24,6 +24,7 @@ class Item:
         item_id: Unique identifier
         name: Display name
         item_type: Category (weapon, armor, consumable, quest_item)
+        rarity: Rarity tier (common, uncommon, rare, epic, legendary)
         description: Item lore and information
         value: Gold value for buying/selling
         is_tradeable: Whether item can be sold on marketplace
@@ -49,7 +50,8 @@ class Item:
     item_id: str
     name: str
     item_type: ItemType
-    description: str
+    rarity: ItemRarity = ItemRarity.COMMON
+    description: str = ""
     value: int = 0
     is_tradeable: bool = True
 
@@ -158,6 +160,7 @@ class Item:
         """
         data = asdict(self)
         data["item_type"] = self.item_type.value
+        data["rarity"] = self.rarity.value
         if self.damage_type:
             data["damage_type"] = self.damage_type.value
         if self.elemental_damage_type:
@@ -178,6 +181,7 @@ class Item:
         """
         # Convert string values back to enums
         item_type = ItemType(data["item_type"])
+        rarity = ItemRarity(data.get("rarity", "common"))
         damage_type = DamageType(data["damage_type"]) if data.get("damage_type") else None
         elemental_damage_type = (
             DamageType(data["elemental_damage_type"])
@@ -194,7 +198,8 @@ class Item:
             item_id=data["item_id"],
             name=data["name"],
             item_type=item_type,
-            description=data["description"],
+            rarity=rarity,
+            description=data.get("description", ""),
             value=data.get("value", 0),
             is_tradeable=data.get("is_tradeable", True),
             stat_bonuses=data.get("stat_bonuses", {}),