# Instagram POC 개발 계획서

## 프로젝트 개요

Instagram Graph API를 사용하여 이미지, 영상, 컨텐츠를 업로드하고 결과를 확인하는 POC 모듈 개발

## 목표

- 단일 파일, 단일 클래스로 Instagram API 기능 구현
- 여러 사용자가 각자의 계정으로 컨텐츠 업로드 가능 (멀티테넌트)
- API 예외처리 및 에러 핸들링
- 테스트 파일 및 사용 매뉴얼 제공

## 참고 자료

1. **기존 코드**: `poc/instagram1/` 폴더
2. **공식 문서**: https://developers.facebook.com/docs/instagram-platform/instagram-api-with-instagram-login/content-publishing

## 기존 코드(instagram1) 분석 결과

### 발견된 문제점 (모두 수정 완료 ✅)

| 심각도 | 문제 | 설명 | 상태 |
|--------|------|------|------|
| 🔴 Critical | 잘못된 import 경로 | `poc.instagram` → `poc.instagram1`로 수정 | ✅ 완료 |
| 🔴 Critical | Timezone 혼합 | `datetime.now()` → `datetime.now(timezone.utc)`로 수정 | ✅ 완료 |
| 🟡 Warning | 파일 중간 import | `config.py`에서 `lru_cache` import를 파일 상단으로 이동 | ✅ 완료 |
| 🟡 Warning | Deprecated alias 사용 | `PermissionError` → `InstagramPermissionError`로 변경 | ✅ 완료 |
| 🟡 Warning | docstring 경로 오류 | `__init__.py` 예제 경로 수정 | ✅ 완료 |

### 수정된 파일

- `poc/instagram1/config.py` - import 위치 수정
- `poc/instagram1/__init__.py` - docstring 경로 수정
- `poc/instagram1/examples/auth_example.py` - timezone 및 import 경로 수정
- `poc/instagram1/examples/account_example.py` - import 경로 수정
- `poc/instagram1/examples/comments_example.py` - import 경로 수정
- `poc/instagram1/examples/insights_example.py` - import 경로 및 deprecated alias 수정
- `poc/instagram1/examples/media_example.py` - import 경로 수정

## 산출물

```
poc/instagram/
├── client.py      # InstagramClient 클래스 + 예외 클래스
├── main.py        # 테스트 실행 파일
└── poc.md         # 사용 매뉴얼
```

## 필수 기능

1. **이미지 업로드** - 단일 이미지 게시
2. **영상(릴스) 업로드** - 비디오 게시
3. **캐러셀 업로드** - 멀티 이미지 게시 (2-10개)
4. **미디어 조회** - 업로드된 게시물 확인
5. **예외처리** - API 에러 코드별 처리

## 설계 요구사항

### 클래스 구조

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

    - 인스턴스 생성 시 access_token 전달 (멀티테넌트 지원)
    - 비동기 컨텍스트 매니저 패턴
    """

    def __init__(self, access_token: str): ...

    async def publish_image(self, image_url: str, caption: str) -> Media: ...
    async def publish_video(self, video_url: str, caption: str) -> Media: ...
    async def publish_carousel(self, media_urls: list[str], caption: str) -> Media: ...
    async def get_media(self, media_id: str) -> Media: ...
    async def get_media_list(self, limit: int) -> list[Media]: ...
```

### 예외 클래스

```python
class InstagramAPIError(Exception): ...      # 기본 예외
class AuthenticationError(InstagramAPIError): ...  # 인증 오류
class RateLimitError(InstagramAPIError): ...       # Rate Limit 초과
class MediaPublishError(InstagramAPIError): ...    # 게시 실패
class InvalidRequestError(InstagramAPIError): ...  # 잘못된 요청
```

---

## 에이전트 워크플로우

### 1단계: 설계 에이전트 (`/design`)

```
/design

## 요청 개요
Instagram Graph API를 사용하여 이미지, 영상, 컨텐츠를 업로드하고 결과를 확인하는 POC 모듈 설계

## 참고 자료
1. Instagram Graph API 공식 문서: https://developers.facebook.com/docs/instagram-platform/instagram-api-with-instagram-login/content-publishing
2. 기존 코드: poc/instagram1/ 폴더 내용

## 요구사항
1. poc/instagram/ 폴더에 단일 파일, 단일 클래스로 구현
2. 여러 사용자가 각자의 계정으로 컨텐츠 업로드 가능하도록 설계 (멀티테넌트)
3. 필수 기능:
   - 이미지 업로드
   - 영상(릴스) 업로드
   - 캐러셀(멀티 이미지) 업로드
   - 업로드된 미디어 조회
4. Instagram API 에러 코드별 예외처리
5. main.py 테스트 파일 포함
6. poc.md 사용 매뉴얼 문서 포함

## 산출물
- 클래스 구조 및 메서드 시그니처
- 예외 클래스 설계
- 파일 구조
```

---

### 2단계: 개발 에이전트 (`/develop`)

```
/develop

## 작업 내용
1단계 설계를 기반으로 Instagram POC 모듈 구현

## 구현 대상
1. poc/instagram/client.py
   - InstagramClient 클래스 (단일 클래스로 모든 기능 포함)
   - 예외 클래스들 (같은 파일 내 정의)
   - 기능별 주석 필수

2. poc/instagram/main.py
   - 테스트 코드 (import하여 각 기능 테스트)
   - 환경변수 기반 토큰 설정

3. poc/instagram/poc.md
   - 동작 원리 설명
   - 환경 설정 방법
   - 사용 예제 코드
   - API 제한사항

## 참고
- poc/instagram1/ 폴더의 기존 코드 참고
- Instagram Graph API 공식 문서 기반으로 구현
- 잘못된 import 경로, timezone 문제 등 기존 코드의 버그 수정 반영
```

---

### 3단계: 코드리뷰 에이전트 (`/review`)

```
/review

## 리뷰 대상
poc/instagram/ 폴더의 모든 파일

## 리뷰 항목
1. 코드 품질
   - PEP 8 준수 여부
   - 타입 힌트 적용
   - 비동기 패턴 적절성

2. 기능 완성도
   - 이미지/영상/캐러셀 업로드 기능
   - 미디어 조회 기능
   - 멀티테넌트 지원

3. 예외처리
   - API 에러 코드별 처리
   - Rate Limit 처리
   - 타임아웃 처리

4. 문서화
   - 주석의 적절성
   - poc.md 완성도

5. 보안
   - 토큰 노출 방지
   - 민감 정보 로깅 마스킹

## instagram1 대비 개선점 확인
- import 경로 오류 수정됨
- timezone aware/naive 혼합 문제 수정됨
- deprecated alias 제거됨
```

---

## 실행 순서

```bash
# 1. 설계 단계
/design

# 2. 개발 단계 (설계 승인 후)
/develop

# 3. 코드 리뷰 단계 (개발 완료 후)
/review
```

---

## 환경 설정

### 필수 환경변수

```bash
export INSTAGRAM_ACCESS_TOKEN="your_access_token"
export INSTAGRAM_APP_ID="your_app_id"           # 선택
export INSTAGRAM_APP_SECRET="your_app_secret"   # 선택
```

### 의존성

```bash
uv add httpx pydantic pydantic-settings
```

---

## 일정

| 단계 | 작업 | 상태 |
|------|------|------|
| 1 | 설계 (`/design`) | ✅ 완료 |
| 2 | 개발 (`/develop`) | ✅ 완료 |
| 3 | 코드리뷰 (`/review`) | ⬜ 대기 |
| 4 | 테스트 및 검증 | ⬜ 대기 |