mirror of
https://github.com/hwanny1128/HGZero.git
synced 2025-12-06 20:46:23 +00:00
d2f396cffb
## 주요 변경사항 ### 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>
637 lines
17 KiB
YAML
637 lines
17 KiB
YAML
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: 서버 오류가 발생했습니다
|