설계서 전면 업데이트: 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>

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

@@ -18,18 +18,19 @@
 
 ### 프로젝트 정보
 - **프로젝트명**: 회의록 작성 및 공유 개선 서비스
-- **설계 버전**: v2.0
-- **설계일**: 2025-01-23
-- **설계자**: 아키텍트(길동), Backend Developer(준호)
+- **설계 버전**: v2.1
+- **최종 수정일**: 2025-01-29
+- **설계자**: 아키텍트(길동), Backend Developer(준호, 동욱)
 
 ### 마이크로서비스 구성
-본 서비스는 5개의 마이크로서비스로 구성됩니다:
+본 서비스는 6개의 마이크로서비스로 구성됩니다:
 
 1. **User Service** - 사용자 인증 (LDAP 연동, JWT 토큰 발급/검증)
 2. **Meeting Service** - 회의, 회의록, Todo, 실시간 협업 통합 관리
 3. **STT Service** - 음성 녹음 관리, 음성-텍스트 변환, 화자 식별
-4. **AI Service** - AI 기반 회의록 자동화, Todo 추출, 지능형 검색 (RAG 통합)
-5. **Notification Service** - 알림 발송 및 리마인더 관리
+4. **AI Service** - AI 기반 회의록 자동화, Todo 추출, RAG 서비스 연동
+5. **RAG Service** - 용어집/관련자료/회의록 검색 (Python/FastAPI 독립 서비스)
+6. **Notification Service** - 알림 발송 및 리마인더 관리
 
 ---
 
@@ -194,52 +195,106 @@
 
 #### API 목록
 
-**Transcript Processing APIs (2개)**
+**Transcript Processing APIs (1개)**
 | 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개)**
+**Summary APIs (2개)**
 | Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
 |--------|----------|------|-----------|----------|
-| GET | /transcripts/{meetingId}/related | 관련 회의록 연결 | UFR-AI-040 | TranscriptController |
+| POST | /sections/{sectionId}/summary | 안건별 AI 요약 생성 | UFR-AI-010 | SectionController |
+| POST | /sections/{sectionId}/regenerate | 한줄 요약 재생성 | UFR-AI-036 | SectionController |
 
-**Term Explanation APIs (2개)**
+**Suggestion APIs (1개) - 실시간 AI 제안**
 | Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
 |--------|----------|------|-----------|----------|
-| POST | /terms/detect | 전문용어 감지 | UFR-RAG-010 | TermController |
-| GET | /terms/{term}/explain | 맥락 기반 용어 설명 | UFR-RAG-020 | TermController |
+| GET | /meetings/{meetingId}/suggestions/stream | 실시간 주요 내용 제안 (SSE) | UFR-AI-030 | SuggestionController |
 
-**Suggestion APIs (2개)**
+**Related Transcripts APIs (1개) - RAG 연동**
 | Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
 |--------|----------|------|-----------|----------|
-| POST | /suggestions/discussion | 논의사항 제안 | UFR-AI-010 | SuggestionController |
-| POST | /suggestions/decision | 결정사항 제안 | UFR-AI-010 | SuggestionController |
+| 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 기반 회의록 자동 작성
-- 7가지 프롬프트 유형 지원
-  - 1Page 요약, 핵심 요약, 상세 보고서
-  - 의사결정 중심, 액션 아이템 중심
-  - 경영진 보고용, 커스텀
-- RAG 기반 관련 회의록 검색 (벡터 유사도 70% 이상)
-- 맥락 기반 전문용어 설명
-- 실시간 논의사항/결정사항 제안
+- LLM 기반 회의록 자동 작성 (Claude 3.5 Sonnet)
+- RAG Service 연동
+  - 전문용어 자동 감지 및 맥락 기반 설명
+  - 관련 회의록 검색 (벡터 유사도 70% 이상)
+  - 조직 내 문서 및 이력 기반 용어 설명 생성
+- 안건별 요약 생성 (한줄 요약 + 상세 요약)
+- 실시간 주요 내용 제안 (SSE 스트리밍)
+- Todo 자동 추출 (Meeting Service에 전달)
 
 #### 차별화 포인트
