scripts/chunk_handlers.py

"""
청크 생성 핸들러
================

YAML의 각 섹션을 검색 가능한 청크로 변환하는 핸들러 함수들.
sync_to_supabase.py에서 동적으로 호출됩니다.

핸들러 규칙:
- 각 핸들러는 (data, context) -> List[Dict] 형태
- context에는 chain, hotel_name, hotel_name_ko 등 포함
- 반환값은 [{content: str, metadata: dict}, ...] 형태
"""

from typing import Dict, Any, List, Optional


# ===========================================================================
# 유틸리티
# ===========================================================================

DISCLAIMER_PRICE = "\n\n⚠️ 참고: 위 포인트/가격 정보는 과거 데이터 기반 참고용입니다. 실제 필요 포인트와 가격은 예약 시점에 따라 변동되므로, 공식 웹사이트에서 직접 확인하시기 바랍니다."
DISCLAIMER_SHORT = "\n\n⚠️ 참고용 정보입니다. 실제 내용은 공식 웹사이트에서 확인하세요."


def safe_format_number(value: Any, suffix: str = "", prefix: str = "") -> str:
    """숫자를 안전하게 포맷팅 - None이나 비숫자 값 처리
    
    Args:
        value: 포맷팅할 값 (int, float, None 등)
        suffix: 숫자 뒤에 붙일 문자열 (예: '원', '마일', 'P')
        prefix: 숫자 앞에 붙일 문자열 (예: '약 ', '최대 ')
    
    Returns:
        포맷된 문자열 또는 'N/A'
    
    Examples:
        safe_format_number(1000, "원") -> "1,000원"
        safe_format_number(None, "원") -> "N/A"
        safe_format_number("unknown", "P") -> "N/A"
    """
    if value is None:
        return "N/A"
    
    try:
        if isinstance(value, (int, float)):
            return f"{prefix}{value:,}{suffix}"
        # 문자열이 숫자로 변환 가능한지 시도
        num_value = float(value)
        if num_value.is_integer():
            return f"{prefix}{int(num_value):,}{suffix}"
        return f"{prefix}{num_value:,.2f}{suffix}"
    except (ValueError, TypeError):
        return str(value) if value else "N/A"


def get_hotel_info(context: Dict[str, Any]) -> tuple:
    """context에서 호텔 정보 추출"""
    hotel_name = context.get("hotel_name", "Unknown Hotel")
    hotel_name_ko = context.get("hotel_name_ko")
    chain = context.get("chain", "UNKNOWN")
    return hotel_name, hotel_name_ko, chain


def format_hotel_header(hotel_name: str, hotel_name_ko: Optional[str], chain: str) -> str:
    """호텔 정보 헤더 생성"""
    content = f"호텔명: {hotel_name}\n"
    if hotel_name_ko:
        content += f"호텔명 (한국어): {hotel_name_ko}\n"
    content += f"체인: {chain}\n"
    return content


def format_evidence(evidence_list: list, max_items: int = 2, max_quote_len: int = 80) -> str:
    """Evidence 배열을 청크에 포함할 포맷으로 변환
    
    Args:
        evidence_list: evidence 객체 리스트
        max_items: 포함할 최대 evidence 수
        max_quote_len: 인용문 최대 길이
    
    Returns:
        포맷된 출처 정보 문자열 (비어있으면 빈 문자열)
    """
    if not evidence_list or not isinstance(evidence_list, list):
        return ""
    
    content = "\n출처:\n"
    added = 0
    
    for ev in evidence_list:
        if added >= max_items:
            break
        if not isinstance(ev, dict):
            continue
        
        section = ev.get("section_path", "")
        quote = ev.get("quote", "")
        
        if section or quote:
            if section:
                content += f"  - [{section}] "
            else:
                content += "  - "
            
            if quote:
                # 인용문 길이 제한
                truncated = quote[:max_quote_len]
                if len(quote) > max_quote_len:
                    truncated += "..."
                content += f'"{truncated}"\n'
            else:
                content += "\n"
            added += 1
    
    return content if added > 0 else ""


# ===========================================================================
# 핸들러: 로열티 프로그램
# ===========================================================================

def handle_loyalty_programs(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """loyalty_programs 또는 loyalty_program 처리
    
    LoyaltyProgram 스키마의 내부 구성 요소도 서브청킹:
    - points_system → handle_points_systems
    - member_rates → handle_member_rates
    - milestone_program → handle_milestone_programs
    - partner_status_matches → handle_partner_status_matches
    - co_branded_cards → handle_credit_cards
    """
    chunks = []
    chain = context.get("chain", "UNKNOWN")
    
    # 단일 객체인 경우 리스트로 변환
    programs = data if isinstance(data, list) else [data]
    
    for program in programs[:5]:
        if not isinstance(program, dict):
            continue
            
        program_name = program.get("program_name", "N/A")
        program_chain = program.get("chain", chain)
        
        content = f"""
로열티 프로그램: {program_name}
체인: {program_chain}
포인트 이름: {program.get("points_name", "N/A")}
포인트 만료: {program.get("points_expiry", "N/A")}
"""
        
        # 회원 등급
        tiers = program.get("tiers", [])
        if tiers:
            content += "\n등급:\n"
            for tier in tiers[:7]:
                tier_name = tier.get("tier_name", "N/A")
                upgrade_req = tier.get("upgrade_requirement", {})
                req_nights = upgrade_req.get("nights")
                content += f"  - {tier_name}: {req_nights}박 이상\n" if req_nights else f"  - {tier_name}\n"
        
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "loyalty_program",
                "program_name": program_name,
                "chain": program_chain
            }
        })
        
        # === 내부 구성 요소 서브청킹 ===
        # 프로그램별 컨텍스트 생성 (chain 정보 보강)
        program_context = {**context, "chain": program_chain}
        
        # 1. points_system 처리
        points_system = program.get("points_system")
        if points_system:
            try:
                sub_chunks = handle_points_systems(points_system, program_context)
                chunks.extend(sub_chunks)
            except Exception:
                pass
        
        # 2. member_rates 처리
        member_rates = program.get("member_rates")
        if member_rates:
            try:
                sub_chunks = handle_member_rates(member_rates, program_context)
                chunks.extend(sub_chunks)
            except Exception:
                pass
        
        # 3. milestone_program 처리
        milestone_program = program.get("milestone_program")
        if milestone_program:
            try:
                sub_chunks = handle_milestone_programs(milestone_program, program_context)
                chunks.extend(sub_chunks)
            except Exception:
                pass
        
        # 4. partner_status_matches 처리
        partner_status_matches = program.get("partner_status_matches")
        if partner_status_matches:
            try:
                sub_chunks = handle_partner_status_matches(partner_status_matches, program_context)
                chunks.extend(sub_chunks)
            except Exception:
                pass
        
        # 5. co_branded_cards 처리 (제휴 카드)
        co_branded_cards = program.get("co_branded_cards")
        if co_branded_cards:
            try:
                sub_chunks = handle_credit_cards(co_branded_cards, program_context)
                chunks.extend(sub_chunks)
            except Exception:
                pass
        
        # 6. best_rate_guarantee 처리 (BRG)
        brg = program.get("best_rate_guarantee")
        if brg:
            try:
                sub_chunks = handle_best_rate_guarantee(brg, program_context)
                chunks.extend(sub_chunks)
            except Exception:
                pass
    
    return chunks


def handle_membership_tiers(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """membership_tiers 처리"""
    chunks = []
    chain = context.get("chain", "UNKNOWN")

    if data is None:
        return chunks

    tiers = data if isinstance(data, list) else [data]
    
    for tier in tiers[:10]:
        if not isinstance(tier, dict):
            continue
            
        tier_name = tier.get("tier_name", "N/A")
        tier_level = tier.get("tier_level", "N/A")
        tier_chain = tier.get("chain", chain)
        
        # 스키마 필드명: qualification (TierQualification)
        # 하위 호환성: upgrade_requirement도 폴백 지원
        qualification = tier.get("qualification", tier.get("upgrade_requirement", {}))
        req_nights = qualification.get("nights_required", qualification.get("nights", "N/A"))
        req_stays = qualification.get("stays_required")
        req_points = qualification.get("points_required", qualification.get("points"))
        req_spending = qualification.get("spending_required")
        qual_period = qualification.get("qualification_period", "calendar_year")
        
        # 스키마 필드명: bonus_points_percentage
        bonus_pct = tier.get("bonus_points_percentage", tier.get("elite_bonus_points"))
        
        content = f"""
등급: {tier_name} ({tier_level})
체인: {tier_chain}
등급 순위: {tier.get("rank", "N/A")}
자격 요건:
  - 숙박: {req_nights}박"""
        
        if req_stays:
            content += f"\n  - 체류: {req_stays}회"
        if req_points:
            content += f"\n  - 포인트: {req_points:,}P" if isinstance(req_points, int) else f"\n  - 포인트: {req_points}"
        if req_spending and isinstance(req_spending, dict):
            content += f"\n  - 지출: {req_spending.get('amount', 'N/A')} {req_spending.get('currency', '')}"
        
        content += f"\n  - 산정 기간: {qual_period}\n"
        
        # 대체 자격 경로
        alt_paths = qualification.get("alternative_paths", [])
        if alt_paths:
            content += f"  - 대체 경로: {', '.join(alt_paths[:3])}\n"
        
        if bonus_pct:
            content += f"보너스 포인트: {bonus_pct}%\n"
        
        # 등급 유지 조건: retention (TierRetention)
        retention = tier.get("retention")
        if retention and isinstance(retention, dict):
            content += "\n등급 유지 조건:\n"
            ret_nights = retention.get("nights_required")
            ret_points = retention.get("points_required")
            if ret_nights:
                content += f"  - 숙박: {ret_nights}박\n"
            if ret_points:
                content += f"  - 포인트: {ret_points:,}P\n"
        
        # 평생 등급
        if tier.get("lifetime_tier_available"):
            content += f"\n평생 등급: 가능"
            if tier.get("lifetime_requirements"):
                content += f" ({tier.get('lifetime_requirements')})"
            content += "\n"
        
        # 주요 혜택
        benefits = tier.get("benefits", [])
        if benefits:
            content += "\n주요 혜택:\n"
            for benefit in benefits[:8]:
                if isinstance(benefit, dict):
                    ben_name = benefit.get("name", benefit.get("benefit_name", "N/A"))
                    ben_desc = benefit.get("description", "")[:80]
                    content += f"  - {ben_name}"
                    if ben_desc:
                        content += f": {ben_desc}"
                    content += "\n"
        
        # evidence 정보 포함 (선택적)
        evidence = tier.get("evidence", [])
        if evidence:
            content += format_evidence(evidence, max_items=2)
        
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "membership_tier",
                "tier_name": tier_name,
                "tier_level": tier_level,
                "rank": tier.get("rank")
            }
        })
    
    return chunks


# ===========================================================================
# 핸들러: 마일스톤 프로그램
# ===========================================================================

def handle_milestone_programs(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """milestone_program 처리 (IHG Milestone Rewards 등)"""
    chunks = []
    chain = context.get("chain", "UNKNOWN")
    
    programs = data if isinstance(data, list) else [data]
    
    for program in programs[:3]:
        if not isinstance(program, dict):
            continue
        
        program_name = program.get("program_name", "Milestone Rewards")
        program_chain = program.get("chain", chain)
        minimum_tier = program.get("minimum_tier", "N/A")
        reset_period = program.get("reset_period", "calendar_year")
        
        content = f"""
마일스톤 프로그램: {program_name}
체인: {program_chain}
참여 최소 등급: {minimum_tier}
리셋 주기: {reset_period}
롤오버 가능: {"예" if program.get("rollover_enabled") else "아니오"}
"""
        
        # 롤오버 가능 등급
        rollover_tiers = program.get("rollover_eligible_tiers", [])
        if rollover_tiers:
            content += f"롤오버 가능 등급: {', '.join(str(t) for t in rollover_tiers)}\n"
        
        # 마일스톤 목록
        milestones = program.get("milestones", [])
        if milestones:
            content += "\n마일스톤 보상:\n"
            for milestone in milestones[:10]:
                if not isinstance(milestone, dict):
                    continue
                    
                nights = milestone.get("nights_required", "?")
                is_bonus = milestone.get("is_bonus_choice", False)
                max_sel = milestone.get("max_selections", 1)
                
                content += f"\n  [{nights}박 달성]"
                if is_bonus:
                    content += f" (Bonus Choice - {max_sel}개 선택)"
                content += ":\n"
                
                # 보상 옵션
                options = milestone.get("reward_options", [])
                for opt in options[:6]:
                    if isinstance(opt, dict):
                        opt_name = opt.get("name", "N/A")
                        bonus_pts = opt.get("bonus_points")
                        quantity = opt.get("quantity")
                        
                        opt_str = f"    - {opt_name}"
                        if bonus_pts:
                            opt_str += f" ({bonus_pts:,}P)"
                        elif quantity:
                            opt_str += f" ({quantity}개)"
                        content += opt_str + "\n"
        
        content += DISCLAIMER_SHORT
        
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "milestone_program",
                "program_name": program_name,
                "chain": program_chain,
                "minimum_tier": str(minimum_tier)
            }
        })
    
    return chunks


# ===========================================================================
# 핸들러: 파트너 등급 매칭
# ===========================================================================

