hgzero/design/backend/api/spec/ai-service-api-spec.md

AI Service API 설계서

개요

AI Service는 회의록 작성 및 공유 개선 서비스의 핵심 차별화 기능을 제공하는 마이크로서비스입니다.

주요 기능

• 회의록 자동 작성: LLM 기반 회의록 자동 생성
• Todo 자동 추출: 액션 아이템 자동 식별 및 담당자 추출
• 회의록 개선: 프롬프팅 기반 다양한 형식 변환
• 관련 회의록 연결: RAG 기반 벡터 유사도 검색
• 전문용어 감지: 맥락 기반 용어 설명 제공
• 실시간 추천: 논의사항/결정사항 자동 제안

API 명세 파일

• 파일 위치: design/backend/api/ai-service-api.yaml
• OpenAPI 버전: 3.0.3
• 검증 상태: ✅ Valid

API 엔드포인트 목록

1. 회의록 자동 작성 (Transcript)

POST /transcripts/process

회의록 자동 작성

유저스토리: UFR-AI-010 Controller: TranscriptController

Request Body:

{
  "meetingId": "550e8400-e29b-41d4-a716-446655440000",
  "transcriptText": "안녕하세요. 오늘 회의는...",
  "userId": "user123",
  "userName": "김철수",
  "context": {
    "title": "신규 프로젝트 킥오프 미팅",
    "participants": ["김철수", "이영희", "박민수"],
    "agenda": ["프로젝트 개요", "일정 논의", "역할 분담"]
  }
}

Response (200 OK):

{
  "transcriptId": "660e8400-e29b-41d4-a716-446655440001",
  "meetingId": "550e8400-e29b-41d4-a716-446655440000",
  "content": {
    "summary": "프로젝트 킥오프 미팅에서 기술 스택과 일정을 확정했습니다.",
    "discussions": [...],
    "decisions": [...],
    "pendingItems": [...]
  },
  "suggestions": {
    "discussionTopics": [...],
    "decisions": [...]
  },
  "createdAt": "2025-01-23T10:30:00Z",
  "status": "DRAFT"
}

---

2. Todo 자동 추출 (Todo)

POST /todos/extract

Todo 자동 추출

유저스토리: UFR-AI-020 Controller: TodoController

Request Body:

{
  "meetingId": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "user123"
}

Response (200 OK):

{
  "meetingId": "550e8400-e29b-41d4-a716-446655440000",
  "todos": [
    {
      "content": "API 설계서 작성",
      "assignee": "박민수",
      "dueDate": "2025-01-30",
      "priority": "HIGH",
      "sectionReference": "결정사항 #3"
    }
  ],
  "totalCount": 5,
  "extractedAt": "2025-01-23T11:00:00Z"
}

---

3. 회의록 개선 (Improve)

POST /transcripts/{meetingId}/improve

회의록 개선

유저스토리: UFR-AI-030 Controller: ImproveController

Path Parameters:

• meetingId (uuid, required): 회의 ID

Request Body:

{
  "promptType": "1PAGE_SUMMARY",
  "customPrompt": "경영진 보고용으로 3가지 핵심 결정사항만 요약해주세요",
  "userId": "user123"
}

Prompt Types:

• 1PAGE_SUMMARY: A4 1장 분량 요약
• CORE_SUMMARY: 3-5개 핵심 포인트
• DETAILED_REPORT: 시간순 상세 기록
• DECISION_FOCUSED: 의사결정 중심
• ACTION_FOCUSED: 액션 아이템 중심
• EXECUTIVE_REPORT: 경영진 보고용
• CUSTOM: 사용자 정의

Response (200 OK):

{
  "transcriptId": "770e8400-e29b-41d4-a716-446655440002",
  "version": 2,
  "baseVersion": 1,
  "improvementType": "1PAGE_SUMMARY",
  "content": "## 프로젝트 킥오프 미팅 요약\n\n### 핵심 결정사항...",
  "originalLink": "/transcripts/660e8400-e29b-41d4-a716-446655440001",
  "createdAt": "2025-01-23T11:30:00Z"
}

