# Instagram Graph API POC 설계 문서

## 📋 1. 요구사항 요약

### 1.1 기능적 요구사항

| 기능 | 설명 | 우선순위 |
|------|------|----------|
| 인증 | Access Token 관리, Long-lived Token 교환, Token 검증 | 필수 |
| 계정 정보 | 비즈니스 계정 ID 조회, 프로필 정보 조회 | 필수 |
| 미디어 관리 | 목록/상세 조회, 이미지/비디오 게시 (Container → Publish) | 필수 |
| 인사이트 | 계정/미디어별 인사이트 조회 | 필수 |
| 댓글 관리 | 댓글 조회, 답글 작성 | 필수 |

### 1.2 비기능적 요구사항

- **비동기 처리**: 모든 API 호출은 async/await 사용
- **Rate Limit 준수**: 시간당 200 요청 제한, 429 에러 시 지수 백오프
- **에러 처리**: 체계적인 예외 계층 구조
- **로깅**: 요청/응답 추적 가능
- **보안**: Credentials 환경변수 관리, 민감정보 로깅 방지

---

## 📐 2. 설계 개요

### 2.1 아키텍처 다이어그램

```
┌─────────────────────────────────────────────────────────────────┐
│                         examples/                                │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐            │
│  │ auth_example │ │media_example │ │insights_example│           │
│  └──────┬───────┘ └──────┬───────┘ └──────┬───────┘            │
└─────────┼────────────────┼────────────────┼─────────────────────┘
          │                │                │
          ▼                ▼                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    InstagramGraphClient                          │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  - _request()          : 공통 HTTP 요청 (재시도, 로깅)    │   │
│  │  - debug_token()       : 토큰 검증                       │   │
│  │  - exchange_token()    : Long-lived 토큰 교환            │   │
│  │  - get_account()       : 계정 정보 조회                  │   │
│  │  - get_media_list()    : 미디어 목록                     │   │
│  │  - get_media()         : 미디어 상세                     │   │
│  │  - publish_image()     : 이미지 게시                     │   │
│  │  - publish_video()     : 비디오 게시                     │   │
│  │  - get_account_insights() : 계정 인사이트                │   │
│  │  - get_media_insights()   : 미디어 인사이트              │   │
│  │  - get_comments()      : 댓글 조회                       │   │
│  │  - reply_comment()     : 댓글 답글                       │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
          │                │                │
          ▼                ▼                ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│    models.py    │ │  exceptions.py  │ │    config.py    │
│  (Pydantic v2)  │ │ (커스텀 예외)    │ │   (Settings)    │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```

### 2.2 모듈 의존성 관계

```
config.py ◄─────────────────────────────────────┐
    │                                            │
    ▼                                            │
exceptions.py ◄─────────────────────┐           │
    │                                │           │
    ▼                                │           │
models.py ◄──────────────┐          │           │
    │                     │          │           │
    ▼                     │          │           │
client.py ────────────────┴──────────┴───────────┘
    │
    ▼
examples/ (사용 예제)
```

---

## 🌐 3. API 설계 (Instagram Graph API 엔드포인트)

### 3.1 Base URL
```
https://graph.instagram.com (Instagram Platform API)
https://graph.facebook.com/v21.0 (Facebook Graph API - 일부 기능)
```

### 3.2 인증 API

#### 3.2.1 토큰 검증 (Debug Token)
```
GET /debug_token
?input_token={access_token}
&access_token={app_id}|{app_secret}

Response:
{
  "data": {
    "app_id": "123456789",
    "type": "USER",
    "application": "App Name",
    "expires_at": 1234567890,
    "is_valid": true,
    "scopes": ["instagram_basic", "instagram_content_publish"],
    "user_id": "17841400000000000"
  }
}
```

#### 3.2.2 Long-lived Token 교환
```
GET /access_token
?grant_type=ig_exchange_token
&client_secret={app_secret}
&access_token={short_lived_token}

Response:
{
  "access_token": "IGQVJ...",
  "token_type": "bearer",
  "expires_in": 5184000  // 60일 (초)
}
```

#### 3.2.3 토큰 갱신
```
GET /refresh_access_token
?grant_type=ig_refresh_token
&access_token={long_lived_token}

Response:
{
  "access_token": "IGQVJ...",
  "token_type": "bearer",
  "expires_in": 5184000
}
```

### 3.3 계정 API

