# 계획서: task-125.1 InsuWiki 어드민 약관 업로드→인덱싱 파이프라인 연결 + 버그수정

## 작업 요약
어드민 PDF 약관 업로드 API(`drive-upload/route.ts`)에서 Google Drive 업로드 + `insurance_metadata` upsert 후, Firestore `jobs` 컬렉션에 `type: 'index_pdf'` 문서를 생성하여 `onPdfIndexingJob` Cloud Function이 자동 트리거되도록 연결.

## 현황 분석
- `drive-upload/route.ts`: PDF 업로드 + metadata 저장까지만 수행. 인덱싱 파이프라인 미연결.
- `pdfIndexing.ts` (Cloud Function): `jobs/{jobId}` 생성 시 `type==='index_pdf'` && `status==='pending'` 조건으로 트리거.
- `types/firestore.ts`: `Job.type`이 `'pdf_query'`만 선언. `'index_pdf'` 누락 (타입 버그).

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

### ST-1. 백엔드 — 불칸
- `drive-upload/route.ts` 수정: 성공 업로드 건마다 `jobs` 컬렉션에 index_pdf 문서 생성
- Job 문서 필드: `type`, `status`, `driveFileId`, `companyId`, `companyName`, `productId`, `productName`, `category`, `effectiveDate`, `createdAt`, `updatedAt`
- 응답에 `jobId` 추가하여 프론트에서 인덱싱 상태 폴링 가능하도록 함

### ST-2. 백엔드 — 불칸
- `types/firestore.ts` 수정: `Job.type`에 `'index_pdf'` 유니온 추가

### ST-3. 테스터 — 아르고스
- 변경된 코드의 로직 검증 (Cloud Function 트리거 조건 매칭, 필드 누락 여부)
- 엣지 케이스: 파일명 형식 오류 시 job 미생성 확인, 업로드 실패 시 job 미생성 확인

## 실행 순서
1. ST-1 + ST-2 병렬 실행 (둘 다 불칸, 독립적)
2. ST-3 검증 (ST-1, ST-2 완료 후)

## 검토한 대안과 기각 사유
- **대안 A**: Cloud Storage 트리거 사용 → 기각. 프로젝트가 Firestore 기반 job 큐로 통일된 아키텍처 사용 중.
- **대안 B**: 별도 admin API 엔드포인트에서 인덱싱 수동 트리거 → 기각. 업로드와 인덱싱을 자동 연결하는 것이 UX상 우월.

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

### 1. 비정상 입력/상태
- 파일명 형식 오류 → `parseFileName` 실패 → job 미생성 (기존 로직으로 skip, 정상)
- Drive 업로드 실패 → catch 블록에서 error 반환 → job 미생성 (정상)
- `driveFileId`가 null → `uploadRes.data.id!`로 non-null assertion 사용 중. Drive API 실패 시 이전 catch에서 잡힘.

### 2. 동시성/경쟁 조건
- 같은 파일 동시 업로드 → 기존 코드에서 동일 파일명 삭제 후 재업로드. job은 각각 생성되지만, Cloud Function이 idempotent하게 metadata upsert하므로 최종 상태 일관성 유지.
- Firestore 쓰기 충돌 → `.add()`로 자동 ID 생성하므로 충돌 없음.

### 3. 비정상 종료/타임아웃
- job 생성 후 Cloud Function 타임아웃(540s) → job status가 'indexing'에 멈춤. 재처리 메커니즘 미구현이지만, 현재 스코프 외.
- route 응답 전 서버 종료 → Drive에 파일 업로드 완료되었으나 job 미생성 가능. insurance_metadata는 기록됨. 수동 재업로드로 복구.

### 4. 스테일 데이터
- job 문서에 `expireAt` 미설정 → `index_pdf` job은 쿼리 job과 달리 TTL 불필요 (1회성 트리거). 해당 없음.
- 같은 상품 재업로드 시 기존 chunks 유지 → Cloud Function이 chunk ID를 `companyId_productId_chunk_{i}`로 덮어쓰므로 stale chunk 잔존 가능 (chunks 수 감소 시). 현재 스코프 외.

### 5. 통합 시 충돌
- `drive-upload/route.ts`만 수정. 다른 라우트/모듈에 영향 없음.
- `types/firestore.ts` 타입 확장은 기존 코드에 breaking change 없음 (유니온 추가).