def handle_partner_status_matches(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """partner_status_matches 처리 (파트너 등급 매칭)"""
    chunks = []
    chain = context.get("chain", "UNKNOWN")
    
    matches = data if isinstance(data, list) else [data]
    
    # 여러 파트너를 하나의 청크로 묶기
    if not matches:
        return chunks
    
    content = f"""
파트너 등급 매칭 프로그램
체인: {chain}

"""
    
    for match in matches[:10]:
        if not isinstance(match, dict):
            continue
        
        partner_name = match.get("partner_name", "N/A")
        partner_program = match.get("partner_program", "")
        partner_tier = match.get("partner_tier", "N/A")
        required_tier = match.get("required_hotel_tier", "N/A")
        validity = match.get("validity", "")
        
        content += f"• {partner_name}"
        if partner_program:
            content += f" ({partner_program})"
        content += f"\n"
        content += f"  - 필요 호텔 등급: {required_tier}\n"
        content += f"  - 부여 파트너 등급: {partner_tier}\n"
        
        if validity:
            content += f"  - 유효 기간: {validity}\n"
        
        # 파트너 혜택
        partner_benefits = match.get("partner_benefits", [])
        if partner_benefits:
            content += f"  - 혜택: {', '.join(partner_benefits[:3])}\n"
        
        content += "\n"
    
    content += DISCLAIMER_SHORT
    
    chunks.append({
        "content": content.strip(),
        "metadata": {
            "type": "partner_status_match",
            "chain": chain
        }
    })
    
    return chunks


# ===========================================================================
# 핸들러: 포인트 시스템
# ===========================================================================

def handle_points_systems(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """points_systems 또는 points_system 처리"""
    chunks = []
    chain = context.get("chain", "UNKNOWN")

    if data is None:
        return chunks

    systems = data if isinstance(data, list) else [data]

    for system in systems[:3]:
        if not isinstance(system, dict):
            continue

        try:
            point_name = system.get("point_name", system.get("points_name", "N/A"))

            content = f"""
포인트 시스템: {point_name}
체인: {system.get("chain", chain)}
"""

            # 스키마 필드명: expiration_policy (PointExpirationPolicy)
            # 하위 호환성: expiry도 폴백 지원
            expiration = system.get("expiration_policy", system.get("expiry"))
            if expiration:
                if isinstance(expiration, dict):
                    expires = expiration.get("expires", expiration.get("has_expiry", True))
                    exp_months = expiration.get("expiration_months", expiration.get("expiry_period"))
                    can_extend = expiration.get("can_extend_with_activity", False)
                    activity_types = expiration.get("activity_types", [])
                    
                    content += f"\n만료: {'있음' if expires else '없음'}"
                    if exp_months:
                        content += f" ({exp_months}개월)"
                    content += "\n"
                    
                    if can_extend:
                        content += f"활동으로 연장: 가능"
                        if activity_types:
                            content += f" ({', '.join(activity_types)})"
                        content += "\n"
                else:
                    content += f"\n만료: {expiration}\n"

            # 적립 규칙
            content += "\n적립 규칙:\n"
            earning_rules = system.get("earning_rules", [])
            if earning_rules and isinstance(earning_rules, list):
                for rule in earning_rules[:6]:
                    if isinstance(rule, dict):
                        rule_name = rule.get("rule_name", rule.get("name", "N/A"))
                        category = rule.get("category", "")
                        points_per_unit = rule.get("points_per_unit")
                        spending_unit = rule.get("spending_unit", {})
                        
                        content += f"  - {rule_name}"
                        if category:
                            content += f" ({category})"
                        content += ": "
                        
                        # 스키마: points_per_unit, spending_unit (Money 객체)
                        if points_per_unit and spending_unit:
                            # spending_unit이 dict인 경우 Money 구조 확인
                            if isinstance(spending_unit, dict):
                                unit_amount = spending_unit.get("amount", "N/A")
                                unit_currency = spending_unit.get("currency", "")
                                if unit_amount != "N/A" and unit_currency:
                                    content += f"{unit_amount} {unit_currency}당 {points_per_unit}P"
                                else:
                                    content += f"{points_per_unit}P"
                            else:
                                # spending_unit이 단순 값인 경우 (하위 호환성)
                                content += f"{spending_unit}당 {points_per_unit}P"
                        elif rule.get("rate"):
                            content += f"{rule.get('rate')}"
                        else:
                            content += "N/A"
                        content += "\n"
                        
                        # 한도
                        monthly_cap = rule.get("monthly_cap")
                        yearly_cap = rule.get("yearly_cap")
                        if monthly_cap:
                            content += f"    월 한도: {monthly_cap:,}P\n"
                        if yearly_cap:
                            content += f"    연 한도: {yearly_cap:,}P\n"

            # 사용 규칙
            redemption_rules = system.get("redemption_rules", [])
            if redemption_rules:
                content += "\n사용 규칙:\n"
                for rule in redemption_rules[:3]:
                    if isinstance(rule, dict):
                        r_type = rule.get("redemption_type", "N/A")
                        min_points = rule.get("minimum_points", "N/A")
                        content += f"  - {r_type}: 최소 {min_points:,}P\n" if isinstance(min_points, int) else f"  - {r_type}: 최소 {min_points}P\n"

            # 전환 파트너
            transfer_partners = system.get("transfer_partners", [])
            if transfer_partners:
                content += f"\n전환 파트너: {', '.join(transfer_partners[:5])}\n"

            chunks.append({
                "content": content.strip(),
                "metadata": {
                    "type": "points_system",
                    "point_name": point_name
                }
            })

        except Exception as e:
            # 오류 발생시 스킵하고 계속
            continue

    return chunks


# ===========================================================================
# 핸들러: 호텔 프로퍼티
# ===========================================================================

def handle_hotel_properties(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """hotel_properties 처리"""
    chunks = []
    chain = context.get("chain", "UNKNOWN")
    
    hotels = data if isinstance(data, list) else [data]
    
    for hotel in hotels[:5]:
        if not isinstance(hotel, dict):
            continue
            
        hotel_name = hotel.get("name", "Unknown Hotel")
        hotel_chain = hotel.get("chain", chain)
        location = hotel.get("location", {})
        
        # 한국어 이름 추출
        name_localized = hotel.get("name_localized", {})
        name_ko = name_localized.get("ko") if isinstance(name_localized, dict) else None
        
        content = f"호텔명: {hotel_name}\n"
        if name_ko and name_ko != hotel_name:
            content += f"호텔명 (한국어): {name_ko}\n"
        
        content += f"""체인: {hotel_chain}
브랜드: {hotel.get('brand_code', 'N/A')}
카테고리: {hotel.get('category', 'N/A')}
객실 수: {hotel.get('room_count', 'N/A')}실
주소: {location.get('address', 'N/A')}
도시: {location.get('city', 'N/A')}
국가: {location.get('country', 'N/A')}
"""
        
        # 레스토랑
        restaurants = hotel.get("restaurant_names", [])
        if restaurants:
            content += f"레스토랑: {', '.join(restaurants)}\n"
        
        # 라운지
        if hotel.get("lounge_name"):
            content += f"라운지: {hotel.get('lounge_name')}\n"
        
        # 참여 채널 (FHR, Virtuoso 등)
        participating_channels = hotel.get("participating_channels", [])
        if participating_channels:
            content += f"참여 채널: {', '.join(participating_channels)}\n"
        
        # 호텔 식별자 및 위치 정보 추출
        hotel_id = hotel.get("hotel_id")
        country = location.get("country") if isinstance(location, dict) else None
        city = location.get("city") if isinstance(location, dict) else None
        region = hotel.get("region")
        
        # 메타데이터 구성 (hotel_id, chain, country 포함으로 필터링 강화)
        metadata = {
            "type": "hotel_property",
            "hotel_name": hotel_name,
            "hotel_name_ko": name_ko,
            "brand": hotel.get("brand_code"),
            "chain": hotel_chain,
        }
        if hotel_id:
            metadata["hotel_id"] = hotel_id
        if country:
            metadata["country"] = country
        if city:
            metadata["city"] = city
        if region:
            metadata["region"] = region
        
        chunks.append({
            "content": content.strip(),
            "metadata": metadata
        })
    
    return chunks


# ===========================================================================
# 핸들러: 호텔 브랜드
# ===========================================================================

def handle_hotel_brands(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """hotel_brands 처리"""
    chunks = []
    chain = context.get("chain", "UNKNOWN")
    
    brands = data if isinstance(data, list) else [data]
    
    for brand in brands[:10]:
        if not isinstance(brand, dict):
            continue
        
        brand_code = brand.get("brand_code", "N/A")
        brand_name = brand.get("brand_name", "N/A")
        brand_chain = brand.get("chain", chain)
        tier = brand.get("tier", "N/A")
        
        # 한국어 이름
        name_localized = brand.get("brand_name_localized", {})
        name_ko = name_localized.get("ko") if isinstance(name_localized, dict) else None
        
        content = f"""
호텔 브랜드: {brand_name}
"""
        if name_ko and name_ko != brand_name:
            content += f"브랜드명 (한국어): {name_ko}\n"
        
        content += f"""브랜드 코드: {brand_code}
체인: {brand_chain}
티어: {tier}
"""
        
        # 기본 혜택
        default_benefits = brand.get("default_benefits", [])
        if default_benefits:
            content += "\n브랜드 기본 혜택:\n"
            for benefit in default_benefits[:5]:
                if isinstance(benefit, dict):
                    ben_name = benefit.get("name", "N/A")
                    content += f"  - {ben_name}\n"
        
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "hotel_brand",
                "brand_code": brand_code,
                "brand_name": brand_name,
                "tier": str(tier)
            }
        })
    
    return chunks


# ===========================================================================
# 핸들러: 등급별 구현
# ===========================================================================

def handle_tier_implementations(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """tier_implementations 처리 - 국가/호텔명 정보 포함으로 검색 정확도 향상"""
    chunks = []
    chain = context.get("chain", "UNKNOWN")
    hotel_id_map = context.get("hotel_id_map", {})  # hotel_id → 호텔 정보 매핑
    
    impls = data if isinstance(data, list) else [data]
    
    for impl in impls[:10]:
        if not isinstance(impl, dict):
            continue
            
        hotel_id = impl.get("hotel_id", "Unknown")
        tier_level = impl.get("tier_level", "N/A")
        impl_chain = impl.get("chain", chain)
        
        # hotel_id_map에서 호텔 정보 조회 (우선)
        hotel_info = hotel_id_map.get(hotel_id, {})
        hotel_name = hotel_info.get("name", "")
        hotel_name_ko = hotel_info.get("name_ko", "")
        country = hotel_info.get("country", "")
        city = hotel_info.get("city", "")
        
        # extra_attributes에서 보완 (폴백)
        extra = impl.get("extra_attributes", {})
        if not hotel_name:
            hotel_name = extra.get("hotel_name", "")
        if not country:
            country = extra.get("country", "")
        region = extra.get("region", "")
        
        content = f"""
호텔별 멤버십 혜택 구현
"""
        # 실제 호텔명이 있으면 우선 표시
        if hotel_name:
            content += f"호텔: {hotel_name}\n"
            if hotel_name_ko and hotel_name_ko != hotel_name:
                content += f"호텔 (한글명): {hotel_name_ko}\n"
        content += f"호텔 ID: {hotel_id}\n"
        
        # 국가/지역 정보 (검색 매칭에 중요)
        if country:
            content += f"국가: {country}\n"
        if city:
            content += f"도시: {city}\n"
        if region:
            content += f"지역: {region}\n"
            
        content += f"""체인: {impl_chain}
등급: {tier_level}
라운지 이용: {'가능' if impl.get('lounge_access') else '불가'}
조식 포함: {'포함' if impl.get('breakfast_included') else '미포함'}
조식 장소: {impl.get('breakfast_venue', 'N/A')}

혜택 상세:
"""
        
        # 업그레이드 정책 (upgrade_policy, suite_upgrade_available)
        upgrade_policy = impl.get("upgrade_policy")
        if upgrade_policy:
            content += f"업그레이드 정책: {upgrade_policy}\n"
        if impl.get("suite_upgrade_available"):
            content += "스위트 업그레이드: 가능 ✨\n"
        
        # 조식 상세 (breakfast_value)
        breakfast_value = impl.get("breakfast_value")
        if isinstance(breakfast_value, dict):
            amount = breakfast_value.get("amount")
            currency = breakfast_value.get("currency", "")
            if amount:
                content += f"조식 가치: {amount:,} {currency}\n"
        
        # 라운지 시간 (lounge_hours)
        lounge_hours = impl.get("lounge_hours")
        if lounge_hours:
            content += f"라운지 운영: {lounge_hours}\n"
        
        content += "\n혜택 상세:\n"
        
        # 혜택 오버라이드
        overrides = impl.get("benefit_overrides", [])
        for override in overrides[:5]:
            if isinstance(override, dict):
                category = override.get("benefit_category", "N/A")
                detail = override.get("implementation_detail", "")[:150]
                content += f"- {category}: {detail}\n"
                
                # 팁 추가
                tips = override.get("tips", [])
                for tip in tips[:2]:
                    content += f"  → {tip}\n"
        
        # 검증 정보 (last_verified) - 정보 신선도 표시
        last_verified = impl.get("last_verified")
        if last_verified:
            content += f"\n마지막 확인: {last_verified}\n"
        
        content += DISCLAIMER_SHORT
        
        # 메타데이터에도 국가 정보 포함
        metadata = {
            "type": "tier_implementation",
            "hotel_id": hotel_id,
            "tier_level": tier_level
        }
        if country:
            metadata["country"] = country
        if hotel_name:
            metadata["hotel_name"] = hotel_name
        
        chunks.append({
            "content": content.strip(),
            "metadata": metadata
        })
    
    return chunks


# ===========================================================================
# 핸들러: 크레딧 카드
# ===========================================================================

def handle_credit_cards(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """credit_cards 처리 (확장: Phase 3 - 여행 특화 혜택 포함)"""
    chunks = []
    chain = context.get("chain", "UNKNOWN")
    
    cards = data if isinstance(data, list) else [data]
    
    for card in cards[:5]:
        if not isinstance(card, dict):
            continue
            
        card_name = card.get("card_name", "N/A")
        card_chain = card.get("chain", chain)
        card_type = card.get("card_type", "")
        issuer = card.get("issuer", "N/A")
        issuer_code = card.get("issuer_code", "")
        
        # 스키마 구조: AnnualFee.total (Money 객체)
        # 하위 호환성: 레거시 annual_fee.amount도 지원
        annual_fee = card.get("annual_fee", {})
        if isinstance(annual_fee, dict):
            # 스키마 구조: annual_fee.total.amount
            total_fee = annual_fee.get("total", annual_fee)  # 폴백: 직접 접근
            if isinstance(total_fee, dict):
                fee_amount = total_fee.get("amount", "N/A")
                fee_currency = total_fee.get("currency", "KRW")
            else:
                fee_amount = annual_fee.get("amount", "N/A")
                fee_currency = annual_fee.get("currency", "KRW")
            
            # 상세 연회비 정보
            base_fee = annual_fee.get("base_fee", {})
            partner_fee = annual_fee.get("partner_fee", {})
            family_fee = annual_fee.get("family_card_fee", {})
            waiver_conds = annual_fee.get("waiver_conditions", [])
        else:
            fee_amount = annual_fee
            fee_currency = "KRW"
            base_fee = partner_fee = family_fee = {}
            waiver_conds = []
        
        content = f"""
신용카드: {card_name}
발급사: {issuer}"""
        
        if issuer_code:
            content += f" ({issuer_code})"
        
        # 연회비 표시
        if isinstance(fee_amount, (int, float)):
            content += f"\n연회비: {fee_amount:,} {fee_currency}\n"
        else:
            content += f"\n연회비: {fee_amount} {fee_currency}\n"
        
        # 상세 연회비 (스키마 구조 반영)
        if base_fee and isinstance(base_fee, dict) and base_fee.get("amount"):
            content += f"  - 기본: {base_fee.get('amount'):,} {base_fee.get('currency', '')}\n"
        if partner_fee and isinstance(partner_fee, dict) and partner_fee.get("amount"):
            content += f"  - 제휴: {partner_fee.get('amount'):,} {partner_fee.get('currency', '')}\n"
        if family_fee and isinstance(family_fee, dict) and family_fee.get("amount"):
            content += f"  - 가족카드: {family_fee.get('amount'):,} {family_fee.get('currency', '')}\n"
        if waiver_conds:
            # Handle both list of strings and list of dicts
            waiver_strs = []
            for item in waiver_conds[:2]:
                if isinstance(item, dict):
                    waiver_strs.append(item.get("summary", item.get("condition", str(item))))
                else:
                    waiver_strs.append(str(item))
            content += f"  - 면제 조건: {', '.join(waiver_strs)}\n"
        
        # 카드 유형 (Phase 3)
        if card_type:
            type_labels = {
                "HOTEL_PLCC": "호텔 제휴카드",
                "AIRLINE_PLCC": "항공 제휴카드",
                "TRAVEL_PREMIUM": "프리미엄 여행카드",
                "GENERAL_REWARDS": "리워드 카드"
            }
            content += f"카드 유형: {type_labels.get(card_type, card_type)}\n"
        
        # 연계 프로그램
        if card_chain and card_chain != "OTHER":
            content += f"연계 호텔: {card_chain}\n"
        
        linked_airline = card.get("linked_airline")
        linked_program = card.get("linked_airline_program")
        if linked_airline:
            content += f"연계 항공사: {linked_airline}\n"
            if linked_program:
                content += f"마일리지 프로그램: {linked_program}\n"
        
        # 등급 혜택
        granted_tier = card.get("granted_membership_tier")
        if granted_tier:
            content += f"제공 호텔 등급: {granted_tier}\n"
        
        granted_airline_tier = card.get("granted_airline_tier")
        if granted_airline_tier:
            content += f"제공 항공 등급: {granted_airline_tier}\n"
        
        # 마일리지 적립 (Phase 3)
        miles_rate = card.get("miles_earning_rate")
        if miles_rate:
            content += f"마일리지 적립: {miles_rate}\n"
        
        bonus_categories = card.get("bonus_miles_categories", [])
        if bonus_categories:
            content += f"보너스 적립 카테고리: {', '.join(bonus_categories)}\n"
        
        # 가입/기념일 보너스
        welcome_bonus = card.get("welcome_bonus")
        welcome_points = card.get("welcome_bonus_points")
        welcome_miles = card.get("welcome_bonus_miles")
        
        if welcome_bonus or welcome_points or welcome_miles:
            content += "\n가입 혜택:\n"
            if welcome_bonus:
                content += f"  - {welcome_bonus}\n"
            if welcome_points:
                content += f"  - 가입 보너스: {welcome_points:,} 포인트\n"
            if welcome_miles:
                content += f"  - 가입 보너스: {welcome_miles:,} 마일\n"
        
        # 라운지 혜택 (Phase 3)
        lounge_access = card.get("lounge_access", [])
        lounge_visits = card.get("lounge_visits_per_year")
        lounge_guest = card.get("lounge_guest_allowed", False)
        
        if lounge_access or lounge_visits:
            content += "\n라운지 혜택:\n"
            if lounge_access:
                # Handle both list of strings and list of dicts
                lounge_names = []
                for item in lounge_access[:5]:
                    if isinstance(item, dict):
                        lounge_names.append(item.get("lounge_name", item.get("name", str(item))))
                    else:
                        lounge_names.append(str(item))
                content += f"  - 이용 가능: {', '.join(lounge_names)}\n"
            if lounge_visits:
                content += f"  - 연간 이용: {lounge_visits}회\n"
            if lounge_guest:
                content += f"  - 동반자 이용: 가능\n"
        
        # 공항 서비스 (Phase 3)
        airport_services = []
        if card.get("airport_valet"):
            airport_services.append("발렛")
        if card.get("airport_fast_track"):
            airport_services.append("패스트트랙")
        if card.get("airport_transfer"):
            airport_services.append("공항 샌딩")
        
        if airport_services:
            content += f"\n공항 서비스: {', '.join(airport_services)}\n"
        
        # 여행 보험 (Phase 3)
        if card.get("travel_insurance"):
            insurance_detail = card.get("travel_insurance_details", "여행자 보험 포함")
            content += f"여행 보험: {insurance_detail}\n"
        
        # 컨시어지/호텔 서비스 (Phase 3)
        if card.get("concierge_service"):
            content += "컨시어지: 24시간 이용 가능\n"
        
        hotel_status = card.get("hotel_status_benefit")
        if hotel_status:
            content += f"호텔 특별 혜택: {hotel_status}\n"
        
        # 기존 혜택 목록
        benefits = card.get("benefits", card.get("card_benefits", []))
        if benefits:
            content += "\n주요 혜택:\n"
            for benefit in benefits[:7]:
                if isinstance(benefit, dict):
                    ben_name = benefit.get('name', benefit.get('benefit_name', 'N/A'))
                    content += f"  - {ben_name}\n"
                elif isinstance(benefit, str):
                    content += f"  - {benefit}\n"
        
        # extra_attributes 주요 정보 출력 (검색 누락 방지)
        extra_attrs = card.get("extra_attributes", {})
        if isinstance(extra_attrs, dict):
            target_members = extra_attrs.get("target_members", [])
            benefit_period = extra_attrs.get("benefit_period", "")
            hotel_count = extra_attrs.get("participating_hotel_count")
            
            if target_members or benefit_period or hotel_count:
                content += "\n프로그램 정보:\n"
                if target_members:
                    if isinstance(target_members, list):
                        content += f"  - 대상 회원: {', '.join(target_members[:3])}\n"
                    else:
                        content += f"  - 대상 회원: {target_members}\n"
                if benefit_period:
                    content += f"  - 혜택 기간: {benefit_period}\n"
                if hotel_count:
                    content += f"  - 제휴 호텔: {hotel_count}개\n"
        
        # evidence 정보 포함 (선택적)
        evidence = card.get("evidence", [])
        if evidence:
            content += format_evidence(evidence, max_items=2)
        
        content += DISCLAIMER_SHORT
        
        # 메타데이터에 추가 정보 포함
        metadata = {
            "type": "credit_card",
            "card_name": card_name,
            "issuer": issuer
        }
        if card_type:
            metadata["card_type"] = card_type
        if linked_airline:
            metadata["linked_airline"] = linked_airline
        
        chunks.append({
            "content": content.strip(),
            "metadata": metadata
        })
    
    return chunks


# ===========================================================================
# 핸들러: 구독 프로그램
# ===========================================================================

def handle_subscription_programs(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """subscription_programs 처리"""
    chunks = []
    chain = context.get("chain", "UNKNOWN")
    
    programs = data if isinstance(data, list) else [data]
    
    for program in programs[:3]:
        if not isinstance(program, dict):
            continue
            
        program_name = program.get("program_name", "N/A")
        
        content = f"""
구독 프로그램: {program_name}
체인: {program.get('chain', chain)}
기본 멤버십 필요: {program.get('requires_base_membership', 'N/A')}
기본 프로그램: {program.get('base_program_name', 'N/A')}
"""
        
        # 플랜 (스키마: SubscriptionPlan.prices -> SubscriptionPlanPrice)
        plans = program.get("plans", [])
        for plan in plans[:5]:
            if isinstance(plan, dict):
                plan_name = plan.get("plan_name", "N/A")
                prices = plan.get("prices", [])
                price_str = ""

                # 가격 처리 개선 (스키마에 맞춤)
                if prices:
                    for p in prices[:1]:  # 첫 번째 가격만
                        if isinstance(p, dict):
                            billing_cycle = p.get("billing_cycle", "YEARLY")
                            price_info = p.get("price", {})
                            if isinstance(price_info, dict):
                                amount = price_info.get("amount", "N/A")
                                currency = price_info.get("currency", "")

                                # 결제 주기를 한국어로 변환
                                cycle_kr = {
                                    "YEARLY": "년",
                                    "MONTHLY": "월",
                                    "QUARTERLY": "분기",
                                    "WEEKLY": "주"
                                }.get(billing_cycle, billing_cycle.lower())

                                if amount != "N/A" and currency:
                                    price_str = f"{amount} {currency}/{cycle_kr}"
                                else:
                                    price_str = "가격 정보 없음"
                            else:
                                price_str = str(price_info) if price_info else "가격 정보 없음"

                content += f"\n플랜: {plan_name}\n가격: {price_str}\n"
                
                # 플랜 혜택
                plan_benefits = plan.get("benefits", [])
                if plan_benefits:
                    content += "혜택:\n"
                    for pb in plan_benefits[:3]:
                        if isinstance(pb, dict):
                            content += f"- {pb.get('name', 'N/A')}\n"
        
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "subscription_program",
                "program_name": program_name
            }
        })
    
    return chunks


# ===========================================================================
# 핸들러: 프로모션
# ===========================================================================

def handle_promotions(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """promotions 처리"""
    chunks = []
    chain = context.get("chain", "UNKNOWN")
    
    promos = data if isinstance(data, list) else [data]
    
    for promo in promos[:5]:
        if not isinstance(promo, dict):
            continue
            
        title = promo.get("title", "N/A")
        
        content = f"""
프로모션: {title}
체인: {promo.get('chain', chain)}
대상: {promo.get('target_audience', 'N/A')}
기간: {promo.get('valid_from', 'N/A')} ~ {promo.get('valid_until', 'N/A')}
지역: {', '.join(promo.get('regions', []) or ['N/A'])}
설명: {promo.get('description', 'N/A')}
"""
        
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "promotion",
                "title": title
            }
        })
    
    return chunks


# ===========================================================================
# 핸들러: 가격/포인트 (pricing, pricing_analysis)
# ===========================================================================

def handle_pricing(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """pricing, pricing_2026 등 다양한 형식 처리"""
    chunks = []
    hotel_name, hotel_name_ko, chain = get_hotel_info(context)

    if data is None:
        return chunks

    # --- 리스트 구조 처리 (raw_pricing_data 등) ---
    if isinstance(data, list):
        for item in data[:10]:
            if not isinstance(item, dict):
                continue

            room_type = item.get("room_type_code", item.get("room_type", ""))
            room_name = item.get("room_type_full_name", "")
            rate_type = item.get("rate_type", "")
            rate_krw = item.get("rate_krw", 0)
            rate_usd = item.get("rate_usd_approx", 0)

            content = format_hotel_header(hotel_name, hotel_name_ko, chain)
            content += f"객실 유형: {room_type}\n"
            if room_name:
                content += f"객실명: {room_name}\n"
            if rate_type:
                content += f"요금 유형: {rate_type}\n"

            content += f"가격:\n"
            if rate_krw:
                content += f"  - KRW: ₩{rate_krw:,}\n"
            if rate_usd:
                content += f"  - USD: ${rate_usd}\n"

            content += DISCLAIMER_PRICE

            chunks.append({
                "content": content.strip(),
                "metadata": {
                    "type": "room_pricing_raw",
                    "hotel_name": hotel_name,
                    "room_type": room_type,
                    "rate_krw": rate_krw
                }
            })

        return chunks

    # 딕셔너리 구조가 아니면 빈 배열 반환
    if not isinstance(data, dict):
        return chunks

    # --- 형식 1: annual_statistics 구조 (Westin 등) ---
    annual_stats = data.get("annual_statistics", {})
    points_stats = annual_stats.get("points", {})
    
    if points_stats:
        min_points = points_stats.get("minimum", {})
        max_points = points_stats.get("maximum", {})
        avg_points = points_stats.get("average_estimate")
        cash_stats = annual_stats.get("cash", {})
        
        content = format_hotel_header(hotel_name, hotel_name_ko, chain)
        content += f"""예약 유형: 포인트 숙박

포인트 필요량:
  - 최소: {min_points.get('points', 'N/A'):,}P ({min_points.get('period', '비수기 평일')})
  - 최대: {max_points.get('points', 'N/A'):,}P ({max_points.get('period', '성수기/주말')})
"""
        if avg_points:
            content += f"  - 평균: {avg_points:,}P (추정)\n"
        
        if cash_stats:
            min_cash = cash_stats.get("minimum", {})
            content += f"""
현금 가격 비교:
  - 최저가: ₩{min_cash.get('amount', 'N/A'):,} ({min_cash.get('period', '')})
"""
        
        blackout = data.get("points_blackout_dates", [])
        if blackout:
            content += f"\n포인트 예약 불가 기간: {', '.join(blackout[:5])}"
        
        content += DISCLAIMER_PRICE
        
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "points_pricing",
                "hotel_name": hotel_name,
                "hotel_name_ko": hotel_name_ko,
                "min_points": min_points.get("points"),
                "max_points": max_points.get("points")
            }
        })
    
    # --- 형식 2: points_rates 배열 구조 (JW Marriott 등) ---
    points_rates = data.get("points_rates", [])
    
    if points_rates:
        # 포인트 범위 계산
        all_min = []
        all_max = []
        for rate in points_rates:
            if rate.get("min_points"):
                all_min.append(rate["min_points"])
            if rate.get("max_points"):
                all_max.append(rate["max_points"])
        
        min_points = min(all_min) if all_min else None
        max_points = max(all_max) if all_max else None
        
        content = format_hotel_header(hotel_name, hotel_name_ko, chain)
        content += f"""예약 유형: 포인트 숙박

포인트 필요량:
  - 최소: {min_points:,}P (연간)
  - 최대: {max_points:,}P (연간)
"""
        
        # 현금 가격도 있으면 추가
        cash_rates = data.get("cash_rates", [])
        if cash_rates:
            all_cash_min = [r.get("min_krw") for r in cash_rates if r.get("min_krw")]
            all_cash_max = [r.get("max_krw") for r in cash_rates if r.get("max_krw")]
            if all_cash_min:
                content += f"""
현금 가격 비교:
  - 최저가: ₩{min(all_cash_min):,} (연간)
  - 최고가: ₩{max(all_cash_max):,} (연간)
"""
        
        # 월별 요약 추가
        content += "\n월별 포인트:\n"
        for rate in points_rates[:6]:
            month = rate.get("month", "?")
            min_p = rate.get("min_points", "?")
            max_p = rate.get("max_points", "?")
            content += f"  - {month}월: {min_p:,}P ~ {max_p:,}P\n"
        
        if len(points_rates) > 6:
            content += f"  ... (외 {len(points_rates) - 6}개월)\n"
        
        content += DISCLAIMER_PRICE
        
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "points_pricing",
                "hotel_name": hotel_name,
                "hotel_name_ko": hotel_name_ko,
                "min_points": min_points,
                "max_points": max_points
            }
        })
    
    # --- 월별 데이터 (기존) ---
    monthly_data = data.get("monthly_data", {})
    if monthly_data:
        monthly_content = format_hotel_header(hotel_name, hotel_name_ko, chain)
        monthly_content += "월별 포인트 정보:\n"
        
        for month, mdata in list(monthly_data.items())[:6]:
            points_range = mdata.get("points_range", "N/A")
            monthly_content += f"  - {month}: {points_range}\n"
        
        monthly_content += DISCLAIMER_SHORT
        
        chunks.append({
            "content": monthly_content.strip(),
            "metadata": {
                "type": "points_monthly",
                "hotel_name": hotel_name
            }
        })
    
    return chunks


def handle_pricing_analysis(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """pricing_analysis 형식 처리 (Josun Palace 등)"""
    chunks = []
    hotel_name, hotel_name_ko, chain = get_hotel_info(context)

    # 리스트 구조인 경우 처리 (ClassicTravel 등)
    if isinstance(data, list):
        for item in data[:10]:
            if not isinstance(item, dict):
                continue

            hotel_id = item.get("hotel_id", "")
            item_hotel_name = item.get("hotel_name", hotel_name)
            search_date = item.get("search_date", "")
            stay_nights = item.get("stay_nights", 1)
            currency = item.get("currency", "KRW")

            content = format_hotel_header(item_hotel_name, hotel_name_ko, chain)
            content += f"호텔 ID: {hotel_id}\n"
            content += f"검색 날짜: {search_date}\n"
            content += f"숙박 기간: {stay_nights}박\n\n"

            room_rates = item.get("room_rates", [])
            if room_rates:
                content += "객실 요금:\n"
                for rate in room_rates[:5]:
                    room_type = rate.get("room_type", "")
                    rate_plan = rate.get("rate_plan", "")
                    rate_desc = rate.get("rate_plan_description", "")
                    price_krw = rate.get("price_krw", 0)

                    content += f"  - {room_type}\n"
                    content += f"    요금제: {rate_plan}\n"
                    if rate_desc:
                        content += f"    설명: {rate_desc}\n"
                    content += f"    가격: ₩{price_krw:,}\n"

            content += DISCLAIMER_PRICE

            chunks.append({
                "content": content.strip(),
                "metadata": {
                    "type": "room_pricing",
                    "hotel_name": item_hotel_name,
                    "hotel_id": hotel_id,
                    "currency": currency
                }
            })

        return chunks

    # 기존 딕셔너리 구조 처리
    if not isinstance(data, dict):
        return chunks

    points_stats = data.get("points_price_stats", {})
    cash_stats = data.get("cash_price_stats", {})

    if not points_stats:
        return chunks
    
    min_points = points_stats.get("lowest_points")
    max_points = points_stats.get("highest_points")
    avg_points = points_stats.get("annual_average_estimated")
    min_period = points_stats.get("lowest_points_period", "비수기 평일")
    max_period = points_stats.get("highest_points_period", "성수기/주말")
    
    content = format_hotel_header(hotel_name, hotel_name_ko, chain)
    content += f"""예약 유형: 포인트 숙박

포인트 필요량:
  - 최소: {min_points:,}P ({min_period})
  - 최대: {max_points:,}P ({max_period})
"""
    if avg_points:
        content += f"  - 평균: {avg_points:,}P (추정)\n"
    
    # 현금 가격
    if cash_stats:
        min_cash = cash_stats.get("lowest_price")
        min_cash_period = cash_stats.get("lowest_price_period", "")
        if min_cash:
            content += f"""
현금 가격 비교:
  - 최저가: ₩{min_cash:,} ({min_cash_period})
"""
    
    # 시즌별 패턴
    seasonal = data.get("seasonal_patterns", [])
    if seasonal:
        content += "\n시즌별 가격 패턴:\n"
        for pattern in seasonal[:4]:
            content += f"  - {pattern.get('season', '')}: {pattern.get('price_range', '')} ({pattern.get('period', '')})\n"
    
    content += DISCLAIMER_PRICE
    
    chunks.append({
        "content": content.strip(),
        "metadata": {
            "type": "points_pricing",
            "hotel_name": hotel_name,
            "hotel_name_ko": hotel_name_ko,
            "min_points": min_points,
            "max_points": max_points
        }
    })
    
    # 인사이트
    insights = data.get("pricing_insights", [])
    if insights:
        insight_content = format_hotel_header(hotel_name, hotel_name_ko, chain)
        insight_content += "예약 팁:\n"
        
        for insight in insights[:5]:
            insight_content += f"  - {insight}\n"
        
        insight_content += DISCLAIMER_SHORT
        
        chunks.append({
            "content": insight_content.strip(),
            "metadata": {
                "type": "pricing_insight",
                "hotel_name": hotel_name
            }
        })
    
    return chunks


# ===========================================================================
# 핸들러: 혜택
# ===========================================================================

def handle_benefits(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """benefits 처리"""
    chunks = []
    
    benefits = data if isinstance(data, list) else [data]
    
    for benefit in benefits[:10]:
        if not isinstance(benefit, dict):
            continue
            
        ben_name = benefit.get("benefit_name", benefit.get("name", "N/A"))
        
        content = f"""
혜택: {ben_name}
카테고리: {benefit.get('category', 'N/A')}
설명: {benefit.get('description', benefit.get('details', 'N/A'))}
"""
        
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "benefit",
                "benefit_name": ben_name
            }
        })
    
    return chunks


# ===========================================================================
# 핸들러: Best Rate Guarantee
# ===========================================================================

