# 카카오맵 리뷰 분석 서비스 (교육용)

AI 기반 리뷰 분석을 통해 소상공인의 고객 피드백 관리를 지원하는 RESTful API 서비스입니다.

## ⚠️ 중요 법적 경고사항

**이 서비스는 교육 목적으로만 제작되었습니다.**

### 법적 위험
- 카카오 이용약관 위반 → 계정 정지, 법적 조치
- 개인정보보호법(PIPA) 위반 → 과태료 최대 3억원
- 저작권 및 데이터베이스권 침해 → 손해배상
- 업무방해죄 → 5년 이하 징역 또는 1천500만원 이하 벌금

### 합법적 대안
- **카카오 공식 API 활용** ([developers.kakao.com](https://developers.kakao.com))
- 점주 대상 자체 가게 관리 서비스 개발
- 사용자 동의 기반 데이터 수집 앱
- 카카오와 정식 파트너십 체결

**실제 서비스 사용을 금지합니다!**

---

## 📋 프로젝트 개요

### 주요 기능
- 🔍 **카카오맵 리뷰 분석**: HTML 파싱 및 Selenium 기반 동적 수집
- 🤖 **AI 기반 피드백**: Claude API 연동을 통한 맞춤형 개선 방안 제시
- 📊 **감정 분석**: 긍정/부정/중립 감정 분류 및 통계
- 💾 **Vector DB 연동**: 유사 케이스 검색 및 템플릿 활용
- 🚀 **RESTful API 제공**: FastAPI 기반의 완전한 API 서비스
- 📚 **Swagger UI 지원**: 자동 생성되는 API 문서
- ☸️ **Kubernetes 배포**: 완전한 컨테이너 오케스트레이션 지원
- 🔧 **환경변수 설정**: ConfigMap과 Secret을 통한 유연한 설정 관리

### 기술 스택
- **Backend**: Python 3.11, FastAPI, aiohttp
- **Web Scraping**: Selenium, BeautifulSoup4, Chrome WebDriver
- **AI/ML**: Claude AI API, Vector DB (Chroma)
- **Database**: PostgreSQL (향후), Vector DB
- **Container**: Docker, Multi-stage build
- **Orchestration**: Kubernetes (AKS)
- **Registry**: Azure Container Registry (ACR)
- **Documentation**: Swagger UI, ReDoc

## 🏗️ 프로젝트 구조

```
review-api/review/
├── app/                           # 애플리케이션 소스
│   ├── main.py                   # 메인 애플리케이션
│   └── requirements.txt          # Python 의존성
├── deployment/                    # 배포 관련 파일
│   ├── container/                # 컨테이너 이미지 빌드
│   │   ├── Dockerfile           # 서비스 이미지 빌드
│   │   └── Dockerfile-base      # 베이스 이미지 빌드
│   └── manifests/               # Kubernetes 매니페스트
│       ├── configmap.yaml       # 환경 설정
│       ├── secret.yaml          # 민감 정보 (API 키)
│       ├── deployment.yaml      # 애플리케이션 배포
│       ├── service.yaml         # 서비스 노출
│       └── ingress.yaml         # 외부 접근
├── build-base.sh                 # 베이스 이미지 빌드 스크립트
├── build.sh                      # 서비스 이미지 빌드 스크립트
├── create-imagepullsecret.sh     # ACR 인증 설정 스크립트
├── setup.sh                      # 로컬 환경 설정 스크립트
└── README.md                     # 프로젝트 문서
```

## 🚀 빠른 시작

### 1. 로컬 개발 환경 설정

```bash
# 저장소 클론 (review-api/review 디렉토리로 이동)
cd review-api/review

# 환경 설정 스크립트 실행
chmod +x setup.sh
./setup.sh

# 가상환경 활성화
source venv/bin/activate

# 애플리케이션 실행
python app/main.py
```

### 2. 로컬 웹 브라우저 접속

```bash
# 애플리케이션이 정상 실행된 후 아래 URL로 접속
```

- **메인 페이지**: http://localhost:19000
- **Swagger UI**: http://localhost:19000/docs
- **ReDoc**: http://localhost:19000/redoc
- **헬스체크**: http://localhost:19000/health
- **진단 정보**: http://localhost:19000/diagnostic
- **법적 경고**: http://localhost:19000/legal-warning

### 3. API 테스트 (교육용)

```bash
# 기본 리뷰 분석 (교육용 - 실제 사용 금지)
curl -X POST "http://localhost:19000/analyze" \
     -H "Content-Type: application/json" \
     -d '{
       "store_id": "501745730",
       "days_limit": 7,
       "max_time": 300
     }'

# 환경 설정 확인
curl "http://localhost:19000/config"

# 법적 경고사항 확인
curl "http://localhost:19000/legal-warning"
```

## 🐳 Docker 컨테이너 실행

### 베이스 이미지 빌드

```bash
# ACR에 베이스 이미지 빌드 및 푸시
./build-base.sh latest acrdigitalgarage03 rg-digitalgarage-03
```

### 서비스 이미지 빌드

```bash
# ACR에 서비스 이미지 빌드 및 푸시
./build.sh latest acrdigitalgarage03 rg-digitalgarage-03
```

### 로컬 Docker 실행

```bash
# 컨테이너 실행
docker run -p 19000:19000 \
  -e APP_TITLE="카카오맵 리뷰 분석 API" \
  -e PORT=19000 \
  kakao-review-api:latest

# 백그라운드 실행
docker run -d -p 19000:19000 \
  --name kakao-review-api \
  -e PORT=19000 \
  kakao-review-api:latest
```

## ☸️ Kubernetes 배포

### 1. ACR Image Pull Secret 생성

```bash
# Image Pull Secret 생성
./create-imagepullsecret.sh acrdigitalgarage03 rg-digitalgarage-03
```

### 2. Kubernetes 리소스 배포

```bash
# ConfigMap 및 Secret 적용
kubectl apply -f deployment/manifests/configmap.yaml
kubectl apply -f deployment/manifests/secret.yaml

# 애플리케이션 배포
kubectl apply -f deployment/manifests/deployment.yaml
kubectl apply -f deployment/manifests/service.yaml
kubectl apply -f deployment/manifests/ingress.yaml
```

### 3. 배포 상태 확인

```bash
# Pod 상태 확인
kubectl get pods -l app=kakao-review-api

# 서비스 상태 확인
kubectl get svc kakao-review-api-service

# Ingress 상태 확인
kubectl get ingress kakao-review-api-ingress

# 로그 확인
kubectl logs -l app=kakao-review-api -f
```

### 4. 🌐 외부 브라우저에서 접속하기

#### Ingress 주소 확인 방법

```bash
# 1. Ingress 설정된 호스트 확인
kubectl get ingress kakao-review-api-ingress -o jsonpath='{.spec.rules[0].host}'

# 2. Ingress External IP 확인 (LoadBalancer 타입인 경우)
kubectl get ingress kakao-review-api-ingress

# 3. Ingress Controller의 External IP 확인
kubectl get svc -n ingress-nginx ingress-nginx-controller

# 4. 현재 설정된 ingress 주소 확인
INGRESS_HOST=$(kubectl get ingress kakao-review-api-ingress -o jsonpath='{.spec.rules[0].host}')
echo "🌐 Review API URL: http://${INGRESS_HOST}"
```

#### 브라우저 접속 주소

현재 설정된 주소로 접속하세요:

```bash
# 현재 설정된 기본 주소 (환경에 따라 다를 수 있음)
INGRESS_URL="http://kakao-review-api.20.249.191.180.nip.io"
echo "브라우저에서 접속: ${INGRESS_URL}"
```

**주요 접속 페이지:**
- **🏠 메인 페이지**: http://kakao-review-api.20.249.191.180.nip.io
- **📖 Swagger UI**: http://kakao-review-api.20.249.191.180.nip.io/docs
- **📄 ReDoc**: http://kakao-review-api.20.249.191.180.nip.io/redoc
- **❤️ 헬스체크**: http://kakao-review-api.20.249.191.180.nip.io/health
- **🔧 진단 정보**: http://kakao-review-api.20.249.191.180.nip.io/diagnostic
- **⚠️ 법적 경고**: http://kakao-review-api.20.249.191.180.nip.io/legal-warning

#### 접속 테스트

```bash
# API 접속 테스트
curl "http://kakao-review-api.20.249.191.180.nip.io/health"

# 설정 정보 확인
curl "http://kakao-review-api.20.249.191.180.nip.io/config"

# Swagger UI 접속 확인
curl -I "http://kakao-review-api.20.249.191.180.nip.io/docs"

# 법적 경고 확인
curl "http://kakao-review-api.20.249.191.180.nip.io/legal-warning"
```

## ⚙️ 환경 설정

### 환경 변수

| 변수명 | 기본값 | 설명 |
|--------|--------|------|
| `APP_TITLE` | `카카오맵 리뷰 분석 API` | 애플리케이션 제목 |
| `APP_VERSION` | `1.0.1` | 애플리케이션 버전 |
| `HOST` | `0.0.0.0` | 서버 호스트 |
| `PORT` | `19000` | 서버 포트 |
| `DEFAULT_MAX_TIME` | `300` | 기본 최대 스크롤 시간(초) |
| `DEFAULT_DAYS_LIMIT` | `60` | 기본 날짜 제한(일) |
| `MAX_DAYS_LIMIT` | `365` | 최대 날짜 제한(일) |
| `CHROME_OPTIONS` | `--headless...` | Chrome 브라우저 옵션 |
| `LEGAL_WARNING_ENABLED` | `true` | 법적 경고 표시 여부 |
| `CONTACT_EMAIL` | `admin@example.com` | 연락처 이메일 |

### Chrome 및 Selenium 설정

현재 서비스는 Chrome WebDriver를 사용합니다:

```bash
# Chrome 설치 확인
google-chrome --version

# ChromeDriver 설치 확인
chromedriver --version

# Selenium 테스트
python -c "from selenium import webdriver; print('Selenium 설치됨')"
```

## 📊 API 엔드포인트

### 주요 엔드포인트

| Method | Endpoint | 설명 |
|--------|----------|------|
| `GET` | `/` | 메인 페이지 |
| `GET` | `/docs` | Swagger UI 문서 |
| `GET` | `/health` | 헬스체크 |
| `GET` | `/diagnostic` | 시스템 진단 정보 |
| `POST` | `/analyze` | 리뷰 분석 수행 (교육용) |
| `GET` | `/config` | 환경 설정 확인 |
| `GET` | `/legal-warning` | 법적 경고사항 |

### 리뷰 분석 API 예시 (교육용)

```json
POST /analyze
{
  "store_id": "501745730",
  "days_limit": 7,
  "max_time": 300
}
```

**응답:**
```json
{
  "success": true,
  "message": "분석이 성공적으로 완료되었습니다.",
  "store_info": {
    "id": "501745730",
    "name": "맛있는 식당",
    "category": "한식",
    "rating": "4.2",
    "review_count": "1,234"
  },
  "reviews": [...],
  "analysis_date": "2024-06-12T10:30:00",
  "total_reviews": 25,
  "execution_time": 45.2
}
```

## 🔧 개발 및 확장

### 로컬 개발

```bash
# 개발 모드로 실행 (자동 재시작)
uvicorn app.main:app --host 0.0.0.0 --port 19000 --reload

# 의존성 추가
pip install 새패키지명
pip freeze > app/requirements.txt

# 코드 포맷팅
black app/main.py
flake8 app/main.py
```

### Ingress 호스트 변경

현재 환경에 맞게 Ingress 호스트를 변경하려면:

```bash
# 1. 현재 External IP 확인
kubectl get svc -n ingress-nginx ingress-nginx-controller

# 2. deployment/manifests/ingress.yaml 파일에서 host 수정
# 예: kakao-review-api.{YOUR_EXTERNAL_IP}.nip.io

# 3. 변경사항 적용
kubectl apply -f deployment/manifests/ingress.yaml

# 4. 새로운 주소 확인
kubectl get ingress kakao-review-api-ingress
```

## 🐛 문제 해결

### 일반적인 문제

**1. Chrome WebDriver 관련 문제**
```bash
# Chrome 설치 상태 확인
docker run --rm kakao-review-api:latest google-chrome --version

# ChromeDriver 버전 확인
docker run --rm kakao-review-api:latest chromedriver --version

# 헤드리스 모드 테스트
curl -X POST "http://localhost:19000/analyze" \
     -H "Content-Type: application/json" \
     -d '{"store_id": "test", "days_limit": 1, "max_time": 30}'
```

**2. Kubernetes 배포 실패**
```bash
# Pod 로그 확인 (Chrome 에러 확인)
kubectl logs -l app=kakao-review-api

# ConfigMap 확인
kubectl get configmap kakao-review-api-config -o yaml

# 리소스 사용량 확인 (Chrome이 메모리를 많이 사용함)
kubectl top pods -l app=kakao-review-api
```

**3. Ingress 접속 실패**
```bash
# Ingress Controller 상태 확인
kubectl get pods -n ingress-nginx

# Ingress 규칙 확인
kubectl describe ingress kakao-review-api-ingress

# Service 연결 확인
kubectl get endpoints kakao-review-api-service

# 타임아웃 설정 확인 (Chrome 분석은 시간이 오래 걸림)
kubectl get ingress kakao-review-api-ingress -o yaml | grep timeout
```

**4. 포트 관련 문제**
- 로컬 개발: 19000번 포트 사용
- Docker 컨테이너: 19000번 포트로 실행
- Kubernetes: 19000번 포트로 실행 (Service에서 80번으로 노출, Ingress를 통해 외부 접근)

**5. 법적 문제 회피**
```bash
# 법적 경고 항상 확인
curl "http://kakao-review-api.20.249.191.180.nip.io/legal-warning"

# 교육용임을 명시하는 환경변수 설정
export LEGAL_WARNING_ENABLED=true
export EDUCATIONAL_USE_ONLY=true
```

## 🎯 성능 최적화

### Chrome 최적화 설정

```yaml
# deployment.yaml에서 Chrome 최적화를 위한 리소스 설정
resources:
  requests:
    memory: "1Gi"     # Chrome은 메모리를 많이 사용
    cpu: "500m"
  limits:
    memory: "2Gi"     # Chrome 분석을 위한 충분한 메모리
    cpu: "1000m"
```

### 타임아웃 설정

```yaml
# ingress.yaml에서 긴 분석 시간을 고려한 타임아웃
nginx.ingress.kubernetes.io/proxy-read-timeout: "1800"    # 30분
nginx.ingress.kubernetes.io/proxy-send-timeout: "1800"    # 30분
```

## 📈 향후 확장 계획

- [ ] **Claude AI 연동**: 리뷰 분석 및 개선 방안 자동 생성
- [ ] **Vector DB 구축**: 유사 케이스 검색 및 템플릿 관리
- [ ] **PostgreSQL 연동**: 분석 결과 영구 저장
- [ ] **다중 플랫폼 지원**: 네이버, 구글 등 추가 플랫폼 (합법적 방법으로)
- [ ] **실시간 분석**: WebSocket 기반 실시간 피드백
- [ ] **사용자 인증**: JWT 기반 인증 시스템
- [ ] **대시보드**: 분석 결과 시각화
- [ ] **알림 시스템**: 새로운 리뷰 알림 기능
- [ ] **감정 분석 고도화**: 더 정확한 감정 분류
- [ ] **비즈니스 통찰**: AI 기반 개선 방안 제시

## ⚖️ 법적 준수 사항

### 필수 확인 사항

1. **교육용 목적으로만 사용**
2. **실제 서비스 환경에서 사용 금지**
3. **카카오 이용약관 준수**
4. **개인정보보호법 준수**
5. **저작권 침해 금지**

### 권장 대안

1. **카카오 공식 API 사용**
2. **자체 플랫폼 개발**
3. **사용자 동의 기반 수집**
4. **정식 파트너십 체결**

---

## 📞 지원 및 문의

- **이슈 리포트**: GitHub Issues
- **기술 문의**: 개발팀 Slack
- **법적 문의**: 법무팀
- **API 문서**: Swagger UI에서 상세 확인

---

**⚠️ 재고지: 이 서비스는 교육용으로만 제작되었으며, 실제 운영 환경에서의 사용을 엄격히 금지합니다.**