수동 작업 안내서

완료 상세 검증 과정에서 드러난 것

1. YouTube Data API v3 키 발급 완료 — 절차는 재발급 시 참고용

발급 절차

1. Google Cloud Console 접속 → console.cloud.google.com
2. 프로젝트 생성 (또는 기존 프로젝트 선택). 상단 프로젝트 선택기 → "새 프로젝트"
3. YouTube Data API v3 사용 설정
   좌측 메뉴 API 및 서비스 → 라이브러리 → "YouTube Data API v3" 검색 → 사용 클릭
4. API 키 생성
   API 및 서비스 → 사용자 인증 정보 → + 사용자 인증 정보 만들기 → API 키
5. 키 제한(권장)
   생성된 키 → API 제한사항 → "키 제한" 선택 → YouTube Data API v3만 체크. 애플리케이션 제한은 서버에서 쓰므로 "없음" 또는 IP 제한.
6. .env.dev 에 추가

   YOUTUBE_API_KEY=AIza...

   ※ .env.prod 에도 동일하게 추가해야 프로덕션에서 동작합니다.

키 발급 후 즉시 확인 (무료)

구현 전에 키가 살아있는지, 그리고 정말 channelId 가 오는지 먼저 확인하세요.

# 1) 영상 조회 — snippet.channelId 가 오는지가 핵심
export YT_KEY='여기에_발급받은_키'

curl -s "https://www.googleapis.com/youtube/v3/videos?part=snippet,statistics&id=dQw4w9WgXcQ&key=$YT_KEY" \
  | python3 -m json.tool | head -40

# 기대: items[0].snippet.channelId = "UCuAXFkgsw1L7xaCfnd5JJOw"
#       items[0].statistics.viewCount / likeCount / commentCount

# 2) 핸들 → channelId 해석 (audit 이 "handle 로 channel id 를 찾을 수 있나" 물었던 부분)
curl -s "https://www.googleapis.com/youtube/v3/channels?part=snippet,statistics&forHandle=@nateherk&key=$YT_KEY" \
  | python3 -m json.tool | head -40

# 기대: items[0].id = "UC..." · snippet.publishedAt(계정 개설일) · statistics.subscriberCount

2. 수정한 fetcher 검증 방법 공통

방법 A — HTTP API (권장, 가장 간단)

디버깅 전용 엔드포인트가 이미 있습니다. URL 1건을 라우팅+fetch 해서 결과를 그대로 돌려줍니다.

# 서버 기동 (포트는 .env.dev 의 APP_PORT=30003)
npm run start:dev

# 다른 터미널에서
curl -s 'http://localhost:30003/v1/social-fetcher/fetch?url=https://x.com/solana' \
  | python3 -m json.tool

{
  "sourceType": "x_tweet",      ← 분류가 맞나
  "sourceKey":  "2070...",      ← 키가 맞나(리터럴 'playlist' 같은 게 아닌지)
  "status":     "ok",
  "valueNature": { ... },        ← fixed/mutable 표기
  "data": { ... }                ← 실제 담긴 필드
}

방법 B — 라우터만 확인 (서버·API 불필요, 무료)

fetch 없이 분류만 보고 싶을 때. 네트워크를 전혀 안 탑니다.

npx jest test/social-fetcher/router-cases.test.ts

# 새 URL 을 케이스로 추가하려면 test/social-fetcher/router-cases.json 에 한 줄:
# { "url": "...", "sourceType": "...", "sourceKey": "...", "group": "manual" }

3. 소셜별 검증 1·2·3 완료 · 4 남음

3-1. X 완료 유료 1콜

# 인용(quote) 트윗으로 테스트해야 nested 필드까지 검증됨
curl -s 'http://localhost:30003/v1/social-fetcher/fetch?url=https://x.com/jncquant/status/2070140594496626759' \
  | python3 -m json.tool

curl -s 'http://localhost:30003/v1/social-fetcher/fetch?url=https://x.com/nvidiamoonbsc' \
  | python3 -m json.tool

3-2. 라우터 분류 무료 — 이번에 고친 버그 3건

fetch 를 안 타므로 비용 0입니다. sourceType·sourceKey 만 보면 됩니다.

