# Meta Ads API 연동 모듈 구축

## 작업 개요
Meta Marketing API를 통해 광고 캠페인을 프로그래밍 방식으로 관리하는 모듈을 구축한다.

## API 인증 정보
`.env.keys`에 저장 완료 (환경변수로 로드):
- `META_APP_ID` — 앱 ID
- `META_APP_SECRET` — 앱 시크릿
- `META_ACCESS_TOKEN` — 액세스 토큰 (단기, 1~2시간 만료)
- `META_AD_ACCOUNT_ID` — 광고 계정 ID (act_ 형태)

⚠️ 키/토큰 값을 코드나 로그에 직접 노출 금지. 반드시 os.environ에서 로드.

## 핵심 구현 사항

### 1. 의존성 설치
```bash
pip install facebook-business
```

### 2. Meta Ads 클라이언트 모듈
- 경로: `/home/jay/workspace/utils/meta_ads_client.py`
- 클래스: `MetaAdsClient`
- 초기화: .env.keys에서 환경변수 로드 → FacebookAdsApi.init()
- 기능:
  - **토큰 관리**: 단기 토큰 → 장기 토큰 자동 교환 (`/oauth/access_token` 엔드포인트)
  - **캠페인 CRUD**: 생성, 조회, 수정, 삭제
  - **광고세트 CRUD**: 타겟팅, 예산, 일정 관리
  - **크리에이티브 관리**: 이미지 업로드, 광고 소재 생성
  - **인사이트 조회**: 캠페인/광고세트/광고별 성과 데이터 조회
  - **계정 정보 조회**: 광고 계정 상태, 잔액, 스펜딩 한도

### 3. 장기 토큰 교환 모듈
- 현재 토큰은 단기 (1~2시간 만료)
- 장기 토큰 교환 API 호출: `GET /oauth/access_token?grant_type=fb_exchange_token&...`
- 장기 토큰(60일)으로 교환 후 .env.keys 업데이트 함수 제공
- 토큰 만료 시점 추적 + 경고 기능

### 4. CLI 인터페이스
- 경로: `/home/jay/workspace/scripts/meta_ads_cli.py`
- 사용법:
  - `python3 meta_ads_cli.py status` — 계정 상태, 토큰 유효성 확인
  - `python3 meta_ads_cli.py campaigns list` — 캠페인 목록 조회
  - `python3 meta_ads_cli.py campaigns create --name "..." --budget 10000` — 캠페인 생성
  - `python3 meta_ads_cli.py upload-image <파일경로>` — 이미지 업로드
  - `python3 meta_ads_cli.py insights --campaign-id <id> --days 7` — 인사이트 조회
  - `python3 meta_ads_cli.py token refresh` — 장기 토큰 교환

### 5. 배너 업로드 자동화 연동
- v-round2 배너 PNG를 Meta에 직접 업로드하는 유틸리티
- 경로: `/home/jay/workspace/output/banners/versions/` 내 PNG 파일 → Meta 크리에이티브 라이브러리

## 참고 자료
- 공식 SDK: https://github.com/facebook/facebook-python-business-sdk
- 공식 문서: https://developers.facebook.com/docs/marketing-api
- API 버전: v25.0 (현재 최신)

## 테스트
- 토큰 유효성 검증 테스트
- 계정 정보 조회 테스트
- 캠페인 생성/조회 테스트 (소액 테스트 캠페인, 즉시 일시중지)
- 이미지 업로드 테스트

## 완료 기준
- meta_ads_client.py 동작 (CRUD + 인사이트)
- 장기 토큰 교환 동작
- CLI 기본 명령어 동작
- 테스트 PASS
- 문서 (사용법 가이드)