def handle_best_rate_guarantee(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """best_rate_guarantee 처리 (스키마: BestRateGuarantee, BRGRule, BRGRemedy)
    
    청크 분리 전략:
    1. 프로그램 개요 청크 (기본 정보, 제외 사항)
    2. 규칙별 청크 (각 BRGRule을 개별 청크로)
    """
    chunks = []
    chain = context.get("chain", "UNKNOWN")
    
    if not isinstance(data, dict):
        return chunks
    
    program_name = data.get("program_name", "Best Rate Guarantee")
    brg_chain = data.get("chain", chain)
    
    # === 청크 1: 프로그램 개요 ===
    overview_content = f"""
최저가 보장 프로그램: {program_name}
체인: {brg_chain}
멤버십 필요: {"예" if data.get("requires_membership") else "아니오"}
"""
    
    # 제외 사항 (스키마 필드)
    excluded_regions = data.get("excluded_regions", [])
    excluded_brands = data.get("excluded_brands", [])
    excluded_hotels = data.get("excluded_hotels", [])
    
    if excluded_regions:
        overview_content += f"제외 지역: {', '.join(excluded_regions[:5])}\n"
    if excluded_brands:
        overview_content += f"제외 브랜드: {', '.join(excluded_brands[:5])}\n"
    if excluded_hotels:
        overview_content += f"제외 호텔: {', '.join(excluded_hotels[:3])}\n"
    
    # 약관
    if data.get("governing_law"):
        overview_content += f"\n준거법: {data.get('governing_law')}\n"
    if data.get("arbitration_clause"):
        overview_content += "중재 조항: 포함\n"
    
    # 마지막 업데이트
    if data.get("last_updated"):
        overview_content += f"마지막 업데이트: {data.get('last_updated')}\n"
    
    overview_content += DISCLAIMER_SHORT
    
    chunks.append({
        "content": overview_content.strip(),
        "metadata": {
            "type": "best_rate_guarantee_overview",
            "program_name": program_name,
            "chain": brg_chain
        }
    })
    
    # === 청크 2+: 규칙별 상세 (스키마: BRGRule) ===
    rules = data.get("rules", [])
    for rule in rules[:5]:  # 최대 5개 규칙
        if not isinstance(rule, dict):
            continue
        
        rule_name = rule.get("rule_name", "N/A")
        summary = rule.get("summary", "")
        
        rule_content = f"""
{program_name} - {rule_name}
체인: {brg_chain}

"""
        if summary:
            rule_content += f"요약: {summary}\n\n"
        
        # 클레임 조건 (스키마 필드)
        claim_window = rule.get("claim_window")
        min_hours = rule.get("minimum_hours_before_checkin")
        rate_diff = rule.get("rate_difference_threshold_percent")
        max_rooms = rule.get("max_rooms_per_claim")
        
        if claim_window or min_hours or rate_diff or max_rooms:
            rule_content += "클레임 조건:\n"
            if claim_window:
                rule_content += f"  - 클레임 가능 기간: {claim_window}\n"
            if min_hours:
                rule_content += f"  - 체크인 전 최소: {min_hours}시간\n"
            if rate_diff:
                rule_content += f"  - 최소 가격 차이: {rate_diff}%\n"
            if max_rooms:
                rule_content += f"  - 클레임당 최대 객실: {max_rooms}실\n"
        
        # 비교 기준
        comparison = rule.get("comparison_criteria", [])
        if comparison:
            rule_content += f"\n비교 기준:\n"
            for c in comparison[:6]:
                rule_content += f"  - {c}\n"
        
        # 채널 요구사항
        channel_reqs = rule.get("channel_requirements", [])
        if channel_reqs:
            rule_content += f"\n예약 채널: {', '.join(channel_reqs)}\n"
        
        # 적용/제외 요금
        eligible_rates = rule.get("eligible_rates", [])
        ineligible_rates = rule.get("ineligible_rates", [])
        if eligible_rates:
            rule_content += f"\n적용 요금:\n"
            for r in eligible_rates[:5]:
                rule_content += f"  - {r}\n"
        if ineligible_rates:
            rule_content += f"\n제외 요금:\n"
            for r in ineligible_rates[:8]:
                rule_content += f"  - {r}\n"
        
        # 보상 (스키마: BRGRemedy)
        remedies = rule.get("remedies", [])
        if remedies:
            rule_content += "\n보상:\n"
            for remedy in remedies[:3]:
                if isinstance(remedy, dict):
                    r_type = remedy.get("type", "N/A")
                    r_desc = remedy.get("description", "")
                    rule_content += f"  [{r_type}] {r_desc}\n"
                    
                    # 가치 (BenefitValue 구조)
                    value = remedy.get("value", {})
                    if isinstance(value, dict):
                        v_type = value.get("type")
                        v_text = value.get("text", "")
                        if v_text:
                            rule_content += f"    - 가치: {v_text}\n"
                        elif v_type == "PERCENT" and value.get("percent"):
                            rule_content += f"    - 가치: {value.get('percent')}%\n"
                        elif v_type == "POINTS" and value.get("points"):
                            rule_content += f"    - 가치: {value.get('points'):,}P\n"
                    
                    # 최대 보상 (Money 구조)
                    max_val = remedy.get("max_value", {})
                    if isinstance(max_val, dict) and max_val.get("amount"):
                        rule_content += f"    - 최대: {max_val.get('amount'):,} {max_val.get('currency', '')}\n"
        
        # 추가 조건
        conditions = rule.get("conditions", [])
        if conditions:
            rule_content += "\n추가 조건:\n"
            for cond in conditions[:5]:
                if isinstance(cond, dict):
                    cond_summary = cond.get("summary", "")
                    if cond_summary:
                        rule_content += f"  - {cond_summary}\n"
        
        rule_content += DISCLAIMER_SHORT
        
        if len(rule_content) > 100:
            chunks.append({
                "content": rule_content.strip(),
                "metadata": {
                    "type": "best_rate_guarantee_rule",
                    "program_name": program_name,
                    "rule_name": rule_name,
                    "chain": brg_chain
                }
            })
    
    # === 하위 호환: 기존 conditions 형식 지원 (rules가 없는 경우) ===
    conditions = data.get("conditions", [])
    if conditions and not rules:
        cond_content = f"""
{program_name} - 이용 조건
체인: {brg_chain}

이용 조건:
"""
        for cond in conditions[:5]:
            if isinstance(cond, dict):
                cond_content += f"  - {cond.get('description', cond.get('summary', cond))}\n"
            else:
                cond_content += f"  - {cond}\n"
        
        exclusions = data.get("exclusions", [])
        if exclusions:
            cond_content += "\n제외 사항:\n"
            for exc in exclusions[:5]:
                if isinstance(exc, str):
                    cond_content += f"  - {exc}\n"
        
        cond_content += DISCLAIMER_SHORT
        
        chunks.append({
            "content": cond_content.strip(),
            "metadata": {
                "type": "best_rate_guarantee_conditions",
                "program_name": program_name,
                "chain": brg_chain
            }
        })
    
    # === 청크: 클레임 거부 사유 (extra_attributes) ===
    extra_attrs = data.get("extra_attributes", {})
    if extra_attrs and isinstance(extra_attrs, dict):
        rejection_reasons = extra_attrs.get("claim_rejection_reasons", [])
        if rejection_reasons:
            rejection_content = f"""
{program_name} - 클레임 거부 사유
체인: {brg_chain}

클레임이 거부될 수 있는 사유:
"""
            for reason in rejection_reasons:
                rejection_content += f"  - {reason}\n"
            
            # 추가 속성
            if extra_attrs.get("nj_resident_exception"):
                rejection_content += f"\n뉴저지 거주자 예외: {extra_attrs.get('nj_resident_exception')}\n"
            if extra_attrs.get("modification_rights"):
                rejection_content += f"프로그램 수정 권한: {extra_attrs.get('modification_rights')}\n"
            if extra_attrs.get("employee_exclusion"):
                rejection_content += f"직원 제외: {extra_attrs.get('employee_exclusion')}\n"
            
            rejection_content += DISCLAIMER_SHORT
            
            chunks.append({
                "content": rejection_content.strip(),
                "metadata": {
                    "type": "best_rate_guarantee_rejection",
                    "program_name": program_name,
                    "chain": brg_chain
                }
            })
    
    return chunks


# ===========================================================================
# 핸들러: Channel Implementations
# ===========================================================================

def handle_channel_implementations(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """channel_implementations 처리 - 국가/호텔명 정보 포함으로 검색 정확도 향상"""
    chunks = []
    chain = context.get("chain", "UNKNOWN")
    
    impls = data if isinstance(data, list) else [data]
    
    for impl in impls[:10]:
        if not isinstance(impl, dict):
            continue
            
        program_name = impl.get("program_name", "N/A")
        hotel_id = impl.get("hotel_id", "N/A")
        
        # extra_attributes에서 국가/호텔명 추출 (검색 정확도 향상)
        extra = impl.get("extra_attributes", {})
        country = extra.get("country", "")
        hotel_name = extra.get("hotel_name", "")
        region = extra.get("region", "")
        
        content = f"""
채널 프로그램: {program_name}
"""
        # 실제 호텔명이 있으면 우선 표시
        if hotel_name:
            content += f"호텔: {hotel_name}\n"
        else:
            content += f"호텔 ID: {hotel_id}\n"
        
        # 국가/지역 정보 (검색 매칭에 중요)
        if country:
            content += f"국가: {country}\n"
        if region:
            content += f"지역: {region}\n"
            
        content += f"""채널: {impl.get('channel', 'DIRECT')}
"""
        
        # 혜택 오버라이드
        overrides = impl.get("benefit_overrides", [])
        if overrides:
            content += "\n혜택:\n"
            for override in overrides[:5]:
                if isinstance(override, dict):
                    category = override.get("benefit_category", "N/A")
                    detail = override.get("implementation_detail", "")[:100]
                    content += f"- {category}: {detail}\n"
                    
                    # 팁 추가
                    tips = override.get("tips", [])
                    for tip in tips[:2]:
                        content += f"  → {tip}\n"
        
        # 추가 혜택 (additional_benefits) 출력 - 검색 누락 방지
        additional = impl.get("additional_benefits", [])
        if additional:
            content += "\n추가 혜택:\n"
            for benefit in additional[:5]:
                if isinstance(benefit, dict):
                    ben_name = benefit.get("name", "N/A")
                    ben_desc = (benefit.get("description", "") or "")[:120]
                    ben_category = benefit.get("category", "")
                    
                    content += f"- {ben_name}"
                    if ben_category:
                        content += f" [{ben_category}]"
                    if ben_desc and ben_desc != ben_name:
                        content += f": {ben_desc}"
                    content += "\n"
                    
                    # 가치 표시
                    value = benefit.get("value", {})
                    if isinstance(value, dict):
                        v_type = value.get("type")
                        if v_type == "PERCENT" and value.get("percent"):
                            content += f"  → 할인율: {value.get('percent')}%\n"
                        elif v_type == "POINTS" and value.get("points"):
                            content += f"  → 포인트: {value.get('points'):,}P\n"
        
        # 일반 팁 (general_tips) - 검색 품질 향상
        general_tips = impl.get("general_tips", [])
        if general_tips:
            content += "\n이용 팁:\n"
            for tip in general_tips[:5]:
                content += f"  💡 {tip}\n"
        
        # 예약 관련 정보 (booking_notes, contact_for_benefits)
        booking_notes = impl.get("booking_notes")
        if booking_notes:
            content += f"\n예약 시 참고: {booking_notes}\n"
        
        contact = impl.get("contact_for_benefits")
        if contact:
            content += f"혜택 문의: {contact}\n"
        
        # 검증 정보 (last_verified, verified_by) - 정보 신선도 표시
        last_verified = impl.get("last_verified")
        verified_by = impl.get("verified_by")
        if last_verified:
            content += f"\n마지막 확인: {last_verified}"
            if verified_by:
                content += f" ({verified_by})"
            content += "\n"
        
        content += DISCLAIMER_SHORT
        
        # 메타데이터에도 국가 정보 포함
        metadata = {
            "type": "channel_implementation",
            "program_name": program_name,
            "hotel_id": hotel_id,
            "chain": context.get("chain", "UNKNOWN")  # chain 정보 추가
        }
        if country:
            metadata["country"] = country
        if hotel_name:
            metadata["hotel_name"] = hotel_name
        if last_verified:
            metadata["last_verified"] = str(last_verified)
        
        chunks.append({
            "content": content.strip(),
            "metadata": metadata
        })
    
    return chunks


# ===========================================================================
# 핸들러: Channel Benefit Packages (FHR 등)
# ===========================================================================

def handle_channel_benefit_packages(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """channel_benefit_packages 처리 (FHR, THC 등) - 스키마: ChannelBenefitPackage"""
    chunks = []
    
    packages = data if isinstance(data, list) else [data]
    
    for pkg in packages[:5]:
        if not isinstance(pkg, dict):
            continue
            
        pkg_name = pkg.get("package_name", pkg.get("name", "N/A"))
        channel = pkg.get("channel", pkg.get("agent", "N/A"))
        
        content = f"""
혜택 패키지: {pkg_name}
채널: {channel}
"""
        
        # 특정 요금제 필요 여부
        if pkg.get("requires_specific_rate"):
            content += "특정 요금제 필요: 예\n"
            eligible_rates = pkg.get("eligible_rates", [])
            if eligible_rates:
                content += f"적용 가능 요금: {', '.join(eligible_rates)}\n"
        
        # 스키마 필드명: standard_benefits
        # 하위 호환: benefits, included_benefits도 지원
        benefits = pkg.get("standard_benefits", pkg.get("benefits", pkg.get("included_benefits", [])))
        if benefits:
            content += "\n포함 혜택:\n"
            for benefit in benefits[:8]:
                if isinstance(benefit, dict):
                    ben_name = benefit.get("name", benefit.get("benefit_name", "N/A"))
                    ben_desc = benefit.get("description", "")[:60]
                    ben_category = benefit.get("category", "")
                    
                    content += f"  - {ben_name}"
                    if ben_category:
                        content += f" [{ben_category}]"
                    if ben_desc:
                        content += f": {ben_desc}"
                    content += "\n"
                    
                    # 가치 표시 (BenefitValue 구조)
                    value = benefit.get("value", {})
                    if isinstance(value, dict):
                        v_type = value.get("type")
                        if v_type == "MONEY" and value.get("money"):
                            money = value.get("money", {})
                            content += f"    가치: {money.get('amount', 'N/A')} {money.get('currency', '')}\n"
                        elif v_type == "TEXT" and value.get("text"):
                            content += f"    가치: {value.get('text')}\n"
                        elif v_type == "PERCENT" and value.get("percent"):
                            content += f"    가치: {value.get('percent')}%\n"
                            
                elif isinstance(benefit, str):
                    content += f"  - {benefit}\n"
        
        content += DISCLAIMER_SHORT
        
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "channel_benefit_package",
                "package_name": pkg_name,
                "channel": channel
            }
        })
    
    return chunks


# ===========================================================================
# 핸들러: Member Rates (회원 요금)
# ===========================================================================

def handle_member_rates(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """member_rates 처리 (회원 전용 요금) - 스키마 MemberRate 필드 구조에 맞춤"""
    chunks = []
    chain = context.get("chain", "UNKNOWN")

    if data is None:
        return chunks

    rates = data if isinstance(data, list) else [data]

    for rate in rates[:5]:
        if not isinstance(rate, dict):
            continue

        rate_name = rate.get("rate_name", rate.get("name", "N/A"))

        content = f"""
회원 요금: {rate_name}
체인: {rate.get('chain', chain)}
"""

        # 할인율 (스키마 구조 반영)
        weekday_discount = rate.get("weekday_discount_percent")
        weekend_discount = rate.get("weekend_discount_percent")
        min_discount = rate.get("minimum_discount_percent")
        max_discount = rate.get("maximum_discount_percent")

        # 하위 호환성: 기존 필드도 지원
        legacy_discount = rate.get("discount_percentage", rate.get("discount"))

        if weekday_discount or weekend_discount:
            content += "할인율:\n"
            if weekday_discount:
                content += f"  - 평일: {weekday_discount}%\n"
            if weekend_discount:
                content += f"  - 주말: {weekend_discount}%\n"
        elif min_discount or max_discount:
            content += f"할인율: {min_discount or '?'}% ~ {max_discount or '?'}%\n"
        elif legacy_discount and legacy_discount != "N/A":
            content += f"할인율: {legacy_discount}%\n"

        # 필수 멤버십
        if rate.get("requires_membership", True):
            content += "멤버십 필요: 예\n"
            if rate.get("minimum_tier"):
                content += f"최소 등급: {rate.get('minimum_tier')}\n"

        # 적용 객실
        applies_to = rate.get("applies_to_room_types", [])
        excluded = rate.get("excluded_room_types", [])
        if applies_to:
            content += f"적용 객실: {', '.join(applies_to)}\n"
        if excluded:
            content += f"제외 객실: {', '.join(excluded)}\n"

        # 예약 채널
        channels = rate.get("eligible_channels", [])
        if channels:
            content += f"예약 채널: {', '.join(channels)}\n"

        # 제한사항
        max_rooms = rate.get("max_rooms")
        if max_rooms:
            content += f"최대 객실: {max_rooms}실\n"

        excluded_rate_types = rate.get("excluded_rate_types", [])
        if excluded_rate_types:
            content += f"제외 요금 유형: {', '.join(excluded_rate_types)}\n"

        excluded_hotels = rate.get("excluded_hotels", [])
        if excluded_hotels:
            content += f"제외 호텔: {', '.join(excluded_hotels[:3])}\n"

        # 중복 적용
        if rate.get("combinable_with_promotions"):
            content += "다른 프로모션과 중복 가능\n"

        # 하위 호환성: 기존 필드들
        legacy_conditions = rate.get("conditions", rate.get("eligibility"))
        if legacy_conditions and legacy_conditions != "N/A":
            content += f"적용 조건: {legacy_conditions}\n"

        if rate.get("description"):
            content += f"설명: {rate.get('description')}\n"

        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "member_rate",
                "rate_name": rate_name,
                "chain": rate.get("chain", chain)
            }
        })

    return chunks


# ===========================================================================
# 핸들러: 호텔 시설
# ===========================================================================

def handle_hotel_facilities(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """hotel_facilities, other_facilities, hotel_amenities_summary, 
    executive_lounge, pulse8_wellness 등 다양한 시설 데이터 처리
    
    지원 형태:
    1. 리스트 형태 (기존 hotel_facilities)
    2. 딕셔너리 형태 (executive_lounge, pulse8_wellness 등)
    3. 문자열 리스트 (hotel_amenities_summary)
    """
    chunks = []
    hotel_name, hotel_name_ko, chain = get_hotel_info(context)
    
    if data is None:
        return chunks
    
    content = format_hotel_header(hotel_name, hotel_name_ko, chain)
    
    # 데이터 형태에 따른 처리
    if isinstance(data, dict):
        # 딕셔너리 형태 (executive_lounge, pulse8_wellness 등)
        facility_name = data.get("name", data.get("lounge_name", "시설"))
        location = data.get("location", "")
        hours = data.get("operating_hours", "")
        
        content += f"시설: {facility_name}\n"
        if location:
            content += f"위치: {location}\n"
        if hours:
            content += f"운영시간: {hours}\n"
        
        # 전망
        if data.get("view"):
            content += f"전망: {data.get('view')}\n"
        
        # 서비스/시설 목록
        services = data.get("services", data.get("facilities", []))
        if services:
            content += "\n제공 서비스/시설:\n"
            for service in services[:10]:
                if isinstance(service, dict):
                    s_name = service.get("name", "N/A")
                    s_desc = service.get("description", "")
                    content += f"  - {s_name}"
                    if s_desc:
                        content += f": {s_desc[:60]}"
                    content += "\n"
                else:
                    content += f"  - {service}\n"
        
        # 드레스코드
        if data.get("dress_code"):
            content += f"\n드레스코드: {data.get('dress_code')}\n"
        
        # 연령 제한
        if data.get("age_restriction"):
            content += f"연령 제한: {data.get('age_restriction')}\n"
        
        # 메타데이터 타입 결정
        meta_type = "hotel_facility"
        if "lounge" in str(data).lower():
            meta_type = "executive_lounge"
        elif "wellness" in str(data).lower() or "pulse" in str(data).lower():
            meta_type = "wellness_facility"
        
    elif isinstance(data, list):
        # 리스트 형태
        facilities = data
        
        # 첫 번째 항목 확인하여 타입 결정
        first_item = facilities[0] if facilities else None
        
        if first_item and isinstance(first_item, str):
            # 문자열 리스트 (hotel_amenities_summary)
            content += "호텔 시설 및 서비스 요약:\n"
            for amenity in facilities[:20]:
                content += f"  ✓ {amenity}\n"
            meta_type = "hotel_amenities_summary"
        else:
            # 딕셔너리 리스트 (기존 hotel_facilities)
            content += "호텔 시설:\n"
            for facility in facilities[:15]:
                if isinstance(facility, dict):
                    name = facility.get("name", facility.get("facility_name", "N/A"))
                    desc = facility.get("description", "")
                    content += f"  - {name}"
                    if desc:
                        content += f": {desc[:60]}"
                    content += "\n"
                elif isinstance(facility, str):
                    content += f"  - {facility}\n"
            meta_type = "hotel_facilities"
    else:
        return chunks
    
    if len(content) > 100:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": meta_type,
                "hotel_name": hotel_name
            }
        })
    
    return chunks


# ===========================================================================
# 핸들러: 객실 유형
# ===========================================================================

def handle_room_types(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """room_types 처리"""
    chunks = []
    hotel_name, hotel_name_ko, chain = get_hotel_info(context)
    
    if data is None:
        return chunks
    
    rooms = data if isinstance(data, list) else [data]
    
    # 각 객실 유형을 청크로
    for room in rooms[:10]:
        if not isinstance(room, dict):
            continue
        
        room_name = room.get("name", room.get("room_name", "N/A"))
        room_name_ko = room.get("name_ko", room.get("name_localized", {}).get("ko"))
        
        content = format_hotel_header(hotel_name, hotel_name_ko, chain)
        content += f"""객실 유형: {room_name}
"""
        if room_name_ko:
            content += f"객실명 (한국어): {room_name_ko}\n"
        
        content += f"""면적: {room.get("area_sqm", room.get("size", "N/A"))}㎡
침대: {room.get("bed_type", "N/A")}
최대 투숙: {room.get("max_occupancy", "N/A")}명
뷰: {room.get("view", "N/A")}
카테고리: {room.get("category", "N/A")}
조식 포함: {'예' if room.get("breakfast_included") else '아니오'}
라운지: {'가능' if room.get("lounge_access") else '불가'}
"""
        
        # 특징
        features = room.get("features", [])
        if features:
            content += "특징:\n"
            for feat in features[:5]:
                content += f"  - {feat}\n"
        
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "room_type",
                "hotel_name": hotel_name,
                "room_name": room_name,
                "category": room.get("category")
            }
        })
    
    return chunks


# ===========================================================================
# 핸들러: 객실 어메니티
# ===========================================================================

def handle_room_amenities(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """room_common_amenities, room_common_features 처리"""
    chunks = []
    hotel_name, hotel_name_ko, chain = get_hotel_info(context)
    
    if data is None:
        return chunks
    
    content = format_hotel_header(hotel_name, hotel_name_ko, chain)
    content += "객실 공통 어메니티:\n"
    
    if isinstance(data, dict):
        for category, items in data.items():
            if isinstance(items, list):
                content += f"\n{category}:\n"
                for item in items[:8]:
                    content += f"  - {item}\n"
    elif isinstance(data, list):
        for item in data[:15]:
            content += f"  - {item}\n"
    
    if len(content) > 100:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "room_amenities",
                "hotel_name": hotel_name
            }
        })
    
    return chunks


# ===========================================================================
# 핸들러: 레스토랑
# ===========================================================================

def handle_restaurants(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """restaurants 처리"""
    chunks = []
    hotel_name, hotel_name_ko, chain = get_hotel_info(context)
    
    if data is None:
        return chunks
    
    restaurants = data if isinstance(data, list) else [data]
    
    for rest in restaurants[:5]:
        if not isinstance(rest, dict):
            continue
        
        rest_name = rest.get("name", rest.get("restaurant_name", "N/A"))
        
        content = format_hotel_header(hotel_name, hotel_name_ko, chain)
        content += f"""레스토랑: {rest_name}
유형: {rest.get("type", rest.get("cuisine_type", "N/A"))}
위치: {rest.get("location", "N/A")}
좌석수: {rest.get("seating", rest.get("capacity", "N/A"))}
"""
        
        # 운영 시간
        hours = rest.get("operating_hours", {})
        if hours:
            content += "운영 시간:\n"
            if isinstance(hours, dict):
                for period, time in hours.items():
                    content += f"  - {period}: {time}\n"
        
        # 메뉴/가격
        prices = rest.get("prices", rest.get("menu_prices", {}))
        if isinstance(prices, dict):
            content += "가격:\n"
            for item, price in list(prices.items())[:3]:
                content += f"  - {item}: ₩{price:,}\n" if isinstance(price, (int, float)) else f"  - {item}: {price}\n"
        
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "restaurant",
                "hotel_name": hotel_name,
                "restaurant_name": rest_name
            }
        })
    
    return chunks


# ===========================================================================
# 핸들러: 조식 옵션
# ===========================================================================

def handle_breakfast(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """breakfast_options 처리"""
    chunks = []
    hotel_name, hotel_name_ko, chain = get_hotel_info(context)
    
    if data is None:
        return chunks
    
    content = format_hotel_header(hotel_name, hotel_name_ko, chain)
    content += "조식 옵션:\n"
    
    if isinstance(data, dict):
        for key, value in data.items():
            if isinstance(value, dict):
                content += f"\n{key}:\n"
                for k, v in value.items():
                    content += f"  - {k}: {v}\n"
            else:
                content += f"  - {key}: {value}\n"
    elif isinstance(data, list):
        for item in data[:10]:
            if isinstance(item, dict):
                name = item.get("name", "N/A")
                price = item.get("price", "")
                content += f"  - {name}"
                if price:
                    content += f": ₩{price:,}" if isinstance(price, (int, float)) else f": {price}"
                content += "\n"
            else:
                content += f"  - {item}\n"
    
    if len(content) > 100:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "breakfast_options",
                "hotel_name": hotel_name
            }
        })
    
    return chunks


# ===========================================================================
# 핸들러: 평점
# ===========================================================================

def handle_ratings(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """ratings 처리"""
    chunks = []
    hotel_name, hotel_name_ko, chain = get_hotel_info(context)
    
    if data is None or not isinstance(data, dict):
        return chunks
    
    content = format_hotel_header(hotel_name, hotel_name_ko, chain)
    content += "호텔 평점:\n"
    
    for source, rating in data.items():
        if isinstance(rating, dict):
            score = rating.get("score", rating.get("rating", "N/A"))
            content += f"  - {source}: {score}\n"
        else:
            content += f"  - {source}: {rating}\n"
    
    if len(content) > 80:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "hotel_ratings",
                "hotel_name": hotel_name
            }
        })
    
    return chunks


# ===========================================================================
# 핸들러: 다이닝 프로그램
# ===========================================================================

