STT 입력 개선

src/docs/asciidoc/app/retrospect-v2-conversation.adoc

@@ -18,6 +18,7 @@ include::{snippets}/retrospect-v2/start/response-fields.adoc[]
 == 메시지 전송
 
 동일한 `clientMessageId`와 내용으로 재전송하면 이미 완료된 응답을 반환합니다.
+`inputType`은 `TEXT` 또는 `STT`이며 생략하면 `TEXT`로 저장됩니다. STT 변환 텍스트를 사용자가 수정한 뒤 전송할 때는 `STT`를 전달합니다.
 
 === Request
 

src/docs/asciidoc/app/retrospect.adoc

@@ -26,6 +26,11 @@ include::{snippets}/retrospect/submit-answer/response-fields.adoc[]
 
 == 음성 답변 제출
 
+[WARNING]
+====
+구버전 앱 호환용 API입니다. 신규 회고에서는 음성 답변 변환 후 사용자가 수정한 텍스트를 일반 메시지 API로 전송해야 합니다.
+====
+
 === Request
 
 include::{snippets}/retrospect/submit-voice-answer/http-request.adoc[]
@@ -300,4 +305,4 @@ include::{snippets}/retrospect/v2/find-by-id/path-parameters.adoc[]
 === Response
 
 include::{snippets}/retrospect/v2/find-by-id/http-response.adoc[]
-include::{snippets}/retrospect/v2/find-by-id/response-fields.adoc[]
+include::{snippets}/retrospect/v2/find-by-id/response-fields.adoc[]

src/main/kotlin/com/didit/adapter/integration/ai/ClovaSpeechClient.kt

