o2o-castad-backend/insta_poc_plan.md

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          # 사용 가이드