#### 3.3.1 계정 정보 조회
```
GET /me
?fields=id,username,name,account_type,profile_picture_url,followers_count,follows_count,media_count
&access_token={access_token}

Response:
{
  "id": "17841400000000000",
  "username": "example_user",
  "name": "Example User",
  "account_type": "BUSINESS",
  "profile_picture_url": "https://...",
  "followers_count": 1000,
  "follows_count": 500,
  "media_count": 100
}
```

### 3.4 미디어 API

#### 3.4.1 미디어 목록 조회
```
GET /{ig-user-id}/media
?fields=id,media_type,media_url,thumbnail_url,caption,timestamp,permalink,like_count,comments_count
&limit=25
&access_token={access_token}

Response:
{
  "data": [
    {
      "id": "17880000000000000",
      "media_type": "IMAGE",
      "media_url": "https://...",
      "caption": "My photo",
      "timestamp": "2024-01-01T00:00:00+0000",
      "permalink": "https://www.instagram.com/p/...",
      "like_count": 100,
      "comments_count": 10
    }
  ],
  "paging": {
    "cursors": {
      "before": "...",
      "after": "..."
    },
    "next": "https://graph.instagram.com/..."
  }
}
```

#### 3.4.2 미디어 상세 조회
```
GET /{ig-media-id}
?fields=id,media_type,media_url,thumbnail_url,caption,timestamp,permalink,like_count,comments_count,children{id,media_type,media_url}
&access_token={access_token}
```

#### 3.4.3 이미지 게시 (2단계 프로세스)

**Step 1: Container 생성**
```
POST /{ig-user-id}/media
?image_url={public_image_url}
&caption={caption_text}
&access_token={access_token}

Response:
{
  "id": "17889000000000000"  // container_id
}
```

**Step 2: Container 상태 확인**
```
GET /{container-id}
?fields=status_code,status
&access_token={access_token}

Response:
{
  "status_code": "FINISHED",  // IN_PROGRESS, FINISHED, ERROR
  "id": "17889000000000000"
}
```

**Step 3: 게시**
```
POST /{ig-user-id}/media_publish
?creation_id={container_id}
&access_token={access_token}

Response:
{
  "id": "17880000000000001"  // 게시된 media_id
}
```

#### 3.4.4 비디오 게시 (3단계 프로세스)

**Step 1: Container 생성**
```
POST /{ig-user-id}/media
?media_type=REELS
&video_url={public_video_url}
&caption={caption_text}
&share_to_feed=true
&access_token={access_token}

Response:
{
  "id": "17889000000000000"
}
```

**Step 2 & 3**: 이미지와 동일 (상태 확인 → 게시)

### 3.5 인사이트 API

#### 3.5.1 계정 인사이트
```
GET /{ig-user-id}/insights
?metric=impressions,reach,profile_views,accounts_engaged
&period=day
&metric_type=total_value
&access_token={access_token}

Response:
{
  "data": [
    {
      "name": "impressions",
      "period": "day",
      "values": [{"value": 1000}],
      "title": "Impressions",
      "description": "Total number of times..."
    }
  ]
}
```

#### 3.5.2 미디어 인사이트
```
GET /{ig-media-id}/insights
?metric=impressions,reach,engagement,saved
&access_token={access_token}

Response:
{
  "data": [
    {
      "name": "impressions",
      "period": "lifetime",
      "values": [{"value": 500}],
      "title": "Impressions"
    }
  ]
}
```

### 3.6 댓글 API

#### 3.6.1 댓글 목록 조회
```
GET /{ig-media-id}/comments
?fields=id,text,username,timestamp,like_count,replies{id,text,username,timestamp}
&access_token={access_token}

Response:
{
  "data": [
    {
      "id": "17890000000000000",
      "text": "Great photo!",
      "username": "commenter",
      "timestamp": "2024-01-01T12:00:00+0000",
      "like_count": 5,
      "replies": {
        "data": [...]
      }
    }
  ]
}
```

#### 3.6.2 댓글 답글 작성
```
POST /{ig-comment-id}/replies
?message={reply_text}
&access_token={access_token}

Response:
{
  "id": "17890000000000001"
}
```

---

## 📦 4. 데이터 모델 (Pydantic v2)

### 4.1 인증 모델

```python
class TokenInfo(BaseModel):
    """토큰 정보"""
    access_token: str
    token_type: str = "bearer"
    expires_in: int  # 초 단위

class TokenDebugData(BaseModel):
    """토큰 디버그 정보"""
    app_id: str
    type: str
    application: str
    expires_at: int  # Unix timestamp
    is_valid: bool
    scopes: list[str]
    user_id: str

class TokenDebugResponse(BaseModel):
    """토큰 디버그 응답"""
    data: TokenDebugData
```

