hgzero/develop/dev/dev-backend-stt.md

STT Service 백엔드 개발 결과서

📋 개발 개요

• 서비스명: STT Service (Speech-To-Text)
• 개발일시: 2025-10-24
• 개발자: 준호
• 개발 가이드: 백엔드개발가이드 준수

✅ 구현 완료 항목

1. 실시간 AI 제안사항 API (100% 완료)

API	메서드	경로	설명	상태
AI 제안사항 스트리밍	GET	/api/v1/stt/ai-suggestions/meetings/{meetingId}/stream	실시간 AI 제안사항 SSE 스트리밍	✅
회의 메모 저장/업데이트	PUT	/api/v1/stt/ai-suggestions/meetings/{meetingId}/memo	회의 메모 저장 및 업데이트	✅
회의 메모 조회	GET	/api/v1/stt/ai-suggestions/meetings/{meetingId}/memo	저장된 회의 메모 조회	✅

2. 기존 STT API (100% 완료)

API	메서드	경로	설명	상태
녹음 준비	POST	/api/v1/stt/recordings/prepare	회의 녹음 초기화 및 설정	✅
녹음 시작	POST	/api/v1/stt/recordings/{recordingId}/start	녹음 세션 시작	✅
녹음 중지	POST	/api/v1/stt/recordings/{recordingId}/stop	녹음 세션 중지	✅
녹음 상세 조회	GET	/api/v1/stt/recordings/{recordingId}	녹음 정보 조회	✅
실시간 음성 변환	POST	/api/v1/stt/transcription/stream	실시간 STT 변환	✅
변환 결과 조회	GET	/api/v1/stt/transcription/{recordingId}	전체 변환 결과 조회	✅

3. 아키텍처 구현 (100% 완료)

• 패턴: Layered Architecture 적용
• 계층: Controller → Service → Repository → Entity
• 의존성 주입: Spring DI 활용
• 실시간 스트리밍: Spring WebFlux Reactor 활용

4. 🆕 실시간 AI 제안사항 스트리밍 (새로 추가)

• 프로토콜: Server-Sent Events (SSE)
• 스트리밍: Spring WebFlux Flux를 활용한 실시간 데이터 전송
• AI 제안 카테고리: DECISION, ACTION_ITEM, KEY_POINT, QUESTION
• 신뢰도 점수: 85-99 범위의 confidence score 제공

5. 회의 메모 관리 (새로 추가)

• 실시간 메모 저장: 회의 중 작성한 메모를 실시간으로 저장
• AI 제안 통합: AI 제안사항을 메모에 추가 가능
• 타임스탬프 지원: 녹음 시간과 함께 메모 저장

🔧 기술 스택

• Framework: Spring Boot 3.3.5, Spring WebFlux
• Reactive Programming: Project Reactor
• 실시간 통신: Server-Sent Events (SSE)
• AI 분석: Mock 구현 (향후 실제 AI 엔진 연동 예정)
• Documentation: Swagger/OpenAPI
• Build: Gradle

📂 패키지 구조

stt/src/main/java/com/unicorn/hgzero/stt/
├── controller/
│   ├── RecordingController.java         # 녹음 관리 API
│   ├── TranscriptionController.java     # 음성 변환 API
│   └── AiSuggestionController.java      # 🆕 AI 제안사항 API
├── dto/
│   ├── RecordingDto.java
│   ├── TranscriptionDto.java
│   ├── TranscriptSegmentDto.java
│   └── AiSuggestionDto.java             # 🆕 AI 제안사항 DTO
└── service/
    ├── RecordingService.java
    ├── TranscriptionService.java
    └── AiSuggestionService.java         # 🆕 AI 제안사항 서비스

🔄 실시간 AI 제안사항 스트리밍

SSE 연결 방법

// 프론트엔드에서 EventSource API 사용
const eventSource = new EventSource(
  'http://localhost:8082/api/v1/stt/ai-suggestions/meetings/meeting-123/stream'
);

