mirror of
https://github.com/hwanny1128/HGZero.git
synced 2025-12-06 23:06:23 +00:00
a551235ad7
- 5개 마이크로서비스 API 명세 작성 (User, Meeting, STT, AI, Notification) - OpenAPI 3.0 표준 준수 - 총 47개 API 설계 - 유저스토리 100% 커버리지 - swagger-cli 검증 통과 - 종합 API 설계서 작성 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
116 lines
3.5 KiB
Markdown
116 lines
3.5 KiB
Markdown
# 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
|