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

**Response (200 OK)**:
```json
{
  "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**:
```json
{
  "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)**:
```json
{
  "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**:
```json
{
  "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)**:
```json
{
  "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)**:
```json
{
  "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**:
```json
{
  "meetingId": "550e8400-e29b-41d4-a716-446655440000",
  "text": "MSA 아키텍처로 설계하고, API Gateway를 통해 라우팅합니다...",
  "organizationId": "org123"
}
```

**Response (200 OK)**:
```json
{
  "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)**:
```json
{
  "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**:
```json
{
  "meetingId": "550e8400-e29b-41d4-a716-446655440000",
  "transcriptText": "프로젝트 일정에 대해 논의했습니다..."
}
```

**Response (200 OK)**:
```json
{
  "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**:
```json
{
  "meetingId": "550e8400-e29b-41d4-a716-446655440000",
  "transcriptText": "React로 프론트엔드를 개발하기로 했습니다..."
}
```

**Response (200 OK)**:
```json
{
  "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
```json
{
  "error": "BAD_REQUEST",
  "message": "필수 파라미터가 누락되었습니다",
  "timestamp": "2025-01-23T10:30:00Z"
}
```

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

#### 500 Internal Server Error
```json
{
  "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 로컬 실행

```bash
# 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 설계 완료 |