shared-dg05-coffeeQuokka/hgzero
1
0
Fork 0
mirror of https://github.com/hwanny1128/HGZero.git synced 2025-12-06 07:56:24 +00:00
Code Issues Packages Projects Releases Wiki Activity
hgzero/design/backend/api/API설계서.md
ondal a551235ad7 API 설계 완료 
- 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>
2025-10-23 10:49:29 +09:00

472 lines
16 KiB
Markdown
Raw Blame History

# API 설계서
회의록 작성 및 공유 개선 서비스
---
## 📋 목차
1. [개요](#개요)
2. [API 설계 원칙](#api-설계-원칙)
3. [마이크로서비스별 API](#마이크로서비스별-api)
4. [공통 사항](#공통-사항)
5. [API 확인 방법](#api-확인-방법)
---
## 개요
### 프로젝트 정보
- **프로젝트명**: 회의록 작성 및 공유 개선 서비스
- **설계 버전**: v2.0
- **설계일**: 2025-01-23
- **설계자**: 아키텍트(길동), Backend Developer(준호)
### 마이크로서비스 구성
본 서비스는 5개의 마이크로서비스로 구성됩니다:
1. **User Service** - 사용자 인증 (LDAP 연동, JWT 토큰 발급/검증)
2. **Meeting Service** - 회의, 회의록, Todo, 실시간 협업 통합 관리
3. **STT Service** - 음성 녹음 관리, 음성-텍스트 변환, 화자 식별
4. **AI Service** - AI 기반 회의록 자동화, Todo 추출, 지능형 검색 (RAG 통합)
5. **Notification Service** - 알림 발송 및 리마인더 관리
---
## API 설계 원칙
### 1. 설계 기준
- **유저스토리 기반**: 모든 API는 유저스토리와 매핑 (x-user-story 필드)
- **시퀀스 일치**: 외부/내부 시퀀스 설계서와 100% 일치
- **OpenAPI 3.0**: OpenAPI 3.0.3 표준 준수
- **컨트롤러 명시**: 각 API별 담당 컨트롤러 명시 (x-controller 필드)
### 2. 공통 표준
- **인증 방식**: JWT Bearer Token
- **요청 헤더**: 모든 API 요청에 사용자 정보 포함
- `X-User-Id`: 사용자 ID
- `X-User-Name`: 사용자 이름
- `X-User-Email`: 사용자 이메일
- **응답 형식**: JSON
- **에러 응답**: 표준화된 에러 응답 형식
### 3. 서비스 독립성
- **각 서비스별 독립적인 OpenAPI 명세**
- **서비스별 모든 스키마 포함**
- **중복 스키마 허용** (초기 단계)
- **독립 배포 가능**
---
## 마이크로서비스별 API
### 1. User Service
#### 개요
- **파일**: `user-service-api.yaml`
- **베이스 URL**: `/api/v1`
- **주요 기능**: 사용자 인증 전용 (LDAP 인증, JWT 토큰 관리)
#### API 목록
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|--------|----------|------|-----------|----------|
| POST | /auth/login | 사용자 로그인 | AFR-USER-010 | UserController |
| POST | /auth/refresh | Access Token 갱신 | AFR-USER-010 | UserController |
| POST | /auth/logout | 로그아웃 | AFR-USER-010 | UserController |
| GET | /auth/validate | 토큰 검증 | AFR-USER-010 | UserController |
#### 주요 특징
- LDAP 인증 (LDAPS, port 636)
- JWT 토큰 관리 (Access: 1시간, Refresh: 7일)
- 계정 잠금 기능 (5회 실패 시 30분)
- Redis 기반 Refresh Token 관리
---
### 2. Meeting Service
#### 개요
- **파일**: `meeting-service-api.yaml`
- **베이스 URL**: `/api/v1`
- **주요 기능**: 회의, 회의록, Todo, 실시간 협업 통합 관리
#### API 목록
**Dashboard APIs (1개)**
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|--------|----------|------|-----------|----------|
| GET | /dashboard | 대시보드 데이터 조회 | AFR-USER-020 | DashboardController |
**Meeting APIs (4개)**
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|--------|----------|------|-----------|----------|
| POST | /meetings | 회의 예약 | UFR-MEET-010 | MeetingController |
| PUT | /meetings/{meetingId}/template | 템플릿 선택 | UFR-MEET-020 | MeetingController |
| POST | /meetings/{meetingId}/start | 회의 시작 | UFR-MEET-030 | MeetingController |
| POST | /meetings/{meetingId}/end | 회의 종료 | UFR-MEET-040 | MeetingController |
**Minutes APIs (7개)**
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|--------|----------|------|-----------|----------|
| GET | /minutes | 회의록 목록 조회 | UFR-MEET-046 | MinutesController |
| GET | /minutes/{minutesId} | 회의록 상세 조회 | UFR-MEET-047 | MinutesController |
| PATCH | /minutes/{minutesId} | 회의록 수정 | UFR-MEET-055 | MinutesController |
| POST | /minutes/{minutesId}/finalize | 회의록 확정 | UFR-MEET-050 | MinutesController |
| POST | /minutes/{minutesId}/sections/{sectionId}/verify | 섹션 검증 완료 | UFR-COLLAB-030 | MinutesController |
| POST | /minutes/{minutesId}/sections/{sectionId}/lock | 섹션 잠금 | UFR-COLLAB-030 | MinutesController |
| DELETE | /minutes/{minutesId}/sections/{sectionId}/lock | 섹션 잠금 해제 | UFR-COLLAB-030 | MinutesController |
**Todo APIs (2개)**
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|--------|----------|------|-----------|----------|
| POST | /todos | Todo 할당 | UFR-TODO-010 | TodoController |
| PATCH | /todos/{todoId}/complete | Todo 완료 처리 | UFR-TODO-030 | TodoController |
**Template APIs (2개)**
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|--------|----------|------|-----------|----------|
| GET | /templates | 템플릿 목록 조회 | UFR-MEET-020 | TemplateController |
| GET | /templates/{templateId} | 템플릿 상세 조회 | UFR-MEET-020 | TemplateController |
**WebSocket Endpoints (1개)**
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|--------|----------|------|-----------|----------|
| GET | /ws/minutes/{minutesId} | 실시간 협업 WebSocket | UFR-COLLAB-010 | WebSocketController |
#### 주요 특징
- WebSocket 기반 실시간 협업
- 충돌 해결 메커니즘 (Last Write Wins)
- 섹션별 검증 및 잠금 기능
- Todo와 회의록 양방향 연결
- 버전 관리
---
### 3. STT Service
#### 개요
- **파일**: `stt-service-api.yaml`
- **베이스 URL**: `/api/v1`
- **주요 기능**: 음성 녹음 관리, 음성-텍스트 변환, 화자 식별
#### API 목록
**Recording APIs (4개)**
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|--------|----------|------|-----------|----------|
| POST | /recordings/prepare | 녹음 준비 | UFR-STT-010 | RecordingController |
| POST | /recordings/{recordingId}/start | 녹음 시작 | UFR-STT-010 | RecordingController |
| POST | /recordings/{recordingId}/stop | 녹음 중지 | UFR-STT-010 | RecordingController |
| GET | /recordings/{recordingId} | 녹음 정보 조회 | UFR-STT-010 | RecordingController |
**Transcription APIs (4개)**
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|--------|----------|------|-----------|----------|
| POST | /transcriptions/stream | 실시간 스트리밍 변환 | UFR-STT-020 | TranscriptionController |
| POST | /transcriptions/batch | 배치 변환 | UFR-STT-020 | TranscriptionController |
| POST | /transcriptions/callback | 변환 완료 콜백 | UFR-STT-020 | TranscriptionController |
| GET | /transcriptions/{recordingId}/full | 전체 텍스트 조회 | UFR-STT-020 | TranscriptionController |
**Speaker APIs (4개)**
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|--------|----------|------|-----------|----------|
| POST | /speakers/identify | 화자 식별 | UFR-STT-010 | SpeakerController |
| GET | /speakers/{speakerId} | 화자 정보 조회 | UFR-STT-010 | SpeakerController |
| PATCH | /speakers/{speakerId} | 화자 정보 수정 | UFR-STT-010 | SpeakerController |
| GET | /recordings/{recordingId}/speakers | 녹음별 화자 목록 | UFR-STT-010 | SpeakerController |
#### 주요 특징
- WebSocket 기반 실시간 스트리밍 (< 1초 지연)
- 화자 식별 정확도 90% 이상
- Azure Speech Service 통합
- Azure Blob Storage 연동
- Azure Event Hubs 비동기 처리
---
### 4. AI Service
#### 개요
- **파일**: `ai-service-api.yaml`
- **베이스 URL**: `/api/v1`
- **주요 기능**: AI 기반 회의록 자동화, Todo 추출, 지능형 검색 (RAG 통합)
#### API 목록
**Transcript Processing APIs (2개)**
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|--------|----------|------|-----------|----------|
| POST | /transcripts/process | 회의록 자동 작성 | UFR-AI-010 | TranscriptController |
| POST | /transcripts/{meetingId}/improve | 회의록 개선 (프롬프팅) | UFR-AI-030 | TranscriptController |
**Todo APIs (1개)**
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|--------|----------|------|-----------|----------|
| POST | /todos/extract | Todo 자동 추출 | UFR-AI-020 | TodoController |
**Related Minutes APIs (1개)**
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|--------|----------|------|-----------|----------|
| GET | /transcripts/{meetingId}/related | 관련 회의록 연결 | UFR-AI-040 | TranscriptController |
**Term Explanation APIs (2개)**
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|--------|----------|------|-----------|----------|
| POST | /terms/detect | 전문용어 감지 | UFR-RAG-010 | TermController |
| GET | /terms/{term}/explain | 맥락 기반 용어 설명 | UFR-RAG-020 | TermController |
**Suggestion APIs (2개)**
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|--------|----------|------|-----------|----------|
| POST | /suggestions/discussion | 논의사항 제안 | UFR-AI-010 | SuggestionController |
| POST | /suggestions/decision | 결정사항 제안 | UFR-AI-010 | SuggestionController |
#### 주요 특징
- LLM 기반 회의록 자동 작성
- 7가지 프롬프트 유형 지원
- 1Page 요약, 핵심 요약, 상세 보고서
- 의사결정 중심, 액션 아이템 중심
- 경영진 보고용, 커스텀
- RAG 기반 관련 회의록 검색 (벡터 유사도 70% 이상)
- 맥락 기반 전문용어 설명
- 실시간 논의사항/결정사항 제안
#### 차별화 포인트
1. **맥락 기반 용어 설명**: 단순 정의가 아닌 조직 내 실제 사용 맥락 제공
2. **프롬프팅 기반 개선**: 다양한 형식의 회의록 생성
3. **실시간 추천**: AI 기반 논의사항/결정사항 자동 제안
---
### 5. Notification Service
#### 개요
- **파일**: `notification-service-api.yaml`
- **베이스 URL**: `/api/v1`
- **주요 기능**: 알림 발송 및 리마인더 관리
#### API 목록
**Internal APIs (2개) - 이벤트 핸들러**
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|--------|----------|------|-----------|----------|
| POST | /notifications/invitation | 회의 초대 알림 발송 | UFR-MEET-010 | NotificationController |
| POST | /notifications/todo | Todo 할당 알림 발송 | UFR-TODO-010 | NotificationController |
**Public APIs (2개)**
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|--------|----------|------|-----------|----------|
| GET | /notifications | 사용자별 알림 이력 조회 | AFR-USER-020 | NotificationController |
| GET | /notifications/{notificationId} | 알림 상세 조회 | AFR-USER-020 | NotificationController |
**Settings APIs (2개)**
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|--------|----------|------|-----------|----------|
| GET | /notifications/settings | 알림 설정 조회 | AFR-USER-020 | NotificationSettingsController |
| PUT | /notifications/settings | 알림 설정 업데이트 | AFR-USER-020 | NotificationSettingsController |
#### 주요 특징
- Azure Event Hubs 기반 비동기 처리
- 이메일 템플릿 렌더링
- 중복 발송 방지 (Idempotency)
- 재시도 메커니즘 (최대 3회, exponential backoff)
- 알림 설정 관리 (채널, 유형, 방해 금지 시간대)
#### 이메일 템플릿
- **회의 초대**: 회의 정보 + 참여 링크 + 캘린더 추가
- **Todo 할당**: Todo 상세 + 회의록 링크
- **리마인더**: 회의 시작 30분 전 자동 발송
- **Todo 리마인더**: 마감일 3일 전, 1일 전, 당일
---
## 공통 사항
### 인증 및 권한
#### JWT 토큰 구조
```json
{
"userId": "string",
"userName": "string",
"email": "string",
"exp": 1234567890
}
```
#### 인증 헤더
```
Authorization: Bearer {access_token}
```
#### 사용자 정보 헤더 (모든 API 요청)
```
X-User-Id: {userId}
X-User-Name: {userName}
X-User-Email: {userEmail}
```
### 에러 응답 형식
#### 공통 에러 응답
```json
{
"status": "error",
"code": "ERROR_CODE",
"message": "에러 메시지",
"details": {
"field": "필드명",
"reason": "상세 사유"
},
"timestamp": "2025-01-23T10:00:00Z"
}
```
#### HTTP 상태 코드
- **200**: 성공
- **201**: 생성 성공
- **400**: 잘못된 요청
- **401**: 인증 실패
- **403**: 권한 없음
- **404**: 리소스 없음
- **409**: 충돌 (동시 수정 등)
- **500**: 서버 오류
### 페이징 표준
#### 요청 파라미터
```
page: 페이지 번호 (default: 0)
size: 페이지 크기 (default: 20, max: 100)
sort: 정렬 기준 (예: createdAt,desc)
```
#### 응답 형식
```json
{
"content": [...],
"pageable": {
"page": 0,
"size": 20,
"totalElements": 100,
"totalPages": 5
}
}
```
---
## API 확인 방법
### 1. Swagger Editor에서 확인
1. **Swagger Editor 접속**
- https://editor.swagger.io/
2. **각 서비스 YAML 파일 확인**
- `design/backend/api/user-service-api.yaml`
- `design/backend/api/meeting-service-api.yaml`
- `design/backend/api/stt-service-api.yaml`
- `design/backend/api/ai-service-api.yaml`
- `design/backend/api/notification-service-api.yaml`
3. **파일 내용 붙여넣기**
- 좌측 패널에 YAML 내용 붙여넣기
- 우측 패널에서 API 문서 확인
4. **API 테스트**
- "Try it out" 버튼으로 API 테스트
- Example 데이터로 요청/응답 시뮬레이션
### 2. 로컬에서 검증
#### swagger-cli 설치
```bash
npm install -g @apidevtools/swagger-cli
```
#### 검증 실행
```bash
# 개별 파일 검증
swagger-cli validate design/backend/api/user-service-api.yaml
# 전체 파일 검증
swagger-cli validate design/backend/api/*.yaml
```
#### 검증 결과
```
design/backend/api/user-service-api.yaml is valid
design/backend/api/meeting-service-api.yaml is valid
design/backend/api/stt-service-api.yaml is valid
design/backend/api/ai-service-api.yaml is valid
design/backend/api/notification-service-api.yaml is valid
```
---
## 통계
### API 개수 요약
| 서비스 | API 개수 | 주요 기능 |
|--------|---------|----------|
| User Service | 4 | 사용자 인증 |
| Meeting Service | 17 | 회의, 회의록, Todo, 실시간 협업 |
| STT Service | 12 | 음성 녹음, 변환, 화자 식별 |
| AI Service | 8 | AI 회의록, Todo 추출, RAG 검색 |
| Notification Service | 6 | 알림 발송, 설정 관리 |
| **합계** | **47** | |
### 유저스토리 커버리지
- **전체 유저스토리**: 25개
- **API로 구현된 유저스토리**: 25개
- **커버리지**: 100%
---
## 문서 이력
| 버전 | 작성일 | 작성자 | 변경 내용 |
|------|--------|--------|----------|
| 1.0 | 2025-01-23 | 길동 (아키텍트), 준호 (Backend Developer) | 초안 작성 (5개 마이크로서비스) |
---
## 부록
### A. 참조 문서
- 유저스토리: `design/userstory.md`
- 외부 시퀀스 설계서: `design/backend/sequence/outer/*.puml`
- 내부 시퀀스 설계서: `design/backend/sequence/inner/*.puml`
- 공통 설계 원칙: `claude/common-principles.md`
- API 설계 가이드: `claude/api-design.md`
### B. 파일 구조
```
design/backend/api/
├── user-service-api.yaml # User Service API 명세
├── meeting-service-api.yaml # Meeting Service API 명세
├── stt-service-api.yaml # STT Service API 명세
├── ai-service-api.yaml # AI Service API 명세
├── notification-service-api.yaml # Notification Service API 명세
└── API설계서.md # 본 문서
```
### C. OpenAPI 3.0 주요 섹션
- **openapi**: 버전 정보 (3.0.3)
- **info**: API 메타데이터
- **servers**: 서버 URL
- **paths**: API 엔드포인트
- **components**: 재사용 가능한 컴포넌트
- schemas: 데이터 모델
- parameters: 공통 파라미터
- responses: 공통 응답
- securitySchemes: 인증 방식
---
**© 2025 회의록 작성 및 공유 개선 서비스. All rights reserved.**
Reference in New Issue View Git Blame Copy Permalink