hgzero/design/backend/api/API설계서.md
yabo0812 d2f396cffb 설계서 전면 업데이트: RAG Service 문서화 및 불필요 설계 정리
## 주요 변경사항

### 1. RAG Service 독립 서비스 문서화
- RAG Service OpenAPI 명세 작성 (9개 API)
  - Terms APIs: 용어 검색, 조회, 맥락 기반 설명 (3개)
  - Documents APIs: 관련 문서 검색, 통계 (2개)
  - Minutes APIs: 회의록 벡터 검색, 연관 검색 (4개)
- 기술 스택: Python 3.11+, FastAPI, PostgreSQL+pgvector, Azure AI Search
- 성능 요구사항 명시 (용어 검색 <500ms, 설명 생성 <3초)

### 2. 불필요한 설계서 삭제 (10개 파일, 27% 감소)
- AI Service (3개): 결정사항제안, 논의사항제안, 회의록개선
- Meeting Service (5개): 실시간수정동기화, 충돌해결, Todo완료처리, Todo할당, 리마인더발송
- Notification Service (2개): Todo알림발송, 초대알림발송

### 3. API 설계서 업데이트 (v2.0 → v2.1)
- 마이크로서비스: 5개 → 6개 (RAG Service 추가)
- 총 API 개수: 47개 → 56개 (+9개)
- AI Service 주요 특징 업데이트
  - RAG Service 연동 명시
  - 삭제된 Suggestion API 제거
  - 차별화 포인트: 맥락 기반 용어 설명, 하이브리드 검색 강조
- RAG Service 섹션 완전 신규 작성
- 통계 및 문서 이력 업데이트

### 4. 내부 시퀀스 다이어그램 업데이트 (2개)
- ai-전문용어감지.puml: RAG Service API 호출 방식 명시
- ai-맥락기반용어설명.puml: RAG Service API 호출 방식 명시

### 5. 문서화
- 설계서 업데이트 요약 문서 작성 (claudedocs/설계서_업데이트_요약.md)
- 전체 변경 사항, 영향 분석, 다음 단계 작업 명시

## 영향 분석
- 설계서 파일: 37개 → 27개 (10개 삭제)
- 유저스토리 커버리지: 28개 유저스토리 100% 반영
- 서비스 아키텍처: AI Service와 RAG Service 분리로 독립성 향상

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-29 17:51:57 +09:00

532 lines
19 KiB
Markdown

