# 댓글 카드(Comment Cards) 기능 설계

작성일: 2026-06-29

## 1. 목적

유튜브 영상 링크를 입력하면 해당 영상의 댓글을 가져와, 댓글마다 **유튜브 댓글 UI를 그대로 재현한 카드**로 보여준다. 사용자가 카드의 프로필 사진과 아이디를 **모자이크(블러)** 처리한 뒤, 각 카드를 **PNG 이미지로 클립보드에 복사**해 영상 편집툴(캡컷 등)에 바로 붙여넣어 영상 하단 소스로 쓰는 것이 목표다.

콘텐츠 제작용 보조 도구이며, DB 저장 없이 일회성 조회/생성으로 동작하는 독립 페이지다.

## 2. 사용 흐름

1. 사이드바 "제작" 그룹의 **댓글 카드** 메뉴 진입 (`/comment-cards`)
2. 유튜브 링크(또는 영상 ID) 입력 → **[가져오기]**
3. 서버가 YouTube Data API로 댓글을 여러 페이지에 걸쳐 수집해 한 번에 전달
4. 프론트에서 정렬/필터:
   - 정렬: 좋아요순 / 답글순 / 최신순
   - 필터: 좋아요 N개 이상, 답글 있는 것만
5. **[전체 모자이크]** 토글 → 모든 카드의 프로필 + 아이디 블러 처리
6. 각 카드의 **[복사]** 버튼 → 그 카드를 PNG 이미지로 만들어 클립보드에 복사
7. 캡컷 등에서 Ctrl+V로 붙여넣기

## 3. 아키텍처

기존 `web/` + `service/` 레이어 컨벤션을 따른다 (YoutubeSearchService / YoutubeSearchApiController와 동일 패턴). DB·엔티티는 추가하지 않는다.

### 3.1 백엔드

**`service/YoutubeCommentService`** (신규)
- `List<CommentCardDto> fetchComments(String videoIdOrUrl)`
- 입력에서 videoId 추출(정규식: `v=`, `youtu.be/`, `/shorts/`, 또는 11자리 ID 그대로)
- YouTube Data API `commentThreads.list` 호출:
  - `part=snippet`
  - `videoId={id}`
  - `order=relevance`
  - `maxResults=100`
  - `key={youtube.api.key}`
  - `pageToken`으로 페이지네이션 (최대 N페이지까지만 — 기본 5페이지 = 약 500개, 쿼터/응답크기 보호)
- 각 thread의 `snippet.topLevelComment.snippet`에서 추출:
  - `authorDisplayName` → authorName
  - `authorProfileImageUrl` → profileImageUrl
  - `textDisplay` → text (HTML 포함 가능, 프론트에서 안전 렌더링)
  - `likeCount` → likeCount
  - `publishedAt` → publishedAt
  - thread의 `snippet.totalReplyCount` → replyCount
- 댓글이 비활성화된 영상(403 commentsDisabled) 등은 빈 목록 + 사유 메시지로 처리

**`web/CommentCardApiController`** (신규, `/api/comment-cards`)
- `POST /api/comment-cards/fetch` — body `{ "url": "..." }`, 응답 `ApiResponse<List<CommentCardDto>>`
- `GET /api/comment-cards/avatar?url=...` — 프로필 이미지 **프록시**.
  - 이유: 카드를 PNG로 캡처할 때 외부 도메인(yt3.ggpht.com 등) 이미지는 canvas를 오염(taint)시켜 클립보드 복사가 막힘. 동일 출처로 프록시해 회피.
  - 화이트리스트: `*.ggpht.com`, `*.googleusercontent.com` 만 허용(SSRF 방지). 그 외 URL은 거부.
  - 응답: 원본 바이트 + 적절한 Content-Type, 캐시 헤더.

**`web/dto/CommentCardDto`** (신규)
- `authorName, profileImageUrl, text, likeCount, replyCount, publishedAt`

**쿼터**: `commentThreads.list`는 호출당 1유닛. 기존 `YoutubeQuotaGuard.tryConsume(pageCount)` 적용 — 예산 초과 시 수집 중단하고 그때까지 모은 댓글 반환 + 안내.

### 3.2 프론트엔드

