# 계획서: task-145.1 — 유튜브 3-Layer 요약 파이프라인 구현

> **작성자**: 헤르메스 (개발1팀장)
> **작성일**: 2026-03-03
> **기반**: task-141.1 분석 보고서 → 방안 B 개선안 확정

---

## 1. 서브태스크 분해 및 팀원 배정

### ST-1: L3 자막 청크 저장 (불칸 - 백엔드)
- `crawlYoutubeChannels.ts`에 자막 추출 후 → 청크 분할 → `youtube_transcripts` 컬렉션 저장 로직 추가
- 청크 전략: 500자 단위, 50자 오버랩
- 스키마: videoId, channelId, channelName, title, chunkIndex, text, embedding, createdAt
- 임베딩: gemini-embedding-001 (기존과 동일)
- 기존 흐름(6섹션→youtube_knowledge) 절대 변경 금지

### ST-2: L2 구조화 요약 저장 (불칸 - 백엔드)
- 기존 6섹션 요약 완료 후, 별도 L2 프롬프트로 구조화 요약 생성
- `youtube_summaries` 컬렉션에 저장 (level: 'L2')
- L2 프롬프트: 4항목 구조 (핵심 주장, 관련 약관 조항, 실무 시사점, 주의사항)
- 환각 방지 가드 적용
- 기존 youtube_knowledge에는 이중 저장 안 함

### ST-3: L1 채널 통합 인사이트 배치 (불칸 - 백엔드)
- 새 Cloud Function `generateYoutubeChannelInsight` 생성
- 채널별 L2 요약들을 집약 → L1 통합 인사이트 생성
- `youtube_summaries` 컬렉션에 저장 (level: 'L1')
- 수동 호출 가능한 onRequest 함수로 구현

### ST-4: 통합 빌드 및 테스트 (아르고스 - 테스터)
- TypeScript 빌드 성공 확인
- 기존 insurance_chunks 벡터 검색 코드 미변경 확인
- youtube_knowledge 기존 흐름 무변경 확인
- 신규 코드 린트/타입 검사

---

## 2. 실행 순서

1. 불칸: ST-1 + ST-2 + ST-3 병렬 구현 (의존성 없음 — 각각 독립 파일/함수)
2. 헤르메스: 결과 통합 및 코드 리뷰
3. 아르고스: ST-4 빌드 검증

---

## 3. 예상 위험 및 대안

- **위험 1**: Gemini API 호출 추가(L2)로 크롤링 시간 증가 → 대안: L2 생성은 기존 요약 텍스트를 입력으로 사용하여 추가 자막 호출 불필요
- **위험 2**: 임베딩 비용 증가(L3 청크당 1회) → 대안: 청크 크기 500자로 제한, 단시간 영상은 청크 수 적음
- **위험 3**: Firestore 배치 쓰기 실패 → 대안: 개별 doc.add()로 부분 실패 허용, 에러 로깅

---

## 4. 실패 시나리오 체크리스트

### 4-1. 비정상 입력/상태
- 자막이 null인 경우: L3 저장 스킵 (기존 동작과 동일하게 제목+설명 기반 요약만 진행)
- 자막이 매우 짧은 경우(100자 미만): 청크 분할 없이 단일 청크로 저장
- Gemini L2 요약 실패: try-catch로 감싸서 실패해도 기존 흐름(6섹션)은 완료됨
- 대응: 각 신규 단계를 독립 try-catch 블록으로 분리

### 4-2. 동시성/경쟁 조건
- 6시간 간격 크롤링이므로 동시 실행 가능성 낮음
- youtube_transcripts/youtube_summaries는 videoId 기반 중복 체크로 방어
- 대응: 저장 전 videoId로 기존 문서 존재 확인

### 4-3. 비정상 종료/타임아웃
- Cloud Function 540초 타임아웃 내 처리 필요
- L3+L2 추가로 영상당 처리 시간 증가(약 8-12초 추가)
- 대응: L3/L2 저장은 기존 처리 완료 후 수행하므로, 타임아웃 시 기존 데이터는 이미 저장됨

### 4-4. 스테일 데이터
- L1 인사이트는 L2 데이터 기반이므로, L2가 아직 없는 채널은 L1 생성 스킵
- 대응: generateYoutubeChannelInsight에서 L2 문서 수 체크 후 최소 3개 이상일 때만 L1 생성

### 4-5. 통합 시 충돌
- index.ts에 export 추가만 필요 (기존 export 무변경)
- crawlYoutubeChannels.ts는 기존 흐름 하단에 신규 코드 추가 (기존 코드 수정 없음)
- 대응: 기존 코드 블록은 변경하지 않고, 새 블록을 기존 처리 완료 지점 이후에 삽입

---

*작성: 헤르메스 (개발1팀장) / 2026-03-03*