### 4.2 계정 모델

```python
class Account(BaseModel):
    """Instagram 비즈니스 계정"""
    id: str
    username: str
    name: Optional[str] = None
    account_type: str  # BUSINESS, CREATOR
    profile_picture_url: Optional[str] = None
    followers_count: int = 0
    follows_count: int = 0
    media_count: int = 0
    biography: Optional[str] = None
    website: Optional[str] = None
```

### 4.3 미디어 모델

```python
class MediaType(str, Enum):
    """미디어 타입"""
    IMAGE = "IMAGE"
    VIDEO = "VIDEO"
    CAROUSEL_ALBUM = "CAROUSEL_ALBUM"
    REELS = "REELS"

class Media(BaseModel):
    """미디어 정보"""
    id: str
    media_type: MediaType
    media_url: Optional[str] = None
    thumbnail_url: Optional[str] = None
    caption: Optional[str] = None
    timestamp: datetime
    permalink: str
    like_count: int = 0
    comments_count: int = 0
    children: Optional[list["Media"]] = None  # 캐러셀용

class MediaContainer(BaseModel):
    """미디어 컨테이너 (게시 전 상태)"""
    id: str
    status_code: Optional[str] = None  # IN_PROGRESS, FINISHED, ERROR
    status: Optional[str] = None

class MediaList(BaseModel):
    """미디어 목록 응답"""
    data: list[Media]
    paging: Optional[Paging] = None

class Paging(BaseModel):
    """페이징 정보"""
    cursors: Optional[dict[str, str]] = None
    next: Optional[str] = None
    previous: Optional[str] = None
```

### 4.4 인사이트 모델

```python
class InsightValue(BaseModel):
    """인사이트 값"""
    value: int
    end_time: Optional[datetime] = None

class Insight(BaseModel):
    """인사이트 정보"""
    name: str
    period: str  # day, week, days_28, lifetime
    values: list[InsightValue]
    title: str
    description: Optional[str] = None
    id: str

class InsightResponse(BaseModel):
    """인사이트 응답"""
    data: list[Insight]
```

### 4.5 댓글 모델

```python
class Comment(BaseModel):
    """댓글 정보"""
    id: str
    text: str
    username: str
    timestamp: datetime
    like_count: int = 0
    replies: Optional["CommentList"] = None

class CommentList(BaseModel):
    """댓글 목록 응답"""
    data: list[Comment]
    paging: Optional[Paging] = None
```

### 4.6 에러 모델

```python
class APIError(BaseModel):
    """Instagram API 에러 응답"""
    message: str
    type: str
    code: int
    error_subcode: Optional[int] = None
    fbtrace_id: Optional[str] = None

class ErrorResponse(BaseModel):
    """에러 응답 래퍼"""
    error: APIError
```

---

## 🚨 5. 예외 처리 전략

### 5.1 예외 계층 구조

```python
class InstagramAPIError(Exception):
    """Instagram API 기본 예외"""
    def __init__(self, message: str, code: int = None, subcode: int = None):
        self.message = message
        self.code = code
        self.subcode = subcode
        super().__init__(self.message)

class AuthenticationError(InstagramAPIError):
    """인증 관련 에러 (토큰 만료, 무효 등)"""
    # code: 190 (Invalid OAuth access token)
    pass

class RateLimitError(InstagramAPIError):
    """Rate Limit 초과 (HTTP 429)"""
    def __init__(self, message: str, retry_after: int = None):
        super().__init__(message, code=4)
        self.retry_after = retry_after

class PermissionError(InstagramAPIError):
    """권한 부족 에러"""
    # code: 10 (Permission denied)
    # code: 200 (Requires business account)
    pass

class MediaPublishError(InstagramAPIError):
    """미디어 게시 실패"""
    # 이미지 URL 접근 불가, 포맷 오류 등
    pass

class InvalidRequestError(InstagramAPIError):
    """잘못된 요청 (파라미터 오류 등)"""
    # code: 100 (Invalid parameter)
    pass

class ResourceNotFoundError(InstagramAPIError):
    """리소스를 찾을 수 없음"""
    # code: 803 (Object does not exist)
    pass
```

### 5.2 에러 코드 매핑