**페이지 라우트**: `WebController`에 `@GetMapping("/comment-cards")` 추가, `currentPage="comment-cards"`, 템플릿 `comment-cards.html` 반환.

**사이드바**: `layout/sidebar.html`의 "제작" 그룹에 메뉴 항목 추가 (아이콘 예: `message-square-quote`).

**템플릿 `templates/comment-cards.html`**: `layout/base.html` 사용, 다크모드 디자인시스템(variables.css) 준수.
- 상단 입력바: URL input + [가져오기]
- 필터바: 정렬 셀렉트 + 좋아요 임계값 input + "답글만" 체크 + [전체 모자이크] 토글 버튼
- 카드 그리드: 유튜브 댓글 스타일 카드
  - 좌측 원형 프로필(프록시 경유 `/api/comment-cards/avatar?url=...`)
  - 상단 아이디 + 작성시간(상대표기)
  - 본문 댓글 텍스트
  - 하단 좋아요수(👍) + 답글수
  - 우상단/하단 [복사] 버튼
- 모자이크 상태일 때 프로필 + 아이디에 블러 적용

**정적 JS `static/js/comment-cards.js`**:
- fetch 호출 → 카드 렌더 → 클라이언트 정렬/필터
- 전체 모자이크 토글 → 카드에 `.mosaic` 클래스 토글
- 복사 → 카드 DOM을 PNG로 캡처 → 클립보드(`navigator.clipboard.write([new ClipboardItem({'image/png': blob})])`)

**DOM → 이미지 캡처 라이브러리**:
- `modern-screenshot`(또는 `snapdom`) 사용 — CSS `filter: blur()`를 SVG foreignObject로 충실히 렌더하므로 모자이크가 캡처 결과에 그대로 반영됨. (html2canvas는 blur 필터 미지원이라 부적합.)
- CDN `<script>`로 로드(기존 정적 자산 방식과 일관). 빌드 파이프라인 없음.
- 프로필 이미지는 프록시 동일출처라 taint 없이 캡처 가능.

**모자이크 방식**: 프로필 사진은 `filter: blur(6px)`(필요시 추가로 축소-확대 픽셀화), 아이디 텍스트는 `filter: blur(5px)`. 보내준 레퍼런스 이미지 수준의 식별 불가 처리.

## 4. 데이터 흐름

```
[브라우저] URL 입력
   → POST /api/comment-cards/fetch
[서버] videoId 추출 → commentThreads.list (페이지네이션, QuotaGuard)
   → List<CommentCardDto> (ApiResponse)
[브라우저] 카드 렌더 (프로필은 /api/comment-cards/avatar 프록시로 로드)
   → 정렬/필터 (클라이언트)
   → 전체 모자이크 토글 (CSS 블러)
   → [복사] → modern-screenshot로 카드 PNG 캡처 → 클립보드
```

## 5. 에러 처리

- 잘못된 URL/videoId 추출 실패 → 400, "유효한 유튜브 링크가 아닙니다"
- 댓글 비활성화 영상 → 빈 목록 + "이 영상은 댓글이 비활성화되어 있습니다"
- API 키 오류/쿼터 초과 → `GlobalExceptionHandler` 경유 에러 응답 + 프론트 토스트
- 프록시 화이트리스트 외 URL → 400 (SSRF 방지)
- 클립보드 복사 미지원 브라우저 → PNG 다운로드로 폴백 + 안내

## 6. 범위 밖 (YAGNI)

- 댓글 DB 저장/이력
- 영상 합성/편집 (사용자가 편집툴에서 직접)
- 답글(대댓글) 펼치기 — 최상위 댓글만
- 감정/키워드 분석
- 카드 디자인 커스터마이징(폰트/색상 옵션)

## 7. 검증

- 인기 영상 링크로 댓글 100+ 수집 확인
- 정렬(좋아요/답글/최신), 필터(임계값) 동작
- 전체 모자이크 토글 → 프로필+아이디 블러
- [복사] → 클립보드에 PNG 들어가고 캡컷/그림판에 붙여넣기 확인 (모자이크 반영 포함)
- 댓글 비활성화 영상/잘못된 링크 에러 처리
- 쿼터 가드 동작(페이지 상한)