# task-136.1 완료 보고서

- 작업 ID: task-136.1
- 팀: dev3-team (라 팀장 + GLM-5)
- 소요 시간: 10분 2초 (2026-03-03 00:02 ~ 00:12)
- 수정 대상: `/home/jay/projects/insuwiki/functions/src/crawlYoutubeChannels.ts`

---

## 작업 요약

InsuWiki YouTube 파이프라인 (`crawlYoutubeChannels.ts`)의 잔여 버그 4건을 수정했습니다.

---

## GLM 결과 평가 (팀장 검토)

### Bug 4: secrets 배열 추가 (1차 검토 통과, 수정 사항 없음)
- 319-325행: `DRIVE_CLIENT_ID`, `DRIVE_CLIENT_SECRET`, `DRIVE_REFRESH_TOKEN` 3개가 secrets 배열에 추가됨.
- 배포 시 Cloud Functions가 Secret Manager에서 올바르게 주입할 수 있도록 됨.

### Bug 3: 환경변수명 fallback (1차 검토 통과, 수정 사항 없음)
- 348-365행: Drive OAuth2 환경변수 (`driveClientId`, `driveClientSecret`, `driveRefreshToken`)를 별도 변수로 분리.
- `hasDriveCredentials` 플래그 도입 — Drive 자격증명이 없어도 파이프라인이 계속 실행되는 graceful degradation 구현.
- Drive 클라이언트 생성 및 Drive 업로드 모두 `hasDriveCredentials/drive` 조건으로 보호됨.
- 개선 제안: `GOOGLE_DRIVE_ROOT_FOLDER_ID`도 Drive 관련 자격증명과 묶어서 `hasDriveCredentials` 내에 포함하는 것을 고려할 수 있으나, 현재 구조도 기능적으로 올바름.

### Bug 2: conflictDetail undefined (1차 검토 통과, 수정 사항 없음)
- 512행: `let conflictDetail = ''` → `const conflictDetail: string | null = null;` 변경.
- Firestore document 저장 시 `undefined` 직접 전달 제거 → `if (conflictDetail !== null)` 조건부 필드 추가 패턴 적용.
- Firestore Admin SDK에서 `undefined` 값은 에러를 유발하지만 `null`은 올바르게 처리됨.

### Bug 1: findNearest 에러 처리 (1차 검토 통과, 수정 사항 없음)
- catch 블록에서 `vecErr?.message || vecErr` 패턴으로 에러 메시지를 명확하게 출력.
- `// 기본값 유지 (conflictsWithPolicy = false, conflictDetail = null)` 주석으로 의도 명확화.
- `.where().findNearest()` 체이닝 구조는 유지됨 — TypeScript 빌드 통과로 타입 안정성 확인.

---

## 생성 파일 목록

- 수정: `/home/jay/projects/insuwiki/functions/src/crawlYoutubeChannels.ts`
  - 변경 사유: Bug 1~4 수정 (secrets 배열, 환경변수 검증, conflictDetail null 처리, findNearest 에러 로깅 개선)
- 신규: `/home/jay/projects/insuwiki/plans/plan-task-136.1.md` (작업 계획서)
- 신규: `/home/jay/projects/insuwiki/memory/reports/task-136.1.md` (이 보고서)

---

## 테스트 결과

### TypeScript 빌드 (functions 디렉토리)
```
Exit: 0 (오류 없음)
```

### GLM 체크리스트 결과
```json
{
  "all_passed": true,
  "checks": {
    "path_validation": { "passed": true },
    "file_exists": { "passed": true },
    "typescript_build": { "passed": true, "details": "tsc --noEmit passed" },
    "security_scan": { "passed": true },
    "api_completeness": { "passed": true },
    "import_validation": { "passed": true }
  }
}
```

※ 전체 프로젝트 대상 체크리스트 실행 시 nextapp 및 기타 기존 파일들의 TypeScript 오류가 감지되었으나, 이는 이번 작업 범위 외의 기존 오류이며 수정 대상인 functions 디렉토리는 완전히 통과.

---

## 보고서 작성 전 셀프 QC

### 1. 이 변경이 다른 파일에 영향을 미치는가?
`crawlYoutubeChannels.ts`만 수정했으며, `functions/src/index.ts`에서 export를 통해 참조되나 함수 시그니처 변경 없음. 영향 없음.

### 2. 이 로직의 엣지 케이스는 무엇인가?
- Drive 자격증명이 일부만 있는 경우 (`hasDriveCredentials = false`로 스킵 처리됨)
- `conflictDetail`이 null이 아닌 경우는 현재 코드에서 발생하지 않음 (Phase 2 구현 예정)
- `findNearest`가 벡터 인덱스 미설정으로 실패해도 catch로 처리됨

### 3. 이 구현이 작업 지시와 정확히 일치하는가?
작업 지시의 4개 버그 항목(findNearest 에러 처리, conflictDetail undefined, 환경변수명 fallback, secrets 배열 추가) 모두 수정됨.

### 4. 에러 처리와 보안은 확인했는가?
- 환경변수 검증 블록이 강화됨
- Drive OAuth 자격증명이 없어도 파이프라인이 안전하게 계속 실행됨
- `conflictDetail` undefined→null로 Firestore 저장 에러 방지
- secrets 배열에 민감 정보 키 등록 완료

### 5. 테스트가 모든 경로를 커버하는가?
TypeScript 빌드 통과 + GLM 체크리스트 `all_passed: true`. 런타임 테스트는 Cloud Functions 배포 환경 필요하므로 제한적이나 정적 분석은 완전히 통과.

---

## 검토한 대안과 기각 사유

### 대안 1: findNearest를 CollectionReference에서만 호출하고 where 필터링을 코드로 처리
- 기각 사유: `.where().findNearest()` 체이닝이 TypeScript 빌드를 통과했으므로 SDK에서 지원됨. 불필요한 코드 변경을 줄임.

### 대안 2: conflictDetail을 항상 string으로 유지하고 빈 문자열일 때 저장
- 기각 사유: 불필요한 빈 문자열 필드가 Firestore document에 저장됨. null 조건부 패턴이 더 깔끔함.

### 대안 3: Drive 자격증명 없을 시 함수 전체 early return
- 기각 사유: Embedding, Firestore 저장 등 Drive와 무관한 핵심 기능들이 있으므로 Drive 없이도 실행되어야 함.