# 계획서: task-129.1 — InsuWiki Phase 3: Claude Code 요약 파이프라인

## 목표
PDF 인덱싱 완료 후 생성되는 summary_jobs를 감지하여, Claude Code 팀봇이 Level 2(섹션별) + Level 1(핵심) 요약을 자동 생성하고 Firestore에 저장하는 파이프라인 구축

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

### ST-1. 요약 파이프라인 CLI 스크립트 (토르/백엔드)
- `scripts/summary-pipeline.ts` 작성
- 서브커맨드: list / read / save / complete
  - `list`: pending summary_jobs 조회 → JSON 출력
  - `read <jobId>`: insurance_chunks 읽기 → 섹션별 정리된 텍스트 파일 출력
  - `save <jobId> --input <file>`: Level 1+2 요약 JSON 입력 → insurance_summaries 저장
  - `complete <jobId>`: summary_jobs status → complete 업데이트
- Firebase Admin SDK + dotenv 패턴 (기존 scripts/ 패턴 따름)
- 섹션 감지: "제n관", "제n장", "제n절" 패턴으로 청크 그룹핑

### ST-2. 어드민 요약 API (토르/백엔드)
- `GET /api/admin/summary-jobs` - 요약 작업 목록 조회 (status 필터링)
- `POST /api/admin/summary-generate` - 요약 결과 저장 API
- 기존 인증 패턴 적용 (Bearer token + ADMIN_EMAILS)

### ST-3. 요약 프롬프트 설계 (미미르/UX)
- Level 2 프롬프트: 보험약관 섹션별 요약 지시
- Level 1 프롬프트: 전체 상품 핵심 요약 지시
- 디스패치 프롬프트: 아누 → 팀봇 요약 작업 지시 템플릿

### ST-4. 통합 테스트 (헤임달/테스터)
- 파이프라인 CLI 각 서브커맨드 단위 테스트
- API 라우트 요청/응답 검증
- 에러 케이스 테스트 (없는 jobId, 빈 chunks 등)

## 실행 순서
1. ST-1 (토르) + ST-3 (미미르) 병렬 실행
2. ST-2 (토르) 순차 (ST-1 완료 후, 동일 타입 시스템 공유)
3. ST-4 (헤임달) 최종 검증

## 검토한 대안 및 기각 사유
1. **Cloud Function으로 자동 요약**: Gemini Flash API 비용 발생 ($3-7/월) → Claude Code 팀봇 무비용 방식 채택
2. **API 기반 실시간 요약**: 응답 시간 불확실, 타임아웃 위험 → 비동기 배치(CLI) 방식 채택
3. **단일 스크립트 (all-in-one)**: 디버깅 어려움 → 서브커맨드 분리로 단계별 실행 가능하게 설계

## 생성/수정 대상 파일
- `scripts/summary-pipeline.ts` (신규) — CLI 파이프라인 스크립트
- `nextapp/src/app/api/admin/summary-jobs/route.ts` (신규) — 요약 작업 API
- `nextapp/src/app/api/admin/summary-generate/route.ts` (신규) — 요약 저장 API
- `scripts/prompts/summary-prompts.ts` (신규) — 프롬프트 템플릿

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

### 1. 비정상 입력/상태
- 대응: summary_jobs에 productId가 없거나 chunks가 0개인 경우 → status: 'failed' + error 메시지 기록
- 대응: JSON 파일 형식이 잘못된 경우 → 파싱 에러 캐치 후 명확한 에러 메시지 출력
- 대응: insurance_chunks가 삭제된 경우 → "No chunks found" 에러로 job 실패 처리

### 2. 동시성/경쟁 조건
- 대응: 같은 summary_job을 두 팀봇이 동시 처리 → status를 'processing'으로 먼저 변경하는 쪽만 진행 (conditional update)
- 대응: 재인덱싱 중 요약 실행 → read 시점의 chunks 스냅샷 사용, 불일치 시 재실행 안내

### 3. 비정상 종료/타임아웃
- 대응: save 중 프로세스 사망 → status가 'processing'에 남음, TTL 정책으로 1시간 후 자동 pending 복귀
- 대응: 부분 저장된 summaries → save 시 기존 summaries 삭제 후 전체 재작성 (idempotent)

### 4. 스테일 데이터
- 대응: 오래된 pending jobs → list 시 createdAt 표시로 판단 가능, 7일 초과 pending은 경고
- 해당 없음: 캐시 사용 안 함 (Firestore 직접 읽기)

### 5. 통합 시 충돌
- 대응: Phase 4 프론트엔드와 insurance_summaries 스키마 일치 필요 → InsuranceSummary 타입 이미 Phase 2에서 정의됨
- 대응: 기존 pdfIndexing.ts 수정 없음 (summary_jobs 생성은 이미 구현됨)
- 대응: firestore.rules 수정 필요 없음 (insurance_summaries 규칙 이미 존재)