요약 진행 상태 동시성 제어 및 실시간 웹소켓 파이프라인 구축

[ckdals4600]

관련 이슈

• close 링크 요약 비동기 처리 상태 웹소켓 알림 연동 #188

PR 설명

비동기 링크 요약 작업의 동시성 충돌(중복 요청 및 덮어쓰기)과 JPA 영속성 컨텍스트 분리(Detached) 문제를 해결하기 위해 아키텍처를 개편하고, 클라이언트에게 실시간 진행 상태를 전달하는 STOMP 웹소켓 파이프라인을 구축함.

작업 내용

Architecture & 트랜잭션 (영속성 문제 해결)

• 워커 스레드의 상태 업데이트와 요약 저장을 단일 트랜잭션으로 묶기 위해 SummaryWorkerFacade 신규 도입함.
• 영속성 컨텍스트 분리(Detached) 문제로 인한 업데이트 누락을 해결하기 위해, 워커에서 엔티티 객체 대신 식별자(linkId)를 넘겨 트랜잭션 내에서 재조회하도록 구조 개선함.
• DB 커넥션 고갈 방지를 위해 외부 AI API 호출부와 DB 트랜잭션 영역을 완벽히 분리함.

Domain & 비즈니스 로직 (재요약 차단 방어 로직)

• Link 엔티티에 요약 작업 상태를 관리하는 summaryStatus (PENDING, PROCESSING, COMPLETED, FAILED) 필드 추가함.
• 엔티티 내부에 상태 검증 로직(validateSummarizable)을 캡슐화함.
• 요약 진행 중일 때 사용자가 재요약 API나 수동 수정 API를 호출하면 ALREADY_PROCESSING 예외를 발생시켜 비정상적인 요청을 차단함.

WebSocket (실시간 상태 전달)

• STOMP 웹소켓 엔드포인트(/ws/link) 및 개별 사용자 구독 채널(/user/queue/summary) 설계 및 인증 허용 처리함.
• 비즈니스 로직과 통신 계층의 디커플링을 위해 SummaryStatusEvent 기반 퍼블리셔/리스너 아키텍처 도입함.

API 명세 & 테스트

• Swagger에 SummaryStatusRes 응답 DTO 및 SummaryStatus Enum 스키마 명세 추가 및 웹소켓 연결 가이드 문서화함.
• LinkFacadeTest가 하위 Service 구현에 의존하지 않도록 모킹(Mocking) 구조 리팩토링 및 단위 테스트 검증 완료함.

리뷰 포인트

• SummaryWorkerFacade 도입으로 인한 기존 Service 간 의존성 분리 및 트랜잭션 범위의 적절성.
• STOMP 웹소켓 JWT 인증 인터셉터 동작 및 /user/queue/summary 메시지 라우팅 규격 타당성.
• 요약 진행 상태(PENDING -> PROCESSING -> COMPLETED) 변경에 따른 동시성 제어가 의도대로 모든 예외 케이스를 방어하는지 여부.

[github-actions]

📊 코드 커버리지 리포트

Overall Project	92.88%	🍏
Files changed	100%	🍏

File	Coverage
SummaryStatusEvent.java	100%	🍏
LinkEventListener.java	100%	🍏
SummaryStatusEventListener.java	100%	🍏
LinkCreatedEvent.java	100%	🍏
LinkErrorCode.java	100%	🍏
SummaryErrorCode.java	100%	🍏
SummaryStatus.java	100%	🍏
SummaryWorker.java	100%	🍏
SummaryWorkerFacade.java	100%	🍏
LinkFacade.java	100%	🍏
SummaryService.java	100%	🍏
SummaryCommandService.java	100%	🍏
LinkService.java	100%	🍏
LinkQueryService.java	99.2%	🍏
SummaryQueryService.java	95%	🍏

[ckdals4600]

@Goder-0 추가로 코드 수정 중에 Worker 내부에서 AI 통신 실패 시 재시도 되는 로직이 존재하지 않아 Worker 내부에도 최대 3회까지 AI 통신을 재시도하는 로직을 추가하였습니다.