hgzero/design/backend/api/API설계서.md

API 설계서

회의록 작성 및 공유 개선 서비스

---

📋 목차

1. 개요
2. API 설계 원칙
3. 마이크로서비스별 API
4. 공통 사항
5. 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 토큰 구조

{
  "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}

에러 응답 형식

공통 에러 응답

{
  "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)

응답 형식

{
  "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 설치

npm install -g @apidevtools/swagger-cli

검증 실행

# 개별 파일 검증
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.