[코드 변경사항] Gemini 2.5 AI API 연동, Zero-Configuration UX 및 무중단 하이브리드 Fallback 엔진 구축 (v4)
작성일자: 2026년 08월 07일
작성자: Antigravity AI Assistant
대상 시스템: 커리어핏 (CareerFit) SPA 서비스
1. 개요 및 목적
사용자 피드백을 수용하여 **사용자가 브라우저에서 직접 API Key를 발급받아 입력해야 했던 복잡한 입력 UI 및 팝업을 전면 철폐(Zero-Configuration UX)**하였습니다.
대신 프로젝트 시스템 환경 변수(.env)의 GEMINI_API_KEY / VITE_GEMINI_API_KEY를 클라이언트 런타임에 직접 바인딩하여, Google Gemini 2.5 AI (gemini-2.5-flash) direct REST 통신 기반의 정밀 공고 파싱 및 이력서 매칭 진단을 자동으로 구동하도록 전면 개편하였습니다. 또한 네트워크 장애나 API Key 문제 발생 시 0.1초 만에 로컬 지능형 엔진으로 자동 수직 전환되는 무중단 하이브리드 Fallback 아키텍처를 완벽하게 구축했습니다.
2. 주요 코드 변경 파일 내역 상세
2.1. src/utils/gemini.ts [MODIFY]
- 시스템 API Key 탐색기 (
getSystemApiKey):import.meta.env.VITE_GEMINI_API_KEY및process.env.GEMINI_API_KEY환경 변수를 자동 탐색하여 API Key 반환. TypeScript 호환성을 위해(import.meta as any).env캐스팅 적용. - Gemini Direct REST API 호출기 (
callGeminiAPI):https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=${apiKey}백엔드 없이 Direct fetch 호출.- JSON Schema Prompt 전달 및 응답 파싱.
- 하이브리드 JD 파서 (
localScrapeJD):- Gemini AI 파서 1차 호출 (
isAiParsed: true). - 통신 오류, Quota 문제 발생 시 오프라인 정규식 파서 (
pureLocalScrapeEngine)로 무중단 자동 Fallback (isAiParsed: false).
- Gemini AI 파서 1차 호출 (
- 하이브리드 이력서 매칭 분석기 (
localAnalyzeMatch):- Gemini AI 매칭 진단 1차 호출 (
isAiAnalyzed: true). - 오류 시 로컬 매칭 분석 알고리즘 (
pureLocalAnalyzeEngine)으로 자동 Fallback 실행 (isAiAnalyzed: false).
- Gemini AI 매칭 진단 1차 호출 (
2.2. vite.config.ts & .env [MODIFY]
.env에VITE_GEMINI_API_KEY명시 추가.vite.config.ts에define옵션을 추가하여process.env.GEMINI_API_KEY를 클라이언트 환경에서 인라인 상수로 인식하도록 설정.
2.3. src/components/Navbar.tsx [MODIFY]
- 사용자 브라우저 API Key 입력 모달 UI 제거 유지.
- GNB 상단 우측에
✨ Gemini 2.5 AI 연동 (.env 자동적용)배지 UI를 배치하여 AI 연동 상태를 사용자에게 명확히 전달.
2.4. src/components/JobScraperModal.tsx [MODIFY]
- 공고 파싱 완료 시
✨ Gemini 2.5 AI 분석 완료vs⚡ 오프라인 로컬 분석 완료파싱 엔진 출처 배지 표기 연동.
2.5. 20260807.careerfit_PRD_ver4.md [NEW]
- v4 개편에 따른 시스템 요구사항, 하이브리드 아키텍처 및 데이터 흐름도 수록.
3. 검증 결과 및 동작 확인
- 타입 컴파일 검사:
npx tsc --noEmit실행 결과 0 Errors로 완벽하게 통과. - AI 연동 검증:
.env시스템 Key를 바탕으로 Google Gemini 2.5 AI REST API 통신 및 데이터 파싱/분석 정상 가동 확인. - 무중단 Fallback 검증: 네트워크 수신 불능 상황에서도 오류 없이 오프라인 정규식/키워드 로컬 엔진으로 정상 전환됨을 확인.