hgzero/docs/eventhub-setup-guide.md

# EventHub 재설정 가이드

## 📋 개요
EventHub 공유 액세스 정책이 초기화되어 재설정이 필요합니다.

### 현재 EventHub 정보
- **EventHub 이름**: `hgzero-eventhub-name`
- **네임스페이스**: `hgzero-eventhub-ns.servicebus.windows.net`
- **소비자 그룹**: `$Default`
- **상태**: 공유 액세스 정책 없음 (재생성 필요)

---

## 🔐 1단계: Azure Portal에서 공유 액세스 정책 생성

### 1.1 send-policy 생성 (STT 서비스용)

1. Azure Portal → EventHubs → `hgzero-eventhub-ns` → `hgzero-eventhub-name`
2. 좌측 메뉴에서 **"공유 액세스 정책"** 클릭
3. **"+ 추가"** 버튼 클릭
4. 다음 정보 입력:
   - **정책 이름**: `send-policy`
   - **권한**: ☑️ Send (보내기만 체크)
5. **"만들기"** 클릭

### 1.2 listen-policy 생성 (AI, Meeting 서비스용)

1. 동일한 공유 액세스 정책 화면에서 **"+ 추가"** 클릭
2. 다음 정보 입력:
   - **정책 이름**: `listen-policy`
   - **권한**: ☑️ Listen (수신 대기만 체크)
3. **"만들기"** 클릭

---

## 📝 2단계: 연결 문자열 복사

### 2.1 send-policy 연결 문자열

1. 생성된 `send-policy` 클릭
2. **"연결 문자열-기본 키"** 복사
3. ⚠️ **중요**: EntityPath 제거 필요

```
원본:
Endpoint=sb://hgzero-eventhub-ns.servicebus.windows.net/;SharedAccessKeyName=send-policy;SharedAccessKey=xxxxx;EntityPath=hgzero-eventhub-name

수정 후 (EntityPath 제거):
Endpoint=sb://hgzero-eventhub-ns.servicebus.windows.net/;SharedAccessKeyName=send-policy;SharedAccessKey=xxxxx
```

### 2.2 listen-policy 연결 문자열

1. 생성된 `listen-policy` 클릭
2. **"연결 문자열-기본 키"** 복사
3. ⚠️ **중요**: EntityPath 제거 필요

```
수정 후:
Endpoint=sb://hgzero-eventhub-ns.servicebus.windows.net/;SharedAccessKeyName=listen-policy;SharedAccessKey=xxxxx
```

---

## 🔧 3단계: 서비스별 설정 업데이트

### 3.1 STT 서비스 (.env 파일)

**파일**: `stt/src/main/resources/.env`

```env
# Azure Event Hub (send-policy - Send 권한, EntityPath 제거)
EVENTHUB_CONNECTION_STRING=Endpoint=sb://hgzero-eventhub-ns.servicebus.windows.net/;SharedAccessKeyName=send-policy;SharedAccessKey=[YOUR_SEND_KEY]
EVENTHUB_NAME=hgzero-eventhub-name
```

### 3.2 AI-Python 서비스 (.env 파일)

**파일**: `ai-python/.env`

```env
# Azure Event Hub (listen-policy - Listen 권한, EntityPath 제거)
EVENTHUB_CONNECTION_STRING=Endpoint=sb://hgzero-eventhub-ns.servicebus.windows.net/;SharedAccessKeyName=listen-policy;SharedAccessKey=[YOUR_LISTEN_KEY]
EVENTHUB_NAME=hgzero-eventhub-name
EVENTHUB_CONSUMER_GROUP=$Default
```

### 3.3 Meeting 서비스 (IntelliJ 실행 프로파일)

**파일**: `meeting/.run/MeetingApplication.run.xml`

`<option name="env">` 섹션에 다음 환경 변수 추가:

```xml
<env name="EVENTHUB_CONNECTION_STRING" value="Endpoint=sb://hgzero-eventhub-ns.servicebus.windows.net/;SharedAccessKeyName=listen-policy;SharedAccessKey=[YOUR_LISTEN_KEY]" />
<env name="EVENTHUB_NAME" value="hgzero-eventhub-name" />
```

---

## 🚀 4단계: 서비스 재시작

### 4.1 STT 서비스
```bash
cd /Users/jominseo/HGZero/stt
./restart.sh
```

### 4.2 AI-Python 서비스
```bash
cd /Users/jominseo/HGZero/ai-python
./restart.sh
```

### 4.3 Meeting 서비스
IntelliJ에서 `MeetingApplication` 실행 프로파일 재시작

---

## ✅ 5단계: 연결 확인

### 5.1 STT 서비스 로그 확인
```bash
tail -f /Users/jominseo/HGZero/logs/stt-service.log | grep -i eventhub
```

**성공 메시지 예시**:
```
EventHub 연결 성공
EventHub Producer 초기화 완료
```

### 5.2 AI-Python 서비스 로그 확인
```bash
tail -f /Users/jominseo/HGZero/logs/ai-python.log | grep -i eventhub
```

**성공 메시지 예시**:
```
Event Hub 리스너 시작 성공
EventProcessor 연결 완료
```

**실패 메시지 (이전)**:
```
AuthenticationError('CBS Token authentication failed')
Event Hub 리스너 오류: 'NoneType' object has no attribute 'eventhub_name'
```

### 5.3 Meeting 서비스 로그 확인
IntelliJ 콘솔에서 확인:
```
EventHub 연결 초기화 완료
EventHub Consumer 시작
```

---

## 🔍 트러블슈팅

### 문제 1: 인증 실패 (Authentication Error)
**원인**: 연결 문자열이 잘못되었거나 권한이 부족
**해결**:
1. 연결 문자열에 EntityPath가 포함되지 않았는지 확인
2. 정책 권한 확인 (STT: Send, AI/Meeting: Listen)
3. SharedAccessKey가 정확한지 확인

### 문제 2: EventHub 이름 오류
**원인**: EVENTHUB_NAME 환경 변수 누락 또는 오타
**해결**:
1. `.env` 파일 또는 실행 프로파일에 `EVENTHUB_NAME=hgzero-eventhub-name` 확인
2. 오타 체크: `hgzero-eventhub-name` (정확히 일치해야 함)

### 문제 3: 소비자 그룹 오류
**원인**: EVENTHUB_CONSUMER_GROUP 잘못 설정
**해결**:
```env
# 올바른 형식 (작은따옴표 제거)
EVENTHUB_CONSUMER_GROUP=$Default
```

---

## 📌 체크리스트

- [ ] Azure Portal에서 `send-policy` 생성 (Send 권한)
- [ ] Azure Portal에서 `listen-policy` 생성 (Listen 권한)
- [ ] `send-policy` 연결 문자열 복사 (EntityPath 제거)
- [ ] `listen-policy` 연결 문자열 복사 (EntityPath 제거)
- [ ] STT 서비스 `.env` 파일 업데이트
- [ ] AI-Python 서비스 `.env` 파일 업데이트
- [ ] Meeting 서비스 실행 프로파일 업데이트
- [ ] STT 서비스 재시작
- [ ] AI-Python 서비스 재시작
- [ ] Meeting 서비스 재시작
- [ ] 모든 서비스 로그에서 EventHub 연결 성공 확인

---

## 🎯 다음 단계

설정 완료 후:
1. STT 테스트 페이지로 음성 녹음 테스트
2. AI 서비스가 EventHub에서 메시지 수신 확인
3. Meeting 서비스가 회의록 업데이트 수신 확인

---

**작성일**: 2025-10-29
**작성자**: 준호 (Backend Developer)