239 lines
6.5 KiB
Markdown
239 lines
6.5 KiB
Markdown
# 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 | 테스트 및 검증 | ⬜ 대기 |
|