@@ -63,7 +63,7 @@ class ClovaSpeechClient(
         runCatching {
             objectMapper.readValue(response, ClovaSpeechResponse::class.java)
         }.getOrElse {
-            throw SpeechTranscriptionFailedException("CLOVA Speech 응답 파싱 실패. response: $response")
+            throw SpeechTranscriptionFailedException("CLOVA Speech 응답 파싱 실패")
         }
 
     private fun validateResult(result: ClovaSpeechResponse) {

src/main/kotlin/com/didit/adapter/integration/ai/OpenAiSpeechClient.kt

@@ -67,7 +67,7 @@ class OpenAiSpeechClient(
         runCatching {
             objectMapper.readValue(response, OpenAiSpeechResponse::class.java)
         }.getOrElse {
-            throw SpeechTranscriptionFailedException("OpenAI STT 응답 파싱 실패. response: $response")
+            throw SpeechTranscriptionFailedException("OpenAI STT 응답 파싱 실패")
         }
 
     private fun createFilePart(

src/main/kotlin/com/didit/adapter/webapi/exception/ApiControllerAdvice.kt

@@ -5,6 +5,7 @@ import com.didit.application.common.exception.ErrorCode
 import org.slf4j.LoggerFactory
 import org.springframework.http.HttpStatus
 import org.springframework.http.ProblemDetail
+import org.springframework.http.converter.HttpMessageNotReadableException
 import org.springframework.web.bind.MethodArgumentNotValidException
 import org.springframework.web.bind.annotation.ExceptionHandler
 import org.springframework.web.bind.annotation.RestControllerAdvice
@@ -31,6 +32,19 @@ class ApiControllerAdvice {
             }
     }
 
+    @ExceptionHandler(HttpMessageNotReadableException::class)
+    fun handleUnreadableMessage(exception: HttpMessageNotReadableException): ProblemDetail {
+        log.warn("[VALIDATION] 요청 본문 파싱 실패 message={}", exception.message)
+
+        return ProblemDetail
+            .forStatusAndDetail(HttpStatus.BAD_REQUEST, ErrorCode.INVALID_REQUEST.detail)
+            .apply {
+                title = HttpStatus.BAD_REQUEST.reasonPhrase
+                setProperty("timestamp", OffsetDateTime.now().toString())
+                setProperty("code", ErrorCode.INVALID_REQUEST.name)
+            }
+    }
+
     @ExceptionHandler(BusinessException::class)
     fun handleBusinessException(exception: BusinessException): ProblemDetail {
         val errorCode = exception.errorCode

src/main/kotlin/com/didit/adapter/webapi/retrospect/RetrospectApi.kt

@@ -87,6 +87,8 @@ class RetrospectApi(
     }
 
     @RequireAuth
+    @Deprecated("Use the transcription endpoint and submit the edited text through the conversation API")
+    @Suppress("DEPRECATION")
     @PostMapping("/api/v1/retrospectives/{retrospectiveId}/answers/voice", consumes = [MediaType.MULTIPART_FORM_DATA_VALUE])
     fun submitVoiceAnswer(
         @CurrentUserId userId: UUID,

src/main/kotlin/com/didit/adapter/webapi/retrospect/RetrospectConversationV2Api.kt

@@ -42,7 +42,7 @@ class RetrospectConversationV2Api(
     ): SuccessResponse<SubmitConversationMessageV2Response> =
         SuccessResponse.of(
             SubmitConversationMessageV2Response.from(
-                conversation.submitMessage(retrospectiveId, userId, request.clientMessageId, request.content),
+                conversation.submitMessage(retrospectiveId, userId, request.clientMessageId, request.content, request.inputType),
             ),
         )
 

src/main/kotlin/com/didit/adapter/webapi/retrospect/dto/ConversationV2ApiDtos.kt

@@ -9,6 +9,7 @@ import com.didit.application.retrospect.dto.SubmitConversationMessageResult
 import com.didit.domain.retrospect.ConversationMessageType
 import com.didit.domain.retrospect.ConversationStatus
 import com.didit.domain.retrospect.ConversationTurnStatus
+import com.didit.domain.retrospect.InputType
 import com.didit.domain.retrospect.Sender
 import com.didit.domain.retrospect.SummaryGenerationStatus
 import jakarta.validation.constraints.NotBlank
@@ -19,6 +20,7 @@ data class SubmitConversationMessageV2Request(
     val clientMessageId: UUID,
     @field:NotBlank
     val content: String,
+    val inputType: InputType = InputType.TEXT,
 )
 
 data class StartConversationV2Response(

src/main/kotlin/com/didit/application/retrospect/RetrospectService.kt

@@ -14,6 +14,7 @@ import com.didit.application.retrospect.exception.RetrospectiveNotFoundException
 import com.didit.application.retrospect.exception.RetrospectiveNotInProgressException
 import com.didit.application.retrospect.exception.SpeechEmptyFileException
 import com.didit.application.retrospect.exception.SpeechEmptyResultException
+import com.didit.application.retrospect.exception.SpeechTranscriptionFailedException
 import com.didit.application.retrospect.exception.SpeechUnsupportedFileException
 import com.didit.application.retrospect.exception.SummaryNotGeneratedException
 import com.didit.application.retrospect.provided.RetrospectiveFinder
@@ -98,6 +99,7 @@ class RetrospectService(
     ): SubmitAnswerResponse = processAnswer(retrospectiveId, userId, content, InputType.TEXT)
 
     @Transactional
+    @Deprecated("Use transcribeVoiceAnswer and submit the edited text through the conversation API")
     override fun submitVoiceAnswer(
         retrospectiveId: UUID,
         userId: UUID,
@@ -113,7 +115,7 @@ class RetrospectService(
 
         if (retrospective.isPending()) retrospective.startProgress()
 
-        val content = transcribe(audioBytes, filename)
+        val content = transcribe(retrospectiveId, audioBytes, filename)
         saveUserAnswer(retrospective, content, currentQuestionType, InputType.STT)
 
         return routeAnswer(retrospective, currentQuestionType).copy(content = content)
@@ -129,7 +131,7 @@ class RetrospectService(
         val retrospective = retrospectiveFinder.findById(retrospectiveId, userId)
         validateRetrospectiveInProgress(retrospective, retrospectiveId)
 
-        return transcribe(audioBytes, filename)
+        return transcribe(retrospectiveId, audioBytes, filename)
     }
 
     @Transactional
@@ -318,23 +320,54 @@ class RetrospectService(
         }
 
     private fun transcribe(
+        retrospectiveId: UUID,
         audioBytes: ByteArray,
         filename: String,
     ): String {
-        if (audioBytes.isEmpty()) throw SpeechEmptyFileException()
-
-        val supportedExtensions = listOf("flac", "mp3", "mp4", "mpeg", "mpga", "m4a", "ogg", "wav", "webm")
         val extension = filename.substringAfterLast('.', "").lowercase()
-
-        if (extension !in supportedExtensions) {
-            throw SpeechUnsupportedFileException(filename, null)
+        return try {
+            if (audioBytes.isEmpty()) throw SpeechEmptyFileException()
+
+            val supportedExtensions = listOf("flac", "mp3", "mp4", "mpeg", "mpga", "m4a", "ogg", "wav", "webm")
+            if (extension !in supportedExtensions) {
+                throw SpeechUnsupportedFileException(filename, null)
+            }
+
+            val text =
+                try {
+                    speechClient.transcribe(audioBytes, filename).trim()
+                } catch (exception: SpeechTranscriptionFailedException) {
+                    throw exception
+                } catch (exception: Exception) {
+                    throw SpeechTranscriptionFailedException(
+                        "providerFailure: ${exception::class.simpleName}",
+                        exception,
+                    )
+                }
+
+            if (text.isBlank()) throw SpeechEmptyResultException()
+            text
+        } catch (exception: Exception) {
+            if (exception is SpeechTranscriptionFailedException) {
+                logger.warn(
+                    "음성 변환 실패 - retrospectiveId: {}, extension: {}, fileSize: {}, failureType: {}",
+                    retrospectiveId,
+                    extension,
+                    audioBytes.size,
+                    exception::class.simpleName,
+                    exception,
+                )
+            } else {
+                logger.warn(
+                    "음성 변환 실패 - retrospectiveId: {}, extension: {}, fileSize: {}, failureType: {}",
+                    retrospectiveId,
+                    extension,
+                    audioBytes.size,
+                    exception::class.simpleName,
+                )
+            }
+            throw exception
         }
-
-        val text = speechClient.transcribe(audioBytes, filename).trim()
-
-        if (text.isBlank()) throw SpeechEmptyResultException()
-
-        return text
     }
 
     private fun validateRetrospectiveInProgress(
@@ -343,6 +376,9 @@ class RetrospectService(
     ) {
         if (retrospective.isCompleted()) throw RetrospectiveAlreadyCompletedException(retrospectiveId)
         if (retrospective.isDeleted()) throw RetrospectiveNotInProgressException(retrospectiveId)
+        if (retrospective.isV2() && !retrospective.isConversationActive()) {
+            throw RetrospectiveNotInProgressException(retrospectiveId)
+        }
     }
 
     private fun saveUserAnswer(

src/main/kotlin/com/didit/application/retrospect/RetrospectiveConversationV2Service.kt

@@ -32,6 +32,7 @@ import com.didit.domain.retrospect.ChatMessage
 import com.didit.domain.retrospect.ConversationMessageType
 import com.didit.domain.retrospect.ConversationStatus
 import com.didit.domain.retrospect.ConversationTurnStatus
+import com.didit.domain.retrospect.InputType
 import com.didit.domain.retrospect.MessageRelevance
 import com.didit.domain.retrospect.Retrospective
 import com.didit.domain.retrospect.RetrospectiveAnalysisEvidence
@@ -98,10 +99,11 @@ class RetrospectiveConversationV2Service(
         userId: UUID,
         clientMessageId: UUID,
         content: String,
+        inputType: InputType,
     ): SubmitConversationMessageResult {
         val preparation =
             metrics.recordStage("conversation_v2", "prepare") {
-                prepareTurn(retrospectiveId, userId, clientMessageId, content)
+                prepareTurn(retrospectiveId, userId, clientMessageId, content, inputType)
             }
         preparation.cachedResult?.let {
             metrics.incrementConversationDuplicate()
@@ -182,6 +184,7 @@ class RetrospectiveConversationV2Service(
         userId: UUID,
         clientMessageId: UUID,
         content: String,
+        inputType: InputType,
     ): TurnPreparation =
         transactionTemplate.execute {
             val retrospective = findV2ForUpdate(retrospectiveId, userId)
@@ -190,7 +193,9 @@ class RetrospectiveConversationV2Service(
             val existing = turnRepository.findByRetrospectiveIdAndClientMessageId(retrospectiveId, clientMessageId)
             if (existing != null) {
                 val userMessage = chatMessageRepository.findById(existing.userMessageId) ?: error("사용자 메시지를 찾을 수 없습니다.")
-                if (userMessage.content != content) throw DuplicateMessageContentMismatchException(clientMessageId)
+                if (userMessage.content != content || userMessage.inputType != inputType) {
+                    throw DuplicateMessageContentMismatchException(clientMessageId)
+                }
                 when (existing.status) {
                     ConversationTurnStatus.PROCESSING -> throw ConversationTurnInProgressException(retrospectiveId)
                     ConversationTurnStatus.COMPLETED ->
@@ -219,7 +224,7 @@ class RetrospectiveConversationV2Service(
             }
 
             if (retrospective.isPending()) retrospective.startProgress()
-            val userMessage = ChatMessage.v2UserMessage(retrospective, content)
+            val userMessage = ChatMessage.v2UserMessage(retrospective, content, inputType)
             retrospective.addMessage(userMessage)
             retrospectiveRepository.save(retrospective)
             val turn =

src/main/kotlin/com/didit/application/retrospect/exception/RetrospectException.kt

@@ -64,10 +64,15 @@ class SpeechUnsupportedFileException(
 
 class SpeechTranscriptionFailedException(
     message: String,
+    cause: Throwable? = null,
 ) : BusinessException(
         RetrospectErrorCode.SPEECH_TRANSCRIPTION_FAILED,
         message,
-    )
+    ) {
+    init {
+        if (cause != null) initCause(cause)
+    }
+}
 
 class SpeechEmptyResultException : BusinessException(RetrospectErrorCode.SPEECH_EMPTY_RESULT)
 

src/main/kotlin/com/didit/application/retrospect/provided/RetrospectiveConversationV2.kt

@@ -4,6 +4,7 @@ import com.didit.application.retrospect.dto.ConversationV2Result
 import com.didit.application.retrospect.dto.FinishConversationV2Result
 import com.didit.application.retrospect.dto.StartConversationV2Result
 import com.didit.application.retrospect.dto.SubmitConversationMessageResult
+import com.didit.domain.retrospect.InputType
 import java.util.UUID
 
 interface RetrospectiveConversationV2 {
@@ -14,6 +15,14 @@ interface RetrospectiveConversationV2 {
         userId: UUID,
         clientMessageId: UUID,
         content: String,
+    ): SubmitConversationMessageResult = submitMessage(retrospectiveId, userId, clientMessageId, content, InputType.TEXT)
+
+    fun submitMessage(
+        retrospectiveId: UUID,
+        userId: UUID,
+        clientMessageId: UUID,
+        content: String,
+        inputType: InputType,
     ): SubmitConversationMessageResult
 
     fun getConversation(

src/main/kotlin/com/didit/application/retrospect/provided/RetrospectiveRegister.kt

@@ -14,6 +14,7 @@ interface RetrospectiveRegister {
         content: String,
     ): SubmitAnswerResponse
 
+    @Deprecated("Use transcribeVoiceAnswer and submit the edited text through the conversation API")
     fun submitVoiceAnswer(
         retrospectiveId: UUID,
         userId: UUID,

src/main/kotlin/com/didit/domain/retrospect/ChatMessage.kt

@@ -115,14 +115,20 @@ class ChatMessage(
         fun v2UserMessage(
             retrospective: Retrospective,
             content: String,
+        ): ChatMessage = v2UserMessage(retrospective, content, InputType.TEXT)
+
+        fun v2UserMessage(
+            retrospective: Retrospective,
+            content: String,
+            inputType: InputType,
         ): ChatMessage {
             require(content.isNotBlank()) { "회고 내용은 비어 있을 수 없습니다." }
             return ChatMessage(
                 retrospective = retrospective,
                 sender = Sender.USER,
                 content = content,
                 questionType = QuestionType.V2_CHAT,
-                inputType = InputType.TEXT,
+                inputType = inputType,
                 messageType = ConversationMessageType.CONVERSATION,
                 includedInResult = false,
             )

src/test/kotlin/com/didit/adapter/webapi/retrospect/RetrospectApiTest.kt

@@ -49,6 +49,7 @@ import java.time.LocalDate
 import java.time.LocalDateTime
 import java.util.UUID
 
+@Suppress("DEPRECATION")
 class RetrospectApiTest : AuthenticatedRestDocsSupport() {
     private val retrospectiveRegister: RetrospectiveRegister = mock(RetrospectiveRegister::class.java)
     private val retrospectiveFinder: RetrospectiveFinder = mock(RetrospectiveFinder::class.java)