feat: 로컬 개발 환경 Docker 전환 및 전체 버그 수정

Author: Hyeonjun0527

.gitignore

@@ -45,4 +45,8 @@ application-local.yml
 src/main/resources/keystore.p12
 src/test/resources/application-s3-secrets.properties
 spy.log
-htmlReport
+htmlReport
+
+# 로컬 개발용 SSL 인증서 개인 키 제외
+nginx/certs/*.key
+nginx/certs/*.crt

compose.yaml

@@ -1,10 +1,23 @@
 services:
+  nginx:
+    image: nginx:1.27
+    container_name: pullit-local-nginx
+    restart: unless-stopped
+    ports:
+      - "443:443"
+    volumes:
+      - ./nginx/conf.d:/etc/nginx/conf.d
+      - ./nginx/certs:/etc/nginx/certs
+    depends_on:
+      - pullit-local-api
+    networks:
+      - pullit-local-network
+
   pullit-local-api:
     build: .
     container_name: pullit-local-api
     restart: unless-stopped
-    ports:
-      - "8080:8080"
+    ports: []
     environment:
       - SPRING_PROFILES_ACTIVE=local
       - DB_URL=jdbc:mariadb://mariadb:3306/mydatabase?createDatabaseIfNotExist=true&serverTimezone=Asia/Seoul&characterEncoding=UTF-8
@@ -14,6 +27,14 @@ services:
       - RABBITMQ_HOST=rabbitmq
       - SPRING_RABBITMQ_USERNAME=guest
       - SPRING_RABBITMQ_PASSWORD=guest
+      - APP_GEMINI_APIKEY=${APP_GEMINI_APIKEY}
+      - AWS_REGION=${AWS_REGION}
+      - GOOGLE_API_KEY=${GOOGLE_API_KEY}
+      - KAKAO_CLIENT_SECRET=${KAKAO_CLIENT_SECRET}
+      - KAKAO_REDIRECT_URI=${KAKAO_REDIRECT_URI}
+      - KAKAO_REST_API_KEY=${KAKAO_REST_API_KEY}
+      - S3_ACCESS_KEY=${S3_ACCESS_KEY}
+      - S3_SECRET_KEY=${S3_SECRET_KEY}
     depends_on:
       mariadb:
         condition: service_healthy
@@ -38,6 +59,14 @@ services:
       - RABBITMQ_HOST=rabbitmq
       - SPRING_RABBITMQ_USERNAME=guest
       - SPRING_RABBITMQ_PASSWORD=guest
+      - APP_GEMINI_APIKEY=${APP_GEMINI_APIKEY}
+      - AWS_REGION=${AWS_REGION}
+      - GOOGLE_API_KEY=${GOOGLE_API_KEY}
+      - KAKAO_CLIENT_SECRET=${KAKAO_CLIENT_SECRET}
+      - KAKAO_REDIRECT_URI=${KAKAO_REDIRECT_URI}
+      - KAKAO_REST_API_KEY=${KAKAO_REST_API_KEY}
+      - S3_ACCESS_KEY=${S3_ACCESS_KEY}
+      - S3_SECRET_KEY=${S3_SECRET_KEY}
     depends_on:
       mariadb:
         condition: service_healthy
@@ -59,6 +88,11 @@ services:
       - "127.0.0.1:3306:3306"
     networks:
       - pullit-local-network
+    healthcheck:
+      test: ["CMD", "mariadb", "-u", "myuser", "-psecret", "-e", "USE mydatabase;"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
 
   prometheus:
     container_name: prometheus
@@ -100,9 +134,8 @@ services:
     healthcheck:
       test: ["CMD", "redis-cli", "ping"]
       interval: 10s
-      timeout: 10s
+      timeout: 5s
       retries: 5
-      start_period: 30s
 
   rabbitmq:
     image: 'rabbitmq:3-management-alpine'
@@ -113,9 +146,9 @@ services:
     networks:
       - pullit-local-network
     healthcheck:
-      test: ["CMD", "rabbitmq-diagnostics", "ping"]
+      test: ["CMD", "rabbitmq-diagnostics", "check_running"]
       interval: 10s
-      timeout: 10s
+      timeout: 5s
       retries: 5
 
 networks:

nginx/certs/README.md

@@ -0,0 +1,52 @@
+# 로컬 개발 환경을 위한 SSL 인증서
+
+이 디렉토리는 `https://localhost` 접속에 필요한 SSL 인증서(`localhost.crt`)와 개인 키(`localhost.key`)를 저장하는 곳입니다.
+
+**주의**: 개인 키 파일(`*.key`)은 보안상의 이유로 Git 버전 관리에서 제외됩니다. 프로젝트를 처음 설정하는 경우, 아래의 방법으로 직접 인증서를 생성해야 합니다.
+
+## 인증서 생성 방법 (mkcert 사용)
+
+`mkcert`는 로컬 환경에서 신뢰할 수 있는 SSL 인증서를 손쉽게 만들어주는 도구입니다.
+
+### 1. mkcert 설치
+
+사용 중인 운영체제에 맞게 `mkcert`를 설치합니다.
+
+- **Linux (Ubuntu/Debian)**:
+  ```bash
+  sudo apt update
+  sudo apt install libnss3-tools mkcert
+  ```
+- **macOS (Homebrew)**:
+  ```bash
+  brew install mkcert
+  brew install nss # Firefox 지원을 위해 필요
+  ```
+- **Windows (Chocolatey)**:
+  ```powershell
+  choco install mkcert
+  ```
+
+### 2. 로컬 인증 기관(CA) 설치
+
+다음 명령어를 실행하여 내 컴퓨터에 로컬 CA를 생성하고 신뢰하도록 설정합니다. 이 작업은 컴퓨터 당 한 번만 수행하면 됩니다.
+
+```bash
+mkcert -install
+```
+
+### 3. 인증서 생성
+
+프로젝트의 `nginx/certs` 디렉토리로 이동한 후, 다음 명령어를 실행하여 `localhost`에 대한 인증서와 개인 키를 생성합니다.
+
+```bash
+# 터미널에서 `pullit/nginx/certs` 디렉토리로 이동
+mkcert localhost
+```
+
+위 명령어를 실행하면 `localhost.pem` (인증서)과 `localhost-key.pem` (개인 키) 파일이 생성됩니다. Nginx 설정 파일(`default.conf`)이 `.crt`와 `.key` 확장자를 사용하므로, 생성된 파일들의 이름을 아래와 같이 변경해주세요.
+
+- `localhost.pem` -> `localhost.crt`
+- `localhost-key.pem` -> `localhost.key`
+
+이제 `docker-compose up -d --build`을 실행하면 Nginx가 인증서를 정상적으로 로드하여 `https://localhost` 접속이 가능해집니다.

nginx/conf.d/default.conf

@@ -0,0 +1,39 @@
+server {
+    listen 443 ssl;
+    server_name localhost;
+
+    ssl_certificate /etc/nginx/certs/localhost.crt;
+    ssl_certificate_key /etc/nginx/certs/localhost.key;
+
+    # SSL Settings
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers HIGH:!aNULL:!MD5;
+
+    # SSE (Server-Sent Events)를 위한 특별 설정
+    # 실시간 알림을 위해 Nginx가 응답을 버퍼링하지 않고 즉시 클라이언트에 전달하도록 함
+    location /api/notifications/subscribe {
+        proxy_pass http://pullit-local-api:8080;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # SSE를 위한 핵심 설정
+        proxy_buffering off; # 응답 버퍼링 비활성화
+        proxy_cache off; # 캐시 비활성화
+        proxy_http_version 1.1; # HTTP/1.1 사용
+        proxy_set_header Connection ''; # Connection 헤더를 비워서 keep-alive 연결 유지
+        proxy_read_timeout 1h; # 타임아웃을 1시간으로 길게 설정
+        keepalive_timeout 7200s; # Keep-alive 타임아웃 설정
+    }
+
+    location / {
+        proxy_pass http://pullit-local-api:8080;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+    }
+}

src/main/java/kr/it/pullit/modules/learningsource/source/service/SourceService.java

@@ -148,6 +148,9 @@ public List<Source> findByIdIn(List<Long> ids) {
   public void deleteSource(Long sourceId, Long memberId) {
     Source source = getOrElseThrow(sourceId, memberId);
     String filePath = source.getFilePath();
+
+    source.getQuestionSets().forEach(questionSet -> questionSet.getSources().remove(source));
+
     sourceRepository.delete(source);
     deleteInS3(filePath);
   }

src/main/java/kr/it/pullit/modules/projection/learnstats/domain/LearnStats.java

@@ -64,7 +64,7 @@ public int calculateLearningProgress() {
     if (this.totalQuestionCount == 0) {
       return 0;
     }
-    return (int) (((double) this.totalSolvedQuestionCount / this.totalQuestionCount) * 100);
+    return (int) (((double) this.totalCorrectQuestionCount / this.totalQuestionCount) * 100);
   }
 
   public void onWeeklyReset() {

src/main/java/kr/it/pullit/modules/projection/outbox/domain/OutboxEvent.java

@@ -49,7 +49,7 @@ public enum Status {
   private String eventType; // WEEKLY_RESET, QUESTION_SOLVED, ...
 
   @Lob
-  @Column(columnDefinition = "json", nullable = false)
+  @Column(columnDefinition = "longtext", nullable = false)
   private String payload; // JSON 문자열
 
   @Enumerated(EnumType.STRING)

src/main/java/kr/it/pullit/modules/questionset/client/GeminiClient.java

@@ -2,11 +2,14 @@
 
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.google.genai.Client;
-import com.google.genai.types.FinishReason;
+import com.google.genai.ResponseStream;
+import com.google.genai.types.FinishReason.Known;
 import com.google.genai.types.GenerateContentResponse;
 import com.google.genai.types.HttpOptions;
 import java.io.IOException;
 import java.time.Duration;
+import java.util.stream.Collectors;
+import java.util.stream.StreamSupport;
 import kr.it.pullit.modules.questionset.api.LlmClient;
 import kr.it.pullit.modules.questionset.client.dto.request.GeminiRequest;
 import kr.it.pullit.modules.questionset.client.dto.request.LlmGeneratedQuestionRequest;
@@ -42,27 +45,35 @@ public LlmGeneratedQuestionSetResponse getLlmGeneratedQuestionContent(
       GeminiRequest geminiRequest = GeminiRequest.from(request, configBuilder);
       logRequestDetails(geminiRequest, request);
 
-      GenerateContentResponse response = callGeminiApi(geminiRequest);
-      validateResponse(response);
+      ResponseStream<GenerateContentResponse> responseStream = callGeminiApiStream(geminiRequest);
+      String aggregatedResponse = aggregateStreamResponse(responseStream);
 
-      return parseResponse(response);
+      return parseResponse(aggregatedResponse);
     } catch (IOException e) {
       throw LlmResponseParseException.create(e);
     } catch (Exception e) {
       throw LlmException.withCause(e);
     }
   }
 
-  private GenerateContentResponse callGeminiApi(GeminiRequest geminiRequest) {
-    return client.models.generateContent(
+  private ResponseStream<GenerateContentResponse> callGeminiApiStream(GeminiRequest geminiRequest) {
+    return client.models.generateContentStream(
         geminiRequest.model(), geminiRequest.content(), geminiRequest.config());
   }
 
-  private void validateResponse(GenerateContentResponse response) {
-    if (response.finishReason().knownEnum() != FinishReason.Known.STOP) {
-      throw LlmException.generationFailed(
-          "AI 모델이 비정상적으로 응답 생성을 중단했습니다. (사유: " + response.finishReason() + ")");
-    }
+  private String aggregateStreamResponse(ResponseStream<GenerateContentResponse> responseStream) {
+    return StreamSupport.stream(responseStream.spliterator(), false)
+        .peek(
+            response -> {
+              if (response.finishReason().knownEnum() != Known.STOP
+                  && response.finishReason().knownEnum() != Known.FINISH_REASON_UNSPECIFIED) {
+                throw LlmException.generationFailed(
+                    "AI 모델이 비정상적으로 응답 생성을 중단했습니다. (사유: " + response.finishReason() + ")");
+              }
+            })
+        .map(GenerateContentResponse::text)
+        .filter(text -> text != null && !text.isEmpty())
+        .collect(Collectors.joining());
   }
 
   private void logRequestDetails(GeminiRequest geminiRequest, LlmGeneratedQuestionRequest request) {
@@ -84,9 +95,7 @@ private void logRequestDetails(GeminiRequest geminiRequest, LlmGeneratedQuestion
             : "");
   }
 
-  private LlmGeneratedQuestionSetResponse parseResponse(GenerateContentResponse response)
-      throws IOException {
-    String rawResponse = response.text();
+  private LlmGeneratedQuestionSetResponse parseResponse(String rawResponse) throws IOException {
     try {
       return mapper.readValue(rawResponse, LlmGeneratedQuestionSetResponse.class);
     } catch (IOException e) {

src/main/java/kr/it/pullit/modules/questionset/repository/QuestionSetRepository.java

@@ -11,6 +11,8 @@ public interface QuestionSetRepository {
 
   Optional<QuestionSet> findById(Long id);
 
+  Optional<QuestionSet> findByIdWithQuestions(Long id);
+
   Optional<QuestionSet> findByIdAndMemberId(Long id, Long memberId);
 
   Optional<QuestionSet> findWithQuestionsForFirstSolving(Long id, Long memberId);

src/main/java/kr/it/pullit/modules/questionset/repository/QuestionSetRepositoryImpl.java

@@ -22,6 +22,11 @@ public Optional<QuestionSet> findById(Long id) {
     return questionSetJpaRepository.findById(id);
   }
 
+  @Override
+  public Optional<QuestionSet> findByIdWithQuestions(Long id) {
+    return questionSetJpaRepository.findByIdWithQuestions(id);
+  }
+
   @Override
   public Optional<QuestionSet> findByIdAndMemberId(Long id, Long memberId) {
     return questionSetJpaRepository.findByIdAndMemberId(id, memberId);