# 맥락노트: InsuWiki 유튜브 3-Layer 요약 파이프라인

> **문서 유형**: Context Note (설계 착수 전 맥락 정리)
> **작성자**: 아테나 (UX/UI 설계자)
> **작성일**: 2026-03-03
> **상태**: 초안 (Draft)
> **관련 스펙**: `docs/specs/260225-insuwiki-rag-spec-v2.md § 12`

---

## 목차

1. [프로젝트 배경 및 동기](#1-프로젝트-배경-및-동기)
2. [현재 시스템 현황](#2-현재-시스템-현황)
3. [핵심 제약사항 및 의존성](#3-핵심-제약사항-및-의존성)
4. [아키텍처 결정 사항 (ADR)](#4-아키텍처-결정-사항-adr)
5. [용어 정의](#5-용어-정의)
6. [UX 관점 고려사항](#6-ux-관점-고려사항)
7. [레퍼런스 문서 목록](#7-레퍼런스-문서-목록)

---

## 1. 프로젝트 배경 및 동기

### 1-1. 왜 유튜브 콘텐츠에도 3-Layer 체계가 필요한가

InsuWiki의 핵심 가치는 **설계사가 한 화면에서 신뢰도 계층이 다른 복수의 정보를 비교하며 업무를 처리**할 수 있게 하는 것입니다. 현재 약관 PDF에는 이미 3-Layer 요약 체계(원문 청크 → 섹션 요약 → 전체 핵심 요약)가 완성되어 있고, RAG 검색도 이 구조를 기반으로 설계되어 있습니다.

반면 유튜브 콘텐츠는 6섹션 평문 요약 하나만 존재합니다. 이는 약관 3-Layer와 구조적으로 이질적이어서 다음과 같은 문제가 발생합니다:

- 약관 Level 2(섹션 요약)와 유튜브 요약을 나란히 비교하는 UI를 구성할 수 없음
- "이 영상에서 어떤 상품을 다루는가"라는 상품 단위 집계 검색이 불가능함
- 채널 전체를 관통하는 "최근 트렌드 요약" 수준의 Level 1이 없어, 설계사가 채널 성격을 파악하기 위해 개별 영상을 일일이 열어봐야 함

유튜브 정보는 4순위 참고자료이지만 **설계사들이 실제로 가장 먼저 소비하는 정보**입니다. 이 정보를 약관과 동일한 구조로 관리해야 "약관 우선, 유튜브 참고"라는 원칙을 UI 레벨에서도 구현할 수 있습니다.

### 1-2. 현재의 문제점 — 6섹션 평문 요약의 한계

현재 `crawlYoutubeChannels.ts`가 생성하는 6섹션 요약은 다음과 같은 구조적 한계를 가집니다:

| 문제 | 설명 |
|---|---|
| **계층적 탐색 불가** | 영상 하나에 요약 하나만 존재. 주제별로 드릴다운하거나 채널 전체를 조감할 단위가 없음 |
| **벡터 검색 품질 저하** | 6섹션 전체가 하나의 청크로 임베딩됨. 섹션 1(핵심요약)과 섹션 4(수치정보)가 섞인 벡터는 검색 정밀도를 낮춤 |
| **약관 3-Layer와 구조 불일치** | insurance_summaries에는 level: 1\|2\|3 체계가 있으나, 유튜브 요약에는 level 개념이 없음. 통합 UI에서 두 소스를 동일한 방식으로 렌더링할 수 없음 |
| **채널 수준 집계 없음** | "이 채널이 최근 1개월간 주로 다룬 주제"를 단번에 파악할 방법이 없음 |
| **상품 연결 미흡** | `relatedProductIds: []`로 저장되나 실제로 값이 채워지지 않음. 유튜브에서 특정 상품을 언급한 영상을 역참조할 수 없음 |

### 1-3. 기대 효과

3-Layer 체계를 유튜브에도 적용하면 다음이 가능해집니다:

- **통합 검색**: "삼성생명 종신보험"을 검색할 때 약관 Level 2 요약과 관련 유튜브 Level 2 요약이 같은 인터페이스에서 비교 가능
- **일관된 UX**: 약관 상세 페이지와 유튜브 요약 페이지가 동일한 3단계 뎁스 구조로 동작
- **계층적 정보 접근**: 채널 전체 트렌드(Level 1) → 영상별 주제 요약(Level 2) → 섹션별 상세 내용(Level 3) 순으로 탐색 가능
- **정밀 벡터 검색**: 섹션별로 분리된 임베딩이 관련성 높은 결과를 반환
- **약관 상충 감지 강화**: Level 2 섹션 단위로 약관과 비교하므로 충돌 위치를 더 정확하게 특정

---

## 2. 현재 시스템 현황

### 2-1. 약관 3-Layer 시스템 상세

약관 PDF 3-Layer 시스템은 `scripts/summary-pipeline.ts`와 `scripts/prompts/summary-prompts.ts`로 구성됩니다.

**데이터 흐름:**

```
[PDF 인덱싱] pdfIndexing.ts
    ↓ insurance_chunks 저장 (sourceType: 'policy')
    ↓ summary_jobs 생성 (status: 'pending')

[요약 파이프라인] scripts/summary-pipeline.ts
    ↓ list: pending summary_jobs 조회
    ↓ read <jobId>: insurance_chunks 섹션별 정리 (관/장/절 패턴 감지)
    ↓ [Claude Code가 LEVEL2_SYSTEM_PROMPT + LEVEL2_USER_PROMPT_TEMPLATE 적용]
    ↓ save <jobId> --input <file>: insurance_summaries 저장

[저장 결과] insurance_summaries 컬렉션
    - level: 3 → insurance_chunks 원문 (별도 저장 없이 chunks 직접 참조)
    - level: 2 → 섹션(관/장/절) 단위 요약 (300~500자)
    - level: 1 → 전체 상품 핵심 요약 (200~400자, Level 2 통합)
```

**섹션 감지 패턴** (`summary-pipeline.ts` 133~138번째 줄):
```
/^제\s*\d+\s*관\s*\S*/   (제1관 총칙)
/^제\s*\d+\s*장\s*\S*/   (제1장 총칙)
/^제\s*\d+\s*절\s*\S*/   (제1절 총칙)
/^부\s*칙/               (부칙)
```

**프롬프트 원칙** (`summary-prompts.ts`):
- `HALLUCINATION_GUARD`: 약관 원문 외 내용 추가 절대 금지, 수치 원문 그대로 인용
- `SOURCE_CITATION_GUIDE`: 조항번호 표기, "(원문 인용)" 형태
- Level 2 출력: 핵심보장 / 면책·부담보·감액 / 지급조건 및 절차 / 특약 주의사항 4항목

### 2-2. 유튜브 파이프라인 상세

`functions/src/crawlYoutubeChannels.ts`가 Cloud Scheduler에 의해 6시간마다 실행됩니다.

**실행 흐름:**

```
1. youtube_channels (isActive: true) 로드
2. YouTube Data API → 업로드 플레이리스트 → 신규 영상 20개 필터
3. 영상별 처리:
   a. youtube_knowledge 중복 확인
   b. 영상 상세 조회 (길이, 설명)
   c. 자막 추출 (한국어 수동 자막 → ASR 자막 → 제목+설명 대체)
   d. Gemini 2.5 Flash → 6섹션 YOUTUBE_SUMMARY_PROMPT 적용
   e. Google Drive 04_유튜브요약/{채널명}/{날짜}_{제목}.md 업로드
   f. gemini-embedding-001으로 요약 텍스트 임베딩
   g. insurance_chunks (sourceType: 'youtube') 저장
   h. youtube_knowledge 저장
4. youtube_channels.lastCrawledAt 갱신
```

**현재 6섹션 프롬프트** (`YOUTUBE_SUMMARY_PROMPT`):
```
1. 핵심 요약
2. 설계사 고객 상담 활용 포인트
3. 언급된 보험 상품 / 보험사
4. 수치 / 금액 정보
5. 약관과 다를 수 있는 내용
6. 주제별 섹션 흐름 요약
```

**모니터링 채널:**
- 보험명의정닥터 (@보험명의정닥터)
- ins-king (@ins-king)

**인프라 설정:**
- Cloud Function 리전: asia-northeast3 (서울)
- 타임아웃: 540초
- 메모리: 1GiB
- 필수 Secret: GEMINI_API_KEY, YOUTUBE_API_KEY, DRIVE_CLIENT_ID, DRIVE_CLIENT_SECRET, DRIVE_REFRESH_TOKEN

### 2-3. 두 시스템의 연결점

두 시스템은 현재 `insurance_chunks` 컬렉션을 통해 느슨하게 연결되어 있습니다.

```typescript
// insurance_chunks 문서 구조 — sourceType으로 출처 구분
{
  sourceType: 'policy' | 'newsletter' | 'youtube',  // ← 핵심 연결점
  companyId: string,     // 약관: 보험사 ID / 유튜브: ''(빈값)
  companyName: string,   // 약관: 보험사명 / 유튜브: 채널명
  productId: string,     // 약관: 상품 ID / 유튜브: videoId
  productName: string,   // 약관: 상품명 / 유튜브: 영상 제목
  chunkText: string,     // 약관: 원문 청크 / 유튜브: 6섹션 요약(최대 2000자)
  embedding: number[],   // 공통 벡터 (gemini-embedding-001)
  pageNumber: number,    // 약관: 페이지 번호 / 유튜브: 0(고정)
  conflictsWithPolicy: boolean,
}
```

**현재의 문제:** 유튜브 청크는 pageNumber가 항상 0이며, 6섹션 전체가 하나의 chunkText로 저장됩니다. 약관 청크는 페이지 단위로 분리되어 세밀한 검색이 가능하지만, 유튜브 청크는 영상 단위로만 존재합니다.

**추가 컬렉션:** `youtube_knowledge`는 `insurance_chunks`와 별도로 유튜브 전용 메타데이터(videoId, channelId, driveUrl, hasTranscript 등)를 저장하지만, level 체계가 없습니다.

---

## 3. 핵심 제약사항 및 의존성

### 3-1. 정보 권위 4순위 제약 (변경 불가 원칙)

`docs/specs/260225-insuwiki-rag-spec-v2.md § 2`에 명시된 최우선 원칙입니다. 코드 어디에서도 이 순서를 역전시킬 수 없습니다.

```
[1순위] 약관 원문 (PDF)        ← 법적 효력, 최고 권위
[2순위] 보험사 공식 소식지      ← 공식 안내
[3순위] InsuWiki 위키 본문      ← 내부 검증 지식
[4순위] 유튜브 채널 정보        ← 참고 자료, 단독 인용 금지
```

**유튜브 정보 사용 규칙:**

| 규칙 | 내용 |
|---|---|
| 단독 인용 금지 | 유튜브 정보만으로 답변 생성 불가 |
| 상충 시 약관 우선 | 유튜브와 약관이 다를 경우 약관 기준 답변 + 경고 |
| 출처 명시 의무 | 답변에 채널명 + 영상 업로드일 반드시 표기 |
| 자동 면책 문구 | "※ 실제 약관 내용과 다를 수 있습니다. 약관 원문을 우선하세요." |
| 시점 주의 | 영상 업로드 시점 약관 기준으로 분석 (현행 약관과 다를 수 있음) |

이 제약은 3-Layer 설계 전반에 영향을 미칩니다. 특히 **유튜브 Level 1(채널 트렌드 요약)은 어떤 상황에서도 단독 답변 근거로 사용할 수 없습니다.**

### 3-2. YouTube Data API 할당량 제한

YouTube Data API v3는 일일 할당량 **10,000 유닛**을 무료로 제공합니다.

| 작업 | 소비 유닛 |
|---|---|
| channels.list (채널 정보) | 1 유닛 |
| playlistItems.list (영상 목록) | 1 유닛 |
| videos.list (영상 상세) | 1 유닛 |

현재 구조에서는 채널당 최대 약 22 유닛을 사용합니다(채널 조회 1 + 목록 조회 1 + 영상 상세 최대 20). 채널 2개 기준 일일 약 44 유닛 소비 — 여유가 충분합니다.

**3-Layer 확장 시 주의사항:** 재처리(Level 2 → Level 1 집계) 과정은 Firestore와 Gemini API만 사용하므로 YouTube API 할당량에 영향 없습니다.

### 3-3. Gemini API 비용 고려

현재 파이프라인에서 영상당 두 번의 Gemini 호출이 발생합니다:

1. **요약 생성**: `gemini-2.5-flash` — 자막 최대 200,000자 입력
2. **임베딩 생성**: `gemini-embedding-001` — 요약 최대 8,000자 입력

**3-Layer 추가 시 예상 비용 증가:**

대안에 따라 다르지만, Level 2(섹션별)와 Level 1(집계) 생성을 위해 영상당 추가 호출이 발생합니다. `gemini-2.5-flash`는 입출력 비용이 낮아 부담이 크지 않으나, 임베딩은 섹션별로 분리하면 호출 횟수가 배증합니다.

**기본 방침:** 영상 처리당 Gemini Flash 호출은 최대 5회로 제한합니다. 현재 Rate Limit 방지를 위한 4초 딜레이가 설정되어 있으며(Gemini Flash 15req/min 제한), 이를 유지합니다.

### 3-4. 기존 crawlYoutubeChannels.ts와의 하위호환성

`crawlYoutubeChannels.ts`는 현재 프로덕션에서 실행 중인 코드입니다. 변경 시 다음 사항을 반드시 준수해야 합니다:

- `youtube_knowledge` 컬렉션 스키마를 **하위호환** 방식으로 확장 (기존 필드 삭제·변경 금지)
- `insurance_chunks`의 `sourceType: 'youtube'` 청크 저장 로직 유지 (RAG 쿼리 라우터가 의존)
- Drive 업로드 경로 `04_유튜브요약/{채널명}/{날짜}_{제목}.md` 변경 금지
- 중복 처리 방지 로직(`youtube_knowledge`에 videoId 존재 여부 확인) 유지
- 기존 `conflictsWithPolicy` 플래그 처리 로직 유지 (Phase 2 완성 예정)

### 3-5. Drive 폴더 구조 의존성

```
InsuWiki_RAG/ (루트 폴더 ID: GOOGLE_DRIVE_ROOT_FOLDER_ID 환경변수)
└── 04_유튜브요약/
    ├── 보험명의정닥터/
    │   └── 260301_영상제목.md
    └── ins-king/
        └── 260301_영상제목.md
```

3-Layer 확장 시 Drive 구조는 변경하지 않습니다. Level 2 섹션별 파일을 별도로 Drive에 저장하는 것은 불필요하며, Firestore에만 저장합니다.

---

## 4. 아키텍처 결정 사항 (ADR)

### 4-1. 문제 정의

유튜브 콘텐츠에 3-Layer 요약 구조를 도입할 때, 기존 6섹션 요약 시스템을 어떻게 처리할 것인가?

### 4-2. 대안 비교

#### 대안 A: 기존 6섹션 요약을 Level 2로 그대로 매핑

**개념:** 현재 6섹션(핵심요약/설계사활용/언급상품/수치정보/약관불일치/흐름요약)을 Level 2로 간주하고, 별도의 Level 1(채널 집계)과 Level 3(자막 원문 청크) 레이어만 추가합니다.

```
Level 3: 영상 자막 원문 시간대별 청크
Level 2: 기존 6섹션 요약 = 영상 단위 요약 (현행 유지)
Level 1: 채널별 월간/전체 트렌드 집계 (신규)
```

**장점:**
- 기존 `YOUTUBE_SUMMARY_PROMPT` 코드 변경 최소화
- 이미 저장된 youtube_knowledge 데이터 재활용 가능
- 구현 비용 최소 (Level 1 집계 로직만 추가)

**단점:**
- 6섹션이 "약관 구조"(핵심보장/면책/지급조건/특약)와 정렬되지 않아, 약관 Level 2와 비교 UI를 만들기 어려움
- 섹션 1~6이 동일한 계층(Level 2)이라면 각 섹션별 임베딩이 없어 검색 정밀도 개선 효과 제한적
- Level 3(자막 청크)는 구현 복잡도가 높음 — 자막이 없는 영상(제목+설명만) 처리 불일치

**구현 비용:** 낮음 (1~2주)
**기존 시스템 영향도:** 낮음 (Level 1 집계 Cloud Function 추가만 필요)

---

#### 대안 B: 6섹션 요약 폐기, 새로운 3-Layer 프롬프트로 완전 교체

**개념:** 기존 6섹션 프롬프트를 제거하고, 약관 3-Layer와 대칭하는 완전히 새로운 프롬프트 체계로 교체합니다.

```
Level 3: 영상 자막 시간대별 청크 (원문)
Level 2: 주제별 섹션 요약 — [보장내용 언급] / [설계사 활용포인트] / [수치정보] / [주의사항]
Level 1: 영상 전체 핵심 요약 (200~300자)
```

**장점:**
- 약관 Level 1/2/3과 완전히 대칭하는 구조 → 통합 UI 설계 용이
- 섹션별 독립 임베딩으로 검색 정밀도 최대화
- "보장내용 언급" 섹션이 약관 Level 2의 "핵심보장"과 직접 비교 가능

**단점:**
- 기존에 저장된 youtube_knowledge 데이터 전수 마이그레이션 필요 (또는 legacy 필드로 보존)
- 자막 없는 영상의 Level 3 품질이 극히 낮음 (제목+설명만으로 청킹 불가)
- 6섹션 중 "설계사 고객 상담 활용 포인트"는 유튜브 고유의 가치 있는 섹션인데, 약관 구조에 맞추면 이 내용이 어느 Level에도 자연스럽게 들어가지 않음
- `YOUTUBE_SUMMARY_PROMPT` 전면 재작성 필요, Cloud Function 수정 공수 큼

**구현 비용:** 높음 (4~6주, 마이그레이션 포함)
**기존 시스템 영향도:** 높음 (crawlYoutubeChannels.ts 대규모 수정, 기존 데이터 마이그레이션)

---

#### 대안 C: 6섹션 유지 + 별도 3-Layer 레이어 추가 (하이브리드)

**개념:** 기존 6섹션 요약은 "영상 상세(Video Detail)" 뷰에서 그대로 사용하고, 추가로 3-Layer 구조를 병렬로 생성합니다. 두 표현 방식이 공존합니다.

```
[기존 유지]
youtube_knowledge.chunkText = 6섹션 전체 요약 (Drive 마크다운과 동일)

[신규 추가] youtube_summaries 컬렉션 (또는 youtube_knowledge 서브컬렉션)
Level 1: 영상 핵심 요약 (1~2문단, 약관 비교용)
Level 2: 주제 섹션별 요약 (약관 비교 가능한 4항목 구조)
Level 3: 자막 원문 청크 (insurance_chunks에 pageNumber를 시간대로 대체)
```

**장점:**
- 하위호환성 완벽 유지 — 기존 코드와 데이터 무변경
- 6섹션(설계사 활용 중심)과 3-Layer(약관 비교 중심)를 목적에 따라 선택 사용
- Level 3 자막 청크의 `pageNumber` 필드를 "자막 시작 시간(초)"으로 재해석 가능
- 기존 Drive 파일 구조 완전 유지

**단점:**
- 영상당 저장 데이터 양 2배 증가 (6섹션 + 3-Layer 별도 저장)
- Gemini 호출 증가 — 영상 처리 시간 및 비용 상승
- 두 가지 요약 구조가 공존하므로 코드 복잡도 증가
- UI에서 어떤 요약을 보여줄지 컨텍스트에 따라 결정하는 로직 필요

**구현 비용:** 중간 (2~4주)
**기존 시스템 영향도:** 중간 (신규 컬렉션 및 처리 로직 추가, 기존 코드 무변경)

---

### 4-3. 비교 요약표

| 항목 | 대안 A | 대안 B | 대안 C |
|---|---|---|---|
| 구현 비용 | 낮음 (1~2주) | 높음 (4~6주) | 중간 (2~4주) |
| 하위호환성 | 높음 | 낮음 | 최고 |
| 약관 구조 정렬 | 낮음 | 높음 | 높음 |
| 검색 정밀도 개선 | 낮음 | 높음 | 높음 |
| 데이터 마이그레이션 | 불필요 | 필요 | 불필요 |
| 기존 코드 변경 | 최소 | 전면 | 최소 |
| 설계사 활용 포인트 보존 | 유지 | 소실 위험 | 완전 유지 |
| Gemini 비용 증가 | 낮음 | 중간 | 중간-높음 |

### 4-4. 추천안

**대안 C (하이브리드)를 추천합니다.**

**근거:**

1. **설계사 활용 포인트 보존**: 현행 6섹션 중 "설계사 고객 상담 활용 포인트"는 약관에 없는 유튜브 고유의 실무 지식입니다. 이를 폐기하면 현재 사용 중인 가치가 손실됩니다.

2. **하위호환성 우선**: `crawlYoutubeChannels.ts`는 프로덕션에서 실행 중이며, 이미 수집된 데이터가 존재합니다. 대안 B의 마이그레이션은 실질적인 위험입니다.

3. **목적 분리의 명확성**: 6섹션은 "이 영상의 업무 활용 가치"를, 3-Layer는 "약관과의 비교 구조"를 각각 담당합니다. 두 목적은 다르며 공존이 자연스럽습니다.

4. **점진적 진화**: 대안 C는 향후 6섹션 폐기(대안 B로 전환) 또는 현행 유지(대안 A 수준) 어느 방향으로도 전환 가능한 중간 경로입니다.

**추천 구현 범위 (Phase):**

- **Phase 1**: Level 1 + Level 2 추가 (자막 있는 영상 대상, youtube_summaries 컬렉션 신규)
- **Phase 2**: Level 3 자막 청크 분리 저장 (insurance_chunks에 시간대별 청크)
- **Phase 3**: 채널 단위 월간 트렌드 집계 (별도 scheduled job)

---

## 5. 용어 정의

### 5-1. Level 1 / 2 / 3 — 유튜브 맥락에서의 정의

| Level | 약관 맥락 | 유튜브 맥락 (대안 C 기준) |
|---|---|---|
| **Level 3** | insurance_chunks의 원문 PDF 청크 (페이지 단위) | 영상 자막 원문 청크 (시간대 단위, 약 60~120초 단위) |
| **Level 2** | insurance_summaries의 섹션(관/장/절) 요약 (300~500자) | youtube_summaries의 주제 섹션별 요약 — [보장내용 언급] / [설계사 포인트] / [수치정보] / [주의사항] |
| **Level 1** | insurance_summaries의 전체 상품 핵심 요약 (200~400자) | youtube_summaries의 영상 전체 핵심 요약 (200~300자) |

### 5-2. 기존 약관 Level 1/2/3과의 차이

| 비교 항목 | 약관 Level 2 | 유튜브 Level 2 |
|---|---|---|
| 단위 | 약관의 관/장/절 (법적 구조) | 영상의 주제 섹션 (콘텐츠 구조) |
| 출처 신뢰도 | 1순위 (법적 효력) | 4순위 (참고 자료) |
| 섹션 감지 | 패턴 매칭 (/^제\s*\d+\s*관/) | LLM 기반 주제 분류 |
| 저장 컬렉션 | insurance_summaries | youtube_summaries (신규 예정) |
| 단독 인용 | 허용 | 금지 |
| 수치 표현 | 원문 그대로만 (환각 방지 최고 강도) | 자막 원문 인용 (동일 원칙 적용) |

### 5-3. 컬렉션 관계 정리

```
[유튜브 데이터 흐름]

자막 원문
   ↓ (시간대별 청킹 — Phase 2)
insurance_chunks (sourceType: 'youtube', pageNumber = 자막 시작초)
   = Level 3

자막 전체
   ↓ (Gemini 2.5 Flash 주제 분류 + 섹션 요약)
youtube_summaries (level: 2, videoId 참조)
   = Level 2

Level 2 전체
   ↓ (집계 요약)
youtube_summaries (level: 1, videoId 참조)
   = Level 1

---

youtube_knowledge: 영상별 메타데이터 허브
  - videoId, channelId, channelName
  - 6섹션 평문 요약 (기존 유지)
  - driveUrl, hasTranscript
  - conflictsWithPolicy
  - level1SummaryId → youtube_summaries 참조 (신규)
  - level2SummaryIds[] → youtube_summaries[] 참조 (신규)

insurance_summaries: 약관 전용 (유튜브 데이터 저장 금지)
insurance_chunks: 약관 + 유튜브 공유 (sourceType으로 구분)
youtube_summaries: 유튜브 3-Layer 전용 (신규 컬렉션)
youtube_knowledge: 유튜브 메타데이터 허브 (기존 + 확장)
youtube_channels: 모니터링 채널 목록 (변경 없음)
```

---

## 6. UX 관점 고려사항

### 6-1. 설계사(사용자)가 유튜브 요약을 어떻게 활용하는가

현장 설계사의 유튜브 요약 활용 시나리오는 크게 세 가지입니다:

**시나리오 A — 상품 학습 전 사전 조사**
> "이 상품 관련 영상 있어? 약관 읽기 전에 개요 파악하고 싶어."

요구: Level 1 요약(영상 핵심)을 빠르게 확인 → 관심 있는 영상 선별 → Level 2(섹션별) 상세 확인

**시나리오 B — 약관 이해 보조**
> "약관 제3관 면책 조항 이해가 안 되는데, 관련 유튜브 설명이 있어?"

요구: 약관 Level 2 섹션과 연관된 유튜브 Level 2 섹션을 나란히 비교. 상충 경고가 있는 경우 즉시 인지.

**시나리오 C — 고객 상담 준비**
> "내일 60대 고객과 종신보험 상담인데, 설계사 활용 포인트 뭐가 있어?"

요구: 유튜브 6섹션 중 "설계사 고객 상담 활용 포인트" 섹션을 빠르게 열람. 이 시나리오에서는 3-Layer가 아닌 기존 6섹션이 더 적합합니다.

**UI 함의:** Level 1/2/3 탐색 뷰와 6섹션 상세 뷰를 탭으로 분리하거나, 기본 뷰는 Level 1 요약으로 시작하고 "상세 보기"로 6섹션을 제공하는 구조가 자연스럽습니다.

### 6-2. 약관 요약과 유튜브 요약이 UI에서 함께 표시되어야 하는 방식

**원칙:**
1. 두 정보 소스의 **신뢰도 차이를 시각적으로 명확히** 구분합니다.
2. 유튜브 요약은 항상 약관 요약보다 **시각적 위계가 낮은 위치**에 배치합니다.
3. 상충 정보가 있을 경우, 사용자가 **화면을 스크롤하지 않아도** 경고를 인지할 수 있어야 합니다.

**레이아웃 제안 (상품 상세 페이지):**

```
┌─────────────────────────────────────────────────────┐
│ [상품명] 삼성생명 퍼펙트종신                          │
│                                                     │
│ ━━━ 약관 요약 (1순위) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│  Level 1: [전체 핵심 요약]                          │
│  Level 2: [섹션 목록 — 펼치기]                     │
│                                                     │
│ ━━━ 유튜브 참고 정보 (4순위) ━━━━━━━━━━━━━━━━━━━━━━ │
│  🎬 관련 영상 3개                                   │
│  ⚠️ [영상 1] 약관과 다른 내용이 감지되었습니다     │
│  [영상 1 Level 1 요약 — 간략]   [상세 보기 ▶]     │
│  [영상 2 Level 1 요약 — 간략]   [상세 보기 ▶]     │
│                                                     │
│ ℹ️ 유튜브 정보는 참고용이며 약관 원문을 우선합니다  │
└─────────────────────────────────────────────────────┘
```

**시각적 구분 방법:**
- 약관 요약: 기본 배경, 파란색 계열 헤더
- 유튜브 요약: 연회색 배경 또는 좌측 노란색 보더, "4순위 참고" 배지
- 상충 감지 시: 주황색 경고 아이콘 + 접을 수 있는 상충 내용 비교 패널

### 6-3. 상충 경고 배너의 UX 패턴

현재 `conflictsWithPolicy` 플래그가 있지만 실제 상충 내용은 Phase 2에서 구현 예정(`crawlYoutubeChannels.ts` 531번째 줄 주석 참조)입니다. 3-Layer 도입 시 상충 감지가 섹션 단위로 정밀해지므로, 경고 UX도 함께 설계해야 합니다.

**상충 경고 3단계 패턴:**

| 단계 | 조건 | UI 표현 |
|---|---|---|
| **정보 알림** | 유튜브 영상이 특정 보장을 언급하나 해당 약관이 DB에 없음 | ℹ️ 파란색 배너 — "약관 확인 필요" |
| **주의 경고** | 유튜브 내용이 약관과 다를 가능성 있음 (벡터 유사도 0.92 이상) | ⚠️ 노란색 배너 — "내용 확인 권장" |
| **충돌 경보** | Gemini 비교 후 실제 상충 확인됨 | 🚨 빨간색 배너 — "약관과 다른 내용입니다" + 상충 내용 나란히 표시 |

**상충 배너 컴포넌트 표준:**

```
┌──────────────────────────────────────────────────────────┐
│ ⚠️ 유튜브 영상과 약관 내용이 다릅니다                     │
│                                                          │
│ [영상 내용] "암 진단 시 3000만원 지급"                    │
│ [약관 기준] "일반암 진단 시 2000만원, 소액암 500만원"      │
│            ↑ 이것이 정확한 내용입니다                     │
│                                                          │
│ ※ 출처: 영상명 (보험명의정닥터, 2026-02-15)               │
│ ※ 약관: 퍼펙트종신 2403, 15p                             │
└──────────────────────────────────────────────────────────┘
```

**중요 원칙:**
- 경고 배너는 **닫을 수 없어야** 합니다 (사용자가 위험 정보를 무시하지 못하도록)
- 약관 근거 없이 "유튜브와 다를 수 있음"만 표시하는 것은 금지 (과도한 경고는 신뢰 손상)
- 경고 발생 시 자동으로 해당 약관 Level 2 섹션 링크 제공

---

## 7. 레퍼런스 문서 목록

### 7-1. 스펙 문서

| 문서 | 경로 | 관련 섹션 |
|---|---|---|
| RAG 아키텍처 스펙 v2.0 | `docs/specs/260225-insuwiki-rag-spec-v2.md` | § 2 (정보 권위 계층), § 12 (유튜브 수집) |
| RAG 아키텍처 스펙 v2.1 | `docs/specs/260225-insuwiki-rag-spec-v2.1.md` | 최신 업데이트 확인 필요 |
| Firestore 스키마 설계 | `docs/decisions/260208-20.59-firestore-schema.md` | insurance_chunks, youtube_knowledge |
| Wiki 보호 ADR | `docs/decisions/260215-21.45-wiki-protection-adr.md` | ADR 작성 형식 참조 |

### 7-2. 코드 파일

| 파일 | 경로 | 역할 |
|---|---|---|
| 유튜브 크롤러 Cloud Function | `functions/src/crawlYoutubeChannels.ts` | 현행 파이프라인 전체 |
| 약관 요약 CLI | `scripts/summary-pipeline.ts` | 3-Layer 저장 흐름 참조 |
| 요약 프롬프트 모듈 | `scripts/prompts/summary-prompts.ts` | Level 1/2 프롬프트 설계 기준 |
| Cloud Functions 인덱스 | `functions/src/index.ts` | 함수 등록 방식 참조 |
| RAG 쿼리 핸들러 | `functions/src/ragQuery.ts` | 유튜브 Level 참조 방식 영향 |

### 7-3. 관련 설계 결정 문서

| 문서 | 경로 | 관련성 |
|---|---|---|
| 에이전트 백링크 분리 분석 | `docs/plans/260219-9-agent-backlink-separation-analysis.md` | 컬렉션 분리 패턴 참조 |
| 에이전트 최적화 미팅 | `docs/plans/260219-9-agent-optimization-meeting.md` | 시스템 최적화 방향 참조 |

### 7-4. 후속 작업 시 참조할 환경 설정

- **Cloud Function 리전**: `asia-northeast3` (서울) — 모든 신규 함수 동일 리전 적용
- **임베딩 모델**: `gemini-embedding-001` (변경 시 기존 벡터와 검색 호환성 깨짐, 절대 단독 변경 금지)
- **요약 모델**: `gemini-2.5-flash` (현행)
- **Firestore 벡터 검색**: `COSINE` 거리 측정, 임계값 0.85 이상 신뢰 (0.70 미만 매칭 없음 선언)
- **Drive 루트**: `GOOGLE_DRIVE_ROOT_FOLDER_ID` 환경변수 (Secret Manager 미등록, 직접 환경변수)

---

> **이 문서의 다음 단계:**
> 맥락노트 검토 후, 추천안(대안 C)으로 결정되면 구체적인 스펙 문서(`260303-youtube-3layer-spec.md`)를 작성하고 `youtube_summaries` 컬렉션 스키마 및 신규 Cloud Function 설계를 시작합니다.
>
> 결정이 필요한 사항:
> 1. 대안 A / B / C 중 최종 선택
> 2. Phase 1 착수 시점 및 담당
> 3. Level 2 섹션 구조 4항목 확정 (약관 구조 차용 vs. 유튜브 고유 구조)