[Feat]: 시나리오 AI 연동 Global 유틸리티 작성

[johnbosco0414]

제목(필수): [TYPE]: 제목 예) [FEAT]: 회원가입 기능 추가

제목 규칙 자세히 보기

• 형식: [TYPE]: 제목
• 제한: 50자 이내, 첫 글자 대문자, 명령문
• TYPE: FEAT FIX REFACTOR COMMENT STYLE TEST CHORE INIT

---

무엇을 / 왜

• 무엇(What):

• AI 서비스 구조

1. AiService 인터페이스: 3개 AI 기능 정의 (베이스시나리오, 결정시나리오, 상황생성)
2. AiServiceImpl 구현체: Gemini API를 사용한 실제 AI 호출 로직
3. TextAiClient 인터페이스: 텍스트 생성 AI 클라이언트 추상화
4. GeminiTextClient 구현체: Google Gemini API 연동 클라이언트

• 프롬프트 템플릿 시스템

1. BaseScenarioPrompt: BaseLine 기반 베이스 시나리오 생성 프롬프트
2. DecisionScenarioPrompt: DecisionLine 기반 새 시나리오 생성 프롬프트
3. SituationPrompt: 이전 선택들 기반 새로운 상황 생성 프롬프트

• AI 응답 결과 DTO

1. BaseScenarioResult: 베이스 시나리오 AI 응답 구조 (job, summary, description, total, 지표점수들, 타임라인, 베이스라인제목)
2. DecisionScenarioResult: 새 시나리오 AI 응답 구조 (job, summary, description, total, 지표점수들, 타임라인, 비교분석, 이미지프롬프트)

• 예외 처리 계층

1. AiServiceException: AI 서비스 기본 예외
2. AiParsingException: AI 응답 파싱 실패 예외
3. AiApiException: AI API 호출 실패 예외 (미사용)
4. AiTimeoutException: AI 요청 타임아웃 예외 (미사용)

• 설정 관리

1. TextAiConfig: Gemini API 설정 (API키, URL, 모델명, 타임아웃)
2. ImageAiConfig: 이미지 AI 설정 (미래 확장용, 현재 비활성화)

• Service 레이어 트랜잭션 분리

1. ScenarioTransactionService: AI 결과 저장용 별도 트랜잭션 서비스
2. @async processScenarioGenerationAsync: 비동기 AI 호출 메서드
3. executeAiGeneration: 트랜잭션 외부 AI 호출 전용 메서드
4. 상태별 트랜잭션 분리: PENDING → PROCESSING → COMPLETED/FAILED 각각 독립 트랜잭션

• 타 도메인 연동 구조

1. Node 도메인 연동: BaseLine, DecisionLine, BaseNode, DecisionNode 엔티티 활용
2. User 도메인 연동: 사용자 정보 (birthdayAt, ageYear) 기반 개인화
3. Scenario 도메인 연동: AI 결과를 Scenario, SceneType, SceneCompare 엔티티에 저장
4. Cross-Domain Repository: BaseLineRepository, DecisionLineRepository 의존성 주입

• 테스트 코드 작성

1. AiServiceImplTest: AI 서비스 단위 테스트 (11개 테스트 메서드, 4개 중첩 클래스)
2. Mock 기반 테스트: @ExtendWith(MockitoExtension.class), BDDMockito 활용
3. CompletableFuture 테스트: 비동기 응답 검증 및 예외 처리 테스트
4. Entity 생성 헬퍼: ReflectionTestUtils로 JPA ID 설정, 컬렉션 초기화

• Scenario 엔티티 구조 개선

1. BaseLine 연관관계 추가: 베이스 시나리오와 BaseLine 직접 연결
2. DecisionLine 구분: decisionLine이 null이면 베이스 시나리오, 존재하면 새 시나리오
3. 이중 참조 구조: baseLine 필드와 decisionLine.baseLine 를 통한 BaseLine 접근
4. Repository 쿼리 개선: findByBaseLineIdAndDecisionLineIsNull() 베이스 시나리오 조회

• 왜(Why):

• 비즈니스 요구사항 충족

1. 사용자 개인화: 사용자별 생년월일과 현재 나이를 고려한 맞춤형 시나리오 생성
2. 현실성 있는 타임라인: 실제 BaseNode/DecisionNode의 ageYear를 사용한 정확한 연도 계산
3. 다양성 확보: 고정 점수 대신 유동적 범위(40-60, 30-96)로 현실적인 시나리오 생성
4. 비교 분석: 베이스라인 대비 새로운 선택의 장단점 분석 제공

• 시스템 안정성 확보

1. 비동기 처리: 긴 AI 응답 시간으로 인한 사용자 대기 시간 최소화
2. 예외 처리: AI 호출 실패, 파싱 오류 등에 대한 적절한 에러 처리
3. 재시도 로직: FAILED 상태 시나리오의 재생성 지원
4. null 안전성: BaseLine, DecisionLine null 체크로 런타임 오류 방지

