문서 정리: 불필요한 claudedocs 파일 삭제 및 설계서 업데이트

- API 설계 가이드 업데이트 - 중복/과거 분석 문서 정리 (API누락요약표, API리뷰, 설계서업데이트요약) - 유저스토리 업데이트 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-06-12 22:59:10 +00:00 · 2025-10-29 18:00:00 +09:00
parent d2f396cffb
commit fb418cface
5 changed files with 99 additions and 1364 deletions
@@ -1,115 +1,111 @@
-# STT Service API 설계 완료
+# API설계가이드

-## 작업 결과
+[요청사항]  
+- <작성원칙>을 준용하여 설계
+- <작성순서>에 따라 설계
+- [결과파일] 안내에 따라 파일 작성 
+- 최종 완료 후 API 확인 방법 안내 
+  - https://editor.swagger.io/ 접근  
+  - 생성된 swagger yaml파일을 붙여서 확인 및 테스트  

-### 생성된 파일
- **파일 경로**: `C:\Users\KTDS\home\workspace\HGZero\design\backend\api\stt-service-api.yaml`
- **형식**: OpenAPI 3.0.3
- **검증 상태**: ✅ 검증 완료 (swagger-cli)
+[가이드]  
+<작성 원칙>
+- 각 서비스 API는 독립적으로 완전한 명세를 포함
+- 공통 스키마는 각 서비스에서 필요에 따라 직접 정의
+- 서비스 간 의존성을 최소화하여 독립 배포 가능
+- 중복되는 스키마가 많아질 경우에만 공통 파일 도입 검토
+<작성순서>
+- 준비: 
+  - 유저스토리, 외부시퀀스설계서, 내부시퀀스설계서 분석 및 이해 
+- 실행:
+  - <병렬처리> 안내에 따라 동시 수행
+  - <API선정원칙>에 따라 API 선정 
+  - <파일작성안내>에 따라 작성  
+  - <검증방법>에 따라 작성된 YAML의 문법 및 구조 검증 수행
+- 검토:
+  - <작성원칙> 준수 검토
+  - 스쿼드 팀원 리뷰: 누락 및 개선 사항 검토
+  - 수정 사항 선택 및 반영 

-### API 개요
+<API선정원칙>
+- 유저스토리와 매칭 되어야 함. 불필요한 추가 설계 금지  
+  (유저스토리 ID를 x-user-story 확장 필드에 명시)
+- '외부시퀀스설계서'/'내부시퀀스설계서'와 일관성 있게 선정 

-#### 1. Recording API (음성 녹음 관리)
- `POST /recordings/prepare` - 회의 녹음 준비
- `POST /recordings/{recordingId}/start` - 음성 녹음 시작
- `POST /recordings/{recordingId}/stop` - 음성 녹음 중지
- `GET /recordings/{recordingId}` - 녹음 정보 조회
+<파일작성안내>
+- OpenAPI 3.0 스펙 준용 
+- **servers 섹션 필수화**
+  - 모든 OpenAPI 명세에 servers 섹션 포함
+  - SwaggerHub Mock URL을 첫 번째 옵션으로 배치
+- **example 데이터 권장**
+  - 스키마에 example을 추가하여 Swagger UI에서 테스트 할 수 있게함 
+- **테스트 시나리오 포함**
+  - 각 API 엔드포인트별 테스트 케이스 정의
+  - 성공/실패 케이스 모두 포함
+- 작성 형식
+  - YAML 형식의 OpenAPI 3.0 명세
+  - 각 API별 필수 항목:
+    - summary: API 목적 설명
+    - operationId: 고유 식별자
+    - x-user-story: 유저스토리 ID
+    - x-controller: 담당 컨트롤러
+    - tags: API 그룹 분류
+    - requestBody/responses: 상세 스키마
+  - 각 서비스 파일에 필요한 모든 스키마 포함:
+    - components/schemas: 요청/응답 모델
+    - components/parameters: 공통 파라미터
+    - components/responses: 공통 응답
+    - components/securitySchemes: 인증 방식

-#### 2. Transcription API (음성-텍스트 변환)
- `POST /transcripts/stream` - 실시간 음성-텍스트 변환 (스트리밍)
- `POST /transcripts/batch` - 배치 음성-텍스트 변환
- `POST /transcripts/callback` - 배치 변환 완료 콜백
- `GET /transcripts/{recordingId}` - 변환 텍스트 전체 조회
+<파일 구조>
+```
+design/backend/api/
+├── {service-name}-api.yaml      # 각 마이크로서비스별 API 명세
+└── ...                          # 추가 서비스들

-#### 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 접속
+예시:
+├── profile-service-api.yaml     # 프로파일 서비스 API
+├── order-service-api.yaml       # 주문 서비스 API
+└── payment-service-api.yaml     # 결제 서비스 API
 ```

-#### 3. VS Code Extension
- **확장**: Swagger Viewer
- YAML 파일 열고 `Shift + Alt + P` 실행
- 미리보기에서 API 문서 확인
+- 파일명 규칙
+  - 서비스명은 kebab-case로 작성
+  - 파일명 형식: {service-name}-api.yaml
+  - 서비스명은 유저스토리의 '서비스' 항목을 영문으로 변환하여 사용

-### 설계 원칙 준수
+<병렬처리>
+- **의존성 분석 선행**: 병렬 처리 전 반드시 의존성 파악
+- **순차 처리 필요시**: 무리한 병렬화보다는 안전한 순차 처리
+- **검증 단계 필수**: 병렬 처리 후 통합 검증

-✅ **유저스토리 기반 설계**
- 모든 API에 x-user-story 필드 명시
- 불필요한 API 추가 없음
+<검증방법>
+- swagger-cli를 사용한 자동 검증 수행
+- 검증 명령어: `swagger-cli validate {파일명}`
+- swagger-cli가 없을 경우 자동 설치:
+  ```bash
+  # swagger-cli 설치 확인 및 자동 설치
+  command -v swagger-cli >/dev/null 2>&1 || npm install -g @apidevtools/swagger-cli
+  
+  # 검증 실행
+  swagger-cli validate design/backend/api/*.yaml
+  ```
+- 검증 항목:
+  - OpenAPI 3.0 스펙 준수
+  - YAML 구문 오류
+  - 스키마 참조 유효성
+  - 필수 필드 존재 여부

-✅ **시퀀스 일관성**
- 내부 시퀀스 설계와 완전히 일치
- 모든 처리 흐름 반영
+[참고자료]
+- 유저스토리
+- 외부시퀀스설계서
+- 내부시퀀스설계서
+- OpenAPI 스펙: https://swagger.io/specification/

-✅ **OpenAPI 3.0 표준**
- servers 섹션 필수 포함
- 완전한 스키마 정의
- JWT 인증 방식 명시
+[예시]
+- swagger api yaml: https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/samples/sample-swagger-api.yaml
+- API설계서: https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/samples/sample-API%20설계서.md

-✅ **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
+[결과파일]
+- 각 서비스별로 별도의 YAML 파일 생성 
+- design/backend/api/*.yaml (OpenAPI 형식)