---

4. 관련 회의록 연결 (Relation)

GET /transcripts/{meetingId}/related

관련 회의록 조회

유저스토리: UFR-AI-040 Controller: RelationController

Path Parameters:

• meetingId (uuid, required): 회의 ID

Query Parameters:

• transcriptId (uuid, required): 회의록 ID
• limit (integer, optional): 최대 개수 (default: 5, max: 10)

Response (200 OK):

{
  "relatedTranscripts": [
    {
      "transcriptId": "aa0e8400-e29b-41d4-a716-446655440005",
      "title": "프로젝트 X 주간 회의",
      "date": "2025-01-15",
      "participants": ["김철수", "이영희"],
      "relevanceScore": 85.5,
      "commonKeywords": ["MSA", "API Gateway", "Spring Boot"],
      "link": "/transcripts/aa0e8400-e29b-41d4-a716-446655440005"
    }
  ],
  "totalCount": 3
}

---

5. 전문용어 감지 및 설명 (Term)

POST /terms/detect

전문용어 감지

유저스토리: UFR-RAG-010 Controller: TermController

Request Body:

{
  "meetingId": "550e8400-e29b-41d4-a716-446655440000",
  "text": "MSA 아키텍처로 설계하고, API Gateway를 통해 라우팅합니다...",
  "organizationId": "org123"
}

Response (200 OK):

{
  "detectedTerms": [
    {
      "term": "MSA",
      "position": {"line": 5, "offset": 42},
      "confidence": 0.92,
      "category": "기술",
      "highlight": true
    }
  ],
  "totalCount": 8,
  "highlightInfo": [...]
}

GET /terms/{term}/explain

맥락 기반 용어 설명

유저스토리: UFR-RAG-020 Controller: ExplanationController

Path Parameters:

• term (string, required): 용어명

Query Parameters:

• meetingId (uuid, required): 회의 ID
• context (string, optional): 현재 회의 맥락

Response (200 OK):

{
  "term": "MSA",
  "basicDefinition": "Microservices Architecture의 약자로, 애플리케이션을 작은 독립적인 서비스로 나누는 아키텍처 패턴",
  "contextualMeaning": "이번 프로젝트에서는 확장성과 독립 배포를 위해 MSA를 적용하기로 결정",
  "useCases": [
    "2024년 프로젝트 X에서 주문/결제/배송 서비스를 독립적으로 구성",
    "서비스별 독립 배포로 배포 시간 70% 단축"
  ],
  "relatedProjects": [...],
  "pastDiscussions": [...],
  "references": [...]
}

---

6. 실시간 추천 (Suggestion)

POST /suggestions/discussion

논의사항 제안

유저스토리: UFR-AI-010 Controller: SuggestionController

Request Body:

{
  "meetingId": "550e8400-e29b-41d4-a716-446655440000",
  "transcriptText": "프로젝트 일정에 대해 논의했습니다..."
}

Response (200 OK):

{
  "suggestions": [
    {
      "id": "880e8400-e29b-41d4-a716-446655440003",
      "topic": "보안 요구사항 검토",
      "reason": "안건에 포함되어 있으나 아직 논의되지 않음",
      "priority": "HIGH",
      "relatedAgenda": "프로젝트 개요",
      "estimatedTime": 15
    }
  ],
  "totalCount": 3,
  "timestamp": "2025-01-23T10:35:00Z"
}

POST /suggestions/decision

결정사항 제안

유저스토리: UFR-AI-010 Controller: SuggestionController

Request Body:

{
  "meetingId": "550e8400-e29b-41d4-a716-446655440000",
  "transcriptText": "React로 프론트엔드를 개발하기로 했습니다..."
}

Response (200 OK):

{
  "suggestions": [
    {
      "id": "990e8400-e29b-41d4-a716-446655440004",
      "content": "React로 프론트엔드 개발",
      "category": "기술",
      "decisionMaker": "김철수",
      "participants": ["김철수", "이영희"],
      "confidence": 0.85,
      "extractedFrom": "프론트엔드는 React로 개발하기로 했습니다",
      "context": "팀원 대부분이 React 경험이 있어 개발 속도가 빠를 것으로 예상"
    }
  ],
  "totalCount": 4,
  "timestamp": "2025-01-23T10:35:00Z"
}

