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

AI Service API 설계서

개요

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

주요 기능

• 회의록 자동 작성: LLM 기반 회의록 자동 생성
• Todo 자동 추출: 액션 아이템 자동 식별 및 담당자 추출
• 섹션 AI 요약 재생성: 작성한 섹션 내용을 AI가 자동으로 요약
• 관련 회의록 연결: 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",
  "minutesContent": "# 신규 프로젝트 킥오프 미팅\n\n## 참석자\n- 김철수, 이영희, 박민수\n\n## 논의사항\n1. 프로젝트 개요\n- React + Spring Boot 기반 개발\n\n## 결정사항\n1. API 설계서는 박민수님이 1월 30일까지 작성\n2. 프론트엔드는 이영희님이 2월 5일까지 개발\n\n## 보류사항\n- 배포 일정은 다음 회의에서 논의"
}

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. 섹션 AI 요약 재생성 (Section Summary)

POST /sections/{sectionId}/regenerate-summary

섹션 AI 요약 재생성

유저스토리: UFR-AI-035 Controller: SectionController

Path Parameters:

• sectionId (uuid, required): 섹션 ID

Request Body:

{
  "sectionContent": "**논의 사항:**\n- AI 기반 회의록 자동화 서비스 출시 결정\n- 타겟 고객: 중소기업, 스타트업\n- 주요 기능: 음성인식, AI 요약, Todo 자동 추출\n- 차별화 포인트: 실시간 검증, 협업 기능\n\n**결정 사항:**\n- 베타 버전 출시일: 2025년 12월 1일\n- 초기 목표 사용자: 100개 팀",
  "meetingId": "550e8400-e29b-41d4-a716-446655440000"
}

Response (200 OK):

{
  "summary": "AI 기반 회의록 자동화 서비스로 결정. 타겟은 중소기업 및 스타트업이며, 주요 기능은 음성인식, AI 요약, Todo 추출입니다. 경쟁사 대비 차별점은 실시간 검증 및 협업 기능입니다.",
  "generatedAt": "2025-01-23T11:00: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. 섹션 AI 요약 재생성

• 작성 중 실시간 AI 요약 생성
• 섹션별 독립적 요약 처리
• 회의 맥락 기반 정확도 향상

4. 실시간 추천

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

---

처리 시간 예상

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

---

문서 이력

버전	작성일	작성자	변경 내용
1.0	2025-01-23	준호 (Backend Developer)	AI Service API 설계 완료
1.1	2025-01-23	준호 (Backend Developer)	회의록 개선 → 섹션 AI 요약 재생성으로 변경 (프로토타입 반영)