def handle_dining_programs(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """dining_programs 처리"""
    chunks = []
    chain = context.get("chain", "UNKNOWN")

    if not isinstance(data, list):
        return chunks

    for program in data:
        if not isinstance(program, dict):
            continue

        program_name = program.get("program_name", "Unknown Program")
        program_id = program.get("program_id", "unknown")
        region = program.get("region", "Unknown")

        # 기본 프로그램 정보 청크
        content = f"다이닝 프로그램: {program_name}\n"
        content += f"체인: {chain}\n"
        content += f"지역: {region}\n"

        # 유효 기간
        validity = program.get("validity", {})
        if validity:
            start_date = validity.get("start_date")
            end_date = validity.get("end_date")
            if start_date and end_date:
                content += f"유효 기간: {start_date} ~ {end_date}\n"

        # 등급별 혜택
        tier_benefits = program.get("tier_benefits", [])
        if tier_benefits:
            content += "\n등급별 혜택:\n"
            for benefit in tier_benefits:
                tier = benefit.get("tier", "Unknown")
                discount = benefit.get("discount_percentage", 0)
                bonus_points = benefit.get("bonus_points", 0)
                min_spend = benefit.get("minimum_spend_usd", 0)

                content += f"  {tier}:\n"
                content += f"    - 할인: {discount}%\n"
                content += f"    - 보너스 포인트: {bonus_points}점\n"
                if min_spend:
                    content += f"    - 최소 소비 금액: ${min_spend}\n"

        # 프로그램 추가 정보 (스키마 필드 기반)
        # 참여 매장 정보
        participating_outlets = program.get("participating_outlets")
        if participating_outlets:
            content += f"\n참여 매장 수: {participating_outlets}개\n"

        outlet_types = program.get("outlet_types", [])
        if outlet_types:
            content += f"매장 유형: {', '.join(outlet_types)}\n"

        # 제한사항
        restrictions_added = False
        max_group = program.get("max_group_size")
        if max_group:
            if not restrictions_added:
                content += "\n제한사항:\n"
                restrictions_added = True
            content += f"  - 최대 그룹 크기: {max_group}명\n"

        split_bills = program.get("split_bills_allowed")
        if split_bills is not None:
            if not restrictions_added:
                content += "\n제한사항:\n"
                restrictions_added = True
            content += f"  - 분할 결제: {'허용' if split_bills else '불허용'}\n"

        member_present = program.get("member_must_be_present")
        if member_present is not None:
            if not restrictions_added:
                content += "\n제한사항:\n"
                restrictions_added = True
            content += f"  - 회원 본인 참석: {'필수' if member_present else '불필요'}\n"

        # 제외사항
        exclusions = program.get("exclusions", [])
        if exclusions:
            content += f"\n제외사항: {', '.join(exclusions[:3])}\n"

        content += DISCLAIMER_SHORT

        if len(content) > 100:
            chunks.append({
                "content": content.strip(),
                "metadata": {
                    "type": "dining_program",
                    "program_id": program_id,
                    "program_name": program_name,
                    "chain": chain,
                    "region": region
                }
            })

    return chunks


# ===========================================================================
# 핸들러: 항공 파트너십 (Flying Blue → Korean Air 등)
# ===========================================================================

def handle_airline_partnership(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """airline_partnership 처리 - 파트너 프로그램으로 타항공사 예약 정보"""
    chunks = []
    
    if not data or not isinstance(data, dict):
        return chunks
    
    partner_program = data.get("partner_program", "N/A")
    operating_airline = data.get("operating_airline", "UNKNOWN")
    alliance = data.get("alliance", "")
    currency_name = data.get("currency_name", "포인트")
    pricing_model = data.get("pricing_model", "")
    pricing_desc = data.get("pricing_model_description", "")
    
    content = f"""# {partner_program}로 {operating_airline} 예약하기

**파트너 프로그램**: {partner_program}
**운항 항공사**: {operating_airline}
**제휴**: {alliance if alliance else "N/A"}
**포인트 단위**: {currency_name}
"""
    
    if pricing_model:
        content += f"**가격 정책**: {pricing_model}"
        if pricing_desc:
            content += f" - {pricing_desc}"
        content += "\n"
    
    # 운영 주체
    operator = data.get("partner_program_operator")
    if operator:
        content += f"**프로그램 운영**: {operator}\n"
    
    # 제한사항
    restrictions = data.get("restrictions", [])
    if restrictions:
        content += "\n## ⚠️ 예약 제한사항\n"
        for restriction in restrictions[:10]:
            if isinstance(restriction, dict):
                r_type = restriction.get("restriction_type", "")
                desc = restriction.get("description", "")
                content += f"- **{r_type}**: {desc}\n"
            else:
                content += f"- {restriction}\n"
    
    # 예약 가능 항목
    available = data.get("available_booking_classes", [])
    if available:
        content += "\n## ✅ 예약 가능 클래스\n"
        for cls in available[:5]:
            if isinstance(cls, dict):
                cabin = cls.get("cabin_class", "")
                is_available = cls.get("available", True)
                status = "✅ 가능" if is_available else "❌ 불가"
                content += f"- {cabin}: {status}\n"
    
    content += DISCLAIMER_SHORT
    
    if len(content) > 100:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "airline_partnership",
                "partner_program": partner_program,
                "operating_airline": operating_airline,
                "alliance": alliance
            }
        })
    
    return chunks


# ===========================================================================
# 핸들러: 항공 프로그램 (Phase 2)
# ===========================================================================

def handle_airline_programs(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """airline_programs 또는 airline_program 처리"""
    chunks = []
    
    programs = data if isinstance(data, list) else [data]
    
    for program in programs[:5]:
        if not isinstance(program, dict):
            continue
        
        program_name = program.get("program_name", "N/A")
        airline = program.get("airline", "UNKNOWN")
        alliance = program.get("alliance", "")
        miles_name = program.get("miles_name", "마일리지")
        
        content = f"""
항공 마일리지 프로그램: {program_name}
항공사: {airline}
동맹: {alliance if alliance else "없음"}
마일리지 명칭: {miles_name}
마일리지 만료: {program.get("miles_expiration_months", "N/A")}개월
활동으로 연장: {"가능" if program.get("can_extend_with_activity") else "불가"}
"""
        
        # 등급 정보
        tiers = program.get("tiers", [])
        if tiers:
            content += "\n등급:\n"
            for tier in tiers[:6]:
                if isinstance(tier, dict):
                    tier_name = tier.get("tier_name", "N/A")
                    miles_req = tier.get("miles_required")
                    alliance_tier = tier.get("alliance_tier", "")
                    tier_info = f"  - {tier_name}"
                    if miles_req:
                        tier_info += f" ({miles_req:,} 마일)"
                    if alliance_tier:
                        tier_info += f" [동맹: {alliance_tier}]"
                    content += tier_info + "\n"
        
        # 파트너 항공사
        partners = program.get("partner_airlines", [])
        if partners:
            content += f"\n제휴 항공사: {', '.join(partners[:8])}\n"
            if len(partners) > 8:
                content += f"  ... 외 {len(partners) - 8}개\n"
        
        # 호텔 파트너
        hotel_partners = program.get("hotel_partners", [])
        if hotel_partners:
            content += f"제휴 호텔: {', '.join(hotel_partners[:5])}\n"
        
        content += DISCLAIMER_SHORT
        
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "airline_program",
                "program_name": program_name,
                "airline": airline,
                "alliance": alliance
            }
        })
        
        # === 내부 구성 요소 서브청킹 ===
        # 프로그램별 컨텍스트 생성
        program_context = {**context, "chain": airline, "airline": airline}
        
        # 1. earning_rules 처리 (마일리지 적립 규칙)
        earning_rules = program.get("earning_rules")
        if earning_rules:
            try:
                sub_chunks = handle_airline_earning_rules(earning_rules, program_context)
                chunks.extend(sub_chunks)
            except Exception:
                pass
        
        # 2. award_chart 처리 (마일리지 사용 차트)
        award_chart = program.get("award_chart")
        if award_chart:
            try:
                sub_chunks = handle_award_charts(award_chart, program_context)
                chunks.extend(sub_chunks)
            except Exception:
                pass
        
        # 3. co_branded_cards 처리 (제휴 신용카드)
        co_branded_cards = program.get("co_branded_cards")
        if co_branded_cards:
            try:
                sub_chunks = handle_credit_cards(co_branded_cards, program_context)
                chunks.extend(sub_chunks)
            except Exception:
                pass
        
        # 4. tiers를 별도 청크로 처리 (상세 등급 정보)
        tiers_data = program.get("tiers")
        if tiers_data and isinstance(tiers_data, list) and len(tiers_data) > 0:
            try:
                sub_chunks = handle_airline_tiers(tiers_data, program_context)
                chunks.extend(sub_chunks)
            except Exception:
                pass
    
    return chunks


def handle_airline_tiers(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """airline_tiers 처리"""
    chunks = []

    if data is None:
        return chunks

    tiers = data if isinstance(data, list) else [data]
    
    for tier in tiers[:10]:
        if not isinstance(tier, dict):
            continue
        
        tier_name = tier.get("tier_name", "N/A")
        airline = tier.get("airline", context.get("chain", "UNKNOWN"))

        # f-string 오류 수정: miles_required 처리
        miles_req = tier.get("miles_required")
        miles_str = f"{miles_req:,}" if isinstance(miles_req, int) else "N/A"

        content = f"""
항공 멤버십 등급: {tier_name}
항공사: {airline}
등급 순위: {tier.get("rank", "N/A")}

자격 요건:
  - 필요 마일리지: {miles_str}
  - 필요 구간: {tier.get("segments_required", "N/A")}
  - 산정 기간: {tier.get("qualification_period", "calendar_year")}
"""
        
        # 동맹 등급
        if tier.get("alliance") or tier.get("alliance_tier"):
            content += f"\n동맹: {tier.get('alliance', 'N/A')}\n"
            content += f"동맹 등급: {tier.get('alliance_tier', 'N/A')}\n"
        
        # 주요 혜택
        content += "\n주요 혜택:\n"
        
        if tier.get("lounge_access"):
            lounge_details = tier.get("lounge_access_details", "라운지 이용 가능")
            content += f"  - 라운지: {lounge_details}\n"
        
        if tier.get("earning_bonus_percent"):
            content += f"  - 마일리지 보너스: {tier.get('earning_bonus_percent')}% 추가\n"
        
        if tier.get("complimentary_upgrades"):
            content += f"  - 무료 업그레이드: 연 {tier.get('complimentary_upgrades')}회\n"
        
        if tier.get("extra_baggage_kg") or tier.get("extra_baggage_pieces"):
            baggage_info = []
            if tier.get("extra_baggage_kg"):
                baggage_info.append(f"+{tier.get('extra_baggage_kg')}kg")
            if tier.get("extra_baggage_pieces"):
                baggage_info.append(f"+{tier.get('extra_baggage_pieces')}개")
            content += f"  - 추가 수하물: {', '.join(baggage_info)}\n"
        
        # 기타 혜택
        benefits = tier.get("benefits", [])
        for benefit in benefits[:5]:
            if isinstance(benefit, dict):
                content += f"  - {benefit.get('name', 'N/A')}\n"
        
        content += DISCLAIMER_SHORT
        
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "airline_tier",
                "tier_name": tier_name,
                "airline": airline,
                "rank": tier.get("rank")
            }
        })
    
    return chunks


def handle_award_charts(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """award_charts 또는 award_chart 처리"""
    chunks = []
    
    charts = data if isinstance(data, list) else [data]
    
    for chart in charts[:3]:
        if not isinstance(chart, dict):
            continue
        
        chart_name = chart.get("chart_name", "마일리지 좌석 차트")
        airline = chart.get("airline", context.get("chain", "UNKNOWN"))
        
        content = f"""
마일리지 좌석 차트: {chart_name}
항공사: {airline}
시행일: {chart.get("effective_date", "N/A")}
유류할증료: {"적용" if chart.get("fuel_surcharge_applies", True) else "미적용"}
세금: {"별도" if chart.get("taxes_additional", True) else "포함"}
"""
        
        # 구간별 필요 마일리지
        entries = chart.get("entries", [])
        regions = chart.get("regions", [])  # regions 키 지원 추가
        
        if entries:
            content += "\n구간별 필요 마일리지 (왕복 기준):\n"
            for entry in entries[:10]:
                if isinstance(entry, dict):
                    route = entry.get("route_type", "N/A")
                    content += f"\n{route}:\n"
                    
                    if entry.get("economy"):
                        content += f"  - 이코노미: {entry['economy']:,} 마일\n"
                    if entry.get("premium_economy"):
                        content += f"  - 프리미엄 이코노미: {entry['premium_economy']:,} 마일\n"
                    if entry.get("business"):
                        content += f"  - 비즈니스: {entry['business']:,} 마일\n"
                    if entry.get("first"):
                        content += f"  - 퍼스트: {entry['first']:,} 마일\n"
        
        # regions 구조 처리 (Asiana 등)
        elif regions:
            content += "\n구간별 필요 마일리지:\n"
            for region in regions[:10]:
                if isinstance(region, dict):
                    r_name = region.get("region_name", region.get("region_code", "N/A"))
                    trip_type = region.get("trip_type", "")
                    trip_label = "왕복" if trip_type == "ROUND_TRIP" else "편도" if trip_type == "ONE_WAY" else ""
                    content += f"\n{r_name} ({trip_label}):\n"
                    
                    cabin_classes = region.get("cabin_classes", [])
                    for cabin in cabin_classes:
                        if isinstance(cabin, dict):
                            c_name = cabin.get("cabin_class", "N/A")
                            cabin_labels = {
                                "ECONOMY": "일반석",
                                "PREMIUM_ECONOMY": "프리미엄 이코노미",
                                "BUSINESS": "비즈니스",
                                "BUSINESS_SMARTIUM": "비즈니스 스마티움",
                                "FIRST": "퍼스트"
                            }
                            c_label = cabin_labels.get(c_name, c_name)
                            low = cabin.get("low_season_miles", 0)
                            high = cabin.get("high_season_miles", 0)
                            if low and high:
                                content += f"  - {c_label}: {low:,}~{high:,} 마일\n"
                            elif low:
                                content += f"  - {c_label}: {low:,} 마일\n"
        
        # 참고사항
        notes = chart.get("notes", [])
        if notes:
            content += "\n참고:\n"
            for note in notes[:5]:
                content += f"  - {note}\n"
        
        content += DISCLAIMER_PRICE
        
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "award_chart",
                "chart_name": chart_name,
                "airline": airline
            }
        })
    
    return chunks


def handle_airline_earning_rules(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """airline_earning_rules 처리 (스키마 AirlineEarningRule 필드 구조에 맞춤)"""
    chunks = []

    rules = data if isinstance(data, list) else [data]
    airline = context.get("chain", "UNKNOWN")

    # 규칙들을 하나의 청크로 묶기
    if not rules:
        return chunks

    content = f"""
마일리지 적립 규칙
항공사: {airline}

"""

    for rule in rules[:15]:
        if not isinstance(rule, dict):
            continue

        rule_name = rule.get("rule_name", "N/A")
        cabin = rule.get("cabin_class", "")

        content += f"• {rule_name}\n"
        if cabin:
            content += f"  - 객실: {cabin}\n"

        # 노선 유형
        route = rule.get("route_type", "")
        if route:
            content += f"  - 노선: {route}\n"

        # 적립률 (스키마 필드 반영)
        earning_rate = rule.get("earning_rate_percent")
        base_miles_type = rule.get("base_miles_type", "FLOWN")
        fixed_miles = rule.get("fixed_miles")

        if earning_rate:
            content += f"  - 적립률: {earning_rate}%\n"
        elif base_miles_type == "FIXED" and fixed_miles:
            content += f"  - 고정 마일: {fixed_miles:,}마일\n"

        # 예약 클래스
        booking_classes = rule.get("booking_classes", [])
        if booking_classes:
            content += f"  - 예약 클래스: {', '.join(booking_classes)}\n"

        # 보너스 마일
        bonus_miles = rule.get("bonus_miles")
        if bonus_miles:
            content += f"  - 보너스: +{bonus_miles:,}마일\n"

        # 필요 등급
        req_tier = rule.get("requires_membership_tier")
        if req_tier:
            content += f"  - 필요 등급: {req_tier}\n"

        # 유효 기간
        validity = rule.get("validity")
        if validity and isinstance(validity, dict):
            start = validity.get("start_date")
            end = validity.get("end_date")
            if start or end:
                content += f"  - 유효 기간: {start or '?'} ~ {end or '?'}\n"

        # 지역
        region = rule.get("region")
        if region and region != "GLOBAL":
            content += f"  - 적용 지역: {region}\n"

        content += "\n"

    content += DISCLAIMER_SHORT

    if len(content) > 100:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "airline_earning_rules",
                "airline": airline
            }
        })

    return chunks


# ===========================================================================
# 핸들러: 항공 운임 (Airline Fares)
# ===========================================================================

def handle_airline_fare_tables(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """airline_fare_tables 처리 - 항공 운임표 기본 정보"""
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    
    for item in items:
        airline = item.get("airline", "UNKNOWN")
        program = item.get("program_name", "")
        currency = item.get("currency", "KRW")
        effective_date = item.get("effective_date", "")
        
        content = f"# {airline} 항공 운임표 정보\n\n"
        content += f"**항공사**: {airline}\n"
        if program:
            content += f"**프로그램**: {program}\n"
        content += f"**통화**: {currency}\n"
        if effective_date:
            content += f"**적용일**: {effective_date}\n"
        
        # 일반 정보
        general_info = item.get("general_info", {})
        if general_info:
            content += f"\n## 운임 포함 사항\n"
            fare_includes = general_info.get("fare_includes", [])
            if fare_includes:
                content += "- " + "\n- ".join(fare_includes) + "\n"
            fare_type = general_info.get("fare_type", "")
            if fare_type:
                content += f"**운임 유형**: {fare_type}\n"
            variability = general_info.get("variability_note", "")
            if variability:
                content += f"**참고**: {variability}\n"
        
        # 좌석 등급
        cabin_classes = item.get("cabin_classes", [])
        if cabin_classes:
            content += f"\n## 좌석 등급\n"
            for cabin in cabin_classes:
                code = cabin.get("cabin_code", "")
                name = cabin.get("cabin_name", "")
                name_en = cabin.get("cabin_name_en", "")
                booking_classes = cabin.get("booking_classes", [])
                content += f"- **{name}** ({name_en}, {code}): {', '.join(booking_classes)}\n"
        
        # 시즌 정보
        seasons = item.get("seasons", [])
        if seasons:
            content += f"\n## 시즌 구분\n"
            for season in seasons:
                code = season.get("season_code", "")
                name = season.get("season_name", "")
                content += f"- {name} ({code})\n"
        
        # 유류할증료
        fuel_table = item.get("fuel_surcharge_table", [])
        if fuel_table:
            content += f"\n## 유류할증료\n"
            for fuel in fuel_table:
                tier = fuel.get("distance_tier", "")
                desc = fuel.get("description", "")
                trip = fuel.get("trip_type", "")
                amount = fuel.get("amount", fuel.get("amount_range", {}).get("min", ""))
                content += f"- {tier}"
                if desc:
                    content += f" ({desc})"
                content += f": {amount:,}원" if isinstance(amount, int) else f": {amount}"
                if trip:
                    content += f" ({trip})"
                content += "\n"
        
        content += DISCLAIMER_SHORT
        
        if len(content) > 100:
            chunks.append({
                "content": content.strip(),
                "metadata": {
                    "type": "airline_fare_table",
                    "airline": airline,
                    "program": program
                }
            })
    
    return chunks


def handle_domestic_fare_rules(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """domestic_fare_rules 처리 - 국내선 운임 규정"""
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    
    for item in items:
        airline = item.get("airline", "UNKNOWN")
        region = item.get("region", "DOMESTIC")
        
        content = f"# {airline} 국내선 운임 규정\n\n"
        
        fare_basis = item.get("fare_basis", "")
        if fare_basis:
            content += f"**운임 기준**: {fare_basis}\n"
        
        fuel = item.get("fuel_surcharge_oneway", 0)
        airport = item.get("airport_fee_oneway", 0)
        if fuel or airport:
            content += f"**유류할증료 (편도)**: {fuel:,}원\n"
            content += f"**공항이용료 (편도)**: {airport:,}원\n"
        
        # 요일 구분
        weekday = item.get("weekday_days", [])
        weekend = item.get("weekend_days", [])
        if weekday or weekend:
            content += f"\n## 요일 구분\n"
            if weekday:
                content += f"- **주중**: {', '.join(weekday)}\n"
            if weekend:
                content += f"- **주말**: {', '.join(weekend)}\n"
        
        # 시간대 구분
        time_zones = item.get("time_zones", [])
        if time_zones:
            content += f"\n## 시간대 구분\n"
            for tz in time_zones:
                direction = tz.get("direction", "")
                preferred = tz.get("preferred_time", "")
                standard = tz.get("standard_time", "")
                content += f"- **{direction}**: 선호 {preferred}, 일반 {standard}\n"
        
        # 탄력할증운임
        flex_routes = item.get("flexible_surcharge_routes", [])
        if flex_routes:
            content += f"\n## 탄력할증운임 적용\n"
            for route in flex_routes:
                direction = route.get("direction", "")
                applies = route.get("applies_to", "")
                content += f"- **{direction}**: {applies}\n"
        
        content += DISCLAIMER_SHORT
        
        if len(content) > 100:
            chunks.append({
                "content": content.strip(),
                "metadata": {
                    "type": "domestic_fare_rules",
                    "airline": airline,
                    "region": region
                }
            })
    
    return chunks


def handle_domestic_peak_seasons(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """domestic_peak_seasons 처리 - 국내선 성수기 기간"""
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    
    content = "# 국내선 성수기 적용 기간\n\n"
    
    for item in items:
        year = item.get("year", "")
        dates = item.get("dates", [])
        if year and dates:
            content += f"## {year}년 성수기\n"
            content += "- " + "\n- ".join(dates) + "\n\n"
    
    content += DISCLAIMER_SHORT
    
    if len(content) > 100:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "domestic_peak_seasons",
                "airline": context.get("chain", "UNKNOWN")
            }
        })
    
    return chunks


def handle_domestic_route_fares(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """domestic_route_fares 처리 - 국내선 노선별 운임"""
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    
    for item in items:
        # 새 데이터 구조 처리
        origin_name = item.get("origin_name", "")
        dest_name = item.get("destination_name", "")
        route = item.get("route", f"{origin_name}-{dest_name}")
        airline = item.get("airline", context.get("chain", "UNKNOWN"))
        cabin_name = item.get("cabin_name", "")
        cabin_class = item.get("cabin_class", "")
        trip_type = item.get("trip_type", "ONE_WAY")
        
        content = f"# {airline} {route} 국내선 운임\n\n"
        content += f"**노선**: {origin_name} → {dest_name}\n"
        if cabin_name:
            content += f"**좌석등급**: {cabin_name} ({cabin_class})\n"
        content += f"**운임유형**: {'편도' if trip_type == 'ONE_WAY' else '왕복'}\n"
        
        # fares가 딕셔너리인 경우 (새 구조)
        fares = item.get("fares", {})
        if isinstance(fares, dict):
            content += f"\n## 운임표\n"
            wd_pref = fares.get("weekday_preferred", "-")
            wd_std = fares.get("weekday_standard", "-")
            we_pref = fares.get("weekend_preferred", "-")
            we_std = fares.get("weekend_standard", "-")
            peak_flex = fares.get("peak_flexible", "-")
            
            if isinstance(wd_pref, int):
                wd_pref = f"{wd_pref:,}"
            if isinstance(wd_std, int):
                wd_std = f"{wd_std:,}"
            if isinstance(we_pref, int):
                we_pref = f"{we_pref:,}"
            if isinstance(we_std, int):
                we_std = f"{we_std:,}"
            if isinstance(peak_flex, int):
                peak_flex = f"{peak_flex:,}"
            
            content += f"- **주중선호**: {wd_pref}원\n"
            content += f"- **주중일반**: {wd_std}원\n"
            content += f"- **주말선호**: {we_pref}원\n"
            content += f"- **주말일반**: {we_std}원\n"
            if peak_flex != "-":
                content += f"- **성수기탄력**: {peak_flex}원\n"
        # fares가 리스트인 경우 (이전 구조)
        elif isinstance(fares, list) and fares:
            content += f"\n## 운임표 (편도)\n"
            content += "| 등급 | 예약클래스 | 주중일반 | 주중선호 | 주말일반 | 주말선호 |\n"
            content += "|------|-----------|---------|---------|---------|--------|\n"
            for fare in fares:
                if isinstance(fare, dict):
                    cabin = fare.get("cabin_name", "")
                    booking = fare.get("booking_class", "")
                    wd_std = fare.get("weekday_standard", "-")
                    wd_pref = fare.get("weekday_preferred", "-")
                    we_std = fare.get("weekend_standard", "-")
                    we_pref = fare.get("weekend_preferred", "-")
                    
                    if isinstance(wd_std, int):
                        wd_std = f"{wd_std:,}"
                    if isinstance(wd_pref, int):
                        wd_pref = f"{wd_pref:,}"
                    if isinstance(we_std, int):
                        we_std = f"{we_std:,}"
                    if isinstance(we_pref, int):
                        we_pref = f"{we_pref:,}"
                    
                    content += f"| {cabin} | {booking} | {wd_std} | {wd_pref} | {we_std} | {we_pref} |\n"
        
        content += DISCLAIMER_SHORT
        
        if len(content) > 100:
            chunks.append({
                "content": content.strip(),
                "metadata": {
                    "type": "domestic_route_fares",
                    "airline": airline,
                    "route": route,
                    "cabin_class": cabin_class
                }
            })
    
    return chunks


def handle_codeshare_domestic_fares(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """codeshare_domestic_fares 처리 - 공동운항 국내선 운임"""
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    
    for item in items:
        route = item.get("route", "")
        operating_carrier = item.get("operating_carrier", "")
        marketing_carrier = item.get("marketing_carrier", context.get("chain", ""))
        
        content = f"# {marketing_carrier} 공동운항 ({operating_carrier}) {route} 운임\n\n"
        content += f"**운항사**: {operating_carrier}\n"
        content += f"**판매사**: {marketing_carrier}\n"
        
        # 운임 정보
        fares = item.get("fares", [])
        if fares:
            content += f"\n## 운임표 (편도)\n"
            content += "| 등급 | 예약클래스 | 주중일반 | 주중선호 | 주말일반 | 주말선호 |\n"
            content += "|------|-----------|---------|---------|---------|--------|\n"
            for fare in fares:
                cabin = fare.get("cabin_name", "")
                booking = fare.get("booking_class", "")
                wd_std = fare.get("weekday_standard", "-")
                wd_pref = fare.get("weekday_preferred", "-")
                we_std = fare.get("weekend_standard", "-")
                we_pref = fare.get("weekend_preferred", "-")
                
                if isinstance(wd_std, int):
                    wd_std = f"{wd_std:,}"
                if isinstance(wd_pref, int):
                    wd_pref = f"{wd_pref:,}"
                if isinstance(we_std, int):
                    we_std = f"{we_std:,}"
                if isinstance(we_pref, int):
                    we_pref = f"{we_pref:,}"
                
                content += f"| {cabin} | {booking} | {wd_std} | {wd_pref} | {we_std} | {we_pref} |\n"
        
        content += DISCLAIMER_SHORT
        
        if len(content) > 100:
            chunks.append({
                "content": content.strip(),
                "metadata": {
                    "type": "codeshare_domestic_fares",
                    "airline": marketing_carrier,
                    "operating_carrier": operating_carrier,
                    "route": route
                }
            })
    
    return chunks


def handle_international_route_fares(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """international_route_fares 처리 - 국제선 노선별 운임"""
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    
    for item in items:
        route = item.get("route", "")
        region = item.get("region", "")
        airline = item.get("airline", context.get("chain", "UNKNOWN"))
        trip_type = item.get("trip_type", "ROUND_TRIP")
        
        content = f"# {airline} {route} 국제선 운임 ({region})\n\n"
        content += f"**노선**: {route}\n"
        content += f"**지역**: {region}\n"
        content += f"**운임 유형**: {'왕복' if trip_type == 'ROUND_TRIP' else '편도'}\n"
        
        # 세금/부가세
        fuel = item.get("fuel_surcharge", 0)
        tax = item.get("tax", 0)
        if fuel or tax:
            content += f"**유류할증료**: {fuel:,}원\n"
            content += f"**세금**: {tax:,}원\n"
        
        # 운임 정보
        fares = item.get("fares", [])
        if fares:
            content += f"\n## 운임표\n"
            content += "| 등급 | 예약클래스 | 비수기 | 준성수기 | 성수기 |\n"
            content += "|------|-----------|---------|---------|--------|\n"
            for fare in fares:
                cabin = fare.get("cabin_name", "")
                booking = fare.get("booking_class", "")
                low = fare.get("low_season", "-")
                shoulder = fare.get("shoulder_season", "-")
                high = fare.get("high_season", "-")
                
                if isinstance(low, int):
                    low = f"{low:,}"
                if isinstance(shoulder, int):
                    shoulder = f"{shoulder:,}"
                if isinstance(high, int):
                    high = f"{high:,}"
                
                content += f"| {cabin} | {booking} | {low} | {shoulder} | {high} |\n"
        
        content += DISCLAIMER_SHORT
        
        if len(content) > 100:
            chunks.append({
                "content": content.strip(),
                "metadata": {
                    "type": "international_route_fares",
                    "airline": airline,
                    "route": route,
                    "region": region
                }
            })
    
    return chunks


def handle_fare_comparison_summary(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """fare_comparison_summary 처리 - 운임 비교 요약"""
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    
    content = "# 노선별 최저가 운임 비교\n\n"
    content += "| 지역 | 노선 | 왕복유형 | 최저운임 | 유류할증료 | 세금 | 총액 |\n"
    content += "|------|------|----------|---------|-----------|-----|------|\n"
    
    for item in items:
        region = item.get("region", "")
        route = item.get("route", "")
        trip = item.get("trip_type", "")
        lowest = item.get("lowest_economy", 0)
        fuel = item.get("fuel_surcharge", 0)
        tax = item.get("tax", 0)
        total = item.get("total", 0)
        note = item.get("note", "")
        
        trip_str = "왕복" if trip == "ROUND_TRIP" else "편도"
        content += f"| {region} | {route} | {trip_str} | {lowest:,} | {fuel:,} | {tax:,} | {total:,} |\n"
    
    content += DISCLAIMER_SHORT
    
    if len(content) > 100:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "fare_comparison_summary",
                "airline": context.get("chain", "UNKNOWN")
            }
        })
    
    return chunks


def handle_important_notes(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """important_notes 처리 - 중요 참고사항"""
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    
    content = "# 운임 관련 중요 참고사항\n\n"
    
    for item in items:
        note_id = item.get("note_id", "")
        description = item.get("description", "")
        if description:
            content += f"- **{note_id}**: {description}\n"
    
    content += DISCLAIMER_SHORT
    
    if len(content) > 100:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "important_notes",
                "category": context.get("chain", "UNKNOWN")
            }
        })
    
    return chunks


