🔀 develop -> main 병합

.gitignore

@@ -47,4 +47,5 @@ src/main/resources/application.properties
 
 ### Claude Code ###
 .omc
+.claude/
 

build.gradle

@@ -29,19 +29,46 @@ dependencies {
 	implementation 'org.springframework.boot:spring-boot-starter-security'
 	implementation 'org.springframework.boot:spring-boot-starter-validation'
 	implementation 'org.springframework.boot:spring-boot-starter-web'
+	implementation 'org.springframework.kafka:spring-kafka'
+	testImplementation 'org.springframework.kafka:spring-kafka-test'
 	compileOnly 'org.projectlombok:lombok'
 	runtimeOnly 'com.mysql:mysql-connector-j'
 	annotationProcessor 'org.projectlombok:lombok'
+	testCompileOnly 'org.projectlombok:lombok'
+	testAnnotationProcessor 'org.projectlombok:lombok'
 	testImplementation 'org.springframework.boot:spring-boot-starter-test'
 	testImplementation 'org.springframework.security:spring-security-test'
+	testImplementation 'org.awaitility:awaitility:4.2.2'
 	testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
 
 	// JWT
 	implementation 'io.jsonwebtoken:jjwt-api:0.12.3'
 	runtimeOnly 'io.jsonwebtoken:jjwt-impl:0.12.3'
 	runtimeOnly 'io.jsonwebtoken:jjwt-jackson:0.12.3'
+
+	// Redis
+	implementation 'org.springframework.boot:spring-boot-starter-data-redis'
+
+	// ArchUnit
+	testImplementation 'com.tngtech.archunit:archunit-junit5:1.3.0'
+
+	// .env 파일 로딩
+	implementation 'me.paulschwarz:spring-dotenv:4.0.0'
 }
 
 tasks.named('test') {
-	useJUnitPlatform()
+	useJUnitPlatform {
+		excludeTags 'kafka-broker'
+	}
+}
+
+tasks.register('kafkaBrokerTest', Test) {
+	description = 'Run kafka-broker tagged tests (EmbeddedKafka 또는 실제 broker 의존)'
+	group = 'verification'
+	useJUnitPlatform {
+		includeTags 'kafka-broker'
+	}
+	testClassesDirs = sourceSets.test.output.classesDirs
+	classpath = sourceSets.test.runtimeClasspath
+	shouldRunAfter test
 }

docker-compose.yml

@@ -9,6 +9,19 @@ services:
       - "8080"
     depends_on:
       - fastapi
+      - redis
+    networks:
+      - kkumteul
+
+  redis:
+    image: redis:latest
+    container_name: redis
+    restart: always
+    command: redis-server --appendonly yes
+    volumes:
+      - redis-data:/data
+    expose:
+      - "6379"
     networks:
       - kkumteul
 
@@ -42,3 +55,6 @@ services:
 networks:
   kkumteul:
     driver: bridge
+
+volumes:
+  redis-data:

src/main/java/com/capstone/kkumteul/KkumteulApplication.java

@@ -2,10 +2,12 @@
 
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.cache.annotation.EnableCaching;
 import org.springframework.scheduling.annotation.EnableScheduling;
 
 @SpringBootApplication
 @EnableScheduling
