# 로빙 MVP 설정 가이드

## 📋 목차
1. [환경 설정](#환경-설정)
2. [Slack 앱 설정](#slack-앱-설정)
3. [OpenAI API 설정](#openai-api-설정)
4. [데이터베이스 설정](#데이터베이스-설정)
5. [서버 실행](#서버-실행)
6. [테스트](#테스트)

## 🔧 환경 설정

### 1. 시스템 요구사항
- Python 3.12+
- PostgreSQL 13+
- Git

### 2. 프로젝트 클론 및 설정
```bash
# 저장소 클론
git clone https://github.com/happybell80/ivada.git
cd ivada

# 가상환경 생성
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate  # Windows

# 의존성 설치
pip install -r requirements.txt
```

### 3. 환경변수 설정
`.env` 파일을 생성하고 다음 내용을 입력:

```env
# Slack Configuration
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_SIGNING_SECRET=your-signing-secret
SLACK_APP_TOKEN=xapp-your-app-token

# OpenAI Configuration
OPENAI_API_KEY=your-openai-api-key

# Database Configuration
DATABASE_URL=postgresql://user:password@localhost/ivada_db
TEST_DATABASE_URL=postgresql://user:password@localhost/ivada_test_db

# JWT Configuration
JWT_SECRET_KEY=your-jwt-secret-key-change-in-production
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30

# Application Configuration
DEBUG=True
LOG_LEVEL=INFO
MAX_MEMORY_SIZE=1000
```

## 📱 Slack 앱 설정

### 1. Slack 앱 생성
1. https://api.slack.com/apps 접속
2. **"Create New App"** 클릭
3. **"From scratch"** 선택
4. App Name: **"Roving"** 입력
5. 워크스페이스 선택 후 **"Create App"** 클릭

### 2. Bot Token 권한 설정
**OAuth & Permissions** 페이지에서 다음 Bot Token Scopes 추가:

#### 필수 권한
- `app_mentions:read` - 앱 멘션 읽기
- `channels:read` - 채널 정보 읽기
- `chat:write` - 메시지 전송
- `chat:write.public` - 공개 채널에 메시지 전송
- `im:read` - DM 읽기
- `im:write` - DM 전송
- `users:read` - 사용자 정보 읽기

#### 선택 권한
- `mpim:read` - 그룹 DM 읽기
- `mpim:write` - 그룹 DM 전송
- `files:read` - 파일 읽기
- `files:write` - 파일 업로드

### 3. 앱 설치 및 토큰 획득
1. **"Install to Workspace"** 클릭
2. 권한 승인
3. **Bot User OAuth Token** 복사 (xoxb-로 시작)
4. **"Basic Information"** 페이지에서 **Signing Secret** 복사

### 4. 연동 방식 선택

#### 방법 A: HTTP 연동 (ngrok 사용)

1. **ngrok 설치**
   ```bash
   # Linux/Mac
   wget https://bin.equinox.io/c/bNyj1mQVY4c/ngrok-v3-stable-linux-amd64.tgz
   tar xzf ngrok-v3-stable-linux-amd64.tgz
   
   # ngrok 계정 생성: https://dashboard.ngrok.com/signup
   # authtoken 설정
   ./ngrok config add-authtoken YOUR_AUTHTOKEN
   ```

2. **Event Subscriptions 설정**
   - Slack 앱 → **"Event Subscriptions"** → **"Enable Events"** ON
   - **Request URL**: `https://your-ngrok-url.ngrok.io/api/slack/events`
   - **Subscribe to bot events**:
     - `app_mention`
     - `message.channels`
     - `message.groups`
     - `message.im`
     - `message.mpim`

#### 방법 B: Socket Mode 연동

1. **Socket Mode 활성화**
   - Slack 앱 → **"Socket Mode"** → **"Enable Socket Mode"** ON

2. **App-Level Token 생성**
   - Token Name: **"Roving Socket Token"**
   - Scopes: `connections:write`
   - **App Token** 복사 (xapp-로 시작)

## 🤖 OpenAI API 설정

### 1. API 키 발급
1. https://platform.openai.com/api-keys 접속
2. **"Create new secret key"** 클릭
3. API 키 복사하여 `.env`의 `OPENAI_API_KEY`에 설정

### 2. 사용량 모니터링
- https://platform.openai.com/usage 에서 사용량 확인
- 필요시 사용량 제한 설정

## 🗄️ 데이터베이스 설정

### 1. PostgreSQL 설치 및 설정
```bash
# Ubuntu/Debian
sudo apt update
sudo apt install postgresql postgresql-contrib

# macOS (Homebrew)
brew install postgresql
brew services start postgresql

# 데이터베이스 생성
sudo -u postgres createdb ivada_db
sudo -u postgres createdb ivada_test_db
```

### 2. 데이터베이스 사용자 생성
```sql
-- PostgreSQL 콘솔에서 실행
sudo -u postgres psql

CREATE USER ivada_user WITH ENCRYPTED PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE ivada_db TO ivada_user;
GRANT ALL PRIVILEGES ON DATABASE ivada_test_db TO ivada_user;
```

### 3. 환경변수 업데이트
```env
DATABASE_URL=postgresql://ivada_user:your_password@localhost/ivada_db
TEST_DATABASE_URL=postgresql://ivada_user:your_password@localhost/ivada_test_db
```

## 🚀 서버 실행

### 1. HTTP 서버 실행 (ngrok 사용)
```bash
# 터미널 1: FastAPI 서버
source venv/bin/activate
python run.py

# 터미널 2: ngrok 터널
./ngrok http 8000
```

### 2. Socket Mode 실행
```bash
source venv/bin/activate
python socket_run.py
```

### 3. 실행 확인
- HTTP: http://localhost:8000
- API 문서: http://localhost:8000/docs
- ngrok 모니터링: http://localhost:4040

## 🧪 테스트

### 1. API 테스트
```bash
# 서버 상태 확인
curl http://localhost:8000/health

# 메시지 처리 테스트
curl -X POST "http://localhost:8000/api/test/message" \
     -H "Content-Type: application/json" \
     -d '{"text": "안녕하세요", "user_id": "test_user"}'
```

### 2. Slack 테스트
1. **봇 초대**: `/invite @Roving`
2. **직접 메시지**: `안녕하세요 로빙!`
3. **멘션 테스트**: `@Roving 오늘 할 일을 정리해주세요`

### 3. 예상 응답
```
안녕하세요! 테스트 모드에서 실행 중입니다. 메시지를 받았습니다: '[메시지]'
```

## 🐛 문제 해결

### Slack 연동 문제
- **봇이 응답하지 않음**: Event Subscriptions 설정 확인
- **권한 오류**: Bot Token Scopes 재확인
- **URL 검증 실패**: ngrok URL 및 서버 실행 상태 확인

### 서버 실행 문제
- **포트 충돌**: `lsof -i :8000`으로 포트 사용 확인
- **의존성 오류**: `pip install -r requirements.txt` 재실행
- **환경변수 오류**: `.env` 파일 경로 및 내용 확인

### 데이터베이스 연결 문제
- **연결 실패**: PostgreSQL 서비스 실행 상태 확인
- **권한 오류**: 사용자 권한 재설정
- **인코딩 문제**: UTF-8 인코딩 설정 확인

## 📞 지원

추가 도움이 필요하시면:
- [GitHub Issues](https://github.com/happybell80/ivada/issues)
- [개발 일지](development-log.md) 참조
- [Slack API 문서](https://api.slack.com/web) 참조