# ===========================================================================
# 핸들러: 항공 부가 요금 규정 (Extra Fee Rules)
# ===========================================================================

def handle_baggage_rules(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """baggage_rules 처리 - 수하물 규정"""
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    
    for item in items:
        airline = item.get("airline", context.get("chain", "UNKNOWN"))
        rule_name = item.get("rule_name", "수하물 규정")
        route_type = item.get("route_type", "")
        
        content = f"# {airline} {rule_name}\n\n"
        if route_type:
            route_label = "국내선" if route_type == "DOMESTIC" else "국제선" if route_type == "INTERNATIONAL" else route_type
            content += f"**노선 유형**: {route_label}\n"
        
        # Allowances
        allowances = item.get("allowances", [])
        if allowances:
            content += f"\n## 무료 수하물 허용량\n"
            for allow in allowances:
                if isinstance(allow, dict):
                    cabin = allow.get("cabin_class_name") or allow.get("cabin_class", "")
                    fare = allow.get("fare_class", "")
                    pieces = allow.get("pieces", "")
                    weight = allow.get("weight_kg") or allow.get("max_weight_per_piece_kg", "")
                    
                    info = f"- **{cabin}**"
                    if fare:
                        info += f" ({fare})"
                    info += ": "
                    if pieces:
                        info += f"{pieces}개"
                    if weight:
                        info += f" (각 {weight}kg)" if pieces else f"{weight}kg"
                    content += info + "\n"
        
        # Excess fee
        excess = item.get("excess_fee", {})
        if excess:
            desc = excess.get("description", "")
            amount = excess.get("amount", 0)
            currency = excess.get("currency", "KRW")
            unit = excess.get("unit", "")
            if desc:
                content += f"\n**초과 요금**: {desc}\n"
            elif amount:
                content += f"\n**초과 요금**: {amount:,} {currency} ({unit})\n"
        
        content += DISCLAIMER_SHORT
        
        if len(content) > 100:
            chunks.append({
                "content": content.strip(),
                "metadata": {
                    "type": "baggage_rules",
                    "airline": airline,
                    "route_type": route_type
                }
            })
    
    return chunks


def handle_baggage_general_rules(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """baggage_general_rules 처리 - 일반 수하물 규정 (정책, 금지 품목, 제한 사항 등)
    
    baggage_rules와 달리 구체적인 허용량보다 정책적인 내용을 다룸:
    - 수하물 정책 개요
    - 위탁/기내/휴대 수하물 제한
    - 금지 품목
    - 특수 수하물 정책
    """
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    airline = context.get("chain", "UNKNOWN")
    
    for item in items:
        if not isinstance(item, dict):
            continue
            
        rule_name = item.get("rule_name", "일반 수하물 규정")
        category = item.get("category", "")
        route_type = item.get("route_type", "")
        
        content = f"# {airline} {rule_name}\n\n"
        
        if route_type:
            route_label = "국내선" if route_type == "DOMESTIC" else "국제선" if route_type == "INTERNATIONAL" else route_type
            content += f"**노선 유형**: {route_label}\n"
        if category:
            content += f"**분류**: {category}\n"
        
        # 정책 설명
        description = item.get("description", "")
        if description:
            content += f"\n{description}\n"
        
        # 금지 품목 (prohibited_items)
        prohibited = item.get("prohibited_items", [])
        if prohibited:
            content += "\n## 금지 품목\n"
            for p_item in prohibited:
                if isinstance(p_item, dict):
                    item_name = p_item.get("item", p_item.get("name", ""))
                    reason = p_item.get("reason", "")
                    location = p_item.get("location", "")  # cabin_only, checked_only, etc.
                    content += f"- **{item_name}**"
                    if location:
                        content += f" ({location})"
                    if reason:
                        content += f": {reason}"
                    content += "\n"
                elif isinstance(p_item, str):
                    content += f"- {p_item}\n"
        
        # 제한 품목 (restricted_items)
        restricted = item.get("restricted_items", [])
        if restricted:
            content += "\n## 제한 품목\n"
            for r_item in restricted:
                if isinstance(r_item, dict):
                    item_name = r_item.get("item", r_item.get("name", ""))
                    condition = r_item.get("condition", "")
                    max_qty = r_item.get("max_quantity", "")
                    content += f"- **{item_name}**"
                    if max_qty:
                        content += f" (최대 {max_qty}개)"
                    if condition:
                        content += f": {condition}"
                    content += "\n"
                elif isinstance(r_item, str):
                    content += f"- {r_item}\n"
        
        # 기내 수하물 정책 (carry_on_policy)
        carry_on = item.get("carry_on_policy", {})
        if carry_on and isinstance(carry_on, dict):
            content += "\n## 기내 수하물\n"
            max_weight = carry_on.get("max_weight_kg", "")
            max_dims = carry_on.get("max_dimensions", "")
            max_pieces = carry_on.get("max_pieces", "")
            if max_weight:
                content += f"- 최대 무게: {max_weight}kg\n"
            if max_dims:
                content += f"- 최대 규격: {max_dims}\n"
            if max_pieces:
                content += f"- 최대 개수: {max_pieces}개\n"
        
        # 위탁 수하물 정책 (checked_policy)
        checked = item.get("checked_policy", {})
        if checked and isinstance(checked, dict):
            content += "\n## 위탁 수하물\n"
            max_weight = checked.get("max_weight_kg", "")
            max_dims = checked.get("max_dimensions", "")
            if max_weight:
                content += f"- 최대 무게: {max_weight}kg\n"
            if max_dims:
                content += f"- 최대 규격: {max_dims}\n"
        
        # 특별 규정 (special_rules)
        special_rules = item.get("special_rules", [])
        if special_rules:
            content += "\n## 특별 규정\n"
            for rule in special_rules:
                if isinstance(rule, dict):
                    rule_title = rule.get("title", rule.get("rule", ""))
                    rule_desc = rule.get("description", "")
                    content += f"- **{rule_title}**"
                    if rule_desc:
                        content += f": {rule_desc}"
                    content += "\n"
                elif isinstance(rule, str):
                    content += f"- {rule}\n"
        
        # 참고 사항 (notes)
        notes = item.get("notes", [])
        if notes:
            content += "\n## 참고 사항\n"
            for note in notes:
                content += f"- {note}\n"
        
        content += DISCLAIMER_SHORT
        
        if len(content) > 100:
            chunks.append({
                "content": content.strip(),
                "metadata": {
                    "type": "baggage_general_rules",
                    "airline": airline,
                    "category": category,
                    "route_type": route_type
                }
            })
    
    return chunks


def handle_sports_equipment_rules(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """sports_equipment_rules 처리 - 스포츠 장비 규정"""
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    airline = context.get("chain", "UNKNOWN")
    
    content = f"# {airline} 스포츠 장비 운송 규정\n\n"
    
    for item in items:
        rule_name = item.get("rule_name", "")
        route_type = item.get("route_type", "")
        equipment_type = item.get("equipment_type", "")
        
        if rule_name:
            content += f"## {rule_name}\n"
        
        max_weight = item.get("max_weight_kg", "")
        max_dims = item.get("max_dimensions_cm", "")
        if max_weight:
            content += f"- **최대 무게**: {max_weight}kg\n"
        if max_dims:
            note = item.get("dimensions_note", "")
            content += f"- **최대 규격**: {max_dims}cm ({note})\n" if note else f"- **최대 규격**: {max_dims}cm\n"
        
        equipment_types = item.get("equipment_types", [])
        if equipment_types:
            content += f"- **적용 장비**: {', '.join(equipment_types)}\n"
        
        exceptions = item.get("exceptions", [])
        if exceptions:
            content += f"\n**예외 규정**:\n"
            for exc in exceptions:
                cond = exc.get("condition", "")
                waiver = exc.get("waiver", "")
                content += f"- {cond}: {waiver}\n"
        
        policy = item.get("policy", "")
        if policy:
            content += f"- **정책**: {policy}\n"
        
        content += "\n"
    
    content += DISCLAIMER_SHORT
    
    if len(content) > 100:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "sports_equipment_rules",
                "airline": airline
            }
        })
    
    return chunks


def handle_pet_transport_rules(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """pet_transport_rules 처리 - 반려동물 운송 규정"""
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    airline = context.get("chain", "UNKNOWN")
    
    content = f"# {airline} 반려동물 운송 규정\n\n"
    
    for item in items:
        rule_name = item.get("rule_name", "")
        route_type = item.get("route_type", "")
        
        if rule_name:
            content += f"## {rule_name}\n"
        
        # Basic conditions
        allowed_pets = item.get("allowed_pets", [])
        if allowed_pets:
            content += f"- **허용 동물**: {', '.join(allowed_pets)}\n"
        
        cabin_weight = item.get("cabin_max_weight_kg", "")
        cargo_weight = item.get("cargo_max_weight_kg", "")
        if cabin_weight:
            content += f"- **기내 반입 최대 무게**: {cabin_weight}kg (용기 포함)\n"
        if cargo_weight:
            content += f"- **화물칸 최대 무게**: {cargo_weight}kg (용기 포함)\n"
        
        # Fees
        fees = item.get("fees", [])
        if fees:
            content += f"\n**요금**:\n"
            for fee in fees:
                if isinstance(fee, dict):
                    weight = fee.get("weight_range", "") or fee.get("route_type", "")
                    route_desc = fee.get("route_description", "")
                    fee_krw = fee.get("fee_krw", 0)
                    transport_type = fee.get("transport_type", "")
                    
                    info = f"- {weight}"
                    if route_desc:
                        info += f" ({route_desc})"
                    if transport_type:
                        info += f" [{transport_type}]"
                    info += f": {fee_krw:,}원"
                    content += info + "\n"
        
        # Container requirements
        container = item.get("container_requirements", {})
        if container:
            content += f"\n**용기 조건**:\n"
            max_dims = container.get("max_dimensions_cm", "")
            max_height = container.get("max_height_cm", "")
            material = container.get("material", "")
            if max_dims:
                content += f"- 최대 크기: {max_dims}cm\n"
            if max_height:
                content += f"- 최대 높이: {max_height}cm\n"
            if material:
                content += f"- 재질: {material}\n"
        
        # Restrictions
        restrictions = item.get("restrictions", {})
        if restrictions:
            content += f"\n**제한 사항**:\n"
            cargo = restrictions.get("cargo_transport", "")
            cabin = restrictions.get("cabin_transport", "")
            if cargo:
                content += f"- 화물칸: {cargo}\n"
            if cabin:
                content += f"- 기내: {cabin}\n"
        
        content += "\n"
    
    content += DISCLAIMER_SHORT
    
    if len(content) > 100:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "pet_transport_rules",
                "airline": airline
            }
        })
    
    return chunks


# ===========================================================================
# 핸들러: 항공 운임 추가 정보 (시즌, 클래스, 세금, 공항, 유류할증료, 팩트)
# ===========================================================================

def handle_international_season_definitions(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """international_season_definitions 처리 - 국제선 시즌 정의"""
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    
    for item in items:
        airline = item.get("airline", context.get("chain", "UNKNOWN"))
        description = item.get("description", "")
        
        content = f"# {airline} 국제선 시즌 구분\n\n"
        if description:
            content += f"{description}\n\n"
        
        seasons = item.get("seasons", [])
        for season in seasons:
            season_type = season.get("season_type", "")
            season_name = season.get("season_name", "")
            content += f"## {season_name} ({season_type})\n"
            
            periods = season.get("typical_periods", [])
            if periods:
                content += "**기간**:\n"
                for period in periods:
                    content += f"- {period}\n"
        
        notes = item.get("notes", [])
        if notes:
            content += "\n**참고사항**:\n"
            for note in notes:
                content += f"- {note}\n"
        
        content += DISCLAIMER_SHORT
        
        if len(content) > 100:
            chunks.append({
                "content": content.strip(),
                "metadata": {
                    "type": "international_season_definitions",
                    "airline": airline
                }
            })
    
    return chunks


def handle_booking_class_definitions(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """booking_class_definitions 처리 - 예약 클래스 정의"""
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    
    for item in items:
        airline = item.get("airline", context.get("chain", "UNKNOWN"))
        cabin_class = item.get("cabin_class", "")
        cabin_name = "비즈니스석" if cabin_class == "BUSINESS" else "일반석" if cabin_class == "ECONOMY" else cabin_class
        
        content = f"# {airline} {cabin_name} 예약 클래스 안내\n\n"
        
        classes = item.get("classes", [])
        for cls in classes:
            code = cls.get("code", "")
            name = cls.get("name", "")
            desc = cls.get("description", "")
            flexibility = cls.get("flexibility", "")
            refundable = cls.get("refundable")
            changeable = cls.get("changeable")
            
            content += f"## {code} 클래스 - {name}\n"
            if desc:
                content += f"- {desc}\n"
            if flexibility:
                flex_label = {"HIGH": "높음", "MEDIUM": "중간", "LOW": "낮음", "VERY_LOW": "매우 낮음"}.get(flexibility, flexibility)
                content += f"- **유연성**: {flex_label}\n"
            if refundable is not None:
                content += f"- **환불 가능**: {'예' if refundable else '아니오'}\n"
            if changeable is not None:
                content += f"- **변경 가능**: {'예' if changeable else '아니오'}\n"
            content += "\n"
        
        content += DISCLAIMER_SHORT
        
        if len(content) > 100:
            chunks.append({
                "content": content.strip(),
                "metadata": {
                    "type": "booking_class_definitions",
                    "airline": airline,
                    "cabin_class": cabin_class
                }
            })
    
    return chunks


def handle_special_tax_structures(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """special_tax_structures 처리 - 특수 세금 구조"""
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    airline = context.get("chain", "UNKNOWN")
    
    content = f"# {airline} 노선별 특수 세금 안내\n\n"
    content += "일부 노선은 도착 국가의 특별 세금으로 인해 타 노선 대비 세금이 높습니다.\n\n"
    
    for item in items:
        route = item.get("route", "")
        route_name = item.get("route_name", "")
        tax_note = item.get("tax_note", "")
        
        content += f"## {route_name} ({route})\n"
        if tax_note:
            content += f"**특이사항**: {tax_note}\n\n"
        
        tax_by_class = item.get("tax_by_class", [])
        if tax_by_class:
            content += "| 좌석 등급 | 세금 |\n|----------|------|\n"
            for tax in tax_by_class:
                cabin = tax.get("cabin_class", "")
                cabin_label = "비즈니스" if cabin == "BUSINESS" else "일반석" if cabin == "ECONOMY" else cabin
                amount = tax.get("tax_amount", 0)
                currency = tax.get("currency", "KRW")
                content += f"| {cabin_label} | {amount:,}원 |\n"
            content += "\n"
    
    content += DISCLAIMER_SHORT
    
    if len(content) > 100:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "special_tax_structures",
                "airline": airline
            }
        })
    
    return chunks


def handle_multi_airport_routes(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """multi_airport_routes 처리 - 복수 공항 노선 정보"""
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    airline = context.get("chain", "UNKNOWN")
    
    content = f"# {airline} 복수 공항 노선 정보\n\n"
    content += "일부 도시는 여러 공항에서 운항됩니다.\n\n"
    
    for item in items:
        city = item.get("city", "")
        note = item.get("note", "")
        
        content += f"## {city}\n"
        
        airports = item.get("airports", [])
        for airport in airports:
            code = airport.get("code", "")
            name = airport.get("name", "")
            ap_type = airport.get("type", "")
            type_label = "(메인)" if ap_type == "MAIN" else "(시티)" if ap_type == "CITY" else ""
            content += f"- **{code}** - {name} {type_label}\n"
        
        routes_from = item.get("routes_from_gmp", [])
        if routes_from:
            content += "\n**김포 출발 가능 노선**:\n"
            for route in routes_from:
                dest = route.get("destination", "")
                dest_name = route.get("destination_name", "")
                content += f"- {dest_name} ({dest})\n"
        
        if note:
            content += f"\n**참고**: {note}\n"
        content += "\n"
    
    content += DISCLAIMER_SHORT
    
    if len(content) > 100:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "multi_airport_routes",
                "airline": airline
            }
        })
    
    return chunks