• 확장성과 유지보수성

1. 인터페이스 분리: AI 구현체 교체 가능한 구조 (Gemini → OpenAI 등)
2. 프롬프트 템플릿화: AI 요청 내용 수정 시 코드 변경 없이 템플릿만 수정
3. 설정 외부화: API 키 등 민감 정보를 환경변수로 분리
4. 미래 확장 대비: ImageAiClient 등 이미지 생성 기능을 위한 구조 준비

• 성능 최적화

1. CompletableFuture: 논블로킹 AI 호출로 서버 자원 효율적 사용
2. 트랜잭션 분리: 긴 AI 호출을 트랜잭션 외부에서 실행하여 DB 락 방지
3. 상태 관리: PENDING → PROCESSING → COMPLETED 상태로 진행상황 추적
4. 에러 복구: AI 실패 시 FAILED 상태로 마킹 후 재시도 가능

• 데이터 품질 보장

1. 구조화된 응답: JSON 형태의 일관된 AI 응답 구조로 파싱 안정성 확보
2. 검증 로직: 빈 노드 리스트, null 값 등에 대한 사전 검증
3. 타입 안전성: Record 타입 사용으로 불변 객체 보장
4. 에러 메시지: 사용자 친화적인 한글 에러 메시지 제공

• 트랜잭션 분리 이유

1. DB 락 방지: 30초 이상 소요되는 AI 호출을 트랜잭션 외부로 분리하여 커넥션 풀 고갈 방지
2. 장애 격리: AI 서비스 장애가 DB 트랜잭션에 영향을 주지 않도록 분리
3. 동시성 향상: 여러 사용자의 시나리오 생성 요청을 동시에 처리 가능
4. 상태 추적: 각 단계별 독립 트랜잭션으로 정확한 진행 상태 관리

• 타 도메인 연동 이유

1. 데이터 일관성: 사용자의 실제 선택 경로(Trees 도메인)를 기반으로 한 정확한 시나리오 생성
2. 개인화 강화: User 도메인의 개인정보를 활용한 맞춤형 AI 프롬프트 생성
3. 의존성 최소화: Repository 계층에서만 타 도메인 접근하여 결합도 감소
4. 비즈니스 로직 통합: 분산된 도메인 정보를 AI가 이해할 수 있는 통합 컨텍스트로 변환

• 테스트 코드 작성 이유

1. AI 호출 검증: 실제 API 호출 없이 AI 서비스 로직 검증 가능
2. 예외 상황 대응: 네트워크 오류, 파싱 실패 등 다양한 예외 상황 시뮬레이션
3. 리팩토링 안전성: 코드 변경 시 기존 동작 보장을 위한 회귀 테스트
4. 개발 효율성: Mock 데이터로 빠른 개발 및 디버깅 환경 구축

• BaseLine 연관관계 추가 이유

1. 베이스 시나리오 식별: BaseLine별로 하나의 베이스 시나리오를 명확히 구분하기 위함
2. 쿼리 성능 향상: DecisionLine을 거치지 않고 직접 BaseLine으로 베이스 시나리오 조회 가능
3. 데이터 정합성: 베이스 시나리오와 새 시나리오의 관계를 명확히 정의
4. 비즈니스 로직 단순화: 베이스 시나리오 존재 확인 및 생성 로직을 간소화

어떻게(요약) — 3줄 이내

1. AI 기반 시나리오 생성: 사용자의 실제 선택 경로(Trees 도메인)와 개인정보(User 도메인)를 바탕으로 Gemini API를 활용해 맞춤형 인생 시나리오 3종(베이스/새시나리오/상황생성)을 구조화된 프롬프트로 생성
2. 트랜잭션 분리 및 비동기 처리: 30초 이상 소요되는 AI 호출을 @async와 별도 트랜잭션으로 분리하여 DB 락 방지 및 동시성 향상, PENDING→PROCESSING→COMPLETED 상태 관리로 사용자 경험 개선
3. 확장 가능한 구조와 테스트: 인터페이스 기반 AI 클라이언트 추상화로 구현체 교체 가능, Mock 기반 단위 테스트로 AI 호출 없이 로직 검증, BaseLine 직접 연관관계로 베이스 시나리오 성능 최적화

영향 범위

• API 변경
• DB 마이그레이션
• Breaking Change
• 보안/권한 영향
• 문서/가이드 업데이트 필요

체크리스트

• 타입 라벨 부착 (FEAT/FIX/REFACTOR/COMMENT/STYLE/TEST/CHORE/INIT)
• 로컬/CI 테스트 통과
• 영향도 점검 완료
• 주석/문서 반영(필요 시)

ToDo (선택)

• 할 일 1
• 할 일 2

스크린샷/증빙(선택)

이슈 연결 (자동)

Closes #51

[lcs9317]

정말 고생 많으셨습니다!