# STT Service API 설계 완료

## 작업 결과

### 생성된 파일
- **파일 경로**: `C:\Users\KTDS\home\workspace\HGZero\design\backend\api\stt-service-api.yaml`
- **형식**: OpenAPI 3.0.3
- **검증 상태**: ✅ 검증 완료 (swagger-cli)

### API 개요

#### 1. Recording API (음성 녹음 관리)
- `POST /recordings/prepare` - 회의 녹음 준비
- `POST /recordings/{recordingId}/start` - 음성 녹음 시작
- `POST /recordings/{recordingId}/stop` - 음성 녹음 중지
- `GET /recordings/{recordingId}` - 녹음 정보 조회

#### 2. Transcription API (음성-텍스트 변환)
- `POST /transcripts/stream` - 실시간 음성-텍스트 변환 (스트리밍)
- `POST /transcripts/batch` - 배치 음성-텍스트 변환
- `POST /transcripts/callback` - 배치 변환 완료 콜백
- `GET /transcripts/{recordingId}` - 변환 텍스트 전체 조회

#### 3. Speaker API (화자 식별 및 관리)
- `POST /speakers/identify` - 화자 식별
- `GET /speakers/{speakerId}` - 화자 정보 조회
- `PUT /speakers/{speakerId}` - 화자 정보 업데이트
- `GET /recordings/{recordingId}/speakers` - 녹음의 화자 목록 조회

### 주요 특징

#### 1. 유저스토리 매핑
모든 API는 유저스토리와 매핑되어 있습니다:
- **UFR-STT-010** (음성녹음인식): Recording API, Speaker API
- **UFR-STT-020** (텍스트변환): Transcription API

#### 2. 완전한 스키마 정의
- 25개의 스키마 정의
- 모든 Request/Response 모델 포함
- Example 데이터 포함으로 Swagger UI에서 즉시 테스트 가능

#### 3. Azure 통합
- Azure Speech Service 연동
- Azure Blob Storage 통합
- Azure Event Hubs 이벤트 발행

#### 4. 실시간 처리
- WebSocket 기반 스트리밍 지원
- 실시간 인식 지연: < 1초
- 화자 식별 정확도: > 90%

#### 5. 성능 정보
각 API의 예상 처리 시간 명시:
- 녹음 준비: ~1.1초
- 실시간 변환: 1-4초
- 배치 변환: 7-33초

### API 확인 방법

#### 1. Swagger Editor 사용
1. https://editor.swagger.io/ 접속
2. 생성된 YAML 파일 내용 복사하여 붙여넣기
3. 우측 패널에서 API 문서 확인 및 테스트

#### 2. 로컬 Swagger UI 실행
```bash
# Swagger UI Docker 실행
docker run -p 8080:8080 -e SWAGGER_JSON=/api/stt-service-api.yaml \
  -v C:\Users\KTDS\home\workspace\HGZero\design\backend\api:/api \
  swaggerapi/swagger-ui

# 브라우저에서 http://localhost:8080 접속
```

#### 3. VS Code Extension
- **확장**: Swagger Viewer
- YAML 파일 열고 `Shift + Alt + P` 실행
- 미리보기에서 API 문서 확인

### 설계 원칙 준수

✅ **유저스토리 기반 설계**
- 모든 API에 x-user-story 필드 명시
- 불필요한 API 추가 없음

✅ **시퀀스 일관성**
- 내부 시퀀스 설계와 완전히 일치
- 모든 처리 흐름 반영

✅ **OpenAPI 3.0 표준**
- servers 섹션 필수 포함
- 완전한 스키마 정의
- JWT 인증 방식 명시

✅ **Example 데이터**
- 모든 스키마에 example 포함
- 실제 테스트 가능한 데이터

✅ **검증 완료**
- swagger-cli 자동 검증 통과
- YAML 구문 오류 없음
- 스키마 참조 유효성 확인

### 다음 단계

1. **Meeting Service API 설계** (회의, 회의록, Todo 통합)
2. **AI Service API 설계** (회의록 자동 작성, RAG 기능)
3. **User Service API 설계** (인증 전용)
4. **Notification Service API 설계** (알림 발송)

---

**작성자**: 준호 (Backend Developer)
**작성일**: 2025-01-23
**검증 도구**: swagger-cli v4.0.4