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

API 설계서

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

---

📋 목차

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

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

npm install -g @apidevtools/swagger-cli

검증 실행

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