def handle_fuel_surcharge_tiers(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """fuel_surcharge_tiers 처리 - 유류할증료 단계별 정보"""
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    
    for item in items:
        airline = item.get("airline", context.get("chain", "UNKNOWN"))
        effective_date = item.get("effective_date", "")
        currency = item.get("currency", "KRW")
        
        content = f"# {airline} 유류할증료 안내\n\n"
        if effective_date:
            content += f"**적용 기준일**: {effective_date}\n\n"
        
        tiers = item.get("tiers", [])
        if tiers:
            content += "| 구간 | 유류할증료 | 포함 노선 |\n|------|----------|----------|\n"
            for tier in tiers:
                tier_name = tier.get("tier_name", "")
                amount = tier.get("amount", 0)
                routes = tier.get("routes", [])
                desc = tier.get("description", "")
                routes_str = ", ".join(routes[:5])
                if len(routes) > 5:
                    routes_str += f" 외 {len(routes)-5}개"
                if desc:
                    tier_name = f"{tier_name} ({desc})"
                content += f"| {tier_name} | {amount:,}원 | {routes_str} |\n"
            content += "\n"
        
        notes = item.get("notes", [])
        if notes:
            content += "**참고사항**:\n"
            for note in notes:
                content += f"- {note}\n"
        
        content += DISCLAIMER_SHORT
        
        if len(content) > 100:
            chunks.append({
                "content": content.strip(),
                "metadata": {
                    "type": "fuel_surcharge_tiers",
                    "airline": airline,
                    "effective_date": effective_date
                }
            })
    
    return chunks


def handle_facts_router(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """facts 라우터 - 도메인별로 적절한 핸들러로 분기
    
    호텔 도메인: NESTED_HANDLERS로 위임 (facts.pricing_analysis, facts.facilities 등)
    항공 도메인: handle_airline_facts로 처리 (price_analysis, booking_tips, warnings)
    
    이 라우터가 필요한 이유:
    - 호텔과 항공 문서 모두 'facts' 키를 사용하지만 내부 구조가 다름
    - 호텔 facts: facilities, room_types, pricing_analysis 등
    - 항공 facts: price_analysis, booking_tips, warnings 등
    """
    if not data or not isinstance(data, dict):
        return []
    
    # 도메인 감지
    chain = context.get("chain", "UNKNOWN")
    doc_type = context.get("document_type", "") or ""
    doc_category = context.get("document_category", "") or ""
    
    # 항공사 도메인 판별
    airline_chains = {
        "KOREAN_AIR", "ASIANA", "DELTA", "UNITED", "AMERICAN",
        "SINGAPORE", "ANA", "JAL", "CATHAY", "EMIRATES",
        "AIRLINE", "ALLIANCE"
    }
    
    is_airline = (
        chain in airline_chains or
        "AIRLINE" in doc_type.upper() or
        "AIRLINE" in doc_category.upper() or
        "FARE" in doc_type.upper() or
        "MILEAGE" in doc_type.upper()
    )
    
    if is_airline:
        # 항공 facts - 전용 핸들러로 처리
        return handle_airline_facts(data, context)
    
    # 호텔/기타 도메인 - NESTED_HANDLERS로 위임
    # 빈 청크 반환 → sync_to_supabase.py의 중첩 핸들러 루프에서 개별 처리됨
    # (facts.pricing_analysis, facts.facilities 등이 각각 처리됨)
    return []


def handle_airline_facts(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """facts (항공 운임 관련) 처리 - 가격 분석, 예약 팁, 주의사항
    
    주의: facts가 dict가 아닌 경우 (예: string) 빈 청크 반환
    이 함수는 handle_facts_router에서 항공 도메인일 때만 호출됨
    """
    chunks = []
    if not data:
        return chunks
    
    # 타입 안전 체크: facts가 dict가 아니면 처리하지 않음
    if not isinstance(data, dict):
        # string이나 list인 경우 빈 청크 반환 (오류 방지)
        return chunks
    
    airline = context.get("chain", "UNKNOWN")
    
    # 가격 분석
    price_analysis = data.get("price_analysis", [])
    if price_analysis and isinstance(price_analysis, list):
        content = f"# {airline} 노선별 가격 분석\n\n"
        
        for analysis in price_analysis:
            # analysis가 dict가 아니면 스킵
            if not isinstance(analysis, dict):
                continue
                
            category = analysis.get("category", "")
            description = analysis.get("description", "")
            
            if category == "cheapest_international_routes":
                content += "## 가장 저렴한 국제선 노선\n"
            elif category == "most_expensive_routes":
                content += "## 가장 비싼 국제선 노선\n"
            elif category == "seasonal_price_difference":
                content += "## 비수기-성수기 가격 차이가 큰 노선\n"
            else:
                content += f"## {description}\n"
            
            routes = analysis.get("routes", [])
            for route in routes:
                # route가 dict가 아니면 스킵
                if not isinstance(route, dict):
                    continue
                    
                route_name = route.get("route_name", "")
                route_code = route.get("route", "")
                min_price = route.get("min_price")
                max_price = route.get("max_price")
                booking_class = route.get("booking_class", "")
                note = route.get("note", "")
                
                content += f"- **{route_name}** ({route_code}): "
                if min_price is not None:
                    content += safe_format_number(min_price, "원")
                if max_price is not None:
                    if min_price is not None:
                        content += "~"
                    content += safe_format_number(max_price, "원")
                if booking_class:
                    content += f" ({booking_class} 클래스)"
                if note:
                    content += f" - {note}"
                content += "\n"
            content += "\n"
        
        content += DISCLAIMER_SHORT
        
        if len(content) > 100:
            chunks.append({
                "content": content.strip(),
                "metadata": {
                    "type": "airline_price_analysis",
                    "airline": airline
                }
            })
    
    # 예약 팁
    booking_tips = data.get("booking_tips", [])
    if booking_tips and isinstance(booking_tips, list):
        content = f"# {airline} 항공권 예약 팁\n\n"
        
        for tip in booking_tips:
            # tip이 dict가 아니면 스킵
            if not isinstance(tip, dict):
                continue
                
            title = tip.get("title", "")
            description = tip.get("description", "")
            
            content += f"## {title}\n"
            content += f"{description}\n\n"
        
        content += DISCLAIMER_SHORT
        
        if len(content) > 100:
            chunks.append({
                "content": content.strip(),
                "metadata": {
                    "type": "airline_booking_tips",
                    "airline": airline
                }
            })
    
    # 주의사항
    warnings = data.get("warnings", [])
    if warnings and isinstance(warnings, list):
        content = f"# {airline} 항공권 구매 시 주의사항\n\n"
        
        for warning in warnings:
            # warning이 dict가 아니면 스킵
            if not isinstance(warning, dict):
                continue
                
            title = warning.get("title", "")
            description = warning.get("description", "")
            severity = warning.get("severity", "")
            
            severity_icon = "🔴" if severity == "HIGH" else "🟡" if severity == "MEDIUM" else "🟢"
            content += f"## {severity_icon} {title}\n"
            content += f"{description}\n\n"
        
        content += DISCLAIMER_SHORT
        
        if len(content) > 100:
            chunks.append({
                "content": content.strip(),
                "metadata": {
                    "type": "airline_warnings",
                    "airline": airline
                }
            })
    
    return chunks


def handle_unaccompanied_minor_rules(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """unaccompanied_minor_rules 처리 - 비동반 소아 규정"""
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    airline = context.get("chain", "UNKNOWN")
    
    content = f"# {airline} 비동반 소아 (UM) 서비스 규정\n\n"
    
    for item in items:
        rule_name = item.get("rule_name", "")
        route_type = item.get("route_type", "")
        age_range = item.get("age_range", "")
        
        route_label = "국내선" if route_type == "DOMESTIC" else "국제선" if route_type == "INTERNATIONAL" else route_type
        
        content += f"## {rule_name}\n" if rule_name else f"## {route_label}\n"
        content += f"- **대상 나이**: {age_range}\n"
        
        fare_rule = item.get("fare_rule", "")
        if fare_rule:
            content += f"- **운임 규정**: {fare_rule}\n"
        
        service_fees = item.get("service_fees", [])
        if service_fees:
            content += f"- **서비스 수수료**:\n"
            for fee in service_fees:
                currency = fee.get("currency", "")
                amount = fee.get("amount", 0)
                unit = fee.get("unit", "")
                content += f"  - {currency} {amount:,} ({unit})\n"
        
        content += "\n"
    
    content += DISCLAIMER_SHORT
    
    if len(content) > 100:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "unaccompanied_minor_rules",
                "airline": airline
            }
        })
    
    return chunks


def handle_refund_rules(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """refund_rules 처리 - 환불 규정"""
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    airline = context.get("chain", "UNKNOWN")
    
    for item in items:
        rule_name = item.get("rule_name", "환불 규정")
        route_type = item.get("route_type", "")
        cabin_class = item.get("cabin_class", "")
        route_category = item.get("route_category", "")
        
        content = f"# {airline} {rule_name}\n\n"
        
        if route_type:
            route_label = "국내선" if route_type == "DOMESTIC" else "국제선" if route_type == "INTERNATIONAL" else route_type
            content += f"**노선 유형**: {route_label}\n"
        if cabin_class:
            content += f"**좌석 등급**: {cabin_class}\n"
        if route_category:
            content += f"**노선 구분**: {route_category}\n"
        
        # Required documents
        docs = item.get("required_documents", {})
        if docs:
            content += f"\n## 필요 서류\n"
            for doc_type, doc_list in docs.items():
                if isinstance(doc_list, list):
                    content += f"**{doc_type}**:\n"
                    for doc in doc_list:
                        content += f"- {doc}\n"
        
        # Fees
        fees = item.get("fees", [])
        if fees:
            content += f"\n## 수수료\n"
            for fee in fees:
                if isinstance(fee, dict):
                    fare_class = fee.get("fare_class", "")
                    fare_type = fee.get("fare_type", "")
                    fee_krw = fee.get("fee_krw", 0)
                    amount = fee.get("amount", 0)
                    currency = fee.get("currency", "")
                    
                    if fare_class:
                        content += f"- {fare_class} ({fare_type}): {fee_krw:,}원\n"
                    elif currency:
                        content += f"- {currency}: {amount:,}\n"
        
        # Penalties
        penalties = item.get("penalties", [])
        if penalties:
            content += f"\n## 환불 위약금\n"
            for penalty in penalties:
                timing = penalty.get("timing", "")
                # Get all fee values
                fee_values = []
                for key, value in penalty.items():
                    if key != "timing" and isinstance(value, (int, float)) and value >= 0:
                        fee_values.append(f"{key}: {value:,}원")
                if fee_values:
                    content += f"- **{timing}**: {', '.join(fee_values)}\n"
        
        # Waivers
        waivers = item.get("waivers", {})
        if waivers:
            content += f"\n## 면제 조건\n"
            for waiver_type, waiver_list in waivers.items():
                if isinstance(waiver_list, list):
                    content += f"**{waiver_type}**:\n"
                    for waiver in waiver_list:
                        content += f"- {waiver}\n"
        
        content += DISCLAIMER_SHORT
        
        if len(content) > 100:
            chunks.append({
                "content": content.strip(),
                "metadata": {
                    "type": "refund_rules",
                    "airline": airline,
                    "route_type": route_type,
                    "cabin_class": cabin_class
                }
            })
    
    return chunks


def handle_no_show_penalties(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """no_show_penalties 처리 - 예약부도 위약금"""
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    airline = context.get("chain", "UNKNOWN")
    
    content = f"# {airline} 예약부도 (No-Show) 위약금\n\n"
    
    for item in items:
        rule_name = item.get("rule_name", "")
        route_type = item.get("route_type", "")
        
        route_label = "국내선" if route_type == "DOMESTIC" else "국제선" if route_type == "INTERNATIONAL" else route_type
        
        content += f"## {rule_name or route_label}\n"
        
        penalty_krw = item.get("penalty_krw", 0)
        if penalty_krw:
            unit = item.get("unit", "")
            content += f"- **위약금**: {penalty_krw:,}원 ({unit})\n"
        
        condition = item.get("condition", "")
        if condition:
            content += f"- **적용 조건**: {condition}\n"
        
        penalties = item.get("penalties", [])
        if penalties:
            for penalty in penalties:
                cabin = penalty.get("cabin_class_name", "") or penalty.get("cabin_class", "")
                amount = penalty.get("penalty_krw", 0)
                content += f"- {cabin}: {amount:,}원\n"
        
        additional = item.get("additional_penalty", {})
        if additional:
            cond = additional.get("condition", "")
            add_krw = additional.get("additional_krw", 0)
            content += f"- **추가 위약금**: {cond} - {add_krw:,}원 추가\n"
        
        content += "\n"
    
    content += DISCLAIMER_SHORT
    
    if len(content) > 100:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "no_show_penalties",
                "airline": airline
            }
        })
    
    return chunks


def handle_lounge_penalties(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """lounge_penalties 처리 - 라운지 위약금"""
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    airline = context.get("chain", "UNKNOWN")
    
    content = f"# {airline} 라운지 위약금\n\n"
    
    for item in items:
        rule_name = item.get("rule_name", "")
        condition = item.get("condition", "")
        
        if rule_name:
            content += f"## {rule_name}\n"
        if condition:
            content += f"**적용 조건**: {condition}\n"
        
        fees = item.get("fees", [])
        if fees:
            content += f"\n**위약금**:\n"
            for fee in fees:
                route = fee.get("route_type", "")
                fee_krw = fee.get("fee_krw", 0)
                fee_usd = fee.get("fee_usd", 0)
                content += f"- {route}: {fee_krw:,}원 / USD {fee_usd}\n"
        
        notes = item.get("notes", [])
        if notes:
            content += f"\n**유의사항**:\n"
            for note in notes:
                content += f"- {note}\n"
        
        content += "\n"
    
    content += DISCLAIMER_SHORT
    
    if len(content) > 100:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "lounge_penalties",
                "airline": airline
            }
        })
    
    return chunks


def handle_medical_oxygen_rules(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """medical_oxygen_rules 처리 - 기내 의료용 산소 규정"""
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    airline = context.get("chain", "UNKNOWN")
    
    content = f"# {airline} 기내 의료용 산소 서비스\n\n"
    
    for item in items:
        rule_name = item.get("rule_name", "")
        
        if rule_name:
            content += f"## {rule_name}\n"
        
        fees = item.get("fees", [])
        if fees:
            content += f"\n**요금**:\n"
            for fee in fees:
                route = fee.get("route_type", "")
                fee_krw = fee.get("fee_krw", 0)
                fee_usd = fee.get("fee_usd", 0)
                unit = fee.get("unit", "")
                if fee_krw:
                    content += f"- {route}: {fee_krw:,}원 ({unit})\n"
                elif fee_usd:
                    content += f"- {route}: USD {fee_usd} ({unit})\n"
        
        intl_by_country = item.get("international_by_country", [])
        if intl_by_country:
            content += f"\n**국가별 국제선 요금**:\n"
            for country in intl_by_country:
                name = country.get("departure_country", "")
                fee_cad = country.get("fee_cad", 0)
                fee_idr = country.get("fee_idr", 0)
                fee_usd = country.get("fee_usd", 0)
                if fee_cad:
                    content += f"- {name}: CAD {fee_cad}\n"
                elif fee_idr:
                    content += f"- {name}: IDR {fee_idr:,}\n"
                elif fee_usd:
                    content += f"- {name}: USD {fee_usd}\n"
        
        additional = item.get("additional_charge", "")
        if additional:
            content += f"\n**추가 비용**: {additional}\n"
        
        content += "\n"
    
    content += DISCLAIMER_SHORT
    
    if len(content) > 100:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "medical_oxygen_rules",
                "airline": airline
            }
        })
    
    return chunks


def handle_codeshare_baggage_rules(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """codeshare_baggage_rules 처리 - 공동운항 수하물 규정"""
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    airline = context.get("chain", "UNKNOWN")
    
    content = f"# {airline} 공동운항편 수하물 규정\n\n"
    
    for item in items:
        rule_name = item.get("rule_name", "")
        policy_type = item.get("policy_type", "")
        
        if rule_name:
            content += f"## {rule_name}\n"
        
        applicable_airlines = item.get("applicable_airlines", [])
        if applicable_airlines:
            content += f"**적용 항공사**:\n"
            for airline_name in applicable_airlines:
                content += f"- {airline_name}\n"
        
        notes = item.get("notes", [])
        if notes:
            content += f"\n**유의사항**:\n"
            for note in notes:
                content += f"- {note}\n"
        
        content += "\n"
    
    content += DISCLAIMER_SHORT
    
    if len(content) > 100:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "codeshare_baggage_rules",
                "airline": airline
            }
        })
    
    return chunks


def handle_route_classifications(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """route_classifications 처리 - 노선 구분"""
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    airline = context.get("chain", "UNKNOWN")
    
    content = f"# {airline} 노선 구분 기준\n\n"
    
    for item in items:
        rule_name = item.get("rule_name", "")
        classification_type = item.get("classification_type", "")
        
        if rule_name:
            content += f"## {rule_name}\n"
        
        routes = item.get("routes", [])
        if routes:
            for route in routes:
                route_type = route.get("route_type", "")
                route_name = route.get("route_name", "")
                destinations = route.get("destinations", [])
                
                content += f"### {route_name} ({route_type})\n"
                if destinations:
                    content += "- " + ", ".join(destinations) + "\n"
                content += "\n"
    
    content += DISCLAIMER_SHORT
    
    if len(content) > 100:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "route_classifications",
                "airline": airline
            }
        })
    
    return chunks


# ===========================================================================
# 핸들러: 마일리지 효율 분석 (Mileage Efficiency Analysis)
# ===========================================================================

def handle_award_chart_entries(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """award_chart_entries 처리 - 어워드 차트 상세 항목
    
    두 가지 구조 지원:
    1) Flat 구조: [{"region": "...", "route_type": "...", "economy_low": ...}, ...]
    2) Nested 구조: [{"region": "...", "routes": [{"route": "...", ...}]}, ...]
    """
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    airline = context.get("chain", "UNKNOWN")
    
    # 구조 탐지: 첫 번째 항목에 'routes' 키가 있으면 중첩 구조
    is_nested = any(isinstance(item, dict) and "routes" in item for item in items)
    
    if is_nested:
        # === 중첩 구조 처리 (Flying Blue 스타일) ===
        for region_data in items:
            if not isinstance(region_data, dict):
                continue
            
            region = region_data.get("region", "OTHER")
            region_name = region_data.get("region_name", region)
            routes = region_data.get("routes", [])
            
            if not routes:
                continue
            
            content = f"# {airline} 어워드 차트 - {region_name}\n\n"
            content += "| 노선 | 출발 | 도착 | 이코노미 | 비즈니스 | 비고 |\n"
            content += "|------|------|------|----------|----------|------|\n"
            
            for route in routes[:50]:  # 지역당 최대 50개 노선
                if not isinstance(route, dict):
                    continue
                
                route_code = route.get("route", "")
                origin_name = route.get("origin_name", route.get("origin", ""))
                dest_name = route.get("destination_name", route.get("destination", ""))
                
                # 이코노미/비즈니스 포인트
                eco_low = route.get("economy_low")
                eco_high = route.get("economy_high")
                biz_low = route.get("business_low")
                biz_high = route.get("business_high")
                
                eco_str = f"{eco_low:,}" if eco_low else "N/A"
                if eco_high and eco_high != eco_low:
                    eco_str += f"~{eco_high:,}"
                
                if biz_low:
                    biz_str = f"{biz_low:,}"
                    if biz_high and biz_high != biz_low:
                        biz_str += f"~{biz_high:,}"
                else:
                    biz_str = "N/A"
                
                notes = route.get("notes", "") or ""
                
                content += f"| {route_code} | {origin_name} | {dest_name} | {eco_str} | {biz_str} | {notes} |\n"
            
            content += DISCLAIMER_SHORT
            
            if len(content) > 150:
                chunks.append({
                    "content": content.strip(),
                    "metadata": {
                        "type": "award_chart_entries",
                        "airline": airline,
                        "region": region,
                        "region_name": region_name
                    }
                })
    else:
        # === 기존 Flat 구조 처리 ===
        region_entries = {}
        for item in items:
            region = item.get("region", "OTHER")
            if region not in region_entries:
                region_entries[region] = []
            region_entries[region].append(item)
        
        for region, entries in region_entries.items():
            content = f"# {airline} 어워드 차트 - {region}\n\n"
            
            for entry in entries:
                route_type = entry.get("route_type", "")
                trip_type = entry.get("trip_type", "")
                trip_label = "왕복" if trip_type == "ROUND_TRIP" else "편도"
                
                content += f"## {route_type} ({trip_label})\n"
                
                # 좌석 등급별 마일리지
                economy_low = entry.get("economy_low")
                economy_high = entry.get("economy_high")
                if economy_low or economy_high:
                    content += f"- **일반석**: {economy_low:,}~{economy_high:,} 마일\n"
                
                premium_economy_low = entry.get("premium_economy_low")
                premium_economy_high = entry.get("premium_economy_high")
                if premium_economy_low or premium_economy_high:
                    content += f"- **프리미엄 이코노미**: {premium_economy_low:,}~{premium_economy_high:,} 마일\n"
                
                business_low = entry.get("business_low")
                business_high = entry.get("business_high")
                if business_low or business_high:
                    content += f"- **비즈니스/프레스티지**: {business_low:,}~{business_high:,} 마일\n"
                
                first_low = entry.get("first_low")
                first_high = entry.get("first_high")
                if first_low or first_high:
                    content += f"- **일등석**: {first_low:,}~{first_high:,} 마일\n"
                
                notes = entry.get("notes", "")
                if notes:
                    content += f"- 참고: {notes}\n"
                
                content += "\n"
            
            content += DISCLAIMER_SHORT
            
            if len(content) > 100:
                chunks.append({
                    "content": content.strip(),
                    "metadata": {
                        "type": "award_chart_entries",
                        "airline": airline,
                        "region": region
                    }
                })
    
    return chunks


def handle_route_efficiency_data(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """route_efficiency_data 처리 - nested dict 및 리스트 구조 모두 지원"""
    chunks = []
    if not data:
        return chunks
    
    # 데이터 정규화: 딕셔너리(domestic_economy, japan_business 등)라면 모든 값을 평탄화
    items = []
    if isinstance(data, dict):
        for key, val in data.items():
            if isinstance(val, list):
                items.extend(val)
            elif isinstance(val, dict):
                items.append(val)
    elif isinstance(data, list):
        items = data
    else:
        items = [data]
    
    if not items:
        return chunks
    
    airline = context.get("chain", "UNKNOWN")
    
    # 지역별로 그룹화
    region_entries = {}
    for item in items:
        region = item.get("region", "OTHER")
        if region not in region_entries:
            region_entries[region] = []
        region_entries[region].append(item)
    
    for region, entries in region_entries.items():
        # 청크가 너무 커지지 않도록 좌석 등급별로 분할
        class_entries = {}
        for entry in entries:
            cabin_class = entry.get("cabin_class", "ECONOMY")
            if cabin_class not in class_entries:
                class_entries[cabin_class] = []
            class_entries[cabin_class].append(entry)
        
        for cabin_class, class_items in class_entries.items():
            cabin_labels = {
                "ECONOMY": "일반석",
                "PREMIUM_ECONOMY": "프리미엄 이코노미",
                "BUSINESS": "프레스티지/비즈니스",
                "FIRST": "일등석"
            }
            cabin_label = cabin_labels.get(cabin_class, cabin_class)
            
            content = f"# {airline} 마일리지 효율 분석 - {region} {cabin_label}\n\n"
            content += "| 노선 | 운임 유형 | 현금가 | 필요 마일 | 효율 (원/마일) |\n"
            content += "|------|----------|--------|----------|---------------|\n"
            
            for item in class_items[:30]:  # 최대 30개
                route = item.get("route", "")
                fare_type = item.get("fare_type", "")
                cash_fare = item.get("cash_fare_krw", 0)
                required_miles = item.get("required_miles", 0)
                efficiency = item.get("efficiency_krw_per_mile", 0)
                season = item.get("season", "")
                
                season_label = " (성수기)" if season == "HIGH" else " (비수기)" if season == "LOW" else ""
                content += f"| {route} | {fare_type}{season_label} | {cash_fare:,}원 | {required_miles:,} | {efficiency:.2f} |\n"
            
            content += f"\n**효율 해석**: 숫자가 높을수록 마일리지 가치가 높습니다.\n"
            content += DISCLAIMER_SHORT
            
            if len(content) > 100:
                chunks.append({
                    "content": content.strip(),
                    "metadata": {
                        "type": "route_efficiency_data",
                        "airline": airline,
                        "region": region,
                        "cabin_class": cabin_class
                    }
                })
    
    return chunks


def handle_efficiency_ranking(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """efficiency_ranking 처리 - nested dict (top_20/worst_20) 및 리스트 구조 모두 지원"""
    chunks = []
    if not data:
        return chunks
    
    # 데이터 정규화: 딕셔너리(top_20, worst_20 등)라면 모든 값을 평탄화
    items = []
    if isinstance(data, dict):
        for key, val in data.items():
            if isinstance(val, list):
                items.extend(val)
    elif isinstance(data, list):
        items = data
    else:
        items = [data]
    
    if not items:
        return chunks
    
    airline = context.get("chain", "UNKNOWN")
    
    content = f"# {airline} 마일리지 효율 TOP 랭킹\n\n"
    content += "| 순위 | 노선 | 좌석 등급 | 효율 (원/마일) |\n"
    content += "|------|------|----------|---------------|\n"
    
    for item in items[:20]:
        rank = item.get("rank", "")
        route = item.get("route", "")
        cabin_class = item.get("cabin_class", "")
        efficiency = item.get("efficiency_krw_per_mile", 0)
        
        cabin_labels = {
            "ECONOMY": "일반석",
            "PREMIUM_ECONOMY": "프리미엄",
            "BUSINESS": "프레스티지",
            "FIRST": "일등석"
        }
        cabin_label = cabin_labels.get(cabin_class, cabin_class)
        
        content += f"| {rank} | {route} | {cabin_label} | {efficiency:.2f} |\n"
    
    content += "\n**효율 해석**: 숫자가 높을수록 마일리지 사용 시 더 큰 가치를 얻습니다.\n"
    content += DISCLAIMER_SHORT
    
    if len(content) > 100:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "efficiency_ranking",
                "airline": airline
            }
        })
    
    return chunks


def handle_mileage_efficiency_analysis(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """mileage_efficiency_analysis 처리 - 마일리지 효율 분석 메타데이터"""
    chunks = []
    if not data:
        return chunks
    
    airline = context.get("chain", "UNKNOWN")
    program = data.get("program", "")
    
    content = f"# {airline} {program} 마일리지 효율 분석 개요\n\n"
    
    analysis_date = data.get("analysis_date", "")
    if analysis_date:
        content += f"**분석 기준일**: {analysis_date}\n\n"
    
    method = data.get("calculation_method", "")
    if method:
        content += f"**계산 방법**: {method}\n\n"
    
    fare_basis_types = data.get("fare_basis_types", [])
    if fare_basis_types:
        content += "## 운임 기준 유형\n"
        for fb in fare_basis_types:
            basis_type = fb.get("basis_type", "")
            description = fb.get("description", "")
            applies_to = fb.get("applies_to", "")
            content += f"- **{basis_type}**: {description}\n"
            if applies_to:
                content += f"  - 적용 대상: {applies_to}\n"
        content += "\n"
    
    evidence = data.get("evidence", [])
    evidence_str = format_evidence(evidence)
    if evidence_str:
        content += evidence_str
    
    content += DISCLAIMER_SHORT
    
    if len(content) > 100:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "mileage_efficiency_analysis",
                "airline": airline,
                "program": program
            }
        })
    
    return chunks


def handle_fare_basis_comparison(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """fare_basis_comparison 처리 - 운임 기준별 비교"""
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    airline = context.get("chain", "UNKNOWN")
    
    content = f"# {airline} 운임 기준별 마일리지 효율 비교\n\n"
    content += "| 지역 | 좌석 등급 | 최저 운임 효율 | 최고 운임 효율 | 효율 향상 |\n"
    content += "|------|----------|--------------|--------------|----------|\n"
    
    for item in items:
        region = item.get("region", "")
        cabin_class = item.get("cabin_class", "")
        lowest_efficiency = item.get("lowest_fare_efficiency", 0)
        highest_efficiency = item.get("highest_fare_efficiency", 0)
        improvement = item.get("efficiency_improvement", "")
        
        cabin_labels = {
            "ECONOMY": "일반석",
            "PREMIUM_ECONOMY": "프리미엄",
            "BUSINESS": "프레스티지",
            "FIRST": "일등석"
        }
        cabin_label = cabin_labels.get(cabin_class, cabin_class)
        
        content += f"| {region} | {cabin_label} | {lowest_efficiency:.2f} | {highest_efficiency:.2f} | {improvement} |\n"
    
    content += "\n**분석**: 최고 운임(풀플렉스 요금)에서 마일리지 효율이 더 높습니다.\n"
    content += DISCLAIMER_SHORT
    
    if len(content) > 100:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "fare_basis_comparison",
                "airline": airline
            }
        })
    
    return chunks


def handle_key_insights(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """key_insights 처리 - 핵심 인사이트"""
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    airline = context.get("chain", "UNKNOWN")
    
    content = f"# {airline} 마일리지 효율 핵심 인사이트\n\n"
    
    for item in items[:10]:
        if not isinstance(item, dict):
            continue
        
        title = item.get("title", "")
        insight_content = item.get("content", "")
        
        if title and insight_content:
            content += f"## {title}\n"
            content += f"{insight_content}\n\n"
    
    content += DISCLAIMER_SHORT
    
    if len(content) > 100:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "key_insights",
                "airline": airline
            }
        })
    
    return chunks


