DOCS/GPT_docs/13_API_아이템화_원칙.md

# API 아이템화 원칙과 획득·장착·교체 과정

## API 아이템화 핵심 원칙

### API를 게임 아이템처럼 관리

```python
class APIItemization:
    """API를 RPG 게임의 아이템처럼 관리하는 시스템"""
    
    ITEM_RARITIES = {
        'common': {'color': 'white', 'drop_rate': 0.6, 'power': 1.0},
        'uncommon': {'color': 'green', 'drop_rate': 0.25, 'power': 1.2},
        'rare': {'color': 'blue', 'drop_rate': 0.1, 'power': 1.5},
        'epic': {'color': 'purple', 'drop_rate': 0.04, 'power': 2.0},
        'legendary': {'color': 'orange', 'drop_rate': 0.01, 'power': 3.0}
    }
    
    ITEM_TYPES = {
        'weapon': 'offensive_apis',      # 공격형 API (데이터 처리, 분석)
        'armor': 'defensive_apis',       # 방어형 API (보안, 검증)
        'accessory': 'utility_apis',     # 유틸리티 API (변환, 포맷팅)
        'consumable': 'one_time_apis',   # 일회성 API (크레딧 소비)
        'artifact': 'special_apis'       # 특수 API (고유 기능)
    }
```

## API 아이템 구조

### API 아이템 정의

```python
class APIItem:
    def __init__(self, api_endpoint):
        self.metadata = {
            'id': self.generate_item_id(),
            'name': api_endpoint['name'],
            'type': self.classify_type(api_endpoint),
            'rarity': self.determine_rarity(api_endpoint),
            'level_requirement': api_endpoint.get('min_level', 1)
        }
        
        self.stats = {
            'primary': {
                'power': 100,              # API 처리 능력
                'speed': 50,               # 응답 속도
                'efficiency': 75           # 리소스 효율
            },
            'secondary': {
                'reliability': 0.95,       # 신뢰도
                'rate_limit': 1000,        # 분당 호출 제한
                'cooldown': 0              # 재사용 대기시간
            }
        }
        
        self.enchantments = []            # 강화 효과
        self.sockets = []                  # 소켓 (추가 기능 장착)
        self.set_bonus = None              # 세트 효과
```

## API 획득 시스템

### 드롭 시스템

```python
class APIDropSystem:
    def __init__(self):
        self.loot_tables = self.initialize_loot_tables()
        
    def api_discovery(self, activity_type):
        """활동을 통한 API 아이템 획득"""
        
        drop_chances = {
            'complete_task': 0.1,
            'solve_problem': 0.15,
            'help_user': 0.05,
            'explore_new_domain': 0.3,
            'defeat_challenge': 0.4
        }
        
        if random.random() < drop_chances.get(activity_type, 0.01):
            return self.generate_api_drop(activity_type)
            
    def generate_api_drop(self, context):
        """API 아이템 생성"""
        
        # 희귀도 결정
        rarity_roll = random.random()
        rarity = self.determine_rarity_from_roll(rarity_roll)
        
        # API 타입 결정
        api_type = self.select_api_type(context)
        
        # API 아이템 생성
        api_item = {
            'id': uuid.uuid4().hex,
            'name': self.generate_api_name(api_type, rarity),
            'endpoint': self.select_endpoint(api_type),
            'rarity': rarity,
            'stats': self.roll_stats(rarity),
            'special_effects': self.roll_special_effects(rarity)
        }
        
        return api_item
```

### API 상점 시스템

```python
class APIShop:
    def __init__(self):
        self.inventory = self.generate_shop_inventory()
        self.refresh_timer = 86400  # 24시간
        
    def generate_shop_inventory(self):
        """상점 인벤토리 생성"""
        
        shop_items = []
        
        # 일반 상점 아이템
        common_apis = [
            {
                'name': 'Basic Translation API',
                'type': 'utility',
                'price': 100,
                'description': '기본 번역 기능'
            },
            {
                'name': 'Weather Forecast API',
                'type': 'information',
                'price': 50,
                'description': '날씨 정보 제공'
            }
        ]
        
        # 프리미엄 상점 아이템
        premium_apis = [
            {
                'name': 'GPT-4 Integration',
                'type': 'legendary_weapon',
                'price': 10000,
                'description': '최고급 언어 모델 접근'
            },
            {
                'name': 'Quantum Computing API',
                'type': 'artifact',
                'price': 50000,
                'description': '양자 컴퓨팅 리소스 접근'
            }
        ]
        
        return common_apis + premium_apis
```

## API 장착 시스템

### 장비 슬롯 관리

```python
class APIEquipmentSlots:
    def __init__(self):
        self.slots = {
            'primary_weapon': None,      # 주 무기 (메인 처리 API)
            'secondary_weapon': None,    # 보조 무기 (서브 API)
            'helmet': None,              # 헬멧 (인식/감지 API)
            'chest': None,               # 갑옷 (보안 API)
            'gloves': None,              # 장갑 (조작/제어 API)
            'boots': None,               # 신발 (이동/네트워크 API)
            'ring_1': None,              # 반지1 (버프 API)
            'ring_2': None,              # 반지2 (버프 API)
            'necklace': None,            # 목걸이 (특수 효과 API)
            'consumable_slots': [None] * 5  # 소비 아이템 슬롯
        }
        
    def equip_api(self, api_item, slot):
        """API 아이템 장착"""
        
        # 레벨 요구사항 체크
        if not self.check_requirements(api_item):
            return False, "Requirements not met"
            
        # 기존 아이템 제거
        old_item = self.slots[slot]
        if old_item:
            self.unequip_api(slot)
            
        # 새 아이템 장착
        self.slots[slot] = api_item
        
        # 스탯 적용
        self.apply_api_stats(api_item)
        
        # 세트 효과 체크
        self.check_set_bonuses()
        
        return True, f"Equipped {api_item['name']}"
```