# ① reddit share — 이전엔 reddit/{subreddit} 로 오분류(share 가 subreddit 과 한 키로 병합)
curl -s 'http://localhost:30003/v1/social-fetcher/fetch?url=https://www.reddit.com/r/elonmusk/s/SZ4HmKd53H'
# 기대: sourceType=reddit_share, sourceKey=SZ4HmKd53H

# ② youtube playlist — 이전엔 모든 재생목록이 sourceKey='playlist' 를 공유
curl -s 'http://localhost:30003/v1/social-fetcher/fetch?url=https://www.youtube.com/playlist?list=PLabc123'
# 기대: sourceType=youtube_playlist, sourceKey=PLabc123 (status=unsupported — fetch 보류가 의도)

# ③ instagram /{handle}/reel/{code} — 이전엔 handle 을 키로 잡아 게시물이 프로필로 오분류
curl -s 'http://localhost:30003/v1/social-fetcher/fetch?url=https://www.instagram.com/someuser/reel/DZvu_BVzM5W/'
# 기대: sourceType=instagram_post, sourceKey=DZvu_BVzM5W

# ④ vm.tiktok.com — 이전엔 unknown 이라 통째 유실
curl -s 'http://localhost:30003/v1/social-fetcher/fetch?url=https://vm.tiktok.com/ZNRTtUjSM/'
# 기대: sourceType=tiktok_shortlink, sourceKey=ZNRTtUjSM (status=unsupported — 상류 정규화 예정)

# ⑤ github 예약경로 — 이전엔 sponsors/xxx 를 repo 로 오인
curl -s 'http://localhost:30003/v1/social-fetcher/fetch?url=https://github.com/sponsors/someone'
# 기대: sourceType=unknown

3-3. reddit Apify 검증 완료

# APIFY_TOKEN 은 .env.dev 에 이미 있음 (값 출력 금지)
export APIFY_TOKEN=$(grep '^APIFY_TOKEN=' .env.dev | cut -d= -f2-)

curl -s -X POST \
  "https://api.apify.com/v2/acts/harshmaur~reddit-scraper/run-sync-get-dataset-items?token=$APIFY_TOKEN&timeout=120" \
  -H 'Content-Type: application/json' \
  -d '{"startUrls":[{"url":"https://www.reddit.com/r/wallstreetbets/"}],"maxItems":1}' \
  | python3 -m json.tool | head -60

확인할 것: 응답 필드가 문서의 raw 부록과 일치하는지 — 특히 body/bodyHtml(본문) · crawledAt(as-of 앵커) · parsedId · authorName. 이 둘은 완료 rubric 이 "문서에서 통째로 빠져 있었다"고 적발한 필드라 실재 여부 확인이 필요합니다.

3-4. instagram prodiger drop-in 검증 남음 유료 2콜 · 급하지 않음

actor 교체(현행 apify~instagram-scraper → prodiger/instagram-scraper)는 월 $3 차이라 우선순위가 낮습니다. 응답 스키마가 동일한 drop-in 인지만 확인하면 됩니다.

# 같은 URL 을 두 actor 로 호출해 키 집합 비교
for ACTOR in "apify~instagram-scraper" "prodiger~instagram-scraper"; do
  echo "--- $ACTOR"
  curl -s -X POST "https://api.apify.com/v2/acts/$ACTOR/run-sync-get-dataset-items?token=$APIFY_TOKEN&timeout=120" \
    -H 'Content-Type: application/json' \
    -d '{"directUrls":["https://www.instagram.com/knowyourmeme/"],"resultsType":"details","resultsLimit":1}' \
    | python3 -c "import json,sys; d=json.load(sys.stdin); print(sorted(d[0].keys()) if d else 'EMPTY')"
done

키 집합이 같으면 drop-in. 다르면 현행 유지(비용차가 무의미).

4. 전체 회귀 확인 무료 · 언제든

# social-fetcher 전체 (139개)
npx jest test/social-fetcher

# 타입 체크 — social/twitter 관련만 필터(레포에 무관한 사전 에러가 다수 있음)
npx tsc --noEmit -p tsconfig.json 2>&1 | grep -icE 'social|twitter'
# 기대: 0

5. 남은 것 fetcher 계층 밖