| API Error Code | Subcode | Exception Class | 설명 |
|----------------|---------|-----------------|------|
| 4 | - | RateLimitError | Rate limit 초과 |
| 10 | - | PermissionError | 권한 부족 |
| 100 | - | InvalidRequestError | 잘못된 파라미터 |
| 190 | 458 | AuthenticationError | 앱 권한 없음 |
| 190 | 463 | AuthenticationError | 토큰 만료 |
| 190 | 467 | AuthenticationError | 유효하지 않은 토큰 |
| 200 | - | PermissionError | 비즈니스 계정 필요 |
| 803 | - | ResourceNotFoundError | 리소스 없음 |

### 5.3 재시도 전략

```python
RETRY_CONFIG = {
    "max_retries": 3,
    "base_delay": 1.0,  # 초
    "max_delay": 60.0,  # 초
    "exponential_base": 2,
    "retryable_status_codes": [429, 500, 502, 503, 504],
    "retryable_error_codes": [4, 17, 341],  # Rate limit 관련
}
```

---

## 🔧 6. 클라이언트 인터페이스

### 6.1 InstagramGraphClient 클래스

```python
class InstagramGraphClient:
    """Instagram Graph API 클라이언트"""

    def __init__(
        self,
        access_token: str,
        app_id: Optional[str] = None,
        app_secret: Optional[str] = None,
        api_version: str = "v21.0",
        timeout: float = 30.0,
    ):
        """
        Args:
            access_token: Instagram 액세스 토큰
            app_id: Facebook 앱 ID (토큰 검증 시 필요)
            app_secret: Facebook 앱 시크릿 (토큰 교환 시 필요)
            api_version: Graph API 버전
            timeout: HTTP 요청 타임아웃 (초)
        """
        pass

    async def __aenter__(self) -> "InstagramGraphClient":
        """비동기 컨텍스트 매니저 진입"""
        pass

    async def __aexit__(self, *args) -> None:
        """비동기 컨텍스트 매니저 종료"""
        pass

    # ==================== 인증 ====================

    async def debug_token(self) -> TokenDebugResponse:
        """현재 토큰 정보 조회 (유효성 검증)"""
        pass

    async def exchange_long_lived_token(self) -> TokenInfo:
        """단기 토큰을 장기 토큰(60일)으로 교환"""
        pass

    async def refresh_token(self) -> TokenInfo:
        """장기 토큰 갱신"""
        pass

    # ==================== 계정 ====================

    async def get_account(self) -> Account:
        """현재 계정 정보 조회"""
        pass

    async def get_account_id(self) -> str:
        """현재 계정 ID만 조회"""
        pass

    # ==================== 미디어 ====================

    async def get_media_list(
        self,
        limit: int = 25,
        after: Optional[str] = None,
    ) -> MediaList:
        """미디어 목록 조회 (페이지네이션 지원)"""
        pass

    async def get_media(self, media_id: str) -> Media:
        """미디어 상세 조회"""
        pass

    async def publish_image(
        self,
        image_url: str,
        caption: Optional[str] = None,
    ) -> Media:
        """이미지 게시 (Container 생성 → 상태 확인 → 게시)"""
        pass

    async def publish_video(
        self,
        video_url: str,
        caption: Optional[str] = None,
        share_to_feed: bool = True,
    ) -> Media:
        """비디오/릴스 게시"""
        pass

    async def publish_carousel(
        self,
        media_urls: list[str],
        caption: Optional[str] = None,
    ) -> Media:
        """캐러셀(멀티 이미지) 게시"""
        pass

    # ==================== 인사이트 ====================

    async def get_account_insights(
        self,
        metrics: list[str],
        period: str = "day",
    ) -> InsightResponse:
        """계정 인사이트 조회

        Args:
            metrics: 조회할 메트릭 목록
                - impressions, reach, profile_views, accounts_engaged 등
            period: 기간 (day, week, days_28)
        """
        pass

    async def get_media_insights(
        self,
        media_id: str,
        metrics: Optional[list[str]] = None,
    ) -> InsightResponse:
        """미디어 인사이트 조회

        Args:
            media_id: 미디어 ID
            metrics: 조회할 메트릭 (기본: impressions, reach, engagement, saved)
        """
        pass

    # ==================== 댓글 ====================

    async def get_comments(
        self,
        media_id: str,
        limit: int = 50,
    ) -> CommentList:
        """미디어의 댓글 목록 조회"""
        pass

    async def reply_comment(
        self,
        comment_id: str,
        message: str,
    ) -> Comment:
        """댓글에 답글 작성"""
        pass

    # ==================== 내부 메서드 ====================

    async def _request(
        self,
        method: str,
        endpoint: str,
        params: Optional[dict] = None,
        data: Optional[dict] = None,
    ) -> dict:
        """
        공통 HTTP 요청 처리
        - Rate Limit 시 지수 백오프 재시도
        - 에러 응답 → 커스텀 예외 변환
        - 요청/응답 로깅
        """
        pass

    async def _wait_for_container(
        self,
        container_id: str,
        timeout: float = 60.0,
        poll_interval: float = 2.0,
    ) -> MediaContainer:
        """컨테이너 상태가 FINISHED가 될 때까지 대기"""
        pass
```

