# 계획서: task-128.1 — InsuWiki PDF 약관 파이프라인 리팩토링 Phase 1+2

## 목표
- Phase 1: pdfIndexing.ts에서 Gemini 텍스트 추출 → pdf-parse로 교체, 임베딩 병렬화
- Phase 2: InsuranceSummary 타입 정의, insurance_summaries/summary_jobs Firestore 규칙 추가, pdfIndexing 완료 시 summary_jobs 생성

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

### ST-1. [불칸-백엔드] Phase 1 — pdfIndexing.ts 리팩토링
- pdf-parse 도입으로 Gemini 텍스트 추출 대체
- 페이지 단위 [PAGE n] 마커 자동 삽입
- 임베딩 병렬화 (순차 → 배치 Promise.all, 10개 단위)
- 대용량 PDF 분할 처리 로직 (500페이지 초과 시 분할)
- 기존 용어 추출(Gemini) 유지
- functions/package.json에 pdf-parse 의존성 추가

### ST-2. [불칸-백엔드] Phase 2 — summary_jobs 생성 로직
- pdfIndexing 완료 시 summary_jobs 문서 생성 (status: pending)
- insurance_chunks에 sectionId 필드 추가

### ST-3. [이리스-프론트엔드] Phase 2 — InsuranceSummary/SummaryJob 타입 정의
- nextapp/src/types/firestore.ts에 InsuranceSummary, SummaryJob 타입 추가
- COLLECTIONS 상수에 새 컬렉션 추가

### ST-4. [아테나-UX/UI] Phase 2 — Firestore 보안 규칙 추가
- insurance_summaries 컬렉션 규칙 (인증 사용자 읽기, 서버만 쓰기)
- summary_jobs 컬렉션 규칙 (서버 전용)

### ST-5. [아르고스-테스터] 통합 테스트 + TypeScript 빌드 검증
- TypeScript 컴파일 테스트
- 리팩토링된 코드 리뷰 및 검증

## 실행 순서
1. ST-1, ST-3, ST-4 병렬 실행 (독립적)
2. ST-1 완료 후 ST-2 실행 (ST-1 결과에 의존)
3. 전체 통합 후 ST-5 실행

## 검토한 대안과 기각 사유
- **대안 1: pdfjs-dist 사용** → pdf-parse가 더 가볍고 텍스트 추출에 특화. pdfjs-dist는 렌더링 기능까지 포함해 번들 크기 과다. 기각.
- **대안 2: 임베딩 전체 Promise.all** → 수백 개 동시 요청 시 API rate limit 초과 위험. 10개 배치로 절충.
- **대안 3: summary_jobs를 jobs 컬렉션에 통합** → jobs는 TTL 10분 자동 삭제 정책. summary_jobs는 장기 보존 필요. 별도 컬렉션으로 분리.

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

### 1. 비정상 입력/상태
- pdf-parse가 특정 형식 PDF 파싱 실패 → catch 블록에서 기존 Gemini File API 폴백 구현
- 손상된 PDF 업로드 → pdf-parse 에러 → Job status: failed로 기록, 에러 메시지 저장

### 2. 동시성/경쟁 조건
- 여러 PDF 동시 업로드 → 각 Cloud Function 인스턴스가 독립 실행, 공유 자원 없음 → 해당 없음
- summary_jobs 중복 생성 → productId 기반 문서 ID로 upsert (set with merge) → 중복 방지

### 3. 비정상 종료/타임아웃
- 540초 타임아웃 → 대용량 PDF(500p 초과) 분할 처리로 대응
- 임베딩 중 타임아웃 → 이미 저장된 청크는 유지, Job status: failed 기록
- summary_jobs는 pending 상태로 남음 → Phase 3에서 TTL 정책 적용 예정

### 4. 스테일 데이터
- 같은 상품 재인덱싱 시 기존 chunks 잔존 → 기존 동작 유지 (덮어쓰기)
- summary_jobs pending 누적 → Phase 3에서 TTL/정리 로직 구현 예정 (이번 Phase 범위 밖)

### 5. 통합 시 충돌
- pdfIndexing.ts 수정 → index.ts의 export에 영향 없음 (동일 함수명 유지)
- firestore.ts 타입 추가 → 기존 타입에 영향 없음 (순수 추가)
- firestore.rules 추가 → 기존 규칙에 영향 없음 (새 match 블록 추가)

## 수정/생성 대상 파일
1. `functions/package.json` — pdf-parse 의존성 추가
2. `functions/src/pdfIndexing.ts` — pdf-parse 도입, 임베딩 병렬화, summary_jobs 생성
3. `nextapp/src/types/firestore.ts` — InsuranceSummary, SummaryJob 타입 + COLLECTIONS 추가
4. `firestore.rules` — insurance_summaries, summary_jobs 규칙 추가