# task-2065 완료 보고서: InsuRo 일반 사용자 API 키 등록 필요 여부 심층 분석

## S - Situation
InsuRo 베타 오픈 전, 관리자(제이회장님)가 서버 .env에 설정한 API 키와 별도로 일반 사용자(보험 설계사)가 개별 API 키를 등록해야 하는 기능이 있는지 전수 조사가 필요하다.

## C - Complication
서버에 6종 이상의 API 키(Supabase, PostHog, Naver, VAPID, Google Drive, AI)가 설정되어 있으나, 어떤 키가 관리자 전용이고 어떤 키가 사용자 개별 등록이 필요한지 명확히 분류되지 않았다. 베타 사용자 온보딩 시 불필요한 키 등록 요구는 이탈 원인이 된다.

## Q - Question
일반 사용자(보험 설계사)가 직접 등록해야 하는 API 키는 무엇이며, 각각 어디서 어떻게 등록하는가?

## A - Answer
전수 조사 결과, **사용자 개별 등록 필요 3종**, **관리자 전용 6종**, **가이드-구현 불일치 1건**을 식별했다. 사용자 개별 키는 `/settings` > "API 키" 탭에서 등록하며, 나머지 키(AI, Google Drive, Supabase, PostHog, VAPID)는 서버 .env로 관리되어 사용자 개입 불필요.

---

## 분석 결과

### 1. 관리자 전용 (서버 .env 설정 — 사용자 개별 등록 불필요) — 6종

**1-1. AI API 키 (Anthropic/Gemini)**
- 분류: **관리자 전용**
- 근거: `server/anu_provider.py:61` — `ANU_INTERNAL_API_KEY` 환경변수, `supabase/functions/_shared/ai-provider.ts:55-59` — `Deno.env.get()`으로 Edge Function 내부에서만 사용
- 설명: AI API 호출은 서버(Edge Function + Python)에서 처리. 사용자 키 불필요

**1-2. Google Drive OAuth**
- 분류: **관리자 전용**
- 근거: `server/gdrive.py:26-40` — `INSURO_GOOGLE_CLIENT_ID/SECRET/REFRESH_TOKEN` 서버 환경변수, `server/scripts/get_refresh_token.py` — 관리자 1회 실행으로 토큰 발급
- 설명: 단일 서비스 계정 구조. 사용자별 Google Drive 연동 없음

**1-3. Supabase (service_role + anon key)**
- 분류: **관리자 전용**
- 근거: 서버 `INSURO_NEW_SERVICE_ROLE_KEY`, 프론트 `VITE_SUPABASE_PUBLISHABLE_KEY` (anon key, 빌드 타임 고정)
- 설명: 표준 BFF 패턴. 사용자는 Supabase Auth JWT로 인증

**1-4. PostHog 분석**
- 분류: **관리자 전용**
- 근거: `server/analytics.py:91` — 서버 환경변수, `src/components/PostHogProvider.tsx:12` — `VITE_POSTHOG_API_KEY` 빌드 타임
- 설명: 단일 프로젝트 키. 사용자 입력 불필요

**1-5. VAPID Push 키**
- 분류: **관리자 전용**
- 근거: `supabase/functions/send-push/index.ts:105-106` — Edge Function 환경변수. 공개키만 클라이언트에 노출
- 설명: 서비스 전체 단일 키 쌍. 사용자 등록 불필요

**1-6. 네이버 API (서버 공용)**
- 분류: **관리자 전용 (서버 기본 키)**
- 근거: `server/main.py:765-766` — `os.environ.get("NAVER_CLIENT_ID")`. 키 없으면 500 에러 반환
- 설명: 서버 기본 네이버 API 키는 관리자가 설정. 다만 사용자 개별 키 등록도 가능(아래 2-1 참조)

### 2. 사용자 개별 등록 필요 — 3종

**2-1. 네이버 Search API (사용자 개인 키)**
- 분류: **선택적 (사용자 개별 키 등록 가능)**
- 위치: `/settings` > API 키 탭 (`Settings.tsx:619-629`)
- 입력 필드: Client ID + Client Secret
- 저장: `supabase.from("user_naver_keys")` 테이블
- 설명: 서버 기본 키가 있으므로 미등록 시 서버 키 fallback. 개인 키 등록 시 개인 할당량 사용