-1. **맥락 기반 용어 설명**: 단순 정의가 아닌 조직 내 실제 사용 맥락 제공
-2. **프롬프팅 기반 개선**: 다양한 형식의 회의록 생성
-3. **실시간 추천**: AI 기반 논의사항/결정사항 자동 제안
+1. **맥락 기반 용어 설명**: 단순 사전 정의가 아닌, RAG를 통해 조직 내 실제 사용 맥락과 과거 논의 이력 제공
+2. **하이브리드 검색 기반 연관성**: 키워드 매칭과 벡터 유사도를 결합하여 관련 회의록 정확도 향상
+3. **실시간 AI 제안**: SSE 기반 스트리밍으로 회의 중 주요 내용 실시간 제안
 
 ---
 
-### 5. Notification Service
+### 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`
@@ -365,11 +420,12 @@ sort: 정렬 기준 (예: createdAt,desc)
    - 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`
+   - `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 내용 붙여넣기
@@ -389,19 +445,20 @@ npm install -g @apidevtools/swagger-cli
 #### 검증 실행
 ```bash
 # 개별 파일 검증
-swagger-cli validate design/backend/api/user-service-api.yaml
+swagger-cli validate design/backend/api/spec/user-service-api.yaml
 
 # 전체 파일 검증
-swagger-cli validate design/backend/api/*.yaml
+swagger-cli validate design/backend/api/spec/*.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
+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
 ```
 
 ---
@@ -413,16 +470,17 @@ design/backend/api/notification-service-api.yaml is valid
 | 서비스 | API 개수 | 주요 기능 |
 |--------|---------|----------|
 | User Service | 4 | 사용자 인증 |
-| Meeting Service | 17 | 회의, 회의록, Todo, 실시간 협업 |
+| Meeting Service | 17 | 회의, 회의록, Todo 관리 |
 | STT Service | 12 | 음성 녹음, 변환, 화자 식별 |
-| AI Service | 8 | AI 회의록, Todo 추출, RAG 검색 |
+| AI Service | 8 | AI 회의록, Todo 추출, RAG 연동 |
+| RAG Service | 9 | 용어집/문서/회의록 검색 |
 | Notification Service | 6 | 알림 발송, 설정 관리 |
-| **합계** | **47** | |
+| **합계** | **56** | |
 
 ### 유저스토리 커버리지
 
-- **전체 유저스토리**: 25개
-- **API로 구현된 유저스토리**: 25개
+- **전체 유저스토리**: 28개
+- **API로 구현된 유저스토리**: 28개
 - **커버리지**: 100%
 
 ---
@@ -432,6 +490,8 @@ design/backend/api/notification-service-api.yaml is valid
 | 버전 | 작성일 | 작성자 | 변경 내용 |
 |------|--------|--------|----------|
 | 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개 마이크로서비스) |
 
 ---
 

design/backend/api/spec/rag-service-api.yaml

