# 네이버 검색광고 API 연동 — SA 성과 자동 수집 + 대시보드 표시

## 한정승인

## 작업 목표
네이버 검색광고 API로 SA 성과 데이터를 자동 수집하고, 대시보드 캠페인뷰 네이버SA현황 섹션에 실시간 표시한다.

## API 인증 정보
- `.env.keys`에 이미 등록됨:
  - `NAVER_SEARCHAD_CUSTOMER_ID`
  - `NAVER_SEARCHAD_API_KEY`
  - `NAVER_SEARCHAD_SECRET_KEY`
- API 문서: https://naver.github.io/searchad-apidoc/

## 구현 내용

### 1. API 클라이언트 모듈
- 위치: `/home/jay/workspace/tools/naver-ads/sa_api_client.py`
- 네이버 검색광고 API 인증 (HMAC-SHA256 서명)
- 주요 API 호출:
  - `GET /ncc/campaigns`: 캠페인 목록
  - `GET /ncc/adgroups`: 광고그룹 목록
  - `GET /ncc/keywords`: 키워드 목록 + 상태
  - `GET /stats`: 성과 데이터 (노출/클릭/비용/전환)
- 에러 핸들링 + 재시도 (rate limit 대응)

### 2. 성과 데이터 수집 스크립트
- 위치: `/home/jay/workspace/tools/naver-ads/collect_sa_stats.py`
- 일별 성과 수집: 노출수, 클릭수, CTR, CPC, 비용, 전환수
- 키워드별 성과 수집
- 결과 저장: `/home/jay/workspace/dashboard/data/naver-sa-stats.json`
- CLI: `python3 collect_sa_stats.py [--date 2026-04-11] [--days 7]`

### 3. 대시보드 API 엔드포인트
- `GET /api/naver-ads/sa-stats`: 최신 SA 성과 데이터 반환
- `GET /api/naver-ads/sa-stats?days=7`: N일 트렌드 데이터
- server.py에 엔드포인트 추가

### 4. NaverSASection.js 업데이트
- 기존 정적 데이터 → API 기반 실시간 데이터로 전환
- 표시 항목:
  - 오늘/어제 성과 요약 (노출/클릭/비용/CTR/CPC)
  - 키워드 그룹별(F/G/H) 성과 분리
  - 7일 트렌드 차트 (간단한 바 차트)
  - 예산 소진율 (일 예산 대비 소비 비율)
  - 예산 소진율 80% 이상 시 경고
- 다크모드 호환

### 5. 자동 수집 스케줄
- cron으로 매일 새벽 2시 자동 수집 등록 (cokacdir --cron)
- 또는 대시보드 접속 시 마지막 수집 후 1시간 경과 시 자동 갱신

## 참조 파일
- .env.keys: `/home/jay/workspace/.env.keys` (NAVER_SEARCHAD_* 키)
- NaverSASection.js: `/home/jay/workspace/dashboard/components/campaign/NaverSASection.js`
- server.py: `/home/jay/workspace/dashboard/server.py`
- 네이버 API 문서: https://naver.github.io/searchad-apidoc/

## 테스트
1. API 인증 성공 확인 (캠페인 목록 조회)
2. 성과 데이터 수집 → JSON 저장 확인
3. 대시보드 NaverSA 섹션에 실시간 데이터 표시 확인
4. 광고 미운영 시 빈 데이터 graceful 처리
5. API rate limit 초과 시 재시도 동작

## 보고서
`/home/jay/workspace/memory/reports/task-{TASK_ID}.md`