# InfoKeyword 발표형 스크린샷 리포트 시스템 — 설계 문서

## 1. 개요
키워드 분석 시 각 판단 step에서 결정적 근거가 되는 화면을 스크린샷으로 캡처하고,
이를 발표형 HTML 리포트로 자동 생성하여 Google Drive에 업로드하는 시스템.

## 2. 캡처 대상 정의

- **Step 1**: SKIP (단순 단어 수 체크, 스크린샷 불필요)
- **Step 2**: 네이버 연관검색어 결과 화면
  - URL: `https://search.naver.com/search.naver?query={keyword}`
  - 캡처 대상: 연관검색어 영역 (셀렉터: `#nx_related_keywords` 또는 전체 페이지)
- **Step 3**: 네이버 자동완성 결과 화면
  - URL: `https://ac.search.naver.com/nx/ac?q={keyword}&con=1&frm=nv&ans=2`
  - 캡처 방식: 자동완성 드롭다운은 API 결과이므로 데이터 카드로 대체
- **Step 4**: 네이버 검색광고 API 결과 (수치 데이터 → 데이터 카드)
  - 스크린샷 대신 HTML 데이터 카드 렌더링
- **Step 5**: 분석 대상 블로그 TOP10 목록 + 홍보성 판정된 블로그 본문 스크린샷
  - URL: `https://search.naver.com/search.naver?ssc=tab.blog&query={keyword}`
  - 추가: 홍보성 판정 블로그의 개별 URL 스크린샷
- **Step 6**: 블로그 검색 결과에서 외부 블로그 하이라이트
  - Step 5 스크린샷 재사용 + 외부 블로그 표시
- **Step 7**: 카페 검색 결과 화면
  - URL: `https://search.naver.com/search.naver?ssc=tab.cafe&query={keyword}`

## 3. 아키텍처

```
Worker (Python)
├── pipeline/analyzer.py        ← 기존 (수정: 스크린샷 콜백 추가)
└── reporter/                   ← 신규 모듈
    ├── __init__.py
    ├── screenshot.py            ← Playwright 스크린샷 캡처
    ├── drive_uploader.py        ← Google Drive 업로드
    └── report_generator.py      ← HTML 리포트 생성

Frontend (Next.js)
├── app/report/[id]/evidence/page.tsx  ← 근거 리포트 뷰어
└── components/evidence-report.tsx     ← 리포트 표시 컴포넌트
```

## 4. Google Drive 폴더 구조

```
InfoKeyword-Reports/               ← 루트 폴더 (서비스 계정 소유)
└── {analysis_id}/                 ← 분석별 폴더
    ├── screenshots/
    │   ├── step2_related.png
    │   ├── step3_autocomplete.png  (선택)
    │   ├── step5_blog_search.png
    │   ├── step5_blog_{n}.png     (홍보성 블로그별)
    │   ├── step7_cafe.png
    │   └── ...
    └── report.html                ← 발표형 HTML 리포트
```

## 5. 데이터 흐름

1. `analyze_keyword()` 실행 시 각 step에서 스크린샷 캡처
2. 캡처된 이미지를 로컬 임시 폴더에 저장
3. 분석 완료 후 `report_generator.py`가 HTML 리포트 생성
4. `drive_uploader.py`가 이미지 + HTML을 Google Drive에 업로드
5. 업로드된 리포트 URL을 분석 결과에 `report_url` 필드로 추가
6. Firestore에 `report_url` 저장
7. 프론트엔드에서 `report_url`로 리포트 조회

## 6. Graceful Degradation
- 스크린샷 실패 시 분석 자체는 정상 진행
- Drive 업로드 실패 시 로컬 HTML을 Worker API로 서빙
- 모든 스크린샷 관련 오류는 로그만 남기고 분석 결과에 영향 없음

## 7. 자동 정리
- 매일 cron으로 7일 경과 폴더 삭제
- Drive API `files().list()` + `createdTime` 기준 필터링
- Firestore `report_url` 필드는 프론트에서 "만료됨" 처리

## 8. 보안
- 서비스 계정 키: `/home/jay/.config/gcloud/service-accounts/infokeyword-j2h-drive.json`
- Drive 폴더 공유: "링크를 아는 모든 사용자" → 읽기 전용
- 서비스 계정 이메일: `firebase-adminsdk-fbsvc@infokeyword-j2h.iam.gserviceaccount.com`