# API 설계서
회의록 작성 및 공유 개선 서비스
---
## 📋 목차
1. [개요](#개요)
2. [API 설계 원칙](#api-설계-원칙)
3. [마이크로서비스별 API](#마이크로서비스별-api)
4. [공통 사항](#공통-사항)
5. [API 확인 방법](#api-확인-방법)
---
## 개요
### 프로젝트 정보
- **프로젝트명**: 회의록 작성 및 공유 개선 서비스
- **설계 버전**: v2.1
- **최종 수정일**: 2025-01-29
- **설계자**: 아키텍트(길동), Backend Developer(준호, 동욱)
### 마이크로서비스 구성
본 서비스는 6개의 마이크로서비스로 구성됩니다:
1. **User Service** - 사용자 인증 (LDAP 연동, JWT 토큰 발급/검증)
2. **Meeting Service** - 회의, 회의록, Todo, 실시간 협업 통합 관리
3. **STT Service** - 음성 녹음 관리, 음성-텍스트 변환, 화자 식별
4. **AI Service** - AI 기반 회의록 자동화, Todo 추출, RAG 서비스 연동
5. **RAG Service** - 용어집/관련자료/회의록 검색 (Python/FastAPI 독립 서비스)
6. **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 (1개)**
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|--------|----------|------|-----------|----------|
| POST | /transcripts/process | 회의록 자동 작성 | UFR-AI-010 | TranscriptController |
**Todo APIs (1개)**
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|--------|----------|------|-----------|----------|
| POST | /todos/extract | Todo 자동 추출 | UFR-AI-020 | TodoController |
**Summary APIs (2개)**
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|--------|----------|------|-----------|----------|
| POST | /sections/{sectionId}/summary | 안건별 AI 요약 생성 | UFR-AI-010 | SectionController |
| POST | /sections/{sectionId}/regenerate | 한줄 요약 재생성 | UFR-AI-036 | SectionController |
**Suggestion APIs (1개) - 실시간 AI 제안**
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|--------|----------|------|-----------|----------|
| GET | /meetings/{meetingId}/suggestions/stream | 실시간 주요 내용 제안 (SSE) | UFR-AI-030 | SuggestionController |
**Related Transcripts APIs (1개) - RAG 연동**
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|--------|----------|------|-----------|----------|
| GET | /transcripts/{meetingId}/related | 관련 회의록 검색 (RAG 서비스 연동) | UFR-AI-040 | RelatedTranscriptController |
**Term APIs (2개) - RAG 연동**
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|--------|----------|------|-----------|----------|
| POST | /terms/detect | 전문용어 감지 (RAG 서비스 연동) | UFR-RAG-010 | TermController |
| GET | /terms/{termId}/explain | 맥락 기반 용어 설명 (RAG 서비스 연동) | UFR-RAG-020 | ExplanationController |
#### 주요 특징
- LLM 기반 회의록 자동 작성 (Claude 3.5 Sonnet)
- RAG Service 연동
- 전문용어 자동 감지 맥락 기반 설명
- 관련 회의록 검색 (벡터 유사도 70% 이상)
- 조직 문서 이력 기반 용어 설명 생성
- 안건별 요약 생성 (한줄 요약 + 상세 요약)
- 실시간 주요 내용 제안 (SSE 스트리밍)
- Todo 자동 추출 (Meeting Service에 전달)
#### 차별화 포인트
1. **맥락 기반 용어 설명**: 단순 사전 정의가 아닌, RAG를 통해 조직 실제 사용 맥락과 과거 논의 이력 제공
2. **하이브리드 검색 기반 연관성**: 키워드 매칭과 벡터 유사도를 결합하여 관련 회의록 정확도 향상
3. **실시간 AI 제안**: SSE 기반 스트리밍으로 회의 주요 내용 실시간 제안
---
### 5. RAG Service
#### 개요
- **파일**: `rag-service-api.yaml`
- **베이스 URL**: `/api/rag`
- **주요 기능**: 용어집 검색, 관련자료 검색, 회의록 유사도 검색
- **기술 스택**: Python 3.11+, FastAPI, PostgreSQL+pgvector, Azure AI Search, Redis
#### API 목록
**Terms APIs (3개) - 용어집 검색**
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|--------|----------|------|-----------|----------|
| POST | /terms/search | 용어 검색 (Hybrid: Keyword + Vector) | UFR-RAG-010 | TermsController |
| GET | /terms/{termId} | 용어 상세 조회 | UFR-RAG-010 | TermsController |
| POST | /terms/{termId}/explain | 맥락 기반 용어 설명 (Claude AI) | UFR-RAG-020 | TermsController |
**Documents APIs (2개) - 관련자료 검색**
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|--------|----------|------|-----------|----------|
| POST | /documents/search | 관련 문서 검색 (Hybrid Search + Semantic Ranking) | UFR-RAG-030 | DocumentsController |
| GET | /documents/stats | 문서 통계 조회 | - | DocumentsController |
**Minutes APIs (4개) - 회의록 유사도 검색**
| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
|--------|----------|------|-----------|----------|
| POST | /minutes/search | 회의록 벡터 검색 | UFR-RAG-030 | MinutesController |
| GET | /minutes/{minutesId} | 회의록 상세 조회 | UFR-RAG-030 | MinutesController |
| POST | /minutes/related | 연관 회의록 조회 (벡터 유사도) | UFR-RAG-030 | MinutesController |
| GET | /minutes/stats | 회의록 통계 조회 | - | MinutesController |
#### 주요 특징
- **하이브리드 검색**: 키워드 검색 + 벡터 유사도 검색 (가중치 기반 통합)
- **임베딩 모델**: Azure OpenAI text-embedding-3-large (3,072 차원)
- **LLM**: Claude 3.5 Sonnet (맥락 기반 설명 생성)
- **캐싱**: Redis 기반 결과 캐싱 (TTL: 30분~1시간)
- **EventHub 연동**: Meeting 서비스에서 회의록 확정 이벤트 수신 벡터 DB 저장
#### 데이터베이스
- **PostgreSQL + pgvector**: 용어집 저장 벡터 검색
- **Azure AI Search**: 관련자료 하이브리드 검색 + Semantic Ranking
- **벡터 유사도**: Cosine Similarity (임계값 70% 이상)
#### 성능 요구사항
- **용어 검색**: < 500ms (캐시 HIT < 50ms)
- **용어 설명 생성**: < 3초 (Claude API 호출 포함)
- **회의록 검색**: < 1초 (캐시 HIT < 100ms)
---
### 6. 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/spec/user-service-api.yaml`
- `design/backend/api/spec/meeting-service-api.yaml`
- `design/backend/api/spec/stt-service-api.yaml`
- `design/backend/api/spec/ai-service-api.yaml`
- `design/backend/api/spec/rag-service-api.yaml`
- `design/backend/api/spec/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/spec/user-service-api.yaml
# 전체 파일 검증
swagger-cli validate design/backend/api/spec/*.yaml
```
#### 검증 결과
```
design/backend/api/spec/user-service-api.yaml is valid
design/backend/api/spec/meeting-service-api.yaml is valid
design/backend/api/spec/stt-service-api.yaml is valid
design/backend/api/spec/ai-service-api.yaml is valid
design/backend/api/spec/rag-service-api.yaml is valid
design/backend/api/spec/notification-service-api.yaml is valid
```
---
## 통계
### API 개수 요약
| 서비스 | API 개수 | 주요 기능 |
|--------|---------|----------|
| User Service | 4 | 사용자 인증 |
| Meeting Service | 17 | 회의, 회의록, Todo 관리 |
| STT Service | 12 | 음성 녹음, 변환, 화자 식별 |
| AI Service | 8 | AI 회의록, Todo 추출, RAG 연동 |
| RAG Service | 9 | 용어집/문서/회의록 검색 |
| Notification Service | 6 | 알림 발송, 설정 관리 |
| **합계** | **56** | |
### 유저스토리 커버리지
- **전체 유저스토리**: 28개
- **API로 구현된 유저스토리**: 28개
- **커버리지**: 100%
---
## 문서 이력
| 버전 | 작성일 | 작성자 | 변경 내용 |
|------|--------|--------|----------|
| 1.0 | 2025-01-23 | 길동 (아키텍트), 준호 (Backend Developer) | 초안 작성 (5개 마이크로서비스) |
| 2.0 | 2025-01-25 | 준호 (Backend Developer) | Todo 관리 기능 추가, 실시간 협업 설계 |
| 2.1 | 2025-01-29 | 동욱 (Backend Developer) | RAG Service 추가, 불필요한 API 정리 (6개 마이크로서비스) |
---
## 부록
### 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.**