대한민국 국가자격증 통합 분석 및 AI 경력 경로 추천 시스템
CertFinder는 대한민국 1,101개 국가 기술·전문 자격증 데이터를 실시간으로 분석해, 사용자에게 맞는 자격증과 직무 정보를 제공하는 웹 플랫폼입니다. 합격률·난이도·취업 전망과 함께 전공 기반 AI 추천, 직무 분석, 북마크·취득 자격증 관리까지 한 곳에서 이용할 수 있습니다.
| 환경 | URL |
|---|---|
| 서비스 | https://www.certfinder.cloud |
| 백엔드 API | https://api.certfinder.cloud |
| 헬스 체크 | https://api.certfinder.cloud/health |
- 검색·필터: 키워드, 분야(main_field), 자격 유형, 시행기관, 합격률 유무 등으로 필터링
- 페이지네이션: 페이지당 20개, URL
?page=반영으로 뒤로가기 시 페이지 유지 - 북마크: 관심 자격증 저장 (로그인 시)
- 취득 자격증 제외: 로그인 사용자 — “취득 자격증 제외” 토글로 이미 취득한 항목 숨기기, 카드에 “취득” 뱃지 표시
- 상세 페이지: 연도/회차별 합격률·난이도, Recharts 시각화, 연관 직무
- 시험 일정: HRDK 공공데이터 API 연동 — 자격증 상세에서 연도별 시험 일정 탭으로 조회
- 직무 목록: 450여 개 직무의 전망·초임·역량 요약, 레이더 차트
- 페이지네이션: 페이지당 20개, 이전/다음 + 1~5 번호 버튼, URL
?q=&page=동기화 - 직무 상세: 핵심 적성·요구 역량, 취업 경로, 연관 자격증
- 전공 + 관심사 입력: 전공명·커리어 목표 기반 추천
- 알고리즘: 전공 매핑 + BM25 + pgvector(1536) + Contrastive(768) 다채널 검색 → Linear 등 융합 → (옵션) Cross-Encoder 리랭크 → 합격률·난이도·프로필 기반 보정(개인화 soft 등) → 규칙 기반 맞춤 이유 생성
- 퍼지 전공 매칭: DB에 없는 전공명은 pg_trgm 유사도로 근접 전공 사용
- 취득 자격증 제외: 로그인 시 이미 취득한 자격증은 추천 후보에서 제외(하드 제외·개인화 감점 등 설정 가능)
- 게스트: 비로그인 시 결과 3개 제한; 로그인 시 최대 15개 결과 제공
- 개발자 문서:
cert-app/backend/RAG_Indexing.md(인덱싱 가이드),cert-app/backend/RAG_LATEST_DOCS_RECORD.md(최신 문서 기준 기록)
- 인증: Supabase Auth (이메일 OTP, Google OAuth)
- 마이페이지: 닉네임·전공·학년, 북마크·취득 자격증, XP·레벨·티어. 탭 전환 후 복귀 시 5분 캐시로 즉시 표시 후 백그라운드 갱신
- 취득 자격증: DB 자격증 검색 후 등록·삭제, XP 누적
- 문의하기: Naver SMTP 이메일 발송 (백엔드 비동기 처리)
- AboutPage — 서비스 소개, 팀·기술 스택 안내
- ContactPage — 문의 폼 (이메일 발송)
- PrivacyPolicyPage — 개인정보 처리방침
- TermsOfServicePage — 이용약관
- Redis: 자격증·직무 목록/필터 옵션 10분, 상세/통계 1시간 TTL 캐시 (orjson 직렬화)
- Rate limiting: IP 기반 요청 제한
- CORS: Bearer 인증 기반,
allow_origins=["*"],allow_credentials=False
| 영역 | 기술 |
|---|---|
| Frontend | React 19, TypeScript, Vite 7, Tailwind CSS, shadcn/ui (Radix), Recharts, TanStack Query v5 |
| Backend | FastAPI, SQLAlchemy 2, Pydantic v2, orjson |
| DB | PostgreSQL (Supabase), pgvector |
| 캐시 | Redis Cloud |
| Auth | Supabase Auth (JWT, Google OAuth) |
| AI | OpenAI text-embedding-3-small (검색·추천), 선택적 GPT 계열 모델(법령 요약·벡터 인덱싱 파이프라인) |
| 배포 | Vercel (Frontend), Render (Backend) |
| 모니터링 | Vercel Speed Insights (Core Web Vitals) |
| 이메일 | Naver SMTP (문의 폼) |
CertFinder/
├── cert-app/
│ ├── backend/ # FastAPI
│ │ ├── app/
│ │ │ ├── api/ # 라우터 (certs, jobs, recommendations, ai_recommendations,
│ │ │ │ # acquired_certs, favorites, auth, contact, majors,
│ │ │ │ # exam_schedule, admin, fast_certs, ...)
│ │ │ ├── rag/ # 하이브리드 RAG 파이프라인
│ │ │ │ ├── retrieve/ # hybrid(BM25+Vector+Contrastive), RRF 융합
│ │ │ │ ├── rerank/ # Cross-Encoder 리랭킹
│ │ │ │ ├── generate/ # evidence-first 생성
│ │ │ │ ├── index/ # BM25 인덱스, vector_index
│ │ │ │ └── contrastive/ # Contrastive 768-dim 검색
│ │ │ ├── services/ # vector_service, email_service, fast_sync, law_update 등
│ │ │ ├── utils/ # ai.py, auth.py, rag_hybrid.py, xp.py, stream_producer.py
│ │ │ ├── schemas/
│ │ │ ├── crud.py, models.py, database.py, redis_client.py
│ │ │ └── scheduler.py
│ │ ├── main.py
│ │ ├── requirements.txt
│ │ ├── Dockerfile
│ │ ├── RAG_Indexing.md # RAG 인덱싱 가이드
│ │ └── scripts/ # ab_test_golden_mapping.py 등 평가 스크립트
│ └── frontend/
│ └── app/ # Vite + React
│ ├── src/
│ │ ├── pages/ # Home, CertList, CertDetail, CertCompare,
│ │ │ # Recommendation, AiRecommendation,
│ │ │ # JobList, JobDetail, MyPage,
│ │ │ # About, Contact, PrivacyPolicy, TermsOfService
│ │ ├── components/ # layout/, ui/(shadcn), common/, ErrorBoundary
│ │ ├── contexts/ # CompareContext
│ │ ├── hooks/ # useAuth, useCerts, useRecommendations
│ │ ├── lib/ # api.ts, router.tsx, supabase.ts, queryKeys.ts, utils.ts
│ │ └── types/
│ ├── vercel.json
│ ├── index.html
│ └── package.json
├── PRODUCT.md # 제품 목적·디자인 원칙
├── DESIGN.md # 디자인 시스템 전체 스펙
└── README.md
이 서비스는 Vercel(프론트) + Render(백엔드) + Supabase(Postgres) + Redis Cloud 환경에 배포된 상태로 운영되며,
일반 사용자가 로컬에서 직접 서버를 띄우는 것을 전제로 하지 않습니다. 아래 내용은 운영자용 메모입니다.
-
환경 변수 분리
- 프론트(Vercel):
VITE_API_BASE_URL,VITE_SUPABASE_URL,VITE_SUPABASE_ANON_KEY등 브라우저에서 필요한 값만 저장. - 백엔드(Render):
DATABASE_URL,REDIS_URL,SUPABASE_SERVICE_ROLE_KEY,SUPABASE_JWT_SECRET,OPENAI_API_KEY등 비밀 키는 모두 호스트 환경변수에만 저장. - DB 접속 정보나 Service Role Key, JWT Secret은 Vercel에 두지 않고 노출 시 즉시 키를 회전(재발급)한다.
- 프론트(Vercel):
-
RAG 임베딩 관리
- 자격증 요약 텍스트 임베딩은 Supabase
certificates_vectors테이블에 미리 저장되어 있으며, 필요 시 운영자가 RAG 인덱스 빌드 스크립트를 안전한 환경(로컬 관리자 또는 백엔드 워커)에서 실행해 재생성한다. - 이 작업에는
OPENAI_API_KEY와 DB 권한이 필요하므로, 일반 사용자는 수행할 수 없다.
- 자격증 요약 텍스트 임베딩은 Supabase
-
모니터링
- 백엔드
/health엔드포인트와 UptimeRobot 등으로 다운 여부를 모니터링한다. ai_recommendations모듈에서 남기는 metrics 로그(응답 시간, 후보 수, 점수 분포)를 통해 AI 추천 품질·속도를 정기적으로 점검한다.
- 백엔드
로컬 개발/실행 방법은 문서에서 제거하고, 배포된 웹 서비스를 기준으로만 안내한다.
| 구분 | 서비스 | 비고 |
|---|---|---|
| Frontend | Vercel | GitHub 연동 자동 배포, 커스텀 도메인 www.certfinder.cloud |
| Backend | Render | Root: cert-app/backend, Start: uvicorn main:app --host 0.0.0.0 --port $PORT, 커스텀 도메인 api.certfinder.cloud |
| DB | Supabase | PostgreSQL + pgvector |
| Cache | Redis Cloud | REDIS_URL |
Render Free tier는 비활동 시 슬립될 수 있음. /health로 UptimeRobot 등 모니터링 권장.
- AI 추천은 Supabase
certificates_vectors테이블의 임베딩과 통계 테이블(qualification_stats)을 기반으로 동작한다. - 운영 중에는 주기적으로 데이터 변경 여부를 확인하고, 필요 시 운영자가 RAG 인덱스를 재생성한다.
- 이 과정은 배포된 서비스의 일환으로만 수행되며, 일반 사용자는 임베딩 생성/갱신 작업에 접근할 수 없다.
- RLS:
profiles,user_favorites,user_acquired_certs등 사용자 데이터는 RLS 정책으로 본인만 접근. - Leaked password protection: Supabase Auth → Email provider에서 활성화 권장.
- CORS: 백엔드는 Bearer 토큰 인증 기준으로
allow_origins=["*"],allow_credentials=False사용.
개인·포트폴리오 목적. 데이터는 참고용이며, 상업적 이용 시 해당 데이터 출처의 이용 약관을 확인하세요.
CertFinder — 데이터로 여는 당신의 미래.