BE-VibeCodeEval

AI 기반 코딩 테스트 평가 플랫폼 — Spring Boot 백엔드 서버

실시간 시험 관리, AI 채점 연동, WebSocket 브로드캐스트, SSE 스트리밍을 담당합니다.

---

목차

• 기술 스택
• 아키텍처
• 프로젝트 구조
• 주요 기능
• API 개요
• 인증 플로우
• 실시간 통신
• 시작하기
• 환경 변수

---

🛠 기술 스택

분류	기술
Language	Java 17
Framework	Spring Boot 3.2.0
Security	Spring Security + JWT (HttpOnly Cookie)
Database	PostgreSQL 15 (JPA / Hibernate)
Cache	Redis 7 (Lettuce)
Real-time	STOMP WebSocket, SSE
API Docs	Springdoc OpenAPI (Swagger UI)
ID Generation	TSID (hypersistence-utils)
Config Encryption	Jasypt
Monitoring	Micrometer + Prometheus
Build	Gradle 8.5
Container	Docker + Docker Compose

---

🏗 아키텍처

┌─────────────────────────────────────────────────────────────┐
│ Cloudflare │
│ DNS · CDN · WAF · SSL/TLS │
└────────────────────────┬────────────────────────────────────┘
│ HTTPS / WSS
┌────▼────┐
│ Nginx │ :443 → :8080 / :8001
└────┬────┘
┌─────────────┼─────────────┐
│ │ │
┌──────▼──────┐ │ ┌──────▼──────┐
│ BE Server │ │ │ AI Worker │
│ Spring Boot │◄─────┘ │ FastAPI │
│ :8080 │◄────────────│ :8001 │
└──────┬──────┘ Callback └─────────────┘
│
┌──────┴──────┐
│ Data Layer │
│ PostgreSQL │
│ Redis │
└─────────────┘

도메인 구성 (Clean Architecture)

domain/
├── auth # 인증·인가 (JWT, 토큰 재발급)
├── exam # 시험 세션 관리
├── submission # 코드 제출 · Outbox Poller
├── chat # AI 채팅 · 토큰 사용량
├── problem # 문제 CRUD
├── statistics # 통계 집계
└── admin # 관리자 · 마스터 운영

각 도메인은 ui → application → domain → infrastructure 레이어로 분리되며, UseCase 단위로 비즈니스 로직이 구성됩니다.

---

📁 프로젝트 구조

src/main/java/com/yd/vibecode/
├── VibecodeApplication.java
├── domain/
│ ├── admin/ # 관리자 계정·보드·메트릭·시험 관리
│ ├── auth/ # 로그인·로그아웃·토큰 재발급
│ ├── chat/ # 채팅 저장·조회·AI 콜백
│ ├── exam/ # 시험 상태·참가자 세션
│ ├── problem/ # 문제 조회
│ ├── statistics/ # 통계
│ └── submission/ # 제출·스트리밍·내부 처리
└── global/
├── config/ # Web, JPA, Redis, WebSocket, Async
├── security/ # SecurityConfig, JWT, STOMP Interceptor
├── interceptor/ # JWT Blacklist, Cookie Handshake
├── swagger/ # API 명세 인터페이스
├── exception/ # 전역 예외 처리
├── annotation/ # @CurrentUser, @AccessToken 등
└── util/ # CookieUtils, SecureRandomGenerator

---

✨ 주요 기능

🔐 인증 / 인가

• 참가자 입장 — Entry Code + 이름 + 전화번호로 JWT 발급 (회원가입 불필요)
• 관리자 로그인 — ID/PW 기반 Access Token + Refresh Token 발급
• 토큰 저장 — HttpOnly 쿠키 전달 (XSS 방지)
• 토큰 로테이션 — Refresh Token 재발급 시 기존 토큰 즉시 무효화
• 블랙리스트 — 로그아웃된 Access Token을 Redis에 등록하여 재사용 차단
• STOMP 인증 우회 — WebSocket은 HttpOnly 쿠키 접근 불가 → body로 토큰 전달 후 StompPrincipalInterceptor에서 검증

📝 시험 관리

• 시험 생성·시작·종료 (관리자)
• 시험 상태 실시간 조회 (타이머 동기화)
• 참가자 세션 정보 조회
• 코드 드래프트 자동 저장 (PUT /api/exams/{id}/code-draft)

🤖 코드 제출 · AI 채점