def handle_usage_recommendations(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """usage_recommendations 처리 - 마일리지 사용 권장사항
    
    세 가지 구조 지원:
    1) 최상위 List 구조: [{"category": "...", "routes": [...]}]
    2) Dict 구조 (값이 dict): {"highly_recommended": {"description": "...", "routes": [...]}}
    3) Dict 구조 (값이 list): {"highly_recommended": [{route_data...}], "recommended": [...]}
    """
    chunks = []
    if not data:
        return chunks
    
    airline = context.get("chain", "UNKNOWN")
    
    content = f"# {airline} 마일리지 사용 권장사항\n\n"
    
    # 최상위가 리스트인 경우
    if isinstance(data, list):
        for idx, item in enumerate(data[:20]):
            if isinstance(item, dict):
                category = item.get("category", item.get("recommendation_type", f"항목 {idx+1}"))
                desc = item.get("description", "")
                routes = item.get("routes", [])
                
                content += f"## {category}\n"
                if desc:
                    content += f"{desc}\n\n"
                
                for route in routes[:10]:
                    if isinstance(route, dict):
                        r_name = route.get("route", route.get("route_code", ""))
                        cabin = route.get("cabin_class", "")
                        season = route.get("recommended_season", "")
                        eff_range = route.get("efficiency_range", route.get("efficiency", ""))
                        content += f"- **{r_name}** ({cabin}"
                        if season:
                            content += f", {season}"
                        content += f"): {eff_range}\n"
                    else:
                        content += f"- {route}\n"
                content += "\n"
            else:
                # 단순 문자열
                content += f"- {item}\n"
    
    # 딕셔너리 구조 처리
    elif isinstance(data, dict):
        categories = [
            ("highly_recommended", "강력 추천", 5),
            ("recommended", "추천", 3),
            ("not_recommended", "비추천", 1),
            ("booking_strategy", "예약 전략", 4),
        ]
        
        for key, default_title, _ in categories:
            category_data = data.get(key)
            if not category_data:
                continue
            
            # 값이 딕셔너리인 경우 (기존 구조)
            if isinstance(category_data, dict):
                desc = category_data.get("description", default_title)
                content += f"## {desc}\n"
                routes = category_data.get("routes", [])
                for route in routes[:10]:
                    if isinstance(route, dict):
                        r_name = route.get("route", "")
                        cabin = route.get("cabin_class", "")
                        season = route.get("recommended_season", "")
                        eff_range = route.get("efficiency_range", "")
                        if key == "not_recommended":
                            content += f"- **{r_name}** ({cabin}): {eff_range}원/마일\n"
                        else:
                            content += f"- **{r_name}** ({cabin}, {season}): {eff_range}원/마일\n"
                content += "\n"
            
            # 값이 리스트인 경우 (Aeroplan 구조)
            elif isinstance(category_data, list):
                content += f"## {default_title}\n"
                for item in category_data[:10]:
                    if isinstance(item, dict):
                        # route_category 또는 route
                        route_cat = item.get("route_category", item.get("route", ""))
                        cabin = item.get("cabin_class", "")
                        points = item.get("points_required", "")
                        recommendation = item.get("recommendation", item.get("reason", ""))
                        title = item.get("title", "")
                        desc = item.get("description", "")
                        
                        if title:  # booking_strategy 형식
                            content += f"- **{title}**: {desc}\n"
                        elif route_cat:
                            content += f"- **{route_cat}** ({cabin}"
                            if points:
                                # points가 숫자인지 확인 후 천 단위 구분자 적용
                                if isinstance(points, (int, float)):
                                    content += f", {points:,}pts"
                                else:
                                    content += f", {points}pts"
                            content += f"): {recommendation}\n"
                        else:
                            content += f"- {item}\n"
                content += "\n"
    
    content += DISCLAIMER_SHORT
    
    if len(content) > 150:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "usage_recommendations",
                "airline": airline
            }
        })
    
    return chunks


def handle_regional_efficiency_summary(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """regional_efficiency_summary 처리 - 지역별 효율 요약"""
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    airline = context.get("chain", "UNKNOWN")
    
    content = f"# {airline} 지역별 마일리지 효율 요약\n\n"
    content += "| 지역 | 일반석 평균 | 비즈니스 평균 | 비즈니스 스마티움 평균 |\n"
    content += "|------|------------|--------------|---------------------|\n"
    
    for item in items:
        if not isinstance(item, dict):
            continue
        
        region_name = item.get("region_name", item.get("region", ""))
        economy_avg = item.get("economy_avg", 0) or "-"
        business_avg = item.get("business_avg", 0) or "-"
        smartium_avg = item.get("business_smartium_avg") or "-"
        
        if isinstance(economy_avg, (int, float)):
            economy_avg = f"{economy_avg:.2f}"
        if isinstance(business_avg, (int, float)):
            business_avg = f"{business_avg:.2f}"
        if isinstance(smartium_avg, (int, float)):
            smartium_avg = f"{smartium_avg:.2f}"
        
        content += f"| {region_name} | {economy_avg} | {business_avg} | {smartium_avg} |\n"
    
    content += "\n**효율 해석**: 숫자가 높을수록 마일리지 가치가 높습니다.\n"
    content += DISCLAIMER_SHORT
    
    if len(content) > 100:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "regional_efficiency_summary",
                "airline": airline
            }
        })
    
    return chunks


def handle_seasonal_efficiency_summary(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """seasonal_efficiency_summary 처리 - 시즌별 효율 요약"""
    chunks = []
    if not data:
        return chunks
    
    items = data if isinstance(data, list) else [data]
    airline = context.get("chain", "UNKNOWN")
    
    content = f"# {airline} 시즌별 마일리지 효율 비교\n\n"
    content += "| 시즌 | 일반석 평균효율 | 비즈니스 평균효율 |\n"
    content += "|------|----------------|------------------|\n"
    
    season_labels = {
        "LOW": "비수기",
        "SHOULDER": "준성수기",
        "HIGH": "성수기"
    }
    
    for item in items:
        if not isinstance(item, dict):
            continue
        
        season = item.get("season", "")
        season_name = item.get("season_name", season_labels.get(season, season))
        economy_avg = item.get("economy_avg", 0) or 0
        business_avg = item.get("business_avg", 0) or 0
        
        content += f"| {season_name} | {economy_avg:.2f} | {business_avg:.2f} |\n"
    
    content += "\n**분석**: 성수기에는 추가 마일리지 공제로 효율이 하락합니다.\n"
    content += DISCLAIMER_SHORT
    
    if len(content) > 100:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "seasonal_efficiency_summary",
                "airline": airline
            }
        })
    
    return chunks


def handle_mileage_usage_strategy(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """mileage_usage_strategy 처리 - 마일리지 사용 전략"""
    chunks = []
    if not data:
        return chunks
    
    airline = context.get("chain", "UNKNOWN")
    
    content = f"# {airline} 마일리지 사용 전략 가이드\n\n"
    
    # 리스트 형태일 경우 직접 recommendations로 처리
    if isinstance(data, list):
        recommendations = data
    else:
        recommendations = data.get("recommendations", [])
    if recommendations:
        content += "## 추천 전략\n"
        for rec in recommendations:
            if not isinstance(rec, dict):
                content += f"- {rec}\n"
                continue
            
            # strategy_id/title/content 형식 지원 (Asiana 등)
            if rec.get("strategy_id") or rec.get("title"):
                title = rec.get("title", rec.get("strategy_id", ""))
                rec_content = rec.get("content", "")
                content += f"### {title}\n"
                if rec_content:
                    content += f"{rec_content}\n\n"
            # priority/strategy 형식 지원 (기존)
            else:
                priority = rec.get("priority", "")
                strategy = rec.get("strategy", "")
                routes = rec.get("routes", [])
                efficiency_range = rec.get("efficiency_range", "")
                
                if priority or strategy:
                    content += f"### {priority}: {strategy}\n"
                if routes:
                    content += f"- **추천 노선**: {', '.join(routes[:5])}\n"
                if efficiency_range:
                    content += f"- **효율 범위**: {efficiency_range}\n"
                content += "\n"
    
    # 딕셔너리일 경우에만 추가 필드 처리
    if isinstance(data, dict):
        # Efficiency Tiers
        efficiency_tiers = data.get("efficiency_tiers", [])
        if efficiency_tiers:
            content += "## 효율 등급\n"
            for tier in efficiency_tiers:
                if isinstance(tier, dict):
                    tier_name = tier.get("tier", "")
                    efficiency_range = tier.get("efficiency_range", "")
                    description = tier.get("description", "")
                    content += f"- **{tier_name}** ({efficiency_range}): {description}\n"
            content += "\n"
        
        # Seasonal Insight
        seasonal_insight = data.get("seasonal_insight", {})
        if seasonal_insight and isinstance(seasonal_insight, dict):
            content += "## 시즌별 인사이트\n"
            low_season = seasonal_insight.get("low_season_tip", "")
            high_season = seasonal_insight.get("high_season_tip", "")
            if low_season:
                content += f"- **비수기**: {low_season}\n"
            if high_season:
                content += f"- **성수기**: {high_season}\n"
    
    content += DISCLAIMER_SHORT
    
    if len(content) > 100:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "mileage_usage_strategy",
                "airline": airline
            }
        })
    
    return chunks


# ===========================================================================
# 핸들러: 마일리지 규정 (Mileage Rules)
# ===========================================================================

def handle_mileage_rules_generic(data: Any, context: Dict[str, Any], rule_type: str, title: str) -> List[Dict[str, Any]]:
    """범용 마일리지 규정 핸들러"""
    chunks = []
    if not data:
        return chunks
    
    airline = context.get("chain", "UNKNOWN")
    
    content = f"# {airline} {title}\n\n"
    
    if isinstance(data, list):
        for item in data[:20]:
            if isinstance(item, dict):
                for k, v in item.items():
                    content += f"- **{k}**: {v}\n"
            else:
                content += f"- {item}\n"
    elif isinstance(data, dict):
        for k, v in data.items():
            if isinstance(v, list):
                content += f"## {k}\n"
                for item in v[:10]:
                    if isinstance(item, dict):
                        desc = item.get("description", item.get("name", str(item)))
                        content += f"- {desc}\n"
                    else:
                        content += f"- {item}\n"
                content += "\n"
            elif isinstance(v, dict):
                content += f"## {k}\n"
                for sub_k, sub_v in v.items():
                    content += f"- **{sub_k}**: {sub_v}\n"
                content += "\n"
            else:
                content += f"- **{k}**: {v}\n"
    else:
        content += str(data)
    
    content += DISCLAIMER_SHORT
    
    if len(content) > 100:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": rule_type,
                "airline": airline
            }
        })
    
    return chunks


def handle_peak_season_rules(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """peak_seasons, peak_season_rules, peak_season_exemptions 처리"""
    return handle_mileage_rules_generic(data, context, "peak_season_rules", "성수기 규정")


def handle_refund_change_fees(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """refund_fees, change_fees 등 환불/변경 수수료 처리"""
    return handle_mileage_rules_generic(data, context, "refund_change_fees", "환불/변경 수수료")


def handle_mileage_booking_rules(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """booking_process, booking_notes 등 예약 규정 처리"""
    return handle_mileage_rules_generic(data, context, "mileage_booking_rules", "마일리지 항공권 예약 규정")


def handle_mileage_deduction_rules(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """business_smartium_rules, child_mileage_deduction_rules 등 마일리지 차감 규정 처리"""
    return handle_mileage_rules_generic(data, context, "mileage_deduction_rules", "마일리지 차감 규정")


def handle_route_transfer_rules(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """route_restrictions, transfer_rules 등 노선/환승 규정 처리"""
    return handle_mileage_rules_generic(data, context, "route_transfer_rules", "노선/환승 규정")


def handle_no_show_rules(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """no_show_definitions, no_show_post_processing 처리"""
    return handle_mileage_rules_generic(data, context, "no_show_rules", "노쇼 규정")


def handle_itinerary_change_rules(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """itinerary_change_rules, itinerary_change_examples 처리"""
    return handle_mileage_rules_generic(data, context, "itinerary_change_rules", "여정 변경 규정")


def handle_mileage_program_rules(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """mileage_now_program, taxes_and_fees 등 기타 프로그램 규정 처리"""
    return handle_mileage_rules_generic(data, context, "mileage_program_rules", "마일리지 프로그램 규정")


def handle_excluded_routes(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """excluded_routes 처리 - 제외 노선"""
    chunks = []
    if not data:
        return chunks
    
    airline = context.get("chain", "UNKNOWN")
    
    content = f"# {airline} 마일리지 항공권 제외/주의 노선\n\n"
    
    if isinstance(data, list):
        for route in data[:30]:
            if isinstance(route, dict):
                origin = route.get("origin", "")
                dest = route.get("destination", "")
                reason = route.get("reason", route.get("note", ""))
                content += f"- **{origin} → {dest}**: {reason}\n"
            else:
                content += f"- {route}\n"
    elif isinstance(data, dict):
        for region, routes in data.items():
            content += f"\n## {region}\n"
            if isinstance(routes, list):
                for route in routes[:10]:
                    content += f"- {route}\n"
    
    content += DISCLAIMER_SHORT
    
    if len(content) > 100:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "excluded_routes",
                "airline": airline
            }
        })
    
    return chunks


def handle_regional_efficiency_data(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """route_efficiency_data_* 지역별 효율 데이터 처리 (domestic, japan, 등)"""
    chunks = []
    if not data:
        return chunks
    
    airline = context.get("chain", "UNKNOWN")
    
    # 지역명 추출 시도
    region_name = context.get("current_key", "").replace("route_efficiency_data_", "").replace("_", " ").title()
    if not region_name:
        region_name = "Unknown Region"
    
    content = f"# {airline} {region_name} 지역 마일리지 효율 데이터\n\n"
    
    if isinstance(data, list):
        content += "| 노선 | 좌석 | 시즌 | 효율 |\n"
        content += "|------|------|------|------|\n"
        for item in data[:30]:
            if isinstance(item, dict):
                route = item.get("route", item.get("destination", "-"))
                cabin = item.get("cabin_class", item.get("class", "-"))
                season = item.get("season", "-")
                efficiency = item.get("efficiency", item.get("value", "-"))
                content += f"| {route} | {cabin} | {season} | {efficiency} |\n"
    elif isinstance(data, dict):
        for cabin_class, routes in data.items():
            content += f"\n## {cabin_class}\n"
            if isinstance(routes, list):
                for route in routes[:10]:
                    if isinstance(route, dict):
                        route_name = route.get("route", route.get("destination", "-"))
                        eff = route.get("efficiency", route.get("value", "-"))
                        content += f"- **{route_name}**: {eff}\n"
    
    content += DISCLAIMER_SHORT
    
    if len(content) > 100:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "regional_efficiency_data",
                "airline": airline,
                "region": region_name
            }
        })
    
    return chunks


# ===========================================================================
# 핸들러: 마일리지 구매 프로그램 (Mileage Purchase Programs)
# ===========================================================================

def handle_mileage_purchase_programs(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """mileage_purchase_programs 처리 - 항공사별 마일리지 구매 가격 분석"""
    chunks = []
    if not data:
        return chunks
    
    programs = data if isinstance(data, list) else [data]
    
    for program in programs:
        if not isinstance(program, dict):
            continue
        
        program_name = program.get("program_name", "Unknown Program")
        airline = program.get("airline", context.get("chain", "UNKNOWN"))
        alliance = program.get("alliance", "")
        currency_name = program.get("currency_name", "마일")
        
        content = f"# {program_name} ({airline}) 마일리지 구매 가격 분석\n\n"
        
        if alliance:
            content += f"**제휴**: {alliance}\n\n"
        
        # 기본 가격 정보
        base_price = program.get("base_price_cents")
        if base_price:
            content += f"**기본 구매가**: {base_price}센트/{currency_name}\n"
        
        # 구매 한도
        limits = program.get("purchase_limits", {})
        if limits:
            content += "\n## 구매 한도\n"
            if limits.get("minimum"):
                content += f"- 최소 구매: {limits.get('minimum'):,}\n"
            if limits.get("maximum_annual"):
                content += f"- 연간 최대: {limits.get('maximum_annual'):,}\n"
            if limits.get("maximum_monthly"):
                content += f"- 월간 최대: {limits.get('maximum_monthly'):,}\n"
        
        # 보너스 티어
        bonus_tiers = program.get("bonus_tiers", [])
        if bonus_tiers:
            content += "\n## 보너스 티어\n"
            content += "| 구매량 | 보너스율 |\n|--------|----------|\n"
            for tier in bonus_tiers[:10]:
                if isinstance(tier, dict):
                    min_amt = tier.get("purchase_amount_min", 0)
                    max_amt = tier.get("purchase_amount_max", "∞")
                    bonus_pct = tier.get("bonus_percent", 0)
                    if max_amt is None:
                        max_amt = "∞"
                    content += f"| {min_amt:,}~{max_amt} | {bonus_pct}% |\n"
        
        # 권장 구매 가격
        recommended = program.get("recommended_price", {})
        if not recommended:
            # 구/신 체계가 있는 경우
            old_system = program.get("old_system", {})
            new_system = program.get("new_system", {})
            
            if old_system.get("recommended_price"):
                rec = old_system["recommended_price"]
                content += "\n## 권장 구매 가격 (구 체계)\n"
                content += f"- **권장가**: {rec.get('standard_cents', 'N/A')}센트\n"
                content += f"- **최저가**: {rec.get('lowest_cents', 'N/A')}센트\n"
                if rec.get("rationale"):
                    content += f"- **근거**: {rec.get('rationale')}\n"
            
            if new_system.get("recommended_price"):
                rec = new_system["recommended_price"]
                content += "\n## 권장 구매 가격 (신 체계)\n"
                content += f"- **권장가**: {rec.get('standard_cents', 'N/A')}센트\n"
                content += f"- **최저가**: {rec.get('lowest_cents', 'N/A')}센트\n"
                if rec.get("rationale"):
                    content += f"- **근거**: {rec.get('rationale')}\n"
        else:
            content += "\n## 권장 구매 가격\n"
            content += f"- **권장가**: {recommended.get('standard_cents', 'N/A')}센트\n"
            content += f"- **최저가**: {recommended.get('lowest_cents', 'N/A')}센트\n"
            if recommended.get("lowest_condition"):
                content += f"- **최저 조건**: {recommended.get('lowest_condition')}\n"
            if recommended.get("rationale"):
                content += f"- **근거**: {recommended.get('rationale')}\n"
        
        # 프로모션 히스토리 요약
        promo_history = program.get("promotion_history", [])
        if not promo_history:
            old_system = program.get("old_system", {})
            new_system = program.get("new_system", {})
            promo_history = old_system.get("promotion_history", []) + new_system.get("promotion_history", [])
        
        if promo_history:
            content += "\n## 최근 프로모션 (최근 5건)\n"
            content += "| 시작일 | 종료일 | 보너스율 | 실질 단가 |\n|--------|--------|----------|----------|\n"
            for promo in promo_history[:5]:
                if isinstance(promo, dict):
                    start = promo.get("start_date", "-")
                    end = promo.get("end_date", "-")
                    bonus = promo.get("bonus_percent", "-")
                    eff_price = promo.get("effective_price_cents", "-")
                    content += f"| {start} | {end} | {bonus}% | {eff_price}센트 |\n"
        
        # 만료 정책
        expiration = program.get("expiration_policy", {})
        if expiration:
            content += "\n## 만료 정책\n"
            if expiration.get("expires"):
                content += f"- **만료 기간**: {expiration.get('expiration_period', 'N/A')}\n"
                if expiration.get("extension_method"):
                    content += f"- **연장 방법**: {expiration.get('extension_method')}\n"
            else:
                content += "- 마일리지 만료 없음\n"
        
        # Clube Smiles 등 특별 프로그램
        clube = program.get("clube_smiles", {})
        if clube:
            content += "\n## Clube Smiles 구독 플랜\n"
            plans = clube.get("plans", [])
            for plan in plans[:5]:
                if isinstance(plan, dict):
                    plan_name = plan.get("plan_name", "")
                    bonus_pct = plan.get("purchase_bonus_percent", 0)
                    max_bonus = plan.get("max_total_bonus_percent", 0)
                    content += f"- **{plan_name}**: 구매 보너스 +{bonus_pct}%, 최대 {max_bonus}%\n"
        
        content += DISCLAIMER_SHORT
        
        if len(content) > 150:
            chunks.append({
                "content": content.strip(),
                "metadata": {
                    "type": "mileage_purchase_program",
                    "airline": airline,
                    "program_name": program_name,
                    "alliance": alliance
                }
            })
    
    return chunks


def handle_mileage_price_summary(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """price_summary 처리 - 프로그램별 권장 구매 가격 요약"""
    chunks = []
    if not data:
        return chunks
    
    content = "# 항공사 마일리지 구매 가격 요약\n\n"
    content += "| 프로그램 | 권장가 | 최저가 | 보너스율 | 비고 |\n"
    content += "|----------|--------|--------|----------|------|\n"
    
    programs = data if isinstance(data, list) else [data]
    
    for program in programs:
        if not isinstance(program, dict):
            continue
        
        name = program.get("program_name", "-")
        rec_price = program.get("recommended_price_cents", "-")
        low_price = program.get("lowest_price_cents", "-")
        bonus = program.get("typical_bonus_percent", "-")
        notes = program.get("notes", "-")
        
        content += f"| {name} | {rec_price}¢ | {low_price}¢ | {bonus}% | {notes} |\n"
    
    content += "\n> **참고**: 가격은 센트/마일 기준이며, 세금 별도입니다.\n"
    content += DISCLAIMER_SHORT
    
    if len(content) > 150:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "mileage_price_summary"
            }
        })
    
    return chunks


def handle_mileage_insights(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """insights 처리 - 마일리지 구매 주요 인사이트"""
    chunks = []
    if not data or not isinstance(data, dict):
        return chunks
    
    content = "# 마일리지 구매 주요 인사이트\n\n"
    
    # 프로그램별 전략
    strategies = data.get("program_strategies", [])
    if strategies:
        content += "## 프로그램별 구매 전략\n"
        for strategy in strategies[:10]:
            if isinstance(strategy, dict):
                program = strategy.get("program", "")
                strat = strategy.get("strategy", "")
                best_use = strategy.get("best_use", "")
                risk = strategy.get("risk", "")
                
                content += f"\n### {program}\n"
                if strat:
                    content += f"- **전략**: {strat}\n"
                if best_use:
                    content += f"- **최적 사용처**: {best_use}\n"
                if risk:
                    content += f"- **리스크**: {risk}\n"
    
    # 시기별 전략
    timing = data.get("timing_strategies", [])
    if timing:
        content += "\n## 구매 시기 전략\n"
        for t in timing[:5]:
            if isinstance(t, dict):
                period = t.get("period", "")
                tip = t.get("tip", t.get("strategy", ""))
                content += f"- **{period}**: {tip}\n"
    
    # 일반 팁
    general_tips = data.get("general_tips", [])
    if general_tips:
        content += "\n## 일반 팁\n"
        for tip in general_tips[:10]:
            if isinstance(tip, dict):
                content += f"- {tip.get('tip', str(tip))}\n"
            else:
                content += f"- {tip}\n"
    
    # 주의사항
    warnings = data.get("warnings", [])
    if warnings:
        content += "\n## ⚠️ 주의사항\n"
        for w in warnings[:5]:
            if isinstance(w, dict):
                content += f"- {w.get('warning', str(w))}\n"
            else:
                content += f"- {w}\n"
    
    content += DISCLAIMER_SHORT
    
    if len(content) > 150:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "mileage_purchase_insights"
            }
        })
    
    return chunks


# ===========================================================================
# 핸들러: 딜/프로모션 (Phase 5)
# ===========================================================================

def handle_deal_alerts(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """deal_alerts 또는 deal_alert 처리"""
    chunks = []
    
    deals = data if isinstance(data, list) else [data]
    
    for deal in deals[:10]:
        if not isinstance(deal, dict):
            continue
        
        title = deal.get("title", "N/A")
        category = deal.get("category", "OTHER")
        domain = deal.get("domain", "GENERAL")
        
        content = f"""
딜/프로모션: {title}
카테고리: {category}
도메인: {domain}
"""
        
        # 관련 프로그램
        if deal.get("hotel_chain"):
            content += f"호텔: {deal.get('hotel_chain')}\n"
        if deal.get("airline"):
            content += f"항공사: {deal.get('airline')}\n"
        if deal.get("card_issuer"):
            content += f"카드사: {deal.get('card_issuer')}\n"
        
        # 기간
        start_date = deal.get("start_date", "N/A")
        end_date = deal.get("end_date", "N/A")
        content += f"\n기간: {start_date} ~ {end_date}\n"
        
        if deal.get("registration_deadline"):
            content += f"등록 마감: {deal.get('registration_deadline')}\n"
        
        # 요약 및 설명
        summary = deal.get("summary", "")
        if summary:
            content += f"\n요약: {summary}\n"
        
        description = deal.get("description", "")
        if description:
            content += f"\n상세:\n{description}\n"
        
        # 혜택
        benefits = []
        if deal.get("bonus_percentage"):
            benefits.append(f"보너스 {deal.get('bonus_percentage')}%")
        if deal.get("bonus_points"):
            benefits.append(f"+{deal.get('bonus_points'):,} 포인트")
        if deal.get("bonus_miles"):
            benefits.append(f"+{deal.get('bonus_miles'):,} 마일")
        if deal.get("discount_percentage"):
            benefits.append(f"할인 {deal.get('discount_percentage')}%")
        
        if benefits:
            content += f"\n혜택: {', '.join(benefits)}\n"
        
        # 조건
        conditions = deal.get("conditions", [])
        if conditions:
            content += "\n조건:\n"
            for cond in conditions[:5]:
                content += f"  - {cond}\n"
        
        # 프로모션 코드
        if deal.get("promo_code"):
            content += f"\n프로모션 코드: {deal.get('promo_code')}\n"
        
        # 타겟/중복 가능 여부
        flags = []
        if deal.get("is_targeted"):
            flags.append("타겟 오퍼")
        if deal.get("is_stackable"):
            flags.append("중복 가능")
        if flags:
            content += f"참고: {', '.join(flags)}\n"
        
        content += DISCLAIMER_SHORT
        
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "deal_alert",
                "title": title,
                "category": category,
                "end_date": str(end_date) if end_date else None
            }
        })
    
    return chunks


def handle_news_updates(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """news_updates 또는 news_update 처리"""
    chunks = []
    
    news_list = data if isinstance(data, list) else [data]
    
    for news in news_list[:10]:
        if not isinstance(news, dict):
            continue
        
        title = news.get("title", "N/A")
        category = news.get("category", "OTHER")
        domain = news.get("domain", "GENERAL")
        
        content = f"""
뉴스/업데이트: {title}
카테고리: {category}
도메인: {domain}
"""
        
        # 관련 프로그램
        if news.get("hotel_chain"):
            content += f"호텔: {news.get('hotel_chain')}\n"
        if news.get("airline"):
            content += f"항공사: {news.get('airline')}\n"
        if news.get("card_issuer"):
            content += f"카드사: {news.get('card_issuer')}\n"
        
        # 날짜
        if news.get("published_date"):
            content += f"발행일: {news.get('published_date')}\n"
        if news.get("effective_date"):
            content += f"시행일: {news.get('effective_date')}\n"
        
        # 요약 및 내용
        summary = news.get("summary", "")
        if summary:
            content += f"\n요약: {summary}\n"
        
        full_content = news.get("content", "")
        if full_content:
            # 긴 내용은 일부만
            if len(full_content) > 500:
                content += f"\n내용:\n{full_content[:500]}...\n"
            else:
                content += f"\n내용:\n{full_content}\n"
        
        # 영향도
        impact = news.get("impact")
        impact_summary = news.get("impact_summary")
        if impact or impact_summary:
            content += "\n영향:\n"
            if impact:
                impact_labels = {
                    "positive": "긍정적 ✅",
                    "negative": "부정적 ❌",
                    "neutral": "중립 ⚪"
                }
                content += f"  - 영향도: {impact_labels.get(impact, impact)}\n"
            if impact_summary:
                content += f"  - {impact_summary}\n"
        
        # 태그
        tags = news.get("tags", [])
        if tags:
            content += f"\n태그: {', '.join(tags[:5])}\n"
        
        content += DISCLAIMER_SHORT
        
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": "news_update",
                "title": title,
                "category": category,
                "impact": impact
            }
        })
    
    return chunks



