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

## 작업 내용
InsuWiki 보험약관 PDF 인덱싱 파이프라인(pdfIndexing.ts)을 리팩토링하고 3단계 요약 파이프라인의 기반 스키마를 구축.

### Phase 1: pdf-parse 도입 + 임베딩 병렬화
- Gemini API 텍스트 추출 → pdf-parse 로컬 텍스트 추출로 교체 (비용 $0, 속도 향상)
- 페이지 단위 `[PAGE n]` 마커 자동 삽입
- 임베딩 순차 처리 → 10개 단위 배치 `Promise.all` 병렬 처리
- 대용량 PDF(500p 초과) 경고 로그 추가 (분할 처리는 Phase 3 예정)
- 기존 Gemini 용어 추출 코드 유지

### Phase 2: InsuranceSummary 스키마 + summary_jobs 생성
- `InsuranceSummary` 타입 정의 (Level 1/2/3 요약)
- `SummaryJob` 타입 정의 (요약 작업 큐)
- `InsuranceChunk`에 `sectionId?` 필드 추가 (Level 2 연결용)
- `COLLECTIONS` 상수에 `INSURANCE_SUMMARIES`, `SUMMARY_JOBS` 추가
- Firestore 규칙: `insurance_summaries` (인증 사용자 읽기), `summary_jobs` (관리자만 읽기)
- pdfIndexing 완료 시 `summary_jobs` 문서 자동 생성 (status: pending)

## 생성/수정 파일 목록

| 파일 | 변경 유형 | 변경 내용 |
|------|----------|-----------|
| `functions/package.json` | 수정 | `pdf-parse: ^1.1.1` 의존성 추가 |
| `functions/src/pdfIndexing.ts` | 수정 | pdf-parse 도입, 임베딩 병렬화, summary_jobs 생성 |
| `nextapp/src/types/firestore.ts` | 수정 | InsuranceSummary, SummaryJob 타입, sectionId 필드, COLLECTIONS 추가 |
| `firestore.rules` | 수정 | insurance_summaries, summary_jobs 규칙 추가 |
| `teams/dev1/plan-task-128.1.md` | 생성 | 작업 계획서 |

## 검토한 대안과 기각 사유
- **pdfjs-dist vs pdf-parse**: pdf-parse 채택 — 텍스트 추출 특화, 번들 경량
- **임베딩 전체 Promise.all vs 배치**: 10개 배치 절충 — API rate limit 방지
- **summary_jobs를 jobs 컬렉션 통합 vs 별도**: 별도 분리 — jobs는 TTL 10분 자동 삭제, summary_jobs는 장기 보존 필요

## 테스트 결과
- TypeScript 빌드: 초기 에러 3건 (pdf-parse import 방식, 타입 명시) → 수정 후 빌드 통과
- 코드 리뷰: 기존 용어 추출/메타데이터 upsert 코드 정상 유지 확인
- Firestore 규칙: insurance_summaries, summary_jobs 규칙 정상 추가 확인
- 타입 파일: InsuranceSummary, SummaryJob, sectionId 정상 추가 확인

## 버그 유무
- 발견된 버그 없음

## 셀프 QC

### 1. 이 변경이 다른 파일에 영향을 미치는가?
- pdfIndexing.ts: export 함수명(`onPdfIndexingJob`)은 동일하므로 index.ts에 영향 없음. 새 컬렉션(`summary_jobs`)에 쓰기 추가되었으나 Admin SDK 사용으로 클라이언트에 영향 없음.
- firestore.ts: 순수 타입 추가만으로 기존 코드에 영향 없음. InsuranceChunk에 optional 필드 추가이므로 기존 코드 호환성 유지.
- firestore.rules: 새 match 블록 추가만으로 기존 규칙에 영향 없음.

### 2. 이 로직의 엣지 케이스는 무엇인가?
- pdf-parse가 특정 형식 PDF를 파싱 못할 경우 → 전체 try/catch로 Job status: failed 기록됨
- `\n{3,}` 분할이 실제 페이지 경계와 불일치할 수 있음 → [PAGE n] 마커가 대략적 위치 표시, 정확한 원문 참조는 Level 3에서 별도 처리
- 재인덱싱 시 summary_jobs가 `merge: false`로 덮어쓰기됨 → 의도된 동작 (이전 pending 상태 초기화)

### 3. 이 구현이 작업 지시와 정확히 일치하는가?
- Phase 1 체크리스트: pdf-parse 추가, 텍스트 추출 교체, 임베딩 병렬화, 대용량 경고, 용어 추출 유지, 빌드 확인 → 모두 완료
- Phase 2 체크리스트: InsuranceSummary 타입, Firestore 규칙, sectionId 필드, summary_jobs 스키마, pdfIndexing 완료 시 summary_jobs 생성, 빌드 확인 → 모두 완료

### 4. 에러 처리와 보안은 확인했는가?
- 에러 처리: 최상위 try/catch로 Job status: failed 기록. 용어 추출 실패는 warn으로 계속 진행. pdf-parse 실패도 동일하게 catch.
- 보안: Firestore 규칙에서 insurance_summaries는 인증 사용자만 읽기, summary_jobs는 관리자만 읽기. 쓰기는 모두 서버(Admin SDK) 전용으로 클라이언트 직접 조작 차단.

### 5. 테스트가 모든 경로를 커버하는가?
- TypeScript 빌드 통과로 타입 안전성 확인. 런타임 테스트는 실제 PDF 파일과 Firebase 환경이 필요하므로 E2E 테스트는 배포 후 진행 예정.

## 팀장 검토 결과

- **불칸(백엔드)**: 1차 검토 통과. pdf-parse 도입, 임베딩 병렬화, summary_jobs 생성 모두 스펙 대로 구현. 초기 빌드 에러(import 방식)를 아르고스가 발견하여 수정됨.
- **이리스(프론트엔드)**: 1차 검토 통과, 수정 사항 없음. InsuranceSummary, SummaryJob 타입 및 COLLECTIONS 추가 정상.
- **아테나(UX/UI)**: 1차 검토 통과, 수정 사항 없음. Firestore 규칙 정상 추가.
- **아르고스(테스터)**: 빌드 에러 3건 발견 및 수정 완료. import 방식(`import * as pdfParse`), 타입 명시(`pdfParse.Options`, `Promise<string>`) 수정으로 빌드 통과 확인.

## 비고
- `@types/pdf-parse` 패키지가 npm install 시 함께 설치되어야 함 (아르고스가 설치 완료)
- Phase 3(Claude Code 요약 파이프라인)은 2팀에서 별도 진행 예정
- Phase 4(프론트엔드 UI)는 Phase 3 완료 후 진행