KKIUM Backend (KKIUM-BE)

KKIUM 은 흩어진 경험을 한곳으로 모아 AI와 함께 공고와의 매칭률, 자기소개서 작성을 도와주는 서비스입니다.

• 서비스: https://www.kkium.com
• 저장소: team-KKIUM/KKIUM-BE

✨ 프로젝트 구성

기술 스택

구분	기술
언어 / 프레임워크	Java 21, Spring Boot 4.0.5
웹 / API	Spring Web MVC, Spring WebFlux WebClient
인증 / 인가	Spring Security, JWT, OAuth2 Client
소셜 로그인	Kakao, Google
ORM / DB 접근	Spring Data JPA, JPQL @Query, JdbcTemplate
데이터베이스	PostgreSQL
벡터 검색 / 임베딩 저장	pgvector
캐시 / 토큰 저장	Redis
AI / LLM	Gemini API, OpenAI Embedding
크롤링 / 파싱	Jsoup, Playwright
파일 / 문서 처리	Apache PDFBox
API 문서화	Swagger / Springdoc OpenAPI
모니터링	Spring Actuator, Micrometer, Prometheus, Grafana
테스트	JUnit 5, Mockito, Spring Security Test, MockWebServer, Testcontainers, JaCoCo
코드 품질	Spotless, google-java-format
패키지 매니저 / 빌드	Gradle
컨테이너 / 배포	Docker, GitHub Actions, Artifact Registry, GKE, ArgoCD
시크릿 관리	GCP Secret Manager, External Secrets, Workload Identity

시스템 아키텍처

디렉터리 구조

KKIUM-BE/
├── src/
│   ├── main/
│   │   ├── java/com/kusitms/kkium/
│   │   │   ├── auth/              # 인증/인가, JWT, 소셜 로그인, refresh token
│   │   │   ├── user/              # 회원 프로필, 계정 삭제/복구
│   │   │   ├── experience/        # 경험 관리, 경험 분석, 태그, 임베딩
│   │   │   ├── jd/                # 공고 등록/분석, 크롤링, 매칭, 공고 임베딩
│   │   │   ├── resume/            # 자기소개서 답변, AI 초안, 작성 가이드
│   │   │   ├── notion/            # Notion OAuth, 페이지 조회, 경험 분석 연동
│   │   │   ├── home/              # 홈 대시보드
│   │   │   └── global/            # 공통 설정, 예외, 응답, BaseEntity, 공통 유틸
│   │   └── resources/
│   │       ├── application.yml
│   │       ├── application-local.yml
│   │       ├── application-prod.yml
│   │       └── prompts/           # LLM 프롬프트 및 JSON Schema
│   └── test/
│       ├── java/com/kusitms/kkium/
│       │   ├── global/            # Testcontainers 기반 통합 테스트 베이스
│       │   ├── experience/        # 경험 관리, LLM 분석, 임베딩, N+1, E2E 테스트
│       │   ├── jd/                # 공고 크롤링, 임베딩, 매칭, 문항 테스트
│       │   ├── resume/            # 자기소개서 답변, AI 초안, 작성 가이드 테스트
│       │   ├── notion/            # Notion 연동 테스트
│       │   └── home/              # 홈 대시보드 테스트
│       └── resources/
│           ├── application.yml    # 테스트 전용 profile
│           └── init-pgvector.sql  # pgvector extension 초기화
├── k8s/
│   ├── app/                       # GKE 애플리케이션 배포 매니페스트
│   └── monitoring/                # Prometheus / Grafana 매니페스트
├── argocd/                        # ArgoCD Application, Ingress, Notifications 설정
├── .github/
│   ├── workflows/                 # GitHub Actions 배포 파이프라인
│   ├── ISSUE_TEMPLATE/
│   └── pull_request_template.md
├── Dockerfile
├── docker-compose.yml             # 로컬 PostgreSQL(pgvector) 실행
├── build.gradle
└── settings.gradle

🚀 시작하기

필수 환경

• Java 21
• Docker (로컬 PostgreSQL 실행용)

java --version    # Java 21 이상
docker --version

설치 및 실행

1. Repository 클론

git clone https://github.com/team-KKIUM/KKIUM-BE.git
cd KKIUM-BE

2. 로컬 DB 실행

docker-compose up -d

3. 환경변수 설정

프로젝트 루트에 .env 파일을 생성하고 필요한 환경변수를 채웁니다.

4. 앱 실행

./gradlew bootRun --args='--spring.profiles.active=local'

실행 후 http://localhost:8080/swagger-ui/index.html 에서 API 명세를 확인할 수 있습니다.

📝 커밋 컨벤션

prefix	설명
feat	새로운 기능 추가
fix	버그 수정
refactor	코드 리팩토링
chore	빌드, 설정, 의존성 변경
docs	문서 작성 및 수정
test	테스트 코드 추가 및 수정
infra	인프라 및 배포 설정 변경

👩‍💻 Contributors

김유진	우지원	최수희
@ouob123	@jiwonniy	@erika0915