---

공통 응답

에러 응답

400 Bad Request

{
  "error": "BAD_REQUEST",
  "message": "필수 파라미터가 누락되었습니다",
  "timestamp": "2025-01-23T10:30:00Z"
}

404 Not Found

{
  "error": "NOT_FOUND",
  "message": "해당 회의록을 찾을 수 없습니다",
  "timestamp": "2025-01-23T10:30:00Z"
}

500 Internal Server Error

{
  "error": "INTERNAL_SERVER_ERROR",
  "message": "서버 처리 중 오류가 발생했습니다",
  "timestamp": "2025-01-23T10:30:00Z"
}

---

인증 (Security)

모든 API는 JWT 토큰 기반 인증을 사용합니다.

인증 방식: Bearer Token

요청 헤더:

Authorization: Bearer <JWT_TOKEN>

---

API 확인 방법

Swagger Editor 사용

1. https://editor.swagger.io/ 접근
2. 생성된 ai-service-api.yaml 파일 내용 복사
3. Swagger Editor에 붙여넣기
4. 우측 패널에서 API 문서 확인
5. "Try it out" 기능으로 테스트 가능

Swagger UI 로컬 실행

# Swagger UI Docker 실행
docker run -p 8080:8080 \
  -e SWAGGER_JSON=/api/ai-service-api.yaml \
  -v C:\Users\KTDS\home\workspace\HGZero\design\backend\api:/api \
  swaggerapi/swagger-ui

# 브라우저에서 접근
# http://localhost:8080

---

설계 원칙 준수 사항

✅ API 설계 가이드 준수

• OpenAPI 3.0.3 스펙 사용
• 모든 엔드포인트에 x-user-story, x-controller 명시
• 완전한 Request/Response 스키마 정의
• Example 데이터 포함

✅ 유저스토리 매칭

• UFR-AI-010: 회의록 자동 작성 (실시간 추천 포함)
• UFR-AI-020: Todo 자동 추출
• UFR-AI-030: 회의록 개선
• UFR-AI-040: 관련 회의록 연결
• UFR-RAG-010: 전문용어 감지
• UFR-RAG-020: 맥락 기반 용어 설명

✅ 내부 시퀀스 일치

• 모든 API는 내부 시퀀스 설계와 일관성 유지
• LLM 프롬프트 파라미터 포함
• RAG 검색 결과 구조 반영

✅ 서버 URL 설정

• SwaggerHub Mock Server (첫 번째)
• Local/Dev/Production 서버 URL 포함

---

차별화 포인트 반영

1. 맥락 기반 용어 설명

• 단순 정의가 아닌 조직 내 실제 사용 맥락 제공
• 과거 회의록, 사내 문서, 업무 이력 통합 검색
• 실용적인 설명으로 업무 지식 부족 해소

2. 강화된 Todo 연결

• AI 자동 추출 + 담당자 자동 식별
• 회의록과 양방향 연결
• Meeting Service로 실시간 전달

3. 프롬프팅 기반 회의록 개선

• 7가지 프롬프트 유형 지원
• 원본 보존 + 버전 관리
• 사용자 정의 프롬프트 지원

4. 실시간 추천

• 논의사항 제안 (빠진 안건 자동 감지)
• 결정사항 제안 (패턴 기반 자동 추출)
• 회의 진행 중 실시간 제공

---

처리 시간 예상

API	평균 처리 시간
회의록 자동 작성	8-13초
Todo 자동 추출	4-7초
회의록 개선	5-9초
관련 회의록 연결	5-8초
전문용어 감지	3-5초
맥락 기반 용어 설명	5-8초
논의사항 제안	2.5-3.5초
결정사항 제안	2.5-3.5초

---

문서 이력

버전	작성일	작성자	변경 내용
1.0	2025-01-23	준호 (Backend Developer)	AI Service API 설계 완료