feat: AI 서비스 Swagger UI 및 프론트엔드 연동 문서 추가

- Swagger UI를 Spring Boot 스타일(/swagger-ui.html)로 변경 - OpenAPI 스펙 개선 및 상세한 API 문서화 - 프론트엔드 연동을 위한 API-DOCUMENTATION.md 추가 - SSE 연결 예시 (JavaScript/React) - 응답 스키마 및 TypeScript 인터페이스 - 동작 흐름 및 주의사항 - FastAPI 설정 파일(config.py) 추가 - API 엔드포인트: - GET /api/v1/ai/suggestions/meetings/{meeting_id}/stream (SSE) - GET /health (헬스 체크) - GET /v3/api-docs (OpenAPI JSON) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-06-13 00:09:10 +00:00 · 2025-10-28 16:58:01 +09:00
parent 2c3bc432b3
commit 938cfdb98e
4 changed files with 388 additions and 6 deletions
@@ -17,7 +17,61 @@ settings = get_settings()
 claude_service = ClaudeService()


-@router.get("/meetings/{meeting_id}/stream")
+@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 스트리밍
@@ -0,0 +1,47 @@
+"""환경 설정"""
+from pydantic_settings import BaseSettings
+from functools import lru_cache
+
+
+class Settings(BaseSettings):
+    """애플리케이션 설정"""
+
+    # 서버 설정
+    app_name: str = "AI Service"
+    host: str = "0.0.0.0"
+    port: int = 8087
+    log_level: str = "INFO"
+
+    # Claude API
+    claude_api_key: str = ""
+    claude_model: str = "claude-3-5-sonnet-20241022"
+    claude_max_tokens: int = 2000
+    claude_temperature: float = 0.3
+
+    # Redis
+    redis_host: str = "20.249.177.114"
+    redis_port: int = 6379
+    redis_password: str = "Hi5Jessica!"
+    redis_db: int = 4
+
+    # Event Hub
+    eventhub_connection_string: str = ""
+    eventhub_name: str = "hgzero-eventhub-name"
+    eventhub_consumer_group: str = "$Default"
+
+    # AI 분석 설정
+    min_segments_for_analysis: int = 10
+    redis_ttl_seconds: int = 300  # 5분
+
+    # CORS
+    cors_origins: list = ["*"]
+
+    class Config:
+        env_file = ".env"
+        case_sensitive = False
+
+
+@lru_cache()
+def get_settings() -> Settings:
+    """설정 싱글톤"""
+    return Settings()