# task-926.1 — InfoKeyword 근거 리포트 캡처 불일치 개선 (3Phase 전체)

**팀**: dev2-team (오딘)
**일시**: 2026-03-24
**작업자**: 토르(백엔드 구현), 헤임달(테스트)

---

## SCQA

**S**: InfoKeyword 근거 리포트의 스크린샷과 크롤링 데이터 간 5가지 불일치 원인이 task-925.1에서 규명되었으며, 3단계 개선이 필요한 상태다.

**C**: URL 파라미터 불일치, 불충분한 로딩 대기, 광고 필터링 비대칭, 병렬 실행 시간차, 별도 HTTP 클라이언트 사용으로 인해 스크린샷과 분석 데이터가 일치하지 않는다.

**Q**: 3 Phase 개선을 통해 스크린샷과 크롤링 데이터의 구조적 일치를 달성할 수 있는가?

**A**: Phase 1~3 전체 구현 완료. URL 통일, 셀렉터 기반 대기, 광고 숨김, 순차 실행, Playwright 통합 크롤링을 적용. pytest 28건 전체 통과, pyright 에러 0건, black/isort 준수.

---

## 구현 내역

### Phase 1: 즉시 적용

**1-1. 스크린샷 URL 통일** (`screenshot.py`)
- `_NAVER_TAB_URLS["blog"]`를 `blog_search.py`의 `_BLOG_SEARCH_URL`을 직접 import하여 참조
- 변경 전: `where=blog` 파라미터만 사용
- 변경 후: `ssc=tab.blog.all&sm=tab_jum` — 크롤링과 동일한 파라미터

**1-2. 페이지 로딩 대기 개선** (`screenshot.py`)
- `_take_screenshot_of_url`에 `wait_selector`, `pre_screenshot_js` 파라미터 추가
- 블로그 탭: `[data-template-id="ugcItem"]` 셀렉터 대기 (5초 timeout) + 500ms 여유
- 셀렉터 대기 실패 시 graceful fallback (로그만 남기고 계속 진행)
- 고정 2초 대기 → 셀렉터 기반 대기 + 500ms로 개선

### Phase 2: 단기 적용

**2-1. 광고 영역 CSS 숨김** (`screenshot.py`)
- 블로그 탭 캡처 시 `pre_screenshot_js`로 광고 요소 숨김
- 대상: `[data-heatmap-target*="adtag"]`, `[data-power-content-url]` → 부모 `ugcItem`까지 `display:none`
- `blog_search.py`의 `_is_ad()` 함수와 동일한 광고 판별 기준 사용

**2-2. 크롤링 완료 후 스크린샷 순차 실행** (`analyzer.py`)
- `asyncio.gather(step5, screenshot)` → `step5 = await ...` + `_ss_blog = await ...` 순차 실행
- 다른 step 간 병렬 (step2-4 gather, step7 gather)은 유지

### Phase 3: 구조 통합

**3-1. Playwright 기반 블로그 검색 크롤링+스크린샷 통합** (`blog_search.py`, `analyzer.py`)
- `search_blogs_with_playwright(keyword, top_n, screenshot_path)` 함수 신규 추가
- 동일 Playwright 세션에서: 페이지 로드 → DOM 파싱(기존 `_is_ad()`, `_parse_blog_item()` 재활용) → 광고 숨김 → 스크린샷
- 기존 `search_blogs()` (httpx) → fallback으로 유지 (Playwright 실패 시 자동 전환)
- `analyzer.py`에서 `search_blogs_with_playwright` 호출로 변경, 별도 블로그 스크린샷 호출 제거

---

## 생성/수정 파일 목록

| 파일 | 작업 | 변경 요약 |
|------|------|-----------|
| `worker/reporter/screenshot.py` | 수정 | URL 통일, wait_selector/pre_screenshot_js 파라미터, 광고 숨김 |
| `worker/crawler/blog_search.py` | 수정 | `search_blogs_with_playwright()` 함수 추가 (+109줄) |
| `worker/pipeline/analyzer.py` | 수정 | Playwright 통합 함수 호출, 순차 실행 (+24줄, -15줄) |
| `tests/test_screenshot.py` | 신규 | 28개 테스트 (Phase 1-3 전체 커버) |
| `pyrightconfig.json` | 신규 | pyright 설정 (worker 패키지 경로) |
| `setup.cfg` | 신규 | isort profile=black 설정 |

---

## 검증 기준 충족

| 검증 기준 | 충족 | 근거 |
|-----------|------|------|
| 스크린샷 URL과 크롤링 URL 일치 | O | `_BLOG_SEARCH_URL` 직접 import, 테스트 3건 통과 |
| 스크린샷에 광고 미표시 | O | `_BLOG_AD_HIDE_JS` inject, 테스트 3건 통과 |
| 페이지 미로딩 방지 | O | `wait_for_selector` 적용, graceful fallback 테스트 통과 |
| 기존 7단계 판정 로직 영향 없음 | O | threshold/판정 기준 미변경, 기존 테스트 19건 통과 |
| httpx fallback 유지 | O | `search_blogs()` 미삭제, fallback 테스트 통과 |
| pytest 전체 통과 | O | 28 passed in 3.16s |
| pyright 에러 0건 | O | 0 errors, 0 warnings, 0 informations |
| black/isort 준수 | O | 3 files would be left unchanged |

---

## 셀프 QC 체크리스트

- [x] 1. 영향 파일: screenshot.py, blog_search.py, analyzer.py — 모두 수정 완료
- [x] 2. 엣지 케이스: wait_selector timeout → graceful fallback, Playwright 실패 → httpx fallback, 광고 0건 → JS 무해
- [x] 3. 작업 지시 일치: Phase 1~3 전체 구현 완료 (URL 통일, 로딩 대기, 광고 숨김, 시점 조정, Playwright 통합)
- [x] 4. 보안: Playwright 브라우저 --no-sandbox는 서버 환경 기존 관례 유지
- [x] 5. 테스트: 28건 전체 커버 (URL 일치 4건, wait_selector 5건, 광고 숨김 3건, 순차 실행 1건, Phase 3 6건 + 기존 19건 regression 없음)
- [x] 6. 이슈: 3건 발견, 모두 자체 해결

---

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **isort/black 충돌** — `setup.cfg`에 `profile = black` 추가하여 해결
2. **pyright 경로 인식 불가** — `pyrightconfig.json` 생성하여 worker 패키지 경로 설정
3. **cafe 탭 테스트 mock 설정 오류** — `mock_context.new_page` 반환값을 올바른 mock_page로 수정

### 범위 외 미해결 (0건)

---

## 머지 판단

- **머지 필요**: Yes
- **브랜치**: task/task-926.1-dev2
- **워크트리 경로**: /home/jay/projects/InfoKeyword/.worktrees/task-926.1-dev2
- **머지 의견**: pytest 28건 전체 통과, pyright 0 에러, black/isort 준수. 기존 미커밋 변경(src/app, src/types — 다른 작업 산출물)과 충돌 없음. 7단계 판정 로직 미변경으로 기존 분석 결과 보존.

---

## QC 자동 검증

(아래 실행 예정)