• 제출 접수 후 202 Accepted 즉시 응답 (비동기 처리)
• Outbox Poller로 Redis 이벤트를 AI Worker에 전달
• AI 채점 완료 시 Callback 수신 (POST /api/callbacks/ai/**)
• 채점 결과를 SSE 스트림으로 관리자에게 실시간 전송

📡 실시간 통신

• STOMP WebSocket (/ws) — 시험 상태 변경 브로드캐스트
• SSE (/api/admin/submissions/{id}/stream) — 채점 진행 스트리밍

💬 AI 채팅 연동

• 참가자 채팅 메시지 저장 → AI Worker로 전달
• 대화 이력 조회
• 토큰 사용량 추적 및 제한

🧑‍💼 관리자 / 마스터

• 관리자 계정 CRUD, 입장 코드 생성·관리
• 실시간 참가자 현황 보드
• 제출 상세 조회 (루브릭·코드 포함)
• 시스템 메트릭, 활동 로그
• 플랫폼 전역 설정 (시험 시간, 토큰 제한, 데이터 보관 정책)

---

📖 API 개요

Method	Path	설명	권한
POST	/api/auth/enter	참가자 입장 (JWT 발급)	Public
POST	/api/auth/admin/login	관리자 로그인	Public
POST	/api/auth/admin/logout	로그아웃	ADMIN
POST	/api/auth/admin/reissue	토큰 재발급	Cookie
GET	/api/auth/me	내 정보 조회	Any
GET	/api/exams/{id}/state	시험 상태 조회	USER
GET	/api/exams/{id}/participants/me	참가자 세션 조회	USER
POST	/api/exams/{id}/submissions	코드 제출 (202)	USER
GET/PUT	/api/exams/{id}/code-draft	코드 드래프트	USER
GET	/api/submissions/{id}	제출 상세 (본인)	USER
POST	/api/chat/messages	채팅 메시지 저장	USER
GET	/api/chat/history	채팅 이력 조회	Any
GET	/api/problems	문제 목록 조회	USER
GET	/api/admin/**	관리자 전용 API	ADMIN/MASTER
POST	/api/callbacks/ai/**	AI 채점 결과 수신	Internal
GET	/api/admin/submissions/{id}/stream	채점 결과 SSE	ADMIN

Swagger UI — http://localhost:8080/swagger-ui/index.html

---

🔑 인증 플로우

참가자 서버
│ │
├─ POST /api/auth/enter ──────►│
│ { entryCode, name, phone } │
│◄─────────────────────────────┤ Set-Cookie: accessToken (HttpOnly)
│ { accessToken } │ (body 포함: STOMP 인증용)
│ │
│ STOMP Connect │
├─ connectHeaders: { │
│ Authorization: Bearer ... │
│ } ──────────────────────────►│ StompPrincipalInterceptor 검증
│ │
관리자
│
├─ POST /api/auth/admin/login ─►│
│◄─────────────────────────────┤ Set-Cookie: accessToken, refreshToken (HttpOnly)
│ │
├─ POST /api/auth/admin/reissue►│ refreshToken 검증 + 로테이션
│◄─────────────────────────────┤ 새 accessToken, refreshToken 발급

---

📡 실시간 통신

STOMP WebSocket

ws://host/ws
SUBSCRIBE /topic/exams/{examId}/state
→ 시험 시작·종료·상태 변경 브로드캐스트
SUBSCRIBE /topic/exams/{examId}/submissions
→ 신규 제출 알림 (관리자 보드)

SSE (Server-Sent Events)

GET /api/admin/submissions/{submissionId}/stream
← data: {"status":"JUDGING","score":null}
← data: {"status":"COMPLETED","score":85}
← event: close

---

🚀 시작하기

사전 요구사항

• Java 17+
• Docker & Docker Compose

로컬 실행

# 1. 인프라 기동 (PostgreSQL + Redis)
docker compose up -d
# 2. 애플리케이션 실행
./gradlew bootRun
# 서버: http://localhost:8080# Swagger: http://localhost:8080/swagger-ui/index.html

Docker 빌드

docker build -t be-vibecodeeval .
docker run -p 8080:8080 be-vibecodeeval

프로덕션 배포

docker compose -f docker-compose.prod.yml up -d

---

⚙️ 환경 변수

변수	설명	예시
SPRING_DATASOURCE_URL	PostgreSQL JDBC URL	jdbc:postgresql://localhost:5432/ai_vibe_coding_test
SPRING_DATASOURCE_USERNAME	DB 사용자명	postgres
SPRING_DATASOURCE_PASSWORD	DB 비밀번호	password
SPRING_REDIS_HOST	Redis 호스트	localhost
SPRING_REDIS_PORT	Redis 포트	6379
JWT_SECRET	JWT 서명 키 (256bit+)	your-secret-key
JWT_ACCESS_EXPIRATION	Access Token 만료 (ms)	3600000
JWT_REFRESH_EXPIRATION	Refresh Token 만료 (ms)	604800000
JASYPT_ENCRYPTOR_PASSWORD	설정 파일 암호화 키	jasypt-password
AI_SERVER_URL	AI Worker 주소	http://localhost:8001

---

🔗 관련 레포지토리

레포	설명
FE-VibeCodeEval	Next.js 프론트엔드 (User / Admin / Master UI)
AI-VibeCodeEval	FastAPI + LangGraph AI 채점 워커