hgzero/ai-python/API-DOCUMENTATION.md

# 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초마다 체크합니다.