336 lines
8.1 KiB
Markdown
336 lines
8.1 KiB
Markdown
# Instagram Graph API POC 개발 계획
|
|
|
|
## 프로젝트 개요
|
|
- **목적**: Instagram Graph API (비즈니스 계정) 활용 POC 구현
|
|
- **위치**: `poc/instagram/`
|
|
- **기술 스택**: Python 3.13, 비동기(async/await), httpx, Pydantic v2
|
|
|
|
---
|
|
|
|
## 실행 파이프라인
|
|
|
|
| 단계 | 에이전트 | 목적 | 산출물 |
|
|
|------|----------|------|--------|
|
|
| 1 | `/design` | 초기 설계 | DESIGN.md |
|
|
| 2 | `/develop` | 초기 개발 | 소스 코드 |
|
|
| 3 | `/review` | 초기 리뷰 | REVIEW_V1.md |
|
|
| 4 | `/design` | 리팩토링 설계 | DESIGN.md 갱신 |
|
|
| 5 | `/develop` | 리팩토링 개발 | 개선된 코드 |
|
|
| 6 | `/review` | 최종 리뷰 | REVIEW_FINAL.md |
|
|
|
|
---
|
|
|
|
## 1단계: `/design` (초기 설계)
|
|
|
|
```
|
|
## 프로젝트 개요
|
|
Instagram Graph API (비즈니스 계정) POC 초기 설계
|
|
|
|
## 배경
|
|
- 위치: poc/instagram/
|
|
- 기술: Python 3.13, 비동기(async/await), httpx, Pydantic v2
|
|
- 참고: https://developers.facebook.com/docs/instagram-api
|
|
|
|
## 설계 요구사항
|
|
|
|
### 1. 아키텍처 설계
|
|
- 모듈 구조 및 의존성 관계
|
|
- 클래스 다이어그램 (Client, Models, Exceptions)
|
|
|
|
### 2. API 엔드포인트 분석
|
|
공식 문서 기반으로 다음 기능의 엔드포인트, 파라미터, 응답 구조 정리:
|
|
- 인증: Token 교환, 검증
|
|
- 계정: 비즈니스 계정 ID 조회, 프로필 조회
|
|
- 미디어: 목록/상세 조회, 이미지/비디오 게시 (Container → Publish)
|
|
- 인사이트: 계정/미디어 인사이트
|
|
- 댓글: 조회, 답글 작성
|
|
|
|
### 3. 데이터 모델 설계
|
|
- Pydantic 스키마 정의 (Account, Media, Insight, Comment 등)
|
|
- API 응답 매핑 구조
|
|
|
|
### 4. 예외 처리 전략
|
|
- Rate Limit (429)
|
|
- 인증 만료/무효
|
|
- 권한 부족
|
|
- API 에러 코드별 처리
|
|
|
|
### 5. 파일 구조
|
|
poc/instagram/
|
|
├── __init__.py
|
|
├── config.py
|
|
├── client.py
|
|
├── models.py
|
|
├── exceptions.py
|
|
├── examples/
|
|
└── README.md
|
|
|
|
## 산출물
|
|
- 설계 문서 (poc/instagram/DESIGN.md)
|
|
- 각 모듈별 인터페이스 명세
|
|
```
|
|
|
|
---
|
|
|
|
## 2단계: `/develop` (초기 개발)
|
|
|
|
```
|
|
## 작업 개요
|
|
poc/instagram/ 폴더에 Instagram Graph API POC 코드 초기 구현
|
|
|
|
## 참고
|
|
- 설계 문서: poc/instagram/DESIGN.md
|
|
- 공식 문서: https://developers.facebook.com/docs/instagram-api
|
|
|
|
## 구현 요구사항
|
|
|
|
### config.py
|
|
- pydantic-settings 기반 Settings 클래스
|
|
- 환경변수: INSTAGRAM_APP_ID, INSTAGRAM_APP_SECRET, INSTAGRAM_ACCESS_TOKEN
|
|
- API 버전, Base URL 설정
|
|
|
|
### exceptions.py
|
|
- InstagramAPIError (기본 예외)
|
|
- RateLimitError (429)
|
|
- AuthenticationError (인증 실패)
|
|
- PermissionError (권한 부족)
|
|
- MediaPublishError (게시 실패)
|
|
|
|
### models.py (Pydantic v2)
|
|
- TokenInfo, Account, Media, MediaInsight, Comment
|
|
|
|
### client.py
|
|
- InstagramGraphClient 클래스 (httpx.AsyncClient)
|
|
- 인증, 계정, 미디어, 인사이트, 댓글 관련 메서드
|
|
- 요청/응답 로깅, 재시도 로직
|
|
|
|
### examples/
|
|
- 각 기능별 실행 가능한 예제
|
|
|
|
### README.md
|
|
- 설치, 설정, 실행 가이드
|
|
|
|
## 코드 품질
|
|
- 타입 힌트, docstring, 로깅 필수
|
|
```
|
|
|
|
---
|
|
|
|
## 3단계: `/review` (초기 리뷰)
|
|
|
|
```
|
|
## 리뷰 대상
|
|
poc/instagram/ 폴더의 Instagram Graph API POC 초기 구현 코드
|
|
|
|
## 리뷰 항목
|
|
|
|
### 1. 코드 품질
|
|
- 타입 힌트 완전성
|
|
- 네이밍 컨벤션 (PEP8)
|
|
- 코드 중복 여부
|
|
|
|
### 2. 아키텍처
|
|
- 모듈 간 의존성 적절성
|
|
- 단일 책임 원칙 준수
|
|
- 확장 가능성
|
|
|
|
### 3. 에러 처리
|
|
- 예외 처리 누락 여부
|
|
- Rate Limit 처리 적절성
|
|
|
|
### 4. 보안
|
|
- Credentials 노출 위험
|
|
- 민감 정보 로깅 여부
|
|
|
|
### 5. 비동기 처리
|
|
- async/await 올바른 사용
|
|
- 리소스 정리
|
|
|
|
### 6. 문서화
|
|
- README 완성도
|
|
- 예제 코드 실행 가능성
|
|
|
|
## 산출물
|
|
- 리뷰 결과 (poc/instagram/REVIEW_V1.md)
|
|
- 심각도별 분류 (Critical, Major, Minor)
|
|
- 개선 사항 목록
|
|
```
|
|
|
|
---
|
|
|
|
## 4단계: `/design` (리팩토링 설계)
|
|
|
|
```
|
|
## 프로젝트 개요
|
|
Instagram Graph API POC 리팩토링 설계
|
|
|
|
## 배경
|
|
- 초기 리뷰 결과: poc/instagram/REVIEW_V1.md
|
|
- 기존 설계: poc/instagram/DESIGN.md
|
|
- 기존 코드: poc/instagram/
|
|
|
|
## 리팩토링 설계 요구사항
|
|
|
|
### 1. 리뷰 피드백 반영
|
|
- REVIEW_V1.md의 Critical/Major 이슈 해결 방안
|
|
- 아키텍처 개선점 반영
|
|
|
|
### 2. 개선된 아키텍처
|
|
- 기존 구조의 문제점 분석
|
|
- 개선된 모듈 구조 제안
|
|
- 의존성 최적화
|
|
|
|
### 3. 코드 품질 향상 전략
|
|
- 중복 코드 제거 방안
|
|
- 에러 처리 강화 방안
|
|
- 테스트 용이성 개선
|
|
|
|
### 4. 추가 기능 (필요시)
|
|
- 누락된 API 기능
|
|
- 유틸리티 함수
|
|
|
|
## 산출물
|
|
- 업데이트된 설계 문서 (poc/instagram/DESIGN.md 갱신)
|
|
- 리팩토링 변경 사항 요약
|
|
```
|
|
|
|
---
|
|
|
|
## 5단계: `/develop` (리팩토링 개발)
|
|
|
|
```
|
|
## 작업 개요
|
|
poc/instagram/ 코드 리팩토링 및 개선 구현
|
|
|
|
## 참고
|
|
- 업데이트된 설계: poc/instagram/DESIGN.md
|
|
- 초기 리뷰 결과: poc/instagram/REVIEW_V1.md
|
|
- 기존 코드: poc/instagram/
|
|
|
|
## 리팩토링 요구사항
|
|
|
|
### 1. Critical/Major 이슈 수정
|
|
- 리뷰에서 지적된 심각한 문제 해결
|
|
- 보안 취약점 수정
|
|
|
|
### 2. 코드 품질 개선
|
|
- 중복 코드 제거
|
|
- 네이밍 개선
|
|
- 타입 힌트 보완
|
|
|
|
### 3. 에러 처리 강화
|
|
- 누락된 예외 처리 추가
|
|
- 에러 메시지 개선
|
|
- 재시도 로직 보완
|
|
|
|
### 4. 비동기 처리 최적화
|
|
- 리소스 관리 개선
|
|
- Context manager 적용
|
|
|
|
### 5. 문서화 보완
|
|
- README 업데이트
|
|
- docstring 보완
|
|
- 예제 코드 개선
|
|
|
|
## 코드 품질
|
|
- 모든 리뷰 피드백 반영
|
|
- 프로덕션 수준의 코드 품질
|
|
```
|
|
|
|
---
|
|
|
|
## 6단계: `/review` (최종 리뷰)
|
|
|
|
```
|
|
## 리뷰 대상
|
|
poc/instagram/ 폴더의 리팩토링된 최종 코드
|
|
|
|
## 리뷰 목적
|
|
- 초기 리뷰(REVIEW_V1.md) 피드백 반영 확인
|
|
- 최종 코드 품질 검증
|
|
- 프로덕션 배포 가능 여부 판단
|
|
|
|
## 리뷰 항목
|
|
|
|
### 1. 이전 리뷰 피드백 반영 확인
|
|
- REVIEW_V1.md의 Critical 이슈 해결 여부
|
|
- REVIEW_V1.md의 Major 이슈 해결 여부
|
|
- 개선 사항 적용 여부
|
|
|
|
### 2. 코드 품질 최종 검증
|
|
- 타입 힌트 완전성
|
|
- 코드 가독성
|
|
- 테스트 용이성
|
|
|
|
### 3. 아키텍처 최종 검증
|
|
- 모듈 구조 적절성
|
|
- 확장 가능성
|
|
- 유지보수성
|
|
|
|
### 4. 보안 최종 검증
|
|
- Credentials 관리
|
|
- 입력값 검증
|
|
- 로깅 보안
|
|
|
|
### 5. 문서화 최종 검증
|
|
- README 완성도
|
|
- 예제 실행 가능성
|
|
- API 문서화 수준
|
|
|
|
## 산출물
|
|
- 최종 리뷰 결과 (poc/instagram/REVIEW_FINAL.md)
|
|
- 잔여 이슈 목록 (있다면)
|
|
- 최종 승인 여부
|
|
- 향후 개선 제안 (Optional)
|
|
```
|
|
|
|
---
|
|
|
|
## 구현 기능 상세
|
|
|
|
### 1. 인증 (Authentication)
|
|
- Facebook App 기반 Access Token 관리
|
|
- Long-lived Token 교환
|
|
- Token 유효성 검증
|
|
|
|
### 2. 계정 정보 (Account)
|
|
- 비즈니스 계정 ID 조회
|
|
- 프로필 정보 조회 (username, followers_count, media_count 등)
|
|
|
|
### 3. 미디어 관리 (Media)
|
|
- 미디어 목록 조회 (피드)
|
|
- 단일 미디어 상세 조회
|
|
- 이미지/비디오 게시 (Container 생성 → 게시)
|
|
|
|
### 4. 인사이트 (Insights)
|
|
- 계정 인사이트 조회 (reach, impressions 등)
|
|
- 미디어별 인사이트 조회
|
|
|
|
### 5. 댓글 관리 (Comments)
|
|
- 댓글 목록 조회
|
|
- 댓글 답글 작성
|
|
|
|
---
|
|
|
|
## 최종 파일 구조
|
|
|
|
```
|
|
poc/instagram/
|
|
├── __init__.py
|
|
├── config.py # Settings, 환경변수
|
|
├── client.py # InstagramGraphClient
|
|
├── models.py # Pydantic 모델
|
|
├── exceptions.py # 커스텀 예외
|
|
├── examples/
|
|
│ ├── __init__.py
|
|
│ ├── auth_example.py
|
|
│ ├── account_example.py
|
|
│ ├── media_example.py
|
|
│ ├── insights_example.py
|
|
│ └── comments_example.py
|
|
├── DESIGN.md # 설계 문서
|
|
├── REVIEW_V1.md # 초기 리뷰 결과
|
|
├── REVIEW_FINAL.md # 최종 리뷰 결과
|
|
└── README.md # 사용 가이드
|
|
```
|