FastAPI AI 서버 연동 및 피드백 도메인 구현

[cfcromn]

✨ 작업 내용

FastAPI AI 서버와의 아바타 생성 연동 및 피드백 도메인을 구현했습니다.

아바타 생성 방식을 기존 Gemini 직접 호출에서 FastAPI 비동기 Job 방식으로 전환했으며, FastAPI로부터 콜백을 받아 생성 결과를 저장하는 흐름으로 변경했습니다. 아울러 생성 완료된 아바타에 대한 피드백을 저장하고 FastAPI로 전달하는 피드백 도메인을 추가했습니다.

---

🔍 리뷰 시 참고사항

• 생성 흐름 변경: POST /avatars 호출 시 원본 이미지를 S3에 업로드(sources/{id}.ext)한 뒤, FastAPI에 Job을 요청하고 aiJobId를 저장합니다. FastAPI가 생성 완료 후 /internal/ai/avatar-generations/callback으로 콜백을 보내면 아바타 상태와 이미지 URL을 업데이트합니다.
• 콜백 인증: X-Internal-Secret 헤더로 공유 시크릿 검증(INTERNAL_CALLBACK_SECRET 환경변수, 기본값 dev-secret). 미전송 시 400, 불일치 시 401.
• jobId 검증: 콜백 수신 시 reqDto.jobId == avatar.aiJobId 불일치면 INVALID_AVATAR_JOB_ID(400) 예외.
• 피드백 upsert: 아바타당 피드백 1개(UNIQUE avatar_id). 재등록 시 update. FastAPI 전송은 CompletableFuture.runAsync로 best-effort 비동기 처리.
• ENHANCED 스타일: FastAPI 미지원으로 생성 요청 시 즉시 AVATAR_STYLE_NOT_SUPPORTED_BY_AI(422) 반환.
• 아바타 삭제: 원본 이미지(sourceImageUri)도 함께 S3에서 삭제하도록 수정.
• @PostConstruct 검증: aikon.api-base-url이 비어있거나 HTTP(S)로 시작하지 않으면 앱 기동 시 fail-fast.

---

✅ 체크리스트

• 문서(README, .env.example 등) 변경이 필요한 경우 작성 또는 수정했나요?
• 작업한 코드가 정상적으로 동작하는 것을 직접 확인했나요?
• 필요한 경우 테스트 코드를 작성하거나 수정했나요?
• Merge 대상 브랜치를 올바르게 설정했나요?
• PR에 관련 없는 작업이 포함되지 않았나요?
• 적절한 라벨과 리뷰어를 설정했나요?

---

📎 관련 이슈(선택)

• Close feat: FastAPI AI 서버 연동 및 피드백 도메인 구현 #43

[gemini-code-assist]

Code Review

This pull request transitions the avatar generation process to an asynchronous, callback-based system integrated with an external FastAPI service, and introduces a user feedback mechanism. Key additions include the AvatarFeedback entity, FastApiClient for API communication, and a callback controller to handle generation results. The review feedback highlights several critical areas for improvement: resolving Hibernate collection tracking issues with @ElementCollection in AvatarFeedback, ensuring external API calls and event publishing occur after transaction commits to prevent rollback inconsistencies, configuring connection and read timeouts on RestClient to avoid thread blocking, and utilizing a dedicated thread pool for asynchronous tasks in FastApiClient.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[cfcromn]

/gemini review

[gemini-code-assist]

Code Review

This pull request refactors the avatar generation process to integrate with an external FastAPI service, introducing asynchronous generation requests, callback handling, and feedback collection. It adds new controllers, services, DTOs, and database entities for feedback, along with comprehensive unit tests. The review feedback highlights several critical improvement opportunities: addressing a potential timing attack vulnerability in the callback secret validation, replacing CompletableFuture.runAsync with Spring's @async to prevent thread starvation during external API calls, avoiding double slashes in the callback URL by trimming trailing slashes from the base URL, and making S3 URI parsing more robust.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.