# 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.**