mirror of
https://github.com/hwanny1128/HGZero.git
synced 2025-12-06 20:46:23 +00:00
b8ff2a8339
- 프롬프트 기반 회의록 개선 → 섹션 AI 요약 재생성으로 변경
- UFR-AI-030 → UFR-AI-035로 유저스토리 교체
- API 엔드포인트: POST /sections/{sectionId}/regenerate-summary
- 내부 시퀀스, 외부 시퀀스, API 설계서, 유저스토리 일관성 확보
- 프로토타입의 "AI 재생성" 버튼 기능과 정확히 매칭
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
446 lines
11 KiB
Markdown
446 lines
11 KiB
Markdown
# 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**:
|
|
```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. 섹션 AI 요약 재생성 (Section Summary)
|
|
|
|
#### POST /sections/{sectionId}/regenerate-summary
|
|
섹션 AI 요약 재생성
|
|
|
|
**유저스토리**: UFR-AI-035
|
|
**Controller**: SectionController
|
|
|
|
**Path Parameters**:
|
|
- `sectionId` (uuid, required): 섹션 ID
|
|
|
|
**Request Body**:
|
|
```json
|
|
{
|
|
"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)**:
|
|
```json
|
|
{
|
|
"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)**:
|
|
```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. 섹션 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 요약 재생성으로 변경 (프로토타입 반영) |
|