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 연결 방법
```javascript
// 프론트엔드에서 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 제안사항 응답 예시
```json
{
  "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 | 질문 사항 | "추가 검토 필요" |

## 📝 회의 메모 관리

### 메모 저장 요청 예시
```bash
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"
  }'
```

### 메모 저장 응답 예시
```json
{
  "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. 서비스 시작
```bash
./gradlew stt:bootRun
```

### 2. Swagger UI 접속
```
http://localhost:8082/swagger-ui.html
```

### 3. 실시간 AI 제안사항 테스트
```bash
# 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 테스트
```bash
# 메모 저장
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 추가
- ✅ **코드 품질**: 컴파일 에러 없음, 타입 안전성 확보

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

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

### ✅ 개발순서 준수
- [x] 참고자료 분석 및 이해 (회의진행.html 분석)
- [x] DTO 작성 (AiSuggestionDto)
- [x] Service 작성 (AiSuggestionService)
- [x] Controller 작성 (AiSuggestionController)
- [x] 컴파일 및 에러 해결
- [x] Swagger 문서화

### ✅ 설정 표준 준수
- [x] 환경변수 사용 (하드코딩 없음)
- [x] spring.application.name 설정
- [x] OpenAPI 문서화 표준 적용
- [x] 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로 실시간 제안사항 수신
- **메모 추가**: ➕ 버튼 클릭 시 제안사항을 메모에 추가
- **자동 삭제**: 메모에 추가된 제안 카드는 자동으로 사라짐

### 프론트엔드 구현 예시
```javascript
// 실시간 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. **키워드 추출**: 핵심 키워드 자동 추출 및 태깅

## 🔗 관련 문서
- [회의진행 화면](../../design/uiux/prototype/05-회의진행.html)
- [API 설계서](../../design/backend/api/)
- [외부 시퀀스 설계서](../../design/backend/sequence/outer/)
- [내부 시퀀스 설계서](../../design/backend/sequence/inner/)