---

## 📁 7. 파일 구조

```
poc/instagram/
├── __init__.py              # 패키지 초기화 및 public API export
├── config.py                # Settings (환경변수 관리)
├── exceptions.py            # 커스텀 예외 클래스
├── models.py                # Pydantic v2 데이터 모델
├── client.py                # InstagramGraphClient
├── examples/
│   ├── __init__.py
│   ├── auth_example.py      # 토큰 검증, 교환 예제
│   ├── account_example.py   # 계정 정보 조회 예제
│   ├── media_example.py     # 미디어 조회/게시 예제
│   ├── insights_example.py  # 인사이트 조회 예제
│   └── comments_example.py  # 댓글 조회/답글 예제
├── DESIGN.md                # 설계 문서 (본 문서)
└── README.md                # 사용 가이드
```

### 7.1 각 파일의 역할

| 파일 | 역할 | 의존성 |
|------|------|--------|
| `config.py` | 환경변수 로드, API 설정 | pydantic-settings |
| `exceptions.py` | 커스텀 예외 정의 | - |
| `models.py` | API 요청/응답 Pydantic 모델 | pydantic |
| `client.py` | Instagram Graph API 클라이언트 | httpx, 위 모듈들 |
| `examples/*.py` | 실행 가능한 예제 코드 | client.py |

---

## 📋 8. 구현 순서

개발 에이전트가 따라야 할 순서:

### Phase 1: 기반 모듈 (의존성 없음)
1. `config.py` - Settings 클래스
2. `exceptions.py` - 예외 클래스 계층

### Phase 2: 데이터 모델
3. `models.py` - Pydantic 모델 (Token, Account, Media, Insight, Comment)

### Phase 3: 클라이언트 구현
4. `client.py` - InstagramGraphClient
   - 4.1: 기본 구조 및 `_request()` 메서드
   - 4.2: 인증 메서드 (debug_token, exchange_token, refresh_token)
   - 4.3: 계정 메서드 (get_account, get_account_id)
   - 4.4: 미디어 메서드 (get_media_list, get_media, publish_image, publish_video)
   - 4.5: 인사이트 메서드 (get_account_insights, get_media_insights)
   - 4.6: 댓글 메서드 (get_comments, reply_comment)

### Phase 4: 예제 및 문서
5. `examples/auth_example.py`
6. `examples/account_example.py`
7. `examples/media_example.py`
8. `examples/insights_example.py`
9. `examples/comments_example.py`
10. `README.md`

---

## ✅ 9. 설계 검수 결과

### 검수 체크리스트

- [x] **기존 프로젝트 패턴과 일관성** - 3계층 구조, Pydantic v2, 비동기 패턴 적용
- [x] **비동기 처리** - httpx.AsyncClient, async/await 전체 적용
- [x] **N+1 쿼리 문제** - 해당 없음 (외부 API 호출)
- [x] **트랜잭션 경계** - 해당 없음 (DB 미사용)
- [x] **예외 처리 전략** - 계층화된 예외, 에러 코드 매핑, 재시도 로직
- [x] **확장성** - 새 엔드포인트 추가 용이, 모델 확장 가능
- [x] **직관적 구조** - 명확한 모듈 분리, 일관된 네이밍
- [x] **SOLID 원칙** - 단일 책임, 개방-폐쇄 원칙 준수

### 참고 문서

- [Instagram Graph API 공식 가이드](https://elfsight.com/blog/instagram-graph-api-complete-developer-guide-for-2025/)
- [Instagram Platform API 구현 가이드](https://gist.github.com/PrenSJ2/0213e60e834e66b7e09f7f93999163fc)

---

## 🔄 다음 단계

설계가 완료되었습니다. `/develop` 명령으로 개발 에이전트를 호출하여 구현을 진행합니다.