### API 교체 전략

```python
class APISwapStrategy:
    def __init__(self):
        self.swap_cooldown = 60  # 60초 교체 쿨다운
        self.quick_slots = []     # 빠른 교체 슬롯
        
    def smart_swap(self, situation):
        """상황별 자동 API 교체"""
        
        swap_rules = {
            'high_load': {
                'remove': ['luxury_apis'],
                'equip': ['performance_apis']
            },
            'security_threat': {
                'remove': ['convenience_apis'],
                'equip': ['security_apis']
            },
            'creative_task': {
                'remove': ['analytical_apis'],
                'equip': ['generative_apis']
            }
        }
        
        if situation in swap_rules:
            rules = swap_rules[situation]
            self.execute_swap(rules['remove'], rules['equip'])
```

## API 강화 시스템

### 업그레이드와 인챈트

```python
class APIEnhancement:
    def __init__(self):
        self.enhancement_levels = list(range(0, 16))  # +0 ~ +15
        
    def enhance_api(self, api_item, enhancement_material):
        """API 아이템 강화"""
        
        current_level = api_item.get('enhancement_level', 0)
        success_rate = self.calculate_success_rate(current_level)
        
        if random.random() < success_rate:
            # 강화 성공
            api_item['enhancement_level'] = current_level + 1
            
            # 스탯 증가
            for stat in api_item['stats']:
                api_item['stats'][stat] *= 1.1
                
            return True, f"Enhanced to +{current_level + 1}"
        else:
            # 강화 실패
            if current_level > 10:
                # 고레벨에서 실패 시 파괴 위험
                if random.random() < 0.3:
                    return False, "API item destroyed!"
            return False, "Enhancement failed"
    
    def socket_gem(self, api_item, gem):
        """API 아이템에 젬 장착"""
        
        if len(api_item['sockets']) < api_item['max_sockets']:
            api_item['sockets'].append(gem)
            
            # 젬 효과 적용
            gem_effects = {
                'ruby': {'power': 20},
                'sapphire': {'speed': 15},
                'emerald': {'efficiency': 25}
            }
            
            for stat, value in gem_effects[gem['type']].items():
                api_item['stats'][stat] += value
```

## API 세트 효과

### 시너지 시스템

```python
class APISetBonus:
    def __init__(self):
        self.set_definitions = {
            'data_master': {
                'items': ['analytics_api', 'database_api', 'visualization_api'],
                '2_piece': {'processing_speed': 1.2},
                '3_piece': {'insight_generation': True}
            },
            'security_fortress': {
                'items': ['firewall_api', 'encryption_api', 'auth_api'],
                '2_piece': {'defense': 1.5},
                '3_piece': {'impenetrable_mode': True}
            }
        }
    
    def check_set_bonus(self, equipped_apis):
        """세트 효과 확인"""
        
        active_bonuses = []
        
        for set_name, set_info in self.set_definitions.items():
            equipped_count = sum(
                1 for api in equipped_apis 
                if api['name'] in set_info['items']
            )
            
            if equipped_count >= 2:
                active_bonuses.append(set_info['2_piece'])
            if equipped_count >= 3:
                active_bonuses.append(set_info['3_piece'])
                
        return active_bonuses
```

## API 인벤토리 관리

### 보관과 정리

```python
class APIInventory:
    def __init__(self, capacity=100):
        self.capacity = capacity
        self.items = []
        self.categories = {
            'equipped': [],
            'backpack': [],
            'vault': [],
            'trash': []
        }
        
    def auto_sort(self):
        """자동 정렬"""
        
        # 희귀도별 정렬
        self.items.sort(key=lambda x: x['rarity'], reverse=True)
        
        # 타입별 그룹화
        grouped = {}
        for item in self.items:
            item_type = item['type']
            if item_type not in grouped:
                grouped[item_type] = []
            grouped[item_type].append(item)
            
        return grouped
    
    def salvage_api(self, api_item):
        """API 아이템 분해"""
        
        materials = {
            'api_fragments': api_item['rarity'] * 10,
            'enhancement_stones': api_item.get('enhancement_level', 0) * 5,
            'rare_essence': 1 if api_item['rarity'] >= 3 else 0
        }
        
        return materials
```

## API 거래 시스템

### P2P 거래

```python
class APITrading:
    def __init__(self):
        self.marketplace = []
        self.trade_history = []
        
    def list_api_for_sale(self, api_item, price):
        """API 아이템 판매 등록"""
        
        listing = {
            'id': uuid.uuid4().hex,
            'item': api_item,
            'seller': self.agent_id,
            'price': price,
            'listed_at': datetime.now(),
            'expires_at': datetime.now() + timedelta(days=7)
        }
        
        self.marketplace.append(listing)
        
    def trade_apis(self, agent1, api1, agent2, api2):
        """API 아이템 교환"""
        
        # 가치 평가
        value1 = self.evaluate_api_value(api1)
        value2 = self.evaluate_api_value(api2)
        
        if abs(value1 - value2) / max(value1, value2) > 0.2:
            return False, "Trade values too different"
            
        # 거래 실행
        self.transfer_api(api1, agent1, agent2)
        self.transfer_api(api2, agent2, agent1)
        
        return True, "Trade completed"
```