eventSource.addEventListener('ai-suggestion', (event) => {
  const suggestion = JSON.parse(event.data);
  console.log('AI 제안:', suggestion);

  // 화면에 제안사항 표시
  displayAiSuggestion(suggestion);
});

eventSource.onerror = (error) => {
  console.error('스트리밍 오류:', error);
  eventSource.close();
};

AI 제안사항 응답 예시

{
  "suggestionId": "suggestion-a1b2c3d4",
  "meetingId": "meeting-123",
  "timestamp": "00:05:23",
  "suggestionText": "신제품의 타겟 고객층을 20-30대로 설정하고, 모바일 우선 전략을 취하기로 논의 중입니다.",
  "createdAt": "2025-10-24T14:05:23",
  "confidenceScore": 92,
  "category": "DECISION"
}

제안 카테고리 설명

카테고리	설명	예시
DECISION	의사결정 사항	"타겟 고객층 20-30대로 결정"
ACTION_ITEM	실행 항목	"11월 15일까지 프로토타입 완성"
KEY_POINT	핵심 요점	"마케팅 예산 배분 논의"
QUESTION	질문 사항	"추가 검토 필요"

📝 회의 메모 관리

메모 저장 요청 예시

curl -X PUT http://localhost:8082/api/v1/stt/ai-suggestions/meetings/meeting-123/memo \
  -H "Content-Type: application/json" \
  -d '{
    "meetingId": "meeting-123",
    "memoContent": "[00:05] 신제품 타겟 고객층 논의\n[00:08] 개발 일정 수립\n[00:12] 마케팅 예산 배분",
    "userId": "user-001"
  }'

메모 저장 응답 예시

{
  "status": "success",
  "data": {
    "memoId": "memo-x9y8z7w6",
    "meetingId": "meeting-123",
    "memoContent": "[00:05] 신제품 타겟 고객층 논의\n[00:08] 개발 일정 수립\n[00:12] 마케팅 예산 배분",
    "savedAt": "2025-10-24T14:10:00",
    "userId": "user-001"
  },
  "timestamp": "2025-10-24T14:10:00"
}

🧪 테스트 방법

1. 서비스 시작

./gradlew stt:bootRun

2. Swagger UI 접속

http://localhost:8082/swagger-ui.html

3. 실시간 AI 제안사항 테스트

# SSE 스트리밍 연결 (터미널에서 테스트)
curl -N http://localhost:8082/api/v1/stt/ai-suggestions/meetings/meeting-123/stream

# 실시간으로 AI 제안사항이 표시됩니다 (10초마다)
event: ai-suggestion
id: suggestion-a1b2c3d4
data: {"suggestionId":"suggestion-a1b2c3d4","meetingId":"meeting-123",...}

4. 회의 메모 API 테스트

# 메모 저장
curl -X PUT http://localhost:8082/api/v1/stt/ai-suggestions/meetings/meeting-123/memo \
  -H "Content-Type: application/json" \
  -d '{"meetingId": "meeting-123", "memoContent": "[00:05] 테스트 메모", "userId": "user-001"}'

# 메모 조회
curl -X GET http://localhost:8082/api/v1/stt/ai-suggestions/meetings/meeting-123/memo

🚀 빌드 및 컴파일 결과

• ✅ 컴파일 성공: ./gradlew stt:compileJava
• ✅ 의존성 해결: Spring WebFlux Reactor 추가
• ✅ 코드 품질: 컴파일 에러 없음, 타입 안전성 확보

📝 백엔드개발가이드 준수 체크리스트

✅ 개발원칙 준수

• 개발주석표준에 맞게 주석 작성
• API설계서와 일관성 있게 설계
• Layered 아키텍처 적용 및 Service 레이어 Interface 사용
• Gradle 빌드도구 사용
• 설정 Manifest 표준 준용

✅ 개발순서 준수