+@EnableCaching
 public class KkumteulApplication {
 
     public static void main(String[] args) {

src/main/java/com/capstone/kkumteul/domain/fairytale/entity/Fairytale.java

@@ -5,6 +5,9 @@
 import jakarta.persistence.*;
 import lombok.*;
 
+import java.util.ArrayList;
+import java.util.List;
+
 @Entity
 @Getter
 @Builder
@@ -36,6 +39,11 @@ public class Fairytale extends BaseEntity {
     @Column(nullable = false)
     private Background background;
 
-    @Column(columnDefinition = "TEXT")
+    @Column(columnDefinition = "TEXT", nullable = false)
     private String content;
+
+    @Builder.Default
+    @OneToMany(mappedBy = "fairytale", cascade = CascadeType.ALL, orphanRemoval = true)
+    private List<Paragraph> paragraphs = new ArrayList<>();
+
 }

src/main/java/com/capstone/kkumteul/domain/fairytale/entity/Paragraph.java

@@ -25,4 +25,12 @@ public class Paragraph extends BaseEntity {
 
     @Column(nullable = false, columnDefinition = "TEXT")
     private String text;
+
+    //nullable 제약은 추후
+    @Column
+    private String imageUrl;
+
+    public void updateImageUrl(String imageUrl) {
+        this.imageUrl = imageUrl;
+    }
 }

src/main/java/com/capstone/kkumteul/domain/fairytale/exception/FairytaleErrorCode.java

@@ -4,7 +4,7 @@
 import lombok.AllArgsConstructor;
 import lombok.Getter;
 
-import static com.capstone.kkumteul.global.constant.StaticValue.*;
+import static com.capstone.kkumteul.global.constant.StaticValue.NOT_FOUND;
 
 @Getter
 @AllArgsConstructor

src/main/java/com/capstone/kkumteul/domain/fairytale/repository/ParagraphRepository.java

@@ -10,4 +10,7 @@
 public interface ParagraphRepository extends JpaRepository<Paragraph, Long> {
 
     List<Paragraph> findByFairytaleIdOrderByPageAsc(Long fairytaleId);
+
+    /** 특정 페이지의 문장들 조회 — 단어장 추출 시 페이지 단위 본문 로드 */
+    List<Paragraph> findByFairytaleIdAndPage(Long fairytaleId, int page);
 }

src/main/java/com/capstone/kkumteul/domain/fairytale/service/FairytaleCheckService.java

@@ -0,0 +1,12 @@
+package com.capstone.kkumteul.domain.fairytale.service;
+
+public interface FairytaleCheckService {
+
+    void markVocabDone(Long fairytaleId, int page);
+
+    void markImageDone(Long fairytaleId, int page);
+
+    boolean isBothDone(Long fairytaleId, int page);
+
+    void markTotalPages(Long fairytaleId, int totalPages);
+}

src/main/java/com/capstone/kkumteul/domain/fairytale/service/FairytaleCheckServiceImpl.java

@@ -0,0 +1,141 @@
+package com.capstone.kkumteul.domain.fairytale.service;
+
+import com.capstone.kkumteul.domain.fairytale.entity.Paragraph;
+import com.capstone.kkumteul.domain.fairytale.repository.ParagraphRepository;
+import com.capstone.kkumteul.domain.fairytale.service.sse.SseService;
+import com.capstone.kkumteul.domain.fairytale.web.dto.SseEventRes;
+import com.capstone.kkumteul.domain.vocab.entity.WordEntry;
+import com.capstone.kkumteul.domain.vocab.repository.WordEntryRepository;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.data.redis.core.RedisTemplate;
+import org.springframework.stereotype.Service;
+
+import java.time.Duration;
+import java.time.LocalDateTime;
+import java.util.List;
+import java.util.Optional;
+
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class FairytaleCheckServiceImpl implements FairytaleCheckService {
+
+    private final RedisTemplate<String, String> redisTemplate;
+    private final SseService sseService;
+    private final WordEntryRepository wordEntryRepository;
+    private final ParagraphRepository paragraphRepository;
+
+    @Value("${vocab.fallback-threshold-seconds:300}")
+    private long vocabFallbackThresholdSeconds;
+
+    private static final String VOCAB_KEY = "vocab:%d:%d";
+    private static final String IMAGE_KEY = "image:%d:%d";
+    private static final String TOTAL_KEY = "total:%d";
+    private static final String SENT_KEY = "sent:%d";
+    private static final String DONE = "done";
+
+    @Override
+    public void markVocabDone(Long fairytaleId, int page) {
+        redisTemplate.opsForValue().set(String.format(VOCAB_KEY, fairytaleId, page), DONE);
+        log.info("[VOCAB DONE] fairytaleId={}, page={}", fairytaleId, page);
+        checkAndSend(fairytaleId, page);
+    }
+
+    @Override
+    public void markImageDone(Long fairytaleId, int page) {
+        redisTemplate.opsForValue().set(String.format(IMAGE_KEY, fairytaleId, page), DONE);
+        log.info("[IMAGE DONE] fairytaleId={}, page={}", fairytaleId, page);
+        forceVocabIfStale(fairytaleId, page);
+        checkAndSend(fairytaleId, page);
+    }
+
+    /**
+     * image done 시점에 vocab 마커가 없고 paragraph 생성 후 임계 초과면 빈 vocab으로 강제 mark.
+     * AI Producer가 vocab_extracted를 누락한 경우의 SSE hang을 방지한다.
+     */
+    private void forceVocabIfStale(Long fairytaleId, int page) {
+        String vocabKey = String.format(VOCAB_KEY, fairytaleId, page);
+        if (redisTemplate.opsForValue().get(vocabKey) != null) return;
+
+        List<Paragraph> paragraphs = paragraphRepository.findByFairytaleIdAndPage(fairytaleId, page);
+        if (paragraphs.isEmpty()) return;
+
+        LocalDateTime created = paragraphs.getFirst().getCreatedAt();
+        if (created == null) return;
+        long ageSeconds = Duration.between(created, LocalDateTime.now()).getSeconds();
+        if (ageSeconds < vocabFallbackThresholdSeconds) return;
+
+        log.warn("vocab fallback fired fairytaleId={}, page={}, ageSeconds={}", fairytaleId, page, ageSeconds);
+        redisTemplate.opsForValue().set(vocabKey, DONE);
+    }
+
+    @Override
+    public boolean isBothDone(Long fairytaleId, int page) {
+        String vocabStatus = redisTemplate.opsForValue().get(String.format(VOCAB_KEY, fairytaleId, page));
+        String imageStatus = redisTemplate.opsForValue().get(String.format(IMAGE_KEY, fairytaleId, page));
+        return DONE.equals(vocabStatus) && DONE.equals(imageStatus);
+    }
+
+    //sse전송
+    private void checkAndSend(Long fairytaleId, int page) {
+        boolean both = isBothDone(fairytaleId, page);
+        log.info("[CHECK] fairytaleId={}, page={}, isBothDone={}", fairytaleId, page, both);
+        if (!both) return;
+
+        Optional<WordEntry> wordEntry = wordEntryRepository.findByFairytaleIdAndPageNo(fairytaleId, page);
+        List<Paragraph> paragraphs = paragraphRepository.findByFairytaleIdAndPage(fairytaleId, page);
+
+        if (paragraphs.isEmpty()) {
+            sseService.sendToClient(fairytaleId, "error", "문단 데이터 없음");
+            log.warn("SSE 발송 실패 - 문단 없음 fairytaleId={}, page={}", fairytaleId, page);
+            return;
+        }
+
+        Paragraph paragraph = paragraphs.getFirst();
+        List<String> sentences = List.of(paragraph.getText().split("\n"));
+        SseEventRes.Vocabulary vocab = wordEntry
+                .map(w -> new SseEventRes.Vocabulary(w.getWord(), w.getMeaning()))
+                .orElse(null);
+
+        SseEventRes event = new SseEventRes(
+                fairytaleId,
+                page,
+                sentences,
+                vocab,
+                paragraph.getImageUrl()
+        );
+
+        log.info("[PAGE_CONTENT SEND] fairytaleId={}, page={}", fairytaleId, page);
+        sseService.sendToClient(fairytaleId, "page_content", event);
+
+        redisTemplate.delete(String.format(VOCAB_KEY, fairytaleId, page));
+        redisTemplate.delete(String.format(IMAGE_KEY, fairytaleId, page));
+
+        Long sent = redisTemplate.opsForValue().increment(String.format(SENT_KEY, fairytaleId));
+        log.info("[SENT COUNT] fairytaleId={}, sent={}", fairytaleId, sent);
+        checkAndSendDone(fairytaleId, sent);
+    }
+
+    @Override
+    public void markTotalPages(Long fairytaleId, int totalPages) {
+        redisTemplate.opsForValue().set(String.format(TOTAL_KEY, fairytaleId), String.valueOf(totalPages));
+        log.info("[TOTAL SET] fairytaleId={}, totalPages={}", fairytaleId, totalPages);
+        String sentStr = redisTemplate.opsForValue().get(String.format(SENT_KEY, fairytaleId));
+        long sent = sentStr == null ? 0L : Long.parseLong(sentStr);
+        checkAndSendDone(fairytaleId, sent);
+    }
+
+    private void checkAndSendDone(Long fairytaleId, Long sent) {
+        String totalStr = redisTemplate.opsForValue().get(String.format(TOTAL_KEY, fairytaleId));
+        if (totalStr == null) return;
+
+        if (sent >= Long.parseLong(totalStr)) {
+            sseService.sendToClient(fairytaleId, "done", String.valueOf(fairytaleId));
+            redisTemplate.delete(String.format(TOTAL_KEY, fairytaleId));
+            redisTemplate.delete(String.format(SENT_KEY, fairytaleId));
+            log.info("SSE done 전송 fairytaleId={}", fairytaleId);
+        }
+    }
+}

src/main/java/com/capstone/kkumteul/domain/fairytale/service/sse/SseService.java

@@ -0,0 +1,8 @@
+package com.capstone.kkumteul.domain.fairytale.service.sse;
+
+import org.springframework.web.servlet.mvc.method.annotation.SseEmitter;
+
+public interface SseService {
+    SseEmitter subscribe(Long fairytaleId);
+    void sendToClient(Long fairytaleId, String eventName, Object data);
+}

src/main/java/com/capstone/kkumteul/domain/fairytale/service/sse/SseServiceImpl.java

@@ -0,0 +1,50 @@
+package com.capstone.kkumteul.domain.fairytale.service.sse;
+
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+import org.springframework.web.servlet.mvc.method.annotation.SseEmitter;
+
+import java.io.IOException;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+@Slf4j
+@Service
+public class SseServiceImpl implements SseService {
+    private final Map<Long, SseEmitter> sseEmittersMap = new ConcurrentHashMap<>();
+
+    public SseEmitter subscribe(Long fairytaleId) {
+        long timeout = 1000L * 60 * 60;
+
+        SseEmitter emitter = new SseEmitter(timeout);
+        sseEmittersMap.put(fairytaleId, emitter);
+
+        emitter.onCompletion(() -> sseEmittersMap.remove(fairytaleId)); //complete시 콜백함수
+        emitter.onTimeout(() -> sseEmittersMap.remove(fairytaleId)); //타임아웃시 삭제
+        emitter.onError(e -> {
+            log.error("SSE 에러 fairytaleId={}", fairytaleId, e);
+            sseEmittersMap.remove(fairytaleId);
+        }); //전송중 에러시 삭제
+
+        //연결 성공시
+        sendToClient(fairytaleId, "connect", "sse connect...");
+
+        return emitter;
+    }
+
+    public void sendToClient(Long fairytaleId, String eventName, Object data) {
+        SseEmitter emitter = sseEmittersMap.get(fairytaleId);
+        if (emitter == null) return;
+        try {
+            emitter.send(SseEmitter.event()
+                    .name(eventName)
+                    .data(data));
+            if ("done".equals(eventName)) {
+                emitter.complete(); //sse 스트림 종료
+            }
+        } catch (IOException e) {
+            log.error("SSE 전송 실패 fairytaleId={}", fairytaleId, e);
+            sseEmittersMap.remove(fairytaleId);
+        }
+    }
+}