@@ -0,0 +1,636 @@
+openapi: 3.0.3
+info:
+  title: RAG Service API
+  description: |
+    회의록 작성 서비스를 위한 RAG (Retrieval-Augmented Generation) 서비스 API
+
+    **주요 기능**:
+    - 용어집 검색 (PostgreSQL + pgvector)
+    - 관련자료 검색 (Azure AI Search)
+    - 회의록 유사도 검색 (Vector DB)
+
+    **기술 스택**: Python 3.11+, FastAPI, PostgreSQL+pgvector, Azure AI Search, Claude AI, Redis
+  version: 1.0.0
+  contact:
+    name: AI Specialist (서연), Backend Developer (준호)
+
+servers:
+  - url: http://localhost:8000
+    description: 로컬 개발 서버
+  - url: https://api-rag.hgzero.com
+    description: 운영 서버
+
+tags:
+  - name: Terms
+    description: 용어집 검색 API
+  - name: Documents
+    description: 관련자료 검색 API
+  - name: Minutes
+    description: 회의록 유사도 검색 API
+
+paths:
+  # ============================================================================
+  # Terms APIs - 용어집 검색
+  # ============================================================================
+
+  /api/rag/terms/search:
+    post:
+      tags:
+        - Terms
+      summary: 용어 검색 (Hybrid)
+      description: |
+        키워드 검색과 벡터 유사도 검색을 결합한 하이브리드 검색
+
+        **검색 방식**:
+        - `keyword`: 키워드 매칭 (PostgreSQL LIKE)
+        - `vector`: 벡터 유사도 (Cosine Similarity)
+        - `hybrid`: 키워드 + 벡터 가중합 (기본값)
+
+        **성능**: < 500ms (캐시 HIT 시 < 50ms)
+      x-user-story: UFR-RAG-010
+      x-controller: TermsController
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/TermSearchRequest'
+            examples:
+              hybrid_search:
+                summary: 하이브리드 검색 (기본)
+                value:
+                  query: "마이크로서비스 아키텍처"
+                  search_type: "hybrid"
+                  top_k: 5
+                  confidence_threshold: 0.7
+              keyword_search:
+                summary: 키워드 검색만
+                value:
+                  query: "Docker"
+                  search_type: "keyword"
+                  top_k: 3
+                  confidence_threshold: 0.6
+      responses:
+        '200':
+          description: 검색 결과
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/TermSearchResult'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/rag/terms/{termId}:
+    get:
+      tags:
+        - Terms
+      summary: 용어 상세 조회
+      description: 용어 ID로 용어 정보 조회
+      x-user-story: UFR-RAG-010
+      x-controller: TermsController
+      parameters:
+        - name: termId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: 용어 ID
+      responses:
+        '200':
+          description: 용어 정보
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Term'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/rag/terms/{termId}/explain:
+    post:
+      tags:
+        - Terms
+      summary: 맥락 기반 용어 설명 생성
+      description: |
+        Claude AI를 활용한 맥락 기반 용어 설명 생성
+
+        **생성 과정**:
+        1. 현재 회의 맥락 분석
+        2. RAG 검색 (관련 회의록, 문서, 업무 이력)
+        3. Claude AI 호출 (프롬프트 엔지니어링)
+        4. 결과 생성 및 캐싱
+
+        **성능**: < 3초 (Claude API 호출 포함)
+      x-user-story: UFR-RAG-020
+      x-controller: TermsController
+      parameters:
+        - name: termId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: 용어 ID
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/TermExplainRequest'
+      responses:
+        '200':
+          description: 용어 설명
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TermExplanation'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  # ============================================================================
+  # Documents APIs - 관련자료 검색
+  # ============================================================================
+
+  /api/rag/documents/search:
+    post:
+      tags:
+        - Documents
+      summary: 관련 문서 검색
+      description: |
+        Azure AI Search 기반 하이브리드 검색 + Semantic Ranking
+
+        **검색 기능**:
+        - 전체 텍스트 검색
+        - 벡터 유사도 검색
+        - Semantic Ranking (Azure AI Search)
+        - 필터링 (폴더, 문서 유형)
+      x-user-story: UFR-RAG-030
+      x-controller: DocumentsController
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/DocumentSearchRequest'
+      responses:
+        '200':
+          description: 검색 결과
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/DocumentSearchResult'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/rag/documents/stats:
+    get:
+      tags:
+        - Documents
+      summary: 문서 통계 조회
+      description: 전체 문서 통계 정보 조회
+      x-controller: DocumentsController
+      responses:
+        '200':
+          description: 문서 통계
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DocumentStats'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  # ============================================================================
+  # Minutes APIs - 회의록 유사도 검색
+  # ============================================================================
+
+  /api/rag/minutes/search:
+    post:
+      tags:
+        - Minutes
+      summary: 회의록 벡터 검색
+      description: |
+        회의록 내용 기반 벡터 유사도 검색
+
+        **검색 방식**: Cosine Similarity (임계값 70% 이상)
+        **성능**: < 1초 (캐시 HIT 시 < 100ms)
+      x-user-story: UFR-RAG-030
+      x-controller: MinutesController
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/MinutesSearchRequest'
+      responses:
+        '200':
+          description: 검색 결과
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/MinutesSearchResult'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/rag/minutes/{minutesId}:
+    get:
+      tags:
+        - Minutes
+      summary: 회의록 상세 조회
+      description: 회의록 ID로 상세 정보 조회
+      x-user-story: UFR-RAG-030
+      x-controller: MinutesController
+      parameters:
+        - name: minutesId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: 회의록 ID
+      responses:
+        '200':
+          description: 회의록 정보
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RagMinutes'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/rag/minutes/related:
+    post:
+      tags:
+        - Minutes
+      summary: 연관 회의록 조회
+      description: |
+        벡터 유사도 기반 연관 회의록 조회 (Redis 캐싱)
+
+        **처리 과정**:
+        1. Redis 캐시 조회
+        2. 캐시 MISS 시 DB 조회
+        3. 회의록 내용을 벡터 임베딩으로 변환
+        4. 벡터 유사도 검색 (자기 자신 제외)
+        5. 결과 Redis 캐싱 (TTL: 1시간)
+
+        **성능**: < 1초 (캐시 HIT 시 < 100ms)
+      x-user-story: UFR-RAG-030
+      x-controller: MinutesController
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RelatedMinutesRequest'
+      responses:
+        '200':
+          description: 연관 회의록 목록
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/RelatedMinutesResponse'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/rag/minutes/stats:
+    get:
+      tags:
+        - Minutes
+      summary: 회의록 통계 조회
+      description: 전체 회의록 통계 정보 조회
+      x-controller: MinutesController
+      responses:
+        '200':
+          description: 회의록 통계
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MinutesStats'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+# ============================================================================
+# Components
+# ============================================================================
+
+components:
+  schemas:
+    # Terms Schemas
+    TermSearchRequest:
+      type: object
+      required:
+        - query
+      properties:
+        query:
+          type: string
+          description: 검색 쿼리
+          example: "마이크로서비스 아키텍처"
+        search_type:
+          type: string
+          enum: [keyword, vector, hybrid]
+          default: hybrid
+          description: 검색 방식
+        top_k:
+          type: integer
+          default: 5
+          minimum: 1
+          maximum: 20
+          description: 반환할 최대 결과 수
+        confidence_threshold:
+          type: number
+          format: float
+          default: 0.7
+          minimum: 0.0
+          maximum: 1.0
+          description: 최소 신뢰도 임계값
+
+    Term:
+      type: object
+      properties:
+        term_id:
+          type: string
+          description: 용어 ID
+        term_name:
+          type: string
+          description: 용어명
+        definition:
+          type: string
+          description: 용어 정의
+        context:
+          type: string
+          description: 사용 맥락
+        category:
+          type: string
+          description: 카테고리
+        created_at:
+          type: string
+          format: date-time
+          description: 생성 일시
+        updated_at:
+          type: string
+          format: date-time
+          description: 수정 일시
+
+    TermSearchResult:
+      type: object
+      properties:
+        term:
+          $ref: '#/components/schemas/Term'
+        relevance_score:
+          type: number
+          format: float
+          description: 관련도 점수 (0.0 ~ 1.0)
+        match_type:
+          type: string
+          enum: [keyword, vector, hybrid]
+          description: 매칭 방식
+
+    TermExplainRequest:
+      type: object
+      required:
+        - meeting_context
+      properties:
+        meeting_context:
+          type: string
+          description: 현재 회의 맥락 (회의 주제, 안건 등)
+          example: "마이크로서비스 아키텍처 도입 검토 회의"
+
+    TermExplanation:
+      type: object
+      properties:
+        term:
+          $ref: '#/components/schemas/Term'
+        explanation:
+          type: string
+          description: 맥락 기반 설명 (Claude AI 생성)
+        context_documents:
+          type: array
+          items:
+            type: string
+          description: 참조 문서 목록
+        generated_by:
+          type: string
+          default: Claude 3.5 Sonnet
+          description: 생성 모델
+        cached:
+          type: boolean
+          description: 캐시 여부
+
+    # Documents Schemas
+    DocumentSearchRequest:
+      type: object
+      required:
+        - query
+      properties:
+        query:
+          type: string
+          description: 검색 쿼리
+        top_k:
+          type: integer
+          default: 5
+          minimum: 1
+          maximum: 20
+        folder:
+          type: string
+          description: 폴더 필터
+        document_type:
+          type: string
+          description: 문서 유형 필터
+        semantic_ranking:
+          type: boolean
+          default: true
+          description: Semantic Ranking 사용 여부
+        relevance_threshold:
+          type: number
+          format: float
+          default: 0.6
+          description: 최소 관련도 임계값
+
+    DocumentSearchResult:
+      type: object
+      properties:
+        document_id:
+          type: string
+        title:
+          type: string
+        content:
+          type: string
+          description: 문서 내용 (요약)
+        folder:
+          type: string
+        document_type:
+          type: string
+        relevance_score:
+          type: number
+          format: float
+        created_at:
+          type: string
+          format: date-time
+
+    DocumentStats:
+      type: object
+      properties:
+        total_documents:
+          type: integer
+        by_type:
+          type: object
+          additionalProperties:
+            type: integer
+        total_chunks:
+          type: integer
+
+    # Minutes Schemas
+    MinutesSearchRequest:
+      type: object
+      required:
+        - query
+      properties:
+        query:
+          type: string
+          description: 검색 쿼리 (회의 내용)
+        top_k:
+          type: integer
+          default: 5
+          minimum: 1
+          maximum: 20
+        similarity_threshold:
+          type: number
+          format: float
+          default: 0.7
+          minimum: 0.0
+          maximum: 1.0
+
+    RagMinutes:
+      type: object
+      properties:
+        minutes_id:
+          type: string
+        title:
+          type: string
+        full_content:
+          type: string
+          description: 전체 회의록 내용
+        meeting_date:
+          type: string
+          format: date-time
+        participants:
+          type: array
+          items:
+            type: string
+        created_at:
+          type: string
+          format: date-time
+
+    MinutesSearchResult:
+      type: object
+      properties:
+        minutes:
+          $ref: '#/components/schemas/RagMinutes'
+        similarity_score:
+          type: number
+          format: float
+          description: 유사도 점수 (0.0 ~ 1.0)
+
+    RelatedMinutesRequest:
+      type: object
+      required:
+        - minute_id
+      properties:
+        minute_id:
+          type: string
+          description: 기준 회의록 ID
+        top_k:
+          type: integer
+          default: 3
+          minimum: 1
+          maximum: 10
+        similarity_threshold:
+          type: number
+          format: float
+          default: 0.7
+
+    RelatedMinutesResponse:
+      type: object
+      properties:
+        minutes:
+          $ref: '#/components/schemas/RagMinutes'
+        similarity_score:
+          type: number
+          format: float
+
+    MinutesStats:
+      type: object
+      properties:
+        total_minutes:
+          type: integer
+        indexed_count:
+          type: integer
+        average_similarity:
+          type: number
+          format: float
+
+    # Error Schemas
+    ErrorResponse:
+      type: object
+      properties:
+        status:
+          type: string
+          enum: [error]
+        code:
+          type: string
+        message:
+          type: string
+        details:
+          type: object
+
+  responses:
+    BadRequest:
+      description: 잘못된 요청
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            status: error
+            code: BAD_REQUEST
+            message: 검색 쿼리가 비어 있습니다
+
+    NotFound:
+      description: 리소스를 찾을 수 없음
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            status: error
+            code: NOT_FOUND
+            message: 용어를 찾을 수 없습니다
+
+    InternalError:
+      description: 서버 내부 오류
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            status: error
+            code: INTERNAL_ERROR
+            message: 서버 오류가 발생했습니다