**2-2. Threads API Access Token**
- 분류: **사용자 개별 필요**
- 위치: `/settings` > API 키 탭 (`Settings.tsx:658-667`)
- 입력 필드: Access Token (password 타입)
- 저장: `supabase.from("user_api_keys")` 테이블, provider="threads"
- 설명: 스레드 자동 업로드 기능 사용 시 필수. 미등록 시 해당 기능 비활성

**2-3. Instagram API Access Token**
- 분류: **사용자 개별 필요**
- 위치: `/settings` > API 키 탭 (`Settings.tsx:701-711`)
- 입력 필드: Access Token (password 타입)
- 저장: `supabase.from("user_api_keys")` 테이블, provider="instagram"
- 설명: 인스타그램 자동 업로드 기능 사용 시 필수. 미등록 시 해당 기능 비활성

### 3. 가이드-구현 불일치 — 1건

**3-1. Google Gemini API 키**
- 상태: **ApiGuide 문서에는 등록 안내 있으나, Settings UI에 입력 폼 미구현**
- 근거: `ApiGuide.tsx:153` — "AI API 키" 섹션에서 Gemini 키 등록을 안내하나, `Settings.tsx`의 API 키 탭에 gemini/openai provider 입력 필드 없음
- 판단: 가이드 문서가 오래되었거나 기능 미완성. 현재 AI API는 서버 키로 처리

---

## 종합 분류표

| API 키 | 분류 | 등록 위치 | 비고 |
|--------|------|-----------|------|
| AI (Anthropic/Gemini) | 관리자 전용 | 서버 .env | Edge Function + Python 서버 |
| Google Drive OAuth | 관리자 전용 | 서버 .env | 단일 서비스 계정 |
| Supabase | 관리자 전용 | 서버 .env + 빌드 | service_role + anon key |
| PostHog | 관리자 전용 | 서버 .env + 빌드 | 단일 프로젝트 키 |
| VAPID Push | 관리자 전용 | 서버 .env | 서비스 전체 단일 키 |
| 네이버 API (서버) | 관리자 전용 | 서버 .env | 기본 키 |
| 네이버 API (사용자) | 선택적 | /settings > API 키 | 개인 키 등록 시 개인 할당량 |
| Threads API | 사용자 개별 | /settings > API 키 | 자동 업로드 시 필수 |
| Instagram API | 사용자 개별 | /settings > API 키 | 자동 업로드 시 필수 |
| Gemini (사용자) | 미구현 | 가이드만 존재 | 가이드-구현 불일치 |

---

## 발견 이슈 및 해결

### 범위 외 미해결 (1건)
1. **ApiGuide에서 Gemini 키 등록을 안내하나 Settings UI 미구현** — 범위 외 사유: 본 작업은 분석만 수행. UI 구현은 별도 작업 필요. 가이드 문서 업데이트 또는 Gemini 키 입력 UI 추가 중 택1 필요

---

## 셀프 QC

- [x] 1. 다른 파일에 영향: 없음 (분석만 수행, 코드 수정 없음)
- [x] 2. 엣지 케이스: 보험사 전산 직접 접속 코드 미발견 확인
- [x] 3. 작업 지시와 일치: 관리자 전용/사용자 개별/선택적 분류 완료
- [x] 4. 에러 처리/보안: 해당 없음 (분석만)
- [x] 5. 테스트 커버리지: 해당 없음 (분석만)
- [x] 6. 발견 이슈 해결: 범위 외 1건 사유 명시
- [x] 7. 코드 아키텍처 원칙: 해당 없음 (분석만)
- [x] 8. 인터페이스 변경: 해당 없음 (분석만)
- [x] 13. L1 스모크테스트: 해당 없음 (코드 수정 없음)

---

## L1 스모크테스트 결과

- 서버 재시작: 해당없음 (코드 수정 없는 분석 작업)
- API 응답 확인: 해당없음
- 스크린샷: 해당없음

---

## 모델 사용 기록

- 팀원: 불칸(Vulcan) / 작업: 서버/백엔드 API 키 전수 조사 / 모델: sonnet / 정당성: 분석/리서치 작업
- 팀원: 이리스(Iris) / 작업: 프론트엔드 설정 페이지 전수 조사 / 모델: sonnet / 정당성: 분석/리서치 작업

---

## 완료 시그니처 검증

- [x] 보고서에 "관리자 전용" 분류 결과: 6종 (AI, Google Drive, Supabase, PostHog, VAPID, 네이버 서버키)
- [x] 보고서에 "사용자 개별" 분류 결과: 2종 (Threads, Instagram)
- [x] 보고서에 "선택적" 분류 결과: 1종 (네이버 사용자키)

## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회