# task-389.1 완료 보고서: NotebookLM 통합 — 팟캐스트 오디오 자동생성 파이프라인

## 작업 요약
NotebookLM CLI(`nlm`)를 설치하고, ThreadAuto 카드뉴스 콘텐츠에서 팟캐스트 스타일 오디오를 자동 생성하는 래퍼 모듈을 TDD 방식으로 구현했습니다.

## 완료 항목

### Phase 1: 도구 설치
- `notebooklm-cli` 0.1.12 (PyPI, 옵션 C) 설치 완료
- `nlm` CLI 바이너리: `~/.local/bin/nlm`
- Python 모듈: `nlm.core.client` import 가능
- 의존성: httpx, pydantic, typer, websocket-client 모두 설치됨
- **인증**: 미설정 (헤드리스 서버에서 Google 로그인 필요 → AUTH_GUIDE.md에 3가지 방법 문서화)

### Phase 2: 래퍼 모듈 생성
TDD RED→GREEN→REFACTOR 사이클 수행

### Phase 3: 샘플 테스트
- **실행 불가**: 인증(Google 쿠키)이 설정되지 않아 실제 NotebookLM API 호출 불가
- 이는 태스크에서 예상한 시나리오 ("인증이 핵심 난관")

## 생성/수정 파일 목록

| 파일 | 크기 | 설명 |
|------|------|------|
| `audio/__init__.py` | 196B | 패키지 초기화, 공개 API 노출 |
| `audio/notebooklm_client.py` | 8.8KB | NotebookLMClient 래퍼, extract_text_from_slides, generate_podcast_from_slides |
| `audio/setup_check.py` | 3.8KB | 의존성 설치 상태 확인 스크립트 |
| `audio/AUTH_GUIDE.md` | 2.0KB | 헤드리스 서버 인증 가이드 (3가지 방법) |
| `audio/tests/__init__.py` | 0B | 테스트 패키지 |
| `audio/tests/test_notebooklm_client.py` | 6.7KB | 8개 단위 테스트 |

## 핵심 API 설계

**NotebookLMClient** (nlm의 NLMClient 래퍼):
- `create_notebook(title)` → notebook_id
- `add_text_source(notebook_id, text, title)` → source_id
- `generate_audio(notebook_id, language, format, length)` → artifact dict
- `poll_status(notebook_id)` → artifacts list
- `wait_for_audio(notebook_id, timeout, poll_interval)` → completed artifact or None
- `cleanup_notebook(notebook_id)` → None

**generate_podcast_from_slides(slides, topic_title, profile, language, wait, timeout)**:
- 슬라이드 JSON → 텍스트 추출 → 노트북 생성 → 소스 추가 → 오디오 생성 → 결과 반환
- 반환: `{"status": "completed|in_progress|timeout|error", ...}`

## 테스트 결과

```
8 passed in 0.13s
```

- test_nlm_cli_installed: PASS (CLI 설치 확인)
- test_extract_text_from_slides: PASS (텍스트 추출)
- test_extract_text_empty_slides: PASS (빈 입력)
- test_extract_text_various_types: PASS (다양한 슬라이드 타입)
- test_client_init_default: PASS (기본 초기화)
- test_client_init_custom_profile: PASS (커스텀 프로필)
- test_generate_podcast_from_slides_no_auth: PASS (인증 없음 에러)
- test_client_context_manager: PASS (with문)

## 인증 관련 핵심 이슈

**현재 상태**: 인증 미설정 (Google 쿠키 필요)

**해결 방법 (AUTH_GUIDE.md에 상세 기록)**:
1. **로컬에서 인증 후 쿠키 복사** (권장): 로컬 PC에서 `nlm login` → `~/.config/nlm/profiles/default/` 폴더를 서버로 scp
2. **쿠키 파일 직접 생성**: Chrome DevTools에서 NotebookLM 쿠키 추출 → `nlm login --manual --file cookies.txt`
3. **Playwright 자동화**: headless 브라우저로 Google OAuth 처리 (차단 위험 있음)

**다음 단계**: 제이회장님이 로컬 PC에서 `nlm login` 실행 후 쿠키 파일을 서버로 복사하면 Phase 3 샘플 테스트 진행 가능

## 발견한 제한사항

1. **오디오 다운로드 미지원**: nlm CLI는 오디오 생성 + 상태 폴링만 지원. 생성된 오디오 파일의 로컬 다운로드 기능은 없음 (NotebookLM 웹에서 접근 필요)
2. **한국어 지원**: `--language ko` 옵션 있으나, 실제 한국어 소스 → 한국어 팟캐스트 생성 여부는 인증 후 테스트 필요
3. **쿠키 만료**: Google 쿠키 유효 기간 약 2주~1개월. 주기적 재인증 필요

## QC 검증 결과

```json
{
  "overall": "PASS (file_check 제외)",
  "test_runner": "PASS (8 passed)",
  "tdd_check": "PASS",
  "pyright_check": "PASS (메인 모듈 0 errors, 테스트 파일 WARN만)",
  "style_check": "PASS (black + isort)",
  "data_integrity": "PASS"
}
```

WARN: 테스트 파일의 `from audio.notebooklm_client import ...` pyright resolution 경고 (런타임 정상 동작, pytest 환경에서 정상 import)

## 머지 판단
- **머지 필요**: Yes
- **브랜치**: task/task-389.1-dev2
- **워크트리 경로**: /home/jay/projects/ThreadAuto/.worktrees/task-389.1-dev2
- **머지 의견**: 새 `audio/` 디렉토리만 추가, 기존 코드 무변경. 테스트 8/8 통과, pyright 0 에러, black/isort 통과. 단, 실제 API 호출은 인증 설정 후 가능하므로 인증 설정 후 E2E 테스트 권장.