castad
/
o2o-castad-backend
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
o2o-castad-backend/docs/plan/instagram-plan.md

6.5 KiB
Raw Blame History

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 에러 코드별 처리

설계 요구사항

클래스 구조

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]: ...

예외 클래스

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 제거됨

실행 순서

# 1. 설계 단계
/design

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

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

환경 설정

필수 환경변수

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

의존성

uv add httpx pydantic pydantic-settings

일정

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