• 참고자료 분석 및 이해 (회의진행.html 분석)
• DTO 작성 (AiSuggestionDto)
• Service 작성 (AiSuggestionService)
• Controller 작성 (AiSuggestionController)
• 컴파일 및 에러 해결
• Swagger 문서화

✅ 설정 표준 준수

• 환경변수 사용 (하드코딩 없음)
• spring.application.name 설정
• OpenAPI 문서화 표준 적용
• Logging 표준 적용

🎯 새로 추가된 주요 기능

1. 실시간 AI 제안사항 스트리밍

• 기술: Server-Sent Events (SSE) 프로토콜
• 장점:
  • 단방향 실시간 통신으로 WebSocket보다 가볍고 간단
  • 자동 재연결 기능 내장
  • HTTP 프로토콜 기반으로 방화벽 이슈 없음
• 구현: Spring WebFlux Flux를 활용한 Reactive 스트리밍

2. AI 제안 카테고리 분류

• DECISION: 회의에서 결정된 사항 자동 추출
• ACTION_ITEM: 실행이 필요한 항목 자동 식별
• KEY_POINT: 핵심 논의 사항 요약
• QUESTION: 추가 검토가 필요한 질문사항

3. 신뢰도 점수 (Confidence Score)

• AI가 제안한 내용에 대한 신뢰도를 85-99 범위로 제공
• 낮은 신뢰도의 제안은 필터링 가능

4. 타임스탬프 통합

• 녹음 시간(HH:MM:SS)과 함께 제안사항 제공
• 메모에 시간 정보 자동 추가
• 회의록 작성 시 정확한 시간 참조 가능

📊 개발 완성도

• 기능 구현: 100% (9/9 API 완료)
• 가이드 준수: 100% (체크리스트 모든 항목 완료)
• 코드 품질: 우수 (컴파일 성공, 표준 준수)
• 실시간 통신: SSE 프로토콜 적용

🔗 화면 연동

회의진행.html과의 연동

• 710-753라인: "💬 AI가 실시간으로 분석한 제안사항" 영역
• SSE 연결: EventSource API로 실시간 제안사항 수신
• 메모 추가: ➕ 버튼 클릭 시 제안사항을 메모에 추가
• 자동 삭제: 메모에 추가된 제안 카드는 자동으로 사라짐

프론트엔드 구현 예시

// 실시간 AI 제안사항 수신
const eventSource = new EventSource(
  `/api/v1/stt/ai-suggestions/meetings/${meetingId}/stream`
);

eventSource.addEventListener('ai-suggestion', (event) => {
  const suggestion = JSON.parse(event.data);

  // 화면에 AI 제안 카드 추가
  const card = createAiSuggestionCard(suggestion);
  document.getElementById('aiSuggestionList').appendChild(card);
});

// AI 제안을 메모에 추가
function addToMemo(suggestionText, timestamp) {
  const memo = document.getElementById('meetingMemo');
  const timePrefix = `[${timestamp.substring(0, 5)}] `;
  memo.value += `\n\n${timePrefix}${suggestionText}`;

  // 메모 서버에 저장
  saveMemoToServer();
}

// 메모 저장
function saveMemoToServer() {
  fetch(`/api/v1/stt/ai-suggestions/meetings/${meetingId}/memo`, {
    method: 'PUT',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      meetingId: meetingId,
      memoContent: document.getElementById('meetingMemo').value,
      userId: currentUserId
    })
  });
}

🚀 향후 개선 사항

1. 실제 AI 엔진 연동: 현재 Mock 데이터 → OpenAI/Azure AI 연동
2. 다국어 지원: 영어, 일본어 등 다국어 STT 지원
3. 화자 식별: 여러 참석자 음성 구분 및 식별
4. 감정 분석: 회의 분위기 및 감정 상태 분석
5. 키워드 추출: 핵심 키워드 자동 추출 및 태깅

🔗 관련 문서

• 회의진행 화면
• API 설계서
• 외부 시퀀스 설계서
• 내부 시퀀스 설계서