Merge branch 'main' of https://github.com/hwanny1128/HGZero into feat/rag-function

.github/kustomize/base/common/ingress.yaml

@@ -32,6 +32,13 @@ spec:
                 name: stt
                 port:
                   number: 8080
+          - path: /api/ai/suggestions
+            pathType: Prefix
+            backend:
+              service:
+                name: ai-service
+                port:
+                  number: 8087
           - path: /api/ai
             pathType: Prefix
             backend:

.gitignore

@@ -26,6 +26,7 @@ serena/
 
 # Environment
 .env
+ai-python/app/config.py
 
 # Playwright
 .playwright-mcp/

CLAUDE.md

@@ -562,4 +562,14 @@ Product Designer (UI/UX 전문가)
 - "@design-help": "설계실행프롬프트 내용을 터미널에 출력"
 - "@develop-help": "개발실행프롬프트 내용을 터미널에 출력"
 - "@deploy-help": "배포실행프롬프트 내용을 터미널에 출력"
+
+### Spring Boot 설정 관리
+- **설정 파일 구조**: `application.yml` + IntelliJ 실행 프로파일(`.run/*.run.xml`)로 관리
+- **금지 사항**: `application-{profile}.yml` 같은 프로파일별 설정 파일 생성 금지
+- **환경 변수 관리**: IntelliJ 실행 프로파일의 `<option name="env">` 섹션에서 관리
+- **application.yml 작성**: 환경 변수 플레이스홀더 사용 (`${DB_HOST:default}` 형식)
+- **실행 방법**:
+  - IntelliJ: 실행 프로파일 선택 후 실행 (환경 변수 자동 적용)
+  - 명령줄: 환경 변수 또는 `--args` 옵션으로 전달 (`--spring.profiles.active` 불필요)
+
 ```

ai-python/.dockerignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+venv/
+env/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Logs
+logs/
+*.log
+
+# Environment
+.env
+.env.local
+
+# Git
+.git/
+.gitignore
+
+# Documentation
+README.md
+API-DOCUMENTATION.md
+
+# Test
+tests/
+test_*.py

ai-python/.env.example

@@ -0,0 +1,26 @@
+# 서버 설정
+PORT=8087
+HOST=0.0.0.0
+
+# Claude API
+CLAUDE_API_KEY=your-api-key-here
+CLAUDE_MODEL=claude-3-5-sonnet-20241022
+CLAUDE_MAX_TOKENS=2000
+CLAUDE_TEMPERATURE=0.3
+
+# Redis
+REDIS_HOST=20.249.177.114
+REDIS_PORT=6379
+REDIS_PASSWORD=Hi5Jessica!
+REDIS_DB=4
+
+# Azure Event Hub
+EVENTHUB_CONNECTION_STRING=Endpoint=sb://hgzero-eventhub-ns.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=VUqZ9vFgu35E3c6RiUzoOGVUP8IZpFvlV+AEhC6sUpo=
+EVENTHUB_NAME=hgzero-eventhub-name
+EVENTHUB_CONSUMER_GROUP=ai-transcript-group
+
+# CORS
+CORS_ORIGINS=["http://localhost:*","http://127.0.0.1:*"]
+
+# 로깅
+LOG_LEVEL=INFO

ai-python/.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+venv/
+ENV/
+env/
+.venv
+
+# Environment
+.env
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Distribution
+build/
+dist/
+*.egg-info/

ai-python/API-DOCUMENTATION.md

@@ -0,0 +1,300 @@
+# AI Service API Documentation
+
+## 서비스 정보
+- **Base URL**: `http://localhost:8087`
+- **프로덕션 URL**: `http://{AKS-IP}:8087` (배포 후)
+- **포트**: 8087
+- **프로토콜**: HTTP
+- **CORS**: 모든 origin 허용 (개발 환경)
+
+## API 엔드포인트
+
+### 1. 실시간 AI 제안사항 스트리밍 (SSE)
+
+**엔드포인트**: `GET /api/ai/suggestions/meetings/{meeting_id}/stream`
+
+**설명**: 회의 중 실시간으로 AI 제안사항을 Server-Sent Events로 스트리밍합니다.
+
+**파라미터**:
+| 이름 | 위치 | 타입 | 필수 | 설명 |
+|------|------|------|------|------|
+| meeting_id | path | string | O | 회의 ID |
+
+**응답 형식**: `text/event-stream`
+
+**SSE 이벤트 구조**:
+```
+event: ai-suggestion
+id: 15
+data: {"suggestions":[{"id":"uuid","content":"제안 내용","timestamp":"14:23:45","confidence":0.92}]}
+```
+
+**응답 데이터 스키마**:
+```typescript
+interface SimpleSuggestion {
+  id: string;              // 제안 ID (UUID)
+  content: string;         // 제안 내용 (1-2문장)
+  timestamp: string;       // 타임스탬프 (HH:MM:SS)
+  confidence: number;      // 신뢰도 (0.0 ~ 1.0)
+}
+
+interface RealtimeSuggestionsResponse {
+  suggestions: SimpleSuggestion[];
+}
+```
+
+**프론트엔드 연동 예시 (JavaScript/TypeScript)**:
+
+```javascript
+// EventSource 연결
+const meetingId = 'meeting-123';
+const eventSource = new EventSource(
+  `http://localhost:8087/api/ai/suggestions/meetings/${meetingId}/stream`
+);
+
+// AI 제안사항 수신
+eventSource.addEventListener('ai-suggestion', (event) => {
+  const data = JSON.parse(event.data);
+
+  data.suggestions.forEach(suggestion => {
+    console.log('새 제안:', suggestion.content);
+    console.log('신뢰도:', suggestion.confidence);
+    console.log('시간:', suggestion.timestamp);
+
+    // UI 업데이트
+    addSuggestionToUI(suggestion);
+  });
+});
+
+// 에러 핸들링
+eventSource.onerror = (error) => {
+  console.error('SSE 연결 오류:', error);
+  eventSource.close();
+};
+
+// 연결 종료 (회의 종료 시)
+function closeSuggestions() {
+  eventSource.close();
+}
+```
+
+**React 예시**:
+
+```tsx
+import { useEffect, useState } from 'react';
+
+interface Suggestion {
+  id: string;
+  content: string;
+  timestamp: string;
+  confidence: number;
+}
+
+function MeetingRoom({ meetingId }: { meetingId: string }) {
+  const [suggestions, setSuggestions] = useState<Suggestion[]>([]);
+
+  useEffect(() => {
+    const eventSource = new EventSource(
+      `http://localhost:8087/api/ai/suggestions/meetings/${meetingId}/stream`
+    );
+
+    eventSource.addEventListener('ai-suggestion', (event) => {
+      const data = JSON.parse(event.data);
+      setSuggestions(prev => [...prev, ...data.suggestions]);
+    });
+
+    eventSource.onerror = () => {
+      console.error('SSE 연결 오류');
+      eventSource.close();
+    };
+
+    return () => {
+      eventSource.close();
+    };
+  }, [meetingId]);
+
+  return (
+    <div>
+      <h2>AI 제안사항</h2>
+      {suggestions.map(s => (
+        <div key={s.id}>
+          <span>{s.timestamp}</span>
+          <p>{s.content}</p>
+          <small>신뢰도: {(s.confidence * 100).toFixed(0)}%</small>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### 2. 헬스 체크
+
+**엔드포인트**: `GET /health`
+
+**설명**: 서비스 상태 확인 (Kubernetes probe용)
+
+**응답 예시**:
+```json
+{
+  "status": "healthy",
+  "service": "AI Service",
+  "port": 8087
+}
+```
+
+### 3. 서비스 정보
+
+**엔드포인트**: `GET /`
+
+**설명**: 서비스 기본 정보 조회
+
+**응답 예시**:
+```json
+{
+  "service": "AI Service",
+  "version": "1.0.0",
+  "status": "running",
+  "endpoints": {
+    "test": "/api/ai/suggestions/test",
+    "stream": "/api/ai/suggestions/meetings/{meeting_id}/stream"
+  }
+}
+```
+
+## 동작 흐름
+
+```
+1. 회의 시작
+   └─> 프론트엔드가 SSE 연결 시작
+
+2. 음성 녹음
+   └─> STT 서비스가 텍스트 변환
+       └─> Event Hub 발행
+           └─> AI 서비스가 Redis에 축적
+
+3. 실시간 분석 (5초마다)
+   └─> Redis에서 텍스트 조회
+       └─> 임계값(10개 세그먼트) 도달 시
+           └─> Claude API 분석
+               └─> SSE로 제안사항 전송
+                   └─> 프론트엔드 UI 업데이트
+
+4. 회의 종료
+   └─> SSE 연결 종료
+```
+
+## 주의사항
+
+1. **연결 유지**:
+   - SSE 연결은 장시간 유지되므로 네트워크 타임아웃 설정 필요
+   - 브라우저는 연결 끊김 시 자동 재연결 시도
+
+2. **CORS**:
+   - 개발 환경: 모든 origin 허용
+   - 프로덕션: 특정 도메인만 허용하도록 설정 필요
+
+3. **에러 처리**:
+   - SSE 연결 실패 시 재시도 로직 구현 권장
+   - 네트워크 오류 시 사용자에게 알림
+
+4. **성능**:
+   - 한 회의당 하나의 SSE 연결만 유지
+   - 불필요한 재연결 방지
+
+## 테스트
+
+### curl 테스트:
+```bash
+# 헬스 체크
+curl http://localhost:8087/health
+
+# SSE 스트리밍 테스트
+curl -N http://localhost:8087/api/ai/suggestions/meetings/test-meeting/stream
+```
+
+### 브라우저 테스트:
+1. 서비스 실행: `python3 main.py`
+2. Swagger UI 접속: http://localhost:8087/docs
+3. `/api/ai/suggestions/meetings/{meeting_id}/stream` 엔드포인트 테스트
+
+## 환경 변수
+
+프론트엔드에서 API URL을 환경 변수로 관리:
+
+```env
+# .env.local
+NEXT_PUBLIC_AI_SERVICE_URL=http://localhost:8087
+```
+
+```typescript
+const AI_SERVICE_URL = process.env.NEXT_PUBLIC_AI_SERVICE_URL || 'http://localhost:8087';
+
+const eventSource = new EventSource(
+  `${AI_SERVICE_URL}/api/ai/suggestions/meetings/${meetingId}/stream`
+);
+```
+
+## FAQ
+
+**Q: SSE vs WebSocket?**
+A: SSE는 서버→클라이언트 단방향 통신에 최적화되어 있습니다. 이 서비스는 AI 제안사항을 프론트엔드로 전송만 하므로 SSE가 적합합니다.
+
+**Q: 재연결은 어떻게?**
+A: 브라우저의 EventSource는 자동으로 재연결을 시도합니다. 추가 로직 불필요.
+
+**Q: 여러 클라이언트가 동시 연결 가능?**
+A: 네, 각 클라이언트는 독립적으로 SSE 연결을 유지합니다.
+
+**Q: 제안사항이 오지 않으면?**
+A: Redis에 충분한 텍스트(10개 세그먼트)가 축적되어야 분석이 시작됩니다. 5초마다 체크합니다.
+
+### 3. AI 텍스트 요약 생성
+
+**엔드포인트**: `POST /api/v1/ai/summary/generate`
+
+**설명**: 텍스트를 AI로 요약하여 핵심 내용과 포인트를 추출합니다.
+
+**요청 본문**:
+```json
+{
+  "text": "요약할 텍스트 내용",
+  "language": "ko",  // ko: 한국어, en: 영어 (기본값: ko)
+  "style": "bullet", // bullet: 불릿포인트, paragraph: 단락형 (기본값: bullet)
+  "max_length": 100  // 최대 요약 길이 (단어 수) - 선택사항
+}
+```
+
+**응답 예시**:
+```json
+{
+  "summary": "• 프로젝트 총 개발 기간 3개월 확정 (디자인 2주, 개발 8주, 테스트 2주)\n• 총 예산 5천만원 배정 (인건비 3천만원, 인프라 1천만원, 기타 1천만원)\n• 주간 회의 일정: 매주 화요일 오전 10시",
+  "key_points": [
+    "프로젝트 전체 일정 3개월로 확정",
+    "개발 단계별 기간: 디자인 2주, 개발 8주, 테스트 2주",
+    "총 예산 5천만원 책정",
+    "예산 배분: 인건비 60%, 인프라 20%, 기타 20%",
+    "정기 회의: 매주 화요일 오전 10시"
+  ],
+  "word_count": 32,
+  "original_word_count": 46,
+  "compression_ratio": 0.7,
+  "generated_at": "2025-10-29T17:23:49.429982"
+}
+```
+
+**요청 예시 (curl)**:
+```bash
+curl -X POST "http://localhost:8087/api/v1/ai/summary/generate" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "text": "오늘 회의에서는 프로젝트 일정과 예산에 대해 논의했습니다...",
+    "language": "ko",
+    "style": "bullet"
+  }'
+```
+
+**에러 응답**:
+- `400 Bad Request`: 텍스트가 비어있거나 너무 짧은 경우 (최소 20자)
+- `400 Bad Request`: 텍스트가 너무 긴 경우 (최대 10,000자)
+- `500 Internal Server Error`: AI 처리 중 오류 발생

ai-python/DEPLOYMENT.md

@@ -0,0 +1,318 @@
+# AI Service (Python) - AKS 배포 가이드
+
+## 📋 사전 준비
+
+### 1. Azure Container Registry (ACR) 접근 권한
+```bash
+# ACR 로그인
+az acr login --name acrdigitalgarage02
+```
+
+### 2. Kubernetes 클러스터 접근
+```bash
+# AKS 자격 증명 가져오기
+az aks get-credentials --resource-group <리소스그룹> --name <클러스터명>
+
+# 네임스페이스 확인
+kubectl get namespace hgzero
+```
+
+## 🐳 1단계: Docker 이미지 빌드 및 푸시
+
+### 이미지 빌드
+```bash
+cd ai-python
+
+# 이미지 빌드
+docker build -t acrdigitalgarage02.azurecr.io/hgzero/ai-service:latest .
+
+# 특정 버전 태그도 함께 생성 (권장)
+docker tag acrdigitalgarage02.azurecr.io/hgzero/ai-service:latest \
+  acrdigitalgarage02.azurecr.io/hgzero/ai-service:v1.0.0
+```
+
+### ACR에 푸시
+```bash
+# latest 태그 푸시
+docker push acrdigitalgarage02.azurecr.io/hgzero/ai-service:latest
+
+# 버전 태그 푸시
+docker push acrdigitalgarage02.azurecr.io/hgzero/ai-service:v1.0.0
+```
+
+### 로컬 테스트 (선택)
+```bash
+# 이미지 실행 테스트
+docker run -p 8087:8087 \
+  -e CLAUDE_API_KEY="your-api-key" \
+  -e REDIS_HOST="20.249.177.114" \
+  -e REDIS_PASSWORD="Hi5Jessica!" \
+  acrdigitalgarage02.azurecr.io/hgzero/ai-service:latest
+
+# 헬스 체크
+curl http://localhost:8087/health
+```
+
+## 🔐 2단계: Kubernetes Secret 생성
+
+### Claude API Key Secret 생성
+```bash
+# Claude API Key를 base64로 인코딩
+echo -n "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" | base64
+
+# Secret 생성
+kubectl create secret generic ai-secret \
+  --from-literal=claude-api-key="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" \
+  -n hgzero
+```
+
+### Event Hub Secret 생성 (기존에 없는 경우)
+```bash
+# Event Hub Connection String (AI Listen Policy)
+kubectl create secret generic azure-secret \
+  --from-literal=eventhub-ai-connection-string="Endpoint=sb://hgzero-eventhub-ns.servicebus.windows.net/;SharedAccessKeyName=ai-listen-policy;SharedAccessKey=wqcbVIXlOMyn/C562lx6DD75AyjHQ87xo+AEhJ7js9Q=" \
+  -n hgzero --dry-run=client -o yaml | kubectl apply -f -
+```
+
+### Redis Secret 확인/생성
+```bash
+# 기존 Redis Secret 확인
+kubectl get secret redis-secret -n hgzero
+
+# 없으면 생성
+kubectl create secret generic redis-secret \
+  --from-literal=password="Hi5Jessica!" \
+  -n hgzero
+```
+
+### ConfigMap 확인
+```bash
+# Redis ConfigMap 확인
+kubectl get configmap redis-config -n hgzero
+
+# 없으면 생성
+kubectl create configmap redis-config \
+  --from-literal=host="20.249.177.114" \
+  --from-literal=port="6379" \
+  -n hgzero
+```
+
+## 🚀 3단계: AI 서비스 배포
+
+### 배포 실행
+```bash
+# 배포 매니페스트 적용
+kubectl apply -f deploy/k8s/backend/ai-service.yaml
+
+# 배포 상태 확인
+kubectl get deployment ai-service -n hgzero
+kubectl get pods -n hgzero -l app=ai-service
+```
+
+### 로그 확인
+```bash
+# Pod 이름 가져오기
+POD_NAME=$(kubectl get pods -n hgzero -l app=ai-service -o jsonpath='{.items[0].metadata.name}')
+
+# 실시간 로그 확인
+kubectl logs -f $POD_NAME -n hgzero
+
+# Event Hub 연결 로그 확인
+kubectl logs $POD_NAME -n hgzero | grep "Event Hub"
+```
+
+## 🌐 4단계: Ingress 업데이트
+
+### Ingress 적용
+```bash
+# Ingress 설정 적용
+kubectl apply -f .github/kustomize/base/common/ingress.yaml
+
+# Ingress 확인
+kubectl get ingress -n hgzero
+kubectl describe ingress hgzero -n hgzero
+```
+
+### 접속 테스트
+```bash
+# 서비스 URL
+AI_SERVICE_URL="http://hgzero-api.20.214.196.128.nip.io"
+
+# 헬스 체크
+curl $AI_SERVICE_URL/api/ai/suggestions/test
+
+# Swagger UI
+echo "Swagger UI: $AI_SERVICE_URL/swagger-ui.html"
+```
+
+## ✅ 5단계: 배포 검증
+
+### Pod 상태 확인
+```bash
+# Pod 상태
+kubectl get pods -n hgzero -l app=ai-service
+
+# Pod 상세 정보
+kubectl describe pod -n hgzero -l app=ai-service
+
+# Pod 리소스 사용량
+kubectl top pod -n hgzero -l app=ai-service
+```
+
+### 서비스 확인
+```bash
+# Service 확인
+kubectl get svc ai-service -n hgzero
+
+# Service 상세 정보
+kubectl describe svc ai-service -n hgzero
+```
+
+### 엔드포인트 테스트
+```bash
+# 내부 테스트 (Pod에서)
+kubectl exec -it $POD_NAME -n hgzero -- curl http://localhost:8087/health
+
+# 외부 테스트 (Ingress 통해)
+curl http://hgzero-api.20.214.196.128.nip.io/api/ai/suggestions/test
+
+# SSE 스트리밍 테스트
+curl -N http://hgzero-api.20.214.196.128.nip.io/api/ai/suggestions/meetings/test-meeting/stream
+```
+
+## 🔄 업데이트 배포
+
+### 새 버전 배포
+```bash
+# 1. 새 이미지 빌드 및 푸시
+docker build -t acrdigitalgarage02.azurecr.io/hgzero/ai-service:v1.0.1 .
+docker push acrdigitalgarage02.azurecr.io/hgzero/ai-service:v1.0.1
+
+# 2. Deployment 이미지 업데이트
+kubectl set image deployment/ai-service \
+  ai-service=acrdigitalgarage02.azurecr.io/hgzero/ai-service:v1.0.1 \
+  -n hgzero
+
+# 3. 롤아웃 상태 확인
+kubectl rollout status deployment/ai-service -n hgzero
+
+# 4. 롤아웃 히스토리
+kubectl rollout history deployment/ai-service -n hgzero
+```
+
+### 롤백 (문제 발생 시)
+```bash
+# 이전 버전으로 롤백
+kubectl rollout undo deployment/ai-service -n hgzero
+
+# 특정 리비전으로 롤백
+kubectl rollout undo deployment/ai-service -n hgzero --to-revision=2
+```
+
+## 🐛 트러블슈팅
+
+### Pod가 Running 상태가 아닌 경우
+```bash
+# Pod 상태 확인
+kubectl get pods -n hgzero -l app=ai-service
+
+# Pod 이벤트 확인
+kubectl describe pod -n hgzero -l app=ai-service
+
+# 로그 확인
+kubectl logs -n hgzero -l app=ai-service
+```
+
+### ImagePullBackOff 에러
+```bash
+# ACR 접근 권한 확인
+kubectl get secret -n hgzero
+
+# ACR Pull Secret 생성 (필요시)
+kubectl create secret docker-registry acr-secret \
+  --docker-server=acrdigitalgarage02.azurecr.io \
+  --docker-username=<ACR_USERNAME> \
+  --docker-password=<ACR_PASSWORD> \
+  -n hgzero
+```
+
+### CrashLoopBackOff 에러
+```bash
+# 로그 확인
+kubectl logs -n hgzero -l app=ai-service --previous
+
+# 환경 변수 확인
+kubectl exec -it $POD_NAME -n hgzero -- env | grep -E "CLAUDE|REDIS|EVENTHUB"
+```
+
+### Redis 연결 실패
+```bash
+# Redis 접속 테스트 (Pod에서)
+kubectl exec -it $POD_NAME -n hgzero -- \
+  python -c "import redis; r=redis.Redis(host='20.249.177.114', port=6379, password='Hi5Jessica!', db=4); print(r.ping())"
+```
+
+### Event Hub 연결 실패
+```bash
+# Event Hub 연결 문자열 확인
+kubectl get secret azure-secret -n hgzero -o jsonpath='{.data.eventhub-ai-connection-string}' | base64 -d
+
+# 로그에서 Event Hub 오류 확인
+kubectl logs $POD_NAME -n hgzero | grep -i "eventhub\|error"
+```
+
+## 📊 모니터링
+
+### 실시간 로그 모니터링
+```bash
+# 실시간 로그
+kubectl logs -f -n hgzero -l app=ai-service
+
+# 특정 키워드 필터링
+kubectl logs -f -n hgzero -l app=ai-service | grep -E "SSE|Claude|AI"
+```
+
+### 리소스 사용량
+```bash
+# CPU/메모리 사용량
+kubectl top pod -n hgzero -l app=ai-service
+
+# 상세 리소스 정보
+kubectl describe pod -n hgzero -l app=ai-service | grep -A 5 "Resources"
+```
+
+## 🗑️ 삭제
+
+### AI 서비스 삭제
+```bash
+# Deployment와 Service 삭제
+kubectl delete -f deploy/k8s/backend/ai-service.yaml
+
+# Secret 삭제
+kubectl delete secret ai-secret -n hgzero
+
+# ConfigMap 유지 (다른 서비스에서 사용 중)
+# kubectl delete configmap redis-config -n hgzero
+```
+
+## 📝 주의사항
+
+1. **Secret 관리**
+   - Claude API Key는 민감 정보이므로 Git에 커밋하지 마세요
+   - 프로덕션 환경에서는 Azure Key Vault 사용 권장
+
+2. **리소스 제한**
+   - 초기 설정: CPU 250m-1000m, Memory 512Mi-1024Mi
+   - 트래픽에 따라 조정 필요
+
+3. **Event Hub**
+   - AI Listen Policy 사용 (Listen 권한만)
+   - EntityPath는 연결 문자열에서 제거
+
+4. **Redis**
+   - DB 4번 사용 (다른 서비스와 분리)
+   - TTL 5분 설정 (슬라이딩 윈도우)
+
+5. **Ingress 경로**
+   - `/api/ai/suggestions`가 `/api/ai`보다 먼저 정의되어야 함
+   - 더 구체적인 경로를 위에 배치

ai-python/Dockerfile

@@ -0,0 +1,27 @@
+# Python 3.11 slim 이미지 사용
+FROM python:3.11-slim
+
+# 작업 디렉토리 설정
+WORKDIR /app
+
+# 시스템 패키지 업데이트 및 필요한 도구 설치
+RUN apt-get update && apt-get install -y \
+    gcc \
+    && rm -rf /var/lib/apt/lists/*
+
+# Python 의존성 파일 복사 및 설치
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# 애플리케이션 코드 복사
+COPY . .
+
+# 포트 노출
+EXPOSE 8087
+
+# 헬스 체크
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8087/health')" || exit 1
+
+# 애플리케이션 실행
+CMD ["python", "main.py"]

ai-python/README.md

@@ -0,0 +1,167 @@
+# AI Service (Python)
+
+실시간 AI 제안사항 서비스 - FastAPI 기반
+
+## 📋 개요
+
+STT 서비스에서 실시간으로 변환된 텍스트를 받아 Claude API로 분석하여 회의 제안사항을 생성하고, SSE(Server-Sent Events)로 프론트엔드에 스트리밍합니다.
+
+## 🏗️ 아키텍처
+
+```
+Frontend (회의록 작성 화면)
+    ↓ (SSE 연결)
+AI Service (Python)
+    ↓ (Redis 조회)
+Redis (실시간 텍스트 축적)
+    ↑ (Event Hub)
+STT Service (음성 → 텍스트)
+```
+
+## 🚀 실행 방법
+
+### 1. 환경 설정
+
+```bash
+# .env 파일 생성
+cp .env.example .env
+
+# .env에서 아래 값 설정
+CLAUDE_API_KEY=sk-ant-...  # 실제 Claude API 키
+```
+
+### 2. 의존성 설치
+
+```bash
+# 가상환경 생성 (권장)
+python3 -m venv venv
+source venv/bin/activate  # Mac/Linux
+# venv\Scripts\activate   # Windows
+
+# 패키지 설치
+pip install -r requirements.txt
+```
+
+### 3. 서비스 시작
+
+```bash
+# 방법 1: 스크립트 실행
+./start.sh
+
+# 방법 2: 직접 실행
+python3 main.py
+```
+
+### 4. 서비스 확인
+
+```bash
+# 헬스 체크
+curl http://localhost:8087/health
+
+# SSE 스트림 테스트
+curl -N http://localhost:8087/api/v1/ai/suggestions/meetings/test-meeting/stream
+```
+
+## 📡 API 엔드포인트
+
+### SSE 스트리밍
+
+```
+GET /api/v1/ai/suggestions/meetings/{meeting_id}/stream
+```
+
+**응답 형식 (SSE)**:
+```json
+event: ai-suggestion
+data: {
+  "suggestions": [
+    {
+      "id": "uuid",
+      "content": "신제품의 타겟 고객층을 20-30대로 설정...",
+      "timestamp": "00:05:23",
+      "confidence": 0.92
+    }
+  ]
+}
+```
+
+## 🔧 개발 환경
+
+- **Python**: 3.9+
+- **Framework**: FastAPI
+- **AI**: Anthropic Claude API
+- **Cache**: Redis
+- **Event**: Azure Event Hub
+
+## 📂 프로젝트 구조
+
+```
+ai-python/
+├── main.py                    # FastAPI 진입점
+├── requirements.txt           # 의존성
+├── .env.example              # 환경 변수 예시
+├── start.sh                  # 시작 스크립트
+└── app/
+    ├── config.py             # 환경 설정
+    ├── models/
+    │   └── response.py       # 응답 모델
+    ├── services/
+    │   ├── claude_service.py     # Claude API 서비스
+    │   ├── redis_service.py      # Redis 서비스
+    │   └── eventhub_service.py   # Event Hub 리스너
+    └── api/
+        └── v1/
+            └── suggestions.py    # SSE 엔드포인트
+```
+
+## ⚙️ 환경 변수
+
+| 변수 | 설명 | 기본값 |
+|------|------|--------|
+| `CLAUDE_API_KEY` | Claude API 키 | (필수) |
+| `CLAUDE_MODEL` | Claude 모델 | claude-3-5-sonnet-20241022 |
+| `REDIS_HOST` | Redis 호스트 | 20.249.177.114 |
+| `REDIS_PORT` | Redis 포트 | 6379 |
+| `EVENTHUB_CONNECTION_STRING` | Event Hub 연결 문자열 | (선택) |
+| `PORT` | 서비스 포트 | 8087 |
+
+## 🔍 동작 원리
+
+1. **STT → Event Hub**: STT 서비스가 음성을 텍스트로 변환하여 Event Hub에 발행
+2. **Event Hub → Redis**: AI 서비스가 Event Hub에서 텍스트를 받아 Redis에 축적 (슬라이딩 윈도우: 최근 5분)
+3. **Redis → Claude API**: 임계값(10개 세그먼트) 이상이면 Claude API로 분석
+4. **Claude API → Frontend**: 분석 결과를 SSE로 프론트엔드에 스트리밍
+
+## 🧪 테스트
+
+```bash
+# Event Hub 없이 SSE만 테스트 (Mock 데이터)
+curl -N http://localhost:8087/api/v1/ai/suggestions/meetings/test-meeting/stream
+
+# 5초마다 샘플 제안사항이 발행됩니다
+```
+
+## 📝 개발 가이드
+
+### Claude API 키 발급
+1. https://console.anthropic.com/ 접속
+2. API Keys 메뉴에서 새 키 생성
+3. `.env` 파일에 설정
+
+### Redis 연결 확인
+```bash
+redis-cli -h 20.249.177.114 -p 6379 -a Hi5Jessica! ping
+# 응답: PONG
+```
+
+### Event Hub 설정 (선택)
+- Event Hub가 없어도 SSE 스트리밍은 동작합니다
+- STT 연동 시 필요
+
+## 🚧 TODO
+
+- [ ] Event Hub 연동 테스트
+- [ ] 프론트엔드 연동 테스트
+- [ ] 에러 핸들링 강화
+- [ ] 로깅 개선
+- [ ] 성능 모니터링

ai-python/app/__init__.py

@@ -0,0 +1,2 @@
+"""AI Service - Python FastAPI"""
+__version__ = "1.0.0"

ai-python/app/api/__init__.py

@@ -0,0 +1 @@
+"""API 레이어"""

ai-python/app/api/v1/__init__.py

@@ -1,8 +1,12 @@
 """API v1 Router"""
 from fastapi import APIRouter
 from .transcripts import router as transcripts_router
+from .suggestions import router as suggestions_router
+from .summary import router as summary_router
 
 router = APIRouter()
 
 # 라우터 등록
 router.include_router(transcripts_router, prefix="/transcripts", tags=["Transcripts"])
+router.include_router(suggestions_router, prefix="/ai/suggestions", tags=["AI Suggestions"])
+router.include_router(summary_router, prefix="/ai/summary", tags=["AI Summary"])

ai-python/app/api/v1/suggestions.py

@@ -0,0 +1,172 @@
+"""AI 제안사항 SSE 엔드포인트"""
+from fastapi import APIRouter, Response
+from fastapi.responses import StreamingResponse
+from sse_starlette.sse import EventSourceResponse
+import logging
+import asyncio
+from typing import AsyncGenerator
+from app.models import RealtimeSuggestionsResponse
+from app.services.claude_service import ClaudeService
+from app.services.redis_service import RedisService
+from app.config import get_settings
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+settings = get_settings()
+
+# 서비스 인스턴스
+claude_service = ClaudeService()
+
+
+@router.get(
+    "/meetings/{meeting_id}/stream",
+    summary="실시간 AI 제안사항 스트리밍",
+    description="""
+    회의 중 실시간으로 AI 제안사항을 Server-Sent Events(SSE)로 스트리밍합니다.
+
+    ### 동작 방식
+    1. Redis에서 누적된 회의 텍스트 조회 (5초마다)
+    2. 임계값(10개 세그먼트) 이상이면 Claude API로 분석
+    3. 분석 결과를 SSE 이벤트로 전송
+
+    ### SSE 이벤트 형식
+    ```
+    event: ai-suggestion
+    id: {segment_count}
+    data: {"suggestions": [...]}
+    ```
+
+    ### 클라이언트 연결 예시 (JavaScript)
+    ```javascript
+    const eventSource = new EventSource(
+        'http://localhost:8087/api/v1/ai/suggestions/meetings/{meeting_id}/stream'
+    );
+
+    eventSource.addEventListener('ai-suggestion', (event) => {
+        const data = JSON.parse(event.data);
+        console.log('새로운 제안사항:', data.suggestions);
+    });
+
+    eventSource.onerror = (error) => {
+        console.error('SSE 오류:', error);
+        eventSource.close();
+    };
+    ```
+
+    ### 주의사항
+    - 연결은 클라이언트가 종료할 때까지 유지됩니다
+    - 네트워크 타임아웃 설정이 충분히 길어야 합니다
+    - 브라우저는 자동으로 재연결을 시도합니다
+    """,
+    responses={
+        200: {
+            "description": "SSE 스트림 연결 성공",
+            "content": {
+                "text/event-stream": {
+                    "example": """event: ai-suggestion
+id: 15
+data: {"suggestions":[{"id":"550e8400-e29b-41d4-a716-446655440000","content":"신제품의 타겟 고객층을 20-30대로 설정하고, 모바일 우선 전략을 취하기로 논의 중입니다.","timestamp":"14:23:45","confidence":0.92}]}
+
+"""
+                }
+            }
+        }
+    }
+)
+async def stream_ai_suggestions(meeting_id: str):
+    """
+    실시간 AI 제안사항 SSE 스트리밍
+
+    Args:
+        meeting_id: 회의 ID
+
+    Returns:
+        Server-Sent Events 스트림
+    """
+    logger.info(f"SSE 스트림 시작 - meetingId: {meeting_id}")
+
+    async def event_generator() -> AsyncGenerator:
+        """SSE 이벤트 생성기"""
+        redis_service = RedisService()
+
+        try:
+            # Redis 연결
+            await redis_service.connect()
+
+            previous_count = 0
+
+            # Keep-alive를 위한 주석 전송
+            yield {
+                "event": "ping",
+                "data": "connected"
+            }
+
+            while True:
+                # 현재 세그먼트 개수 확인
+                current_count = await redis_service.get_segment_count(meeting_id)
+                logger.debug(f"세그먼트 카운트 - meetingId: {meeting_id}, count: {current_count}, prev: {previous_count}")
+
+                # 임계값 이상이고, 이전보다 증가했으면 분석
+                if (current_count >= settings.min_segments_for_analysis
+                        and current_count > previous_count):
+
+                    # 누적된 텍스트 조회
+                    accumulated_text = await redis_service.get_accumulated_text(meeting_id)
+
+                    if accumulated_text:
+                        logger.info(f"텍스트 누적 완료 - meetingId: {meeting_id}, 길이: {len(accumulated_text)}")
+
+                        # Claude API로 분석
+                        suggestions = await claude_service.analyze_suggestions(accumulated_text)
+
+                        if suggestions.suggestions:
+                            # SSE 이벤트 전송
+                            yield {
+                                "event": "ai-suggestion",
+                                "id": str(current_count),
+                                "data": suggestions.json()
+                            }
+
+                            logger.info(
+                                f"AI 제안사항 발행 - meetingId: {meeting_id}, "
+                                f"개수: {len(suggestions.suggestions)}"
+                            )
+
+                    previous_count = current_count
+
+                # Keep-alive 주석 전송 (SSE 연결 유지)
+                yield {
+                    "event": "ping",
+                    "data": f"alive-{current_count}"
+                }
+
+                # 5초마다 체크
+                await asyncio.sleep(5)
+
+        except asyncio.CancelledError:
+            logger.info(f"SSE 스트림 종료 - meetingId: {meeting_id}")
+            # 회의 종료 시 데이터 정리는 선택사항 (나중에 조회 필요할 수도)
+            # await redis_service.cleanup_meeting_data(meeting_id)
+
+        except Exception as e:
+            logger.error(f"SSE 스트림 오류 - meetingId: {meeting_id}", exc_info=e)
+
+        finally:
+            await redis_service.disconnect()
+
+    # CORS 헤더를 포함한 EventSourceResponse 반환
+    return EventSourceResponse(
+        event_generator(),
+        headers={
+            "Cache-Control": "no-cache",
+            "X-Accel-Buffering": "no",
+            "Access-Control-Allow-Origin": "http://localhost:8888",
+            "Access-Control-Allow-Credentials": "true",
+        }
+    )
+
+
+@router.get("/test")
+async def test_endpoint():
+    """테스트 엔드포인트"""
+    return {"message": "AI Suggestions API is working", "port": settings.port}

ai-python/app/api/v1/summary.py

@@ -0,0 +1,84 @@
+"""AI 요약 API 라우터"""
+from fastapi import APIRouter, HTTPException
+from app.models.summary import SummaryRequest, SummaryResponse
+from app.services.claude_service import claude_service
+import logging
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+
+@router.post("/generate", response_model=SummaryResponse)
+async def generate_summary(request: SummaryRequest):
+    """
+    텍스트 요약 생성 API
+    
+    - **text**: 요약할 텍스트 (필수)
+    - **language**: 요약 언어 (ko: 한국어, en: 영어) - 기본값: ko
+    - **style**: 요약 스타일 (bullet: 불릿포인트, paragraph: 단락형) - 기본값: bullet
+    - **max_length**: 최대 요약 길이 (단어 수) - 선택사항
+    
+    Returns:
+        요약 결과 (요약문, 핵심 포인트, 통계 정보)
+    """
+    try:
+        # 입력 검증
+        if not request.text or len(request.text.strip()) == 0:
+            raise HTTPException(
+                status_code=400,
+                detail="요약할 텍스트가 비어있습니다."
+            )
+        
+        if len(request.text) < 20:
+            raise HTTPException(
+                status_code=400,
+                detail="텍스트가 너무 짧습니다. 최소 20자 이상의 텍스트를 입력해주세요."
+            )
+        
+        if len(request.text) > 10000:
+            raise HTTPException(
+                status_code=400,
+                detail="텍스트가 너무 깁니다. 최대 10,000자까지 요약 가능합니다."
+            )
+        
+        # 언어 검증
+        if request.language not in ["ko", "en"]:
+            raise HTTPException(
+                status_code=400,
+                detail="지원하지 않는 언어입니다. 'ko' 또는 'en'만 사용 가능합니다."
+            )
+        
+        # 스타일 검증
+        if request.style not in ["bullet", "paragraph"]:
+            raise HTTPException(
+                status_code=400,
+                detail="지원하지 않는 스타일입니다. 'bullet' 또는 'paragraph'만 사용 가능합니다."
+            )
+        
+        # 최대 길이 검증
+        if request.max_length and request.max_length < 10:
+            raise HTTPException(
+                status_code=400,
+                detail="최대 길이는 10단어 이상이어야 합니다."
+            )
+        
+        logger.info(f"요약 요청 - 텍스트 길이: {len(request.text)}, 언어: {request.language}, 스타일: {request.style}")
+        
+        # Claude 서비스 호출
+        result = await claude_service.generate_summary(
+            text=request.text,
+            language=request.language,
+            style=request.style,
+            max_length=request.max_length
+        )
+        
+        return SummaryResponse(**result)
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"요약 생성 중 오류 발생: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=500,
+            detail=f"요약 생성 중 오류가 발생했습니다: {str(e)}"
+        )

ai-python/app/config.py

@@ -10,12 +10,12 @@ class Settings(BaseSettings):
     # 서버 설정
     app_name: str = "AI Service (Python)"
     host: str = "0.0.0.0"
-    port: int = 8087  # feature/stt-ai 브랜치 AI Service(8086)와 충돌 방지
+    port: int = 8087
 
     # Claude API
     claude_api_key: str = "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"
-    claude_model: str = "claude-3-5-sonnet-20240620"
+    claude_model: str = "claude-sonnet-4-5-20250929"
-    claude_max_tokens: int = 250000
+    claude_max_tokens: int = 4096
     claude_temperature: float = 0.7
 
     # Redis
@@ -42,8 +42,8 @@ class Settings(BaseSettings):
     # 로깅
     log_level: str = "INFO"
 
-    # 분석 임계값
+    # 분석 임계값 (MVP 수준)
-    min_segments_for_analysis: int = 10
+    min_segments_for_analysis: int = 3  # 3개 세그먼트 = 약 15-30초 분량의 대화
     text_retention_seconds: int = 300  # 5분
 
     class Config:

ai-python/app/models/__init__.py

@@ -6,6 +6,14 @@ from .transcript import (
     ParticipantMinutes,
     ExtractedTodo
 )
+from .response import (
+    SimpleSuggestion,
+    RealtimeSuggestionsResponse
+)
+from .summary import (
+    SummaryRequest,
+    SummaryResponse
+)
 
 __all__ = [
     "ConsolidateRequest",
@@ -13,4 +21,8 @@ __all__ = [
     "AgendaSummary",
     "ParticipantMinutes",
     "ExtractedTodo",
+    "SimpleSuggestion",
+    "RealtimeSuggestionsResponse",
+    "SummaryRequest",
+    "SummaryResponse",
 ]

ai-python/app/models/response.py

@@ -0,0 +1,45 @@
+"""응답 모델"""
+from pydantic import BaseModel, Field
+from typing import List
+
+
+class SimpleSuggestion(BaseModel):
+    """간소화된 AI 제안사항"""
+
+    id: str = Field(..., description="제안 ID")
+    content: str = Field(..., description="제안 내용 (1-2문장)")
+    timestamp: str = Field(..., description="타임스탬프 (HH:MM:SS)")
+    confidence: float = Field(..., ge=0.0, le=1.0, description="신뢰도 (0-1)")
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "id": "sugg-001",
+                "content": "신제품의 타겟 고객층을 20-30대로 설정하고, 모바일 우선 전략을 취하기로 논의 중입니다.",
+                "timestamp": "00:05:23",
+                "confidence": 0.92
+            }
+        }
+
+
+class RealtimeSuggestionsResponse(BaseModel):
+    """실시간 AI 제안사항 응답"""
+
+    suggestions: List[SimpleSuggestion] = Field(
+        default_factory=list,
+        description="AI 제안사항 목록"
+    )
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "suggestions": [
+                    {
+                        "id": "sugg-001",
+                        "content": "신제품의 타겟 고객층을 20-30대로 설정하고...",
+                        "timestamp": "00:05:23",
+                        "confidence": 0.92
+                    }
+                ]
+            }
+        }

ai-python/app/models/summary.py

@@ -0,0 +1,81 @@
+"""요약 관련 모델"""
+from pydantic import BaseModel, Field
+from typing import List, Optional
+from datetime import datetime
+
+
+class SummaryRequest(BaseModel):
+    """요약 요청 모델"""
+    text: str = Field(
+        ..., 
+        description="요약할 텍스트",
+        example="오늘 회의에서는 프로젝트 일정과 예산에 대해 논의했습니다. 첫째, 개발 일정은 3개월로 확정되었고, 디자인 단계는 2주, 개발 단계는 8주, 테스트 단계는 2주로 배분하기로 했습니다. 둘째, 예산은 총 5천만원으로 책정되었으며, 인건비 3천만원, 인프라 비용 1천만원, 기타 비용 1천만원으로 배분됩니다. 셋째, 주간 회의는 매주 화요일 오전 10시에 진행하기로 했습니다."
+    )
+    language: str = Field(
+        default="ko",
+        description="요약 언어 (ko: 한국어, en: 영어)",
+        example="ko"
+    )
+    style: str = Field(
+        default="bullet",
+        description="요약 스타일 (bullet: 불릿 포인트, paragraph: 단락형)",
+        example="bullet"
+    )
+    max_length: Optional[int] = Field(
+        default=None,
+        description="최대 요약 길이 (단어 수)",
+        example=100
+    )
+
+
+class SummaryResponse(BaseModel):
+    """요약 응답 모델"""
+    summary: str = Field(
+        ...,
+        description="생성된 요약",
+        example="• 프로젝트 일정: 총 3개월 (디자인 2주, 개발 8주, 테스트 2주)\n• 예산: 총 5천만원 (인건비 3천만원, 인프라 1천만원, 기타 1천만원)\n• 주간 회의: 매주 화요일 오전 10시"
+    )
+    key_points: List[str] = Field(
+        ...,
+        description="핵심 포인트 리스트",
+        example=[
+            "프로젝트 일정 3개월 확정",
+            "총 예산 5천만원 책정",
+            "주간 회의 화요일 10시"
+        ]
+    )
+    word_count: int = Field(
+        ...,
+        description="요약 단어 수",
+        example=42
+    )
+    original_word_count: int = Field(
+        ...,
+        description="원본 텍스트 단어 수", 
+        example=156
+    )
+    compression_ratio: float = Field(
+        ...,
+        description="압축률 (요약 길이 / 원본 길이)",
+        example=0.27
+    )
+    generated_at: datetime = Field(
+        default_factory=datetime.now,
+        description="생성 시간"
+    )
+    
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "summary": "• 프로젝트 일정: 총 3개월 (디자인 2주, 개발 8주, 테스트 2주)\n• 예산: 총 5천만원 (인건비 3천만원, 인프라 1천만원, 기타 1천만원)\n• 주간 회의: 매주 화요일 오전 10시",
+                "key_points": [
+                    "프로젝트 일정 3개월 확정", 
+                    "총 예산 5천만원 책정",
+                    "주간 회의 화요일 10시"
+                ],
+                "word_count": 42,
+                "original_word_count": 156,
+                "compression_ratio": 0.27,
+                "generated_at": "2024-10-29T17:15:30.123456"
+            }
+        }

ai-python/app/prompts/suggestions_prompt.py

@@ -0,0 +1,72 @@
+"""AI 제안사항 추출 프롬프트"""
+
+
+def get_suggestions_prompt(transcript_text: str) -> tuple[str, str]:
+    """
+    회의 텍스트에서 AI 제안사항을 추출하는 프롬프트 생성
+
+    Returns:
+        (system_prompt, user_prompt) 튜플
+    """
+
+    system_prompt = """당신은 회의 내용 분석 전문가입니다.
+회의 텍스트를 분석하여 실행 가능한 제안사항을 추출해주세요."""
+
+    user_prompt = f"""다음 회의 내용을 분석하여 **구체적이고 실행 가능한 제안사항**을 추출해주세요.
+
+# 회의 내용
+{transcript_text}
+
+---
+
+# 제안사항 추출 기준
+1. **실행 가능성**: 바로 실행할 수 있는 구체적인 액션 아이템
+2. **명확성**: 누가, 무엇을, 언제까지 해야 하는지 명확한 내용
+3. **중요도**: 회의 목표 달성에 중요한 사항
+4. **완결성**: 하나의 제안사항이 독립적으로 완결된 내용
+
+# 제안사항 유형 예시
+- **후속 작업**: "시장 조사 보고서를 다음 주까지 작성하여 공유"
+- **의사결정 필요**: "예산안 3안 중 최종안을 이번 주 금요일까지 결정"
+- **리스크 대응**: "법률 검토를 위해 법무팀과 사전 협의 필요"
+- **일정 조율**: "다음 회의를 3월 15일로 확정하고 참석자에게 공지"
+- **자료 준비**: "경쟁사 분석 자료를 회의 전까지 준비"
+- **검토 요청**: "초안에 대한 팀원들의 피드백 수집 필요"
+- **승인 필요**: "최종 기획안을 경영진에게 보고하여 승인 받기"
+
+# 제안사항 작성 가이드
+- **구체적으로**: "검토 필요" (X) → "법무팀과 계약서 조항 검토 미팅 잡기" (O)
+- **명확하게**: "나중에 하기" (X) → "다음 주 화요일까지 완료" (O)
+- **실행 가능하게**: "잘 되길 바람" (X) → "주간 진행상황 공유 미팅 설정" (O)
+
+---
+
+# 출력 형식
+반드시 아래 JSON 형식으로만 응답하세요:
+
+```json
+{{
+  "suggestions": [
+    {{
+      "content": "제안사항 내용 (구체적이고 실행 가능하게, 50자 이상 작성)",
+      "confidence": 0.85 (이 제안사항의 중요도/확실성, 0.7-1.0 사이)
+    }},
+    {{
+      "content": "또 다른 제안사항",
+      "confidence": 0.92
+    }}
+  ]
+}}
+```
+
+# 중요 규칙
+1. **회의 내용에 명시된 사항만** 추출 (추측하지 않기)
+2. **최소 3개, 최대 7개**의 제안사항 추출
+3. 중요도가 높은 순서로 정렬
+4. confidence는 **0.7 이상**만 포함
+5. 각 제안사항은 **50자 이상** 구체적으로 작성
+6. JSON만 출력 (```json이나 다른 텍스트 포함 금지)
+
+이제 위 회의 내용에서 제안사항을 JSON 형식으로 추출해주세요."""
+
+    return system_prompt, user_prompt

ai-python/app/prompts/summary_prompt.py

@@ -0,0 +1,80 @@
+"""요약 생성용 프롬프트"""
+
+
+def get_summary_prompt(text: str, language: str = "ko", style: str = "bullet", max_length: int = None):
+    """
+    텍스트 요약을 위한 프롬프트 생성
+    
+    Args:
+        text: 요약할 텍스트
+        language: 요약 언어 (ko/en)
+        style: 요약 스타일 (bullet/paragraph)
+        max_length: 최대 요약 길이 (단어 수)
+    
+    Returns:
+        tuple: (system_prompt, user_prompt)
+    """
+    
+    # 언어별 설정
+    if language == "ko":
+        lang_instruction = "한국어로 요약을 작성하세요."
+        bullet_prefix = "•"
+        style_name = "불릿 포인트" if style == "bullet" else "단락형"
+    else:
+        lang_instruction = "Write the summary in English."
+        bullet_prefix = "•"
+        style_name = "bullet points" if style == "bullet" else "paragraph"
+    
+    # 길이 제한 설정
+    length_instruction = ""
+    if max_length:
+        if language == "ko":
+            length_instruction = f"\n- 요약은 {max_length}단어 이내로 작성하세요."
+        else:
+            length_instruction = f"\n- Keep the summary within {max_length} words."
+    
+    system_prompt = f"""당신은 전문적인 텍스트 요약 전문가입니다.
+주어진 텍스트를 명확하고 간결하게 요약하는 것이 당신의 임무입니다.
+
+요약 원칙:
+1. 핵심 정보를 빠뜨리지 않고 포함
+2. 중복되는 내용은 제거
+3. 원문의 의미를 왜곡하지 않음
+4. {style_name} 형식으로 작성
+5. {lang_instruction}{length_instruction}
+
+응답은 반드시 다음 JSON 형식으로 제공하세요:
+{{
+    "summary": "요약 내용",
+    "key_points": ["핵심 포인트 1", "핵심 포인트 2", ...],
+    "analysis": {{
+        "main_topics": ["주요 주제들"],
+        "sentiment": "positive/negative/neutral",
+        "importance_level": "high/medium/low"
+    }}
+}}"""
+    
+    if style == "bullet":
+        style_instruction = f"""
+불릿 포인트 형식 지침:
+- 각 포인트는 '{bullet_prefix}'로 시작
+- 하나의 포인트는 한 문장으로 구성
+- 가장 중요한 정보부터 나열
+- 3-7개의 주요 포인트로 구성"""
+    else:
+        style_instruction = """
+단락형 형식 지침:
+- 자연스러운 문장으로 연결
+- 논리적 흐름을 유지
+- 적절한 접속사 사용
+- 2-3개의 단락으로 구성"""
+    
+    user_prompt = f"""다음 텍스트를 요약해주세요:
+
+{text}
+
+{style_instruction}
+
+JSON 형식으로 응답하세요."""
+
+    return system_prompt, user_prompt

ai-python/app/services/__init__.py

@@ -0,0 +1 @@
+"""서비스 레이어"""

ai-python/app/services/claude_service.py

@@ -85,6 +85,125 @@ class ClaudeService:
             logger.error(f"Claude API 호출 실패: {e}")
             raise
 
+    async def analyze_suggestions(self, transcript_text: str):
+        """
+        회의 텍스트에서 AI 제안사항 추출
+
+        Args:
+            transcript_text: 회의 텍스트
+
+        Returns:
+            RealtimeSuggestionsResponse 객체
+        """
+        from app.models import RealtimeSuggestionsResponse, SimpleSuggestion
+        from app.prompts.suggestions_prompt import get_suggestions_prompt
+        from datetime import datetime
+        import uuid
+
+        try:
+            # 프롬프트 생성
+            system_prompt, user_prompt = get_suggestions_prompt(transcript_text)
+
+            # Claude API 호출
+            result = await self.generate_completion(
+                prompt=user_prompt,
+                system_prompt=system_prompt
+            )
+
+            # 응답 파싱
+            suggestions_data = result.get("suggestions", [])
+
+            # SimpleSuggestion 객체로 변환
+            suggestions = [
+                SimpleSuggestion(
+                    id=str(uuid.uuid4()),
+                    content=s["content"],
+                    timestamp=datetime.now().strftime("%H:%M:%S"),
+                    confidence=s.get("confidence", 0.85)
+                )
+                for s in suggestions_data
+                if s.get("confidence", 0) >= 0.7  # 신뢰도 0.7 이상만
+            ]
+
+            logger.info(f"AI 제안사항 {len(suggestions)}개 추출 완료")
+
+            return RealtimeSuggestionsResponse(suggestions=suggestions)
+
+        except Exception as e:
+            logger.error(f"제안사항 분석 실패: {e}", exc_info=True)
+            # 빈 응답 반환
+            return RealtimeSuggestionsResponse(suggestions=[])
+    
+    async def generate_summary(
+        self,
+        text: str,
+        language: str = "ko",
+        style: str = "bullet",
+        max_length: int = None
+    ) -> Dict[str, Any]:
+        """
+        텍스트 요약 생성
+        
+        Args:
+            text: 요약할 텍스트
+            language: 요약 언어 (ko/en)
+            style: 요약 스타일 (bullet/paragraph)
+            max_length: 최대 요약 길이
+            
+        Returns:
+            요약 결과 딕셔너리
+        """
+        from app.models.summary import SummaryResponse
+        from app.prompts.summary_prompt import get_summary_prompt
+        
+        try:
+            # 프롬프트 생성
+            system_prompt, user_prompt = get_summary_prompt(
+                text=text,
+                language=language,
+                style=style,
+                max_length=max_length
+            )
+            
+            # Claude API 호출
+            result = await self.generate_completion(
+                prompt=user_prompt,
+                system_prompt=system_prompt
+            )
+            
+            # 단어 수 계산
+            summary_text = result.get("summary", "")
+            key_points = result.get("key_points", [])
+            
+            # 한국어와 영어의 단어 수 계산 방식 다르게 처리
+            if language == "ko":
+                # 한국어: 공백으로 구분된 어절 수
+                original_word_count = len(text.split())
+                summary_word_count = len(summary_text.split())
+            else:
+                # 영어: 공백으로 구분된 단어 수
+                original_word_count = len(text.split())
+                summary_word_count = len(summary_text.split())
+            
+            compression_ratio = summary_word_count / original_word_count if original_word_count > 0 else 0
+            
+            # 응답 생성
+            response = SummaryResponse(
+                summary=summary_text,
+                key_points=key_points,
+                word_count=summary_word_count,
+                original_word_count=original_word_count,
+                compression_ratio=round(compression_ratio, 2)
+            )
+            
+            logger.info(f"요약 생성 완료 - 원본: {original_word_count}단어, 요약: {summary_word_count}단어")
+            
+            return response.model_dump()
+            
+        except Exception as e:
+            logger.error(f"요약 생성 실패: {e}", exc_info=True)
+            raise
+
 
 # 싱글톤 인스턴스
 claude_service = ClaudeService()

ai-python/app/services/eventhub_service.py

@@ -0,0 +1,133 @@
+"""Azure Event Hub 서비스 - STT 텍스트 수신"""
+import asyncio
+import logging
+import json
+from azure.eventhub.aio import EventHubConsumerClient
+
+from app.config import get_settings
+from app.services.redis_service import RedisService
+
+logger = logging.getLogger(__name__)
+settings = get_settings()
+
+
+class EventHubService:
+    """Event Hub 리스너 - STT 텍스트 실시간 수신"""
+
+    def __init__(self):
+        self.client = None
+        self.redis_service = RedisService()
+
+    async def start(self):
+        """Event Hub 리스닝 시작"""
+        if not settings.eventhub_connection_string:
+            logger.warning("Event Hub 연결 문자열이 설정되지 않음 - Event Hub 리스너 비활성화")
+            return
+
+        logger.info("Event Hub 리스너 시작")
+
+        try:
+            # Redis 연결
+            await self.redis_service.connect()
+
+            # Event Hub 클라이언트 생성
+            self.client = EventHubConsumerClient.from_connection_string(
+                conn_str=settings.eventhub_connection_string,
+                consumer_group=settings.eventhub_consumer_group,
+                eventhub_name=settings.eventhub_name,
+            )
+
+            # 이벤트 수신 시작
+            async with self.client:
+                await self.client.receive(
+                    on_event=self.on_event,
+                    on_error=self.on_error,
+                    starting_position="-1",  # 최신 이벤트부터
+                )
+
+        except Exception as e:
+            logger.error(f"Event Hub 리스너 오류: {e}")
+        finally:
+            await self.redis_service.disconnect()
+
+    async def on_event(self, partition_context, event):
+        """
+        이벤트 수신 핸들러
+
+        이벤트 형식 (STT Service에서 발행):
+        {
+            "eventType": "TranscriptSegmentReady",
+            "meetingId": "meeting-123",
+            "text": "변환된 텍스트",
+            "timestamp": 1234567890000
+        }
+        """
+        try:
+            # 이벤트 원본 데이터 로깅
+            raw_body = event.body_as_str()
+            logger.info(f"수신한 이벤트 원본 (처음 300자): {raw_body[:300]}")
+
+            # 이벤트 데이터 파싱
+            event_data = json.loads(raw_body)
+
+            event_type = event_data.get("eventType")
+            meeting_id = event_data.get("meetingId")
+            text = event_data.get("text")
+            timestamp_raw = event_data.get("timestamp")
+
+            # timestamp 변환: LocalDateTime 배열 → Unix timestamp (ms)
+            # Java LocalDateTime은 [year, month, day, hour, minute, second, nano] 형식
+            if isinstance(timestamp_raw, list) and len(timestamp_raw) >= 3:
+                from datetime import datetime
+                year, month, day = timestamp_raw[0:3]
+                hour = timestamp_raw[3] if len(timestamp_raw) > 3 else 0
+                minute = timestamp_raw[4] if len(timestamp_raw) > 4 else 0
+                second = timestamp_raw[5] if len(timestamp_raw) > 5 else 0
+                dt = datetime(year, month, day, hour, minute, second)
+                timestamp = int(dt.timestamp() * 1000)  # milliseconds
+            else:
+                timestamp = int(timestamp_raw) if timestamp_raw else int(datetime.now().timestamp() * 1000)
+
+            # SegmentCreated 이벤트 처리
+            if event_type == "SegmentCreated" and meeting_id and text:
+                logger.info(
+                    f"STT 텍스트 수신 - meetingId: {meeting_id}, "
+                    f"텍스트 길이: {len(text)}, timestamp: {timestamp}"
+                )
+
+                try:
+                    # Redis에 텍스트 축적 (슬라이딩 윈도우)
+                    await self.redis_service.add_transcript_segment(
+                        meeting_id=meeting_id,
+                        text=text,
+                        timestamp=timestamp
+                    )
+                    logger.info(f"✅ Redis 저장 완료 - meetingId: {meeting_id}, timestamp: {timestamp}")
+                except Exception as redis_error:
+                    logger.error(f"❌ Redis 저장 실패 - meetingId: {meeting_id}, 오류: {redis_error}", exc_info=True)
+
+            # MVP 개발: checkpoint 업데이트 제거 (InMemory 모드)
+            # await partition_context.update_checkpoint(event)
+
+        except Exception as e:
+            logger.error(f"이벤트 처리 오류: {e}", exc_info=True)
+
+    async def on_error(self, partition_context, error):
+        """에러 핸들러"""
+        logger.error(
+            f"Event Hub 에러 - Partition: {partition_context.partition_id}, "
+            f"Error: {error}"
+        )
+
+    async def stop(self):
+        """Event Hub 리스너 종료"""
+        if self.client:
+            await self.client.close()
+            logger.info("Event Hub 리스너 종료")
+
+
+# 백그라운드 태스크로 실행할 함수
+async def start_eventhub_listener():
+    """Event Hub 리스너 백그라운드 실행"""
+    service = EventHubService()
+    await service.start()

ai-python/app/services/redis_service.py

@@ -0,0 +1,117 @@
+"""Redis 서비스 - 실시간 텍스트 축적"""
+import redis.asyncio as redis
+import logging
+from typing import List
+from app.config import get_settings
+
+logger = logging.getLogger(__name__)
+settings = get_settings()
+
+
+class RedisService:
+    """Redis 서비스 (슬라이딩 윈도우 방식)"""
+
+    def __init__(self):
+        self.redis_client = None
+
+    async def connect(self):
+        """Redis 연결"""
+        try:
+            self.redis_client = await redis.Redis(
+                host=settings.redis_host,
+                port=settings.redis_port,
+                password=settings.redis_password,
+                db=settings.redis_db,
+                decode_responses=True
+            )
+            await self.redis_client.ping()
+            logger.info("Redis 연결 성공")
+        except Exception as e:
+            logger.error(f"Redis 연결 실패: {e}")
+            raise
+
+    async def disconnect(self):
+        """Redis 연결 종료"""
+        if self.redis_client:
+            await self.redis_client.close()
+            logger.info("Redis 연결 종료")
+
+    async def add_transcript_segment(
+        self,
+        meeting_id: str,
+        text: str,
+        timestamp: int
+    ):
+        """
+        실시간 텍스트 세그먼트 추가 (슬라이딩 윈도우)
+
+        Args:
+            meeting_id: 회의 ID
+            text: 텍스트 세그먼트
+            timestamp: 타임스탬프 (밀리초)
+        """
+        key = f"meeting:{meeting_id}:transcript"
+        value = f"{timestamp}:{text}"
+
+        # Sorted Set에 추가 (타임스탬프를 스코어로)
+        await self.redis_client.zadd(key, {value: timestamp})
+
+        # 설정된 시간 이전 데이터 제거 (기본 5분)
+        retention_ms = settings.text_retention_seconds * 1000
+        cutoff_time = timestamp - retention_ms
+        await self.redis_client.zremrangebyscore(key, 0, cutoff_time)
+
+        logger.debug(f"텍스트 세그먼트 추가 - meetingId: {meeting_id}")
+
+    async def get_accumulated_text(self, meeting_id: str) -> str:
+        """
+        누적된 텍스트 조회 (최근 5분)
+
+        Args:
+            meeting_id: 회의 ID
+
+        Returns:
+            누적된 텍스트 (시간순)
+        """
+        key = f"meeting:{meeting_id}:transcript"
+
+        # 최신순으로 모든 세그먼트 조회
+        segments = await self.redis_client.zrevrange(key, 0, -1)
+
+        if not segments:
+            return ""
+
+        # 타임스탬프 제거하고 텍스트만 추출
+        texts = []
+        for seg in segments:
+            parts = seg.split(":", 1)
+            if len(parts) == 2:
+                texts.append(parts[1])
+
+        # 시간순으로 정렬 (역순으로 조회했으므로 다시 뒤집기)
+        return "\n".join(reversed(texts))
+
+    async def get_segment_count(self, meeting_id: str) -> int:
+        """
+        누적된 세그먼트 개수
+
+        Args:
+            meeting_id: 회의 ID
+
+        Returns:
+            세그먼트 개수
+        """
+        key = f"meeting:{meeting_id}:transcript"
+        count = await self.redis_client.zcard(key)
+        return count if count else 0
+
+    async def cleanup_meeting_data(self, meeting_id: str):
+        """
+        회의 종료 시 데이터 정리
+
+        Args:
+            meeting_id: 회의 ID
+        """
+        key = f"meeting:{meeting_id}:transcript"
+        await self.redis_client.delete(key)
+        logger.info(f"회의 데이터 정리 완료 - meetingId: {meeting_id}")

ai-python/cleanup_redis.py

@@ -0,0 +1,27 @@
+"""Redis 데이터 정리 스크립트"""
+import asyncio
+import sys
+sys.path.append('/Users/jominseo/HGZero/ai-python')
+
+from app.services.redis_service import RedisService
+
+async def cleanup():
+    redis_service = RedisService()
+
+    try:
+        await redis_service.connect()
+        print("✅ Redis 연결 성공")
+
+        # test-meeting-001 데이터 정리
+        meeting_id = "test-meeting-001"
+        await redis_service.cleanup_meeting_data(meeting_id)
+        print(f"✅ {meeting_id} 데이터 정리 완료")
+
+    except Exception as e:
+        print(f"❌ 오류 발생: {e}")
+    finally:
+        await redis_service.disconnect()
+        print("✅ Redis 연결 종료")
+
+if __name__ == "__main__":
+    asyncio.run(cleanup())

ai-python/logs/ai-python.log

@@ -1,2 +1,213 @@
+/Users/jominseo/HGZero/ai-python/main.py:45: DeprecationWarning: 
+        on_event is deprecated, use lifespan event handlers instead.
+
+        Read more about it in the
+        [FastAPI docs for Lifespan Events](https://fastapi.tiangolo.com/advanced/events/).
+        
+  @app.on_event("startup")
 INFO:     Will watch for changes in these directories: ['/Users/jominseo/HGZero/ai-python']
-ERROR:    [Errno 48] Address already in use
+INFO:     Uvicorn running on http://0.0.0.0:8086 (Press CTRL+C to quit)
+INFO:     Started reloader process [83849] using WatchFiles
+INFO:     Started server process [83852]
+INFO:     Waiting for application startup.
+2025-10-29 17:40:52,272 - main - INFO - 애플리케이션 시작 - Event Hub 리스너 백그라운드 실행
+2025-10-29 17:40:52,272 - app.services.eventhub_service - INFO - Event Hub 리스너 시작
+INFO:     Application startup complete.
+2025-10-29 17:40:52,370 - app.services.redis_service - INFO - Redis 연결 성공
+2025-10-29 17:40:52,370 - azure.eventhub.aio._eventprocessor.event_processor - INFO - EventProcessor 'e4acf592-7d23-4eed-bfc5-79f73d26adbb' is being started
+2025-10-29 17:40:52,504 - azure.eventhub._pyamqp.aio._connection_async - INFO - Connection state changed: None -> <ConnectionState.START: 0>
+2025-10-29 17:40:52,531 - azure.eventhub._pyamqp.aio._connection_async - INFO - Connection state changed: <ConnectionState.START: 0> -> <ConnectionState.HDR_SENT: 2>
+2025-10-29 17:40:52,531 - azure.eventhub._pyamqp.aio._connection_async - INFO - Connection state changed: <ConnectionState.HDR_SENT: 2> -> <ConnectionState.HDR_SENT: 2>
+2025-10-29 17:40:52,531 - azure.eventhub._pyamqp.aio._connection_async - INFO - Connection state changed: <ConnectionState.HDR_SENT: 2> -> <ConnectionState.OPEN_PIPE: 4>
+2025-10-29 17:40:52,531 - azure.eventhub._pyamqp.aio._session_async - INFO - Session state changed: <SessionState.UNMAPPED: 0> -> <SessionState.BEGIN_SENT: 1>
+2025-10-29 17:40:52,531 - azure.eventhub._pyamqp.aio._link_async - INFO - Link state changed: <LinkState.DETACHED: 0> -> <LinkState.ATTACH_SENT: 1>
+2025-10-29 17:40:52,531 - azure.eventhub._pyamqp.aio._management_link_async - INFO - Management link receiver state changed: <LinkState.DETACHED: 0> -> <LinkState.ATTACH_SENT: 1>
+2025-10-29 17:40:52,532 - azure.eventhub._pyamqp.aio._link_async - INFO - Link state changed: <LinkState.DETACHED: 0> -> <LinkState.ATTACH_SENT: 1>
+2025-10-29 17:40:52,532 - azure.eventhub._pyamqp.aio._management_link_async - INFO - Management link sender state changed: <LinkState.DETACHED: 0> -> <LinkState.ATTACH_SENT: 1>
+2025-10-29 17:40:52,545 - azure.eventhub._pyamqp.aio._connection_async - INFO - Connection state changed: <ConnectionState.OPEN_PIPE: 4> -> <ConnectionState.OPEN_SENT: 7>
+2025-10-29 17:40:52,595 - azure.eventhub._pyamqp.aio._connection_async - INFO - Connection state changed: <ConnectionState.OPEN_SENT: 7> -> <ConnectionState.OPENED: 9>
+2025-10-29 17:40:52,647 - azure.eventhub._pyamqp.aio._session_async - INFO - Session state changed: <SessionState.BEGIN_SENT: 1> -> <SessionState.MAPPED: 3>
+2025-10-29 17:40:52,698 - azure.eventhub._pyamqp.aio._link_async - INFO - Link state changed: <LinkState.ATTACH_SENT: 1> -> <LinkState.ATTACHED: 3>
+2025-10-29 17:40:52,699 - azure.eventhub._pyamqp.aio._management_link_async - INFO - Management link receiver state changed: <LinkState.ATTACH_SENT: 1> -> <LinkState.ATTACHED: 3>
+2025-10-29 17:40:52,750 - azure.eventhub._pyamqp.aio._link_async - INFO - Link state changed: <LinkState.ATTACH_SENT: 1> -> <LinkState.ATTACHED: 3>
+2025-10-29 17:40:52,750 - azure.eventhub._pyamqp.aio._management_link_async - INFO - Management link sender state changed: <LinkState.ATTACH_SENT: 1> -> <LinkState.ATTACHED: 3>
+2025-10-29 17:40:52,750 - azure.eventhub._pyamqp.aio._cbs_async - INFO - CBS completed opening with status: <ManagementOpenResult.OK: 1>
+2025-10-29 17:40:52,955 - azure.eventhub._pyamqp.aio._link_async - INFO - Link state changed: <LinkState.DETACHED: 0> -> <LinkState.ATTACH_SENT: 1>
+2025-10-29 17:40:52,955 - azure.eventhub._pyamqp.aio._management_link_async - INFO - Management link receiver state changed: <LinkState.DETACHED: 0> -> <LinkState.ATTACH_SENT: 1>
+2025-10-29 17:40:52,955 - azure.eventhub._pyamqp.aio._link_async - INFO - Link state changed: <LinkState.DETACHED: 0> -> <LinkState.ATTACH_SENT: 1>
+2025-10-29 17:40:52,955 - azure.eventhub._pyamqp.aio._management_link_async - INFO - Management link sender state changed: <LinkState.DETACHED: 0> -> <LinkState.ATTACH_SENT: 1>
+2025-10-29 17:40:52,967 - azure.eventhub._pyamqp.aio._link_async - INFO - Link state changed: <LinkState.ATTACH_SENT: 1> -> <LinkState.ATTACHED: 3>
+2025-10-29 17:40:52,967 - azure.eventhub._pyamqp.aio._management_link_async - INFO - Management link receiver state changed: <LinkState.ATTACH_SENT: 1> -> <LinkState.ATTACHED: 3>
+2025-10-29 17:40:52,967 - azure.eventhub._pyamqp.aio._link_async - INFO - Link state changed: <LinkState.ATTACH_SENT: 1> -> <LinkState.ATTACHED: 3>
+2025-10-29 17:40:52,967 - azure.eventhub._pyamqp.aio._management_link_async - INFO - Management link sender state changed: <LinkState.ATTACH_SENT: 1> -> <LinkState.ATTACHED: 3>
+2025-10-29 17:40:52,976 - azure.eventhub._pyamqp.aio._link_async - INFO - Link state changed: <LinkState.ATTACHED: 3> -> <LinkState.DETACH_SENT: 4>
+2025-10-29 17:40:52,976 - azure.eventhub._pyamqp.aio._management_link_async - INFO - Management link receiver state changed: <LinkState.ATTACHED: 3> -> <LinkState.DETACH_SENT: 4>
+2025-10-29 17:40:52,976 - azure.eventhub._pyamqp.aio._link_async - INFO - Link state changed: <LinkState.ATTACHED: 3> -> <LinkState.DETACH_SENT: 4>
+2025-10-29 17:40:52,976 - azure.eventhub._pyamqp.aio._management_link_async - INFO - Management link sender state changed: <LinkState.ATTACHED: 3> -> <LinkState.DETACH_SENT: 4>
+2025-10-29 17:40:52,976 - azure.eventhub._pyamqp.aio._link_async - INFO - Link state changed: <LinkState.ATTACHED: 3> -> <LinkState.DETACH_SENT: 4>
+2025-10-29 17:40:52,976 - azure.eventhub._pyamqp.aio._management_link_async - INFO - Management link sender state changed: <LinkState.ATTACHED: 3> -> <LinkState.DETACH_SENT: 4>
+2025-10-29 17:40:52,976 - azure.eventhub._pyamqp.aio._link_async - INFO - Link state changed: <LinkState.ATTACHED: 3> -> <LinkState.DETACH_SENT: 4>
+2025-10-29 17:40:52,976 - azure.eventhub._pyamqp.aio._management_link_async - INFO - Management link receiver state changed: <LinkState.ATTACHED: 3> -> <LinkState.DETACH_SENT: 4>
+2025-10-29 17:40:52,976 - azure.eventhub._pyamqp.aio._session_async - INFO - Session state changed: <SessionState.MAPPED: 3> -> <SessionState.END_SENT: 4>
+2025-10-29 17:40:52,976 - azure.eventhub._pyamqp.aio._connection_async - INFO - Connection state changed: <ConnectionState.OPENED: 9> -> <ConnectionState.CLOSE_SENT: 11>
+2025-10-29 17:40:52,976 - azure.eventhub._pyamqp.aio._connection_async - INFO - Connection state changed: <ConnectionState.CLOSE_SENT: 11> -> <ConnectionState.END: 13>
+2025-10-29 17:40:52,976 - azure.eventhub._pyamqp.aio._session_async - INFO - Session state changed: <SessionState.END_SENT: 4> -> <SessionState.DISCARDING: 6>
+2025-10-29 17:40:52,976 - azure.eventhub._pyamqp.aio._link_async - INFO - Link state changed: <LinkState.DETACH_SENT: 4> -> <LinkState.DETACHED: 0>
+2025-10-29 17:40:52,976 - azure.eventhub._pyamqp.aio._management_link_async - INFO - Management link sender state changed: <LinkState.DETACH_SENT: 4> -> <LinkState.DETACHED: 0>
+2025-10-29 17:40:52,976 - azure.eventhub._pyamqp.aio._link_async - INFO - Link state changed: <LinkState.DETACH_SENT: 4> -> <LinkState.DETACHED: 0>
+2025-10-29 17:40:52,977 - azure.eventhub._pyamqp.aio._management_link_async - INFO - Management link receiver state changed: <LinkState.DETACH_SENT: 4> -> <LinkState.DETACHED: 0>
+2025-10-29 17:40:52,977 - azure.eventhub._pyamqp.aio._link_async - INFO - Link state changed: <LinkState.DETACH_SENT: 4> -> <LinkState.DETACHED: 0>
+2025-10-29 17:40:52,977 - azure.eventhub._pyamqp.aio._management_link_async - INFO - Management link sender state changed: <LinkState.DETACH_SENT: 4> -> <LinkState.DETACHED: 0>
+2025-10-29 17:40:52,977 - azure.eventhub._pyamqp.aio._link_async - INFO - Link state changed: <LinkState.DETACH_SENT: 4> -> <LinkState.DETACHED: 0>
+2025-10-29 17:40:52,977 - azure.eventhub._pyamqp.aio._management_link_async - INFO - Management link receiver state changed: <LinkState.DETACH_SENT: 4> -> <LinkState.DETACHED: 0>
+2025-10-29 17:40:52,977 - azure.eventhub.aio._eventprocessor.event_processor - INFO - EventProcessor 'e4acf592-7d23-4eed-bfc5-79f73d26adbb' has claimed partition '0'
+2025-10-29 17:40:52,977 - azure.eventhub.aio._eventprocessor.event_processor - INFO - start ownership '0', checkpoint None
+2025-10-29 17:40:53,043 - azure.eventhub._pyamqp.aio._connection_async - INFO - Connection state changed: None -> <ConnectionState.START: 0>
+2025-10-29 17:40:53,068 - azure.eventhub._pyamqp.aio._connection_async - INFO - Connection state changed: <ConnectionState.START: 0> -> <ConnectionState.HDR_SENT: 2>
+2025-10-29 17:40:53,068 - azure.eventhub._pyamqp.aio._connection_async - INFO - Connection state changed: <ConnectionState.HDR_SENT: 2> -> <ConnectionState.HDR_SENT: 2>
+2025-10-29 17:40:53,068 - azure.eventhub._pyamqp.aio._connection_async - INFO - Connection state changed: <ConnectionState.HDR_SENT: 2> -> <ConnectionState.OPEN_PIPE: 4>
+2025-10-29 17:40:53,068 - azure.eventhub._pyamqp.aio._session_async - INFO - Session state changed: <SessionState.UNMAPPED: 0> -> <SessionState.BEGIN_SENT: 1>
+2025-10-29 17:40:53,069 - azure.eventhub._pyamqp.aio._link_async - INFO - Link state changed: <LinkState.DETACHED: 0> -> <LinkState.ATTACH_SENT: 1>
+2025-10-29 17:40:53,069 - azure.eventhub._pyamqp.aio._management_link_async - INFO - Management link receiver state changed: <LinkState.DETACHED: 0> -> <LinkState.ATTACH_SENT: 1>
+2025-10-29 17:40:53,069 - azure.eventhub._pyamqp.aio._link_async - INFO - Link state changed: <LinkState.DETACHED: 0> -> <LinkState.ATTACH_SENT: 1>
+2025-10-29 17:40:53,069 - azure.eventhub._pyamqp.aio._management_link_async - INFO - Management link sender state changed: <LinkState.DETACHED: 0> -> <LinkState.ATTACH_SENT: 1>
+2025-10-29 17:40:53,083 - azure.eventhub._pyamqp.aio._connection_async - INFO - Connection state changed: <ConnectionState.OPEN_PIPE: 4> -> <ConnectionState.OPEN_SENT: 7>
+2025-10-29 17:40:53,134 - azure.eventhub._pyamqp.aio._connection_async - INFO - Connection state changed: <ConnectionState.OPEN_SENT: 7> -> <ConnectionState.OPENED: 9>
+2025-10-29 17:40:53,185 - azure.eventhub._pyamqp.aio._session_async - INFO - Session state changed: <SessionState.BEGIN_SENT: 1> -> <SessionState.MAPPED: 3>
+2025-10-29 17:40:53,236 - azure.eventhub._pyamqp.aio._link_async - INFO - Link state changed: <LinkState.ATTACH_SENT: 1> -> <LinkState.ATTACHED: 3>
+2025-10-29 17:40:53,236 - azure.eventhub._pyamqp.aio._management_link_async - INFO - Management link receiver state changed: <LinkState.ATTACH_SENT: 1> -> <LinkState.ATTACHED: 3>
+2025-10-29 17:40:53,288 - azure.eventhub._pyamqp.aio._link_async - INFO - Link state changed: <LinkState.ATTACH_SENT: 1> -> <LinkState.ATTACHED: 3>
+2025-10-29 17:40:53,288 - azure.eventhub._pyamqp.aio._management_link_async - INFO - Management link sender state changed: <LinkState.ATTACH_SENT: 1> -> <LinkState.ATTACHED: 3>
+2025-10-29 17:40:53,288 - azure.eventhub._pyamqp.aio._cbs_async - INFO - CBS completed opening with status: <ManagementOpenResult.OK: 1>
+2025-10-29 17:40:53,491 - azure.eventhub._pyamqp.aio._link_async - INFO - Link state changed: <LinkState.DETACHED: 0> -> <LinkState.ATTACH_SENT: 1>
+2025-10-29 17:40:53,503 - azure.eventhub._pyamqp.aio._link_async - INFO - Link state changed: <LinkState.ATTACH_SENT: 1> -> <LinkState.ATTACHED: 3>
+2025-10-29 17:40:53,592 - app.services.eventhub_service - INFO - 수신한 이벤트 원본 (처음 300자): {"eventId":"7436b96c-3a60-418b-848d-727770d7cfd9","eventType":"SegmentCreated","segmentId":"9483cf8a-e41e-49e9-b2c0-28519bba798d","recordingId":"test-meeting-001","meetingId":"test-meeting-001","text”:”오늘은 OFDM 기술 적용방안과 AICC 구축 협의에 대해 논의해보겠습니다.”,”speakerId":"UNKNOWN","speakerName":"참석자","timestamp":
+2025-10-29 17:40:53,592 - app.services.eventhub_service - INFO - 수신한 이벤트 원본 (처음 300자): {"eventId":"7436b96c-3a60-418b-848d-727770d7cfd9","eventType":"SegmentCreated","segmentId":"9483cf8a-e41e-49e9-b2c0-28519bba798d","recordingId":"test-meeting-001","meetingId":"test-meeting-001","text”:”오늘은 OFDM 기술 적용방안과 AICC 구축 협의에 대해 논의해보겠습니다.”,”speakerId":"UNKNOWN","speakerName":"참석자","timestamp":
+2025-10-29 17:40:53,593 - app.services.eventhub_service - INFO - 수신한 이벤트 원본 (처음 300자): {"eventId":"7436b96c-3a60-418b-848d-727770d7cfd9","eventType":"SegmentCreated","segmentId":"9483cf8a-e41e-49e9-b2c0-28519bba798e”,”recordingId":"test-meeting-001","meetingId":"test-meeting-001","text”:”오늘은 OFDM 기술 적용방안과 AICC 구축 협의에 대해 논의해보겠습니다.”,”speakerId":"UNKNOWN","speakerName":"참석자","timestamp":
+2025-10-29 17:40:53,593 - app.services.eventhub_service - ERROR - 이벤트 처리 오류: Expecting ',' delimiter: line 1 column 144 (char 143)
+Traceback (most recent call last):
+  File "/Users/jominseo/HGZero/ai-python/app/services/eventhub_service.py", line 71, in on_event
+    event_data = json.loads(raw_body)
+  File "/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/__init__.py", line 346, in loads
+    return _default_decoder.decode(s)
+           ~~~~~~~~~~~~~~~~~~~~~~~^^^
+  File "/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/decoder.py", line 345, in decode
+    obj, end = self.raw_decode(s, idx=_w(s, 0).end())
+               ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
+  File "/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/decoder.py", line 361, in raw_decode
+    obj, end = self.scan_once(s, idx)
+               ~~~~~~~~~~~~~~^^^^^^^^
+json.decoder.JSONDecodeError: Expecting ',' delimiter: line 1 column 144 (char 143)
+2025-10-29 17:40:53,597 - app.services.eventhub_service - INFO - 수신한 이벤트 원본 (처음 300자): {"eventId":"7436b96c-3a60-418b-848d-727770d7cfe9","eventType":"SegmentCreated","segmentId":"9483cf8a-e41e-49e9-b2c0-28519bba798e”,”recordingId":"test-meeting-001","meetingId":"test-meeting-001","text”:”오늘은 OFDM 기술 적용방안과 AICC 구축 협의에 대해 논의해보겠습니다.”,”speakerId":"UNKNOWN","speakerName":"참석자","timestamp":
+2025-10-29 17:40:53,597 - app.services.eventhub_service - ERROR - 이벤트 처리 오류: Expecting ',' delimiter: line 1 column 144 (char 143)
+Traceback (most recent call last):
+  File "/Users/jominseo/HGZero/ai-python/app/services/eventhub_service.py", line 71, in on_event
+    event_data = json.loads(raw_body)
+  File "/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/__init__.py", line 346, in loads
+    return _default_decoder.decode(s)
+           ~~~~~~~~~~~~~~~~~~~~~~~^^^
+  File "/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/decoder.py", line 345, in decode
+    obj, end = self.raw_decode(s, idx=_w(s, 0).end())
+               ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
+  File "/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/decoder.py", line 361, in raw_decode
+    obj, end = self.scan_once(s, idx)
+               ~~~~~~~~~~~~~~^^^^^^^^
+json.decoder.JSONDecodeError: Expecting ',' delimiter: line 1 column 144 (char 143)
+2025-10-29 17:40:53,598 - app.services.eventhub_service - INFO - 수신한 이벤트 원본 (처음 300자): {"eventId":"7436b96c-3a60-418b-848d-727770d7cfd9","eventType":"SegmentCreated","segmentId":"9483cf8a-e41e-49e9-b2c0-28519bba798d","recordingId":"test-meeting-001","meetingId":"test-meeting-001","text":"신제품 개발 일정에 대해 논의하고 있습니다.","speakerId":"UNKNOWN","speakerName":"참석자","timestamp":[2025,10,29,10,25,
+2025-10-29 17:40:53,598 - app.services.eventhub_service - INFO - STT 텍스트 수신 - meetingId: test-meeting-001, 텍스트 길이: 24, timestamp: 1761701136000
+2025-10-29 17:40:53,618 - app.services.eventhub_service - INFO - ✅ Redis 저장 완료 - meetingId: test-meeting-001, timestamp: 1761701136000
+2025-10-29 17:40:53,618 - app.services.eventhub_service - INFO - 수신한 이벤트 원본 (처음 300자): {"eventId":"7436b96c-3a60-418b-848d-727770d7cfd9","eventType":"SegmentCreated","segmentId":"9483cf8a-e41e-49e9-b2c0-28519bba798d","recordingId":"test-meeting-001","meetingId":"test-meeting-001","text":"오늘은 OFDM 기술 적용방안과 AICC 구축 협의에 대해 논의해보겠습니다.","speakerId":"UNKNOWN","speakerName":"참석자","timestamp":
+2025-10-29 17:40:53,618 - app.services.eventhub_service - INFO - STT 텍스트 수신 - meetingId: test-meeting-001, 텍스트 길이: 42, timestamp: 1761701137000
+2025-10-29 17:40:53,637 - app.services.eventhub_service - INFO - ✅ Redis 저장 완료 - meetingId: test-meeting-001, timestamp: 1761701137000
+2025-10-29 17:40:53,638 - app.services.eventhub_service - INFO - 수신한 이벤트 원본 (처음 300자): {"eventId":"7436b96c-3a60-418b-848d-727770d7cfd9","eventType":"SegmentCreated","segmentId":"9483cf8a-e41e-49e9-b2c0-28519bba798d","recordingId":"test-meeting-001","meetingId":"test-meeting-001”,”sessionId”:”meeting-123”,“text":"오늘은 OFDM 기술 적용방안과 AICC 구축 협의에 대해 논의해보겠습니다.","speakerId":"UNKNOWN","speak
+2025-10-29 17:40:53,638 - app.services.eventhub_service - ERROR - 이벤트 처리 오류: Expecting ',' delimiter: line 1 column 227 (char 226)
+Traceback (most recent call last):
+  File "/Users/jominseo/HGZero/ai-python/app/services/eventhub_service.py", line 71, in on_event
+    event_data = json.loads(raw_body)
+  File "/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/__init__.py", line 346, in loads
+    return _default_decoder.decode(s)
+           ~~~~~~~~~~~~~~~~~~~~~~~^^^
+  File "/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/decoder.py", line 345, in decode
+    obj, end = self.raw_decode(s, idx=_w(s, 0).end())
+               ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
+  File "/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/decoder.py", line 361, in raw_decode
+    obj, end = self.scan_once(s, idx)
+               ~~~~~~~~~~~~~~^^^^^^^^
+json.decoder.JSONDecodeError: Expecting ',' delimiter: line 1 column 227 (char 226)
+2025-10-29 17:40:53,639 - app.services.eventhub_service - INFO - 수신한 이벤트 원본 (처음 300자): {"eventId":"7436b96c-3a60-418b-848d-727770d7cfd9","eventType":"SegmentCreated","segmentId":"9483cf8a-e41e-49e9-b2c0-28519bba798d","recordingId":"test-meeting-001","meetingId":"test-meeting-001”,”sessionId”:”meeting-123”,“text":"오늘은 OFDM 기술 적용방안과 AICC 구축 협의에 대해 논의해보겠습니다.","speakerId":"UNKNOWN","speak
+2025-10-29 17:40:53,639 - app.services.eventhub_service - ERROR - 이벤트 처리 오류: Expecting ',' delimiter: line 1 column 227 (char 226)
+Traceback (most recent call last):
+  File "/Users/jominseo/HGZero/ai-python/app/services/eventhub_service.py", line 71, in on_event
+    event_data = json.loads(raw_body)
+  File "/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/__init__.py", line 346, in loads
+    return _default_decoder.decode(s)
+           ~~~~~~~~~~~~~~~~~~~~~~~^^^
+  File "/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/decoder.py", line 345, in decode
+    obj, end = self.raw_decode(s, idx=_w(s, 0).end())
+               ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
+  File "/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/decoder.py", line 361, in raw_decode
+    obj, end = self.scan_once(s, idx)
+               ~~~~~~~~~~~~~~^^^^^^^^
+json.decoder.JSONDecodeError: Expecting ',' delimiter: line 1 column 227 (char 226)
+2025-10-29 17:40:53,640 - app.services.eventhub_service - INFO - 수신한 이벤트 원본 (처음 300자): {"eventId":"7436b96c-3a60-418b-848d-727770d7cfd9","eventType":"SegmentCreated","segmentId":"9483cf8a-e41e-49e9-b2c0-28519bba798d","recordingId":"test-meeting-001","meetingId":"test-meeting-001","text":"오늘은 OFDM 기술 적용방안과 AICC 구축 협의에 대해 논의해보겠습니다.","speakerId":"UNKNOWN","speakerName":"참석자","timestamp":
+2025-10-29 17:40:53,641 - app.services.eventhub_service - INFO - STT 텍스트 수신 - meetingId: test-meeting-001, 텍스트 길이: 42, timestamp: 1761701137000
+2025-10-29 17:40:53,660 - app.services.eventhub_service - INFO - ✅ Redis 저장 완료 - meetingId: test-meeting-001, timestamp: 1761701137000
+2025-10-29 17:40:53,661 - app.services.eventhub_service - INFO - 수신한 이벤트 원본 (처음 300자): {"eventId":"7436b96c-3a60-418b-848d-727770d7cfd9","eventType":"SegmentCreated","segmentId":"9483cf8a-e41e-49e9-b2c0-28519bba798d","recordingId":"test-meeting-001","meetingId":"test-meeting-001”,”sessionId”:”meeting-123”,“text":"오늘은 OFDM 기술 적용방안과 AICC 구축 협의에 대해 논의해보겠습니다.","speakerId":"UNKNOWN","speak
+2025-10-29 17:40:53,661 - app.services.eventhub_service - ERROR - 이벤트 처리 오류: Expecting ',' delimiter: line 1 column 227 (char 226)
+Traceback (most recent call last):
+  File "/Users/jominseo/HGZero/ai-python/app/services/eventhub_service.py", line 71, in on_event
+    event_data = json.loads(raw_body)
+  File "/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/__init__.py", line 346, in loads
+    return _default_decoder.decode(s)
+           ~~~~~~~~~~~~~~~~~~~~~~~^^^
+  File "/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/decoder.py", line 345, in decode
+    obj, end = self.raw_decode(s, idx=_w(s, 0).end())
+               ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
+  File "/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/decoder.py", line 361, in raw_decode
+    obj, end = self.scan_once(s, idx)
+               ~~~~~~~~~~~~~~^^^^^^^^
+json.decoder.JSONDecodeError: Expecting ',' delimiter: line 1 column 227 (char 226)
+2025-10-29 17:40:53,662 - app.services.eventhub_service - INFO - 수신한 이벤트 원본 (처음 300자): {"eventId":"7436b96c-3a60-418b-848d-727770d7cfd9","eventType":"SegmentCreated","segmentId":"9483cf8a-e41e-49e9-b2c0-28519bba798d","recordingId":"test-meeting-001","meetingId":"test-meeting-001”,”sessionId”:”meeting-123”,“text":"오늘은 OFDM. 기술 적용방안과 AICC 구축 협의에 대해 논의해보겠습니다.","speakerId":"UNKNOWN","spea
+2025-10-29 17:40:53,662 - app.services.eventhub_service - ERROR - 이벤트 처리 오류: Expecting ',' delimiter: line 1 column 227 (char 226)
+Traceback (most recent call last):
+  File "/Users/jominseo/HGZero/ai-python/app/services/eventhub_service.py", line 71, in on_event
+    event_data = json.loads(raw_body)
+  File "/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/__init__.py", line 346, in loads
+    return _default_decoder.decode(s)
+           ~~~~~~~~~~~~~~~~~~~~~~~^^^
+  File "/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/decoder.py", line 345, in decode
+    obj, end = self.raw_decode(s, idx=_w(s, 0).end())
+               ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
+  File "/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/decoder.py", line 361, in raw_decode
+    obj, end = self.scan_once(s, idx)
+               ~~~~~~~~~~~~~~^^^^^^^^
+json.decoder.JSONDecodeError: Expecting ',' delimiter: line 1 column 227 (char 226)
+2025-10-29 17:40:53,663 - app.services.eventhub_service - INFO - 수신한 이벤트 원본 (처음 300자): {"eventId":"7436b96c-3a60-418b-848d-727770d7cfd9","eventType":"SegmentCreated","segmentId":"9483cf8a-e41e-49e9-b2c0-28519bba798d","recordingId":"test-meeting-001","meetingId":"test-meeting-001”,”sessionId”:”meeting-123”,“text":"오늘은 OFDM. 기술 적용방안과 AICC 구축 협의에 대해 논의해보겠습니다.","speakerId":"UNKNOWN","spea
+2025-10-29 17:40:53,663 - app.services.eventhub_service - ERROR - 이벤트 처리 오류: Expecting ',' delimiter: line 1 column 227 (char 226)
+Traceback (most recent call last):
+  File "/Users/jominseo/HGZero/ai-python/app/services/eventhub_service.py", line 71, in on_event
+    event_data = json.loads(raw_body)
+  File "/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/__init__.py", line 346, in loads
+    return _default_decoder.decode(s)
+           ~~~~~~~~~~~~~~~~~~~~~~~^^^
+  File "/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/decoder.py", line 345, in decode
+    obj, end = self.raw_decode(s, idx=_w(s, 0).end())
+               ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
+  File "/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/decoder.py", line 361, in raw_decode
+    obj, end = self.scan_once(s, idx)
+               ~~~~~~~~~~~~~~^^^^^^^^
+json.decoder.JSONDecodeError: Expecting ',' delimiter: line 1 column 227 (char 226)
+2025-10-29 17:40:53,664 - app.services.eventhub_service - INFO - 수신한 이벤트 원본 (처음 300자): {"eventId":"7436b96c-3a60-418b-848d-727770d7dgd9","eventType":"SegmentCreated","segmentId":"9483cf8a-e41e-49e9-b2c0-28519bdg798d","recordingId":"test-meeting-001","meetingId":"test-meeting-001","sessionId":"meeting-123","text":"오늘은 OFDM. 기술 적용방안과 AICC 구축 협의에 대해 논의해보겠습니다.","speakerId":"UNKNOWN","spea
+2025-10-29 17:40:53,664 - app.services.eventhub_service - INFO - STT 텍스트 수신 - meetingId: test-meeting-001, 텍스트 길이: 43, timestamp: 1761701137000
+2025-10-29 17:40:53,685 - app.services.eventhub_service - INFO - ✅ Redis 저장 완료 - meetingId: test-meeting-001, timestamp: 1761701137000
+INFO:     127.0.0.1:49558 - "GET /health HTTP/1.1" 200 OK
+2025-10-29 17:42:22,649 - app.services.eventhub_service - INFO - 수신한 이벤트 원본 (처음 300자): {"eventId":"7436b96c-3a60-418b-848d-727770d7dgd9","eventType":"SegmentCreated","segmentId":"9483cf8a-e41e-49e9-b2c0-28519bdg798d","recordingId":"test-meeting-001","meetingId":"test-meeting-001","sessionId":"meeting-123","text":"오늘은 OFDM. 기술 적용방안과 AICC 구축 협의에 대해 논의해보겠습니다.","speakerId":"UNKNOWN","spea
+2025-10-29 17:42:22,649 - app.services.eventhub_service - INFO - STT 텍스트 수신 - meetingId: test-meeting-001, 텍스트 길이: 43, timestamp: 1761701137000
+2025-10-29 17:42:22,667 - app.services.eventhub_service - INFO - ✅ Redis 저장 완료 - meetingId: test-meeting-001, timestamp: 1761701137000
+2025-10-29 17:42:52,639 - watchfiles.main - INFO - 3 changes detected
+2025-10-29 17:42:55,136 - watchfiles.main - INFO - 3 changes detected
+INFO:     Shutting down
+INFO:     Waiting for application shutdown.
+INFO:     Application shutdown complete.
+INFO:     Finished server process [83852]
+INFO:     Stopping reloader process [83849]

ai-python/main.py

@@ -4,7 +4,9 @@ from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 from app.config import get_settings
 from app.api.v1 import router as api_v1_router
+from app.services.eventhub_service import start_eventhub_listener
 import logging
+import asyncio
 
 # 로깅 설정
 logging.basicConfig(
@@ -36,7 +38,15 @@ app.add_middleware(
 )
 
 # API 라우터 등록
-app.include_router(api_v1_router, prefix="/api")
+app.include_router(api_v1_router, prefix="/api/v1")
+
+
+# Event Hub 리스너 백그라운드 태스크
+@app.on_event("startup")
+async def startup_event():
+    """애플리케이션 시작 시 Event Hub 리스너 시작"""
+    logger.info("애플리케이션 시작 - Event Hub 리스너 백그라운드 실행")
+    asyncio.create_task(start_eventhub_listener())
 
 
 @app.get("/health")

ai-python/restart.sh

@@ -0,0 +1,115 @@
+#!/bin/bash
+
+# AI Python 서비스 재시작 스크립트
+# 8087 포트로 깔끔하게 재시작
+
+echo "=================================="
+echo "AI Python 서비스 재시작"
+echo "=================================="
+
+# 1. 기존 프로세스 종료
+echo "1️⃣ 기존 프로세스 정리 중..."
+pkill -9 -f "python.*main.py" 2>/dev/null
+pkill -9 -f "uvicorn.*8086" 2>/dev/null
+pkill -9 -f "uvicorn.*8087" 2>/dev/null
+
+# 잠시 대기 (포트 해제 대기)
+sleep 2
+
+# 2. 포트 확인
+echo "2️⃣ 포트 상태 확인..."
+if lsof -i:8087 > /dev/null 2>&1; then
+    echo "   ⚠️  8087 포트가 아직 사용 중입니다."
+    echo "   강제 종료 시도..."
+    PID=$(lsof -ti:8087)
+    if [ ! -z "$PID" ]; then
+        kill -9 $PID
+        sleep 2
+    fi
+fi
+
+if lsof -i:8087 > /dev/null 2>&1; then
+    echo "   ❌ 8087 포트를 해제할 수 없습니다."
+    echo "   시스템 재부팅 후 다시 시도하거나,"
+    echo "   다른 포트를 사용하세요."
+    exit 1
+else
+    echo "   ✅ 8087 포트 사용 가능"
+fi
+
+# 3. 가상환경 활성화
+echo "3️⃣ 가상환경 활성화..."
+if [ ! -d "venv" ]; then
+    echo "   ❌ 가상환경이 없습니다. venv 디렉토리를 생성하세요."
+    exit 1
+fi
+
+source venv/bin/activate
+echo "   ✅ 가상환경 활성화 완료"
+
+# 4. 로그 디렉토리 확인
+mkdir -p ../logs
+
+# 5. 서비스 시작
+echo "4️⃣ AI Python 서비스 시작 (포트: 8087)..."
+nohup python3 main.py > ../logs/ai-python.log 2>&1 &
+PID=$!
+
+echo "   PID: $PID"
+echo "   로그: ../logs/ai-python.log"
+
+# 6. 시작 대기
+echo "5️⃣ 서비스 시작 대기 (7초)..."
+sleep 7
+
+# 7. 상태 확인
+echo "6️⃣ 서비스 상태 확인..."
+
+# 프로세스 확인
+if ps -p $PID > /dev/null; then
+    echo "   ✅ 프로세스 실행 중 (PID: $PID)"
+else
+    echo "   ❌ 프로세스 종료됨"
+    echo "   로그 확인:"
+    tail -20 ../logs/ai-python.log
+    exit 1
+fi
+
+# 포트 확인
+if lsof -i:8087 > /dev/null 2>&1; then
+    echo "   ✅ 8087 포트 리스닝 중"
+else
+    echo "   ⚠️  8087 포트 아직 준비 중..."
+fi
+
+# Health 체크
+echo "7️⃣ Health Check..."
+sleep 2
+HEALTH=$(curl -s http://localhost:8087/health 2>/dev/null)
+
+if [ $? -eq 0 ]; then
+    echo "   ✅ Health Check 성공"
+    echo "   $HEALTH"
+else
+    echo "   ⚠️  Health Check 실패 (서버가 아직 시작 중일 수 있습니다)"
+    echo ""
+    echo "   최근 로그:"
+    tail -10 ../logs/ai-python.log
+fi
+
+echo ""
+echo "=================================="
+echo "✅ AI Python 서비스 시작 완료"
+echo "=================================="
+echo "📊 서비스 정보:"
+echo "   - PID: $PID"
+echo "   - 포트: 8087"
+echo "   - 로그: tail -f ../logs/ai-python.log"
+echo ""
+echo "📡 엔드포인트:"
+echo "   - Health: http://localhost:8087/health"
+echo "   - Root: http://localhost:8087/"
+echo "   - Swagger: http://localhost:8087/swagger-ui.html"
+echo ""
+echo "🛑 서비스 중지: pkill -f 'python.*main.py'"
+echo "=================================="

ai/.run/ai-service.run.xml

@@ -57,7 +57,7 @@
           <entry key="AZURE_AI_SEARCH_INDEX" value="meeting-transcripts" />
 
           <!-- Azure Event Hubs Configuration -->
-          <entry key="AZURE_EVENTHUB_CONNECTION_STRING" value="Endpoint=sb://hgzero-eventhub-ns.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=VUqZ9vFgu35E3c6RiUzoOGVUP8IZpFvlV+AEhC6sUpo=" />
+          <entry key="AZURE_EVENTHUB_CONNECTION_STRING" value="Endpoint=sb://hgzero-eventhub-ns.servicebus.windows.net/;SharedAccessKeyName=ai-listen-policy;SharedAccessKey=wqcbVIXlOMyn/C562lx6DD75AyjHQ87xo+AEhJ7js9Q=;EntityPath=hgzero-eventhub-name" />
           <entry key="AZURE_EVENTHUB_NAMESPACE" value="hgzero-eventhub-ns" />
           <entry key="AZURE_EVENTHUB_NAME" value="hgzero-eventhub-name" />
           <entry key="AZURE_CHECKPOINT_STORAGE_CONNECTION_STRING" value="" />

ai/build.gradle

@@ -3,16 +3,38 @@ bootJar {
 }
 
 dependencies {
+    // Common module
+    implementation project(':common')
+
+    // Redis
+    implementation 'org.springframework.boot:spring-boot-starter-data-redis'
+
+    // PostgreSQL
+    runtimeOnly 'org.postgresql:postgresql'
+
     // OpenAI
     implementation "com.theokanning.openai-gpt3-java:service:${openaiVersion}"
 
+    // Anthropic Claude SDK
+    implementation 'com.anthropic:anthropic-java:2.1.0'
+
     // Azure AI Search
     implementation "com.azure:azure-search-documents:${azureAiSearchVersion}"
 
+    // Azure Event Hubs
+    implementation "com.azure:azure-messaging-eventhubs:${azureEventHubsVersion}"
+    implementation "com.azure:azure-messaging-eventhubs-checkpointstore-blob:${azureEventHubsCheckpointVersion}"
+
     // Feign (for external API calls)
     implementation "io.github.openfeign:feign-jackson:${feignJacksonVersion}"
     implementation "io.github.openfeign:feign-okhttp:${feignJacksonVersion}"
 
+    // Spring WebFlux for SSE streaming
+    implementation 'org.springframework.boot:spring-boot-starter-webflux'
+
+    // Springdoc OpenAPI
+    implementation "org.springdoc:springdoc-openapi-starter-webmvc-ui:${springdocVersion}"
+
     // H2 Database for local development
     runtimeOnly 'com.h2database:h2'
 }

ai/src/main/java/com/unicorn/hgzero/ai/biz/domain/RelatedMinutes.java

@@ -48,6 +48,11 @@ public class RelatedMinutes {
      */
     private List<String> commonKeywords;
 
+    /**
+     * 회의록 핵심 내용 요약 (1-2문장)
+     */
+    private String summary;
+
     /**
      * 회의록 링크
      */

ai/src/main/java/com/unicorn/hgzero/ai/biz/domain/Term.java

@@ -31,10 +31,26 @@ public class Term {
     private Double confidence;
 
     /**
-     * 용어 카테고리 (기술, 업무, 도메인)
+     * 용어 카테고리 (기술, 업무, 도메인, 기획, 비즈니스, 전략, 마케팅)
      */
     private String category;
 
+    /**
+     * 용어 정의 (간단한 설명)
+     */
+    private String definition;
+
+    /**
+     * 용어가 사용된 맥락 (과거 회의록 참조)
+     * 예: "신제품 기획 회의(2024-09-15)에서 언급"
+     */
+    private String context;
+
+    /**
+     * 관련 회의 ID (용어가 논의된 과거 회의)
+     */
+    private String relatedMeetingId;
+
     /**
      * 하이라이트 여부
      */

ai/src/main/java/com/unicorn/hgzero/ai/biz/service/SuggestionService.java

@@ -3,11 +3,22 @@ package com.unicorn.hgzero.ai.biz.service;
 import com.unicorn.hgzero.ai.biz.domain.Suggestion;
 import com.unicorn.hgzero.ai.biz.gateway.LlmGateway;
 import com.unicorn.hgzero.ai.biz.usecase.SuggestionUseCase;
+import com.unicorn.hgzero.ai.infra.client.ClaudeApiClient;
+import com.unicorn.hgzero.ai.infra.dto.common.SimpleSuggestionDto;
+import com.unicorn.hgzero.ai.infra.dto.common.RealtimeSuggestionsDto;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
+import org.springframework.data.redis.core.RedisTemplate;
 import org.springframework.stereotype.Service;
+import reactor.core.publisher.Flux;
+import reactor.core.publisher.Sinks;
 
+import java.time.Duration;
 import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.stream.Collectors;
 
 /**
  * 논의사항/결정사항 제안 Service
@@ -19,6 +30,15 @@ import java.util.List;
 public class SuggestionService implements SuggestionUseCase {
 
     private final LlmGateway llmGateway;
+    private final ClaudeApiClient claudeApiClient;
+    private final RedisTemplate<String, String> redisTemplate;
+
+    // 회의별 실시간 스트림 관리 (회의 ID -> Sink)
+    private final Map<String, Sinks.Many<RealtimeSuggestionsDto>> meetingSinks = new ConcurrentHashMap<>();
+
+    // 분석 임계값 설정 (MVP용 완화)
+    private static final int MIN_SEGMENTS_FOR_ANALYSIS = 5; // 5개 세그먼트 = 약 50-100자 (MVP용 완화)
+    private static final long TEXT_RETENTION_MS = 5 * 60 * 1000; // 5분
 
     @Override
     public List<Suggestion> suggestDiscussions(String meetingId, String transcriptText) {
@@ -66,4 +86,202 @@ public class SuggestionService implements SuggestionUseCase {
                 .build()
         );
     }
+
+    @Override
+    public Flux<RealtimeSuggestionsDto> streamRealtimeSuggestions(String meetingId) {
+        log.info("실시간 AI 제안사항 스트리밍 시작 - meetingId: {}", meetingId);
+
+        // Sink 생성 및 등록 (멀티캐스트 - 여러 클라이언트 동시 지원)
+        Sinks.Many<RealtimeSuggestionsDto> sink = Sinks.many()
+            .multicast()
+            .onBackpressureBuffer();
+
+        meetingSinks.put(meetingId, sink);
+
+        // TODO: AI 개발 완료 후 제거 - 개발 중 프론트엔드 테스트를 위한 Mock 데이터 자동 발행
+        startMockDataEmission(meetingId, sink);
+
+        return sink.asFlux()
+            .doOnCancel(() -> {
+                log.info("SSE 스트림 종료 - meetingId: {}", meetingId);
+                meetingSinks.remove(meetingId);
+                cleanupMeetingData(meetingId);
+            })
+            .doOnError(error ->
+                log.error("AI 제안사항 스트리밍 오류 - meetingId: {}", meetingId, error));
+    }
+
+    /**
+     * Event Hub에서 수신한 실시간 텍스트 처리
+     * STT Service에서 TranscriptSegmentReady 이벤트를 받아 처리
+     *
+     * @param meetingId 회의 ID
+     * @param text 변환된 텍스트 세그먼트
+     * @param timestamp 타임스탬프 (ms)
+     */
+    public void processRealtimeTranscript(String meetingId, String text, Long timestamp) {
+        try {
+            // 1. Redis에 실시간 텍스트 축적 (슬라이딩 윈도우: 최근 5분)
+            String key = "meeting:" + meetingId + ":transcript";
+            String value = timestamp + ":" + text;
+
+            redisTemplate.opsForZSet().add(key, value, timestamp.doubleValue());
+
+            // 5분 이전 데이터 제거
+            long fiveMinutesAgo = System.currentTimeMillis() - TEXT_RETENTION_MS;
+            redisTemplate.opsForZSet().removeRangeByScore(key, 0, fiveMinutesAgo);
+
+            // 2. 누적 텍스트가 임계값 이상이면 AI 분석
+            Long segmentCount = redisTemplate.opsForZSet().size(key);
+            if (segmentCount != null && segmentCount >= MIN_SEGMENTS_FOR_ANALYSIS) {
+                analyzeAndEmitSuggestions(meetingId);
+            }
+        } catch (Exception e) {
+            log.error("실시간 텍스트 처리 실패 - meetingId: {}", meetingId, e);
+        }
+    }
+
+    /**
+     * AI 분석 및 SSE 발행
+     */
+    private void analyzeAndEmitSuggestions(String meetingId) {
+        // Redis에서 최근 5분 텍스트 조회
+        String key = "meeting:" + meetingId + ":transcript";
+        Set<String> recentTexts = redisTemplate.opsForZSet().reverseRange(key, 0, -1);
+
+        if (recentTexts == null || recentTexts.isEmpty()) {
+            return;
+        }
+
+        // 타임스탬프 제거 및 텍스트만 추출
+        String accumulatedText = recentTexts.stream()
+            .map(entry -> entry.split(":", 2)[1])
+            .collect(Collectors.joining("\n"));
+
+        // Claude API 분석 (비동기)
+        claudeApiClient.analyzeSuggestions(accumulatedText)
+            .subscribe(
+                suggestions -> {
+                    // SSE 스트림으로 전송
+                    Sinks.Many<RealtimeSuggestionsDto> sink = meetingSinks.get(meetingId);
+                    if (sink != null) {
+                        sink.tryEmitNext(suggestions);
+                        log.info("AI 제안사항 발행 완료 - meetingId: {}, 제안사항: {}개",
+                            meetingId,
+                            suggestions.getSuggestions().size());
+                    }
+                },
+                error -> log.error("Claude API 분석 실패 - meetingId: {}", meetingId, error)
+            );
+    }
+
+    /**
+     * 회의 종료 시 데이터 정리
+     */
+    private void cleanupMeetingData(String meetingId) {
+        String key = "meeting:" + meetingId + ":transcript";
+        redisTemplate.delete(key);
+        log.info("회의 데이터 정리 완료 - meetingId: {}", meetingId);
+    }
+
+    /**
+     * TODO: AI 개발 완료 후 제거
+     * Mock 데이터 자동 발행 (프론트엔드 개발용)
+     * 5초마다 샘플 제안사항을 발행합니다.
+     */
+    private void startMockDataEmission(String meetingId, Sinks.Many<RealtimeSuggestionsDto> sink) {
+        log.info("Mock 데이터 자동 발행 시작 - meetingId: {}", meetingId);
+
+        // 프론트엔드 HTML에 맞춘 샘플 데이터 (3개)
+        List<SimpleSuggestionDto> mockSuggestions = List.of(
+            SimpleSuggestionDto.builder()
+                .id("suggestion-1")
+                .content("신제품의 타겟 고객층을 20-30대로 설정하고, 모바일 우선 전략을 취하기로 논의 중입니다.")
+                .timestamp("00:05:23")
+                .confidence(0.92)
+                .build(),
+            SimpleSuggestionDto.builder()
+                .id("suggestion-2")
+                .content("개발 일정: 1차 프로토타입은 11월 15일까지 완성, 2차 베타는 12월 1일 론칭")
+                .timestamp("00:08:45")
+                .confidence(0.88)
+                .build(),
+            SimpleSuggestionDto.builder()
+                .id("suggestion-3")
+                .content("마케팅 예산 배분에 대해 SNS 광고 60%, 인플루언서 마케팅 40%로 의견이 나왔으나 추가 검토 필요")
+                .timestamp("00:12:18")
+                .confidence(0.85)
+                .build()
+        );
+
+        // 5초마다 하나씩 발행 (총 3개)
+        Flux.interval(Duration.ofSeconds(5))
+            .take(3)
+            .map(index -> {
+                SimpleSuggestionDto suggestion = mockSuggestions.get(index.intValue());
+                return RealtimeSuggestionsDto.builder()
+                    .suggestions(List.of(suggestion))
+                    .build();
+            })
+            .subscribe(
+                suggestions -> {
+                    sink.tryEmitNext(suggestions);
+                    log.info("Mock 제안사항 발행 - meetingId: {}, 제안: {}",
+                        meetingId,
+                        suggestions.getSuggestions().get(0).getContent());
+                },
+                error -> log.error("Mock 데이터 발행 오류 - meetingId: {}", meetingId, error),
+                () -> log.info("Mock 데이터 발행 완료 - meetingId: {}", meetingId)
+            );
+    }
+
+    /**
+     * 실시간 AI 제안사항 생성 (Mock) - 간소화 버전
+     * 실제로는 STT 텍스트를 분석하여 AI가 제안사항을 생성
+     *
+     * @param meetingId 회의 ID
+     * @param sequence 시퀀스 번호
+     * @return RealtimeSuggestionsDto AI 제안사항
+     */
+    private RealtimeSuggestionsDto generateRealtimeSuggestions(String meetingId, Long sequence) {
+        // Mock 데이터 - 실제로는 LLM을 통해 STT 텍스트 분석 후 생성
+        List<SimpleSuggestionDto> suggestions = List.of(
+            SimpleSuggestionDto.builder()
+                    .id("sugg-" + sequence)
+                    .content(getMockSuggestionContent(sequence))
+                    .timestamp(getCurrentTimestamp())
+                    .confidence(0.85 + (sequence % 15) * 0.01)
+                    .build()
+        );
+
+        return RealtimeSuggestionsDto.builder()
+                .suggestions(suggestions)
+                .build();
+    }
+
+    /**
+     * Mock 제안사항 내용 생성
+     */
+    private String getMockSuggestionContent(Long sequence) {
+        String[] suggestions = {
+            "신제품의 타겟 고객층을 20-30대로 설정하고, 모바일 우선 전략을 취하기로 논의 중입니다.",
+            "개발 일정: 1차 프로토타입은 11월 15일까지 완성, 2차 베타는 12월 1일 론칭",
+            "마케팅 예산 배분에 대해 SNS 광고 60%, 인플루언서 마케팅 40%로 의견이 나왔으나 추가 검토 필요",
+            "보안 요구사항 검토가 필요하며, 데이터 암호화 방식에 대한 논의가 진행 중입니다.",
+            "React로 프론트엔드 개발하기로 결정되었으며, TypeScript 사용을 권장합니다.",
+            "데이터베이스는 PostgreSQL을 메인으로 사용하고, Redis를 캐시로 활용하기로 했습니다."
+        };
+        return suggestions[(int) (sequence % suggestions.length)];
+    }
+
+    /**
+     * 현재 타임스탬프 생성 (HH:MM:SS 형식)
+     */
+    private String getCurrentTimestamp() {
+        java.time.LocalTime now = java.time.LocalTime.now();
+        return String.format("%02d:%02d:%02d",
+            now.getHour(),
+            now.getMinute(),
+            now.getSecond());
+    }
 }

ai/src/main/java/com/unicorn/hgzero/ai/biz/usecase/SuggestionUseCase.java

@@ -1,6 +1,8 @@
 package com.unicorn.hgzero.ai.biz.usecase;
 
 import com.unicorn.hgzero.ai.biz.domain.Suggestion;
+import com.unicorn.hgzero.ai.infra.dto.common.RealtimeSuggestionsDto;
+import reactor.core.publisher.Flux;
 
 import java.util.List;
 
@@ -27,4 +29,13 @@ public interface SuggestionUseCase {
      * @return 결정사항 제안 목록
      */
     List<Suggestion> suggestDecisions(String meetingId, String transcriptText);
+
+    /**
+     * 실시간 AI 제안사항 스트리밍
+     * 회의 진행 중 실시간으로 논의사항과 결정사항을 분석하여 제안
+     *
+     * @param meetingId 회의 ID
+     * @return 실시간 제안사항 스트림
+     */
+    Flux<RealtimeSuggestionsDto> streamRealtimeSuggestions(String meetingId);
 }

ai/src/main/java/com/unicorn/hgzero/ai/infra/client/ClaudeApiClient.java

@@ -0,0 +1,173 @@
+package com.unicorn.hgzero.ai.infra.client;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.unicorn.hgzero.ai.infra.config.ClaudeConfig;
+import com.unicorn.hgzero.ai.infra.dto.common.RealtimeSuggestionsDto;
+import com.unicorn.hgzero.ai.infra.dto.common.SimpleSuggestionDto;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.MediaType;
+import org.springframework.stereotype.Component;
+import org.springframework.web.reactive.function.client.WebClient;
+import reactor.core.publisher.Mono;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.UUID;
+
+/**
+ * Claude API 클라이언트
+ * Anthropic Claude API를 호출하여 AI 제안사항 생성
+ */
+@Slf4j
+@Component
+@RequiredArgsConstructor
+public class ClaudeApiClient {
+
+    private final ClaudeConfig claudeConfig;
+    private final ObjectMapper objectMapper;
+    private final WebClient webClient;
+
+    /**
+     * 실시간 AI 제안사항 분석 (간소화 버전)
+     *
+     * @param transcriptText 누적된 회의록 텍스트
+     * @return AI 제안사항 (논의사항과 결정사항 통합)
+     */
+    public Mono<RealtimeSuggestionsDto> analyzeSuggestions(String transcriptText) {
+        log.debug("Claude API 호출 - 텍스트 길이: {}", transcriptText.length());
+
+        String systemPrompt = """
+            당신은 회의록 작성 전문 AI 어시스턴트입니다.
+
+            실시간 회의 텍스트를 분석하여 **제안사항을 적극적으로** 추출하세요.
+
+            **추출 대상 (MVP용 - 넓은 기준)**:
+            - 회의 안건 관련 내용
+            - 논의 중인 주제 (확정되지 않아도 OK)
+            - 의견이나 제안
+            - 결정된 사항
+            - 액션 아이템
+            - 계획이나 일정 관련 언급
+            - 검토가 필요한 내용
+
+            **제외할 내용** (최소화):
+            - 명백한 잡담이나 농담
+            - 회의 시작/종료 인사말
+
+            **응답 형식**: JSON만 반환 (다른 설명 없이)
+            {
+              "suggestions": [
+                {
+                  "content": "구체적인 제안 내용 (자연스러운 문장으로)",
+                  "confidence": 0.7
+                }
+              ]
+            }
+
+            **주의**:
+            - 확신이 없어도 제안사항으로 포함 (confidence 0.6 이상이면 OK)
+            - 회의 내용에서 의미 있는 내용은 모두 제안사항으로 추출
+            - confidence는 0-1 사이 값 (MVP에서는 낮아도 괜찮음)
+            """;
+
+        String userPrompt = String.format("""
+            다음 회의 내용을 분석해주세요:
+
+            %s
+            """, transcriptText);
+
+        // Claude API 요청 페이로드
+        Map<String, Object> requestBody = Map.of(
+            "model", claudeConfig.getModel(),
+            "max_tokens", claudeConfig.getMaxTokens(),
+            "temperature", claudeConfig.getTemperature(),
+            "system", systemPrompt,
+            "messages", List.of(
+                Map.of(
+                    "role", "user",
+                    "content", userPrompt
+                )
+            )
+        );
+
+        return webClient.post()
+            .uri(claudeConfig.getBaseUrl() + "/v1/messages")
+            .header(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
+            .header("x-api-key", claudeConfig.getApiKey())
+            .header("anthropic-version", "2023-06-01")
+            .bodyValue(requestBody)
+            .retrieve()
+            .bodyToMono(String.class)
+            .map(this::parseClaudeResponse)
+            .doOnSuccess(result -> log.info("Claude API 응답 성공 - 제안사항: {}개",
+                result.getSuggestions().size()))
+            .doOnError(error -> log.error("Claude API 호출 실패", error))
+            .onErrorResume(error -> Mono.just(RealtimeSuggestionsDto.builder()
+                .suggestions(new ArrayList<>())
+                .build()));
+    }
+
+    /**
+     * Claude API 응답 파싱 (간소화 버전)
+     */
+    private RealtimeSuggestionsDto parseClaudeResponse(String responseBody) {
+        try {
+            JsonNode root = objectMapper.readTree(responseBody);
+
+            // Claude 응답 구조: { "content": [ { "text": "..." } ] }
+            String contentText = root.path("content").get(0).path("text").asText();
+
+            // JSON 부분만 추출 (코드 블록 제거)
+            String jsonText = extractJson(contentText);
+
+            JsonNode suggestionsJson = objectMapper.readTree(jsonText);
+
+            // 제안사항 파싱
+            List<SimpleSuggestionDto> suggestions = new ArrayList<>();
+            JsonNode suggestionsNode = suggestionsJson.path("suggestions");
+            if (suggestionsNode.isArray()) {
+                for (JsonNode node : suggestionsNode) {
+                    suggestions.add(SimpleSuggestionDto.builder()
+                        .id(UUID.randomUUID().toString())
+                        .content(node.path("content").asText())
+                        .confidence(node.path("confidence").asDouble(0.8))
+                        .build());
+                }
+            }
+
+            return RealtimeSuggestionsDto.builder()
+                .suggestions(suggestions)
+                .build();
+
+        } catch (Exception e) {
+            log.error("Claude 응답 파싱 실패", e);
+            return RealtimeSuggestionsDto.builder()
+                .suggestions(new ArrayList<>())
+                .build();
+        }
+    }
+
+    /**
+     * 응답에서 JSON 부분만 추출
+     * Claude가 마크다운 코드 블록으로 감싼 경우 처리
+     */
+    private String extractJson(String text) {
+        // ```json ... ``` 형식 제거
+        if (text.contains("```json")) {
+            int start = text.indexOf("```json") + 7;
+            int end = text.lastIndexOf("```");
+            return text.substring(start, end).trim();
+        }
+        // ``` ... ``` 형식 제거
+        else if (text.contains("```")) {
+            int start = text.indexOf("```") + 3;
+            int end = text.lastIndexOf("```");
+            return text.substring(start, end).trim();
+        }
+        return text.trim();
+    }
+}

ai/src/main/java/com/unicorn/hgzero/ai/infra/config/ClaudeConfig.java

@@ -0,0 +1,28 @@
+package com.unicorn.hgzero.ai.infra.config;
+
+import lombok.Getter;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.annotation.Configuration;
+
+/**
+ * Claude API 설정
+ */
+@Configuration
+@Getter
+public class ClaudeConfig {
+
+    @Value("${external.ai.claude.api-key}")
+    private String apiKey;
+
+    @Value("${external.ai.claude.base-url}")
+    private String baseUrl;
+
+    @Value("${external.ai.claude.model}")
+    private String model;
+
+    @Value("${external.ai.claude.max-tokens}")
+    private Integer maxTokens;
+
+    @Value("${external.ai.claude.temperature}")
+    private Double temperature;
+}

ai/src/main/java/com/unicorn/hgzero/ai/infra/config/EventHubConfig.java

@@ -0,0 +1,131 @@
+package com.unicorn.hgzero.ai.infra.config;
+
+import com.azure.messaging.eventhubs.EventProcessorClient;
+import com.azure.messaging.eventhubs.EventProcessorClientBuilder;
+import com.azure.messaging.eventhubs.checkpointstore.blob.BlobCheckpointStore;
+import com.azure.messaging.eventhubs.models.ErrorContext;
+import com.azure.messaging.eventhubs.models.EventContext;
+import com.azure.storage.blob.BlobContainerAsyncClient;
+import com.azure.storage.blob.BlobContainerClientBuilder;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.unicorn.hgzero.ai.biz.service.SuggestionService;
+import com.unicorn.hgzero.ai.infra.event.TranscriptSegmentReadyEvent;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+import jakarta.annotation.PostConstruct;
+import jakarta.annotation.PreDestroy;
+
+/**
+ * Azure Event Hub 설정
+ * STT Service의 TranscriptSegmentReady 이벤트 구독
+ */
+@Slf4j
+@Configuration
+@RequiredArgsConstructor
+public class EventHubConfig {
+
+    private final SuggestionService suggestionService;
+    private final ObjectMapper objectMapper;
+
+    @Value("${external.eventhub.connection-string}")
+    private String connectionString;
+
+    @Value("${external.eventhub.eventhub-name}")
+    private String eventHubName;
+
+    @Value("${external.eventhub.consumer-group.transcript}")
+    private String consumerGroup;
+
+    @Value("${external.eventhub.checkpoint-storage-connection-string:}")
+    private String checkpointStorageConnectionString;
+
+    @Value("${external.eventhub.checkpoint-container}")
+    private String checkpointContainer;
+
+    private EventProcessorClient eventProcessorClient;
+
+    @PostConstruct
+    public void startEventProcessor() {
+        log.info("Event Hub Processor 시작 - eventhub: {}, consumerGroup: {}",
+            eventHubName, consumerGroup);
+
+        EventProcessorClientBuilder builder = new EventProcessorClientBuilder()
+            .connectionString(connectionString, eventHubName)
+            .consumerGroup(consumerGroup)
+            .processEvent(this::processEvent)
+            .processError(this::processError);
+
+        // Checkpoint Storage 설정
+        if (checkpointStorageConnectionString != null && !checkpointStorageConnectionString.isEmpty()) {
+            log.info("Checkpoint Storage 활성화 (Azure Blob) - container: {}", checkpointContainer);
+            BlobContainerAsyncClient blobContainerAsyncClient = new BlobContainerClientBuilder()
+                .connectionString(checkpointStorageConnectionString)
+                .containerName(checkpointContainer)
+                .buildAsyncClient();
+            builder.checkpointStore(new BlobCheckpointStore(blobContainerAsyncClient));
+        } else {
+            log.warn("⚠️ Checkpoint Storage 미설정 - 체크포인트 저장 안 함 (재시작 시 처음부터 읽음)");
+            log.warn("⚠️ 프로덕션 환경에서는 AZURE_BLOB_CONNECTION_STRING 설정 필요");
+            // Checkpoint Store 없이 실행 (재시작 시 처음부터 읽음)
+        }
+
+        eventProcessorClient = builder.buildEventProcessorClient();
+        eventProcessorClient.start();
+
+        log.info("Event Hub Processor 시작 완료");
+    }
+
+    @PreDestroy
+    public void stopEventProcessor() {
+        if (eventProcessorClient != null) {
+            log.info("Event Hub Processor 종료");
+            eventProcessorClient.stop();
+        }
+    }
+
+    /**
+     * 이벤트 처리 핸들러
+     */
+    private void processEvent(EventContext eventContext) {
+        try {
+            String eventData = eventContext.getEventData().getBodyAsString();
+            log.debug("이벤트 수신: {}", eventData);
+
+            // JSON 역직렬화
+            TranscriptSegmentReadyEvent event = objectMapper.readValue(
+                eventData,
+                TranscriptSegmentReadyEvent.class
+            );
+
+            log.info("실시간 텍스트 수신 - meetingId: {}, text: {}",
+                event.getMeetingId(), event.getText());
+
+            // SuggestionService로 전달하여 AI 분석 트리거
+            suggestionService.processRealtimeTranscript(
+                event.getMeetingId(),
+                event.getText(),
+                event.getTimestamp()
+            );
+
+            // 체크포인트 업데이트
+            eventContext.updateCheckpoint();
+
+        } catch (Exception e) {
+            log.error("이벤트 처리 실패", e);
+        }
+    }
+
+    /**
+     * 에러 처리 핸들러
+     */
+    private void processError(ErrorContext errorContext) {
+        log.error("Event Hub 에러 - partition: {}, error: {}",
+            errorContext.getPartitionContext().getPartitionId(),
+            errorContext.getThrowable().getMessage(),
+            errorContext.getThrowable());
+    }
+}

ai/src/main/java/com/unicorn/hgzero/ai/infra/config/SecurityConfig.java

@@ -1,8 +1,5 @@
 package com.unicorn.hgzero.ai.infra.config;
 
-import com.unicorn.hgzero.common.security.JwtTokenProvider;
-import com.unicorn.hgzero.common.security.filter.JwtAuthenticationFilter;
-import lombok.RequiredArgsConstructor;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
@@ -11,7 +8,6 @@ import org.springframework.security.config.annotation.web.configuration.EnableWe
 import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer;
 import org.springframework.security.config.http.SessionCreationPolicy;
 import org.springframework.security.web.SecurityFilterChain;
-import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;
 import org.springframework.web.cors.CorsConfiguration;
 import org.springframework.web.cors.CorsConfigurationSource;
 import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
@@ -20,15 +16,12 @@ import java.util.Arrays;
 
 /**
  * Spring Security 설정
- * JWT 기반 인증 및 API 보안 설정
+ * CORS 설정 및 API 보안 설정 (인증 없음)
  */
 @Configuration
 @EnableWebSecurity
-@RequiredArgsConstructor
 public class SecurityConfig {
 
-    private final JwtTokenProvider jwtTokenProvider;
-
     @Value("${cors.allowed-origins:http://localhost:3000,http://localhost:8080,http://localhost:8081,http://localhost:8082,http://localhost:8083,http://localhost:8084}")
     private String allowedOrigins;
 
@@ -39,17 +32,9 @@ public class SecurityConfig {
                 .cors(cors -> cors.configurationSource(corsConfigurationSource()))
                 .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
                 .authorizeHttpRequests(auth -> auth
-                        // Actuator endpoints
+                        // 모든 요청 허용 (인증 없음)
-                        .requestMatchers("/actuator/**").permitAll()
+                        .anyRequest().permitAll()
-                        // Swagger UI endpoints - context path와 상관없이 접근 가능하도록 설정
-                        .requestMatchers("/swagger-ui/**", "/swagger-ui.html", "/v3/api-docs/**", "/swagger-resources/**", "/webjars/**").permitAll()
-                        // Health check
-                        .requestMatchers("/health").permitAll()
-                        // All other requests require authentication
-                        .anyRequest().authenticated()
                 )
-                .addFilterBefore(new JwtAuthenticationFilter(jwtTokenProvider),
-                                UsernamePasswordAuthenticationFilter.class)
                 .build();
     }
 

ai/src/main/java/com/unicorn/hgzero/ai/infra/config/WebClientConfig.java

@@ -0,0 +1,22 @@
+package com.unicorn.hgzero.ai.infra.config;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.reactive.function.client.WebClient;
+
+/**
+ * WebClient 설정
+ * 외부 API 호출을 위한 WebClient 빈 생성
+ */
+@Configuration
+public class WebClientConfig {
+
+    @Bean
+    public WebClient webClient() {
+        return WebClient.builder()
+            .codecs(configurer -> configurer
+                .defaultCodecs()
+                .maxInMemorySize(10 * 1024 * 1024)) // 10MB
+            .build();
+    }
+}

ai/src/main/java/com/unicorn/hgzero/ai/infra/controller/RelationController.java

@@ -52,6 +52,7 @@ public class RelationController {
                                 .participants(r.getParticipants())
                                 .relevanceScore(r.getRelevanceScore())
                                 .commonKeywords(r.getCommonKeywords())
+                                .summary(r.getSummary())
                                 .link(r.getLink())
                                 .build())
                         .collect(Collectors.toList()))

ai/src/main/java/com/unicorn/hgzero/ai/infra/controller/SuggestionController.java

@@ -10,12 +10,16 @@ import com.unicorn.hgzero.ai.infra.dto.common.DiscussionSuggestionDto;
 import com.unicorn.hgzero.ai.infra.dto.common.DecisionSuggestionDto;
 import com.unicorn.hgzero.common.dto.ApiResponse;
 import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
+import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
+import org.springframework.http.codec.ServerSentEvent;
 import org.springframework.web.bind.annotation.*;
+import reactor.core.publisher.Flux;
 
 import java.time.LocalDateTime;
 import java.util.List;
@@ -96,4 +100,33 @@ public class SuggestionController {
 
         return ResponseEntity.ok(ApiResponse.success(response));
     }
+
+    /**
+     * 실시간 AI 제안사항 스트리밍 (SSE)
+     * 회의 진행 중 실시간으로 AI가 분석한 제안사항을 Server-Sent Events로 스트리밍
+     *
+     * @param meetingId 회의 ID
+     * @return Flux<ServerSentEvent<RealtimeSuggestionsDto>> AI 제안사항 스트림
+     */
+    @GetMapping(value = "/meetings/{meetingId}/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
+    @Operation(
+        summary = "실시간 AI 제안사항 스트리밍",
+        description = "회의 진행 중 실시간으로 AI가 분석한 제안사항을 Server-Sent Events(SSE)로 스트리밍합니다. " +
+                     "클라이언트는 EventSource API를 사용하여 연결할 수 있습니다."
+    )
+    public Flux<ServerSentEvent<com.unicorn.hgzero.ai.infra.dto.common.RealtimeSuggestionsDto>> streamRealtimeSuggestions(
+            @Parameter(description = "회의 ID", required = true, example = "550e8400-e29b-41d4-a716-446655440000")
+            @PathVariable String meetingId) {
+
+        log.info("실시간 AI 제안사항 스트리밍 요청 - meetingId: {}", meetingId);
+
+        return suggestionUseCase.streamRealtimeSuggestions(meetingId)
+                .map(suggestions -> ServerSentEvent.<com.unicorn.hgzero.ai.infra.dto.common.RealtimeSuggestionsDto>builder()
+                        .id(suggestions.hashCode() + "")
+                        .event("ai-suggestion")
+                        .data(suggestions)
+                        .build())
+                .doOnComplete(() -> log.info("AI 제안사항 스트리밍 완료 - meetingId: {}", meetingId))
+                .doOnError(error -> log.error("AI 제안사항 스트리밍 오류 - meetingId: {}", meetingId, error));
+    }
 }

ai/src/main/java/com/unicorn/hgzero/ai/infra/controller/TermController.java

@@ -55,6 +55,9 @@ public class TermController {
                                 .build() : null)
                         .confidence(t.getConfidence())
                         .category(t.getCategory())
+                        .definition(t.getDefinition())
+                        .context(t.getContext())
+                        .relatedMeetingId(t.getRelatedMeetingId())
                         .highlight(t.getHighlight())
                         .build())
                 .collect(Collectors.toList());

ai/src/main/java/com/unicorn/hgzero/ai/infra/dto/common/DetectedTermDto.java

@@ -31,10 +31,26 @@ public class DetectedTermDto {
     private Double confidence;
 
     /**
-     * 용어 카테고리 (기술, 업무, 도메인)
+     * 용어 카테고리 (기술, 업무, 도메인, 기획, 비즈니스, 전략, 마케팅)
      */
     private String category;
 
+    /**
+     * 용어 정의 (간단한 설명)
+     */
+    private String definition;
+
+    /**
+     * 용어가 사용된 맥락 (과거 회의록 참조)
+     * 예: "신제품 기획 회의(2024-09-15)에서 언급"
+     */
+    private String context;
+
+    /**
+     * 관련 회의 ID (용어가 논의된 과거 회의)
+     */
+    private String relatedMeetingId;
+
     /**
      * 하이라이트 여부
      */

ai/src/main/java/com/unicorn/hgzero/ai/infra/dto/common/RealtimeSuggestionsDto.java

@@ -8,8 +8,8 @@ import lombok.NoArgsConstructor;
 import java.util.List;
 
 /**
- * 실시간 추천사항 DTO
+ * 실시간 추천사항 DTO (간소화 버전)
- * 논의 주제와 결정사항 제안을 포함
+ * 논의사항과 결정사항을 구분하지 않고 통합 제공
  */
 @Getter
 @Builder
@@ -18,12 +18,7 @@ import java.util.List;
 public class RealtimeSuggestionsDto {
 
     /**
-     * 논의 주제 제안 목록
+     * AI 제안사항 목록 (논의사항 + 결정사항 통합)
      */
-    private List<DiscussionSuggestionDto> discussionTopics;
+    private List<SimpleSuggestionDto> suggestions;
-
-    /**
-     * 결정사항 제안 목록
-     */
-    private List<DecisionSuggestionDto> decisions;
 }

ai/src/main/java/com/unicorn/hgzero/ai/infra/dto/common/RelatedTranscriptDto.java

@@ -48,6 +48,11 @@ public class RelatedTranscriptDto {
      */
     private List<String> commonKeywords;
 
+    /**
+     * 회의록 핵심 내용 요약 (1-2문장)
+     */
+    private String summary;
+
     /**
      * 회의록 링크
      */

ai/src/main/java/com/unicorn/hgzero/ai/infra/dto/common/SimpleSuggestionDto.java

@@ -0,0 +1,37 @@
+package com.unicorn.hgzero.ai.infra.dto.common;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+/**
+ * 간소화된 AI 제안사항 DTO
+ * 논의사항과 결정사항을 구분하지 않고 통합 제공
+ */
+@Getter
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class SimpleSuggestionDto {
+
+    /**
+     * 제안 ID
+     */
+    private String id;
+
+    /**
+     * 제안 내용 (논의사항 또는 결정사항)
+     */
+    private String content;
+
+    /**
+     * 타임스탬프 (초 단위, 예: 00:05:23)
+     */
+    private String timestamp;
+
+    /**
+     * 신뢰도 점수 (0-1)
+     */
+    private Double confidence;
+}

ai/src/main/java/com/unicorn/hgzero/ai/infra/event/TranscriptSegmentReadyEvent.java

@@ -0,0 +1,52 @@
+package com.unicorn.hgzero.ai.infra.event;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+/**
+ * STT Service에서 발행하는 음성 변환 세그먼트 이벤트
+ * Azure Event Hub를 통해 전달됨
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class TranscriptSegmentReadyEvent {
+
+    /**
+     * 녹음 ID
+     */
+    private String recordingId;
+
+    /**
+     * 회의 ID
+     */
+    private String meetingId;
+
+    /**
+     * 변환 텍스트 세그먼트 ID
+     */
+    private String transcriptId;
+
+    /**
+     * 변환된 텍스트
+     */
+    private String text;
+
+    /**
+     * 타임스탬프 (ms)
+     */
+    private Long timestamp;
+
+    /**
+     * 신뢰도 점수 (0-1)
+     */
+    private Double confidence;
+
+    /**
+     * 이벤트 발생 시간
+     */
+    private String eventTime;
+}

ai/src/main/resources/application.yml

@@ -77,6 +77,9 @@ external:
     claude:
       api-key: ${CLAUDE_API_KEY:}
       base-url: ${CLAUDE_BASE_URL:https://api.anthropic.com}
+      model: ${CLAUDE_MODEL:claude-3-5-sonnet-20241022}
+      max-tokens: ${CLAUDE_MAX_TOKENS:2000}
+      temperature: ${CLAUDE_TEMPERATURE:0.3}
     openai:
       api-key: ${OPENAI_API_KEY:}
       base-url: ${OPENAI_BASE_URL:https://api.openai.com}
@@ -150,3 +153,6 @@ logging:
       max-file-size: ${LOG_MAX_FILE_SIZE:10MB}
       max-history: ${LOG_MAX_HISTORY:7}
       total-size-cap: ${LOG_TOTAL_SIZE_CAP:100MB}
+
+
+

build.gradle

@@ -44,7 +44,7 @@ subprojects {
         hypersistenceVersion = '3.7.3'
         openaiVersion = '0.18.2'
         feignJacksonVersion = '13.1'
-        azureSpeechVersion = '1.37.0'
+        azureSpeechVersion = '1.44.0'
         azureBlobVersion = '12.25.3'
         azureEventHubsVersion = '5.18.2'
         azureEventHubsCheckpointVersion = '1.19.2'

claude/api-design.md

@@ -1,115 +1,111 @@
-# STT Service API 설계 완료
+# API설계가이드
 
-## 작업 결과
+[요청사항]  
+- <작성원칙>을 준용하여 설계
+- <작성순서>에 따라 설계
+- [결과파일] 안내에 따라 파일 작성 
+- 최종 완료 후 API 확인 방법 안내 
+  - https://editor.swagger.io/ 접근  
+  - 생성된 swagger yaml파일을 붙여서 확인 및 테스트  
 
-### 생성된 파일
+[가이드]  
-- **파일 경로**: `C:\Users\KTDS\home\workspace\HGZero\design\backend\api\stt-service-api.yaml`
+<작성 원칙>
-- **형식**: OpenAPI 3.0.3
+- 각 서비스 API는 독립적으로 완전한 명세를 포함
-- **검증 상태**: ✅ 검증 완료 (swagger-cli)
+- 공통 스키마는 각 서비스에서 필요에 따라 직접 정의
+- 서비스 간 의존성을 최소화하여 독립 배포 가능
+- 중복되는 스키마가 많아질 경우에만 공통 파일 도입 검토
+<작성순서>
+- 준비: 
+  - 유저스토리, 외부시퀀스설계서, 내부시퀀스설계서 분석 및 이해 
+- 실행:
+  - <병렬처리> 안내에 따라 동시 수행
+  - <API선정원칙>에 따라 API 선정 
+  - <파일작성안내>에 따라 작성  
+  - <검증방법>에 따라 작성된 YAML의 문법 및 구조 검증 수행
+- 검토:
+  - <작성원칙> 준수 검토
+  - 스쿼드 팀원 리뷰: 누락 및 개선 사항 검토
+  - 수정 사항 선택 및 반영 
 
-### API 개요
+<API선정원칙>
+- 유저스토리와 매칭 되어야 함. 불필요한 추가 설계 금지  
+  (유저스토리 ID를 x-user-story 확장 필드에 명시)
+- '외부시퀀스설계서'/'내부시퀀스설계서'와 일관성 있게 선정 
 
-#### 1. Recording API (음성 녹음 관리)
+<파일작성안내>
-- `POST /recordings/prepare` - 회의 녹음 준비
+- OpenAPI 3.0 스펙 준용 
-- `POST /recordings/{recordingId}/start` - 음성 녹음 시작
+- **servers 섹션 필수화**
-- `POST /recordings/{recordingId}/stop` - 음성 녹음 중지
+  - 모든 OpenAPI 명세에 servers 섹션 포함
-- `GET /recordings/{recordingId}` - 녹음 정보 조회
+  - SwaggerHub Mock URL을 첫 번째 옵션으로 배치
+- **example 데이터 권장**
+  - 스키마에 example을 추가하여 Swagger UI에서 테스트 할 수 있게함 
+- **테스트 시나리오 포함**
+  - 각 API 엔드포인트별 테스트 케이스 정의
+  - 성공/실패 케이스 모두 포함
+- 작성 형식
+  - YAML 형식의 OpenAPI 3.0 명세
+  - 각 API별 필수 항목:
+    - summary: API 목적 설명
+    - operationId: 고유 식별자
+    - x-user-story: 유저스토리 ID
+    - x-controller: 담당 컨트롤러
+    - tags: API 그룹 분류
+    - requestBody/responses: 상세 스키마
+  - 각 서비스 파일에 필요한 모든 스키마 포함:
+    - components/schemas: 요청/응답 모델
+    - components/parameters: 공통 파라미터
+    - components/responses: 공통 응답
+    - components/securitySchemes: 인증 방식
 
-#### 2. Transcription API (음성-텍스트 변환)
+<파일 구조>
-- `POST /transcripts/stream` - 실시간 음성-텍스트 변환 (스트리밍)
+```
-- `POST /transcripts/batch` - 배치 음성-텍스트 변환
+design/backend/api/
-- `POST /transcripts/callback` - 배치 변환 완료 콜백
+├── {service-name}-api.yaml      # 각 마이크로서비스별 API 명세
-- `GET /transcripts/{recordingId}` - 변환 텍스트 전체 조회
+└── ...                          # 추가 서비스들
 
-#### 3. Speaker API (화자 식별 및 관리)
+예시:
-- `POST /speakers/identify` - 화자 식별
+├── profile-service-api.yaml     # 프로파일 서비스 API
-- `GET /speakers/{speakerId}` - 화자 정보 조회
+├── order-service-api.yaml       # 주문 서비스 API
-- `PUT /speakers/{speakerId}` - 화자 정보 업데이트
+└── payment-service-api.yaml     # 결제 서비스 API
-- `GET /recordings/{recordingId}/speakers` - 녹음의 화자 목록 조회
-
-### 주요 특징
-
-#### 1. 유저스토리 매핑
-모든 API는 유저스토리와 매핑되어 있습니다:
-- **UFR-STT-010** (음성녹음인식): Recording API, Speaker API
-- **UFR-STT-020** (텍스트변환): Transcription API
-
-#### 2. 완전한 스키마 정의
-- 25개의 스키마 정의
-- 모든 Request/Response 모델 포함
-- Example 데이터 포함으로 Swagger UI에서 즉시 테스트 가능
-
-#### 3. Azure 통합
-- Azure Speech Service 연동
-- Azure Blob Storage 통합
-- Azure Event Hubs 이벤트 발행
-
-#### 4. 실시간 처리
-- WebSocket 기반 스트리밍 지원
-- 실시간 인식 지연: < 1초
-- 화자 식별 정확도: > 90%
-
-#### 5. 성능 정보
-각 API의 예상 처리 시간 명시:
-- 녹음 준비: ~1.1초
-- 실시간 변환: 1-4초
-- 배치 변환: 7-33초
-
-### API 확인 방법
-
-#### 1. Swagger Editor 사용
-1. https://editor.swagger.io/ 접속
-2. 생성된 YAML 파일 내용 복사하여 붙여넣기
-3. 우측 패널에서 API 문서 확인 및 테스트
-
-#### 2. 로컬 Swagger UI 실행
-```bash
-# Swagger UI Docker 실행
-docker run -p 8080:8080 -e SWAGGER_JSON=/api/stt-service-api.yaml \
-  -v C:\Users\KTDS\home\workspace\HGZero\design\backend\api:/api \
-  swaggerapi/swagger-ui
-
-# 브라우저에서 http://localhost:8080 접속
 ```
 
-#### 3. VS Code Extension
+- 파일명 규칙
-- **확장**: Swagger Viewer
+  - 서비스명은 kebab-case로 작성
-- YAML 파일 열고 `Shift + Alt + P` 실행
+  - 파일명 형식: {service-name}-api.yaml
-- 미리보기에서 API 문서 확인
+  - 서비스명은 유저스토리의 '서비스' 항목을 영문으로 변환하여 사용
 
-### 설계 원칙 준수
+<병렬처리>
+- **의존성 분석 선행**: 병렬 처리 전 반드시 의존성 파악
+- **순차 처리 필요시**: 무리한 병렬화보다는 안전한 순차 처리
+- **검증 단계 필수**: 병렬 처리 후 통합 검증
 
-✅ **유저스토리 기반 설계**
+<검증방법>
-- 모든 API에 x-user-story 필드 명시
+- swagger-cli를 사용한 자동 검증 수행
-- 불필요한 API 추가 없음
+- 검증 명령어: `swagger-cli validate {파일명}`
+- swagger-cli가 없을 경우 자동 설치:
+  ```bash
+  # swagger-cli 설치 확인 및 자동 설치
+  command -v swagger-cli >/dev/null 2>&1 || npm install -g @apidevtools/swagger-cli
+  
+  # 검증 실행
+  swagger-cli validate design/backend/api/*.yaml
+  ```
+- 검증 항목:
+  - OpenAPI 3.0 스펙 준수
+  - YAML 구문 오류
+  - 스키마 참조 유효성
+  - 필수 필드 존재 여부
 
-✅ **시퀀스 일관성**
+[참고자료]
-- 내부 시퀀스 설계와 완전히 일치
+- 유저스토리
-- 모든 처리 흐름 반영
+- 외부시퀀스설계서
+- 내부시퀀스설계서
+- OpenAPI 스펙: https://swagger.io/specification/
 
-✅ **OpenAPI 3.0 표준**
+[예시]
-- servers 섹션 필수 포함
+- swagger api yaml: https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/samples/sample-swagger-api.yaml
-- 완전한 스키마 정의
+- API설계서: https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/samples/sample-API%20설계서.md
-- JWT 인증 방식 명시
 
-✅ **Example 데이터**
+[결과파일]
-- 모든 스키마에 example 포함
+- 각 서비스별로 별도의 YAML 파일 생성 
-- 실제 테스트 가능한 데이터
+- design/backend/api/*.yaml (OpenAPI 형식)
-
-✅ **검증 완료**
-- swagger-cli 자동 검증 통과
-- YAML 구문 오류 없음
-- 스키마 참조 유효성 확인
-
-### 다음 단계
-
-1. **Meeting Service API 설계** (회의, 회의록, Todo 통합)
-2. **AI Service API 설계** (회의록 자동 작성, RAG 기능)
-3. **User Service API 설계** (인증 전용)
-4. **Notification Service API 설계** (알림 발송)
-
----
-
-**작성자**: 준호 (Backend Developer)
-**작성일**: 2025-01-23
-**검증 도구**: swagger-cli v4.0.4

claudedocs/API-누락-요약표.md

@@ -1,95 +0,0 @@
-# API 누락 요약표 (회의 진행 실시간 기능)
-
-**작성일**: 2025년 10월 28일
-**근거 문서**: [API리뷰-프로토타입vs구현.md](./API리뷰-프로토타입vs구현.md)
-
----
-
-## 🔴 P0 (치명적 - 즉시 구현 필요)
-
-| # | API | 프로토타입 근거 | 영향받는 유저스토리 | 비고 |
-|---|-----|----------------|-------------------|------|
-| 1 | `PUT /api/meetings/{meetingId}/memo` | [05-회의진행.html:1119-1143](../design/uiux/prototype/05-회의진행.html#L1119-L1143) | US-07, US-10 | 메모 저장 불가, 데이터 손실 위험 |
-| 2 | `GET /api/ai/suggestions/realtime/{meetingId}` | [05-회의진행.html:767-806](../design/uiux/prototype/05-회의진행.html#L767-L806) | US-07, US-08 | AI 실시간 추천 완전 미동작 |
-| 3 | `POST /api/stt/recordings/{recordingId}/pause` | [05-회의진행.html:1212-1243](../design/uiux/prototype/05-회의진행.html#L1212-L1243) | US-06 | 녹음 일시정지 불가 |
-| 4 | `POST /api/stt/recordings/{recordingId}/resume` | [05-회의진행.html:1212-1243](../design/uiux/prototype/05-회의진행.html#L1212-L1243) | US-06 | 녹음 재개 불가 |
-
----
-
-## 🟡 P1 (중요 - 우선 구현 필요)
-
-| # | API | 프로토타입 근거 | 영향받는 유저스토리 | 비고 |
-|---|-----|----------------|-------------------|------|
-| 5 | `POST /api/ai/suggestions/{suggestionId}/adopt` | [05-회의진행.html:1070-1097](../design/uiux/prototype/05-회의진행.html#L1070-L1097) | US-07 | AI 추천 채택 불가, 수동 복붙 필요 |
-| 6 | `GET /api/ai/terms/search` | [05-회의진행.html:1145-1182](../design/uiux/prototype/05-회의진행.html#L1145-L1182) | US-09 | 용어 검색 불가 |
-
----
-
-## 🟢 P2 (일반 - 향후 개선)
-
-| # | API | 프로토타입 근거 | 영향받는 유저스토리 | 비고 |
-|---|-----|----------------|-------------------|------|
-| 7 | `GET /api/ai/terms/{termName}/detail` | [05-회의진행.html:1305-1308](../design/uiux/prototype/05-회의진행.html#L1305-L1308) | US-09 | 용어 상세 조회 불가 |
-
----
-
-## 📊 탭별 API 구현 현황
-
-| 탭 | 기능 | 필요 API 수 | 구현 API 수 | 구현률 | 우선순위 |
-|----|------|------------|------------|--------|---------|
-| **참석자** | 참석자 관리 | 4 | 4 | 100% ✅ | - |
-| **AI 메모** | 실시간 메모 & AI 추천 | 3 | 0 | 0% ❌ | P0 (3개) |
-| **용어사전** | 용어 감지/검색 | 3 | 1 | 33% ⚠️ | P1 (1개), P2 (1개) |
-| **관련회의록** | 유사 회의록 찾기 | 2 | 2 | 100% ✅ | - |
-| **녹음 제어** | 녹음 상태 관리 | 5 | 3 | 60% ⚠️ | P0 (2개) |
-
----
-
-## 🎯 구현 권장 순서
-
-### Sprint 1 (1주) - P0 필수 기능
-1. **메모 저장 API** (`PUT /api/meetings/{meetingId}/memo`)
-   - 예상 작업: 4시간
-   - 구현 위치: `MeetingController.java`
-
-2. **AI 실시간 추천 API** (`GET /api/ai/suggestions/realtime/{meetingId}`)
-   - 예상 작업: 8시간
-   - 구현 위치: `SuggestionController.java`
-   - 폴링 또는 SSE 방식 선택 필요
-
-3. **녹음 일시정지/재개 API** (`POST pause`, `POST resume`)
-   - 예상 작업: 6시간
-   - 구현 위치: `RecordingController.java`
-
-### Sprint 2 (3일) - P1 중요 기능
-4. **AI 추천 채택 API** (`POST /api/ai/suggestions/{suggestionId}/adopt`)
-   - 예상 작업: 4시간
-
-5. **용어 검색 API** (`GET /api/ai/terms/search`)
-   - 예상 작업: 3시간
-
-### Sprint 3 (2일) - P2 보조 기능
-6. **용어 상세 조회 API** (`GET /api/ai/terms/{termName}/detail`)
-   - 예상 작업: 4시간
-
----
-
-## 📝 비고
-
-### 구현 고려사항
-1. **AI 실시간 추천**: 폴링(Polling) vs SSE(Server-Sent Events) 방식 결정 필요
-2. **메모 저장**: 개인별 메모 vs 공유 메모 정책 확인 필요
-3. **녹음 일시정지**: 타이머 상태 동기화 로직 필요
-4. **용어 검색**: 조직 용어 사전과 회의별 용어 통합 검색 정책 필요
-
-### 테스트 시나리오
-- [ ] 회의 진행 중 메모 작성 후 저장 → 다시 로드 시 메모 복원 확인
-- [ ] AI 추천 메모 실시간 조회 → 5초마다 새 추천 확인
-- [ ] AI 추천 채택 → 입력창에 시간 포함하여 추가 확인
-- [ ] 용어 검색 → 키워드로 조직/회의 용어 찾기 확인
-- [ ] 녹음 일시정지 → 타이머 정지 확인
-- [ ] 녹음 재개 → 타이머 재개 확인
-
----
-
-**문서 종료**

claudedocs/API리뷰-프로토타입vs구현.md

@@ -1,832 +0,0 @@
-# API 리뷰 분석 - 프로토타입 vs 구현
-
-**작성일**: 2025-10-28
-**검토자**: Architect, Backend Developer, Frontend Developer
-**분석 방법**: 프로토타입 HTML 파일과 실제 구현된 Controller 소스코드 비교 분석
-
----
-
-## 📋 요약
-
-### 전체 현황 (v2.0 - 회의 진행 실시간 기능 추가 분석)
-- **분석된 화면**: 9개 프로토타입 화면
-- **프로토타입 요구 API**: **34개** (v1: 27개 → v2: +7개)
-- **구현된 API**: 27개 엔드포인트
-- **완전 누락 API**: **11개** (v1: 4개 → v2: +7개)
-- **개선 필요 API**: 2개
-- **불필요한 API**: 0개
-
-### 주요 발견사항 (v2.0 업데이트)
-1. ✅ **강점**: 핵심 비즈니스 로직 API는 모두 구현됨
-2. 🔴 **치명적 누락 (기존)**:
-   - `GET /api/meetings` (목록 조회) - 대시보드 "최근 회의" 표시 불가
-   - `PUT/PATCH /api/meetings/{meetingId}` (회의 수정) - 예정된 회의 수정 불가
-   - `GET /api/dashboard/statistics` - 대시보드 통계 카드 표시 불가
-3. 🔴 **치명적 누락 (신규 발견)**: **회의 진행 중 실시간 기능 API 7개 누락**
-   - **탭2: AI 메모 (3개 누락)**
-     - `PUT /api/meetings/{meetingId}/memo` - 회의 중 메모 저장
-     - `GET /api/ai/suggestions/realtime/{meetingId}` - AI 실시간 추천 메모
-     - `POST /api/ai/suggestions/{suggestionId}/adopt` - AI 추천 채택
-   - **탭3: 용어사전 (2개 누락)**
-     - `GET /api/ai/terms/search` - 용어 검색
-     - `GET /api/ai/terms/{termName}/detail` - 용어 상세 조회
-   - **녹음 제어 (2개 누락)**
-     - `POST /api/stt/recordings/{recordingId}/pause` - 녹음 일시정지
-     - `POST /api/stt/recordings/{recordingId}/resume` - 녹음 재개
-4. 🟡 **기능 누락**: AI 요약 재생성 API 미구현
-5. 🟡 **개선 필요**: 회의록 검색/필터링 파라미터 추가 필요
-
-### 비즈니스 영향도
-- **사용자 경험**: 회의 진행 중 핵심 편의 기능 미동작으로 인한 UX 저하
-- **AI 활용도**: 실시간 AI 추천 기능이 동작하지 않아 서비스 차별화 가치 감소
-- **메모 손실 위험**: 회의 중 작성한 메모가 저장되지 않아 데이터 손실 가능성
-- **유저스토리 영향**: US-06, US-07, US-08, US-09, US-10의 핵심/보조 기능 미동작
-
----
-
-## 🔍 화면별 상세 분석
-
-### 1. 로그인 화면 (01-로그인.html)
-
-| 화면 기능 | 요구 API | 구현 상태 | 구현 위치 | 비고 |
-|---------|---------|----------|----------|------|
-| 로그인 | `POST /api/auth/login` | ✅ 구현됨 | [UserController.java:37-50](user/src/main/java/com/unicorn/hgzero/user/controller/UserController.java#L37-L50) | LDAP 인증, JWT 토큰 발급 |
-| 토큰 갱신 | `POST /api/auth/refresh` | ✅ 구현됨 | [UserController.java:59-72](user/src/main/java/com/unicorn/hgzero/user/controller/UserController.java#L59-L72) | Refresh Token 사용 |
-| 로그아웃 | `POST /api/auth/logout` | ✅ 구현됨 | [UserController.java:82-96](user/src/main/java/com/unicorn/hgzero/user/controller/UserController.java#L82-L96) | Refresh Token 삭제 |
-| 토큰 검증 | `GET /api/auth/validate` | ✅ 구현됨 | [UserController.java:105-126](user/src/main/java/com/unicorn/hgzero/user/controller/UserController.java#L105-L126) | JWT 토큰 유효성 검증 |
-
-**분석 결과**: ✅ **완벽 구현** - 모든 인증 관련 API가 구현되어 있으며, 보안 모범 사례를 따르고 있음
-
----
-
-### 2. 대시보드 화면 (02-대시보드.html)
-
-| 화면 기능 | 요구 API | 구현 상태 | 구현 위치 | 비고 |
-|---------|---------|----------|----------|------|
-| 최근 회의 목록 (3개) | `GET /api/meetings` | ❌ **누락** | - | **전체 회의 목록 조회 후 프론트에서 정렬** |
-| 최근 회의록 목록 (4개) | `GET /api/meetings/minutes` | ✅ 구현됨 | [MinutesController.java:210-268](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L210-L268) | 페이징, 필터링 지원 |
-| 통계 정보 (2개 카드) | `GET /api/dashboard/statistics` | ❌ **누락** | - | 예정된 회의, 작성중 회의록 수 |
-
-**상세 분석**:
-
-#### "최근 회의" 섹션 요구사항 ([02-대시보드.html:665-681](design/uiux/prototype/02-대시보드.html#L665-L681))
-프로토타입 JavaScript 로직:
-```javascript
-// 회의록 미생성(scheduled, ongoing) 먼저, 빠른 일시 순 정렬
-const meetings = [...SAMPLE_MEETINGS]
-  .sort((a, b) => {
-    // 회의록 미생성 회의 우선
-    const aNoMinutes = a.status === 'scheduled' || a.status === 'ongoing';
-    const bNoMinutes = b.status === 'scheduled' || b.status === 'ongoing';
-
-    if (aNoMinutes && !bNoMinutes) return -1;
-    if (!aNoMinutes && bNoMinutes) return 1;
-
-    // 동일 그룹 내에서는 빠른 일시 순 (오름차순)
-    return new Date(a.date + ' ' + a.time) - new Date(b.date + ' ' + b.time);
-  })
-  .slice(0, 3); // 상위 3개만 표시
-```
-
-**요구사항 해석**:
-1. **전체 회의 목록**을 가져와야 함 (상태 무관)
-2. **회의록 생성 여부 정보** 포함 필요 (scheduled, ongoing, draft, complete)
-3. 프론트엔드에서 다음 우선순위로 정렬:
-   - 1순위: 회의록 미생성 회의 (`scheduled`, `ongoing`)
-   - 2순위: 빠른 일시 순
-4. 상위 3개만 표시
-
-**현재 구현 상태**:
-- ❌ `GET /api/meetings` (목록 조회) - **완전 누락**
-- ✅ `GET /api/meetings/{meetingId}` (단건 조회) - 구현됨
-
-**분석 결과**: ⚠️ **부분 구현** (33%)
-- **누락 API (2개)**:
-  1. `GET /api/meetings` - 회의 목록 조회 (전체 상태, 날짜/시간 정렬 필요)
-  2. `GET /api/dashboard/statistics` - 통계 정보 (예정된 회의, 작성중 회의록)
-
-**권장사항**:
-```java
-// MeetingController에 추가 필요
-@GetMapping
-@Operation(summary = "회의 목록 조회", description = "사용자의 회의 목록을 조회합니다")
-public ResponseEntity<ApiResponse<MeetingListResponse>> getMeetingList(
-    @RequestHeader("X-User-Id") String userId,
-    @RequestParam(required = false) String status,  // all(기본값), scheduled, ongoing, draft, complete
-    @RequestParam(required = false) LocalDateTime startDate,
-    @RequestParam(required = false) LocalDateTime endDate,
-    @RequestParam(defaultValue = "0") int page,
-    @RequestParam(defaultValue = "10") int size,
-    @RequestParam(defaultValue = "startTime") String sortBy,
-    @RequestParam(defaultValue = "asc") String sortDir
-) {
-    // 사용자가 참여한 모든 회의 조회
-    // 응답에 회의록 생성 여부(hasMinutes), 회의록 상태(minutesStatus) 포함 필수
-}
-
-// 새로운 DashboardController 생성 권장
-@GetMapping("/api/dashboard/statistics")
-public ResponseEntity<ApiResponse<DashboardStatistics>> getStatistics(
-    @RequestHeader("X-User-Id") String userId
-)
-```
-
----
-
-### 3. 회의 예약/수정 화면 (03-회의예약.html)
-
-| 화면 기능 | 요구 API | 구현 상태 | 구현 위치 | 비고 |
-|---------|---------|----------|----------|------|
-| 회의 생성 | `POST /api/meetings` | ✅ 구현됨 | [MeetingController.java:60-93](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L60-L93) | 참석자 초대 포함 |
-| 회의 정보 수정 | `PUT /api/meetings/{meetingId}` 또는 `PATCH /api/meetings/{meetingId}` | ❌ **누락** | - | **예정된 회의 수정 불가** |
-
-**상세 분석**:
-
-#### 회의 수정 요구사항 ([02-대시보드.html:724](design/uiux/prototype/02-대시보드.html#L724))
-프로토타입 JavaScript 로직:
-```javascript
-// 상태에 따른 이동 처리
-if (meetingStatus === 'ongoing') {
-  navigateTo('05-회의진행.html');
-} else if (meetingStatus === 'draft' || meetingStatus === 'complete' || meetingStatus === 'completed') {
-  navigateTo('10-회의록상세조회.html');
-} else if (meetingStatus === 'scheduled') {
-  navigateTo('03-회의예약.html');  // 예정된 회의 → 회의예약 화면 (수정 모드)
-}
-```
-
-**요구사항 해석**:
-1. 대시보드에서 **예정된 회의(scheduled) 카드 클릭**
-2. 회의예약 화면(03-회의예약.html)으로 이동
-3. 기존 회의 정보를 **로드하여 수정 가능**해야 함
-4. 수정 완료 시 `PUT` 또는 `PATCH` 요청 필요
-
-**현재 상태**:
-- ❌ API 설계서([meeting-service-api.yaml](design/backend/api/meeting-service-api.yaml)) - **회의 수정 API 명세 없음**
-- ❌ MeetingController - **회의 수정 API 구현 없음**
-- ✅ `POST /api/meetings` (생성) - 구현됨
-- ✅ `GET /api/meetings/{meetingId}` (단건 조회) - 구현됨
-- ❌ `PUT/PATCH /api/meetings/{meetingId}` (수정) - **완전 누락**
-
-**분석 결과**: ⚠️ **치명적 누락** (50%)
-- 회의 생성은 가능하지만, **예약된 회의 수정 불가**
-- 사용자가 대시보드에서 예정된 회의를 클릭해도 수정할 수 없음
-
-**권장사항**:
-```java
-// MeetingController에 추가 필요
-@PutMapping("/{meetingId}")
-@Operation(summary = "회의 정보 수정", description = "예정된 회의의 정보를 수정합니다")
-public ResponseEntity<ApiResponse<MeetingResponse>> updateMeeting(
-    @PathVariable String meetingId,
-    @RequestHeader("X-User-Id") String userId,
-    @RequestHeader("X-User-Name") String userName,
-    @RequestHeader("X-User-Email") String userEmail,
-    @Valid @RequestBody UpdateMeetingRequest request
-) {
-    // 회의 정보 수정 로직
-    // - 제목, 날짜, 시간, 장소, 안건 수정 가능
-    // - 참석자 추가/제거 가능
-    // - 회의 상태가 'scheduled'일 때만 수정 가능
-    // - 변경 사항 참석자에게 알림
-}
-```
-
-**UpdateMeetingRequest DTO**:
-```java
-public class UpdateMeetingRequest {
-    private String title;           // 회의 제목
-    private LocalDateTime startTime; // 시작 시간
-    private LocalDateTime endTime;   // 종료 시간
-    private String location;         // 장소
-    private String agenda;           // 안건
-    private List<String> participants; // 참석자 이메일 목록
-}
-```
-
----
-
-### 4. 템플릿 선택 화면 (04-템플릿선택.html)
-
-| 화면 기능 | 요구 API | 구현 상태 | 구현 위치 | 비고 |
-|---------|---------|----------|----------|------|
-| 템플릿 목록 조회 | `GET /api/meetings/templates` | ✅ 구현됨 | [TemplateController.java:33-63](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/TemplateController.java#L33-L63) | 4가지 고정 템플릿 제공 |
-| 템플릿 적용 | `PUT /api/meetings/{meetingId}/template` | ✅ 구현됨 | [MeetingController.java:108-135](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L108-L135) | 템플릿 ID로 적용 |
-
-**분석 결과**: ✅ **완벽 구현** - 템플릿 관리 기능 완전 구현
-
----
-
-### 5. 회의 진행 화면 (05-회의진행.html) ⚠️ **중요 업데이트**
-
-#### 화면 구조 분석
-프로토타입은 4개 탭으로 구성되어 있으며, 각 탭마다 실시간 기능이 요구됩니다:
-
-```
-┌─────────────────────────────────────────┐
-│ 📍 헤더: 회의 제목 + 녹음 상태          │
-├─────────────────────────────────────────┤
-│ 📋 회의 기본정보 (카드)                  │
-├─────────────────────────────────────────┤
-│ 📑 4개 탭 컨테이너                       │
-│  ┌──────────────────────────────────┐  │
-│  │ 🧑‍🤝‍🧑 참석자 | 📝 AI메모 | 📚 용어  │  │
-│  │ 사전 | 📂 관련회의록               │  │
-│  └──────────────────────────────────┘  │
-├─────────────────────────────────────────┤
-│ ⏸️ 일시정지 | 🔴 회의 종료 버튼         │
-└─────────────────────────────────────────┘
-```
-
-#### 탭1: 참석자 (Lines 697-747)
-
-| 화면 기능 | 요구 API | 구현 상태 | 구현 위치 | 비고 |
-|---------|---------|----------|----------|------|
-| 회의 시작 | `POST /api/meetings/{meetingId}/start` | ✅ 구현됨 | [MeetingController.java:149-170](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L149-L170) | WebSocket 세션 생성 |
-| WebSocket 연결 | `ws://localhost:8080/ws/collaboration` | ✅ 구현됨 | [MeetingController.java:165](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L165) | 실시간 협업 지원 |
-| 참석자 초대 | `POST /api/meetings/{meetingId}/invite` | ✅ 구현됨 | [MeetingController.java:289-321](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L289-L321) | 이메일 발송 포함 |
-| 참석자 목록 표시 | `GET /api/meetings/{meetingId}` | ✅ 구현됨 | [MeetingController.java:228-244](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L228-L244) | 회의 정보에 참석자 포함 |
-
-#### 탭2: AI 메모 (Lines 750-807) 🔴 **치명적 누락**
-
-| 화면 기능 | 요구 API | 구현 상태 | 프로토타입 근거 | 비고 |
-|---------|---------|----------|---------------|------|
-| **메모 입력 및 저장** | `PUT /api/meetings/{meetingId}/memo` | ❌ **누락** | [Line 1119-1143](design/uiux/prototype/05-회의진행.html#L1119-L1143) | 개인별 메모 저장 |
-| **AI 추천 실시간 조회** | `GET /api/ai/suggestions/realtime/{meetingId}` | ❌ **누락** | [Line 767-806](design/uiux/prototype/05-회의진행.html#L767-L806) | 실시간 폴링 필요 |
-| **AI 추천 채택** | `POST /api/ai/suggestions/{suggestionId}/adopt` | ❌ **누락** | [Line 1070-1097](design/uiux/prototype/05-회의진행.html#L1070-L1097) | 시간 포함 저장 |
-
-**프로토타입 JavaScript 분석** (saveMemo 함수):
-```javascript
-function saveMemo() {
-  const memo = memoTextarea.value.trim();
-  // 실제 구현시에는 서버로 전송
-  // fetch('/api/meetings/memo', {
-  //   method: 'PUT',
-  //   body: JSON.stringify({ memo: memo }),
-  //   headers: { 'Content-Type': 'application/json' }
-  // });
-}
-```
-
-**영향도**:
-- 🔴 사용자가 작성한 메모가 저장되지 않음 (데이터 손실 위험)
-- 🔴 AI 실시간 추천 기능 완전 미동작
-- 🔴 **유저스토리 US-07, US-08**의 핵심 기능
-
-#### 탭3: 용어사전 (Lines 810-967) 🟡 **부분 구현**
-
-| 화면 기능 | 요구 API | 구현 상태 | 구현 위치 | 비고 |
-|---------|---------|----------|----------|------|
-| **AI 전문용어 실시간 감지** | `POST /api/ai/terms/detect` | ✅ 구현됨 | [TermController.java:35-79](ai/src/main/java/com/unicorn/hgzero/ai/infra/controller/TermController.java#L35-L79) | 회의 중 용어 자동 감지 |
-| **용어 검색** | `GET /api/ai/terms/search` | ❌ **누락** | [Line 1145-1182](design/uiux/prototype/05-회의진행.html#L1145-L1182) | 키워드 검색 |
-| **용어 상세 조회** | `GET /api/ai/terms/{termName}/detail` | ❌ **누락** | [Line 1305-1308](design/uiux/prototype/05-회의진행.html#L1305-L1308) | 모달 표시 |
-
-#### 탭4: 관련회의록 (Lines 970-1010) ✅ **완벽 구현**
-
-| 화면 기능 | 요구 API | 구현 상태 | 구현 위치 | 비고 |
-|---------|---------|----------|----------|------|
-| **AI 유사 회의록 찾기** | `GET /api/ai/transcripts/{meetingId}/related` | ✅ 구현됨 | [RelationController.java:31-62](ai/src/main/java/com/unicorn/hgzero/ai/infra/controller/RelationController.java#L31-L62) | 벡터 유사도 검색 |
-| 관련 회의록 열기 | `GET /api/meetings/minutes/{minutesId}` | ✅ 구현됨 | 기존 API 재사용 | 새 탭 열기 |
-
-#### 녹음 제어 (Bottom Bar) 🔴 **치명적 누락**
-
-| 화면 기능 | 요구 API | 구현 상태 | 프로토타입 근거 | 비고 |
-|---------|---------|----------|---------------|------|
-| **녹음 일시정지** | `POST /api/stt/recordings/{recordingId}/pause` | ❌ **누락** | [Line 1212-1243](design/uiux/prototype/05-회의진행.html#L1212-L1243) | 타이머 정지 |
-| **녹음 재개** | `POST /api/stt/recordings/{recordingId}/resume` | ❌ **누락** | [Line 1212-1243](design/uiux/prototype/05-회의진행.html#L1212-L1243) | 타이머 재개 |
-| 녹음 시작 | `POST /api/stt/recordings/{recordingId}/start` | ✅ 구현됨 | [RecordingController.java:83-94](stt/src/main/java/com/unicorn/hgzero/stt/controller/RecordingController.java#L83-L94) | - |
-| 녹음 중지 | `POST /api/stt/recordings/{recordingId}/stop` | ✅ 구현됨 | [RecordingController.java:115-126](stt/src/main/java/com/unicorn/hgzero/stt/controller/RecordingController.java#L115-L126) | - |
-| 회의 종료 | `POST /api/meetings/{meetingId}/end` | ✅ 구현됨 | [MeetingController.java:184-214](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L184-L214) | AI 분석 포함 |
-
-**현재 상태**: RecordingController에는 `start`와 `stop`만 있고 `pause/resume` 없음
-
-**영향도**:
-- 🔴 회의 중 잠깐 중단 후 재개 시나리오 불가
-- 🔴 **유저스토리 US-06**의 핵심 기능
-
----
-
-**분석 결과**: ⚠️ **부분 구현 (50%)** - **실시간 기능 7개 API 누락**
-
-### 누락 API 상세 명세
-
-#### 1. 메모 저장 API 🔴 P0
-```java
-PUT /api/meetings/{meetingId}/memo
-Request Body: {
-  "memo": "string",
-  "userId": "string",
-  "timestamp": "datetime"
-}
-Response: { "memoId": "string", "savedAt": "datetime" }
-```
-
-#### 2. AI 실시간 추천 조회 API 🔴 P0
-```java
-GET /api/ai/suggestions/realtime/{meetingId}?since={timestamp}&limit=10
-Response: {
-  "suggestions": [
-    {
-      "suggestionId": "string",
-      "timestamp": "00:05:23",
-      "content": "string",
-      "confidence": 0.95,
-      "category": "DISCUSSION|DECISION"
-    }
-  ]
-}
-```
-
-#### 3. AI 추천 채택 API 🟡 P1
-```java
-POST /api/ai/suggestions/{suggestionId}/adopt
-Request Body: {
-  "meetingId": "string",
-  "timestamp": "00:05:23",
-  "userId": "string"
-}
-```
-
-#### 4. 용어 검색 API 🟡 P1
-```java
-GET /api/ai/terms/search?query={keyword}&meetingId={id}
-Response: {
-  "terms": [...],
-  "totalCount": 5
-}
-```
-
-#### 5. 용어 상세 조회 API 🟢 P2
-```java
-GET /api/ai/terms/{termName}/detail?meetingId={id}
-Response: {
-  "term": "string",
-  "definition": "string",
-  "usageInMeeting": [...],
-  "externalLinks": [...]
-}
-```
-
-#### 6-7. 녹음 일시정지/재개 API 🔴 P0
-```java
-POST /api/stt/recordings/{recordingId}/pause
-POST /api/stt/recordings/{recordingId}/resume
-Response: { "status": "PAUSED|RECORDING", "timestamp": "datetime" }
-```
-
----
-
-### 6. 회의 종료 화면 (07-회의종료.html)
-
-| 화면 기능 | 요구 API | 구현 상태 | 구현 위치 | 비고 |
-|---------|---------|----------|----------|------|
-| 회의 종료 | `POST /api/meetings/{meetingId}/end` | ✅ 구현됨 | [MeetingController.java:184-214](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L184-L214) | AI 분석, 회의록 생성 |
-
-**분석 결과**: ✅ **완벽 구현** - AI 기반 회의록 자동 생성 포함
-
----
-
-### 7. 회의록 상세 조회 화면 (10-회의록상세조회.html)
-
-| 화면 기능 | 요구 API | 구현 상태 | 구현 위치 | 비고 |
-|---------|---------|----------|----------|------|
-| 회의록 상세 조회 | `GET /api/meetings/minutes/{minutesId}` | ✅ 구현됨 | [MinutesController.java:271-297](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L271-L297) | 대시보드 탭, 회의록 탭 데이터 포함 |
-
-**분석 결과**: ✅ **완벽 구현** - 상세 조회 완전 구현 (Mock 데이터 포함)
-
----
-
-### 8. 회의록 수정 화면 (11-회의록수정.html)
-
-| 화면 기능 | 요구 API | 구현 상태 | 구현 위치 | 비고 |
-|---------|---------|----------|----------|------|
-| 회의록 수정 | `PATCH /api/meetings/minutes/{minutesId}` | ✅ 구현됨 | [MinutesController.java:300-343](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L300-L343) | 제목, 섹션 내용 수정 |
-| 회의록 확정 | `POST /api/meetings/minutes/{minutesId}/finalize` | ✅ 구현됨 | [MinutesController.java:346-374](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L346-L374) | 버전 관리 포함 |
-| 섹션 검증 | `POST /api/meetings/minutes/{minutesId}/sections/{sectionId}/verify` | ✅ 구현됨 | [MinutesController.java:377-410](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L377-L410) | 섹션별 완료 검증 |
-| 섹션 잠금 | `POST /api/meetings/minutes/{minutesId}/sections/{sectionId}/lock` | ✅ 구현됨 | [MinutesController.java:413-446](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L413-L446) | 동시 편집 방지 |
-| 섹션 잠금 해제 | `DELETE /api/meetings/minutes/{minutesId}/sections/{sectionId}/lock` | ✅ 구현됨 | [MinutesController.java:449-480](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L449-L480) | 잠금 해제 |
-| AI 요약 재생성 | `POST /api/meetings/minutes/{minutesId}/sections/{sectionId}/regenerate-summary` | ❌ **누락** | - | AI 요약 재생성 기능 필요 |
-
-**분석 결과**: ⚠️ **부분 구현** (83%)
-- **누락 API (1개)**: AI 요약 재생성 기능
-
-**권장사항**:
-```java
-// MinutesController에 추가 필요
-@PostMapping("/{minutesId}/sections/{sectionId}/regenerate-summary")
-@Operation(summary = "AI 요약 재생성", description = "섹션의 AI 요약을 재생성합니다")
-public ResponseEntity<ApiResponse<SectionSummary>> regenerateSummary(
-    @PathVariable String minutesId,
-    @PathVariable String sectionId,
-    @RequestHeader("X-User-Id") String userId
-)
-```
-
----
-
-### 9. 회의록 목록 조회 화면 (12-회의록목록조회.html)
-
-| 화면 기능 | 요구 API | 구현 상태 | 구현 위치 | 비고 |
-|---------|---------|----------|----------|------|
-| 회의록 목록 조회 | `GET /api/meetings/minutes` | ✅ 구현됨 | [MinutesController.java:210-268](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L210-L268) | 상태 필터, 페이징 지원 |
-| 검색 기능 | `GET /api/meetings/minutes?keyword={keyword}` | ⚠️ **개선 필요** | [MinutesController.java:210](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L210) | 키워드 검색 파라미터 추가 필요 |
-| 참여 유형 필터 | `GET /api/meetings/minutes?participationType={type}` | ⚠️ **개선 필요** | [MinutesController.java:210](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L210) | 참여 유형 필터 추가 필요 |
-
-**분석 결과**: ⚠️ **개선 필요**
-- 기본 목록 조회는 구현되어 있으나, 프로토타입에서 요구하는 세부 필터링 기능 미구현
-
-**권장사항**:
-```java
-// MinutesController 개선 필요
-@GetMapping
-public ResponseEntity<ApiResponse<MinutesListResponse>> getMinutesList(
-    @RequestHeader("X-User-Id") String userId,
-    @RequestParam(required = false) String status,  // 기존 기능
-    @RequestParam(required = false) String keyword,  // 추가 필요 - 제목/내용 검색
-    @RequestParam(required = false) String participationType,  // 추가 필요 - host, participant, all
-    @RequestParam(defaultValue = "0") int page,
-    @RequestParam(defaultValue = "20") int size,
-    @RequestParam(defaultValue = "createdAt") String sortBy,
-    @RequestParam(defaultValue = "desc") String sortDir
-)
-```
-
----
-
-## 📊 통합 분석
-
-### 구현된 API 목록 (24개)
-
-#### 인증 서비스 (4개)
-| API | 메서드 | 엔드포인트 | 구현 위치 |
-|-----|--------|-----------|----------|
-| 로그인 | POST | `/api/auth/login` | [UserController.java:37](user/src/main/java/com/unicorn/hgzero/user/controller/UserController.java#L37) |
-| 토큰 갱신 | POST | `/api/auth/refresh` | [UserController.java:59](user/src/main/java/com/unicorn/hgzero/user/controller/UserController.java#L59) |
-| 로그아웃 | POST | `/api/auth/logout` | [UserController.java:82](user/src/main/java/com/unicorn/hgzero/user/controller/UserController.java#L82) |
-| 토큰 검증 | GET | `/api/auth/validate` | [UserController.java:105](user/src/main/java/com/unicorn/hgzero/user/controller/UserController.java#L105) |
-
-#### 회의 관리 서비스 (6개 - 목록 조회, 회의 수정 누락)
-| API | 메서드 | 엔드포인트 | 구현 위치 |
-|-----|--------|-----------|----------|
-| 회의 생성 | POST | `/api/meetings` | [MeetingController.java:60](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L60) |
-| 템플릿 적용 | PUT | `/api/meetings/{meetingId}/template` | [MeetingController.java:108](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L108) |
-| 회의 시작 | POST | `/api/meetings/{meetingId}/start` | [MeetingController.java:149](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L149) |
-| 회의 종료 | POST | `/api/meetings/{meetingId}/end` | [MeetingController.java:184](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L184) |
-| 회의 단건 조회 | GET | `/api/meetings/{meetingId}` | [MeetingController.java:228](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L228) |
-| 회의 취소 | DELETE | `/api/meetings/{meetingId}` | [MeetingController.java:258](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L258) |
-| 참석자 초대 | POST | `/api/meetings/{meetingId}/invite` | [MeetingController.java:289](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L289) |
-
-**⚠️ 누락 API (2개)**:
-1. `GET /api/meetings` (회의 목록 조회) - 대시보드 "최근 회의" 섹션에 필수
-2. `PUT /api/meetings/{meetingId}` (회의 정보 수정) - **예정된 회의 수정 불가**
-
-#### 회의록 관리 서비스 (7개)
-| API | 메서드 | 엔드포인트 | 구현 위치 |
-|-----|--------|-----------|----------|
-| 회의록 목록 조회 | GET | `/api/meetings/minutes` | [MinutesController.java:210](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L210) |
-| 회의록 상세 조회 | GET | `/api/meetings/minutes/{minutesId}` | [MinutesController.java:271](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L271) |
-| 회의록 수정 | PATCH | `/api/meetings/minutes/{minutesId}` | [MinutesController.java:300](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L300) |
-| 회의록 확정 | POST | `/api/meetings/minutes/{minutesId}/finalize` | [MinutesController.java:346](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L346) |
-| 섹션 검증 | POST | `/api/meetings/minutes/{minutesId}/sections/{sectionId}/verify` | [MinutesController.java:377](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L377) |
-| 섹션 잠금 | POST | `/api/meetings/minutes/{minutesId}/sections/{sectionId}/lock` | [MinutesController.java:413](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L413) |
-| 섹션 잠금 해제 | DELETE | `/api/meetings/minutes/{minutesId}/sections/{sectionId}/lock` | [MinutesController.java:449](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MinutesController.java#L449) |
-
-#### Todo 관리 서비스 (4개)
-| API | 메서드 | 엔드포인트 | 구현 위치 |
-|-----|--------|-----------|----------|
-| Todo 생성 | POST | `/api/meetings/todos` | [TodoController.java:50](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/TodoController.java#L50) |
-| Todo 수정 | PATCH | `/api/meetings/todos/{todoId}` | [TodoController.java:114](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/TodoController.java#L114) |
-| Todo 완료 | PATCH | `/api/meetings/todos/{todoId}/complete` | [TodoController.java:163](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/TodoController.java#L163) |
-| Todo 목록 조회 | GET | `/api/meetings/todos` | [TodoController.java:210](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/TodoController.java#L210) |
-
-#### 템플릿 관리 서비스 (1개)
-| API | 메서드 | 엔드포인트 | 구현 위치 |
-|-----|--------|-----------|----------|
-| 템플릿 목록 조회 | GET | `/api/meetings/templates` | [TemplateController.java:33](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/TemplateController.java#L33) |
-
-#### WebSocket (1개)
-| API | 프로토콜 | 엔드포인트 | 구현 위치 |
-|-----|---------|-----------|----------|
-| 실시간 협업 | WebSocket | `ws://localhost:8080/ws/collaboration` | [MeetingController.java:165](meeting/src/main/java/com/unicorn/hgzero/meeting/infra/controller/MeetingController.java#L165) |
-
----
-
-### ❌ 누락된 API 목록 (4개 완전 누락 + 2개 개선 필요)
-
-#### 완전 누락 (4개)
-| 우선순위 | API | 메서드 | 엔드포인트 | 필요한 이유 | 권장 구현 위치 |
-|---------|-----|--------|-----------|-----------|--------------|
-| 🔴 **긴급** | 회의 목록 조회 | GET | `/api/meetings` | 대시보드 "최근 회의" 섹션 표시 **불가** | MeetingController |
-| 🔴 **긴급** | 회의 정보 수정 | PUT/PATCH | `/api/meetings/{meetingId}` | 대시보드에서 예정된 회의 클릭 시 수정 **불가** | MeetingController |
-| 🔴 **긴급** | 대시보드 통계 | GET | `/api/dashboard/statistics` | 대시보드 통계 카드 (예정된 회의, 작성중 회의록) 표시 **불가** | 신규 DashboardController |
-| 🟡 중간 | AI 요약 재생성 | POST | `/api/meetings/minutes/{minutesId}/sections/{sectionId}/regenerate-summary` | 회의록 수정 화면 AI 요약 재생성 버튼 **동작 불가** | MinutesController |
-
-#### 기능 개선 필요 (2개)
-| 우선순위 | API | 현재 상태 | 개선 내용 | 필요한 이유 |
-|---------|-----|----------|-----------|-----------|
-| 🟡 중간 | 회의록 목록 조회 | `GET /api/meetings/minutes` 구현됨 | `keyword` 파라미터 추가 | 회의록 목록 화면 검색 기능 동작 안 함 |
-| 🟡 중간 | 회의록 목록 조회 | `GET /api/meetings/minutes` 구현됨 | `participationType` 파라미터 추가 | 회의록 목록 화면 참여 유형 필터 동작 안 함 |
-
----
-
-### ✅ 불필요한 API (0개)
-
-**분석 결과**: 구현된 모든 API가 프로토타입에서 요구하는 기능과 매칭되며, 불필요한 API는 없음.
-
----
-
-## 💡 권장 개선사항
-
-### 1. 높은 우선순위 (🔴 필수)
-
-#### 1.1 회의 목록 조회 API 추가
-```java
-// MeetingController.java에 추가
-@GetMapping
-@Operation(summary = "회의 목록 조회", description = "사용자의 회의 목록을 조회합니다")
-public ResponseEntity<ApiResponse<MeetingListResponse>> getMeetingList(
-    @RequestHeader("X-User-Id") String userId,
-    @RequestParam(required = false) String status,  // upcoming, ongoing, completed
-    @RequestParam(required = false) LocalDateTime startDate,
-    @RequestParam(required = false) LocalDateTime endDate,
-    @RequestParam(defaultValue = "0") int page,
-    @RequestParam(defaultValue = "10") int size,
-    @RequestParam(defaultValue = "startTime") String sortBy,
-    @RequestParam(defaultValue = "asc") String sortDir
-) {
-    // 구현 로직
-}
-```
-
-**요구사항**:
-- 상태별 필터링: `upcoming` (예정), `ongoing` (진행 중), `completed` (완료)
-- 날짜 범위 필터링
-- 페이징 지원
-- 정렬 기능 (시작 시간, 생성 시간 등)
-
----
-
-#### 1.2 대시보드 통계 API 추가
-```java
-// 신규 DashboardController.java 생성
-@RestController
-@RequestMapping("/api/dashboard")
-@RequiredArgsConstructor
-@Tag(name = "Dashboard", description = "대시보드 API")
-public class DashboardController {
-
-    @GetMapping("/statistics")
-    @Operation(summary = "대시보드 통계 조회", description = "사용자의 통계 정보를 조회합니다")
-    public ResponseEntity<ApiResponse<DashboardStatistics>> getStatistics(
-        @RequestHeader("X-User-Id") String userId
-    ) {
-        // 구현 로직
-    }
-}
-```
-
-**응답 데이터 구조**:
-```json
-{
-  "totalMeetings": 24,
-  "upcomingMeetings": 3,
-  "completedMinutes": 18,
-  "pendingTodos": 7,
-  "completedTodos": 15,
-  "thisWeekMeetings": 5,
-  "thisMonthMeetings": 12
-}
-```
-
----
-
-### 2. 중간 우선순위 (🟡 권장)
-
-#### 2.1 AI 요약 재생성 API 추가
-```java
-// MinutesController.java에 추가
-@PostMapping("/{minutesId}/sections/{sectionId}/regenerate-summary")
-@Operation(summary = "AI 요약 재생성", description = "섹션의 AI 요약을 재생성합니다")
-public ResponseEntity<ApiResponse<SectionSummary>> regenerateSummary(
-    @PathVariable String minutesId,
-    @PathVariable String sectionId,
-    @RequestHeader("X-User-Id") String userId,
-    @RequestHeader("X-User-Name") String userName
-) {
-    // AI 서비스 호출하여 요약 재생성
-    // 버전 관리 (이전 요약 보존)
-    // 이벤트 발행 (요약 재생성 알림)
-}
-```
-
----
-
-#### 2.2 회의록 목록 API 개선
-```java
-// MinutesController.java 수정
-@GetMapping
-public ResponseEntity<ApiResponse<MinutesListResponse>> getMinutesList(
-    @RequestHeader("X-User-Id") String userId,
-    @RequestParam(required = false) String status,
-    @RequestParam(required = false) String keyword,  // 추가 - 제목/내용 검색
-    @RequestParam(required = false) String participationType,  // 추가 - host, participant, all
-    @RequestParam(defaultValue = "0") int page,
-    @RequestParam(defaultValue = "20") int size,
-    @RequestParam(defaultValue = "createdAt") String sortBy,
-    @RequestParam(defaultValue = "desc") String sortDir
-) {
-    // 구현 로직
-}
-```
-
-**추가 필터 설명**:
-- `keyword`: 회의록 제목 또는 내용에서 검색 (LIKE 검색)
-- `participationType`:
-  - `host`: 주최한 회의록만
-  - `participant`: 참여한 회의록만
-  - `all`: 모든 회의록 (기본값)
-
----
-
-### 3. 낮은 우선순위 (🟢 선택)
-
-#### 3.1 회의록 버전 관리 API
-```java
-// MinutesController.java에 추가 고려
-@GetMapping("/{minutesId}/versions")
-@Operation(summary = "회의록 버전 목록 조회")
-public ResponseEntity<ApiResponse<List<MinutesVersion>>> getMinutesVersions(
-    @PathVariable String minutesId
-)
-
-@GetMapping("/{minutesId}/versions/{version}")
-@Operation(summary = "특정 버전 회의록 조회")
-public ResponseEntity<ApiResponse<MinutesDetail>> getMinutesVersion(
-    @PathVariable String minutesId,
-    @PathVariable int version
-)
-```
-
----
-
-## 🎯 구현 우선순위 로드맵
-
-### Phase 1: 필수 기능 (Sprint 1-2)
-1. ✅ **회의 목록 조회 API** (MeetingController)
-   - 예상 작업 시간: 4시간
-   - 의존성: MeetingService, MeetingRepository
-
-2. ✅ **대시보드 통계 API** (신규 DashboardController)
-   - 예상 작업 시간: 6시간
-   - 의존성: MeetingService, MinutesService, TodoService
-
-### Phase 2: 개선 기능 (Sprint 3)
-3. ✅ **AI 요약 재생성 API** (MinutesController)
-   - 예상 작업 시간: 8시간
-   - 의존성: AI Service, Event Publisher
-
-4. ✅ **회의록 검색/필터 개선** (MinutesController)
-   - 예상 작업 시간: 3시간
-   - 의존성: MinutesRepository (쿼리 추가)
-
-### Phase 3: 선택 기능 (Sprint 4)
-5. ⏸️ **버전 관리 API** (MinutesController)
-   - 예상 작업 시간: 6시간
-   - 의존성: 버전 관리 스키마 설계
-
----
-
-## 📝 코드 리뷰 의견
-
-### ✅ 잘된 점
-
-1. **일관된 API 설계**
-   - RESTful 원칙 준수
-   - 명확한 엔드포인트 네이밍
-   - 표준 HTTP 메서드 사용
-
-2. **포괄적인 문서화**
-   - Swagger/OpenAPI 주석 완벽 작성
-   - 각 API마다 상세한 설명과 파라미터 문서화
-
-3. **보안 고려**
-   - JWT 기반 인증/인가
-   - LDAP 통합
-   - Request Header를 통한 사용자 식별
-
-4. **실용적인 Mock 데이터**
-   - 프론트엔드 개발을 위한 상세한 Mock 데이터 제공
-   - 실제 데이터 구조와 동일한 형태
-
-5. **캐시 전략**
-   - Redis 캐시 적극 활용
-   - 적절한 캐시 무효화 로직
-
-6. **이벤트 기반 아키텍처**
-   - Event Publisher를 통한 비동기 처리
-   - 알림 시스템 통합 준비
-
-### ⚠️ 개선이 필요한 점
-
-1. **누락된 핵심 API**
-   - 대시보드 통계 API 없음 → 사용자 경험 저하
-   - 회의 목록 조회 API 없음 → 대시보드 불완전
-
-2. **검색 기능 부족**
-   - 회의록 검색 파라미터 미구현
-   - 키워드 기반 검색 불가
-
-3. **에러 처리 일관성**
-   - 일부 Controller에서 try-catch로 처리
-   - 일부는 비즈니스 예외를 그대로 던짐
-   - 통일된 예외 처리 전략 필요
-
-4. **테스트 코드 부재**
-   - Controller 테스트 코드 확인 필요
-   - API 통합 테스트 권장
-
----
-
-## 🔧 기술적 권장사항
-
-### 1. API 버전 관리
-```java
-// 향후 API 변경에 대비한 버전 관리 권장
-@RequestMapping("/api/v1/meetings")
-```
-
-### 2. 페이징 표준화
-```java
-// 모든 목록 조회 API에 일관된 페이징 파라미터 적용
-@RequestParam(defaultValue = "0") int page
-@RequestParam(defaultValue = "20") int size
-@RequestParam(defaultValue = "createdAt") String sortBy
-@RequestParam(defaultValue = "desc") String sortDir
-```
-
-### 3. 응답 데이터 일관성
-```java
-// 모든 API가 ApiResponse 래퍼 사용 (이미 잘 적용됨)
-public class ApiResponse<T> {
-    private String message;
-    private T data;
-    private String errorCode;  // 에러 처리 강화
-}
-```
-
-### 4. Rate Limiting
-```java
-// 공격 방지를 위한 Rate Limiting 추가 권장
-@RateLimit(limit = 100, duration = 1, unit = TimeUnit.MINUTES)
-```
-
----
-
-## 📈 비교 지표
-
-| 항목 | 프로토타입 요구사항 | 구현 현황 | 구현률 |
-|-----|------------------|----------|--------|
-| 인증 API | 4개 | 4개 | 100% ✅ |
-| 회의 관리 API | 8개 | 6개 | 75% ⚠️ |
-| 회의록 관리 API | 8개 | 7개 | 88% ⚠️ |
-| Todo 관리 API | 4개 | 4개 | 100% ✅ |
-| 템플릿 API | 2개 | 2개 | 100% ✅ |
-| 대시보드 API | 1개 | 0개 | 0% ❌ |
-| **전체 합계** | **27개** | **23개** | **85%** ⚠️ |
-
----
-
-## 🎬 결론
-
-### 종합 평가
-- **전체 구현률**: 85% (23/27 API)
-- **핵심 비즈니스 로직**: ⚠️ 회의 수정 기능 누락
-- **사용자 경험**: ⚠️ 개선 필요 (대시보드 회의 목록, 회의 수정, 통계, 검색 기능)
-- **코드 품질**: ✅ 우수 (문서화, 구조, 보안)
-
-### 즉시 조치 필요 (🔴 긴급 - 3개)
-1. 🔴 **회의 목록 조회 API 구현** (`GET /api/meetings`)
-   - 대시보드 "최근 회의" 섹션 표시 불가
-
-2. 🔴 **회의 정보 수정 API 구현** (`PUT /api/meetings/{meetingId}`)
-   - **설계서에도 누락됨** - API 명세서 작성 필요
-   - 예정된 회의를 수정할 수 없음
-   - 대시보드에서 scheduled 회의 클릭 시 동작 불가
-
-3. 🔴 **대시보드 통계 API 구현** (`GET /api/dashboard/statistics`)
-   - 대시보드 통계 카드 표시 불가
-
-### 다음 스프린트 권장
-3. 🟡 **AI 요약 재생성 API 구현** (사용자 경험 개선)
-4. 🟡 **회의록 검색 기능 강화** (사용성 향상)
-
-### 장기 개선 과제
-5. 🟢 **버전 관리 API** (고급 기능)
-6. 🟢 **Rate Limiting 적용** (보안 강화)
-7. 🟢 **API 버전 관리 도입** (확장성)
-
----
-
-**리뷰 완료일**: 2025-10-28
-**리뷰어**: Architect, Backend Developer, Frontend Developer
-**다음 리뷰 예정**: Phase 1 구현 완료 후

common/src/main/java/com/unicorn/hgzero/common/exception/ErrorCode.java

@@ -41,6 +41,9 @@ public enum ErrorCode {
     INVALID_MEETING_TIME(HttpStatus.BAD_REQUEST, "M002", "회의 시작 시간이 종료 시간보다 늦습니다."),
     MEETING_NOT_FOUND(HttpStatus.NOT_FOUND, "M003", "회의를 찾을 수 없습니다."),
     INVALID_MEETING_STATUS(HttpStatus.BAD_REQUEST, "M004", "유효하지 않은 회의 상태입니다."),
+    MEETING_NOT_IN_PROGRESS(HttpStatus.BAD_REQUEST, "M005", "회의가 진행 중이 아닙니다."),
+    MINUTES_NOT_FOUND(HttpStatus.NOT_FOUND, "M006", "회의록을 찾을 수 없습니다."),
+    AGENDA_SECTION_NOT_FOUND(HttpStatus.NOT_FOUND, "M007", "안건 섹션을 찾을 수 없습니다."),
 
     // 외부 시스템 에러 (4xxx)
     EXTERNAL_API_ERROR(HttpStatus.INTERNAL_SERVER_ERROR, "E001", "외부 API 호출 중 오류가 발생했습니다."),

deploy/k8s/backend/ai-secret-template.yaml

@@ -0,0 +1,27 @@
+---
+# AI Service Secret Template
+# 실제 배포 시 base64로 인코딩된 값으로 교체 필요
+apiVersion: v1
+kind: Secret
+metadata:
+  name: ai-secret
+  namespace: hgzero
+type: Opaque
+data:
+  # Claude API Key (base64 인코딩 필요)
+  # echo -n "sk-ant-api03-..." | base64
+  claude-api-key: <BASE64_ENCODED_CLAUDE_API_KEY>
+
+---
+# Azure EventHub Secret for AI Service
+# AI 서비스용 Event Hub 연결 문자열
+apiVersion: v1
+kind: Secret
+metadata:
+  name: azure-secret
+  namespace: hgzero
+type: Opaque
+data:
+  # Event Hub Connection String (AI Listen Policy)
+  # echo -n "Endpoint=sb://..." | base64
+  eventhub-ai-connection-string: <BASE64_ENCODED_EVENTHUB_CONNECTION_STRING>

deploy/k8s/backend/ai-service.yaml

@@ -0,0 +1,130 @@
+---
+# AI Service (Python) Deployment
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: ai-service
+  namespace: hgzero
+  labels:
+    app: ai-service
+    tier: backend
+    language: python
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: ai-service
+  template:
+    metadata:
+      labels:
+        app: ai-service
+        tier: backend
+        language: python
+    spec:
+      containers:
+      - name: ai-service
+        image: acrdigitalgarage02.azurecr.io/hgzero/ai-service:latest
+        imagePullPolicy: Always
+        ports:
+        - containerPort: 8087
+          name: http
+        env:
+        # 서버 설정
+        - name: PORT
+          value: "8087"
+        - name: HOST
+          value: "0.0.0.0"
+        - name: LOG_LEVEL
+          value: "INFO"
+
+        # Claude API
+        - name: CLAUDE_API_KEY
+          valueFrom:
+            secretKeyRef:
+              name: ai-secret
+              key: claude-api-key
+        - name: CLAUDE_MODEL
+          value: "claude-3-5-sonnet-20241022"
+        - name: CLAUDE_MAX_TOKENS
+          value: "2000"
+        - name: CLAUDE_TEMPERATURE
+          value: "0.3"
+
+        # Redis
+        - name: REDIS_HOST
+          valueFrom:
+            configMapKeyRef:
+              name: redis-config
+              key: host
+        - name: REDIS_PORT
+          valueFrom:
+            configMapKeyRef:
+              name: redis-config
+              key: port
+        - name: REDIS_PASSWORD
+          valueFrom:
+            secretKeyRef:
+              name: redis-secret
+              key: password
+        - name: REDIS_DB
+          value: "4"
+
+        # Azure Event Hub
+        - name: EVENTHUB_CONNECTION_STRING
+          valueFrom:
+            secretKeyRef:
+              name: azure-secret
+              key: eventhub-ai-connection-string
+        - name: EVENTHUB_NAME
+          value: "hgzero-eventhub-name"
+        - name: EVENTHUB_CONSUMER_GROUP
+          value: "$Default"
+
+        # CORS
+        - name: CORS_ORIGINS
+          value: '["*"]'
+
+        resources:
+          requests:
+            cpu: 250m
+            memory: 512Mi
+          limits:
+            cpu: 1000m
+            memory: 1024Mi
+
+        livenessProbe:
+          httpGet:
+            path: /health
+            port: 8087
+          initialDelaySeconds: 30
+          periodSeconds: 10
+          timeoutSeconds: 5
+          failureThreshold: 3
+
+        readinessProbe:
+          httpGet:
+            path: /health
+            port: 8087
+          initialDelaySeconds: 10
+          periodSeconds: 5
+          timeoutSeconds: 3
+          failureThreshold: 3
+
+---
+# AI Service Service
+apiVersion: v1
+kind: Service
+metadata:
+  name: ai-service
+  namespace: hgzero
+  labels:
+    app: ai-service
+spec:
+  type: ClusterIP
+  ports:
+  - port: 8087
+    targetPort: 8087
+    protocol: TCP
+    name: http
+  selector:
+    app: ai-service

design/backend/api/API설계서.md

@@ -18,18 +18,19 @@
 
 ### 프로젝트 정보
 - **프로젝트명**: 회의록 작성 및 공유 개선 서비스
-- **설계 버전**: v2.0
+- **설계 버전**: v2.1
-- **설계일**: 2025-01-23
+- **최종 수정일**: 2025-01-29
-- **설계자**: 아키텍트(길동), Backend Developer(준호)
+- **설계자**: 아키텍트(길동), Backend Developer(준호, 동욱)
 
 ### 마이크로서비스 구성
-본 서비스는 5개의 마이크로서비스로 구성됩니다:
+본 서비스는 6개의 마이크로서비스로 구성됩니다:
 
 1. **User Service** - 사용자 인증 (LDAP 연동, JWT 토큰 발급/검증)
 2. **Meeting Service** - 회의, 회의록, Todo, 실시간 협업 통합 관리
 3. **STT Service** - 음성 녹음 관리, 음성-텍스트 변환, 화자 식별
-4. **AI Service** - AI 기반 회의록 자동화, Todo 추출, 지능형 검색 (RAG 통합)
+4. **AI Service** - AI 기반 회의록 자동화, Todo 추출, RAG 서비스 연동
-5. **Notification Service** - 알림 발송 및 리마인더 관리
+5. **RAG Service** - 용어집/관련자료/회의록 검색 (Python/FastAPI 독립 서비스)
+6. **Notification Service** - 알림 발송 및 리마인더 관리
 
 ---
 
@@ -194,52 +195,106 @@
 
 #### API 목록
 
-**Transcript Processing APIs (2개)**
+**Transcript Processing APIs (1개)**
 | Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
 |--------|----------|------|-----------|----------|
 | POST | /transcripts/process | 회의록 자동 작성 | UFR-AI-010 | TranscriptController |
-| POST | /transcripts/{meetingId}/improve | 회의록 개선 (프롬프팅) | UFR-AI-030 | TranscriptController |
 
 **Todo APIs (1개)**
 | Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
 |--------|----------|------|-----------|----------|
 | POST | /todos/extract | Todo 자동 추출 | UFR-AI-020 | TodoController |
 
-**Related Minutes APIs (1개)**
+**Summary APIs (2개)**
 | Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
 |--------|----------|------|-----------|----------|
-| GET | /transcripts/{meetingId}/related | 관련 회의록 연결 | UFR-AI-040 | TranscriptController |
+| POST | /sections/{sectionId}/summary | 안건별 AI 요약 생성 | UFR-AI-010 | SectionController |
+| POST | /sections/{sectionId}/regenerate | 한줄 요약 재생성 | UFR-AI-036 | SectionController |
 
-**Term Explanation APIs (2개)**
+**Suggestion APIs (1개) - 실시간 AI 제안**
 | Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
 |--------|----------|------|-----------|----------|
-| POST | /terms/detect | 전문용어 감지 | UFR-RAG-010 | TermController |
+| GET | /meetings/{meetingId}/suggestions/stream | 실시간 주요 내용 제안 (SSE) | UFR-AI-030 | SuggestionController |
-| GET | /terms/{term}/explain | 맥락 기반 용어 설명 | UFR-RAG-020 | TermController |
 
-**Suggestion APIs (2개)**
+**Related Transcripts APIs (1개) - RAG 연동**
 | Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
 |--------|----------|------|-----------|----------|
-| POST | /suggestions/discussion | 논의사항 제안 | UFR-AI-010 | SuggestionController |
+| GET | /transcripts/{meetingId}/related | 관련 회의록 검색 (RAG 서비스 연동) | UFR-AI-040 | RelatedTranscriptController |
-| POST | /suggestions/decision | 결정사항 제안 | UFR-AI-010 | SuggestionController |
+
+**Term APIs (2개) - RAG 연동**
+| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
+|--------|----------|------|-----------|----------|
+| POST | /terms/detect | 전문용어 감지 (RAG 서비스 연동) | UFR-RAG-010 | TermController |
+| GET | /terms/{termId}/explain | 맥락 기반 용어 설명 (RAG 서비스 연동) | UFR-RAG-020 | ExplanationController |
 
 #### 주요 특징
-- LLM 기반 회의록 자동 작성
+- LLM 기반 회의록 자동 작성 (Claude 3.5 Sonnet)
-- 7가지 프롬프트 유형 지원
+- RAG Service 연동
-  - 1Page 요약, 핵심 요약, 상세 보고서
+  - 전문용어 자동 감지 및 맥락 기반 설명
-  - 의사결정 중심, 액션 아이템 중심
+  - 관련 회의록 검색 (벡터 유사도 70% 이상)
-  - 경영진 보고용, 커스텀
+  - 조직 내 문서 및 이력 기반 용어 설명 생성
-- RAG 기반 관련 회의록 검색 (벡터 유사도 70% 이상)
+- 안건별 요약 생성 (한줄 요약 + 상세 요약)
-- 맥락 기반 전문용어 설명
+- 실시간 주요 내용 제안 (SSE 스트리밍)
-- 실시간 논의사항/결정사항 제안
+- Todo 자동 추출 (Meeting Service에 전달)
 
 #### 차별화 포인트
-1. **맥락 기반 용어 설명**: 단순 정의가 아닌 조직 내 실제 사용 맥락 제공
+1. **맥락 기반 용어 설명**: 단순 사전 정의가 아닌, RAG를 통해 조직 내 실제 사용 맥락과 과거 논의 이력 제공
-2. **프롬프팅 기반 개선**: 다양한 형식의 회의록 생성
+2. **하이브리드 검색 기반 연관성**: 키워드 매칭과 벡터 유사도를 결합하여 관련 회의록 정확도 향상
-3. **실시간 추천**: AI 기반 논의사항/결정사항 자동 제안
+3. **실시간 AI 제안**: SSE 기반 스트리밍으로 회의 중 주요 내용 실시간 제안
 
 ---
 
-### 5. Notification Service
+### 5. RAG Service
+
+#### 개요
+- **파일**: `rag-service-api.yaml`
+- **베이스 URL**: `/api/rag`
+- **주요 기능**: 용어집 검색, 관련자료 검색, 회의록 유사도 검색
+- **기술 스택**: Python 3.11+, FastAPI, PostgreSQL+pgvector, Azure AI Search, Redis
+
+#### API 목록
+
+**Terms APIs (3개) - 용어집 검색**
+| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
+|--------|----------|------|-----------|----------|
+| POST | /terms/search | 용어 검색 (Hybrid: Keyword + Vector) | UFR-RAG-010 | TermsController |
+| GET | /terms/{termId} | 용어 상세 조회 | UFR-RAG-010 | TermsController |
+| POST | /terms/{termId}/explain | 맥락 기반 용어 설명 (Claude AI) | UFR-RAG-020 | TermsController |
+
+**Documents APIs (2개) - 관련자료 검색**
+| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
+|--------|----------|------|-----------|----------|
+| POST | /documents/search | 관련 문서 검색 (Hybrid Search + Semantic Ranking) | UFR-RAG-030 | DocumentsController |
+| GET | /documents/stats | 문서 통계 조회 | - | DocumentsController |
+
+**Minutes APIs (4개) - 회의록 유사도 검색**
+| Method | Endpoint | 설명 | 유저스토리 | 컨트롤러 |
+|--------|----------|------|-----------|----------|
+| POST | /minutes/search | 회의록 벡터 검색 | UFR-RAG-030 | MinutesController |
+| GET | /minutes/{minutesId} | 회의록 상세 조회 | UFR-RAG-030 | MinutesController |
+| POST | /minutes/related | 연관 회의록 조회 (벡터 유사도) | UFR-RAG-030 | MinutesController |
+| GET | /minutes/stats | 회의록 통계 조회 | - | MinutesController |
+
+#### 주요 특징
+- **하이브리드 검색**: 키워드 검색 + 벡터 유사도 검색 (가중치 기반 통합)
+- **임베딩 모델**: Azure OpenAI text-embedding-3-large (3,072 차원)
+- **LLM**: Claude 3.5 Sonnet (맥락 기반 설명 생성)
+- **캐싱**: Redis 기반 결과 캐싱 (TTL: 30분~1시간)
+- **EventHub 연동**: Meeting 서비스에서 회의록 확정 이벤트 수신 → 벡터 DB 저장
+
+#### 데이터베이스
+- **PostgreSQL + pgvector**: 용어집 저장 및 벡터 검색
+- **Azure AI Search**: 관련자료 하이브리드 검색 + Semantic Ranking
+- **벡터 유사도**: Cosine Similarity (임계값 70% 이상)
+
+#### 성능 요구사항
+- **용어 검색**: < 500ms (캐시 HIT 시 < 50ms)
+- **용어 설명 생성**: < 3초 (Claude API 호출 포함)
+- **회의록 검색**: < 1초 (캐시 HIT 시 < 100ms)
+
+---
+
+### 6. Notification Service
 
 #### 개요
 - **파일**: `notification-service-api.yaml`
@@ -365,11 +420,12 @@ sort: 정렬 기준 (예: createdAt,desc)
    - https://editor.swagger.io/
 
 2. **각 서비스 YAML 파일 확인**
-   - `design/backend/api/user-service-api.yaml`
+   - `design/backend/api/spec/user-service-api.yaml`
-   - `design/backend/api/meeting-service-api.yaml`
+   - `design/backend/api/spec/meeting-service-api.yaml`
-   - `design/backend/api/stt-service-api.yaml`
+   - `design/backend/api/spec/stt-service-api.yaml`
-   - `design/backend/api/ai-service-api.yaml`
+   - `design/backend/api/spec/ai-service-api.yaml`
-   - `design/backend/api/notification-service-api.yaml`
+   - `design/backend/api/spec/rag-service-api.yaml`
+   - `design/backend/api/spec/notification-service-api.yaml`
 
 3. **파일 내용 붙여넣기**
    - 좌측 패널에 YAML 내용 붙여넣기
@@ -389,19 +445,20 @@ npm install -g @apidevtools/swagger-cli
 #### 검증 실행
 ```bash
 # 개별 파일 검증
-swagger-cli validate design/backend/api/user-service-api.yaml
+swagger-cli validate design/backend/api/spec/user-service-api.yaml
 
 # 전체 파일 검증
-swagger-cli validate design/backend/api/*.yaml
+swagger-cli validate design/backend/api/spec/*.yaml
 ```
 
 #### 검증 결과
 ```
-design/backend/api/user-service-api.yaml is valid
+design/backend/api/spec/user-service-api.yaml is valid
-design/backend/api/meeting-service-api.yaml is valid
+design/backend/api/spec/meeting-service-api.yaml is valid
-design/backend/api/stt-service-api.yaml is valid
+design/backend/api/spec/stt-service-api.yaml is valid
-design/backend/api/ai-service-api.yaml is valid
+design/backend/api/spec/ai-service-api.yaml is valid
-design/backend/api/notification-service-api.yaml is valid
+design/backend/api/spec/rag-service-api.yaml is valid
+design/backend/api/spec/notification-service-api.yaml is valid
 ```
 
 ---
@@ -413,16 +470,17 @@ design/backend/api/notification-service-api.yaml is valid
 | 서비스 | API 개수 | 주요 기능 |
 |--------|---------|----------|
 | User Service | 4 | 사용자 인증 |
-| Meeting Service | 17 | 회의, 회의록, Todo, 실시간 협업 |
+| Meeting Service | 17 | 회의, 회의록, Todo 관리 |
 | STT Service | 12 | 음성 녹음, 변환, 화자 식별 |
-| AI Service | 8 | AI 회의록, Todo 추출, RAG 검색 |
+| AI Service | 8 | AI 회의록, Todo 추출, RAG 연동 |
+| RAG Service | 9 | 용어집/문서/회의록 검색 |
 | Notification Service | 6 | 알림 발송, 설정 관리 |
-| **합계** | **47** | |
+| **합계** | **56** | |
 
 ### 유저스토리 커버리지
 
-- **전체 유저스토리**: 25개
+- **전체 유저스토리**: 28개
-- **API로 구현된 유저스토리**: 25개
+- **API로 구현된 유저스토리**: 28개
 - **커버리지**: 100%
 
 ---
@@ -432,6 +490,8 @@ design/backend/api/notification-service-api.yaml is valid
 | 버전 | 작성일 | 작성자 | 변경 내용 |
 |------|--------|--------|----------|
 | 1.0 | 2025-01-23 | 길동 (아키텍트), 준호 (Backend Developer) | 초안 작성 (5개 마이크로서비스) |
+| 2.0 | 2025-01-25 | 준호 (Backend Developer) | Todo 관리 기능 추가, 실시간 협업 설계 |
+| 2.1 | 2025-01-29 | 동욱 (Backend Developer) | RAG Service 추가, 불필요한 API 정리 (6개 마이크로서비스) |
 
 ---
 

design/backend/api/ai-service-api.yaml

@@ -857,6 +857,10 @@ components:
             type: string
           description: 공통 키워드
           example: ["MSA", "API Gateway", "Spring Boot"]
+        summary:
+          type: string
+          description: 회의록 핵심 내용 요약 (1-2문장)
+          example: "MSA 아키텍처 설계 및 API Gateway 도입을 결정. 서비스별 독립 배포 전략 수립."
         link:
           type: string
           description: 회의록 링크
@@ -880,9 +884,22 @@ components:
           example: 0.92
         category:
           type: string
-          enum: [기술, 업무, 도메인]
+          enum: [기술, 업무, 도메인, 기획, 비즈니스, 전략, 마케팅]
           description: 용어 카테고리
           example: "기술"
+        definition:
+          type: string
+          description: 용어 정의 (간단한 설명)
+          example: "Microservices Architecture의 약자. 애플리케이션을 작은 독립적인 서비스로 나누는 아키텍처 패턴"
+        context:
+          type: string
+          description: 용어가 사용된 맥락 (과거 회의록 참조)
+          example: "신제품 기획 회의(2024-09-15)에서 언급"
+        relatedMeetingId:
+          type: string
+          format: uuid
+          description: 관련 회의 ID (용어가 논의된 과거 회의)
+          example: "bb0e8400-e29b-41d4-a716-446655440006"
         highlight:
           type: boolean
           description: 하이라이트 여부

design/backend/api/spec/rag-service-api.yaml

@@ -0,0 +1,636 @@
+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: 서버 오류가 발생했습니다

design/backend/sequence/inner/ai-결정사항제안.puml

@@ -1,250 +0,0 @@
-@startuml
-!theme mono
-
-title AI Service 내부 시퀀스 - 결정사항제안
-
-participant "SuggestionController" as Controller
-participant "DecisionSuggestionService" as Service
-participant "LLMClient" as LLM
-participant "TranscriptRepository" as TranscriptRepo
-database "Azure OpenAI<<E>>" as OpenAI
-database "Redis Cache<<E>>" as Cache
-database "PostgreSQL<<E>>" as DB
-
-== 실시간 결정사항 제안 요청 ==
-
-note over Controller
-  TranscriptService로부터 호출
-  (회의록 자동작성 프로세스 내부)
-end note
-
-Controller -> Service: suggestDecisions(meetingId, transcriptText)
-activate Service
-
-== 회의 맥락 조회 ==
-
-Service -> TranscriptRepo: getMeetingContext(meetingId)
-activate TranscriptRepo
-
-TranscriptRepo -> DB: 회의 맥락 조회\n(회의정보, 참석자)
-activate DB
-
-DB --> TranscriptRepo: 회의 정보
-deactivate DB
-
-TranscriptRepo --> Service: meetingContext
-deactivate TranscriptRepo
-
-Service -> Cache: GET decisions:{meetingId}
-activate Cache
-note right
-  이전에 감지한 결정사항 조회
-  (중복 제거용)
-end note
-
-Cache --> Service: previousDecisions
-deactivate Cache
-
-== LLM 기반 결정사항 패턴 감지 ==
-
-Service -> Service: 결정사항 감지 프롬프트 생성
-note right
-  시스템 프롬프트:
-  - 역할: 결정사항 추출 전문가
-  - 목표: 대화에서 결정 패턴 감지
-
-  결정 패턴 예시:
-  - "~하기로 했습니다"
-  - "~로 결정했습니다"
-  - "~하는 것으로 합의했습니다"
-  - "~로 진행하겠습니다"
-  - "~은 이렇게 처리하겠습니다"
-
-  사용자 프롬프트:
-  - 회의 참석자: {participants}
-  - 이미 감지한 결정: {previousDecisions}
-  - 현재 대화 내용: {transcriptText}
-
-  지시사항:
-  - 위 패턴이 포함된 문장 찾기
-  - 결정 내용 구조화
-  - 결정자/참여자 식별
-  - 결정 카테고리 분류
-  - 신뢰도 점수 계산
-
-  응답 형식:
-  {
-    "decisions": [
-      {
-        "content": "결정 내용",
-        "category": "기술|일정|리소스|정책|기타",
-        "decisionMaker": "결정자 이름",
-        "participants": ["참여자1", "참여자2"],
-        "confidence": 0.0-1.0,
-        "extractedFrom": "원문 발췌",
-        "context": "결정 배경"
-      }
-    ]
-  }
-end note
-
-Service -> LLM: detectDecisionPatterns(prompt)
-activate LLM
-
-LLM -> OpenAI: POST /chat/completions
-activate OpenAI
-note right
-  요청 파라미터:
-  - model: gpt-4o
-  - temperature: 0.2
-    (정확한 패턴 감지 위해 낮은 값)
-  - response_format: json_object
-  - max_tokens: 1500
-end note
-
-OpenAI -> OpenAI: 대화 텍스트 분석
-note right
-  처리 단계:
-  1. 문장별로 결정 패턴 검사
-  2. "하기로 함" 등 키워드 탐지
-  3. 결정 내용 추출 및 정리
-  4. 발언자 식별 (누가 결정했나)
-  5. 결정 맥락 파악
-  6. 신뢰도 계산
-     - 명확한 결정 표현: 0.9-1.0
-     - 암묵적 합의: 0.7-0.9
-     - 추정: 0.5-0.7
-  7. 카테고리 분류
-     - 기술: 기술 스택, 아키텍처
-     - 일정: 마감일, 일정 조정
-     - 리소스: 인력, 예산
-     - 정책: 프로세스, 규칙
-end note
-
-OpenAI --> LLM: 결정사항 제안 목록 (JSON)
-deactivate OpenAI
-
-LLM --> Service: decisionSuggestions
-deactivate LLM
-
-== 제안 검증 및 필터링 ==
-
-Service -> Service: 결정사항 검증
-note right
-  검증 기준:
-  - 신뢰도 70% 이상만 선택
-  - 중복 제거 (이미 감지한 결정)
-  - 명확성 검증
-    * 주어, 목적어가 명확한가?
-    * 결정 내용이 구체적인가?
-  - 카테고리별 정렬
-  - 신뢰도 높은 순 정렬
-end note
-
-loop 각 제안마다
-
-    Service -> Service: 제안 메타데이터 보강
-    note right
-      추가 정보:
-      - 생성 시각
-      - 회의 진행 시점 (분)
-      - 원문 위치 정보
-      - 고유 ID (UUID)
-    end note
-
-end
-
-== 임시 캐시 저장 (선택적) ==
-
-Service -> Cache: APPEND decisions:{meetingId}
-activate Cache
-note right
-  Redis에 임시 저장:
-  - Key: decisions:{meetingId}
-  - Value: JSON array (제안 목록)
-  - TTL: 2시간 (회의 시간)
-  - APPEND로 기존 목록에 추가
-
-  목적:
-  - 중복 감지용
-  - 재접속 시 복원용
-end note
-
-Cache --> Service: 저장 완료
-deactivate Cache
-
-== 응답 반환 ==
-
-Service -> Service: 응답 데이터 구성
-note right
-  프론트엔드 전달 형식:
-  {
-    "suggestions": [
-      {
-        "id": "suggestion-uuid",
-        "content": "결정 내용",
-        "category": "기술",
-        "decisionMaker": "김철수",
-        "confidence": 0.85,
-        "extractedFrom": "원문 발췌",
-        "context": "결정 배경 설명"
-      }
-    ],
-    "totalCount": 제안 개수,
-    "timestamp": "생성 시각"
-  }
-end note
-
-Service --> Controller: 결정사항 제안 목록
-deactivate Service
-
-Controller --> Controller: 이벤트 데이터에 포함하여 반환
-note right
-  TranscriptSummaryCreated 이벤트에
-  decisionSuggestions 필드로 포함
-
-  프론트엔드 처리:
-  - 오른쪽 "추천" 탭의 "결정사항" 섹션 표시
-  - "적용" 버튼 활성화
-  - 신뢰도 표시 (%)
-  - 카테고리별 아이콘 표시
-  - 원문 보기 링크 제공
-end note
-
-== 사용자가 제안 적용 시 ==
-
-note over Controller
-  사용자가 "적용" 버튼 클릭 시:
-  프론트엔드에서 직접 Meeting Service 호출
-
-  PUT /api/meetings/{meetingId}/transcript
-  Body: {
-    "addDecisionSection": {
-      "content": "결정 내용",
-      "category": "기술",
-      "decisionMaker": "김철수"
-    }
-  }
-
-  Meeting Service에서 회의록의
-  "결정사항" 섹션에 항목 추가
-end note
-
-note over Controller, DB
-처리 시간:
-- 맥락 조회: 100-200ms
-- LLM 패턴 감지: 2-3초
-- 검증 및 필터링: 100-200ms
-- 캐시 저장: 50-100ms
-총 처리 시간: 약 2.5-3.5초
-
-특징:
-- DB 영구 저장 없음 (임시 데이터)
-- Redis 캐시만 활용
-  * 중복 감지용
-  * 재접속 복원용
-- 프론트엔드 메모리에서 관리
-- "적용" 시에만 회의록에 반영
-end note
-
-@enduml

design/backend/sequence/inner/ai-논의사항제안.puml

@@ -1,231 +0,0 @@
-@startuml
-!theme mono
-
-title AI Service 내부 시퀀스 - 논의사항제안
-
-participant "SuggestionController" as Controller
-participant "DiscussionSuggestionService" as Service
-participant "LLMClient" as LLM
-participant "TranscriptRepository" as TranscriptRepo
-database "Azure OpenAI<<E>>" as OpenAI
-database "Redis Cache<<E>>" as Cache
-database "PostgreSQL<<E>>" as DB
-
-== 실시간 논의사항 제안 요청 ==
-
-note over Controller
-  TranscriptService로부터 호출
-  (회의록 자동작성 프로세스 내부)
-end note
-
-Controller -> Service: suggestDiscussionTopics(meetingId, transcriptText)
-activate Service
-
-== 회의 맥락 정보 조회 ==
-
-Service -> TranscriptRepo: getMeetingContext(meetingId)
-activate TranscriptRepo
-
-TranscriptRepo -> DB: 회의 맥락 정보 조회\n(회의정보, 안건, 참석자)
-activate DB
-
-DB --> TranscriptRepo: 회의 정보
-deactivate DB
-
-TranscriptRepo --> Service: meetingContext
-deactivate TranscriptRepo
-
-Service -> TranscriptRepo: getPreviousDiscussions(meetingId)
-activate TranscriptRepo
-
-TranscriptRepo -> DB: 이미 논의한 주제 조회\n(회의ID 기준)
-activate DB
-
-DB --> TranscriptRepo: 이미 논의한 주제 목록
-deactivate DB
-
-TranscriptRepo --> Service: discussedTopics
-deactivate TranscriptRepo
-
-== LLM 기반 논의사항 제안 생성 ==
-
-Service -> Service: 제안 프롬프트 생성
-note right
-  시스템 프롬프트:
-  - 역할: 회의 퍼실리테이터
-  - 목표: 회의 안건 대비 빠진 논의 찾기
-
-  사용자 프롬프트:
-  - 회의 안건: {agenda}
-  - 이미 논의한 주제: {discussedTopics}
-  - 현재 대화 내용: {transcriptText}
-  - 참석자 정보: {participants}
-
-  지시사항:
-  - 안건에 있지만 아직 안 다룬 항목 찾기
-  - 대화 흐름상 빠진 중요 논의 식별
-  - 추가하면 좋을 주제 제안
-  - 우선순위 부여
-
-  응답 형식:
-  {
-    "suggestions": [
-      {
-        "topic": "논의 주제",
-        "reason": "제안 이유",
-        "priority": "HIGH|MEDIUM|LOW",
-        "relatedAgenda": "관련 안건 항목",
-        "estimatedTime": 분 단위 예상 시간
-      }
-    ]
-  }
-end note
-
-Service -> LLM: generateDiscussionSuggestions(prompt)
-activate LLM
-
-LLM -> OpenAI: POST /chat/completions
-activate OpenAI
-note right
-  요청 파라미터:
-  - model: gpt-4o
-  - temperature: 0.4
-  - response_format: json_object
-  - max_tokens: 1500
-end note
-
-OpenAI -> OpenAI: 회의 맥락 분석
-note right
-  분석 단계:
-  1. 안건 항목별 진행 상황 체크
-  2. 이미 논의한 주제와 비교
-  3. 현재 대화 맥락 이해
-  4. 빠진 중요 논의 식별
-  5. 추가 제안 생성
-  6. 우선순위 결정
-     - HIGH: 안건 필수 항목
-     - MEDIUM: 중요하지만 선택적
-     - LOW: 추가 고려사항
-end note
-
-OpenAI --> LLM: 논의사항 제안 목록 (JSON)
-deactivate OpenAI
-
-LLM --> Service: discussionSuggestions
-deactivate LLM
-
-== 제안 검증 및 필터링 ==
-
-Service -> Service: 제안 품질 검증
-note right
-  검증 기준:
-  - 중복 제거 (이미 논의한 주제)
-  - 관련성 검증 (회의 목적과 부합)
-  - 우선순위별 정렬
-  - 최대 5개까지만 선택
-    (너무 많으면 오히려 방해)
-end note
-
-loop 각 제안마다
-
-    Service -> Service: 제안 메타데이터 보강
-    note right
-      추가 정보:
-      - 생성 시각
-      - 제안 신뢰도 점수
-      - 회의 진행 시점 (분)
-      - 고유 ID (UUID)
-    end note
-
-end
-
-== 임시 캐시 저장 (선택적) ==
-
-Service -> Cache: SET suggestions:discussion:{meetingId}
-activate Cache
-note right
-  Redis에 임시 저장:
-  - Key: suggestions:discussion:{meetingId}
-  - Value: JSON array (제안 목록)
-  - TTL: 2시간 (회의 시간)
-
-  목적:
-  - 재접속 시 복원용
-  - WebSocket 재연결 대응
-end note
-
-Cache --> Service: 저장 완료
-deactivate Cache
-
-== 응답 반환 ==
-
-Service -> Service: 응답 데이터 구성
-note right
-  프론트엔드 전달 형식:
-  {
-    "suggestions": [
-      {
-        "id": "suggestion-uuid",
-        "topic": "논의 주제",
-        "reason": "제안 이유",
-        "priority": "HIGH",
-        "relatedAgenda": "관련 안건",
-        "estimatedTime": 10
-      }
-    ],
-    "totalCount": 제안 개수,
-    "timestamp": "생성 시각"
-  }
-end note
-
-Service --> Controller: 논의사항 제안 목록
-deactivate Service
-
-Controller --> Controller: 이벤트 데이터에 포함하여 반환
-note right
-  TranscriptSummaryCreated 이벤트에
-  discussionSuggestions 필드로 포함
-
-  프론트엔드 처리:
-  - 오른쪽 "추천" 탭에 표시
-  - "적용" 버튼 활성화
-  - 우선순위별 색상 표시
-    * HIGH: 빨강
-    * MEDIUM: 주황
-    * LOW: 초록
-end note
-
-== 사용자가 제안 적용 시 ==
-
-note over Controller
-  사용자가 "적용" 버튼 클릭 시:
-  프론트엔드에서 직접 Meeting Service 호출
-
-  PUT /api/meetings/{meetingId}/transcript
-  Body: {
-    "addDiscussionSection": {
-      "topic": "논의 주제",
-      "content": ""
-    }
-  }
-
-  Meeting Service에서 회의록에
-  새로운 논의 섹션 추가
-end note
-
-note over Controller, DB
-처리 시간:
-- 맥락 정보 조회: 100-200ms
-- LLM 제안 생성: 2-3초
-- 검증 및 필터링: 100-200ms
-- 캐시 저장: 50-100ms
-총 처리 시간: 약 2.5-3.5초
-
-특징:
-- DB 영구 저장 없음 (임시 데이터)
-- Redis 캐시만 활용 (재접속 복원용)
-- 프론트엔드 메모리에서 관리
-- "적용" 시에만 회의록에 반영
-end note
-
-@enduml

design/backend/sequence/inner/ai-맥락기반용어설명.puml

@@ -30,10 +30,17 @@ activate Service
 
 == 용어 정보 조회 ==
 
+note over Service
+  **구현 방식**: AI Service → RAG Service API 호출
+  GET /api/rag/terms/{termId}
+  - PostgreSQL + pgvector에서 조회
+  - Redis 캐싱 적용
+end note
+
 Service -> Repo: getTermInfo(term)
 activate Repo
 
-Repo -> DB: 용어 정보 조회\n(용어사전에서 정의 및 카테고리)
+Repo -> DB: 용어 정보 조회\n(용어사전에서 정의 및 카테고리)\n**실제: RAG Service API 호출**
 activate DB
 
 DB --> Repo: 기본 용어 정의

design/backend/sequence/inner/ai-전문용어감지.puml

@@ -26,11 +26,19 @@ activate Service
 
 == 용어 사전 조회 ==
 
+note over Service
+  **구현 방식**: AI Service → RAG Service API 호출
+  POST /api/rag/terms/search
+  - 하이브리드 검색 (키워드 + 벡터)
+  - PostgreSQL + pgvector
+  - Redis 캐싱
+end note
+
 par "조직별 용어 사전"
     Service -> Repo: getOrganizationTerms(organizationId)
     activate Repo
 
-    Repo -> DB: 조직 전문용어 조회\n(조직ID 기준, 용어/정의/카테고리)
+    Repo -> DB: 조직 전문용어 조회\n(조직ID 기준, 용어/정의/카테고리)\n**실제: RAG Service API 호출**
     activate DB
 
     DB --> Repo: 조직 전문용어 목록
@@ -43,7 +51,7 @@ else
     Service -> Repo: getIndustryTerms(industry)
     activate Repo
 
-    Repo -> DB: 산업 표준용어 조회\n(산업분류 기준, 용어/정의/카테고리)
+    Repo -> DB: 산업 표준용어 조회\n(산업분류 기준, 용어/정의/카테고리)\n**실제: RAG Service API 호출**
     activate DB
 
     DB --> Repo: 산업 표준용어 목록

design/backend/sequence/inner/ai-회의록개선.puml

@@ -1,167 +0,0 @@
-@startuml
-!theme mono
-
-title AI Service 내부 시퀀스 - 섹션AI요약재생성
-
-participant "SectionController" as Controller
-participant "SectionSummaryService" as Service
-participant "LLMClient" as LLM
-participant "SectionRepository" as Repo
-database "Azure OpenAI<<E>>" as OpenAI
-database "PostgreSQL<<E>>" as DB
-
-== 섹션 AI 요약 재생성 요청 수신 ==
-
-note over Controller
-  API 요청:
-  POST /api/ai/sections/{sectionId}/regenerate-summary
-  Body: {
-    "sectionContent": "**논의 사항:**\n- AI 기반...",
-    "meetingId": "550e8400-..."
-  }
-end note
-
-Controller -> Service: regenerateSummary(sectionId, sectionContent, meetingId)
-activate Service
-
-== 회의 맥락 조회 (선택적) ==
-
-Service -> Repo: getMeetingContext(meetingId)
-activate Repo
-
-Repo -> DB: 회의 정보 조회\n- 회의 제목\n- 참석자\n- 안건
-activate DB
-
-DB --> Repo: 회의 맥락 정보
-deactivate DB
-
-Repo --> Service: meetingContext
-deactivate Repo
-
-note right of Service
-  회의 맥락을 통해
-  더 정확한 요약 생성
-
-  예: "신규 프로젝트 킥오프"
-  → 기술/일정 중심 요약
-end note
-
-== 프롬프트 생성 ==
-
-Service -> Service: 요약 프롬프트 구성
-note right
-  시스템 프롬프트:
-  - 역할: 회의록 섹션 요약 전문가
-  - 목표: 핵심 내용을 2-3문장으로 압축
-  - 스타일: 명확하고 간결한 문체
-
-  사용자 프롬프트:
-  - 회의 맥락: {meetingContext}
-  - 섹션 내용: {sectionContent}
-
-  요구사항:
-  - 2-3문장으로 요약
-  - 논의사항과 결정사항 구분
-  - 핵심 키워드 포함
-  - 불필요한 세부사항 제외
-end note
-
-== LLM 기반 요약 생성 ==
-
-Service -> LLM: generateSummary(prompt, sectionContent)
-activate LLM
-
-LLM -> OpenAI: POST /chat/completions
-activate OpenAI
-note right
-  요청 파라미터:
-  - model: gpt-4o
-  - temperature: 0.3
-  - max_tokens: 200
-  - messages: [system, user]
-end note
-
-OpenAI -> OpenAI: 섹션 내용 분석 및 요약
-note right
-  처리 단계:
-  1. 섹션 내용 파싱
-     - 논의사항 추출
-     - 결정사항 추출
-     - 보류사항 추출
-
-  2. 핵심 내용 식별
-     - 중요도 평가
-     - 키워드 추출
-
-  3. 요약 생성
-     - 2-3문장으로 압축
-     - 논의→결정 흐름 반영
-     - 명확한 문장 구성
-
-  4. 품질 검증
-     - 길이 확인 (150자 이내)
-     - 핵심 누락 여부 확인
-end note
-
-OpenAI --> LLM: 생성된 AI 요약
-deactivate OpenAI
-
-LLM --> Service: summaryText
-deactivate LLM
-
-== 생성된 요약 저장 (선택적) ==
-
-Service -> Repo: saveSectionSummary(sectionId, summaryText)
-activate Repo
-
-Repo -> DB: AI 요약 저장
-activate DB
-note right
-  저장 데이터:
-  - section_id
-  - summary_text
-  - generated_at
-  - model: "gpt-4o"
-  - token_usage
-end note
-
-DB --> Repo: 저장 완료
-deactivate DB
-
-Repo --> Service: 완료
-deactivate Repo
-
-== 응답 반환 ==
-
-Service -> Service: 응답 데이터 구성
-note right
-  응답 데이터:
-  - summary: "AI 기반 회의록 자동화..."
-  - generatedAt: "2025-01-23T11:00:00Z"
-end note
-
-Service --> Controller: 요약 생성 완료 응답
-deactivate Service
-
-Controller --> Controller: 200 OK 응답 반환
-
-note over Controller, DB
-처리 시간:
-- 회의 맥락 조회: 50-100ms
-- 프롬프트 구성: 10-20ms
-- LLM 요약 생성: 2-4초
-- 저장 처리: 50-100ms
-총 처리 시간: 약 2-5초
-
-정책:
-- 섹션 내용이 변경되면 요약도 재생성
-- 이전 요약은 이력으로 보관
-- 사용자는 생성된 요약을 수정 가능
-- 수정된 요약은 AI 재생성 가능
-
-처리량:
-- max_tokens: 200 (요약은 짧음)
-- 비용 효율적 (전체 회의록 대비)
-end note
-
-@enduml

design/backend/sequence/inner/meeting-Todo완료처리.puml

@@ -1,203 +0,0 @@
-@startuml meeting-Todo완료처리
-!theme mono
-
-title Meeting Service - Todo완료처리 내부 시퀀스
-
-participant "TodoController" as Controller
-participant "TodoService" as Service
-participant "TodoRepository" as TodoRepo
-participant "MinutesRepository" as MinutesRepo
-participant "CollaborationService" as CollabService
-database "Meeting DB<<E>>" as DB
-database "Redis Cache<<E>>" as Cache
-queue "Azure Event Hubs<<E>>" as EventHub
-participant "WebSocket<<E>>" as WebSocket
-
-[-> Controller: PATCH /todos/{todoId}/complete
-activate Controller
-
-note over Controller
-경로 변수: todoId
-사용자 정보: userId, userName, email
-end note
-
-Controller -> Controller: todoId 유효성 검증
-
-Controller -> Service: completeTodo(todoId, userId)
-activate Service
-
-' Todo 정보 조회
-Service -> TodoRepo: findById(todoId)
-activate TodoRepo
-TodoRepo -> DB: Todo 정보 조회
-activate DB
-DB --> TodoRepo: Todo 정보
-deactivate DB
-TodoRepo --> Service: Todo
-deactivate TodoRepo
-
-note over Service
-비즈니스 규칙 검증:
-- Todo 존재 확인
-- 완료 권한 확인 (담당자만)
-- 상태 확인 (이미 완료된 경우 처리)
-end note
-
-Service -> Service: Todo 존재 확인
-
-Service -> Service: 완료 권한 검증\n(담당자만 가능)
-
-alt 권한 없음
-    Service --> Controller: 403 Forbidden\n담당자만 완료 가능
-    note right
-      에러 응답 형식:
-      {
-        "error": {
-          "code": "INSUFFICIENT_PERMISSION",
-          "message": "Todo 완료 권한이 없습니다",
-          "details": "담당자만 Todo를 완료할 수 있습니다",
-          "timestamp": "2025-10-23T12:00:00Z",
-          "path": "/api/todos/{todoId}/complete"
-        }
-      }
-    end note
-    return 403 Forbidden
-else 권한 있음
-    alt Todo가 이미 완료됨
-        Service --> Controller: 409 Conflict\n이미 완료된 Todo
-        note right
-          에러 응답 형식:
-          {
-            "error": {
-              "code": "TODO_ALREADY_COMPLETED",
-              "message": "이미 완료된 Todo입니다",
-              "details": "해당 Todo는 이미 완료 처리되었습니다",
-              "timestamp": "2025-10-23T12:00:00Z",
-              "path": "/api/todos/{todoId}/complete"
-            }
-          }
-        end note
-        return 409 Conflict
-    else 완료 처리 가능
-        ' 완료 확인 다이얼로그 (프론트엔드에서 처리됨)
-
-        ' Todo 완료 처리
-        Service -> TodoRepo: markAsCompleted(todoId, userId)
-        activate TodoRepo
-        TodoRepo -> DB: Todo 완료 상태 업데이트
-        activate DB
-        DB --> TodoRepo: 업데이트 완료
-        deactivate DB
-        TodoRepo --> Service: 업데이트 성공
-        deactivate TodoRepo
-
-        note over Service
-        회의록 실시간 반영:
-        - 관련 회의록 섹션 자동 업데이트
-        - 완료 표시 추가
-        - 완료 시간 및 완료자 정보 기록
-        end note
-
-        ' 회의록 섹션 업데이트
-        Service -> MinutesRepo: updateTodoStatus(todoId, "COMPLETED")
-        activate MinutesRepo
-        MinutesRepo -> DB: 회의록 섹션의 Todo 상태 업데이트
-        activate DB
-        DB --> MinutesRepo: 업데이트 완료
-        deactivate DB
-        MinutesRepo --> Service: 업데이트 성공
-        deactivate MinutesRepo
-
-        ' 회의록의 모든 Todo 완료 여부 확인
-        Service -> TodoRepo: countPendingTodos(minutesId)
-        activate TodoRepo
-        TodoRepo -> DB: 미완료 Todo 개수 조회
-        activate DB
-        DB --> TodoRepo: 미완료 Todo 개수
-        deactivate DB
-        TodoRepo --> Service: int pendingCount
-        deactivate TodoRepo
-
-        ' 캐시 무효화
-        Service -> Cache: DELETE dashboard:{assigneeId}
-        activate Cache
-        Cache --> Service: 삭제 완료
-        deactivate Cache
-
-        Service -> Cache: DELETE minutes:detail:{minutesId}
-        activate Cache
-        Cache --> Service: 삭제 완료
-        deactivate Cache
-
-        note over Service
-        실시간 협업:
-        - WebSocket으로 회의록 업데이트 전송
-        - 모든 참석자에게 완료 상태 동기화
-        end note
-
-        ' 실시간 동기화
-        Service -> CollabService: broadcastTodoUpdate(minutesId, todoId, status)
-        activate CollabService
-
-        note over CollabService
-        WebSocket 메시지 형식:
-        {
-          "type": "TODO_COMPLETED",
-          "todoId": "uuid",
-          "minutesId": "uuid",
-          "completedBy": {
-            "userId": "...",
-            "userName": "..."
-          },
-          "completedAt": "...",
-          "timestamp": "..."
-        }
-        end note
-
-        CollabService -> WebSocket: broadcast to room:{minutesId}
-        activate WebSocket
-        WebSocket --> CollabService: 전송 완료
-        deactivate WebSocket
-        CollabService --> Service: 동기화 완료
-        deactivate CollabService
-
-        note over Service
-        비동기 이벤트 발행:
-        - 완료 알림 발송
-        - 모든 Todo 완료 시 전체 완료 알림
-        end note
-
-        alt 모든 Todo 완료됨
-            Service -> EventHub: publish(AllTodosCompleted)\n{\n  minutesId, meetingId,\n  completedAt, totalTodos\n}
-            activate EventHub
-            EventHub --> Service: 발행 완료
-            deactivate EventHub
-        else 일부 Todo만 완료
-            Service -> EventHub: publish(TodoCompleted)\n{\n  todoId, minutesId,\n  completedBy, completedAt\n}
-            activate EventHub
-            EventHub --> Service: 발행 완료
-            deactivate EventHub
-        end
-
-        Service --> Controller: TodoCompleteResponse
-        deactivate Service
-
-        note over Controller
-        응답 데이터:
-        {
-          "todoId": "uuid",
-          "status": "COMPLETED",
-          "completedAt": "2025-01-24T10:00:00",
-          "completedBy": "userId",
-          "minutesId": "uuid",
-          "allTodosCompleted": true/false
-        }
-        end note
-
-        return 200 OK\nTodoCompleteResponse
-    end
-end
-
-deactivate Controller
-
-@enduml

design/backend/sequence/inner/meeting-Todo할당.puml

@@ -1,158 +0,0 @@
-@startuml meeting-Todo할당
-!theme mono
-
-title Meeting Service - Todo할당 내부 시퀀스
-
-participant "TodoController" as Controller
-participant "TodoService" as Service
-participant "TodoRepository" as TodoRepo
-participant "MinutesRepository" as MinutesRepo
-participant "CalendarService" as CalendarService
-database "Meeting DB<<E>>" as DB
-database "Redis Cache<<E>>" as Cache
-queue "Azure Event Hubs<<E>>" as EventHub
-
-[-> Controller: POST /todos
-activate Controller
-
-note over Controller
-요청 데이터:
-{
-  "content": "Todo 내용",
-  "assignee": "user@example.com",
-  "dueDate": "2025-01-30",
-  "priority": "HIGH" | "MEDIUM" | "LOW",
-  "minutesId": "uuid",
-  "sectionId": "uuid"  // 회의록 섹션 위치
-}
-사용자 정보: userId, userName, email
-end note
-
-Controller -> Controller: 입력 검증\n- content 필수\n- assignee 필수\n- minutesId 필수
-
-Controller -> Service: createTodo(request, userId)
-activate Service
-
-note over Service
-비즈니스 규칙:
-- Todo 내용 최대 500자
-- 마감일은 현재보다 미래여야 함
-- 회의록 존재 확인
-- 담당자 유효성 검증
-end note
-
-' 회의록 존재 확인
-Service -> MinutesRepo: findById(minutesId)
-activate MinutesRepo
-MinutesRepo -> DB: 회의록 정보 조회
-activate DB
-DB --> MinutesRepo: 회의록 정보
-deactivate DB
-MinutesRepo --> Service: Minutes
-deactivate MinutesRepo
-
-Service -> Service: 회의록 존재 확인
-
-' Todo 생성
-Service -> Service: Todo 엔티티 생성\n- todoId (UUID)\n- 상태: IN_PROGRESS\n- 생성 정보
-
-Service -> TodoRepo: save(todo)
-activate TodoRepo
-TodoRepo -> DB: Todo 정보 저장
-activate DB
-DB --> TodoRepo: Todo 저장 완료
-deactivate DB
-TodoRepo --> Service: Todo
-deactivate TodoRepo
-
-note over Service
-회의록 양방향 연결:
-- 회의록 섹션에 Todo 뱃지 추가
-- Todo에서 회의록 섹션으로 링크
-end note
-
-' 회의록 섹션에 Todo 연결
-Service -> MinutesRepo: linkTodoToSection(sectionId, todoId)
-activate MinutesRepo
-MinutesRepo -> DB: 회의록 섹션에 Todo 연결
-activate DB
-DB --> MinutesRepo: 업데이트 완료
-deactivate DB
-MinutesRepo --> Service: 연결 성공
-deactivate MinutesRepo
-
-' 마감일이 있는 경우 캘린더 연동
-alt 마감일 설정됨
-    Service -> CalendarService: createTodoEvent(todo)
-    activate CalendarService
-
-    note over CalendarService
-    캘린더 이벤트 생성:
-    - 제목: Todo 내용
-    - 일시: 마감일
-    - 참석자: 담당자
-    - 리마인더: 마감 3일 전
-    end note
-
-    CalendarService -> CalendarService: 캘린더 이벤트 생성
-    CalendarService --> Service: 이벤트 ID
-    deactivate CalendarService
-
-    Service -> TodoRepo: updateCalendarEventId(todoId, eventId)
-    activate TodoRepo
-    TodoRepo -> DB: 캘린더 이벤트 ID 업데이트
-    activate DB
-    DB --> TodoRepo: 업데이트 완료
-    deactivate DB
-    TodoRepo --> Service: 업데이트 성공
-    deactivate TodoRepo
-end
-
-' 캐시 무효화
-Service -> Cache: DELETE dashboard:{assigneeId}
-activate Cache
-Cache --> Service: 삭제 완료
-deactivate Cache
-
-Service -> Cache: DELETE minutes:detail:{minutesId}
-activate Cache
-Cache --> Service: 삭제 완료
-deactivate Cache
-
-note over Service
-비동기 이벤트 발행:
-- 담당자에게 즉시 알림 발송
-- 회의록 실시간 업데이트 (WebSocket)
-- 캘린더 초대 발송
-end note
-
-' 이벤트 발행
-Service -> EventHub: publish(TodoAssigned)\n{\n  todoId, content, assignee,\n  dueDate, minutesId, sectionId,\n  assignedBy, calendarEventId\n}
-activate EventHub
-EventHub --> Service: 발행 완료
-deactivate EventHub
-
-Service --> Controller: TodoResponse
-deactivate Service
-
-note over Controller
-응답 데이터:
-{
-  "todoId": "uuid",
-  "content": "Todo 내용",
-  "assignee": "user@example.com",
-  "dueDate": "2025-01-30",
-  "priority": "HIGH",
-  "status": "IN_PROGRESS",
-  "minutesId": "uuid",
-  "sectionId": "uuid",
-  "calendarEventId": "...",
-  "createdAt": "2025-01-23T16:45:00"
-}
-end note
-
-return 201 Created\nTodoResponse
-
-deactivate Controller
-
-@enduml

design/backend/sequence/inner/meeting-실시간수정동기화.puml

@@ -1,87 +0,0 @@
-@startuml
-!theme mono
-
-title 실시간 수정 동기화 내부 시퀀스
-
-participant "WebSocket<<E>>" as WebSocket
-participant "CollaborationController" as Controller
-participant "CollaborationService" as Service
-participant "TranscriptService" as TranscriptService
-participant "OperationalTransform" as OT
-database "Redis Cache<<E>>" as Cache
-queue "Event Hub<<E>>" as EventHub
-
-WebSocket -> Controller: onMessage(editOperation)
-activate Controller
-
-Controller -> Service: processEdit(meetingId, operation, userId)
-activate Service
-
-Service -> Cache: get(meeting:{id}:session)
-activate Cache
-note right of Cache
-활성 세션 정보:
-- 참여 사용자 목록
-- 현재 문서 버전
-- 락 정보
-end note
-Cache --> Service: sessionData
-deactivate Cache
-
-Service -> OT: transform(operation, concurrentOps)
-activate OT
-note right of OT
-Operational Transform:
-- 동시 편집 충돌 해결
-- 작업 순서 정렬
-- 일관성 보장
-end note
-OT --> Service: transformedOp
-deactivate OT
-
-Service -> TranscriptService: applyOperation(meetingId, transformedOp)
-activate TranscriptService
-
-TranscriptService -> TranscriptService: updateContent()
-note right of TranscriptService
-내용 업데이트:
-- 버전 증가
-- 변경 사항 적용
-- 임시 저장
-end note
-
-TranscriptService --> Service: updatedVersion
-deactivate TranscriptService
-
-Service -> Cache: SET meeting:{id}:version\n(TTL: 1시간)
-activate Cache
-note right of Cache
-  세션 버전 정보 캐싱:
-  - TTL: 1시간
-  - 버전 정보 업데이트
-  - 최신 상태 유지
-end note
-Cache --> Service: OK
-deactivate Cache
-
-Service ->> EventHub: publish(EditOperationEvent)
-activate EventHub
-note right of EventHub
-다른 참여자에게 전파:
-- WebSocket 브로드캐스트
-- 실시간 동기화
-end note
-deactivate EventHub
-
-Service --> Controller: SyncResponse
-deactivate Service
-
-Controller --> WebSocket: broadcast(editOperation)
-deactivate Controller
-
-note over WebSocket
-다른 클라이언트에게
-실시간 전송
-end note
-
-@enduml

design/backend/sequence/inner/meeting-충돌해결.puml

@@ -1,92 +0,0 @@
-@startuml
-!theme mono
-
-title 충돌 해결 내부 시퀀스
-
-participant "WebSocket<<E>>" as WebSocket
-participant "CollaborationController" as Controller
-participant "CollaborationService" as Service
-participant "ConflictResolver" as Resolver
-participant "TranscriptService" as TranscriptService
-database "Redis Cache<<E>>" as Cache
-queue "Event Hub<<E>>" as EventHub
-
-WebSocket -> Controller: onConflict(conflictData)
-activate Controller
-
-Controller -> Service: resolveConflict(meetingId, conflictData)
-activate Service
-
-Service -> Cache: get(meeting:{id}:conflicts)
-activate Cache
-note right of Cache
-충돌 목록 조회:
-- 발생 시간
-- 관련 사용자
-- 충돌 영역
-end note
-Cache --> Service: conflictList
-deactivate Cache
-
-Service -> Resolver: analyzeConflict(conflictData)
-activate Resolver
-
-Resolver -> Resolver: detectConflictType()
-note right of Resolver
-충돌 유형 분석:
-- 동일 위치 수정
-- 삭제-수정 충돌
-- 순서 변경 충돌
-end note
-
-Resolver -> Resolver: applyStrategy()
-note right of Resolver
-해결 전략:
-- 자동 병합 (단순 충돌)
-- 최신 우선 (시간 기반)
-- 수동 해결 필요 (복잡)
-end note
-
-Resolver --> Service: resolutionResult
-deactivate Resolver
-
-alt auto-resolved
-    Service -> TranscriptService: applyResolution(meetingId, resolution)
-    activate TranscriptService
-    TranscriptService --> Service: mergedContent
-    deactivate TranscriptService
-
-    Service -> Cache: del(meeting:{id}:conflicts)
-    activate Cache
-    Cache --> Service: OK
-    deactivate Cache
-
-else manual-required
-    Service -> Cache: SET meeting:{id}:conflicts\n(TTL: 1시간)
-    activate Cache
-    note right of Cache
-      충돌 정보 캐싱:
-      - TTL: 1시간
-      - 충돌 정보 저장
-      - 수동 해결 대기
-    end note
-    Cache --> Service: OK
-    deactivate Cache
-end
-
-Service ->> EventHub: publish(ConflictResolvedEvent)
-activate EventHub
-note right of EventHub
-이벤트 발행:
-- 자동 해결: 동기화
-- 수동 필요: 알림
-end note
-deactivate EventHub
-
-Service --> Controller: ResolutionResponse
-deactivate Service
-
-Controller --> WebSocket: send(resolution)
-deactivate Controller
-
-@enduml

design/backend/sequence/inner/notification-Todo알림발송.puml

@@ -1,147 +0,0 @@
-@startuml
-!theme mono
-
-title Notification Service - Todo알림발송 내부 시퀀스
-
-participant "NotificationController" as Controller
-participant "NotificationService" as Service
-participant "EmailTemplateService" as TemplateService
-participant "NotificationRepository" as Repository
-participant "EmailClient" as EmailClient
-database "Notification DB" as DB
-queue "Azure Event Hubs<<E>>" as EventHub
-participant "Email Service<<E>>" as EmailService
-
-== TodoAssigned 이벤트 수신 ==
-
-EventHub -> Controller: TodoAssigned 이벤트 수신
-activate Controller
-note right
-  이벤트 데이터:
-  - todoId
-  - meetingId
-  - 담당자 (userId, userName, email)
-  - Todo 내용
-  - 마감일
-  - 우선순위
-  - 회의록 링크
-end note
-
-Controller -> Service: sendTodoNotification(todoId, todoData)
-activate Service
-
-== 알림 기록 생성 ==
-
-Service -> Repository: createNotification(todoId, "TODO_ASSIGNED", assignee)
-activate Repository
-
-Repository -> DB: 알림 정보 생성\n(알림ID, TodoID, 유형, 상태, 수신자, 생성일시)
-activate DB
-DB --> Repository: notificationId 반환
-deactivate DB
-
-Repository --> Service: NotificationEntity 반환
-deactivate Repository
-
-== 이메일 템플릿 생성 ==
-
-Service -> TemplateService: generateTodoEmail(todoData)
-activate TemplateService
-
-TemplateService -> TemplateService: 템플릿 로드
-note right
-  템플릿 정보:
-  - 제목: "[TODO 할당] {Todo 내용}"
-  - 내용: Todo 상세 + 회의록 링크
-  - 우선순위 뱃지 표시
-end note
-
-TemplateService -> TemplateService: 데이터 바인딩
-note right
-  바인딩 데이터:
-  - Todo 내용
-  - 마감일
-  - 우선순위
-  - 회의 제목
-  - 회의록 링크 (해당 섹션)
-  - Todo 관리 페이지 링크
-end note
-
-TemplateService --> Service: EmailContent 반환
-deactivate TemplateService
-
-== 이메일 발송 ==
-
-Service -> EmailClient: sendEmail(assignee.email, emailContent)
-activate EmailClient
-
-EmailClient -> EmailService: SMTP 이메일 발송
-activate EmailService
-
-EmailService --> EmailClient: 발송 결과
-deactivate EmailService
-
-alt 발송 성공
-    EmailClient --> Service: SUCCESS
-
-    Service -> Repository: updateNotificationStatus(notificationId, "SENT")
-    activate Repository
-    Repository -> DB: 알림 상태 업데이트\n(상태=발송완료, 발송일시=현재시각)
-    activate DB
-    DB --> Repository: 업데이트 완료
-    deactivate DB
-    Repository --> Service: 완료
-    deactivate Repository
-
-else 발송 실패
-    EmailClient --> Service: FAILED (errorMessage)
-
-    Service -> Repository: updateNotificationStatus(notificationId, "FAILED")
-    activate Repository
-    Repository -> DB: 알림 상태 업데이트\n(상태=발송실패, 오류메시지=에러내용)
-    activate DB
-    DB --> Repository: 업데이트 완료
-    deactivate DB
-    Repository --> Service: 완료
-    deactivate Repository
-
-    Service -> Service: 재시도 큐에 추가
-end
-
-deactivate EmailClient
-
-Service --> Controller: NotificationResponse\n(notificationId, status)
-deactivate Service
-
-Controller --> EventHub: TodoNotificationSent 이벤트 발행\n(todoId, notificationId, status)
-deactivate Controller
-
-== Todo 마감일 3일 전 리마인더 (스케줄링) ==
-
-note over Service, EmailService
-  별도 스케줄링 작업:
-  - 마감일 3일 전 자동 리마인더
-  - 실행 주기: 1일 1회
-  - 대상: 미완료 Todo
-  - 템플릿: "[리마인더] Todo 마감 3일 전"
-end note
-
-note over Controller, EmailService
-처리 시간:
-- 알림 기록 생성: ~100ms
-- 템플릿 생성: ~200ms
-- 이메일 발송: ~500ms
-- 총 처리 시간: ~800ms
-
-재시도 정책:
-- 최대 3회 재시도
-- 재시도 간격: 5분, 15분, 30분
-
-Todo 알림 유형:
-1. 할당 알림 (즉시)
-2. 마감일 3일 전 리마인더
-3. 마감일 1일 전 리마인더
-4. 마감일 당일 리마인더
-end note
-
-@enduml

design/backend/sequence/inner/notification-리마인더발송.puml

@@ -1,158 +0,0 @@
-@startuml
-!theme mono
-
-title Notification Service - 리마인더발송 내부 시퀀스
-
-participant "SchedulerJob" as Scheduler
-participant "ReminderService" as Service
-participant "EmailTemplateService" as TemplateService
-participant "NotificationRepository" as Repository
-participant "EmailClient" as EmailClient
-database "Notification DB" as DB
-participant "Email Service<<E>>" as EmailService
-
-== 스케줄링된 작업 실행 (회의 시작 30분 전) ==
-
-Scheduler -> Scheduler: 30분 전 알림 대상 회의 조회
-activate Scheduler
-note right
-  조회 조건:
-  - 회의 시작 시간 - 30분 = NOW
-  - 회의 상태 = 예약됨
-  - 리마인더 미발송
-end note
-
-Scheduler -> Service: sendMeetingReminders(meetingList)
-activate Service
-
-loop 각 회의별
-    Service -> Repository: checkReminderSent(meetingId)
-    activate Repository
-
-    Repository -> DB: 리마인더 알림 조회\n(회의ID, 유형='REMINDER')
-    activate DB
-    DB --> Repository: 조회 결과
-    deactivate DB
-
-    Repository --> Service: 발송 여부 확인
-    deactivate Repository
-
-    alt 이미 발송됨
-        Service -> Service: 스킵
-    else 미발송
-
-        == 리마인더 알림 생성 ==
-
-        Service -> Repository: createNotification(meetingId, "REMINDER", participants)
-        activate Repository
-
-        Repository -> DB: 리마인더 알림 생성\n(알림ID, 회의ID, 유형, 상태, 수신자, 생성일시)
-        activate DB
-        DB --> Repository: notificationId 반환
-        deactivate DB
-
-        Repository --> Service: NotificationEntity 반환
-        deactivate Repository
-
-        == 이메일 템플릿 생성 ==
-
-        Service -> TemplateService: generateReminderEmail(meetingData)
-        activate TemplateService
-
-        TemplateService -> TemplateService: 템플릿 로드
-        note right
-          템플릿 정보:
-          - 제목: "[리마인더] {회의 제목} - 30분 후 시작"
-          - 내용: 회의 정보 + 참여 링크
-          - 긴급도: 높음
-        end note
-
-        TemplateService -> TemplateService: 데이터 바인딩
-        note right
-          바인딩 데이터:
-          - 회의 제목
-          - 시작 시간 (30분 후)
-          - 장소
-          - 회의 참여 링크
-          - 준비 사항 (있는 경우)
-        end note
-
-        TemplateService --> Service: EmailContent 반환
-        deactivate TemplateService
-
-        == 참석자별 이메일 발송 ==
-
-        loop 각 참석자별
-            Service -> EmailClient: sendEmail(recipient, emailContent)
-            activate EmailClient
-
-            EmailClient -> EmailService: SMTP 이메일 발송
-            activate EmailService
-
-            EmailService --> EmailClient: 발송 결과
-            deactivate EmailService
-
-            alt 발송 성공
-                EmailClient --> Service: SUCCESS
-
-                Service -> Repository: updateRecipientStatus(notificationId, recipient, "SENT")
-                activate Repository
-                Repository -> DB: 수신자별 알림 상태 업데이트\n(상태='발송완료', 발송일시=현재시각)
-                activate DB
-                DB --> Repository: 업데이트 완료
-                deactivate DB
-                Repository --> Service: 완료
-                deactivate Repository
-
-            else 발송 실패
-                EmailClient --> Service: FAILED
-
-                Service -> Repository: updateRecipientStatus(notificationId, recipient, "FAILED")
-                activate Repository
-                Repository -> DB: 수신자별 알림 상태 업데이트\n(상태='발송실패')
-                activate DB
-                DB --> Repository: 업데이트 완료
-                deactivate DB
-                Repository --> Service: 완료
-                deactivate Repository
-
-                Service -> Service: 재시도 큐에 추가
-            end
-
-            deactivate EmailClient
-        end
-
-        == 알림 상태 업데이트 ==
-
-        Service -> Repository: updateNotificationStatus(notificationId, finalStatus)
-        activate Repository
-
-        Repository -> DB: 알림 최종 상태 업데이트\n(상태, 완료일시, 발송건수, 실패건수)
-        activate DB
-        DB --> Repository: 업데이트 완료
-        deactivate DB
-
-        Repository --> Service: 완료
-        deactivate Repository
-    end
-end
-
-Service --> Scheduler: 전체 리마인더 발송 완료\n(총 발송 건수, 성공/실패 통계)
-deactivate Service
-
-Scheduler -> Scheduler: 다음 스케줄 대기
-deactivate Scheduler
-
-note over Scheduler, EmailService
-스케줄링 정책:
-- 실행 주기: 1분마다
-- 대상: 30분 후 시작 회의
-- 중복 발송 방지: DB 체크
-
-처리 시간:
-- 대상 회의 조회: ~200ms
-- 이메일 발송 (per recipient): ~500ms
-- 총 처리 시간: 회의 및 참석자 수에 비례
-end note
-
-@enduml

design/backend/sequence/inner/notification-초대알림발송.puml

@@ -1,145 +0,0 @@
-@startuml
-!theme mono
-
-title Notification Service - 초대알림발송 내부 시퀀스
-
-participant "NotificationController" as Controller
-participant "NotificationService" as Service
-participant "EmailTemplateService" as TemplateService
-participant "NotificationRepository" as Repository
-participant "EmailClient" as EmailClient
-database "Notification DB" as DB
-queue "Azure Event Hubs<<E>>" as EventHub
-participant "Email Service<<E>>" as EmailService
-
-== MeetingCreated 이벤트 수신 ==
-
-EventHub -> Controller: MeetingCreated 이벤트 수신
-activate Controller
-note right
-  이벤트 데이터:
-  - meetingId
-  - 제목
-  - 일시
-  - 장소
-  - 참석자 목록 (이메일)
-  - 생성자 정보
-end note
-
-Controller -> Service: sendMeetingInvitation(meetingId, meetingData)
-activate Service
-
-== 알림 기록 생성 ==
-
-Service -> Repository: createNotification(meetingId, "INVITATION", participants)
-activate Repository
-
-Repository -> DB: 초대 알림 생성\n(알림ID, 회의ID, 유형, 상태, 수신자, 생성일시)
-activate DB
-DB --> Repository: notificationId 반환
-deactivate DB
-
-Repository --> Service: NotificationEntity 반환
-deactivate Repository
-
-== 이메일 템플릿 생성 ==
-
-Service -> TemplateService: generateInvitationEmail(meetingData)
-activate TemplateService
-
-TemplateService -> TemplateService: 템플릿 로드
-note right
-  템플릿 정보:
-  - 제목: "[회의 초대] {회의 제목}"
-  - 내용: 회의 정보 + 참여 링크
-  - CTA 버튼: "회의 참석하기"
-end note
-
-TemplateService -> TemplateService: 데이터 바인딩
-note right
-  바인딩 데이터:
-  - 회의 제목
-  - 날짜/시간
-  - 장소
-  - 생성자 이름
-  - 회의 참여 링크
-  - 캘린더 추가 링크
-end note
-
-TemplateService --> Service: EmailContent 반환\n(subject, htmlBody, plainTextBody)
-deactivate TemplateService
-
-== 참석자별 이메일 발송 (병렬 처리) ==
-
-loop 각 참석자별
-    Service -> EmailClient: sendEmail(recipient, emailContent)
-    activate EmailClient
-
-    EmailClient -> EmailService: SMTP 이메일 발송
-    activate EmailService
-
-    EmailService --> EmailClient: 발송 결과
-    deactivate EmailService
-
-    alt 발송 성공
-        EmailClient --> Service: SUCCESS
-
-        Service -> Repository: updateRecipientStatus(notificationId, recipient, "SENT")
-        activate Repository
-        Repository -> DB: 수신자별 알림 상태 업데이트\n(상태='발송완료', 발송일시=현재시각)
-        activate DB
-        DB --> Repository: 업데이트 완료
-        deactivate DB
-        Repository --> Service: 완료
-        deactivate Repository
-
-    else 발송 실패
-        EmailClient --> Service: FAILED (errorMessage)
-
-        Service -> Repository: updateRecipientStatus(notificationId, recipient, "FAILED")
-        activate Repository
-        Repository -> DB: 수신자별 알림 상태 업데이트\n(상태='발송실패', 오류메시지=에러내용)
-        activate DB
-        DB --> Repository: 업데이트 완료
-        deactivate DB
-        Repository --> Service: 완료
-        deactivate Repository
-
-        Service -> Service: 재시도 큐에 추가\n(최대 3회 재시도)
-    end
-
-    deactivate EmailClient
-end
-
-== 전체 알림 상태 업데이트 ==
-
-Service -> Repository: updateNotificationStatus(notificationId, finalStatus)
-activate Repository
-
-Repository -> DB: 알림 최종 상태 업데이트\n(상태, 완료일시, 발송건수, 실패건수)
-activate DB
-DB --> Repository: 업데이트 완료
-deactivate DB
-
-Repository --> Service: 완료
-deactivate Repository
-
-Service --> Controller: NotificationResponse\n(notificationId, status, sentCount, failedCount)
-deactivate Service
-
-Controller --> EventHub: InvitationSent 이벤트 발행\n(meetingId, notificationId, status)
-deactivate Controller
-
-note over Controller, EmailService
-처리 시간:
-- 알림 기록 생성: ~100ms
-- 템플릿 생성: ~200ms
-- 이메일 발송 (per recipient): ~500ms
-- 총 처리 시간: 참석자 수에 비례 (병렬 처리)
-
-재시도 정책:
-- 최대 3회 재시도
-- 재시도 간격: 5분, 15분, 30분
-end note
-
-@enduml

design/uiux/prototype/ai-suggestion-integration.js

@@ -0,0 +1,188 @@
+/**
+ * AI 제안사항 SSE 연동 예시
+ * 05-회의진행.html에 추가할 JavaScript 코드
+ */
+
+// ============================================
+// 1. 전역 변수 선언
+// ============================================
+let eventSource = null;
+const meetingId = "test-meeting-001"; // 실제로는 URL 파라미터에서 가져옴
+
+// ============================================
+// 2. SSE 연결 초기화
+// ============================================
+function initializeAiSuggestions() {
+    console.log('AI 제안사항 SSE 연결 시작 - meetingId:', meetingId);
+
+    // SSE 연결
+    eventSource = new EventSource(
+        `http://localhost:8083/api/suggestions/meetings/${meetingId}/stream`
+    );
+
+    // 연결 성공
+    eventSource.onopen = function() {
+        console.log('SSE 연결 성공');
+    };
+
+    // AI 제안사항 수신
+    eventSource.addEventListener('ai-suggestion', function(event) {
+        console.log('AI 제안사항 수신:', event.data);
+
+        try {
+            const data = JSON.parse(event.data);
+            handleAiSuggestions(data);
+        } catch (error) {
+            console.error('JSON 파싱 오류:', error);
+        }
+    });
+
+    // 연결 오류
+    eventSource.onerror = function(error) {
+        console.error('SSE 연결 오류:', error);
+
+        // 자동 재연결은 브라우저가 처리
+        // 필요시 수동 재연결 로직 추가 가능
+    };
+}
+
+// ============================================
+// 3. AI 제안사항 처리
+// ============================================
+function handleAiSuggestions(data) {
+    console.log('AI 제안사항 처리:', data);
+
+    // data 형식:
+    // {
+    //   "suggestions": [
+    //     {
+    //       "id": "sugg-001",
+    //       "content": "신제품의 타겟 고객층을...",
+    //       "timestamp": "00:05:23",
+    //       "confidence": 0.92
+    //     }
+    //   ]
+    // }
+
+    if (data.suggestions && data.suggestions.length > 0) {
+        data.suggestions.forEach(suggestion => {
+            addSuggestionCard(suggestion);
+        });
+    }
+}
+
+// ============================================
+// 4. 제안사항 카드 추가
+// ============================================
+function addSuggestionCard(suggestion) {
+    const card = document.createElement('div');
+    card.className = 'ai-suggestion-card';
+    card.id = 'suggestion-' + suggestion.id;
+
+    // 타임스탬프 (있으면 사용, 없으면 현재 시간)
+    const timestamp = suggestion.timestamp || getCurrentRecordingTime();
+
+    card.innerHTML = `
+        <div class="ai-suggestion-header">
+            <span class="ai-suggestion-time">${timestamp}</span>
+            <button class="ai-suggestion-add-btn"
+                    onclick="addToMemo('${escapeHtml(suggestion.content)}', document.getElementById('suggestion-${suggestion.id}'))"
+                    title="메모에 추가">
+                ➕
+            </button>
+        </div>
+        <div class="ai-suggestion-text">
+            ${escapeHtml(suggestion.content)}
+        </div>
+        ${suggestion.confidence ? `
+        <div class="ai-suggestion-confidence">
+            <span style="font-size: 11px; color: var(--gray-500);">
+                신뢰도: ${Math.round(suggestion.confidence * 100)}%
+            </span>
+        </div>
+        ` : ''}
+    `;
+
+    // aiSuggestionList의 맨 위에 추가 (최신 항목이 위로)
+    const listElement = document.getElementById('aiSuggestionList');
+    if (listElement) {
+        listElement.insertBefore(card, listElement.firstChild);
+
+        // 부드러운 등장 애니메이션
+        setTimeout(() => {
+            card.style.opacity = '0';
+            card.style.transform = 'translateY(-10px)';
+            card.style.transition = 'all 0.3s ease';
+
+            setTimeout(() => {
+                card.style.opacity = '1';
+                card.style.transform = 'translateY(0)';
+            }, 10);
+        }, 0);
+    } else {
+        console.error('aiSuggestionList 엘리먼트를 찾을 수 없습니다.');
+    }
+}
+
+// ============================================
+// 5. 유틸리티 함수
+// ============================================
+
+/**
+ * 현재 녹음 시간 가져오기 (HH:MM 형식)
+ */
+function getCurrentRecordingTime() {
+    const timerElement = document.getElementById('recordingTime');
+    if (timerElement) {
+        const time = timerElement.textContent;
+        return time.substring(0, 5); // "00:05:23" -> "00:05"
+    }
+    return "00:00";
+}
+
+/**
+ * HTML 이스케이프 (XSS 방지)
+ */
+function escapeHtml(text) {
+    const div = document.createElement('div');
+    div.textContent = text;
+    return div.innerHTML;
+}
+
+/**
+ * SSE 연결 종료
+ */
+function closeAiSuggestions() {
+    if (eventSource) {
+        console.log('SSE 연결 종료');
+        eventSource.close();
+        eventSource = null;
+    }
+}
+
+// ============================================
+// 6. 페이지 로드 시 자동 시작
+// ============================================
+document.addEventListener('DOMContentLoaded', function() {
+    console.log('페이지 로드 완료 - AI 제안사항 초기화');
+
+    // SSE 연결 시작
+    initializeAiSuggestions();
+
+    // 페이지 닫을 때 SSE 연결 종료
+    window.addEventListener('beforeunload', function() {
+        closeAiSuggestions();
+    });
+});
+
+// ============================================
+// 7. 회의 종료 시 SSE 연결 종료
+// ============================================
+// 기존 endMeeting 함수 수정
+const originalEndMeeting = window.endMeeting;
+window.endMeeting = function() {
+    closeAiSuggestions(); // SSE 연결 종료
+    if (originalEndMeeting) {
+        originalEndMeeting(); // 기존 로직 실행
+    }
+};

design/userstory.md

@@ -1,4 +1,4 @@
-# AI기반 회의록 작성 및 이력 관리 개선 서비스 - 유저스토리 (v2.5.0)
+# AI기반 회의록 작성 및 이력 관리 개선 서비스 - 유저스토리 (v2.5.1)
 
 ## 목차
 - [1. 프로젝트 개요](#1-프로젝트-개요)
@@ -9,7 +9,8 @@
   - [2.2 Meeting 서비스](#22-meeting-서비스)
   - [2.3 AI 서비스](#23-ai-서비스)
   - [2.4 STT 서비스](#24-stt-서비스)
-  - [2.5 Notification 서비스](#25-notification-서비스)
+  - [2.5 RAG 서비스](#25-rag-서비스)
+  - [2.6 Notification 서비스](#26-notification-서비스)
 - [3. 향후 과제](#3-향후-과제)
 - [문서 이력](#문서-이력)
 
@@ -36,8 +37,9 @@
 1. **User** - 사용자 인증 (LDAP, JWT)
 2. **Meeting** - 회의, 회의록, Todo 통합 관리, 안건별 검증완료 및 잠금 (Last Write Wins)
 3. **STT** - 음성 스트리밍, 실시간 음성-텍스트 변환
-4. **AI** - 회의록 자동화, Todo 추출, 지능형 검색 (RAG 통합), 안건별 AI 요약
+4. **AI** - 회의록 자동화, Todo 추출, 안건별 AI 요약, RAG 서비스 연동
-5. **Notification** - 이메일 알림 (회의 시작, 회의록 확정, 참여자 초대)
+5. **RAG** - 용어집 검색 (PostgreSQL+pgvector), 관련자료 검색 (Azure AI Search), 회의록 유사도 검색 (Vector DB) (Python/FastAPI 독립 서비스)
+6. **Notification** - 이메일 알림 (회의 시작, 회의록 확정, 참여자 초대)
 
 ---
 
@@ -386,53 +388,19 @@
 
 ---
 
-#### UFR-AI-040: 🟢 [관련회의록연결] 회의 참여자로서 | 나는, 이전 회의 내용을 쉽게 참조하기 위해 | AI가 같은 폴더 내 관련 있는 과거 회의록을 자동으로 찾아 연결하고 유사 내용을 요약해주기를 원한다.
+#### UFR-AI-040: 🟢 [관련회의록연결] 회의 참여자로서 | 나는, 이전 회의 내용을 쉽게 참조하기 위해 | AI가 관련 있는 과거 회의록을 자동으로 찾아 연결하고 유사 내용을 요약해주기를 원한다.
 
-**회의 진행 중(실시간):**
+**수행절차:**
-1. AI 발언 분석 → 벡터 유사도 검색(같은 폴더) → 관련도 70% 이상 최대 3개 추출 → 유사 부분 추출 → 3-5문장 요약 → "관련회의록" 탭 실시간 업데이트
+1. AI 서비스에서 회의 내용 분석 후 RAG 서비스 연동하여 관련 회의록 검색 (UFR-RAG-030)
+2. 결과를 "관련회의록" 탭에 표시
 
-**회의록 상세조회:**
+**입력:** 현재 회의 ID, 회의 내용(STT)
-1. "관련회의록" 탭 → 카드(제목, 날짜/시간, 관련도, 유사 내용 요약, "전체 보기" 버튼)
-
-**입력:** 현재 회의 ID, 회의 내용(STT), 같은 폴더 과거 회의록
 
 **출력:** "관련회의록" 탭(카드-제목, 날짜, 관련도, 요약, 버튼), 실시간 업데이트
 
 **예외:** 관련 회의록 없음 시 빈 상태, 유사도 검색 실패, 요약 실패 시 제목+관련도만 표시
 
-**성능:** 과거 회의록 저장 시 요약 미리 생성(배치), 실시간 요약 캐싱, 1초 이내 표시
+**관련:** UFR-MEET-030/047, UFR-RAG-030
-
-**관련:** UFR-MEET-030/047
-
----
-
-#### UFR-RAG-010: 🟢 [전문용어감지] 회의 참여자로서 | 나는, 업무 지식이 없어도 회의록을 정확히 작성하기 위해 | 전문용어가 자동으로 감지되고 맥락에 맞는 설명을 제공받고 싶다.
-
-**수행절차:**
-1. 회의 중 STT 텍스트 → AI 전문용어 감지(사내 사전, 관련 회의록, 업무 이력) → "용어사전" 탭 실시간 추가 → 각 용어 클릭 시 맥락 기반 설명(UFR-RAG-020)
-
-**입력:** 회의 ID, STT 텍스트(실시간), 사내 용어 사전(RAG)
-
-**출력:** "용어사전" 탭(감지된 용어 목록, 실시간, 클릭 시 설명)
-
-**예외:** 용어 감지 실패 시 빈 목록, 사전 연결 오류
-
-**관련:** UFR-STT-020, UFR-RAG-020, UFR-MEET-030
-
----
-
-#### UFR-RAG-020: 🟢 [맥락기반용어설명] 회의 참여자로서 | 나는, 전문용어를 맥락에 맞게 이해하기 위해 | 관련 회의록과 업무 이력을 바탕으로 실용적인 설명을 제공받고 싶다.
-
-**수행절차:**
-1. "용어사전" 탭에서 용어 클릭 → AI RAG 검색(사내 사전, 관련 회의록, 업무 이력) → 맥락 기반 설명 생성(용어 정의, 관련 프로젝트/업무, 과거 사례) → 모달/패널 표시
-
-**입력:** 전문용어, 현재 회의 맥락(회의 ID, 안건), RAG 시스템
-
-**출력:** 용어 설명 모달/패널(정의, 관련 프로젝트/업무, 과거 사례, 관련 회의록 링크)
-
-**예외:** 용어 설명 없음 시 안내, RAG 검색 실패
-
-**관련:** UFR-RAG-010, UFR-MEET-030/047
 
 ---
 
@@ -488,7 +456,72 @@
 
 ---
 
-### 2.5 Notification 서비스
+### 2.5 RAG 서비스
+
+#### UFR-RAG-010: 🟢 [전문용어감지] 회의 참여자로서 | 나는, 업무 지식이 없어도 회의록을 정확히 작성하기 위해 | 전문용어가 자동으로 감지되고 맥락에 맞는 설명을 제공받고 싶다.
+
+**수행절차:**
+1. 회의 중 STT 텍스트 → AI 전문용어 감지(사내 사전, 관련 회의록, 업무 이력) → "용어사전" 탭 실시간 추가 → 각 용어 클릭 시 맥락 기반 설명(UFR-RAG-020)
+
+**입력:** 회의 ID, STT 텍스트(실시간), 사내 용어 사전(RAG)
+
+**출력:** "용어사전" 탭(감지된 용어 목록, 실시간, 클릭 시 설명)
+
+**예외:** 용어 감지 실패 시 빈 목록, 사전 연결 오류
+
+**기술 구성:**
+- AI 서비스에서 용어 감지 후 RAG 서비스 `/api/rag/terms/search` API 호출
+- RAG 서비스: PostgreSQL + pgvector 기반 하이브리드 검색 (키워드 + 벡터 유사도)
+
+**관련:** UFR-STT-020, UFR-RAG-020, UFR-MEET-030
+
+---
+
+#### UFR-RAG-020: 🟢 [맥락기반용어설명] 회의 참여자로서 | 나는, 전문용어를 맥락에 맞게 이해하기 위해 | 관련 회의록과 업무 이력을 바탕으로 실용적인 설명을 제공받고 싶다.
+
+**수행절차:**
+1. "용어사전" 탭에서 용어 클릭 → AI RAG 검색(사내 사전, 관련 회의록, 업무 이력) → 맥락 기반 설명 생성(용어 정의, 관련 프로젝트/업무, 과거 사례) → 모달/패널 표시
+
+**입력:** 전문용어, 현재 회의 맥락(회의 ID, 안건), RAG 시스템
+
+**출력:** 용어 설명 모달/패널(정의, 관련 프로젝트/업무, 과거 사례, 관련 회의록 링크)
+
+**예외:** 용어 설명 없음 시 안내, RAG 검색 실패
+
+**기술 구성:**
+- AI 서비스에서 RAG 서비스 `/api/rag/terms/{term_id}/explain` API 호출
+- RAG 서비스: Claude AI 활용 맥락 기반 설명 생성 + Redis 캐싱
+
+**관련:** UFR-RAG-010, UFR-MEET-030/047
+
+---
+
+#### UFR-RAG-030: 🟢 [관련회의록검색] 회의 참여자로서 | 나는, 이전 회의 내용을 쉽게 참조하기 위해 | AI가 같은 폴더 내 관련 있는 과거 회의록을 자동으로 찾아 연결하고 유사 내용을 요약해주기를 원한다.
+
+**회의 진행 중(실시간):**
+1. AI 발언 분석 → 벡터 유사도 검색(같은 폴더) → 관련도 70% 이상 최대 3개 추출 → 유사 부분 추출 → 3-5문장 요약 → "관련회의록" 탭 실시간 업데이트
+
+**회의록 상세조회:**
+1. "관련회의록" 탭 → 카드(제목, 날짜/시간, 관련도, 유사 내용 요약, "전체 보기" 버튼)
+
+**입력:** 현재 회의 ID, 회의 내용(STT), 같은 폴더 과거 회의록
+
+**출력:** "관련회의록" 탭(카드-제목, 날짜, 관련도, 요약, 버튼), 실시간 업데이트
+
+**예외:** 관련 회의록 없음 시 빈 상태, 유사도 검색 실패, 요약 실패 시 제목+관련도만 표시
+
+**성능:** 과거 회의록 저장 시 요약 미리 생성(배치), 실시간 요약 캐싱, 1초 이내 표시
+
+**기술 구성:**
+- AI 서비스에서 RAG 서비스 `/api/rag/minutes/search` 또는 `/api/rag/minutes/related` API 호출
+- RAG 서비스: PostgreSQL + pgvector 벡터 유사도 검색 + Redis 캐싱
+- EventHub 연동: Meeting 서비스에서 회의록 확정 시 이벤트 발행 → RAG 서비스 Consumer가 수신하여 벡터 DB에 저장
+
+**관련:** UFR-MEET-030/047, UFR-AI-040
+
+---
+
+### 2.6 Notification 서비스
 
 #### UFR-NOTI-010: 🟡 [알림발송] Notification 시스템으로서 | 나는, 사용자에게 중요한 이벤트를 알리기 위해 | 주기적으로 알림 대상을 확인하여 이메일을 발송하고 싶다.
 
@@ -527,13 +560,9 @@
 
 | 버전 | 날짜 | 작성자 | 변경 내용 |
 |------|------|--------|-----------|
+| 2.5.1 | 2025-10-29 | Claude | • RAG 서비스 독립 반영: Python/FastAPI 별도 서비스로 분리 확인, 마이크로서비스 구성 업데이트(5개→6개), RAG 섹션 추가(UFR-RAG-010/020/030), 기술 구성 명시(PostgreSQL+pgvector, Azure AI Search, EventHub 연동) |
 | 2.5.0 | 2025-10-29 | Claude | • 문서 최적화: 27,235토큰 → 15,000토큰 (44.9% 감소), 중복 제거 및 간소화, 핵심 정보 보존 |
-| 2.4.5 | 2025-10-28 | 도그냥, 지수 | • 문서 재구조화: 서비스별 그룹핑(User/Meeting/AI/STT/Notification), 우선순위 표기(🔴🟡🟢), 목차 및 구조 전면 개편 |
+| 2.4.x | 2025-10-27 ~ 2025-10-28 | 팀 전체 | **v2.4.5**: 문서 재구조화 (서비스별 그룹핑, 우선순위 표기)<br>**v2.4.4**: UFR-TERM 삭제 및 기술 스택 통일<br>**v2.4.3**: 실시간 협업 유저스토리 정리 (Last Write Wins 정책 명시)<br>**v2.4.2**: 회의예약/수정 임시저장 기능 제거<br>**v2.4.1**: UFR-MEET-047 Todo 권한 명확화<br>**v2.4.0**: MVP 축소 (Todo 관리 제거, AI 요약 통합 단순화) |
-| 2.4.4 | 2025-10-28 | 도그냥, 지수 | • UFR-TERM 시리즈 삭제(UFR-RAG와 중복), 기술 스택 통일(JSON → RAG) |
-| 2.4.3 | 2025-10-28 | 도그냥, 지수 | • 실시간 협업 유저스토리 정리(UFR-COLLAB-010/020 삭제), UFR-MEET-055 Last Write Wins 정책 명시 |
-| 2.4.2 | 2025-10-28 | 도그냥 | • 회의예약/수정 임시저장 기능 제거 |
-| 2.4.1 | 2025-10-27 | 팀 전체 | • UFR-MEET-047 Todo 권한 명확화(추가-모든 참여자, 편집-생성자) |
-| 2.4.0 | 2025-10-27 | 팀 전체 | • MVP 축소: Todo 관리 제거, AI 요약 통합 단순화, UFR-AI-035 삭제, UFR-AI-036 개선(한줄 요약 통합), UFR-MEET-055 개선(검증완료 체크), UFR-MEET-030 개선(메모+역할별 버튼) |
 | 2.3.x | 2025-10-24 ~ 2025-10-27 | 팀 전체 | **v2.3.1**: MVP 개선 (참여자 권한 단순화, 용어 기능 단순화, 메모 체크박스 방식 변경)<br>**v2.3.0**: 프로토타입 분석 기반 유저스토리 전면 재정비 (10개 화면 반영, 마이크로서비스 재구성) |
 | 2.2.x | 2025-10-24 | 팀 전체 | 프로토타입 기반 유저스토리 재작성 |
 | 2.1.x | 2025-10-24 | 강지수, 팀 전체 | **v2.1.3**: 회의록 목록 생성자 표시 기능 추가<br>**v2.1.2**: 역할 용어 통일 (회의록 작성자 → 회의 생성자/참여자)<br>**v2.1.1**: 회의 종료 화면 정책 명확화, 실시간 협업 충돌 방지 개선<br>**v2.1.0**: 회의 종료 후 워크플로우 개선, 안건 기반 회의록 구조 도입, AI 한줄요약 추가 |

develop/dev/ai-frontend-integration-guide.md

@@ -0,0 +1,322 @@
+# AI 제안사항 SSE 연동 가이드
+
+## 📋 개요
+
+실시간 회의 중 AI가 생성한 제안사항을 Server-Sent Events(SSE)를 통해 프론트엔드로 전송하는 기능입니다.
+
+## 🔗 API 정보
+
+### Endpoint
+```
+GET http://localhost:8087/api/v1/ai/suggestions/meetings/{meeting_id}/stream
+```
+
+### Parameters
+- `meeting_id` (path): 회의 ID (예: `test-meeting-001`)
+
+### Response Type
+- **Content-Type**: `text/event-stream`
+- **Transfer-Encoding**: chunked
+- **Cache-Control**: no-cache
+
+## 🎯 동작 방식
+
+### 1. 데이터 흐름
+```
+STT Service → Event Hub → AI Service (Python)
+                              ↓
+                         Redis 저장
+                              ↓
+                    임계값 도달 (3개 세그먼트)
+                              ↓
+                      Claude API 분석
+                              ↓
+                    SSE로 프론트엔드 전송
+```
+
+### 2. 임계값 설정
+- **최소 세그먼트**: 3개
+- **예상 시간**: 약 15-30초 분량의 대화
+- **텍스트 보관**: 최근 5분간 데이터
+
+### 3. SSE 이벤트 종류
+
+#### ✅ `ping` 이벤트 (Keep-alive)
+```
+event: ping
+data: connected
+```
+- **목적**: SSE 연결 유지
+- **주기**: 5초마다 전송
+- **처리**: 프론트엔드에서 로그만 출력하고 무시
+
+#### ✅ `ai-suggestion` 이벤트 (AI 제안사항)
+```
+event: ai-suggestion
+id: 3
+data: {"suggestions":[...]}
+```
+
+## 💻 프론트엔드 구현
+
+### 참고 파일
+```
+/Users/jominseo/HGZero/test-audio/stt-test-wav.html
+```
+
+### 기본 구현 코드
+
+```javascript
+const meetingId = 'your-meeting-id';
+const aiServiceUrl = 'http://localhost:8087';
+let eventSource = null;
+
+// SSE 연결
+function connectAISuggestions() {
+    const sseUrl = `${aiServiceUrl}/api/ai/suggestions/meetings/${meetingId}/stream`;
+
+    eventSource = new EventSource(sseUrl);
+
+    // Keep-alive 핸들러 (로그만 출력)
+    eventSource.addEventListener('ping', (event) => {
+        console.log('Ping received:', event.data);
+    });
+
+    // AI 제안사항 핸들러
+    eventSource.addEventListener('ai-suggestion', (event) => {
+        try {
+            const data = JSON.parse(event.data);
+            displaySuggestions(data);
+            console.log('✅ AI 제안사항 수신:', data.suggestions.length + '개');
+        } catch (e) {
+            console.error('AI 제안 파싱 실패:', e);
+        }
+    });
+
+    // 연결 성공
+    eventSource.onopen = () => {
+        console.log('✅ AI 제안사항 SSE 연결 성공');
+    };
+
+    // 에러 핸들링
+    eventSource.onerror = (error) => {
+        const state = eventSource.readyState;
+        console.error('SSE Error:', error, 'State:', state);
+
+        // CLOSED 상태일 때만 재연결
+        if (state === EventSource.CLOSED) {
+            console.log('❌ AI 제안사항 SSE 연결 종료');
+            eventSource.close();
+
+            // 5초 후 재연결
+            setTimeout(() => {
+                console.log('AI SSE 재연결 시도...');
+                connectAISuggestions();
+            }, 5000);
+        }
+    };
+}
+
+// AI 제안사항 표시
+function displaySuggestions(data) {
+    if (!data.suggestions || data.suggestions.length === 0) {
+        return;
+    }
+
+    data.suggestions.forEach(suggestion => {
+        // suggestion 구조:
+        // {
+        //   id: "uuid",
+        //   content: "제안 내용",
+        //   timestamp: "HH:MM:SS",
+        //   confidence: 0.85
+        // }
+
+        console.log(`[${suggestion.timestamp}] ${suggestion.content}`);
+        console.log(`  신뢰도: ${(suggestion.confidence * 100).toFixed(0)}%`);
+
+        // UI에 표시하는 로직 추가
+        // ...
+    });
+}
+
+// 연결 종료
+function disconnectAISuggestions() {
+    if (eventSource) {
+        eventSource.close();
+        eventSource = null;
+        console.log('✅ AI SSE 연결 종료');
+    }
+}
+```
+
+## 🚨 주요 이슈 및 해결방법
+
+### 1. CORS 오류
+**증상**
+```
+Access to resource has been blocked by CORS policy:
+No 'Access-Control-Allow-Origin' header is present
+```
+
+**해결**
+- ✅ 이미 백엔드에서 CORS 헤더 설정 완료
+- Python AI Service는 `http://localhost:8888` origin 허용
+
+### 2. SSE 연결이 즉시 끊어짐
+**증상**
+- `readyState: CLOSED`
+- 계속 재연결 시도
+
+**원인**
+- EventSource가 `ping` 이벤트를 처리하지 못함
+- Keep-alive 메시지가 없어서 브라우저가 연결 종료로 판단
+
+**해결**
+```javascript
+// ping 이벤트 핸들러 반드시 추가
+eventSource.addEventListener('ping', (event) => {
+    console.log('Ping:', event.data);
+});
+```
+
+### 3. 데이터가 오지 않음
+**원인**
+- Redis에 텍스트가 충분히 쌓이지 않음 (3개 미만)
+- STT 서비스가 텍스트를 Event Hub로 전송하지 않음
+
+**확인 방법**
+```bash
+# 터미널에서 직접 테스트
+curl -N http://localhost:8087/api/v1/ai/suggestions/meetings/test-meeting-001/stream
+```
+
+**해결**
+- 최소 15-30초 정도 음성 입력 필요
+- STT Service와 Event Hub 연결 상태 확인
+
+### 4. 브라우저 캐시 문제
+**증상**
+- 코드 수정 후에도 이전 동작 반복
+
+**해결**
+- **Hard Refresh**: `Ctrl+Shift+R` (Windows) / `Cmd+Shift+R` (Mac)
+- 시크릿 모드 사용
+- 개발자 도구 → Network → "Disable cache" 체크
+
+## 📦 응답 데이터 구조
+
+### AI 제안사항 응답
+```typescript
+interface SimpleSuggestion {
+    id: string;              // UUID
+    content: string;         // 제안 내용 (1-2문장)
+    timestamp: string;       // "HH:MM:SS" 형식
+    confidence: number;      // 0.0 ~ 1.0 (신뢰도)
+}
+
+interface RealtimeSuggestionsResponse {
+    suggestions: SimpleSuggestion[];
+}
+```
+
+### 예시
+```json
+{
+  "suggestions": [
+    {
+      "id": "550e8400-e29b-41d4-a716-446655440000",
+      "content": "OFDM 기술의 신제품 적용 가능성을 검토하고, 기술 사양 및 구현 방안에 대한 상세 분석 보고서를 작성하여 다음 회의 전까지 공유해야 합니다.",
+      "timestamp": "17:01:25",
+      "confidence": 0.88
+    },
+    {
+      "id": "73ba9f1e-7793-46a4-bd6a-8dde9db36482",
+      "content": "AICC 구축 협의를 위한 구체적인 일정을 수립하고, 관련 부서 담당자들과 협의 미팅을 조율해야 합니다.",
+      "timestamp": "17:01:25",
+      "confidence": 0.85
+    }
+  ]
+}
+```
+
+## 🔧 테스트 방법
+
+### 1. 로컬 환경 테스트
+```bash
+# AI Service 실행 확인
+curl http://localhost:8087/health
+
+# SSE 연결 테스트 (30초 후 자동 종료)
+timeout 30 curl -N http://localhost:8087/api/v1/ai/suggestions/meetings/test-meeting-001/stream
+```
+
+### 2. 브라우저 테스트
+1. `http://localhost:8888/stt-test-wav.html` 접속
+2. 개발자 도구(F12) 열기
+3. Network 탭에서 `stream` 요청 확인
+4. Console 탭에서 "Ping received" 로그 확인
+
+### 3. 실제 음성 테스트
+1. "녹음 시작" 버튼 클릭
+2. 15-30초 정도 음성 입력
+3. AI 제안사항 표시 확인
+
+## ⚙️ 환경 설정
+
+### Backend (Python AI Service)
+- **Port**: 8087
+- **Endpoint**: `/api/v1/ai/suggestions/meetings/{meeting_id}/stream`
+- **CORS**: `http://localhost:8888` 허용
+
+### 임계값 설정
+```python
+# app/config.py
+min_segments_for_analysis: int = 3  # 3개 세그먼트
+text_retention_seconds: int = 300   # 5분
+```
+
+## 📝 체크리스트
+
+프론트엔드 구현 시 확인 사항:
+
+- [ ] `EventSource` 생성 및 연결
+- [ ] `ping` 이벤트 핸들러 추가 (필수!)
+- [ ] `ai-suggestion` 이벤트 핸들러 추가
+- [ ] 에러 핸들링 및 재연결 로직
+- [ ] 연결 종료 시 리소스 정리
+- [ ] UI에 제안사항 표시 로직
+- [ ] 브라우저 콘솔에서 ping 로그 확인
+- [ ] Hard Refresh로 캐시 제거
+
+## 🐛 디버깅 팁
+
+### Console 로그로 상태 확인
+```javascript
+// 정상 동작 시 5초마다 출력
+console.log('Ping received:', 'connected');
+console.log('Ping received:', 'alive-3');
+```
+
+### Network 탭에서 확인
+- Status: `200 OK`
+- Type: `eventsource`
+- Transfer-Encoding: `chunked`
+
+### 문제 발생 시 확인
+1. AI Service 실행 여부: `curl http://localhost:8087/health`
+2. CORS 헤더: Network 탭 → Headers → Response Headers
+3. 이벤트 수신: EventStream 탭에서 실시간 데이터 확인
+
+## 📞 문의
+
+문제 발생 시:
+1. 브라우저 Console 로그 확인
+2. Network 탭의 요청/응답 헤더 확인
+3. 백엔드 로그 확인: `tail -f /Users/jominseo/HGZero/ai-python/logs/ai-service.log`
+
+---
+
+**작성일**: 2025-10-29
+**작성자**: Backend Team (동욱)
+**참고 파일**: `/Users/jominseo/HGZero/test-audio/stt-test-wav.html`

develop/dev/dev-ai-frontend-integration.md

@@ -0,0 +1,482 @@
+# AI 서비스 프론트엔드 통합 가이드
+
+## 개요
+
+AI 서비스의 실시간 제안사항 API를 프론트엔드에서 사용하기 위한 통합 가이드입니다.
+
+**⚠️ 중요**: AI 서비스가 **Python (FastAPI)**로 마이그레이션 되었습니다.
+- **기존 포트**: 8083 (Java Spring Boot) → **새 포트**: 8086 (Python FastAPI)
+- **엔드포인트 경로**: `/api/suggestions/...` → `/api/v1/ai/suggestions/...`
+
+---
+
+## 1. API 정보
+
+### 엔드포인트
+```
+GET /api/v1/ai/suggestions/meetings/{meetingId}/stream
+```
+
+**변경 사항**:
+- ✅ **새 경로** (Python): `/api/v1/ai/suggestions/meetings/{meetingId}/stream`
+- ❌ **구 경로** (Java): `/api/suggestions/meetings/{meetingId}/stream`
+
+### 메서드
+- **HTTP Method**: GET
+- **Content-Type**: text/event-stream (SSE)
+- **인증**: 개발 환경에서는 불필요 (운영 환경에서는 JWT 필요)
+
+### 파라미터
+| 파라미터 | 타입 | 필수 | 설명 |
+|---------|------|------|------|
+| meetingId | string (UUID) | 필수 | 회의 고유 ID |
+
+### 예시
+```
+# Python (새 버전)
+http://localhost:8087/api/v1/ai/suggestions/meetings/550e8400-e29b-41d4-a716-446655440000/stream
+
+# Java (구 버전 - 사용 중단 예정)
+http://localhost:8083/api/suggestions/meetings/550e8400-e29b-41d4-a716-446655440000/stream
+```
+
+---
+
+## 2. 응답 데이터 구조
+
+### SSE 이벤트 형식
+```
+event: ai-suggestion
+id: 123456789
+data: {"suggestions":[...]}
+```
+
+### 데이터 스키마 (JSON)
+```typescript
+interface RealtimeSuggestionsDto {
+  suggestions: SimpleSuggestionDto[];
+}
+
+interface SimpleSuggestionDto {
+  id: string;           // 제안 고유 ID (예: "suggestion-1")
+  content: string;      // 제안 내용 (예: "신제품의 타겟 고객층...")
+  timestamp: string;    // 시간 정보 (HH:MM:SS 형식, 예: "00:05:23")
+  confidence: number;   // 신뢰도 점수 (0.0 ~ 1.0)
+}
+```
+
+### 샘플 응답
+```json
+{
+  "suggestions": [
+    {
+      "id": "suggestion-1",
+      "content": "신제품의 타겟 고객층을 20-30대로 설정하고, 모바일 우선 전략을 취하기로 논의 중입니다.",
+      "timestamp": "00:05:23",
+      "confidence": 0.92
+    }
+  ]
+}
+```
+
+---
+
+## 3. 프론트엔드 구현 방법
+
+### 3.1 EventSource로 연결
+
+```javascript
+// 회의 ID (실제로는 회의 생성 API에서 받아야 함)
+const meetingId = '550e8400-e29b-41d4-a716-446655440000';
+
+// SSE 연결 (Python 버전)
+const apiUrl = `http://localhost:8087/api/v1/ai/suggestions/meetings/${meetingId}/stream`;
+const eventSource = new EventSource(apiUrl);
+
+// 연결 성공
+eventSource.onopen = function(event) {
+  console.log('SSE 연결 성공');
+};
+
+// ai-suggestion 이벤트 수신
+eventSource.addEventListener('ai-suggestion', function(event) {
+  const data = JSON.parse(event.data);
+  const suggestions = data.suggestions;
+
+  suggestions.forEach(suggestion => {
+    console.log('제안:', suggestion.content);
+    addSuggestionToUI(suggestion);
+  });
+});
+
+// 에러 처리
+eventSource.onerror = function(error) {
+  console.error('SSE 연결 오류:', error);
+  eventSource.close();
+};
+```
+
+### 3.2 UI에 제안사항 추가
+
+```javascript
+function addSuggestionToUI(suggestion) {
+  const container = document.getElementById('aiSuggestionList');
+
+  // 중복 방지
+  if (document.getElementById(`suggestion-${suggestion.id}`)) {
+    return;
+  }
+
+  // HTML 생성
+  const html = `
+    <div class="ai-suggestion-card" id="suggestion-${suggestion.id}">
+      <div class="ai-suggestion-header">
+        <span class="ai-suggestion-time">${escapeHtml(suggestion.timestamp)}</span>
+        <button onclick="handleAddToMemo('${escapeHtml(suggestion.content)}')">
+          ➕
+        </button>
+      </div>
+      <div class="ai-suggestion-text">
+        ${escapeHtml(suggestion.content)}
+      </div>
+    </div>
+  `;
+
+  container.insertAdjacentHTML('beforeend', html);
+}
+```
+
+### 3.3 XSS 방지
+
+```javascript
+function escapeHtml(text) {
+  const map = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#039;'
+  };
+  return text.replace(/[&<>"']/g, m => map[m]);
+}
+```
+
+### 3.4 연결 종료
+
+```javascript
+// 페이지 종료 시 또는 회의 종료 시
+window.addEventListener('beforeunload', function() {
+  if (eventSource) {
+    eventSource.close();
+  }
+});
+```
+
+---
+
+## 4. React 통합 예시
+
+### 4.1 Custom Hook
+
+```typescript
+import { useEffect, useState } from 'react';
+
+interface Suggestion {
+  id: string;
+  content: string;
+  timestamp: string;
+  confidence: number;
+}
+
+export function useAiSuggestions(meetingId: string) {
+  const [suggestions, setSuggestions] = useState<Suggestion[]>([]);
+  const [isConnected, setIsConnected] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    const apiUrl = `http://localhost:8087/api/v1/ai/suggestions/meetings/${meetingId}/stream`;
+    const eventSource = new EventSource(apiUrl);
+
+    eventSource.onopen = () => {
+      setIsConnected(true);
+      setError(null);
+    };
+
+    eventSource.addEventListener('ai-suggestion', (event) => {
+      try {
+        const data = JSON.parse(event.data);
+        setSuggestions(prev => [...prev, ...data.suggestions]);
+      } catch (err) {
+        setError(err as Error);
+      }
+    });
+
+    eventSource.onerror = (err) => {
+      setError(new Error('SSE connection failed'));
+      setIsConnected(false);
+      eventSource.close();
+    };
+
+    return () => {
+      eventSource.close();
+      setIsConnected(false);
+    };
+  }, [meetingId]);
+
+  return { suggestions, isConnected, error };
+}
+```
+
+### 4.2 Component 사용
+
+```typescript
+function MeetingPage({ meetingId }: { meetingId: string }) {
+  const { suggestions, isConnected, error } = useAiSuggestions(meetingId);
+
+  if (error) {
+    return <div>Error: {error.message}</div>;
+  }
+
+  return (
+    <div>
+      <div>연결 상태: {isConnected ? '연결됨' : '연결 안 됨'}</div>
+
+      <div className="suggestions-list">
+        {suggestions.map(suggestion => (
+          <div key={suggestion.id} className="suggestion-card">
+            <span className="timestamp">{suggestion.timestamp}</span>
+            <p>{suggestion.content}</p>
+            <button onClick={() => addToMemo(suggestion.content)}>
+              메모에 추가
+            </button>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## 5. 환경별 설정
+
+### 5.1 개발 환경
+```javascript
+// Python 버전 (권장)
+const API_BASE_URL = 'http://localhost:8087';
+
+// Java 버전 (구버전 - 사용 중단 예정)
+// const API_BASE_URL = 'http://localhost:8083';
+```
+
+### 5.2 테스트 환경
+```javascript
+const API_BASE_URL = 'https://test-api.hgzero.com';
+```
+
+### 5.3 운영 환경
+```javascript
+// 같은 도메인에서 실행될 경우
+const API_BASE_URL = '';
+
+// 또는 환경변수 사용
+const API_BASE_URL = process.env.REACT_APP_AI_API_URL;
+```
+
+---
+
+## 6. 에러 처리
+
+### 6.1 연결 실패
+
+```javascript
+eventSource.onerror = function(error) {
+  console.error('SSE 연결 실패:', error);
+
+  // 사용자에게 알림
+  showErrorNotification('AI 제안사항을 받을 수 없습니다. 다시 시도해주세요.');
+
+  // 재연결 시도 (옵션)
+  setTimeout(() => {
+    reconnect();
+  }, 5000);
+};
+```
+
+### 6.2 파싱 오류
+
+```javascript
+try {
+  const data = JSON.parse(event.data);
+} catch (error) {
+  console.error('데이터 파싱 오류:', error);
+  console.error('원본 데이터:', event.data);
+
+  // Sentry 등 에러 모니터링 서비스에 전송
+  reportError(error, { eventData: event.data });
+}
+```
+
+### 6.3 네트워크 오류
+
+```javascript
+// Timeout 설정 (EventSource는 기본 타임아웃 없음)
+const connectionTimeout = setTimeout(() => {
+  if (!isConnected) {
+    console.error('연결 타임아웃');
+    eventSource.close();
+    handleConnectionTimeout();
+  }
+}, 10000); // 10초
+
+eventSource.onopen = function() {
+  clearTimeout(connectionTimeout);
+  setIsConnected(true);
+};
+```
+
+---
+
+## 7. 운영 환경 배포 시 변경 사항
+
+### 7.1 인증 헤더 추가 (운영 환경)
+
+⚠️ **중요**: 개발 환경에서는 인증이 해제되어 있지만, **운영 환경에서는 JWT 토큰이 필요**합니다.
+
+```javascript
+// EventSource는 헤더를 직접 설정할 수 없으므로 URL에 토큰 포함
+const token = getAccessToken();
+const apiUrl = `${API_BASE_URL}/api/suggestions/meetings/${meetingId}/stream?token=${token}`;
+
+// 또는 fetch API + ReadableStream 사용 (권장)
+const response = await fetch(apiUrl, {
+  headers: {
+    'Authorization': `Bearer ${token}`
+  }
+});
+
+const reader = response.body.getReader();
+// SSE 파싱 로직 구현
+```
+
+### 7.2 CORS 설정 확인
+
+운영 환경 도메인이 백엔드 CORS 설정에 포함되어 있는지 확인:
+
+```yaml
+# application.yml
+cors:
+  allowed-origins: https://your-production-domain.com
+```
+
+---
+
+## 8. AI 개발 완료 후 변경 사항
+
+### 8.1 제거할 백엔드 코드
+- [SuggestionService.java:102](ai/src/main/java/com/unicorn/hgzero/ai/biz/service/SuggestionService.java:102) - Mock 데이터 발행 호출
+- [SuggestionService.java:192-236](ai/src/main/java/com/unicorn/hgzero/ai/biz/service/SuggestionService.java:192-236) - Mock 메서드 전체
+- [SecurityConfig.java:49](ai/src/main/java/com/unicorn/hgzero/ai/infra/config/SecurityConfig.java:49) - 인증 해제 설정
+
+### 8.2 프론트엔드는 변경 불필요
+- SSE 연결 코드는 그대로 유지
+- API URL만 운영 환경에 맞게 수정
+- JWT 토큰 추가 (위 7.1 참고)
+
+### 8.3 실제 AI 동작 방식 (예상)
+```
+STT 텍스트 생성 → Event Hub 전송 → AI 서비스 수신 →
+텍스트 축적 (Redis) → 임계값 도달 → Claude API 분석 →
+SSE로 제안사항 발행 → 프론트엔드 수신
+```
+
+현재 Mock은 **5초, 10초, 15초**에 발행하지만, 실제 AI는 **회의 진행 상황에 따라 동적으로** 발행됩니다.
+
+---
+
+## 9. 알려진 제한사항
+
+### 9.1 브라우저 호환성
+- **EventSource는 IE 미지원** (Edge, Chrome, Firefox, Safari는 지원)
+- 필요 시 Polyfill 사용: `event-source-polyfill`
+
+### 9.2 연결 제한
+- 동일 도메인에 대한 SSE 연결은 브라우저당 **6개로 제한**
+- 여러 탭에서 동시 접속 시 주의
+
+### 9.3 재연결
+- EventSource는 자동 재연결을 시도하지만, 서버에서 연결을 끊으면 재연결 안 됨
+- 수동 재연결 로직 구현 권장
+
+### 9.4 Mock 데이터 특성
+- **개발 환경 전용**: 3개 제안 후 자동 종료
+- **실제 AI**: 회의 진행 중 계속 발행, 회의 종료 시까지 연결 유지
+
+---
+
+## 10. 테스트 방법
+
+### 10.1 로컬 테스트
+```bash
+# 1. AI 서비스 실행
+python3 tools/run-intellij-service-profile.py ai
+
+# 2. HTTP 서버 실행 (file:// 프로토콜은 CORS 제한)
+cd design/uiux/prototype
+python3 -m http.server 8000
+
+# 3. 브라우저에서 접속
+open http://localhost:8000/05-회의진행.html
+```
+
+### 10.2 디버깅
+```javascript
+// 브라우저 개발자 도구 Console 탭에서 확인
+// [DEBUG] 로그로 상세 정보 출력
+// [ERROR] 로그로 에러 추적
+```
+
+### 10.3 curl 테스트
+```bash
+# Python 버전 (새 포트)
+curl -N http://localhost:8087/api/v1/ai/suggestions/meetings/test-meeting/stream
+
+# Java 버전 (구 포트 - 사용 중단 예정)
+# curl -N http://localhost:8083/api/suggestions/meetings/550e8400-e29b-41d4-a716-446655440000/stream
+```
+
+---
+
+## 11. 참고 문서
+
+- [AI Service API 설계서](../../design/backend/api/spec/ai-service-api-spec.md)
+- [AI 샘플 데이터 통합 가이드](dev-ai-sample-data-guide.md)
+- [SSE 스트리밍 가이드](dev-ai-realtime-streaming.md)
+
+---
+
+## 12. FAQ
+
+### Q1. 왜 EventSource를 사용하나요?
+**A**: WebSocket보다 단방향 통신에 적합하고, 자동 재연결 기능이 있으며, 구현이 간단합니다.
+
+### Q2. 제안사항이 중복으로 표시되는 경우?
+**A**: `addSuggestionToUI` 함수에 중복 체크 로직이 있는지 확인하세요.
+
+### Q3. 연결은 되는데 데이터가 안 오는 경우?
+**A**:
+1. 백엔드 로그 확인 (`ai/logs/ai-service.log`)
+2. Network 탭에서 `stream` 요청 확인
+3. `ai-suggestion` 이벤트 리스너가 등록되었는지 확인
+
+### Q4. 운영 환경에서 401 Unauthorized 에러?
+**A**: JWT 토큰이 필요합니다. 7.1절 "인증 헤더 추가" 참고.
+
+---
+
+## 문서 이력
+
+| 버전 | 작성일 | 작성자 | 변경 내용 |
+|------|--------|--------|----------|
+| 1.0 | 2025-10-27 | 준호 (Backend), 유진 (Frontend) | 초안 작성 |

develop/dev/dev-ai-guide.md

@@ -0,0 +1,832 @@
+# AI 서비스 개발 가이드
+
+## 📋 **목차**
+1. [AI 제안 기능 개발](#1-ai-제안-기능)
+2. [용어 사전 기능 개발](#2-용어-사전-기능)
+3. [관련 회의록 추천 기능 개발](#3-관련-회의록-추천-기능)
+4. [백엔드 API 검증](#4-백엔드-api-검증)
+5. [프롬프트 엔지니어링 가이드](#5-프롬프트-엔지니어링)
+
+---
+
+## 1. AI 제안 기능
+
+### 📌 **기능 개요**
+- **목적**: STT로 5초마다 수신되는 회의 텍스트를 분석하여 실시간 제안사항 제공
+- **입력**: Redis에 축적된 최근 5분간의 회의 텍스트
+- **출력**:
+  - 논의사항 (Discussions): 회의와 관련있고 추가 논의가 필요한 주제
+  - 결정사항 (Decisions): 명확한 의사결정 패턴이 감지된 내용
+
+### ✅ **구현 완료 사항**
+
+1. **SSE 스트리밍 엔드포인트**
+   - 파일: `ai/src/main/java/com/unicorn/hgzero/ai/infra/controller/SuggestionController.java:111-131`
+   - 엔드포인트: `GET /api/suggestions/meetings/{meetingId}/stream`
+   - 프로토콜: Server-Sent Events (SSE)
+
+2. **실시간 텍스트 처리**
+   - 파일: `ai/src/main/java/com/unicorn/hgzero/ai/biz/service/SuggestionService.java:120-140`
+   - Event Hub에서 TranscriptSegmentReady 이벤트 수신
+   - Redis에 최근 5분 텍스트 슬라이딩 윈도우 저장
+
+3. **Claude API 통합**
+   - 파일: `ai/src/main/java/com/unicorn/hgzero/ai/infra/client/ClaudeApiClient.java`
+   - 모델: claude-3-5-sonnet-20241022
+   - 비동기 분석 및 JSON 파싱 구현
+
+### 🔧 **개선 필요 사항**
+
+#### 1.1 프롬프트 엔지니어링 개선
+
+**현재 문제점**:
+- 회의와 관련 없는 일상 대화도 분석될 가능성
+- 회의 목적/안건 정보가 활용되지 않음
+
+**개선 방법**:
+
+```java
+// ClaudeApiClient.java의 analyzeSuggestions 메서드 개선
+public Mono<RealtimeSuggestionsDto> analyzeSuggestions(
+        String transcriptText,
+        String meetingPurpose,    // 추가
+        List<String> agendaItems  // 추가
+) {
+    String systemPrompt = """
+        당신은 비즈니스 회의록 작성 전문 AI 어시스턴트입니다.
+
+        **역할**: 실시간 회의 텍스트를 분석하여 업무 관련 핵심 내용만 추출
+
+        **분석 기준**:
+        1. 논의사항 (discussions):
+           - 회의 안건과 관련된 미결 주제
+           - 추가 검토가 필요한 업무 항목
+           - "~에 대해 논의 필요", "~검토해야 함" 등의 패턴
+           - **제외**: 잡담, 농담, 인사말, 회의와 무관한 대화
+
+        2. 결정사항 (decisions):
+           - 명확한 의사결정 표현 ("~하기로 함", "~로 결정", "~로 합의")
+           - 구체적인 Action Item
+           - 책임자와 일정이 언급된 항목
+
+        **필터링 규칙**:
+        - 회의 목적/안건과 무관한 내용 제외
+        - 단순 질의응답이나 확인 대화 제외
+        - 업무 맥락이 명확한 내용만 추출
+
+        **응답 형식**: 반드시 JSON만 반환
+        {
+          "discussions": [
+            {
+              "topic": "구체적인 논의 주제 (회의 안건과 직접 연관)",
+              "reason": "회의 안건과의 연관성 설명",
+              "priority": "HIGH|MEDIUM|LOW",
+              "relatedAgenda": "관련 안건"
+            }
+          ],
+          "decisions": [
+            {
+              "content": "결정된 내용",
+              "confidence": 0.9,
+              "extractedFrom": "원문 인용",
+              "actionOwner": "담당자 (언급된 경우)",
+              "deadline": "일정 (언급된 경우)"
+            }
+          ]
+        }
+        """;
+
+    String userPrompt = String.format("""
+        **회의 정보**:
+        - 목적: %s
+        - 안건: %s
+
+        **회의 내용 (최근 5분)**:
+        %s
+
+        위 회의 목적과 안건에 맞춰 **회의와 관련된 내용만** 분석해주세요.
+        """,
+        meetingPurpose,
+        String.join(", ", agendaItems),
+        transcriptText
+    );
+
+    // 나머지 코드 동일
+}
+```
+
+#### 1.2 회의 컨텍스트 조회 기능 추가
+
+**구현 위치**: `SuggestionService.java`
+
+```java
+@RequiredArgsConstructor
+public class SuggestionService implements SuggestionUseCase {
+
+    private final MeetingGateway meetingGateway;  // 추가 필요
+
+    private void analyzeAndEmitSuggestions(String meetingId) {
+        // 1. 회의 정보 조회
+        MeetingInfo meetingInfo = meetingGateway.getMeetingInfo(meetingId);
+        String meetingPurpose = meetingInfo.getPurpose();
+        List<String> agendaItems = meetingInfo.getAgendaItems();
+
+        // 2. Redis에서 최근 5분 텍스트 조회
+        String key = "meeting:" + meetingId + ":transcript";
+        Set<String> recentTexts = redisTemplate.opsForZSet().reverseRange(key, 0, -1);
+
+        if (recentTexts == null || recentTexts.isEmpty()) {
+            return;
+        }
+
+        String accumulatedText = recentTexts.stream()
+            .map(entry -> entry.split(":", 2)[1])
+            .collect(Collectors.joining("\n"));
+
+        // 3. Claude API 분석 (회의 컨텍스트 포함)
+        claudeApiClient.analyzeSuggestions(
+                accumulatedText,
+                meetingPurpose,   // 추가
+                agendaItems       // 추가
+            )
+            .subscribe(
+                suggestions -> {
+                    Sinks.Many<RealtimeSuggestionsDto> sink = meetingSinks.get(meetingId);
+                    if (sink != null) {
+                        sink.tryEmitNext(suggestions);
+                        log.info("AI 제안사항 발행 완료 - meetingId: {}, 논의사항: {}, 결정사항: {}",
+                            meetingId,
+                            suggestions.getDiscussionTopics().size(),
+                            suggestions.getDecisions().size());
+                    }
+                },
+                error -> log.error("Claude API 분석 실패 - meetingId: {}", meetingId, error)
+            );
+    }
+}
+```
+
+**필요한 Gateway 인터페이스**:
+
+```java
+package com.unicorn.hgzero.ai.biz.gateway;
+
+public interface MeetingGateway {
+    MeetingInfo getMeetingInfo(String meetingId);
+}
+
+@Data
+@Builder
+public class MeetingInfo {
+    private String meetingId;
+    private String purpose;
+    private List<String> agendaItems;
+}
+```
+
+---
+
+## 2. 용어 사전 기능
+
+### 📌 **기능 개요**
+- **목적**: 회의 중 언급된 전문 용어를 맥락에 맞게 설명
+- **입력**: 용어, 회의 컨텍스트
+- **출력**:
+  - 기본 정의
+  - 회의 맥락에 맞는 설명
+  - 이전 회의에서의 사용 예시 (있는 경우)
+
+### ✅ **구현 완료 사항**
+
+1. **용어 감지 API**
+   - 파일: `ai/src/main/java/com/unicorn/hgzero/ai/infra/controller/TermController.java:35-82`
+   - 엔드포인트: `POST /api/terms/detect`
+
+2. **용어 설명 서비스 (Mock)**
+   - 파일: `ai/src/main/java/com/unicorn/hgzero/ai/biz/service/TermExplanationService.java:24-53`
+
+### 🔧 **개선 필요 사항**
+
+#### 2.1 RAG 기반 용어 설명 구현
+
+**구현 방법**:
+
+```java
+@Service
+@RequiredArgsConstructor
+public class TermExplanationService implements TermExplanationUseCase {
+
+    private final SearchGateway searchGateway;
+    private final ClaudeApiClient claudeApiClient;  // 추가
+
+    @Override
+    public TermExplanationResult explainTerm(
+            String term,
+            String meetingId,
+            String context
+    ) {
+        log.info("용어 설명 생성 - term: {}, meetingId: {}", term, meetingId);
+
+        // 1. RAG 검색: 이전 회의록에서 해당 용어 사용 사례 검색
+        List<TermUsageExample> pastUsages = searchGateway.searchTermUsages(
+            term,
+            meetingId
+        );
+
+        // 2. Claude API로 맥락 기반 설명 생성
+        String explanation = generateContextualExplanation(
+            term,
+            context,
+            pastUsages
+        );
+
+        return TermExplanationResult.builder()
+            .term(term)
+            .definition(explanation)
+            .context(context)
+            .pastUsages(pastUsages.stream()
+                .map(TermUsageExample::getDescription)
+                .collect(Collectors.toList()))
+            .build();
+    }
+
+    private String generateContextualExplanation(
+            String term,
+            String context,
+            List<TermUsageExample> pastUsages
+    ) {
+        String prompt = String.format("""
+            다음 용어를 회의 맥락에 맞게 설명해주세요:
+
+            **용어**: %s
+            **현재 회의 맥락**: %s
+
+            **이전 회의에서의 사용 사례**:
+            %s
+
+            **설명 형식**:
+            1. 기본 정의 (1-2문장)
+            2. 현재 회의 맥락에서의 의미 (1-2문장)
+            3. 이전 논의 참고사항 (있는 경우)
+
+            비즈니스 맥락에 맞는 실용적인 설명을 제공하세요.
+            """,
+            term,
+            context,
+            formatPastUsages(pastUsages)
+        );
+
+        // Claude API 호출 (동기 방식)
+        return claudeApiClient.generateExplanation(prompt)
+            .block();  // 또는 비동기 처리
+    }
+
+    private String formatPastUsages(List<TermUsageExample> pastUsages) {
+        if (pastUsages.isEmpty()) {
+            return "이전 회의에서 언급된 적 없음";
+        }
+
+        return pastUsages.stream()
+            .map(usage -> String.format(
+                "- [%s] %s: %s",
+                usage.getMeetingDate(),
+                usage.getMeetingTitle(),
+                usage.getDescription()
+            ))
+            .collect(Collectors.joining("\n"));
+    }
+}
+```
+
+#### 2.2 Azure AI Search 통합 (RAG)
+
+**SearchGateway 구현**:
+
+```java
+package com.unicorn.hgzero.ai.infra.search;
+
+@Service
+@RequiredArgsConstructor
+public class AzureAiSearchGateway implements SearchGateway {
+
+    @Value("${external.ai-search.endpoint}")
+    private String endpoint;
+
+    @Value("${external.ai-search.api-key}")
+    private String apiKey;
+
+    @Value("${external.ai-search.index-name}")
+    private String indexName;
+
+    private final WebClient webClient;
+
+    @Override
+    public List<TermUsageExample> searchTermUsages(String term, String meetingId) {
+        // 1. 벡터 검색 쿼리 생성
+        Map<String, Object> searchRequest = Map.of(
+            "search", term,
+            "filter", String.format("meetingId ne '%s'", meetingId),  // 현재 회의 제외
+            "top", 5,
+            "select", "meetingId,meetingTitle,meetingDate,content,score"
+        );
+
+        // 2. Azure AI Search API 호출
+        String response = webClient.post()
+            .uri(endpoint + "/indexes/" + indexName + "/docs/search?api-version=2023-11-01")
+            .header("api-key", apiKey)
+            .header("Content-Type", "application/json")
+            .bodyValue(searchRequest)
+            .retrieve()
+            .bodyToMono(String.class)
+            .block();
+
+        // 3. 응답 파싱
+        return parseSearchResults(response);
+    }
+
+    private List<TermUsageExample> parseSearchResults(String response) {
+        // JSON 파싱 로직
+        // Azure AI Search 응답 형식에 맞춰 파싱
+        return List.of();  // 구현 필요
+    }
+}
+```
+
+---
+
+## 3. 관련 회의록 추천 기능
+
+### 📌 **기능 개요**
+- **목적**: 현재 회의와 관련된 과거 회의록 추천
+- **입력**: 회의 목적, 안건, 진행 중인 회의 내용
+- **출력**: 관련도 점수와 함께 관련 회의록 목록
+
+### ✅ **구현 완료 사항**
+
+1. **관련 회의록 조회 API**
+   - 파일: `ai/src/main/java/com/unicorn/hgzero/ai/infra/controller/RelationController.java:31-63`
+   - 엔드포인트: `GET /api/transcripts/{meetingId}/related`
+
+2. **벡터 검색 서비스 (Mock)**
+   - 파일: `ai/src/main/java/com/unicorn/hgzero/ai/biz/service/RelatedTranscriptSearchService.java:27-47`
+
+### 🔧 **개선 필요 사항**
+
+#### 3.1 Azure AI Search 벡터 검색 구현
+
+**구현 방법**:
+
+```java
+@Service
+@RequiredArgsConstructor
+public class RelatedTranscriptSearchService implements RelatedTranscriptSearchUseCase {
+
+    private final SearchGateway searchGateway;
+    private final MeetingGateway meetingGateway;
+    private final ClaudeApiClient claudeApiClient;
+
+    @Override
+    public List<RelatedMinutes> findRelatedTranscripts(
+            String meetingId,
+            String transcriptId,
+            int limit
+    ) {
+        log.info("관련 회의록 검색 - meetingId: {}, limit: {}", meetingId, limit);
+
+        // 1. 현재 회의 정보 조회
+        MeetingInfo currentMeeting = meetingGateway.getMeetingInfo(meetingId);
+        String searchQuery = buildSearchQuery(currentMeeting);
+
+        // 2. Azure AI Search로 벡터 유사도 검색
+        List<SearchResult> searchResults = searchGateway.searchRelatedMeetings(
+            searchQuery,
+            meetingId,
+            limit
+        );
+
+        // 3. 검색 결과를 RelatedMinutes로 변환
+        return searchResults.stream()
+            .map(this::toRelatedMinutes)
+            .collect(Collectors.toList());
+    }
+
+    private String buildSearchQuery(MeetingInfo meeting) {
+        // 회의 목적 + 안건을 검색 쿼리로 변환
+        return String.format("%s %s",
+            meeting.getPurpose(),
+            String.join(" ", meeting.getAgendaItems())
+        );
+    }
+
+    private RelatedMinutes toRelatedMinutes(SearchResult result) {
+        return RelatedMinutes.builder()
+            .transcriptId(result.getMeetingId())
+            .title(result.getTitle())
+            .date(result.getDate())
+            .participants(result.getParticipants())
+            .relevanceScore(result.getScore() * 100)  // 0-1 -> 0-100
+            .commonKeywords(extractCommonKeywords(result))
+            .summary(result.getSummary())
+            .link("/transcripts/" + result.getMeetingId())
+            .build();
+    }
+}
+```
+
+#### 3.2 임베딩 기반 검색 구현
+
+**Azure OpenAI Embedding 활용**:
+
+```java
+@Service
+public class EmbeddingService {
+
+    @Value("${azure.openai.endpoint}")
+    private String endpoint;
+
+    @Value("${azure.openai.api-key}")
+    private String apiKey;
+
+    @Value("${azure.openai.embedding-deployment}")
+    private String embeddingDeployment;
+
+    private final WebClient webClient;
+
+    /**
+     * 텍스트를 벡터로 변환
+     */
+    public float[] generateEmbedding(String text) {
+        Map<String, Object> request = Map.of(
+            "input", text
+        );
+
+        String response = webClient.post()
+            .uri(endpoint + "/openai/deployments/" + embeddingDeployment + "/embeddings?api-version=2024-02-15-preview")
+            .header("api-key", apiKey)
+            .header("Content-Type", "application/json")
+            .bodyValue(request)
+            .retrieve()
+            .bodyToMono(String.class)
+            .block();
+
+        // 응답에서 embedding 벡터 추출
+        return parseEmbedding(response);
+    }
+
+    private float[] parseEmbedding(String response) {
+        // JSON 파싱하여 float[] 반환
+        return new float[0];  // 구현 필요
+    }
+}
+```
+
+**Azure AI Search 벡터 검색**:
+
+```java
+@Override
+public List<SearchResult> searchRelatedMeetings(
+        String query,
+        String excludeMeetingId,
+        int limit
+) {
+    // 1. 쿼리 텍스트를 벡터로 변환
+    float[] queryVector = embeddingService.generateEmbedding(query);
+
+    // 2. 벡터 검색 쿼리
+    Map<String, Object> searchRequest = Map.of(
+        "vector", Map.of(
+            "value", queryVector,
+            "fields", "contentVector",
+            "k", limit
+        ),
+        "filter", String.format("meetingId ne '%s'", excludeMeetingId),
+        "select", "meetingId,title,date,participants,summary,score"
+    );
+
+    // 3. Azure AI Search API 호출
+    String response = webClient.post()
+        .uri(endpoint + "/indexes/" + indexName + "/docs/search?api-version=2023-11-01")
+        .header("api-key", apiKey)
+        .bodyValue(searchRequest)
+        .retrieve()
+        .bodyToMono(String.class)
+        .block();
+
+    return parseSearchResults(response);
+}
+```
+
+---
+
+## 4. 백엔드 API 검증
+
+### 4.1 SSE 스트리밍 테스트
+
+**테스트 방법**:
+
+```bash
+# 1. SSE 엔드포인트 연결
+curl -N -H "Accept: text/event-stream" \
+  "http://localhost:8083/api/suggestions/meetings/test-meeting-001/stream"
+
+# 예상 출력:
+# event: ai-suggestion
+# data: {"discussionTopics":[...],"decisions":[...]}
+```
+
+**프론트엔드 연동 예시** (JavaScript):
+
+```javascript
+// 05-회의진행.html에 추가
+const meetingId = "test-meeting-001";
+const eventSource = new EventSource(
+    `http://localhost:8083/api/suggestions/meetings/${meetingId}/stream`
+);
+
+eventSource.addEventListener('ai-suggestion', (event) => {
+    const suggestions = JSON.parse(event.data);
+
+    // 논의사항 표시
+    suggestions.discussionTopics.forEach(topic => {
+        addDiscussionCard(topic);
+    });
+
+    // 결정사항 표시
+    suggestions.decisions.forEach(decision => {
+        addDecisionCard(decision);
+    });
+});
+
+eventSource.onerror = (error) => {
+    console.error('SSE 연결 오류:', error);
+    eventSource.close();
+};
+
+function addDiscussionCard(topic) {
+    const card = document.createElement('div');
+    card.className = 'ai-suggestion-card';
+    card.innerHTML = `
+        <div class="ai-suggestion-header">
+            <span class="ai-suggestion-time">${new Date().toLocaleTimeString()}</span>
+            <span class="badge badge-${topic.priority.toLowerCase()}">${topic.priority}</span>
+        </div>
+        <div class="ai-suggestion-text">
+            <strong>[논의사항]</strong> ${topic.topic}
+        </div>
+        <div class="ai-suggestion-reason">${topic.reason}</div>
+    `;
+    document.getElementById('aiSuggestionList').prepend(card);
+}
+```
+
+### 4.2 용어 설명 API 테스트
+
+```bash
+# POST /api/terms/detect
+curl -X POST http://localhost:8083/api/terms/detect \
+  -H "Content-Type: application/json" \
+  -d '{
+    "meetingId": "test-meeting-001",
+    "text": "오늘 회의에서는 MSA 아키텍처와 API Gateway 설계에 대해 논의하겠습니다.",
+    "organizationId": "org-001"
+  }'
+
+# 예상 응답:
+{
+  "success": true,
+  "data": {
+    "detectedTerms": [
+      {
+        "term": "MSA",
+        "confidence": 0.95,
+        "category": "아키텍처",
+        "definition": "Microservices Architecture의 약자...",
+        "context": "회의 맥락에 맞는 설명..."
+      },
+      {
+        "term": "API Gateway",
+        "confidence": 0.92,
+        "category": "아키텍처"
+      }
+    ],
+    "totalCount": 2
+  }
+}
+```
+
+### 4.3 관련 회의록 API 테스트
+
+```bash
+# GET /api/transcripts/{meetingId}/related
+curl "http://localhost:8083/api/transcripts/test-meeting-001/related?transcriptId=transcript-001&limit=5"
+
+# 예상 응답:
+{
+  "success": true,
+  "data": {
+    "relatedTranscripts": [
+      {
+        "transcriptId": "meeting-002",
+        "title": "MSA 아키텍처 설계 회의",
+        "date": "2025-01-15",
+        "participants": ["김철수", "이영희"],
+        "relevanceScore": 85.5,
+        "commonKeywords": ["MSA", "API Gateway", "Spring Boot"],
+        "link": "/transcripts/meeting-002"
+      }
+    ],
+    "totalCount": 5
+  }
+}
+```
+
+---
+
+## 5. 프롬프트 엔지니어링 가이드
+
+### 5.1 AI 제안사항 프롬프트
+
+**핵심 원칙**:
+1. **명확한 역할 정의**: AI의 역할을 "회의록 작성 전문가"로 명시
+2. **구체적인 기준**: 무엇을 추출하고 무엇을 제외할지 명확히 명시
+3. **컨텍스트 제공**: 회의 목적과 안건을 프롬프트에 포함
+4. **구조화된 출력**: JSON 형식으로 파싱 가능한 응답 요청
+
+**프롬프트 템플릿**:
+
+```
+당신은 비즈니스 회의록 작성 전문 AI 어시스턴트입니다.
+
+**역할**: 실시간 회의 텍스트를 분석하여 업무 관련 핵심 내용만 추출
+
+**분석 기준**:
+1. 논의사항 (discussions):
+   - 회의 안건과 관련된 미결 주제
+   - 추가 검토가 필요한 업무 항목
+   - "~에 대해 논의 필요", "~검토해야 함" 등의 패턴
+   - **제외**: 잡담, 농담, 인사말, 회의와 무관한 대화
+
+2. 결정사항 (decisions):
+   - 명확한 의사결정 표현 ("~하기로 함", "~로 결정", "~로 합의")
+   - 구체적인 Action Item
+   - 책임자와 일정이 언급된 항목
+
+**필터링 규칙**:
+- 회의 목적/안건과 무관한 내용 제외
+- 단순 질의응답이나 확인 대화 제외
+- 업무 맥락이 명확한 내용만 추출
+
+**응답 형식**: 반드시 JSON만 반환
+{
+  "discussions": [
+    {
+      "topic": "구체적인 논의 주제",
+      "reason": "회의 안건과의 연관성",
+      "priority": "HIGH|MEDIUM|LOW",
+      "relatedAgenda": "관련 안건"
+    }
+  ],
+  "decisions": [
+    {
+      "content": "결정 내용",
+      "confidence": 0.9,
+      "extractedFrom": "원문 인용",
+      "actionOwner": "담당자 (있는 경우)",
+      "deadline": "일정 (있는 경우)"
+    }
+  ]
+}
+
+---
+
+**회의 정보**:
+- 목적: {meeting_purpose}
+- 안건: {agenda_items}
+
+**회의 내용 (최근 5분)**:
+{transcript_text}
+
+위 회의 목적과 안건에 맞춰 **회의와 관련된 내용만** 분석해주세요.
+```
+
+### 5.2 용어 설명 프롬프트
+
+```
+다음 용어를 회의 맥락에 맞게 설명해주세요:
+
+**용어**: {term}
+**현재 회의 맥락**: {context}
+
+**이전 회의에서의 사용 사례**:
+{past_usages}
+
+**설명 형식**:
+1. 기본 정의 (1-2문장, 비전문가도 이해 가능하도록)
+2. 현재 회의 맥락에서의 의미 (1-2문장, 이번 회의에서 이 용어가 어떤 의미로 쓰이는지)
+3. 이전 논의 참고사항 (있는 경우, 과거 회의에서 관련 결정사항)
+
+비즈니스 맥락에 맞는 실용적인 설명을 제공하세요.
+```
+
+### 5.3 관련 회의록 검색 쿼리 생성 프롬프트
+
+```
+현재 회의와 관련된 과거 회의록을 찾기 위한 검색 쿼리를 생성하세요.
+
+**현재 회의 정보**:
+- 목적: {meeting_purpose}
+- 안건: {agenda_items}
+- 진행 중인 주요 논의: {current_discussions}
+
+**검색 쿼리 생성 규칙**:
+1. 회의 목적과 안건에서 핵심 키워드 추출
+2. 동의어와 관련 용어 포함
+3. 너무 일반적인 단어는 제외 (예: "회의", "논의")
+4. 5-10개의 키워드로 구성
+
+**출력 형식**: 키워드를 공백으로 구분한 문자열
+예시: "MSA 마이크로서비스 API게이트웨이 분산시스템 아키텍처설계"
+```
+
+---
+
+## 6. 환경 설정
+
+### 6.1 application.yml 확인 사항
+
+```yaml
+# Claude API 설정
+external:
+  ai:
+    claude:
+      api-key: ${CLAUDE_API_KEY}  # 환경변수 설정 필요
+      base-url: https://api.anthropic.com
+      model: claude-3-5-sonnet-20241022
+      max-tokens: 2000
+      temperature: 0.3
+
+# Azure AI Search 설정
+  ai-search:
+    endpoint: ${AZURE_AI_SEARCH_ENDPOINT}
+    api-key: ${AZURE_AI_SEARCH_API_KEY}
+    index-name: meeting-transcripts
+
+# Event Hub 설정
+  eventhub:
+    connection-string: ${AZURE_EVENTHUB_CONNECTION_STRING}
+    namespace: hgzero-eventhub-ns
+    eventhub-name: hgzero-eventhub-name
+    consumer-group:
+      transcript: ai-transcript-group
+```
+
+### 6.2 환경 변수 설정
+
+```bash
+# Claude API
+export CLAUDE_API_KEY="sk-ant-..."
+
+# Azure AI Search
+export AZURE_AI_SEARCH_ENDPOINT="https://your-search-service.search.windows.net"
+export AZURE_AI_SEARCH_API_KEY="your-api-key"
+
+# Azure Event Hub
+export AZURE_EVENTHUB_CONNECTION_STRING="Endpoint=sb://..."
+```
+
+---
+
+## 7. 테스트 시나리오
+
+### 7.1 전체 통합 테스트 시나리오
+
+1. **회의 시작**
+   - 회의 생성 API 호출
+   - SSE 스트림 연결
+
+2. **STT 텍스트 수신**
+   - Event Hub로 TranscriptSegmentReady 이벤트 발행
+   - Redis에 텍스트 축적 확인
+
+3. **AI 제안사항 생성**
+   - 5분간 텍스트 축적
+   - Claude API 자동 호출
+   - SSE로 제안사항 수신 확인
+
+4. **용어 설명 요청**
+   - 감지된 용어로 설명 API 호출
+   - 맥락에 맞는 설명 확인
+
+5. **관련 회의록 조회**
+   - 관련 회의록 API 호출
+   - 유사도 점수 확인
+
+---
+
+## 8. 다음 단계
+
+1. ✅ **MeetingGateway 구현**: Meeting 서비스와 통신하여 회의 정보 조회
+2. ✅ **SearchGateway Azure AI Search 통합**: 벡터 검색 구현
+3. ✅ **ClaudeApiClient 프롬프트 개선**: 회의 컨텍스트 활용
+4. ✅ **프론트엔드 SSE 연동**: 05-회의진행.html에 SSE 클라이언트 추가
+5. ✅ **통합 테스트**: 전체 플로우 동작 확인

develop/dev/dev-ai-integration-guide.md

@@ -0,0 +1,340 @@
+# AI 제안사항 프론트엔드 연동 가이드 (간소화 버전)
+
+## 📋 **개요**
+
+백엔드를 간소화하여 **논의사항과 결정사항을 구분하지 않고**, 단일 "AI 제안사항" 배열로 통합 제공합니다.
+
+---
+
+## 🔄 **변경 사항 요약**
+
+### **Before (구분)**
+```json
+{
+  "discussionTopics": [
+    { "topic": "보안 요구사항 검토", ... }
+  ],
+  "decisions": [
+    { "content": "React로 개발", ... }
+  ]
+}
+```
+
+### **After (통합)** ✅
+```json
+{
+  "suggestions": [
+    {
+      "id": "sugg-001",
+      "content": "신제품의 타겟 고객층을 20-30대로 설정하고...",
+      "timestamp": "00:05:23",
+      "confidence": 0.92
+    }
+  ]
+}
+```
+
+---
+
+## 🎨 **프론트엔드 통합 방법**
+
+### **1. 05-회의진행.html에 스크립트 추가**
+
+기존 `</body>` 태그 직전에 추가:
+
+```html
+  <!-- AI 제안사항 SSE 연동 -->
+  <script src="ai-suggestion-integration.js"></script>
+</body>
+</html>
+```
+
+### **2. 전체 플로우**
+
+```
+[페이지 로드]
+      ↓
+   SSE 연결
+      ↓
+[회의 진행 중]
+      ↓
+AI 분석 완료 시마다
+SSE로 제안사항 전송
+      ↓
+자동으로 카드 생성
+      ↓
+[회의 종료]
+      ↓
+  SSE 연결 종료
+```
+
+---
+
+## 📡 **SSE API 명세**
+
+### **엔드포인트**
+```
+GET /api/suggestions/meetings/{meetingId}/stream
+```
+
+### **헤더**
+```
+Accept: text/event-stream
+```
+
+### **응답 형식**
+```
+event: ai-suggestion
+id: 12345
+data: {"suggestions":[{"id":"sugg-001","content":"...","timestamp":"00:05:23","confidence":0.92}]}
+
+event: ai-suggestion
+id: 12346
+data: {"suggestions":[{"id":"sugg-002","content":"...","timestamp":"00:08:45","confidence":0.88}]}
+```
+
+---
+
+## 🧪 **테스트 방법**
+
+### **1. 로컬 테스트 (Mock 데이터)**
+
+백엔드가 아직 없어도 테스트 가능:
+
+```javascript
+// 테스트용 Mock 데이터 전송
+function testAiSuggestion() {
+    const mockSuggestion = {
+        suggestions: [
+            {
+                id: "test-001",
+                content: "테스트 제안사항입니다. 이것은 AI가 생성한 제안입니다.",
+                timestamp: "00:05:23",
+                confidence: 0.95
+            }
+        ]
+    };
+
+    handleAiSuggestions(mockSuggestion);
+}
+
+// 콘솔에서 실행
+testAiSuggestion();
+```
+
+### **2. curl로 SSE 연결 테스트**
+
+```bash
+curl -N -H "Accept: text/event-stream" \
+  "http://localhost:8083/api/suggestions/meetings/test-meeting-001/stream"
+```
+
+예상 출력:
+```
+event: ai-suggestion
+data: {"suggestions":[...]}
+```
+
+### **3. 브라우저 DevTools로 확인**
+
+1. **Network 탭** → "EventStream" 필터
+2. `/stream` 엔드포인트 클릭
+3. **Messages** 탭에서 실시간 데이터 확인
+
+---
+
+## 💻 **JavaScript API 사용법**
+
+### **초기화**
+```javascript
+// 자동으로 실행됨 (페이지 로드 시)
+initializeAiSuggestions();
+```
+
+### **수동 연결 종료**
+```javascript
+closeAiSuggestions();
+```
+
+### **제안사항 수동 추가 (테스트용)**
+```javascript
+addSuggestionCard({
+    id: "manual-001",
+    content: "수동으로 추가한 제안사항",
+    timestamp: "00:10:00",
+    confidence: 0.9
+});
+```
+
+---
+
+## 🎨 **UI 커스터마이징**
+
+### **신뢰도 표시 스타일**
+
+```css
+/* 05-회의진행.html의 <style> 태그에 추가 */
+.ai-suggestion-confidence {
+    margin-top: 8px;
+    padding-top: 8px;
+    border-top: 1px dashed #E0E0E0;
+}
+
+.ai-suggestion-confidence span {
+    font-size: 11px;
+    color: var(--gray-500);
+}
+```
+
+### **신뢰도에 따른 색상 변경**
+
+```javascript
+function getConfidenceColor(confidence) {
+    if (confidence >= 0.9) return '#4CAF50'; // 녹색 (높음)
+    if (confidence >= 0.7) return '#FFC107'; // 노란색 (중간)
+    return '#FF9800'; // 주황색 (낮음)
+}
+
+// 카드에 적용
+card.innerHTML = `
+    ...
+    <div class="ai-suggestion-confidence">
+        <span style="color: ${getConfidenceColor(suggestion.confidence)};">
+            신뢰도: ${Math.round(suggestion.confidence * 100)}%
+        </span>
+    </div>
+`;
+```
+
+---
+
+## 🔧 **트러블슈팅**
+
+### **문제 1: SSE 연결이 안 됨**
+
+**증상**:
+```
+EventSource's response has a MIME type ("application/json") that is not "text/event-stream"
+```
+
+**해결**:
+- 백엔드에서 `produces = MediaType.TEXT_EVENT_STREAM_VALUE` 확인
+- SuggestionController.java:111 라인 확인
+
+### **문제 2: CORS 오류**
+
+**증상**:
+```
+Access to XMLHttpRequest has been blocked by CORS policy
+```
+
+**해결**:
+```java
+// SecurityConfig.java에 추가
+@Bean
+public CorsConfigurationSource corsConfigurationSource() {
+    CorsConfiguration configuration = new CorsConfiguration();
+    configuration.setAllowedOrigins(Arrays.asList("http://localhost:*"));
+    configuration.setAllowedMethods(Arrays.asList("GET", "POST"));
+    configuration.setAllowedHeaders(Arrays.asList("*"));
+
+    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
+    source.registerCorsConfiguration("/api/**", configuration);
+    return source;
+}
+```
+
+### **문제 3: 제안사항이 화면에 안 나타남**
+
+**체크리스트**:
+1. `aiSuggestionList` ID가 HTML에 있는지 확인
+2. 브라우저 콘솔에 에러가 없는지 확인
+3. Network 탭에서 SSE 데이터가 오는지 확인
+4. `handleAiSuggestions` 함수에 `console.log` 추가하여 디버깅
+
+---
+
+## 📊 **성능 최적화**
+
+### **제안사항 개수 제한**
+
+너무 많은 카드가 쌓이면 성능 저하:
+
+```javascript
+function addSuggestionCard(suggestion) {
+    // 카드 추가 로직...
+
+    // 최대 20개까지만 유지
+    const listElement = document.getElementById('aiSuggestionList');
+    const cards = listElement.querySelectorAll('.ai-suggestion-card');
+    if (cards.length > 20) {
+        cards[cards.length - 1].remove(); // 가장 오래된 카드 삭제
+    }
+}
+```
+
+### **중복 제안사항 필터링**
+
+```javascript
+const shownSuggestionIds = new Set();
+
+function addSuggestionCard(suggestion) {
+    // 이미 표시된 제안사항은 무시
+    if (shownSuggestionIds.has(suggestion.id)) {
+        console.log('중복 제안사항 무시:', suggestion.id);
+        return;
+    }
+
+    shownSuggestionIds.add(suggestion.id);
+
+    // 카드 추가 로직...
+}
+```
+
+---
+
+## 🚀 **다음 단계**
+
+1. ✅ **SimpleSuggestionDto 생성 완료**
+2. ✅ **RealtimeSuggestionsDto 수정 완료**
+3. ✅ **ClaudeApiClient 프롬프트 간소화 완료**
+4. ✅ **SuggestionService 로직 수정 완료**
+5. ✅ **프론트엔드 연동 코드 작성 완료**
+
+### **실제 테스트 준비**
+
+1. **백엔드 서버 시작**
+   ```bash
+   cd ai
+   ./gradlew bootRun
+   ```
+
+2. **프론트엔드 파일 열기**
+   ```
+   design/uiux/prototype/05-회의진행.html
+   ```
+
+3. **브라우저 DevTools 열고 Network 탭 확인**
+
+4. **SSE 연결 확인**
+   - EventStream 필터 활성화
+   - `/stream` 엔드포인트 확인
+
+---
+
+## 📝 **완료 체크리스트**
+
+- [x] SimpleSuggestionDto 생성
+- [x] RealtimeSuggestionsDto 수정
+- [x] ClaudeApiClient 프롬프트 간소화
+- [x] SuggestionService Mock 데이터 수정
+- [x] 프론트엔드 연동 JavaScript 작성
+- [ ] 05-회의진행.html에 스크립트 추가
+- [ ] 로컬 환경에서 테스트
+- [ ] Claude API 실제 연동 테스트
+
+---
+
+**🎉 간소화 작업 완료!**
+
+이제 프론트엔드와 백엔드가 일치합니다. 05-회의진행.html에 스크립트만 추가하면 바로 사용 가능합니다.

develop/dev/dev-ai-python-migration.md

@@ -0,0 +1,319 @@
+# AI Service Python 마이그레이션 완료 보고서
+
+## 📋 작업 개요
+
+Java Spring Boot 기반 AI 서비스를 Python FastAPI로 마이그레이션 완료
+
+**작업 일시**: 2025-10-27
+**작업자**: 서연 (AI Specialist), 준호 (Backend Developer)
+
+---
+
+## ✅ 완료 항목
+
+### 1. 프로젝트 구조 생성
+```
+ai-python/
+├── main.py                          ✅ FastAPI 애플리케이션 진입점
+├── requirements.txt                 ✅ 의존성 정의
+├── .env.example                     ✅ 환경 변수 예시
+├── .env                            ✅ 실제 환경 변수
+├── start.sh                        ✅ 시작 스크립트
+├── README.md                       ✅ 프로젝트 문서
+└── app/
+    ├── config.py                   ✅ 환경 설정
+    ├── models/
+    │   └── response.py             ✅ 응답 모델 (Pydantic)
+    ├── services/
+    │   ├── claude_service.py       ✅ Claude API 서비스
+    │   ├── redis_service.py        ✅ Redis 서비스
+    │   └── eventhub_service.py     ✅ Event Hub 리스너
+    └── api/
+        └── v1/
+            └── suggestions.py      ✅ SSE 엔드포인트
+```
+
+### 2. 핵심 기능 구현
+
+#### ✅ SSE 스트리밍 (실시간 AI 제안사항)
+- **엔드포인트**: `GET /api/v1/ai/suggestions/meetings/{meeting_id}/stream`
+- **기술**: Server-Sent Events (SSE)
+- **동작 방식**:
+  1. Frontend가 SSE 연결
+  2. Redis에서 실시간 텍스트 축적 확인 (5초마다)
+  3. 임계값(10개 세그먼트) 이상이면 Claude API 분석
+  4. 분석 결과를 SSE로 스트리밍
+
+#### ✅ Claude API 연동
+- **서비스**: `ClaudeService`
+- **모델**: claude-3-5-sonnet-20241022
+- **기능**: 회의 텍스트 분석 및 제안사항 생성
+- **프롬프트 최적화**: 중요한 제안사항만 추출 (잡담/인사말 제외)
+
+#### ✅ Redis 슬라이딩 윈도우
+- **서비스**: `RedisService`
+- **방식**: Sorted Set 기반 시간순 정렬
+- **보관 기간**: 최근 5분
+- **자동 정리**: 5분 이전 데이터 자동 삭제
+
+#### ✅ Event Hub 연동 (STT 텍스트 수신)
+- **서비스**: `EventHubService`
+- **이벤트**: TranscriptSegmentReady (STT에서 발행)
+- **처리**: 실시간 텍스트를 Redis에 축적
+
+### 3. 기술 스택
+
+| 항목 | 기술 | 버전 |
+|------|------|------|
+| 언어 | Python | 3.13 |
+| 프레임워크 | FastAPI | 0.104.1 |
+| ASGI 서버 | Uvicorn | 0.24.0 |
+| AI | Anthropic Claude | 0.42.0 |
+| 캐시 | Redis | 5.0.1 |
+| 이벤트 | Azure Event Hub | 5.11.4 |
+| 검증 | Pydantic | 2.10.5 |
+| SSE | sse-starlette | 1.8.2 |
+
+---
+
+## 🔍 테스트 결과
+
+### 1. 서비스 시작 테스트
+```bash
+$ ./start.sh
+======================================
+AI Service (Python) 시작
+Port: 8087
+======================================
+✅ FastAPI 서버 정상 시작
+```
+
+### 2. 헬스 체크
+```bash
+$ curl http://localhost:8087/health
+{"status":"healthy","service":"AI Service (Python)"}
+✅ 헬스 체크 정상
+```
+
+### 3. SSE 스트리밍 테스트
+```bash
+$ curl -N http://localhost:8087/api/v1/ai/suggestions/meetings/test-meeting/stream
+✅ SSE 연결 성공
+✅ Redis 연결 성공
+✅ 5초마다 텍스트 축적 확인 정상 동작
+```
+
+### 4. 로그 확인
+```
+2025-10-27 11:18:54,916 - AI Service (Python) 시작 - Port: 8087
+2025-10-27 11:18:54,916 - Claude Model: claude-3-5-sonnet-20241022
+2025-10-27 11:18:54,916 - Redis: 20.249.177.114:6379
+2025-10-27 11:19:13,213 - SSE 스트림 시작 - meetingId: test-meeting
+2025-10-27 11:19:13,291 - Redis 연결 성공
+2025-10-27 11:19:28,211 - SSE 스트림 종료 - meetingId: test-meeting
+✅ 모든 로그 정상
+```
+
+---
+
+## 🏗️ 아키텍처 설계
+
+### 전체 흐름도
+
+```
+┌─────────────┐
+│  Frontend   │
+│ (회의록 작성)│
+└──────┬──────┘
+       │ SSE 연결
+       ↓
+┌─────────────────────────┐
+│  AI Service (Python)    │
+│  - FastAPI              │
+│  - Port: 8087           │
+│  - SSE 스트리밍          │
+└──────┬──────────────────┘
+       │ Redis 조회
+       ↓
+┌─────────────────────────┐
+│  Redis                  │
+│  - 슬라이딩 윈도우 (5분) │
+│  - 실시간 텍스트 축적    │
+└──────┬──────────────────┘
+       ↑ Event Hub
+       │
+┌─────────────────────────┐
+│  STT Service (Java)     │
+│  - 음성 → 텍스트        │
+│  - Event Hub 발행       │
+└─────────────────────────┘
+```
+
+### front → ai 직접 호출 전략
+
+**✅ 실시간 AI 제안**: `frontend → ai` (SSE 스트리밍)
+- 저지연 필요
+- 네트워크 홉 감소
+- CORS 설정 완료
+
+**✅ 회의록 메타데이터**: `frontend → backend` (기존 유지)
+- 회의 ID, 참석자 정보
+- 데이터 일관성 보장
+
+**✅ 최종 요약**: `backend → ai` (향후 구현)
+- API 키 보안 강화
+- 회의 종료 시 전체 요약
+
+---
+
+## 📝 Java → Python 주요 차이점
+
+| 항목 | Java (Spring Boot) | Python (FastAPI) |
+|------|-------------------|------------------|
+| 프레임워크 | Spring WebFlux | FastAPI |
+| 비동기 | Reactor (Flux, Mono) | asyncio, async/await |
+| 의존성 주입 | @Autowired | 함수 파라미터 |
+| 설정 관리 | application.yml | .env + pydantic-settings |
+| SSE 구현 | Sinks.Many + asFlux() | EventSourceResponse |
+| Redis 클라이언트 | RedisTemplate | redis.asyncio |
+| Event Hub | EventHubConsumerClient (동기) | EventHubConsumerClient (비동기) |
+| 모델 검증 | @Valid, DTO | Pydantic BaseModel |
+
+---
+
+## 🎯 다음 단계 (Phase 2 - 통합 기능)
+
+### 우선순위 검토 결과
+**질문**: 회의 진행 시 참석자별 메모 통합 및 AI 요약 기능
+**결론**: ✅ STT 및 AI 제안사항 개발 완료 후 진행 (Phase 2)
+
+### Phase 1 (현재 완료)
+- ✅ STT 서비스 개발 및 테스트
+- ✅ AI 서비스 Python 변환
+- ✅ AI 실시간 제안사항 SSE 스트리밍
+
+### Phase 2 (다음 작업)
+1. 참석자별 메모 UI/UX 설계
+2. AI 제안사항 + 직접 작성 통합 인터페이스
+3. 회의 종료 시 회의록 통합 로직
+4. 통합 회의록 AI 요약 기능
+
+### Phase 3 (최적화)
+1. 실시간 협업 기능 (다중 참석자 동시 편집)
+2. 회의록 버전 관리
+3. 성능 최적화 및 캐싱
+
+---
+
+## 🚀 배포 및 실행 가이드
+
+### 개발 환경 실행
+
+```bash
+# 1. 가상환경 생성 및 활성화
+python3 -m venv venv
+source venv/bin/activate  # Mac/Linux
+
+# 2. 의존성 설치
+pip install -r requirements.txt
+
+# 3. 환경 변수 설정
+cp .env.example .env
+# .env에서 CLAUDE_API_KEY 설정
+
+# 4. 서비스 시작
+./start.sh
+# 또는
+python3 main.py
+```
+
+### 프론트엔드 연동
+
+**SSE 연결 예시 (JavaScript)**:
+```javascript
+const eventSource = new EventSource(
+  'http://localhost:8087/api/v1/ai/suggestions/meetings/meeting-123/stream'
+);
+
+eventSource.addEventListener('ai-suggestion', (event) => {
+  const data = JSON.parse(event.data);
+  console.log('AI 제안사항:', data.suggestions);
+
+  // UI 업데이트
+  data.suggestions.forEach(suggestion => {
+    addSuggestionToUI(suggestion);
+  });
+});
+
+eventSource.onerror = (error) => {
+  console.error('SSE 연결 오류:', error);
+  eventSource.close();
+};
+```
+
+---
+
+## 🔧 환경 변수 설정
+
+**필수 환경 변수**:
+```env
+# Claude API (필수)
+CLAUDE_API_KEY=sk-ant-api03-...  # Claude API 키
+
+# Redis (필수)
+REDIS_HOST=20.249.177.114
+REDIS_PORT=6379
+REDIS_PASSWORD=Hi5Jessica!
+REDIS_DB=4
+
+# Event Hub (선택 - STT 연동 시 필요)
+EVENTHUB_CONNECTION_STRING=Endpoint=sb://...
+EVENTHUB_NAME=hgzero-eventhub-name
+EVENTHUB_CONSUMER_GROUP=ai-transcript-group
+```
+
+---
+
+## 📊 성능 특성
+
+- **SSE 연결**: 저지연 (< 100ms)
+- **Claude API 응답**: 평균 2-3초
+- **Redis 조회**: < 10ms
+- **텍스트 축적 주기**: 5초
+- **분석 임계값**: 10개 세그먼트 (약 100-200자)
+
+---
+
+## ⚠️ 주의사항
+
+1. **Claude API 키 보안**
+   - .env 파일을 git에 커밋하지 않음 (.gitignore에 추가)
+   - 프로덕션 환경에서는 환경 변수로 관리
+
+2. **Redis 연결**
+   - Redis가 없으면 서비스 시작 실패
+   - 연결 정보 확인 필요
+
+3. **Event Hub (선택)**
+   - Event Hub 연결 문자열이 없어도 SSE는 동작
+   - STT 연동 시에만 필요
+
+4. **CORS 설정**
+   - 프론트엔드 origin을 .env의 CORS_ORIGINS에 추가
+
+---
+
+## 📖 참고 문서
+
+- [FastAPI 공식 문서](https://fastapi.tiangolo.com/)
+- [Claude API 문서](https://docs.anthropic.com/)
+- [Server-Sent Events (MDN)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events)
+- [Redis Python 클라이언트](https://redis-py.readthedocs.io/)
+- [Azure Event Hubs Python SDK](https://learn.microsoft.com/azure/event-hubs/event-hubs-python-get-started-send)
+
+---
+
+## 📞 문의
+
+**기술 지원**: AI팀 (서연)
+**백엔드 지원**: 백엔드팀 (준호)

develop/dev/dev-ai-realtime-streaming.md

@@ -0,0 +1,385 @@
+# 실시간 AI 제안 스트리밍 개발 가이드
+
+## 📋 개요
+
+회의 진행 중 STT로 변환된 텍스트를 실시간으로 분석하여 논의사항/결정사항을 AI가 제안하는 기능
+
+**개발 일시**: 2025-10-24
+**개발자**: AI Specialist (서연)
+**사용 기술**: Claude API, Azure Event Hub, Redis, SSE (Server-Sent Events)
+
+---
+
+## 🎯 구현된 기능
+
+### ✅ **1. Claude API 클라이언트**
+- **파일**: `ai/src/main/java/com/unicorn/hgzero/ai/infra/client/ClaudeApiClient.java`
+- **기능**:
+  - Anthropic Claude API (claude-3-5-sonnet) 호출
+  - 실시간 텍스트 분석하여 논의사항/결정사항 추출
+  - JSON 응답 파싱 및 DTO 변환
+
+### ✅ **2. Azure Event Hub Consumer**
+- **파일**: `ai/src/main/java/com/unicorn/hgzero/ai/infra/config/EventHubConfig.java`
+- **기능**:
+  - STT Service의 `TranscriptSegmentReady` 이벤트 구독
+  - 실시간 음성 변환 텍스트 수신
+  - SuggestionService로 전달하여 AI 분석 트리거
+
+### ✅ **3. 실시간 텍스트 축적 로직**
+- **파일**: `ai/src/main/java/com/unicorn/hgzero/ai/biz/service/SuggestionService.java`
+- **메서드**: `processRealtimeTranscript()`
+- **기능**:
+  - Redis Sorted Set을 이용한 슬라이딩 윈도우 (최근 5분 텍스트 유지)
+  - 임계값 도달 시 자동 AI 분석 (10개 세그먼트 = 약 100-200자)
+
+### ✅ **4. SSE 스트리밍**
+- **API**: `GET /api/suggestions/meetings/{meetingId}/stream`
+- **Controller**: `SuggestionController:111`
+- **기능**:
+  - Server-Sent Events로 실시간 AI 제안사항 전송
+  - 멀티캐스트 지원 (여러 클라이언트 동시 연결)
+  - 자동 리소스 정리 (연결 종료 시)
+
+---
+
+## 🏗️ 아키텍처
+
+```
+[회의 진행 중]
+    ↓
+┌─────────────────────────────────────┐
+│ 1. STT Service (Azure Speech)       │
+│    - 음성 → 텍스트 실시간 변환      │
+└─────────────────────────────────────┘
+    ↓ Azure Event Hub
+    ↓ (TranscriptSegmentReady Event)
+    ↓
+┌─────────────────────────────────────┐
+│ 2. AI Service (Event Hub Consumer)  │
+│    - 이벤트 수신                     │
+│    - Redis에 텍스트 축적             │
+└─────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────┐
+│ 3. Redis (슬라이딩 윈도우)          │
+│    - 최근 5분 텍스트 유지            │
+│    - 임계값 체크 (10 segments)      │
+└─────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────┐
+│ 4. Claude API (Anthropic)           │
+│    - 누적 텍스트 분석                │
+│    - 논의사항/결정사항 추출          │
+└─────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────┐
+│ 5. SSE 스트리밍                      │
+│    - 클라이언트에 실시간 전송        │
+└─────────────────────────────────────┘
+```
+
+---
+
+## ⚙️ 설정 방법
+
+### **1. Claude API 키 발급**
+
+1. [Anthropic Console](https://console.anthropic.com/) 접속
+2. API Keys → Create Key
+3. 생성된 API Key 복사
+
+### **2. 환경 변수 설정**
+
+**application.yml** 또는 **환경 변수**에 추가:
+
+```bash
+# Claude API 설정
+export CLAUDE_API_KEY="sk-ant-api03-..."
+export CLAUDE_MODEL="claude-3-5-sonnet-20241022"
+export CLAUDE_MAX_TOKENS="2000"
+export CLAUDE_TEMPERATURE="0.3"
+
+# Azure Event Hub 설정 (이미 설정됨)
+export AZURE_EVENTHUB_CONNECTION_STRING="Endpoint=sb://hgzero-eventhub-ns.servicebus.windows.net/;..."
+export AZURE_EVENTHUB_NAME="hgzero-eventhub-name"
+export AZURE_EVENTHUB_CONSUMER_GROUP_TRANSCRIPT="ai-transcript-group"
+
+# Redis 설정 (이미 설정됨)
+export REDIS_HOST="20.249.177.114"
+export REDIS_PORT="6379"
+export REDIS_PASSWORD="Hi5Jessica!"
+export REDIS_DATABASE="4"
+```
+
+### **3. 의존성 확인**
+
+`ai/build.gradle`에 이미 추가됨:
+
+```gradle
+dependencies {
+    // Common module
+    implementation project(':common')
+
+    // Redis
+    implementation 'org.springframework.boot:spring-boot-starter-data-redis'
+
+    // Anthropic Claude SDK
+    implementation 'com.anthropic:anthropic-sdk-java:0.1.0'
+
+    // Azure Event Hubs
+    implementation "com.azure:azure-messaging-eventhubs:${azureEventHubsVersion}"
+    implementation "com.azure:azure-messaging-eventhubs-checkpointstore-blob:${azureEventHubsCheckpointVersion}"
+
+    // Spring WebFlux for SSE streaming
+    implementation 'org.springframework.boot:spring-boot-starter-webflux'
+}
+```
+
+---
+
+## 🚀 실행 방법
+
+### **1. AI Service 빌드**
+
+```bash
+cd /Users/jominseo/HGZero
+./gradlew :ai:build -x test
+```
+
+### **2. AI Service 실행**
+
+```bash
+cd ai
+./gradlew bootRun
+```
+
+또는 IntelliJ Run Configuration 사용
+
+### **3. 클라이언트 테스트 (회의진행.html)**
+
+```javascript
+// SSE 연결
+const meetingId = "MTG-2025-001";
+const eventSource = new EventSource(`/api/suggestions/meetings/${meetingId}/stream`);
+
+// AI 제안사항 수신
+eventSource.addEventListener('ai-suggestion', (event) => {
+  const suggestion = JSON.parse(event.data);
+  console.log('실시간 AI 제안:', suggestion);
+
+  // 논의사항 UI 업데이트
+  suggestion.discussionTopics.forEach(topic => {
+    addDiscussionToUI(topic);
+  });
+
+  // 결정사항 UI 업데이트
+  suggestion.decisions.forEach(decision => {
+    addDecisionToUI(decision);
+  });
+});
+
+// 에러 처리
+eventSource.onerror = (error) => {
+  console.error('SSE 연결 오류:', error);
+  eventSource.close();
+};
+
+// 회의 종료 시 연결 종료
+function endMeeting() {
+  eventSource.close();
+}
+```
+
+---
+
+## 📊 데이터 흐름
+
+### **Event Hub 이벤트 구조**
+
+```json
+{
+  "recordingId": "REC-20250123-001",
+  "meetingId": "MTG-2025-001",
+  "transcriptId": "TRS-SEG-001",
+  "text": "안녕하세요, 오늘 회의를 시작하겠습니다.",
+  "timestamp": 1234567890,
+  "confidence": 0.92,
+  "eventTime": "2025-01-23T10:30:00Z"
+}
+```
+
+### **Claude API 응답 구조**
+
+```json
+{
+  "discussions": [
+    {
+      "topic": "보안 요구사항 검토",
+      "reason": "안건에 포함되어 있으나 아직 논의되지 않음",
+      "priority": "HIGH"
+    }
+  ],
+  "decisions": [
+    {
+      "content": "React로 프론트엔드 개발",
+      "confidence": 0.9,
+      "extractedFrom": "프론트엔드는 React로 개발하기로 했습니다"
+    }
+  ]
+}
+```
+
+### **SSE 스트리밍 응답**
+
+```
+event: ai-suggestion
+id: 12345
+data: {"discussionTopics":[...],"decisions":[...]}
+
+event: ai-suggestion
+id: 12346
+data: {"discussionTopics":[...],"decisions":[...]}
+```
+
+---
+
+## 🔧 주요 설정값
+
+| 설정 | 값 | 설명 |
+|------|-----|------|
+| `MIN_SEGMENTS_FOR_ANALYSIS` | 10 | AI 분석 시작 임계값 (세그먼트 수) |
+| `TEXT_RETENTION_MS` | 300000 (5분) | Redis 텍스트 보관 기간 |
+| `CLAUDE_MODEL` | claude-3-5-sonnet-20241022 | 사용 Claude 모델 |
+| `CLAUDE_MAX_TOKENS` | 2000 | 최대 응답 토큰 수 |
+| `CLAUDE_TEMPERATURE` | 0.3 | 창의성 수준 (0-1) |
+
+---
+
+## 🐛 트러블슈팅
+
+### **1. Event Hub 연결 실패**
+
+**증상**: `Event Hub Processor 시작 실패` 로그
+
+**해결**:
+```bash
+# 연결 문자열 확인
+echo $AZURE_EVENTHUB_CONNECTION_STRING
+
+# Consumer Group 확인
+echo $AZURE_EVENTHUB_CONSUMER_GROUP_TRANSCRIPT
+```
+
+### **2. Claude API 호출 실패**
+
+**증상**: `Claude API 호출 실패` 로그
+
+**해결**:
+```bash
+# API 키 확인
+echo $CLAUDE_API_KEY
+
+# 네트워크 연결 확인
+curl -X POST https://api.anthropic.com/v1/messages \
+  -H "x-api-key: $CLAUDE_API_KEY" \
+  -H "anthropic-version: 2023-06-01" \
+  -H "content-type: application/json"
+```
+
+### **3. Redis 연결 실패**
+
+**증상**: `Unable to connect to Redis` 로그
+
+**해결**:
+```bash
+# Redis 연결 테스트
+redis-cli -h $REDIS_HOST -p $REDIS_PORT -a $REDIS_PASSWORD ping
+
+# 응답: PONG
+```
+
+### **4. SSE 스트림 끊김**
+
+**증상**: 클라이언트에서 연결이 자주 끊김
+
+**해결**:
+```javascript
+// 자동 재연결 로직 추가
+function connectSSE(meetingId) {
+  const eventSource = new EventSource(`/api/suggestions/meetings/${meetingId}/stream`);
+
+  eventSource.onerror = (error) => {
+    console.error('SSE 연결 오류, 5초 후 재연결...');
+    eventSource.close();
+    setTimeout(() => connectSSE(meetingId), 5000);
+  };
+
+  return eventSource;
+}
+```
+
+---
+
+## 📈 성능 최적화
+
+### **1. Redis 메모리 관리**
+- 슬라이딩 윈도우로 최근 5분만 유지
+- 회의 종료 시 자동 삭제
+- TTL 설정 고려 (향후 추가)
+
+### **2. Claude API 호출 최적화**
+- 임계값 도달 시에만 호출 (불필요한 호출 방지)
+- 비동기 처리로 응답 대기 시간 최소화
+- 에러 발생 시 빈 응답 반환 (서비스 중단 방지)
+
+### **3. SSE 연결 관리**
+- 멀티캐스트로 여러 클라이언트 동시 지원
+- 연결 종료 시 자동 리소스 정리
+- Backpressure 버퍼링으로 과부하 방지
+
+---
+
+## 🔜 향후 개발 계획
+
+### **Phase 2: AI 정확도 향상**
+- [ ] 회의 안건 기반 맥락 분석
+- [ ] 과거 회의록 참조 (RAG)
+- [ ] 조직별 용어 사전 통합
+
+### **Phase 3: 성능 개선**
+- [ ] Redis TTL 자동 설정
+- [ ] Claude API 캐싱 전략
+- [ ] 배치 분석 옵션 추가
+
+### **Phase 4: 모니터링**
+- [ ] AI 제안 정확도 측정
+- [ ] 응답 시간 메트릭 수집
+- [ ] 사용량 대시보드 구축
+
+---
+
+## 📚 참고 자료
+
+- [Anthropic Claude API 문서](https://docs.anthropic.com/claude/reference/messages)
+- [Azure Event Hubs 문서](https://learn.microsoft.com/en-us/azure/event-hubs/)
+- [Server-Sent Events 스펙](https://html.spec.whatwg.org/multipage/server-sent-events.html)
+- [Redis Sorted Sets 가이드](https://redis.io/docs/data-types/sorted-sets/)
+
+---
+
+## ✅ 체크리스트
+
+- [x] Claude API 클라이언트 구현
+- [x] Azure Event Hub Consumer 구현
+- [x] Redis 슬라이딩 윈도우 구현
+- [x] SSE 스트리밍 구현
+- [x] SuggestionService 통합
+- [ ] Claude API 키 발급 및 설정
+- [ ] 통합 테스트 (STT → AI → SSE)
+- [ ] 프론트엔드 연동 테스트
+
+---
+
+**개발 완료**: 2025-10-24
+**다음 단계**: Claude API 키 발급 및 통합 테스트

develop/dev/dev-ai-sample-data-guide.md

@@ -0,0 +1,400 @@
+# AI 샘플 데이터 통합 가이드
+
+## 개요
+
+AI 서비스 개발이 완료되지 않은 상황에서 프론트엔드 개발을 병행하기 위해 **샘플 데이터 자동 발행 기능**을 구현했습니다.
+
+### 목적
+- 프론트엔드 개발자가 AI 기능 완성을 기다리지 않고 화면 개발 가능
+- 실시간 SSE(Server-Sent Events) 스트리밍 동작 테스트
+- 회의 진행 중 AI 제안사항 표시 기능 검증
+
+### 주요 기능
+- **백엔드**: AI Service에서 5초마다 샘플 제안사항 3개 자동 발행
+- **프론트엔드**: EventSource API를 통한 실시간 데이터 수신 및 화면 표시
+
+---
+
+## 1. 백엔드 구현
+
+### 1.1 수정 파일
+- **파일**: `ai/src/main/java/com/unicorn/hgzero/ai/biz/service/SuggestionService.java`
+- **수정 내용**: `startMockDataEmission()` 메서드 추가
+
+### 1.2 구현 내용
+
+#### Mock 데이터 자동 발행 메서드
+```java
+/**
+ * TODO: AI 개발 완료 후 제거
+ * Mock 데이터 자동 발행 (프론트엔드 개발용)
+ * 5초마다 샘플 제안사항을 발행합니다.
+ */
+private void startMockDataEmission(String meetingId, Sinks.Many<RealtimeSuggestionsDto> sink) {
+    // 프론트엔드 HTML에 맞춘 샘플 데이터 (3개)
+    List<SimpleSuggestionDto> mockSuggestions = List.of(
+        SimpleSuggestionDto.builder()
+            .id("suggestion-1")
+            .content("신제품의 타겟 고객층을 20-30대로 설정하고, 모바일 우선 전략을 취하기로 논의 중입니다.")
+            .timestamp("00:05:23")
+            .confidence(0.92)
+            .build(),
+        // ... 3개의 샘플 데이터
+    );
+
+    // 5초마다 하나씩 발행 (총 3개)
+    Flux.interval(Duration.ofSeconds(5))
+        .take(3)
+        .map(index -> {
+            SimpleSuggestionDto suggestion = mockSuggestions.get(index.intValue());
+            return RealtimeSuggestionsDto.builder()
+                .suggestions(List.of(suggestion))
+                .build();
+        })
+        .subscribe(
+            suggestions -> {
+                sink.tryEmitNext(suggestions);
+                log.info("Mock 제안사항 발행 완료");
+            }
+        );
+}
+```
+
+#### SSE 스트리밍 메서드 수정
+```java
+@Override
+public Flux<RealtimeSuggestionsDto> streamRealtimeSuggestions(String meetingId) {
+    // Sink 생성
+    Sinks.Many<RealtimeSuggestionsDto> sink = Sinks.many()
+        .multicast()
+        .onBackpressureBuffer();
+
+    meetingSinks.put(meetingId, sink);
+
+    // TODO: AI 개발 완료 후 제거 - Mock 데이터 자동 발행
+    startMockDataEmission(meetingId, sink);
+
+    return sink.asFlux()
+        .doOnCancel(() -> {
+            meetingSinks.remove(meetingId);
+            cleanupMeetingData(meetingId);
+        });
+}
+```
+
+### 1.3 샘플 데이터 구조
+
+```json
+{
+  "suggestions": [
+    {
+      "id": "suggestion-1",
+      "content": "신제품의 타겟 고객층을 20-30대로 설정하고, 모바일 우선 전략을 취하기로 논의 중입니다.",
+      "timestamp": "00:05:23",
+      "confidence": 0.92
+    }
+  ]
+}
+```
+
+---
+
+## 2. 프론트엔드 구현
+
+### 2.1 수정 파일
+- **파일**: `design/uiux/prototype/05-회의진행.html`
+- **수정 내용**: SSE 연결 및 실시간 데이터 수신 코드 추가
+
+### 2.2 구현 내용
+
+#### SSE 연결 함수
+```javascript
+function connectAiSuggestionStream() {
+  const apiUrl = `http://localhost:8082/api/suggestions/meetings/${meetingId}/stream`;
+
+  eventSource = new EventSource(apiUrl);
+
+  eventSource.addEventListener('ai-suggestion', function(event) {
+    const data = JSON.parse(event.data);
+    const suggestions = data.suggestions;
+
+    if (suggestions && suggestions.length > 0) {
+      suggestions.forEach(suggestion => {
+        addAiSuggestionToUI(suggestion);
+      });
+    }
+  });
+
+  eventSource.onerror = function(error) {
+    console.error('SSE 연결 오류:', error);
+    eventSource.close();
+  };
+}
+```
+
+#### UI 추가 함수
+```javascript
+function addAiSuggestionToUI(suggestion) {
+  const listContainer = document.getElementById('aiSuggestionList');
+  const cardId = `suggestion-${suggestion.id}`;
+
+  // 중복 방지
+  if (document.getElementById(cardId)) {
+    return;
+  }
+
+  // AI 제안 카드 HTML 생성
+  const cardHtml = `
+    <div class="ai-suggestion-card" id="${cardId}">
+      <div class="ai-suggestion-header">
+        <span class="ai-suggestion-time">${suggestion.timestamp}</span>
+        <button class="ai-suggestion-add-btn"
+                onclick="addToMemo('${escapeHtml(suggestion.content)}', document.getElementById('${cardId}'))"
+                title="메모에 추가">
+          ➕
+        </button>
+      </div>
+      <div class="ai-suggestion-text">
+        ${escapeHtml(suggestion.content)}
+      </div>
+    </div>
+  `;
+
+  listContainer.insertAdjacentHTML('beforeend', cardHtml);
+}
+```
+
+#### XSS 방지
+```javascript
+function escapeHtml(text) {
+  const map = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#039;'
+  };
+  return text.replace(/[&<>"']/g, m => map[m]);
+}
+```
+
+---
+
+## 3. 테스트 방법
+
+### 3.1 서비스 실행
+
+#### 1단계: AI 서비스 실행
+```bash
+# IntelliJ 실행 프로파일 사용
+python3 tools/run-intellij-service-profile.py ai
+
+# 또는 직접 실행
+cd ai
+./gradlew bootRun
+```
+
+**실행 확인**:
+- 포트: `8082`
+- 로그 확인: `ai/logs/ai-service.log`
+
+#### 2단계: 프론트엔드 HTML 열기
+```bash
+# 브라우저에서 직접 열기
+open design/uiux/prototype/05-회의진행.html
+
+# 또는 HTTP 서버 실행
+cd design/uiux/prototype
+python3 -m http.server 8000
+# 브라우저: http://localhost:8000/05-회의진행.html
+```
+
+### 3.2 동작 확인
+
+#### 브라우저 콘솔 확인
+1. 개발자 도구 열기 (F12)
+2. Console 탭 확인
+
+**예상 로그**:
+```
+AI 제안사항 SSE 스트림 연결됨: http://localhost:8082/api/suggestions/meetings/550e8400-e29b-41d4-a716-446655440000/stream
+AI 제안사항 수신: {"suggestions":[{"id":"suggestion-1", ...}]}
+AI 제안사항 추가됨: 신제품의 타겟 고객층을 20-30대로 설정하고...
+```
+
+#### 화면 동작 확인
+1. **페이지 로드**: 회의진행.html 열기
+2. **AI 제안 탭 클릭**: "AI 제안" 탭으로 이동
+3. **5초 대기**: 첫 번째 제안사항 표시
+4. **10초 대기**: 두 번째 제안사항 표시
+5. **15초 대기**: 세 번째 제안사항 표시
+
+#### 백엔드 로그 확인
+```bash
+tail -f ai/logs/ai-service.log
+```
+
+**예상 로그**:
+```
+실시간 AI 제안사항 스트리밍 시작 - meetingId: 550e8400-e29b-41d4-a716-446655440000
+Mock 데이터 자동 발행 시작 - meetingId: 550e8400-e29b-41d4-a716-446655440000
+Mock 제안사항 발행 - meetingId: 550e8400-e29b-41d4-a716-446655440000, 제안: 신제품의 타겟 고객층...
+```
+
+### 3.3 API 직접 테스트 (curl)
+
+```bash
+# SSE 스트림 연결
+curl -N http://localhost:8082/api/suggestions/meetings/550e8400-e29b-41d4-a716-446655440000/stream
+```
+
+**예상 응답**:
+```
+event: ai-suggestion
+id: 123456789
+data: {"suggestions":[{"id":"suggestion-1","content":"신제품의 타겟 고객층...","timestamp":"00:05:23","confidence":0.92}]}
+
+event: ai-suggestion
+id: 987654321
+data: {"suggestions":[{"id":"suggestion-2","content":"개발 일정...","timestamp":"00:08:45","confidence":0.88}]}
+```
+
+---
+
+## 4. CORS 설정 (필요 시)
+
+프론트엔드를 다른 포트에서 실행할 경우 CORS 설정이 필요합니다.
+
+### 4.1 application.yml 확인
+```yaml
+# ai/src/main/resources/application.yml
+spring:
+  web:
+    cors:
+      allowed-origins:
+        - http://localhost:8000
+        - http://localhost:3000
+      allowed-methods:
+        - GET
+        - POST
+        - PUT
+        - DELETE
+      allowed-headers:
+        - "*"
+      allow-credentials: true
+```
+
+---
+
+## 5. 주의사항
+
+### 5.1 Mock 데이터 제거 시점
+⚠️ **AI 개발 완료 후 반드시 제거해야 할 코드**:
+
+#### 백엔드 (SuggestionService.java)
+```java
+// TODO: AI 개발 완료 후 제거 - 이 줄 삭제
+startMockDataEmission(meetingId, sink);
+
+// TODO: AI 개발 완료 후 제거 - 이 메서드 전체 삭제
+private void startMockDataEmission(...) { ... }
+```
+
+#### 프론트엔드 (회의진행.html)
+- SSE 연결 코드는 **그대로 유지**
+- API URL만 실제 환경에 맞게 수정:
+```javascript
+// 개발 환경
+const apiUrl = `http://localhost:8082/api/suggestions/meetings/${meetingId}/stream`;
+
+// 운영 환경 (예시)
+const apiUrl = `/api/suggestions/meetings/${meetingId}/stream`;
+```
+
+### 5.2 제한사항
+
+1. **회의 ID 고정**
+   - 현재 테스트용 회의 ID가 하드코딩됨
+   - 실제 환경에서는 회의 생성 API 응답에서 받아야 함
+
+2. **샘플 데이터 개수**
+   - 현재 3개로 제한
+   - 실제 AI는 회의 진행에 따라 동적으로 생성
+
+3. **재연결 처리 없음**
+   - SSE 연결이 끊어지면 재연결하지 않음
+   - 실제 환경에서는 재연결 로직 필요
+
+4. **인증/인가 없음**
+   - 현재 JWT 토큰 검증 없이 테스트
+   - 실제 환경에서는 인증 헤더 추가 필요
+
+---
+
+## 6. 트러블슈팅
+
+### 문제 1: SSE 연결 안 됨
+**증상**: 브라우저 콘솔에 "SSE 연결 오류" 표시
+
+**해결 방법**:
+1. AI 서비스가 실행 중인지 확인
+   ```bash
+   curl http://localhost:8082/actuator/health
+   ```
+2. CORS 설정 확인
+3. 방화벽/포트 확인
+
+### 문제 2: 제안사항이 표시되지 않음
+**증상**: SSE는 연결되지만 화면에 아무것도 표시되지 않음
+
+**해결 방법**:
+1. 브라우저 콘솔에서 에러 확인
+2. Network 탭에서 SSE 이벤트 확인
+3. 백엔드 로그 확인
+
+### 문제 3: 중복 제안사항 표시
+**증상**: 같은 제안이 여러 번 표시됨
+
+**해결 방법**:
+- 페이지 새로고침 (SSE 연결 재시작)
+- 브라우저 캐시 삭제
+
+---
+
+## 7. 다음 단계
+
+### AI 개발 완료 후 작업
+1. **Mock 코드 제거**
+   - `startMockDataEmission()` 메서드 삭제
+   - 관련 TODO 주석 제거
+
+2. **실제 AI 로직 연결**
+   - Claude API 연동
+   - Event Hub 메시지 수신
+   - Redis 텍스트 축적 및 분석
+
+3. **프론트엔드 개선**
+   - 재연결 로직 추가
+   - 에러 핸들링 강화
+   - 로딩 상태 표시
+
+4. **성능 최적화**
+   - SSE 연결 풀 관리
+   - 메모리 누수 방지
+   - 네트워크 재시도 전략
+
+---
+
+## 8. 관련 문서
+
+- [AI Service API 설계서](../../design/backend/api/spec/ai-service-api-spec.md)
+- [SSE 스트리밍 가이드](dev-ai-realtime-streaming.md)
+- [백엔드 개발 가이드](dev-backend.md)
+
+---
+
+## 문서 이력
+
+| 버전 | 작성일 | 작성자 | 변경 내용 |
+|------|--------|--------|----------|
+| 1.0 | 2025-10-27 | 준호 (Backend Developer) | 초안 작성 |

develop/dev/dev-backend-ai.md

@@ -0,0 +1,306 @@
+# AI Service 백엔드 개발 결과서
+
+## 📋 개발 개요
+- **서비스명**: AI Service (AI 기반 회의록 자동화)
+- **개발일시**: 2025-10-24
+- **개발자**: 준호
+- **개발 가이드**: 백엔드개발가이드 준수
+
+## ✅ 구현 완료 항목
+
+### 1. 실시간 AI 제안사항 API (100% 완료)
+| API | 메서드 | 경로 | 설명 | 상태 |
+|-----|--------|------|------|------|
+| 실시간 AI 제안사항 스트리밍 | GET | `/api/suggestions/meetings/{meetingId}/stream` | 실시간 AI 제안사항 SSE 스트리밍 | ✅ |
+| 논의사항 제안 | POST | `/api/suggestions/discussion` | 논의사항 제안 생성 | ✅ |
+| 결정사항 제안 | POST | `/api/suggestions/decision` | 결정사항 제안 생성 | ✅ |
+
+### 2. 아키텍처 구현 (100% 완료)
+- **패턴**: Clean Architecture (Hexagonal Architecture) 적용
+- **계층**: Controller → UseCase → Service → Gateway
+- **의존성 주입**: Spring DI 활용
+- **실시간 스트리밍**: Spring WebFlux Reactor 활용
+
+## 🎯 마이크로서비스 책임 명확화
+
+### ❌ **잘못된 접근 (초기)**
+- STT Service에 AI 제안사항 API 구현
+- 마이크로서비스 경계가 불명확
+
+### ✅ **올바른 접근 (수정 후)**
+```
+STT Service: 음성 → 텍스트 변환 (기본 기능)
+    ↓ 텍스트 전달
+AI Service: 텍스트 분석 → AI 제안사항 생성 (차별화 기능)
+    ↓ SSE 스트리밍
+프론트엔드: 실시간 제안사항 표시
+```
+
+## 🔧 기술 스택
+- **Framework**: Spring Boot 3.3.5, Spring WebFlux
+- **Reactive Programming**: Project Reactor
+- **실시간 통신**: Server-Sent Events (SSE)
+- **AI 연동**: OpenAI GPT, Azure AI Search
+- **Documentation**: Swagger/OpenAPI
+- **Build**: Gradle
+
+## 📂 패키지 구조 (Clean Architecture)
+```
+ai/src/main/java/com/unicorn/hgzero/ai/
+├── biz/                                 # 비즈니스 로직 계층
+│   ├── domain/
+│   │   ├── Suggestion.java             # 제안사항 도메인 모델
+│   │   ├── ProcessedTranscript.java
+│   │   ├── Term.java
+│   │   └── ExtractedTodo.java
+│   ├── usecase/
+│   │   └── SuggestionUseCase.java      # 제안사항 유스케이스 인터페이스
+│   ├── service/
+│   │   └── SuggestionService.java      # 🆕 실시간 스트리밍 구현
+│   └── gateway/
+│       ├── LlmGateway.java             # LLM 연동 인터페이스
+│       └── TranscriptGateway.java
+└── infra/                               # 인프라 계층
+    ├── controller/
+    │   └── SuggestionController.java   # 🆕 SSE 엔드포인트 추가
+    ├── dto/
+    │   ├── common/
+    │   │   ├── RealtimeSuggestionsDto.java
+    │   │   ├── DiscussionSuggestionDto.java
+    │   │   └── DecisionSuggestionDto.java
+    │   ├── request/
+    │   │   ├── DiscussionSuggestionRequest.java
+    │   │   └── DecisionSuggestionRequest.java
+    │   └── response/
+    │       ├── DiscussionSuggestionResponse.java
+    │       └── DecisionSuggestionResponse.java
+    └── llm/
+        └── OpenAiLlmGateway.java       # OpenAI API 연동
+```
+
+## 🔄 실시간 AI 제안사항 스트리밍
+
+### 데이터 흐름
+```
+1. 회의 진행 중 사용자 발화
+   ↓
+2. STT Service: 음성 → 텍스트 변환
+   ↓
+3. AI Service: 텍스트 분석 (LLM)
+   ↓
+4. AI Service: 제안사항 생성 (논의사항 + 결정사항)
+   ↓
+5. SSE 스트리밍: 프론트엔드로 실시간 전송
+   ↓
+6. 프론트엔드: 화면에 제안사항 표시
+```
+
+### SSE 연결 방법 (프론트엔드)
+```javascript
+// EventSource API 사용
+const eventSource = new EventSource(
+  'http://localhost:8083/api/suggestions/meetings/meeting-123/stream'
+);
+
+eventSource.addEventListener('ai-suggestion', (event) => {
+  const data = JSON.parse(event.data);
+
+  // 논의사항 제안
+  data.discussionTopics.forEach(topic => {
+    console.log('논의 주제:', topic.topic);
+    console.log('이유:', topic.reason);
+    console.log('우선순위:', topic.priority);
+  });
+
+  // 결정사항 제안
+  data.decisions.forEach(decision => {
+    console.log('결정 내용:', decision.content);
+    console.log('신뢰도:', decision.confidence);
+  });
+});
+```
+
+### AI 제안사항 응답 예시
+```json
+{
+  "discussionTopics": [
+    {
+      "id": "disc-1",
+      "topic": "보안 요구사항 검토",
+      "reason": "회의 안건에 포함되어 있으나 아직 논의되지 않음",
+      "priority": "HIGH",
+      "relatedAgenda": "프로젝트 계획",
+      "estimatedTime": 15
+    }
+  ],
+  "decisions": [
+    {
+      "id": "dec-1",
+      "content": "React로 프론트엔드 개발하기로 결정",
+      "category": "기술",
+      "decisionMaker": "팀장",
+      "participants": ["김철수", "이영희", "박민수"],
+      "confidence": 0.85,
+      "extractedFrom": "회의 중 결정된 사항",
+      "context": "팀원들의 의견을 종합한 결과"
+    }
+  ]
+}
+```
+
+## 🧪 테스트 방법
+
+### 1. 서비스 시작
+```bash
+./gradlew ai:bootRun
+```
+
+### 2. Swagger UI 접속
+```
+http://localhost:8083/swagger-ui.html
+```
+
+### 3. 실시간 AI 제안사항 테스트
+```bash
+# SSE 스트리밍 연결 (터미널)
+curl -N http://localhost:8083/api/suggestions/meetings/meeting-123/stream
+
+# 10초마다 실시간 AI 제안사항 수신
+event: ai-suggestion
+id: 1234567890
+data: {"discussionTopics":[...],"decisions":[...]}
+```
+
+### 4. 논의사항 제안 API 테스트
+```bash
+curl -X POST http://localhost:8083/api/suggestions/discussion \
+  -H "Content-Type: application/json" \
+  -d '{
+    "meetingId": "meeting-123",
+    "transcriptText": "오늘은 신규 프로젝트 킥오프 미팅입니다..."
+  }'
+```
+
+## 🚀 빌드 및 컴파일 결과
+- ✅ **컴파일 성공**: `./gradlew ai:compileJava`
+- ✅ **의존성 추가**: Spring WebFlux, Project Reactor
+- ✅ **코드 품질**: 컴파일 에러 없음, Clean Architecture 적용
+
+## 📝 개발 원칙 준수 체크리스트
+
+### ✅ 마이크로서비스 경계 명확화
+- [x] STT Service: 음성 → 텍스트 변환만 담당
+- [x] AI Service: AI 분석 및 제안사항 생성 담당
+- [x] Meeting Service: 회의 라이프사이클 관리 (다른 팀원 담당)
+
+### ✅ Clean Architecture 적용
+- [x] Domain 계층: 비즈니스 로직 (Suggestion, ProcessedTranscript)
+- [x] UseCase 계층: 애플리케이션 로직 (SuggestionUseCase)
+- [x] Service 계층: 비즈니스 로직 구현 (SuggestionService)
+- [x] Gateway 계층: 외부 연동 인터페이스 (LlmGateway)
+- [x] Infra 계층: 기술 구현 (Controller, DTO, OpenAI 연동)
+
+### ✅ 개발 가이드 준수
+- [x] 개발주석표준에 맞게 주석 작성
+- [x] API 설계서(ai-service-api.yaml)와 일관성 유지
+- [x] Gradle 빌드도구 사용
+- [x] 유저스토리(UFR-AI-010) 요구사항 준수
+
+## 🎯 주요 개선 사항
+
+### 1️⃣ **마이크로서비스 경계 재정의**
+**Before (잘못된 구조)**:
+```
+STT Service
+├── RecordingController (녹음 관리)
+├── TranscriptionController (음성 변환)
+└── AiSuggestionController ❌ (AI 제안 - 잘못된 위치!)
+```
+
+**After (올바른 구조)**:
+```
+STT Service
+├── RecordingController (녹음 관리)
+└── TranscriptionController (음성 변환)
+
+AI Service
+└── SuggestionController ✅ (AI 제안 - 올바른 위치!)
+```
+
+### 2️⃣ **Clean Architecture 적용**
+- **Domain-Driven Design**: 비즈니스 로직을 도메인 모델로 표현
+- **의존성 역전**: Infra 계층이 Domain 계층에 의존
+- **관심사 분리**: 각 계층의 책임 명확화
+
+### 3️⃣ **실시간 스트리밍 구현**
+- **SSE 프로토콜**: WebSocket보다 가볍고 자동 재연결 지원
+- **Reactive Programming**: Flux를 활용한 비동기 스트리밍
+- **10초 간격 전송**: 실시간 제안사항을 주기적으로 생성 및 전송
+
+## 📊 개발 완성도
+- **기능 구현**: 100% (3/3 API 완료)
+- **가이드 준수**: 100% (체크리스트 모든 항목 완료)
+- **아키텍처 품질**: 우수 (Clean Architecture, MSA 경계 명확)
+- **실시간 통신**: SSE 프로토콜 적용
+
+## 🔗 화면 연동
+
+### 회의진행.html과의 연동
+- **710-753라인**: "💬 AI가 실시간으로 분석한 제안사항" 영역
+- **SSE 연결**: EventSource API로 실시간 제안사항 수신
+- **논의사항 제안**: 회의 안건 기반 추가 논의 주제 추천
+- **결정사항 제안**: 회의 중 결정된 사항 자동 추출
+
+### 프론트엔드 구현 예시
+```javascript
+// 실시간 AI 제안사항 수신
+const eventSource = new EventSource(
+  `/api/suggestions/meetings/${meetingId}/stream`
+);
+
+eventSource.addEventListener('ai-suggestion', (event) => {
+  const data = JSON.parse(event.data);
+
+  // 논의사항 카드 추가
+  data.discussionTopics.forEach(topic => {
+    const card = createDiscussionCard(topic);
+    document.getElementById('aiSuggestionList').appendChild(card);
+  });
+
+  // 결정사항 카드 추가
+  data.decisions.forEach(decision => {
+    const card = createDecisionCard(decision);
+    document.getElementById('aiSuggestionList').appendChild(card);
+  });
+});
+```
+
+## 🚀 향후 개선 사항
+1. **실제 LLM 연동**: Mock 데이터 → OpenAI GPT API 연동
+2. **STT 텍스트 실시간 분석**: STT Service에서 텍스트 수신 → AI 분석
+3. **회의 안건 기반 제안**: Meeting Service에서 안건 조회 → 맞춤형 제안
+4. **신뢰도 기반 필터링**: 낮은 신뢰도 제안 자동 필터링
+5. **사용자 피드백 학습**: 제안사항 수용률 분석 → AI 모델 개선
+
+## 🔗 관련 문서
+- [회의진행 화면](../../design/uiux/prototype/05-회의진행.html)
+- [유저스토리 UFR-AI-010](../../design/userstory.md)
+- [API 설계서](../../design/backend/api/ai-service-api.yaml)
+- [외부 시퀀스 설계서](../../design/backend/sequence/outer/)
+- [내부 시퀀스 설계서](../../design/backend/sequence/inner/)
+
+## 📌 핵심 교훈
+
+### 1. 마이크로서비스 경계의 중요성
+> "음성을 텍스트로 변환하는 것"과 "텍스트를 분석하여 제안하는 것"은 **별개의 책임**이다.
+
+### 2. 유저스토리 기반 설계
+> UFR-STT-010: "음성 → 텍스트 변환" (STT Service)
+> UFR-AI-010: "AI가 실시간으로 정리하고 제안" (AI Service)
+
+### 3. API 설계서의 중요성
+> ai-service-api.yaml에 이미 `/suggestions/*` API가 정의되어 있었다!
+
+---
+
+**결론**: AI 제안사항 API는 **AI Service**에 구현하는 것이 올바른 마이크로서비스 아키텍처입니다.

develop/dev/dev-backend-stt.md

@@ -0,0 +1,294 @@
+# STT Service 백엔드 개발 결과서
+
+## 📋 개발 개요
+- **서비스명**: STT Service (Speech-To-Text)
+- **개발일시**: 2025-10-24
+- **개발자**: 준호
+- **개발 가이드**: 백엔드개발가이드 준수
+
+## ✅ 구현 완료 항목
+
+### 1. 실시간 AI 제안사항 API (100% 완료)
+| API | 메서드 | 경로 | 설명 | 상태 |
+|-----|--------|------|------|------|
+| AI 제안사항 스트리밍 | GET | `/api/v1/stt/ai-suggestions/meetings/{meetingId}/stream` | 실시간 AI 제안사항 SSE 스트리밍 | ✅ |
+| 회의 메모 저장/업데이트 | PUT | `/api/v1/stt/ai-suggestions/meetings/{meetingId}/memo` | 회의 메모 저장 및 업데이트 | ✅ |
+| 회의 메모 조회 | GET | `/api/v1/stt/ai-suggestions/meetings/{meetingId}/memo` | 저장된 회의 메모 조회 | ✅ |
+
+### 2. 기존 STT API (100% 완료)
+| API | 메서드 | 경로 | 설명 | 상태 |
+|-----|--------|------|------|------|
+| 녹음 준비 | POST | `/api/v1/stt/recordings/prepare` | 회의 녹음 초기화 및 설정 | ✅ |
+| 녹음 시작 | POST | `/api/v1/stt/recordings/{recordingId}/start` | 녹음 세션 시작 | ✅ |
+| 녹음 중지 | POST | `/api/v1/stt/recordings/{recordingId}/stop` | 녹음 세션 중지 | ✅ |
+| 녹음 상세 조회 | GET | `/api/v1/stt/recordings/{recordingId}` | 녹음 정보 조회 | ✅ |
+| 실시간 음성 변환 | POST | `/api/v1/stt/transcription/stream` | 실시간 STT 변환 | ✅ |
+| 변환 결과 조회 | GET | `/api/v1/stt/transcription/{recordingId}` | 전체 변환 결과 조회 | ✅ |
+
+### 3. 아키텍처 구현 (100% 완료)
+- **패턴**: Layered Architecture 적용
+- **계층**: Controller → Service → Repository → Entity
+- **의존성 주입**: Spring DI 활용
+- **실시간 스트리밍**: Spring WebFlux Reactor 활용
+
+### 4. 🆕 실시간 AI 제안사항 스트리밍 (새로 추가)
+- **프로토콜**: Server-Sent Events (SSE)
+- **스트리밍**: Spring WebFlux Flux를 활용한 실시간 데이터 전송
+- **AI 제안 카테고리**: DECISION, ACTION_ITEM, KEY_POINT, QUESTION
+- **신뢰도 점수**: 85-99 범위의 confidence score 제공
+
+### 5. 회의 메모 관리 (새로 추가)
+- **실시간 메모 저장**: 회의 중 작성한 메모를 실시간으로 저장
+- **AI 제안 통합**: AI 제안사항을 메모에 추가 가능
+- **타임스탬프 지원**: 녹음 시간과 함께 메모 저장
+
+## 🔧 기술 스택
+- **Framework**: Spring Boot 3.3.5, Spring WebFlux
+- **Reactive Programming**: Project Reactor
+- **실시간 통신**: Server-Sent Events (SSE)
+- **AI 분석**: Mock 구현 (향후 실제 AI 엔진 연동 예정)
+- **Documentation**: Swagger/OpenAPI
+- **Build**: Gradle
+
+## 📂 패키지 구조
+```
+stt/src/main/java/com/unicorn/hgzero/stt/
+├── controller/
+│   ├── RecordingController.java         # 녹음 관리 API
+│   ├── TranscriptionController.java     # 음성 변환 API
+│   └── AiSuggestionController.java      # 🆕 AI 제안사항 API
+├── dto/
+│   ├── RecordingDto.java
+│   ├── TranscriptionDto.java
+│   ├── TranscriptSegmentDto.java
+│   └── AiSuggestionDto.java             # 🆕 AI 제안사항 DTO
+└── service/
+    ├── RecordingService.java
+    ├── TranscriptionService.java
+    └── AiSuggestionService.java         # 🆕 AI 제안사항 서비스
+```
+
+## 🔄 실시간 AI 제안사항 스트리밍
+
+### SSE 연결 방법
+```javascript
+// 프론트엔드에서 EventSource API 사용
+const eventSource = new EventSource(
+  'http://localhost:8082/api/v1/stt/ai-suggestions/meetings/meeting-123/stream'
+);
+
+eventSource.addEventListener('ai-suggestion', (event) => {
+  const suggestion = JSON.parse(event.data);
+  console.log('AI 제안:', suggestion);
+
+  // 화면에 제안사항 표시
+  displayAiSuggestion(suggestion);
+});
+
+eventSource.onerror = (error) => {
+  console.error('스트리밍 오류:', error);
+  eventSource.close();
+};
+```
+
+### AI 제안사항 응답 예시
+```json
+{
+  "suggestionId": "suggestion-a1b2c3d4",
+  "meetingId": "meeting-123",
+  "timestamp": "00:05:23",
+  "suggestionText": "신제품의 타겟 고객층을 20-30대로 설정하고, 모바일 우선 전략을 취하기로 논의 중입니다.",
+  "createdAt": "2025-10-24T14:05:23",
+  "confidenceScore": 92,
+  "category": "DECISION"
+}
+```
+
+### 제안 카테고리 설명
+| 카테고리 | 설명 | 예시 |
+|---------|------|------|
+| DECISION | 의사결정 사항 | "타겟 고객층 20-30대로 결정" |
+| ACTION_ITEM | 실행 항목 | "11월 15일까지 프로토타입 완성" |
+| KEY_POINT | 핵심 요점 | "마케팅 예산 배분 논의" |
+| QUESTION | 질문 사항 | "추가 검토 필요" |
+
+## 📝 회의 메모 관리
+
+### 메모 저장 요청 예시
+```bash
+curl -X PUT http://localhost:8082/api/v1/stt/ai-suggestions/meetings/meeting-123/memo \
+  -H "Content-Type: application/json" \
+  -d '{
+    "meetingId": "meeting-123",
+    "memoContent": "[00:05] 신제품 타겟 고객층 논의\n[00:08] 개발 일정 수립\n[00:12] 마케팅 예산 배분",
+    "userId": "user-001"
+  }'
+```
+
+### 메모 저장 응답 예시
+```json
+{
+  "status": "success",
+  "data": {
+    "memoId": "memo-x9y8z7w6",
+    "meetingId": "meeting-123",
+    "memoContent": "[00:05] 신제품 타겟 고객층 논의\n[00:08] 개발 일정 수립\n[00:12] 마케팅 예산 배분",
+    "savedAt": "2025-10-24T14:10:00",
+    "userId": "user-001"
+  },
+  "timestamp": "2025-10-24T14:10:00"
+}
+```
+
+## 🧪 테스트 방법
+
+### 1. 서비스 시작
+```bash
+./gradlew stt:bootRun
+```
+
+### 2. Swagger UI 접속
+```
+http://localhost:8082/swagger-ui.html
+```
+
+### 3. 실시간 AI 제안사항 테스트
+```bash
+# SSE 스트리밍 연결 (터미널에서 테스트)
+curl -N http://localhost:8082/api/v1/stt/ai-suggestions/meetings/meeting-123/stream
+
+# 실시간으로 AI 제안사항이 표시됩니다 (10초마다)
+event: ai-suggestion
+id: suggestion-a1b2c3d4
+data: {"suggestionId":"suggestion-a1b2c3d4","meetingId":"meeting-123",...}
+```
+
+### 4. 회의 메모 API 테스트
+```bash
+# 메모 저장
+curl -X PUT http://localhost:8082/api/v1/stt/ai-suggestions/meetings/meeting-123/memo \
+  -H "Content-Type: application/json" \
+  -d '{"meetingId": "meeting-123", "memoContent": "[00:05] 테스트 메모", "userId": "user-001"}'
+
+# 메모 조회
+curl -X GET http://localhost:8082/api/v1/stt/ai-suggestions/meetings/meeting-123/memo
+```
+
+## 🚀 빌드 및 컴파일 결과
+- ✅ **컴파일 성공**: `./gradlew stt:compileJava`
+- ✅ **의존성 해결**: Spring WebFlux Reactor 추가
+- ✅ **코드 품질**: 컴파일 에러 없음, 타입 안전성 확보
+
+## 📝 백엔드개발가이드 준수 체크리스트
+
+### ✅ 개발원칙 준수
+- [x] 개발주석표준에 맞게 주석 작성
+- [x] API설계서와 일관성 있게 설계
+- [x] Layered 아키텍처 적용 및 Service 레이어 Interface 사용
+- [x] Gradle 빌드도구 사용
+- [x] 설정 Manifest 표준 준용
+
+### ✅ 개발순서 준수
+- [x] 참고자료 분석 및 이해 (회의진행.html 분석)
+- [x] DTO 작성 (AiSuggestionDto)
+- [x] Service 작성 (AiSuggestionService)
+- [x] Controller 작성 (AiSuggestionController)
+- [x] 컴파일 및 에러 해결
+- [x] Swagger 문서화
+
+### ✅ 설정 표준 준수
+- [x] 환경변수 사용 (하드코딩 없음)
+- [x] spring.application.name 설정
+- [x] OpenAPI 문서화 표준 적용
+- [x] Logging 표준 적용
+
+## 🎯 새로 추가된 주요 기능
+
+### 1. 실시간 AI 제안사항 스트리밍
+- **기술**: Server-Sent Events (SSE) 프로토콜
+- **장점**:
+  - 단방향 실시간 통신으로 WebSocket보다 가볍고 간단
+  - 자동 재연결 기능 내장
+  - HTTP 프로토콜 기반으로 방화벽 이슈 없음
+- **구현**: Spring WebFlux Flux를 활용한 Reactive 스트리밍
+
+### 2. AI 제안 카테고리 분류
+- **DECISION**: 회의에서 결정된 사항 자동 추출
+- **ACTION_ITEM**: 실행이 필요한 항목 자동 식별
+- **KEY_POINT**: 핵심 논의 사항 요약
+- **QUESTION**: 추가 검토가 필요한 질문사항
+
+### 3. 신뢰도 점수 (Confidence Score)
+- AI가 제안한 내용에 대한 신뢰도를 85-99 범위로 제공
+- 낮은 신뢰도의 제안은 필터링 가능
+
+### 4. 타임스탬프 통합
+- 녹음 시간(HH:MM:SS)과 함께 제안사항 제공
+- 메모에 시간 정보 자동 추가
+- 회의록 작성 시 정확한 시간 참조 가능
+
+## 📊 개발 완성도
+- **기능 구현**: 100% (9/9 API 완료)
+- **가이드 준수**: 100% (체크리스트 모든 항목 완료)
+- **코드 품질**: 우수 (컴파일 성공, 표준 준수)
+- **실시간 통신**: SSE 프로토콜 적용
+
+## 🔗 화면 연동
+
+### 회의진행.html과의 연동
+- **710-753라인**: "💬 AI가 실시간으로 분석한 제안사항" 영역
+- **SSE 연결**: EventSource API로 실시간 제안사항 수신
+- **메모 추가**: ➕ 버튼 클릭 시 제안사항을 메모에 추가
+- **자동 삭제**: 메모에 추가된 제안 카드는 자동으로 사라짐
+
+### 프론트엔드 구현 예시
+```javascript
+// 실시간 AI 제안사항 수신
+const eventSource = new EventSource(
+  `/api/v1/stt/ai-suggestions/meetings/${meetingId}/stream`
+);
+
+eventSource.addEventListener('ai-suggestion', (event) => {
+  const suggestion = JSON.parse(event.data);
+
+  // 화면에 AI 제안 카드 추가
+  const card = createAiSuggestionCard(suggestion);
+  document.getElementById('aiSuggestionList').appendChild(card);
+});
+
+// AI 제안을 메모에 추가
+function addToMemo(suggestionText, timestamp) {
+  const memo = document.getElementById('meetingMemo');
+  const timePrefix = `[${timestamp.substring(0, 5)}] `;
+  memo.value += `\n\n${timePrefix}${suggestionText}`;
+
+  // 메모 서버에 저장
+  saveMemoToServer();
+}
+
+// 메모 저장
+function saveMemoToServer() {
+  fetch(`/api/v1/stt/ai-suggestions/meetings/${meetingId}/memo`, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      meetingId: meetingId,
+      memoContent: document.getElementById('meetingMemo').value,
+      userId: currentUserId
+    })
+  });
+}
+```
+
+## 🚀 향후 개선 사항
+1. **실제 AI 엔진 연동**: 현재 Mock 데이터 → OpenAI/Azure AI 연동
+2. **다국어 지원**: 영어, 일본어 등 다국어 STT 지원
+3. **화자 식별**: 여러 참석자 음성 구분 및 식별
+4. **감정 분석**: 회의 분위기 및 감정 상태 분석
+5. **키워드 추출**: 핵심 키워드 자동 추출 및 태깅
+
+## 🔗 관련 문서
+- [회의진행 화면](../../design/uiux/prototype/05-회의진행.html)
+- [API 설계서](../../design/backend/api/)
+- [외부 시퀀스 설계서](../../design/backend/sequence/outer/)
+- [내부 시퀀스 설계서](../../design/backend/sequence/inner/)