# ===========================================================================
# 핸들러: 월별 가격 상세 (현금/포인트)
# ===========================================================================

def handle_monthly_prices_detailed(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """monthly_cash_prices_detailed, monthly_points_prices_detailed 처리
    
    월별 날짜별 상세 가격 데이터를 시즌별로 요약하여 청크 생성
    """
    chunks = []
    hotel_name, hotel_name_ko, chain = get_hotel_info(context)
    
    if not isinstance(data, dict):
        return chunks
    
    # 가격 유형 판단 (포인트 vs 현금)
    is_points = any("points" in str(list(v[0].keys()) if isinstance(v, list) and v else []) 
                    for v in data.values() if v)
    
    price_type = "포인트" if is_points else "현금"
    content_type = "monthly_points_prices" if is_points else "monthly_cash_prices"
    
    content = format_hotel_header(hotel_name, hotel_name_ko, chain)
    content += f"월별 {price_type} 가격 상세:\n\n"
    
    # 월별로 통계 계산
    for month_key, prices_list in list(data.items())[:12]:
        if not isinstance(prices_list, list) or not prices_list:
            continue
        
        # 월 이름 포맷
        month_name = month_key.replace("_", " ").title()
        
        # 가격/포인트 추출
        if is_points:
            values = [p.get("points", 0) for p in prices_list if isinstance(p, dict) and p.get("points")]
        else:
            values = [p.get("price_krw", 0) for p in prices_list if isinstance(p, dict) and p.get("price_krw")]
        
        if not values:
            continue
        
        min_val = min(values)
        max_val = max(values)
        
        if is_points:
            content += f"• {month_name}: {min_val:,}P ~ {max_val:,}P\n"
        else:
            content += f"• {month_name}: ₩{min_val:,} ~ ₩{max_val:,}\n"
    
    content += DISCLAIMER_PRICE
    
    if len(content) > 150:
        chunks.append({
            "content": content.strip(),
            "metadata": {
                "type": content_type,
                "hotel_name": hotel_name
            }
        })
    
    return chunks


# ===========================================================================
# 핸들러: 객실 유형별 요금
# ===========================================================================

def handle_room_rates_by_type(data: Any, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """room_rates_by_type 처리 - 객실 유형별 멤버 요금"""
    chunks = []
    hotel_name, hotel_name_ko, chain = get_hotel_info(context)
    
    if not isinstance(data, list) or not data:
        return chunks
    
    content = format_hotel_header(hotel_name, hotel_name_ko, chain)
    content += "객실 유형별 멤버 요금:\n\n"
    
    for room in data[:15]:
        if not isinstance(room, dict):
            continue
        
        room_type = room.get("room_type", "N/A")
        rate = room.get("member_rate_krw", room.get("rate", "N/A"))
        notes = room.get("notes", "")
        
        if isinstance(rate, (int, float)):
            content += f"• {room_type}: ₩{rate:,}"
        else:
            content += f"• {room_type}: {rate}"
        
        if notes:
            content += f" ({notes})"
        content += "\n"
    
    content += DISCLAIMER_PRICE
    
    chunks.append({
        "content": content.strip(),
        "metadata": {
            "type": "room_rates_by_type",
            "hotel_name": hotel_name
        }
    })
    
    return chunks


# ===========================================================================
# 키-핸들러 매핑
# ===========================================================================

# 키 이름 → 핸들러 매핑
# 같은 핸들러를 여러 키에 매핑 가능
CHUNK_HANDLERS = {
    # 로열티 프로그램
    "loyalty_programs": handle_loyalty_programs,
    "loyalty_program": handle_loyalty_programs,

    # 멤버십 등급
    "membership_tiers": handle_membership_tiers,
    
    # 마일스톤 프로그램
    "milestone_program": handle_milestone_programs,
    "milestone_programs": handle_milestone_programs,
    "milestones": handle_milestone_programs,
    
    # 파트너 등급 매칭
    "partner_status_matches": handle_partner_status_matches,
    "partner_status_match": handle_partner_status_matches,

    # 포인트 시스템
    "points_systems": handle_points_systems,
    "points_system": handle_points_systems,

    # 호텔
    "hotel_properties": handle_hotel_properties,
    "hotel_brands": handle_hotel_brands,

    # 등급별 구현
    "tier_implementations": handle_tier_implementations,

    # 크레딧 카드
    "credit_cards": handle_credit_cards,

    # 구독 프로그램
    "subscription_programs": handle_subscription_programs,

    # 프로모션
    "promotions": handle_promotions,

    # 가격/포인트
    "pricing": handle_pricing,
    "pricing_analysis": handle_pricing_analysis,
    "pricing_2025": handle_pricing,  # 연도별 요금 정보
    "pricing_2026": handle_pricing,
    "pricing_2027": handle_pricing,

    # 혜택
    "benefits": handle_benefits,

    # Best Rate Guarantee
    "best_rate_guarantee": handle_best_rate_guarantee,

    # 채널 구현
    "channel_implementations": handle_channel_implementations,

    # 채널 혜택 패키지
    "channel_benefit_packages": handle_channel_benefit_packages,

    # 호텔 시설
    "hotel_facilities": handle_hotel_facilities,
    "other_facilities": handle_hotel_facilities,
    
    # 이그제큐티브 라운지 - hotel_facilities 핸들러로 통합 처리
    "executive_lounge": handle_hotel_facilities,
    
    # 웰니스 시설 - hotel_facilities 핸들러로 통합 처리
    "pulse8_wellness": handle_hotel_facilities,
    "wellness_facility": handle_hotel_facilities,
    "spa_wellness": handle_hotel_facilities,
    
    # 호텔 어메니티 요약 - hotel_facilities 핸들러로 통합 처리
    "hotel_amenities_summary": handle_hotel_facilities,
    "amenities_summary": handle_hotel_facilities,
    
    # 월별 가격 상세 (고유 구조로 별도 핸들러 유지)
    "monthly_cash_prices_detailed": handle_monthly_prices_detailed,
    "monthly_points_prices_detailed": handle_monthly_prices_detailed,
    
    # 객실 유형별 요금 (고유 구조로 별도 핸들러 유지)
    "room_rates_by_type": handle_room_rates_by_type,

    # 객실 유형
    "room_types": handle_room_types,

    # 객실 어메니티
    "room_common_amenities": handle_room_amenities,
    "room_common_features": handle_room_amenities,

    # 레스토랑/다이닝
    "restaurants": handle_restaurants,
    "breakfast_options": handle_breakfast,
    "breakfast_special_features": handle_breakfast,
    "dining_programs": handle_dining_programs,

    # 평점
    "ratings": handle_ratings,
    
    # 가격 분석 (Core 키)
    "price_analysis": handle_pricing_analysis,
    
    # 회원 요금
    "member_rates": handle_member_rates,

    # 정책 관련 (혜택 핸들러로 처리)
    "blackout_periods": handle_benefits,
    "excluded_rate_types": handle_benefits,
    "excluded_rate_evidence": handle_benefits,
    "excluded_properties": handle_benefits,
    "regional_exceptions": handle_benefits,
    "elite_qualifying_points_rules": handle_benefits,
    "rate_classifications": handle_benefits,
    "rollover_nights_policy": handle_benefits,
    "sub_programs": handle_benefits,
    "point_exclusions": handle_benefits,
    "general_policies": handle_benefits,
    "tier_upgrade_exclusion_rules": handle_benefits,
    "overseas_usage_info": handle_benefits,
    "performance_calculation_rules": handle_benefits,
    "family_card_info": handle_benefits,
    "customer_service": handle_benefits,
    "common_benefits": handle_benefits,
    "elite_night_credit_rules": handle_benefits,
    "amex_common_benefits": handle_benefits,
    "annual_choice_benefits": handle_benefits,
    "partner_programs": handle_benefits,
    "non_qualifying_rates": handle_benefits,
    "key_policies": handle_benefits,

    # 카드 혜택/할인 관련 (Phase 3 확장)
    "club_lounge_services": handle_benefits,      # 클럽 라운지 서비스
    "spending_exclusions": handle_benefits,       # 적립 제외 항목
    "account_linking_guide": handle_benefits,     # 계정 연동 가이드
    "hotel_discounts": handle_benefits,           # 호텔 할인 혜택
    "spa_discounts": handle_benefits,             # 스파 할인 혜택
    "airport_lounges": handle_benefits,           # 공항 라운지 혜택

    # 시설/호텔 정보 관련
    "dining_venues": handle_restaurants,
    "dining_details": handle_restaurants,
    "room_service": handle_restaurants,
    "policies": handle_hotel_facilities,
    "facilities": handle_hotel_facilities,

    # FHR/아멕스 관련 (채널 구현 또는 혜택으로 처리)
    "partner_program": handle_benefits,
    "channel_comparison": handle_benefits,
    "booking_payment_rules": handle_benefits,
    "eligible_cards": handle_benefits,
    "korea_cards": handle_benefits,
    "korea_booking": handle_benefits,
    "price_comparison": handle_pricing,
    "point_earning_rules": handle_benefits,
    "korea_amex_usage": handle_benefits,
    "korea_cardholder_guides": handle_benefits,
    "terms_and_conditions": handle_benefits,
    
    # --- 항공 프로그램 (Phase 2) ---
    "airline_programs": handle_airline_programs,
    "airline_program": handle_airline_programs,
    "airline_partnership": handle_airline_partnership,  # Flying Blue → Korean Air 등
    "airline_tiers": handle_airline_tiers,
    "airline_tier": handle_airline_tiers,
    "award_charts": handle_award_charts,
    "award_chart": handle_award_charts,
    "airline_earning_rules": handle_airline_earning_rules,

    
    # --- 항공 운임 (Airline Fares) ---
    "airline_fare_tables": handle_airline_fare_tables,
    "domestic_fare_rules": handle_domestic_fare_rules,
    "domestic_peak_seasons": handle_domestic_peak_seasons,
    "domestic_route_fares": handle_domestic_route_fares,
    "codeshare_domestic_fares": handle_codeshare_domestic_fares,
    "international_route_fares": handle_international_route_fares,
    "fare_comparison_summary": handle_fare_comparison_summary,
    "important_notes": handle_important_notes,
    
    # --- 항공 부가 요금 규정 (Extra Fee Rules) ---
    "baggage_rules": handle_baggage_rules,
    "baggage_general_rules": handle_baggage_general_rules,
    "sports_equipment_rules": handle_sports_equipment_rules,
    "pet_transport_rules": handle_pet_transport_rules,
    "unaccompanied_minor_rules": handle_unaccompanied_minor_rules,
    "refund_rules": handle_refund_rules,
    "no_show_penalties": handle_no_show_penalties,
    "lounge_penalties": handle_lounge_penalties,
    "medical_oxygen_rules": handle_medical_oxygen_rules,
    "codeshare_baggage_rules": handle_codeshare_baggage_rules,
    "route_classifications": handle_route_classifications,
    
    # --- 항공 운임 추가 정보 (시즌, 클래스, 세금, 공항, 유류할증료, 팩트) ---
    "international_season_definitions": handle_international_season_definitions,
    "booking_class_definitions": handle_booking_class_definitions,
    "special_tax_structures": handle_special_tax_structures,
    "multi_airport_routes": handle_multi_airport_routes,
    "fuel_surcharge_tiers": handle_fuel_surcharge_tiers,
    "facts": handle_facts_router,  # 도메인별 라우팅 (호텔 → NESTED, 항공 → handle_airline_facts)
    
    # --- 딜/뉴스 (Phase 5) ---
    "deal_alerts": handle_deal_alerts,
    "deal_alert": handle_deal_alerts,
    "news_updates": handle_news_updates,
    "news_update": handle_news_updates,
    
    # --- 마일리지 효율 분석 (Mileage Efficiency) ---
    "award_chart_entries": handle_award_chart_entries,
    "mileage_efficiency_analysis": handle_mileage_efficiency_analysis,
    "route_efficiency_data_lowest_fare": handle_route_efficiency_data,
    "route_efficiency_data_highest_fare": handle_route_efficiency_data,
    "efficiency_ranking_lowest_fare_low_season": handle_efficiency_ranking,
    "efficiency_ranking_highest_fare_low_season": handle_efficiency_ranking,
    "efficiency_ranking_lowest_fare_high_season": handle_efficiency_ranking,
    "efficiency_ranking_highest_fare_high_season": handle_efficiency_ranking,
    "fare_basis_comparison": handle_fare_basis_comparison,
    "mileage_usage_strategy": handle_mileage_usage_strategy,
    
    # --- 누락된 마일리지 효율 분석 키 매핑 추가 ---
    "route_efficiency_data": handle_route_efficiency_data,  # nested dict 구조 지원
    "efficiency_ranking": handle_efficiency_ranking,  # nested dict (top_20/worst_20) 지원
    "key_insights": handle_key_insights,  # 핵심 인사이트
    "usage_recommendations": handle_usage_recommendations,  # 사용 권장사항
    "strategy_recommendations": handle_mileage_usage_strategy,  # 기존 핸들러 재사용
    "regional_efficiency_summary": handle_regional_efficiency_summary,  # 지역별 효율 요약
    "seasonal_efficiency_summary": handle_seasonal_efficiency_summary,  # 시즌별 효율 요약
    
    # --- 추가 마일리지 효율 키 매핑 ---
    "route_efficiency_evidence": handle_route_efficiency_data,  # 노선별 효율 증거
    "business_vs_smartium_comparison": handle_fare_basis_comparison,  # 비즈니스 vs 스마티움 비교
    "weekday_weekend_comparison": handle_fare_basis_comparison,  # 주중/주말 효율 비교
    "usage_recommendations_detailed": handle_usage_recommendations,  # 상세 권장사항
    
    # --- 마일리지 규정 관련 키 매핑 (신규 추가) ---
    # 성수기/시즌 규정
    "peak_seasons": handle_peak_season_rules,
    "peak_season_rules": handle_peak_season_rules,
    "peak_season_exemptions": handle_peak_season_rules,
    
    # 마일리지 차감 규정
    "business_smartium_rules": handle_mileage_deduction_rules,
    "child_mileage_deduction_rules": handle_mileage_deduction_rules,
    
    # 노선/환승 규정
    "route_restrictions": handle_route_transfer_rules,
    "transfer_rules": handle_route_transfer_rules,
    
    # 환불/변경 수수료
    "refund_fees": handle_refund_change_fees,
    "change_fees": handle_refund_change_fees,
    "fee_exemptions": handle_refund_change_fees,
    "refund_channel_restrictions": handle_refund_change_fees,
    "online_change_fee_rules": handle_refund_change_fees,
    "mileage_refund_calculation": handle_refund_change_fees,
    "mileage_validity_on_refund": handle_refund_change_fees,
    "change_additional_costs": handle_refund_change_fees,
    "fuel_surcharge_change_rules": handle_refund_change_fees,
    
    # 노쇼 규정
    "no_show_definitions": handle_no_show_rules,
    "no_show_post_processing": handle_no_show_rules,
    
    # 여정 변경 규정
    "itinerary_change_rules": handle_itinerary_change_rules,
    "itinerary_change_examples": handle_itinerary_change_rules,
    
    # 프로그램/세금 규정
    "mileage_now_program": handle_mileage_program_rules,
    "taxes_and_fees": handle_mileage_program_rules,
    
    # 예약 규정
    "booking_process": handle_mileage_booking_rules,
    "booking_notes": handle_mileage_booking_rules,
    
    # 제외 노선
    "excluded_routes": handle_excluded_routes,
    
    # --- 지역별 효율 데이터 (Asiana 등) ---
    "route_efficiency_data_domestic": handle_regional_efficiency_data,
    "route_efficiency_data_japan": handle_regional_efficiency_data,
    "route_efficiency_data_china_northeast_asia": handle_regional_efficiency_data,
    "route_efficiency_data_southeast_asia": handle_regional_efficiency_data,
    "route_efficiency_data_south_asia_cis": handle_regional_efficiency_data,
    "route_efficiency_data_oceania": handle_regional_efficiency_data,
    "route_efficiency_data_americas": handle_regional_efficiency_data,
    "route_efficiency_data_europe": handle_regional_efficiency_data,
    "efficiency_ranking_low_season": handle_efficiency_ranking,
    
    # --- 마일리지 구매 프로그램 (Mileage Purchase Programs) ---
    "mileage_purchase_programs": handle_mileage_purchase_programs,
    "price_summary": handle_mileage_price_summary,
    "insights": handle_mileage_insights,

    # --- 미처리 키들을 적절한 핸들러에 매핑 ---
    "raw_pricing_data": handle_pricing,               # ClassicTravel 원시 가격 데이터
    "rate_descriptions": handle_benefits,             # ClassicTravel 요금 설명
    "brunch_options": handle_breakfast,               # ClassicTravel 브런치 옵션
    "regional_info": handle_hotel_facilities,         # ClassicTravel 지역 정보
    "breakfast_benefit_participating_brands": handle_benefits, # GHA Discovery 조식 혜택 참여 브랜드
    "direct_channels": handle_benefits,               # GHA Discovery 직접 채널
    "irregular_prices_observed": handle_pricing,      # 항공사 불규칙 가격 관찰
    "route_availability_patterns": handle_airline_programs, # 항공사 노선 가용성 패턴
    "booking_policies": handle_benefits,              # WhataHotel 예약 정책 (서비스 수수료, 결제 정책, 취소 정책)
    
    # --- AMEX Platinum 카드 전용 키 매핑 ---
    "travel_programs": handle_benefits,               # FHR, THC 등 여행 프로그램
    "statement_credit_timing": handle_benefits,       # 스테이트먼트 크레딧 처리 시간
    "statement_credit_troubleshooting": handle_benefits, # 크레딧 문제 해결 팁
    "tier_eligibility_comparison": handle_benefits,   # 등급 자격 비교표
    "benefit_exclusions": handle_benefits,            # 혜택 제외 항목
    "benefit_calendar": handle_benefits,              # 혜택 일정 (월간/분기/연간)
    "contact_information": handle_benefits,           # 연락처 정보
    "important_notices": handle_benefits,             # 중요 공지사항
    "benefit_value_summary": handle_benefits,         # 혜택 가치 요약
    
    # --- Chase 카드 관련 키 매핑 ---
    "lounge_access_details": handle_benefits,         # 공항 라운지 접근 정보
    "spending_tier_benefits": handle_benefits,        # 지출 등급별 혜택
    "balance_transfer_conditions": handle_benefits,   # 잔액 이체 조건
    "chase_pay_over_time": handle_benefits,           # Chase 할부 결제 옵션
    "state_notices": handle_benefits,                 # 주별 고지사항
    "mileageplus_integration": handle_benefits,       # MileagePlus 연동 정보
    "privacy_legal": handle_benefits,                 # 개인정보/법적 고지
    "concierge_services": handle_benefits,            # 컨시어지 서비스
    "other_info": handle_benefits,                    # 기타 정보
    
    # --- 추가 미처리 키 매핑 (credit card 관련) ---
    "ihg_membership_earning_rules": handle_benefits,  # IHG 멤버십 적립 규칙
    "points_expiration_policy": handle_benefits,      # 포인트 만료 정책
    "terms_summary": handle_benefits,                 # 약관 요약
    "hyatt_brands_reference": handle_hotel_brands,    # Hyatt 브랜드 목록
    "ihg_program_earning_info": handle_benefits,      # IHG 프로그램 적립 정보
    "related_cards_comparison": handle_benefits,      # 관련 카드 비교
    "value_analysis": handle_benefits,                # 가치 분석
    
    # --- Disney 카드 전용 키 매핑 ---
    "dining_eligible_restaurants": handle_benefits,   # Disney 식당 할인 대상 레스토랑
    "tour_eligible_experiences": handle_benefits,     # Disney 투어/체험 할인 대상
    "photo_opportunities": handle_benefits,           # Disney 카드 포토 기회
    
    # --- IHG/United 카드 관련 키 매핑 ---
    "airline_program_integration": handle_benefits,   # 항공사 프로그램 연동

    # --- 추가 미처리 키 매핑 (Citi/Barclays/BoA 카드) ---
    "aadvantage_program_tiers": handle_benefits,      # AAdvantage 프로그램 등급
    "american_eagle_operators": handle_benefits,      # American Eagle 운항사
    "additional_benefits": handle_benefits,           # 추가 혜택
    "insurance_benefits": handle_benefits,            # 보험 혜택
    "security_features": handle_benefits,             # 보안 기능
    "entertainment_program": handle_benefits,         # 엔터테인먼트 프로그램
    "annual_benefit_value_summary": handle_benefits,  # 연간 혜택 가치 요약
    "card_benefits": handle_benefits,                 # 카드 혜택 (최상위 키)
    "eligibility_requirements": handle_benefits,      # 자격 요건
    "balance_transfer_terms": handle_benefits,        # 잔액 이체 조건
    "cash_equivalent_transactions": handle_benefits,  # 현금 등가 거래
    "points_forfeiture_conditions": handle_benefits,  # 포인트 몰수 조건
    "trueblue_integration": handle_benefits,          # TrueBlue 연동
    "trueblue_points_important_info": handle_benefits, # TrueBlue 포인트 중요 정보
    "additional_info": handle_benefits,               # 추가 정보
    "partnership_programs": handle_benefits,          # 파트너십 프로그램
}

# 중첩 키 지원 (예: facts.pricing_analysis)
NESTED_HANDLERS = {
    # facts.* 키들 (범용 핸들러로 처리)
    "facts.pricing_analysis": handle_pricing_analysis,
    "facts.pricing_insights": handle_pricing_analysis,
    "facts.pricing_2025": handle_pricing,  # 연도별 가격 정보
    "facts.pricing_2026": handle_pricing,
    "facts.pricing_2027": handle_pricing,
    "facts.user_tips": None,  # 범용 텍스트로 처리 예정
    "facts.pros_cons": None,
    "facts.dining_venues": handle_restaurants,
    "facts.facilities": handle_hotel_facilities,
    "facts.room_types": handle_room_types,
}

# 무시할 키 (메타데이터 등 - 검색 가치 낮음)
IGNORED_KEYS = {
    # 메타데이터
    "extraction_timestamp",
    "extractor_model",
    "schema_version",
    "document_reference",
    "identity",
    "source",
    "version",
    "document_metadata",
    "extraction_metadata",
    "extraction_notes",
    "analysis_metadata",  # 분석 메타데이터
    
    # 내부/참조용
    "evidence",
    "extra_attributes",
    "data_sources",
    "verification_needed",
    "price_summary_evidence",  # 가격 요약 증거 (별도 핸들러 불필요)
    
    # 중첩 핸들러로 처리 (호텔 facts는 NESTED_HANDLERS에서 처리)
    # "facts" - 항공 운임용은 handle_airline_facts에서 처리
    
    # Core 키에 포함되므로 별도 처리 불필요
    # "hotel_brands",  # 이제 handle_hotel_brands로 처리
    "nearby_attractions",  # extra_attributes에 포함
    
    # 검색 가치 낮음
    "loyalty_program_features",  # loyalty_program으로 커버
    "breakfast_special_features",  # breakfast_options으로 커버
    "unverified_items",
    "unverified_items_evidence",
    "pending_items",
    "to_verify",
    "sources",
    "legal_provisions",
    "external_references",
    "general_terms",
    "pros_cons",
    "verification_needed",  # 확인 필요 사항 (검색 가치 낮음)
    "collection_date",  # 수집일 메타데이터
    "related_documents",  # 관련 문서 참조
    
    # AMEX 카드 관련 증거자료 및 법적 정보 (검색 가치 낮음)
    "seller_of_travel",  # 여행 판매자 법적 정보
    "statement_credit_evidence",  # 스테이트먼트 크레딧 증거
    "verification_needed_evidence",  # 확인 필요 사항 증거
    
    # Chase 카드 관련 메타데이터 (검색 가치 낮음)
    "related_links",  # 관련 링크 (URL 참조용)
    "benefit_value_summary_total",  # 혜택 가치 총합 (메타데이터)
    "spending_tier_120k_additional",  # 추가 지출 등급 (상세 내용 없음)
    "benefit_value_evidence",  # 혜택 가치 증거 (내부용)
    "legal_notices",  # 법적 고지사항
    
    # Deprecated 키 (사용하지 않음)
    # "loyalty_programs" (복수) - 단, 하위 호환성 위해 핸들러는 유지
}



def get_handler(key: str):
    """키에 대한 핸들러 반환"""
    return CHUNK_HANDLERS.get(key)


def get_nested_handler(parent_key: str, child_key: str):
    """중첩 키에 대한 핸들러 반환"""
    nested_key = f"{parent_key}.{child_key}"
    return NESTED_HANDLERS.get(nested_key)


def is_ignored(key: str) -> bool:
    """무시해야 할 키인지 확인"""
    return key in IGNORED_KEYS


def get_all_handler_keys() -> set:
    """처리 가능한 모든 키 반환"""
    keys = set(CHUNK_HANDLERS.keys())
    keys.update(IGNORED_KEYS)
    return keys