# 🍽️ Vector - 음식점 Vector DB 구축 및 AI 추천 서비스

카카오 로컬 API를 활용하여 음식점 정보와 리뷰를 수집하고, **Chroma DB** 기반 Vector DB로 구축한 후, **Claude AI**와 연동하여 소상공인의 비즈니스 개선을 지원하는 마이크로서비스입니다.

## 🎯 프로젝트 개요

### 핵심 기능
- **🔍 스마트 음식점 검색**: 지역과 가게명으로 타겟 음식점 자동 발견
- **📊 동종업체 리뷰 수집**: 카카오맵 리뷰 대량 수집 및 전처리
- **🤖 Vector DB 구축**: Sentence Transformers 기반 고품질 임베딩 생성
- **🧠 AI 비즈니스 컨설팅**: Claude Sonnet 4 기반 맞춤형 액션 플랜 제공
- **🔄 실시간 API 서비스**: RESTful API 기반 완전 자동화 시스템
- **☸️ 클라우드 네이티브**: Kubernetes 기반 확장 가능한 마이크로서비스

### 비즈니스 가치
- **소상공인**: 동종업체 분석을 통한 데이터 기반 경영 개선
- **경쟁 우위**: AI 기반 개인화된 비즈니스 전략 제공
- **운영 효율**: 완전 자동화된 분석 및 추천 시스템

## 🏗️ 기술 아키텍처

### 🔧 백엔드 스택
- **Framework**: FastAPI 0.115.9 (고성능 비동기 API)
- **Language**: Python 3.11 (최신 타입 힌팅 지원)
- **Dependency Management**: Poetry (락 파일 기반 재현 가능한 빌드)

### 🤖 AI/ML 스택
- **Vector DB**: ChromaDB 1.0.12 (HNSW 알고리즘 기반)
- **Embedding Model**: `sentence-transformers/all-MiniLM-L6-v2` (384차원)
- **AI Engine**: Claude Sonnet 4 (`claude-sonnet-4-20250514`)
- **ML Framework**: PyTorch 2.7.1+cpu, Transformers 4.52.4

### 🚀 인프라 스택
- **Container**: Docker (Multi-stage build 최적화)
- **Orchestration**: Kubernetes (AKS 배포)
- **Registry**: Azure Container Registry (ACR)
- **Storage**: Persistent Volume (Vector DB 데이터 영속화)

### 🔗 외부 연동
- **Restaurant API**: 카카오 로컬 API 기반 음식점 검색 서비스
- **Review API**: 카카오맵 리뷰 수집 서비스
- **Claude API**: Anthropic Claude AI API

## 📁 프로젝트 구조

```
vector/
├── app/                          # 메인 애플리케이션
│   ├── main.py                  # FastAPI 애플리케이션 엔트리포인트
│   ├── config/
│   │   └── settings.py          # 환경별 설정 관리
│   ├── models/                  # Pydantic 데이터 모델
│   │   ├── vector_models.py     # Vector DB 요청/응답 모델
│   │   ├── restaurant_models.py # 음식점 정보 모델
│   │   └── review_models.py     # 리뷰 데이터 모델
│   ├── services/                # 비즈니스 로직 서비스
│   │   ├── vector_service.py    # Vector DB 관리 서비스
│   │   ├── claude_service.py    # Claude AI 통합 서비스
│   │   ├── restaurant_service.py # 음식점 검색 서비스
│   │   └── review_service.py    # 리뷰 수집 서비스
│   └── utils/
│       └── category_utils.py    # 음식 카테고리 추출 유틸
├── deployment/                   # 배포 인프라
│   ├── container/
│   │   ├── Dockerfile          # 메인 서비스 이미지
│   │   └── Dockerfile-base     # 베이스 의존성 이미지
│   └── manifests/              # Kubernetes 리소스
│       ├── configmap.yaml      # 환경 설정
│       ├── secret.yaml         # API 키 등 민감 정보
│       ├── deployment.yaml     # 애플리케이션 배포
│       ├── service.yaml        # 내부 서비스 노출
│       ├── ingress.yaml        # 외부 접근 설정
│       └── pvc.yaml            # Vector DB 영구 볼륨
├── pyproject.toml               # Poetry 의존성 정의
├── poetry.lock                  # 의존성 락 파일
├── setup.sh                     # 로컬 개발 환경 자동 설정
├── build-base.sh               # 베이스 이미지 빌드
├── build.sh                    # 메인 이미지 빌드
├── create-imagepullsecret.sh   # ACR 인증 설정
└── README.md                   # 프로젝트 문서
```

## 📊 API 엔드포인트

### 🏠 메인 서비스
| Method | Endpoint | 설명 | 요청 모델 | 응답 모델 |
|--------|----------|------|-----------|-----------|
| `GET` | `/` | 서비스 홈페이지 (HTML) | - | HTMLResponse |
| `GET` | `/docs` | Swagger UI API 문서 | - | HTMLResponse |
| `GET` | `/health` | 헬스체크 | - | JSONResponse |
| `GET` | `/vector-status` | Vector DB 상태 확인 | - | VectorDBStatusResponse |

### 🔍 핵심 비즈니스 API
| Method | Endpoint | 설명 | 요청 모델 | 응답 모델 |
|--------|----------|------|-----------|-----------|
| `POST` | `/find-reviews` | 리뷰 수집 및 Vector DB 저장 | VectorBuildRequest | FindReviewsResponse |
| `POST` | `/action-recommendation` | AI 기반 비즈니스 추천 | ActionRecommendationRequest | ActionRecommendationSimpleResponse |

## 🚀 빠른 시작

### 1. 사전 준비

#### 필수 API 키 발급

**카카오 API 설정**
```bash
# 1. 카카오 개발자 센터 접속
https://developers.kakao.com/console/app

# 2. 애플리케이션 등록
- 앱 이름: VectorDBBuilder
- 카테고리: 식음료

# 3. 카카오맵 API 활성화
- 좌측 메뉴 > 카카오맵 > 활성화
```

**Claude API 설정**
```bash
# 1. Anthropic Console 접속
https://console.anthropic.com/

# 2. API 키 발급
- API Keys 메뉴에서 새 키 생성
- 모델: claude-sonnet-4-20250514
```

### 2. 로컬 개발 환경

#### 자동 환경 설정
```bash
# 저장소 클론
git clone <repository-url>
cd vector

# Poetry 및 의존성 자동 설치
chmod +x setup.sh
./setup.sh
```

#### 환경변수 설정
```bash
# .env 파일 생성
cat > .env << EOF
# Claude API 설정
CLAUDE_API_KEY=your-claude-api-key
CLAUDE_MODEL=claude-sonnet-4-20250514

# API 서버 설정 (로컬 개발용)
RESTAURANT_API_HOST=0.0.0.0
RESTAURANT_API_PORT=18000
REVIEW_API_HOST=0.0.0.0
REVIEW_API_PORT=19000

# Vector DB 설정
VECTOR_DB_PATH=./vectordb
VECTOR_DB_COLLECTION=restaurant_reviews
EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2

# 애플리케이션 설정
HOST=0.0.0.0
PORT=8000
LOG_LEVEL=info
EOF
```

#### 서비스 실행
```bash
# 개발 모드 (자동 재시작)
poetry run uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# 또는 직접 실행
poetry run python app/main.py
```

### 3. Docker 실행

```bash
# 베이스 이미지 빌드 (의존성 캐싱)
./build-base.sh

# 메인 서비스 이미지 빌드
./build.sh

# 컨테이너 실행 (환경변수 파일 사용)
docker run -p 8000:8000 --env-file .env vector-api:latest
```

### 4. Kubernetes 배포

#### ACR 인증 설정
```bash
# Azure Container Registry 인증
./create-imagepullsecret.sh acrdigitalgarage03 rg-digitalgarage-03
```

#### 리소스 배포
```bash
# 1. 영구 볼륨 생성 (Vector DB 저장용)
kubectl apply -f deployment/manifests/pvc.yaml

# 2. 설정 정보 생성
kubectl apply -f deployment/manifests/configmap.yaml
kubectl apply -f deployment/manifests/secret.yaml

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

#### 배포 상태 확인
```bash
# Pod 상태 확인
kubectl get pods -l app=vector-api

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

# Ingress 확인
kubectl get ingress vector-api-ingress

# 로그 모니터링
kubectl logs -l app=vector-api -f
```

## 🌐 서비스 접속

### 배포된 서비스 URL

```bash
# 현재 배포된 서비스 주소
INGRESS_URL="http://vector-api.20.249.191.180.nip.io"
```

| 서비스 | URL | 설명 |
|--------|-----|------|
| **🏠 홈페이지** | http://vector-api.20.249.191.180.nip.io | 서비스 대시보드 |
| **📖 API 문서** | http://vector-api.20.249.191.180.nip.io/docs | Swagger UI |
| **📄 ReDoc** | http://vector-api.20.249.191.180.nip.io/redoc | API 문서 (ReDoc) |
| **❤️ 헬스체크** | http://vector-api.20.249.191.180.nip.io/health | 서비스 상태 |
| **🗂️ Vector DB 상태** | http://vector-api.20.249.191.180.nip.io/vector-status | DB 상태 확인 |

### 접속 테스트

```bash
# 서비스 상태 확인
curl "http://vector-api.20.249.191.180.nip.io/health"

# Vector DB 상태 확인
curl "http://vector-api.20.249.191.180.nip.io/vector-status"
```

## 💡 API 사용 예제

### 1. 리뷰 수집 및 Vector DB 구축

**요청**
```bash
curl -X POST "http://vector-api.20.249.191.180.nip.io/find-reviews" \
  -H "Content-Type: application/json" \
  -d '{
    "region": "서울특별시 강남구 역삼동",
    "store_name": "맛있는 치킨집"
  }'
```

**응답**
```json
{
  "success": true,
  "message": "총 127개 리뷰, 8개 업체 분석됨",
  "target_store": {
    "id": "501745730",
    "place_name": "맛있는 치킨집",
    "category_name": "음식점 > 치킨",
    "address_name": "서울특별시 강남구 역삼동 123-45",
    "phone": "02-123-4567",
    "place_url": "http://place.map.kakao.com/501745730",
    "x": "127.0276543",
    "y": "37.4979234"
  },
  "food_category": "치킨",
  "total_reviews": 127,
  "total_stores": 8,
  "execution_time": 45.2,
  "stored_data": {
    "501745730": {
      "store_info": {
        "id": "501745730",
        "name": "맛있는 치킨집",
        "category": "음식점 > 치킨",
        "rating": "4.2",
        "review_count": "23",
        "status": "영업중",
        "address": "서울특별시 강남구 역삼동 123-45",
        "phone": "02-123-4567",
        "place_url": "http://place.map.kakao.com/501745730",
        "x": "127.0276543",
        "y": "37.4979234"
      },
      "reviews": [
        {
          "reviewer_name": "김○○",
          "reviewer_level": "골드리뷰어",
          "reviewer_stats": {
            "reviews": 156,
            "average_rating": 4.3,
            "followers": 23
          },
          "rating": 5,
          "date": "2024-06-10",
          "content": "치킨이 정말 맛있어요! 바삭하고 양념이 잘 배어있어서 자꾸 손이 갑니다. 배달도 빨라서 좋았어요.",
          "badges": ["맛집", "친절", "빠른배달"],
          "likes": 12,
          "photo_count": 3,
          "has_photos": true
        },
        {
          "reviewer_name": "이○○",
          "reviewer_level": "실버리뷰어",
          "reviewer_stats": {
            "reviews": 89,
            "average_rating": 4.1,
            "followers": 8
          },
          "rating": 4,
          "date": "2024-06-08",
          "content": "치킨은 맛있는데 가격이 조금 비싼 것 같아요. 그래도 재주문 의향 있습니다.",
          "badges": ["맛있음", "가격"],
          "likes": 7,
          "photo_count": 1,
          "has_photos": true
        },
        {
          "reviewer_name": "박○○",
          "reviewer_level": "브론즈리뷰어",
          "reviewer_stats": {
            "reviews": 34,
            "average_rating": 3.9,
            "followers": 2
          },
          "rating": 3,
          "date": "2024-06-05",
          "content": "치킨은 괜찮은데 배달이 좀 늦었어요. 포장도 조금 아쉬웠습니다.",
          "badges": ["배달지연", "포장"],
          "likes": 3,
          "photo_count": 0,
          "has_photos": false
        }
      ],
      "review_summary": {
        "total_reviews": 23,
        "average_rating": 4.2,
        "rating_distribution": {
          "5": 8,
          "4": 9,
          "3": 4,
          "2": 1,
          "1": 1
        },
        "positive_keywords": [
          "맛있음",
          "바삭함",
          "친절",
          "빠른배달"
        ],
        "negative_keywords": [
          "가격",
          "배달지연",
          "포장"
        ],
        "common_keywords": [
          "맛있음",
          "치킨",
          "배달",
          "친절",
          "가격",
          "바삭함"
        ],
        "sentiment_analysis": {
          "positive": 65.2,
          "neutral": 26.1,
          "negative": 8.7
        },
        "photo_reviews": 15,
        "recent_trend": "상승",
        "peak_hours": ["19:00-21:00", "12:00-13:00"]
      },
      "combined_at": "2024-06-16T10:30:15"
    },
    "502156891": {
      "store_info": {
        "id": "502156891",
        "name": "황금치킨",
        "category": "음식점 > 치킨",
        "rating": "4.4",
        "review_count": "67",
        "status": "영업중",
        "address": "서울특별시 강남구 역삼동 234-56",
        "phone": "02-234-5678",
        "place_url": "http://place.map.kakao.com/502156891",
        "x": "127.0298765",
        "y": "37.4965432"
      },
      "reviews": [
        {
          "reviewer_name": "최○○",
          "reviewer_level": "플래티넘리뷰어",
          "reviewer_stats": {
            "reviews": 234,
            "average_rating": 4.5,
            "followers": 45
          },
          "rating": 5,
          "date": "2024-06-12",
          "content": "여기 치킨은 정말 최고예요! 특히 양념치킨이 달콤하면서도 매콤해서 중독성이 있어요. 사장님도 너무 친절하시고 서비스도 좋습니다.",
          "badges": ["최고", "양념치킨", "친절", "서비스"],
          "likes": 18,
          "photo_count": 4,
          "has_photos": true
        },
        {
          "reviewer_name": "정○○",
          "reviewer_level": "골드리뷰어",
          "reviewer_stats": {
            "reviews": 145,
            "average_rating": 4.2,
            "followers": 19
          },
          "rating": 4,
          "date": "2024-06-09",
          "content": "맛은 좋은데 매장이 좀 좁아요. 포장해서 먹는 걸 추천합니다.",
          "badges": ["맛좋음", "매장좁음", "포장추천"],
          "likes": 9,
          "photo_count": 2,
          "has_photos": true
        }
      ],
      "review_summary": {
        "total_reviews": 67,
        "average_rating": 4.4,
        "rating_distribution": {
          "5": 32,
          "4": 25,
          "3": 7,
          "2": 2,
          "1": 1
        },
        "positive_keywords": [
          "최고",
          "양념치킨",
          "친절",
          "맛좋음",
          "서비스"
        ],
        "negative_keywords": [
          "매장좁음",
          "대기시간"
        ],
        "common_keywords": [
          "양념치킨",
          "맛좋음",
          "친절",
          "서비스",
          "최고",
          "포장"
        ],
        "sentiment_analysis": {
          "positive": 73.1,
          "neutral": 20.9,
          "negative": 6.0
        },
        "photo_reviews": 45,
        "recent_trend": "상승",
        "peak_hours": ["18:00-20:00", "12:00-14:00"]
      },
      "combined_at": "2024-06-16T10:31:22"
    },
    "503789456": {
      "store_info": {
        "id": "503789456",
        "name": "크리스피치킨",
        "category": "음식점 > 치킨",
        "rating": "3.9",
        "review_count": "34",
        "status": "영업중",
        "address": "서울특별시 강남구 역삼동 345-67",
        "phone": "02-345-6789",
        "place_url": "http://place.map.kakao.com/503789456",
        "x": "127.0312345",
        "y": "37.4951234"
      },
      "reviews": [
        {
          "reviewer_name": "한○○",
          "reviewer_level": "실버리뷰어",
          "reviewer_stats": {
            "reviews": 76,
            "average_rating": 3.8,
            "followers": 5
          },
          "rating": 4,
          "date": "2024-06-11",
          "content": "바삭한 치킨을 좋아한다면 추천! 다만 양념이 좀 짜요.",
          "badges": ["바삭함", "양념짠맛"],
          "likes": 6,
          "photo_count": 1,
          "has_photos": true
        }
      ],
      "review_summary": {
        "total_reviews": 34,
        "average_rating": 3.9,
        "rating_distribution": {
          "5": 8,
          "4": 15,
          "3": 7,
          "2": 3,
          "1": 1
        },
        "positive_keywords": [
          "바삭함",
          "맛있음"
        ],
        "negative_keywords": [
          "양념짠맛",
          "서비스"
        ],
        "common_keywords": [
          "바삭함",
          "치킨",
          "양념",
          "맛있음"
        ],
        "sentiment_analysis": {
          "positive": 58.8,
          "neutral": 29.4,
          "negative": 11.8
        },
        "photo_reviews": 18,
        "recent_trend": "보통",
        "peak_hours": ["19:00-21:00"]
      },
      "combined_at": "2024-06-16T10:32:05"
    }
  }
}
```

### 2. AI 기반 비즈니스 추천

**요청**
```bash
curl -X POST "http://vector-api.20.249.191.180.nip.io/action-recommendation" \
  -H "Content-Type: application/json" \
  -d '{
    "store_id": "501745730",
    "context": "매출이 감소하고 있어서 메뉴 개선이 필요합니다."
  }'
```

**응답**
```json
{
  "success": true,
  "recommendation": {
    "summary": {
      "current_situation": "치킨 전문점으로 강남구 역삼동에 위치, 평균 별점 3.8점으로 동종업체 대비 개선 여지 존재",
      "key_insights": [
        "배달 서비스 만족도가 경쟁업체 대비 낮음",
        "신메뉴 출시 주기가 3개월 이상으로 긴 편",
        "온라인 리뷰 관리 시스템 부재"
      ],
      "priority_areas": ["배달 품질 개선", "메뉴 혁신"]
    },
    "action_plans": {
      "short_term": [
        {
          "title": "배달 포장재 개선",
          "description": "보온성이 우수한 친환경 포장재로 교체하여 배달 만족도 향상",
          "expected_impact": "배달 리뷰 평점 0.5점 상승 예상",
          "timeline": "2주",
          "cost": "월 50만원"
        }
      ],
      "mid_term": [
        {
          "title": "시즌 한정 메뉴 런칭",
          "description": "여름 시즌 매운맛 신메뉴 2종 개발 및 SNS 마케팅",
          "expected_impact": "신규 고객 유입 20% 증가",
          "timeline": "6주",
          "cost": "초기 투자 300만원"
        }
      ],
      "long_term": [
        {
          "title": "브랜드 리뉴얼",
          "description": "매장 인테리어 개선 및 브랜드 아이덴티티 강화",
          "expected_impact": "브랜드 인지도 향상, 객단가 15% 상승",
          "timeline": "4개월",
          "cost": "1,500만원"
        }
      ]
    },
    "implementation_tips": [
      "배달앱 리뷰 모니터링 시스템 도입",
      "경쟁업체 메뉴 트렌드 주기적 분석",
      "고객 피드백 기반 개선사항 우선순위 설정"
    ]
  },
  "input_data": {
    "request_context": {
      "store_id": "501745730",
      "owner_request": "매출이 감소하고 있어서 메뉴 개선이 필요합니다.",
      "analysis_timestamp": "2024-06-16T10:30:00"
    },
    "market_intelligence": {
      "total_competitors": 7,
      "industry_insights": [
        "업계 전반적으로 고객 만족도 개선 필요",
        "고성과 업체 3개 벤치마킹 가능"
      ],
      "performance_benchmarks": {
        "average_rating": 4.1,
        "review_volume_trend": "증가"
      }
    },
    "competitive_insights": [
      {
        "rank": 1,
        "store_name": "○○치킨",
        "similarity_score": 0.892,
        "performance_analysis": {
          "performance": {
            "rating": "4.3",
            "review_count": "156"
          },
          "feedback": {
            "positive_aspects": ["맛", "친절", "빠른배달"],
            "negative_aspects": ["가격"]
          },
          "business_insights": {
            "key_finding": "신메뉴 런칭으로 리뷰 급증"
          }
        }
      }
    ],
    "actionable_recommendations": {
      "immediate_actions": [
        "배달 서비스 개선 (업계 5개 업체 공통 문제)"
      ],
      "strategic_improvements": [
        "메뉴 다양성 확대"
      ],
      "benchmarking_targets": [
        "○○치킨: 신메뉴 마케팅 전략"
      ]
    }
  }
}
```

## ⚙️ 환경 설정

### 필수 환경변수

| 변수명 | 설명 | 예시 | 기본값 |
|--------|------|------|--------|
| `CLAUDE_API_KEY` | Claude AI API 키 | `sk-ant-api03-...` | - |
| `RESTAURANT_API_HOST` | Restaurant API 호스트 | `localhost` | `0.0.0.0` |
| `RESTAURANT_API_PORT` | Restaurant API 포트 | `18000` | `18000` |
| `REVIEW_API_HOST` | Review API 호스트 | `localhost` | `0.0.0.0` |
| `REVIEW_API_PORT` | Review API 포트 | `19000` | `19000` |

### 선택적 환경변수

| 변수명 | 설명 | 기본값 |
|--------|------|--------|
| `CLAUDE_MODEL` | Claude 모델명 | `claude-sonnet-4-20250514` |
| `VECTOR_DB_PATH` | Vector DB 저장 경로 | `./vectordb` |
| `VECTOR_DB_COLLECTION` | 컬렉션명 | `restaurant_reviews` |
| `EMBEDDING_MODEL` | 임베딩 모델 | `sentence-transformers/all-MiniLM-L6-v2` |
| `MAX_RESTAURANTS_PER_CATEGORY` | 카테고리별 최대 수집 음식점 | `50` |
| `MAX_REVIEWS_PER_RESTAURANT` | 음식점별 최대 리뷰 수 | `100` |
| `LOG_LEVEL` | 로그 레벨 | `info` |

### Kubernetes 환경 자동 감지

시스템이 자동으로 환경을 감지하여 적절한 설정을 적용합니다:

- **로컬 개발**: `localhost` 기반 API 연동
- **Kubernetes**: 서비스 디스커버리 기반 연동
  - `restaurant-api-service:80`
  - `kakao-review-api-service:80`

## 🔧 개발 가이드

### 로컬 개발

```bash
# 의존성 추가
poetry add 새패키지명

# 개발 서버 실행 (Hot Reload)
poetry run uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# 직접 실행
poetry run python app/main.py

# 의존성 업데이트
poetry update

# 가상환경 정보 확인
poetry env info
```

### 코드 품질

```bash
# 코드 포맷팅
poetry run black app/

# 린팅
poetry run flake8 app/

# 타입 체크
poetry run mypy app/
```

### Docker 개발

```bash
# 베이스 이미지 재빌드 (의존성 변경 시)
./build-base.sh

# 서비스 이미지 빌드
./build.sh

# 로컬 실행
docker run -p 8000:8000 --env-file .env vector-api:latest
```

## 🐛 문제 해결

### 일반적인 문제

**1. Vector DB 초기화 실패**
```bash
# Vector DB 상태 확인
curl "http://localhost:8000/vector-status"

# 로그 확인
kubectl logs -l app=vector-api | grep -i vector

# Vector DB 디렉토리 확인 (Kubernetes)
kubectl exec -it deployment/vector-api -- ls -la /app/vectordb/
```

**2. Claude API 연결 실패**
```bash
# API 키 유효성 테스트
curl -X POST "https://api.anthropic.com/v1/messages" \
  -H "x-api-key: your-claude-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 10,
    "messages": [{"role": "user", "content": "Hi"}]
  }'

# 환경변수 확인
kubectl exec -it deployment/vector-api -- env | grep CLAUDE
```

**3. 외부 API 연동 실패**
```bash
# Restaurant API 연결 테스트
kubectl exec -it deployment/vector-api -- curl http://restaurant-api-service/health

# Review API 연결 테스트  
kubectl exec -it deployment/vector-api -- curl http://kakao-review-api-service/health

# 서비스 디스커버리 확인
kubectl get svc | grep -E "(restaurant|review)"
```

**4. 메모리 부족 문제**
```bash
# 리소스 사용량 확인
kubectl top pods -l app=vector-api

# Pod 리소스 제한 확인
kubectl describe pod -l app=vector-api | grep -A 5 -B 5 Resources

# 메모리 사용량 모니터링
kubectl exec -it deployment/vector-api -- free -h
```

**5. 영구 볼륨 문제**
```bash
# PVC 상태 확인
kubectl get pvc vector-db-pvc
kubectl describe pvc vector-db-pvc

# 볼륨 마운트 확인
kubectl exec -it deployment/vector-api -- df -h /app/vectordb
```

### 성능 최적화

**메모리 최적화**
```yaml
# deployment.yaml에서 리소스 조정
resources:
  requests:
    memory: "2Gi"     # Vector DB + ML 모델
    cpu: "1000m"      # 임베딩 계산
  limits:
    memory: "4Gi"     # 대량 처리를 위한 여유
    cpu: "2000m"      # 병렬 처리
```

**Vector DB 최적화**
- 임베딩 배치 처리로 메모리 효율성 향상
- 중복 데이터 감지로 불필요한 재처리 방지
- 적절한 청크 크기로 메모리 사용량 조절

## 📈 모니터링 및 로깅

### 헬스체크 모니터링

```bash
# 주기적 헬스체크
watch -n 5 "curl -s http://vector-api.20.249.191.180.nip.io/health | jq"

# Vector DB 상태 모니터링
watch -n 10 "curl -s http://vector-api.20.249.191.180.nip.io/vector-status | jq"
```

### 로그 분석

```bash
# 실시간 로그 스트림
kubectl logs -l app=vector-api -f

# 에러 로그 필터링
kubectl logs -l app=vector-api | grep -i error

# Claude API 호출 로그
kubectl logs -l app=vector-api | grep -i claude

# Vector DB 작업 로그
kubectl logs -l app=vector-api | grep -i vector
```

## 🎯 워크플로우 다이어그램

### Vector DB 구축 프로세스

```mermaid
sequenceDiagram
    participant Client
    participant VectorAPI
    participant RestaurantAPI  
    participant ReviewAPI
    participant VectorDB
    participant ClaudeAI

    Client->>VectorAPI: POST /find-reviews
    VectorAPI->>RestaurantAPI: 타겟 음식점 검색
    RestaurantAPI-->>VectorAPI: 음식점 정보 반환
    VectorAPI->>RestaurantAPI: 동종업체 검색
    RestaurantAPI-->>VectorAPI: 경쟁업체 목록 반환
    
    loop 각 음식점
        VectorAPI->>ReviewAPI: 리뷰 수집
        ReviewAPI-->>VectorAPI: 리뷰 데이터 반환
    end
    
    VectorAPI->>VectorAPI: 텍스트 전처리 및 임베딩
    VectorAPI->>VectorDB: Vector 저장
    VectorDB-->>VectorAPI: 저장 완료
    VectorAPI-->>Client: 결과 반환
```

### AI 추천 프로세스

```mermaid
sequenceDiagram
    participant Client
    participant VectorAPI
    participant VectorDB
    participant ClaudeAI

    Client->>VectorAPI: POST /action-recommendation
    VectorAPI->>VectorDB: 유사 케이스 검색
    VectorDB-->>VectorAPI: 관련 데이터 반환
    VectorAPI->>VectorAPI: 컨텍스트 구성
    VectorAPI->>ClaudeAI: 추천 요청
    ClaudeAI-->>VectorAPI: 액션 플랜 반환
    VectorAPI->>VectorAPI: JSON 파싱
    VectorAPI-->>Client: 구조화된 추천 반환
```

## 📈 향후 로드맵

### Phase 1: 기능 안정화 ✅
- [x] Vector DB 구축 및 관리
- [x] Claude AI 통합
- [x] 마이크로서비스 아키텍처
- [x] Kubernetes 배포
- [x] API 문서화

### Phase 2: 기능 확장 🚧
- [ ] **실시간 데이터 수집**: 새로운 리뷰 자동 업데이트
- [ ] **다중 Vector DB 지원**: FAISS, Pinecone 추가
- [ ] **감정 분석 고도화**: 세밀한 감정 분류 및 트렌드 분석
- [ ] **업종별 특화 모델**: 음식점 유형별 맞춤 추천

### Phase 3: 고급 기능 📋
- [ ] **실시간 대시보드**: Grafana 기반 모니터링
- [ ] **A/B 테스트 프레임워크**: 추천 효과 측정
- [ ] **멀티모달 분석**: 이미지 + 텍스트 통합 분석
- [ ] **예측 분석**: 매출 및 트렌드 예측 모델

### Phase 4: 엔터프라이즈 📊
- [ ] **API 배치 처리**: 대량 데이터 일괄 처리
- [ ] **고급 보안**: OAuth 2.0, API 키 관리
- [ ] **멀티 테넌트**: 고객별 격리된 데이터 관리
- [ ] **비즈니스 인텔리전스**: 시장 분석 및 보고서 생성

## 🤝 기여 가이드

### 개발 워크플로우

1. **이슈 생성**: 기능 요청 또는 버그 리포트
2. **브랜치 생성**: `feature/기능명` 또는 `fix/버그명`
3. **개발 및 테스트**: 로컬에서 충분한 테스트
4. **Pull Request**: 코드 리뷰 요청
5. **배포**: 검토 후 메인 브랜치 병합

### 코딩 컨벤션

- **타입 힌팅**: 모든 함수와 변수에 타입 명시
- **Docstring**: Google 스타일 문서화
- **에러 처리**: 모든 외부 API 호출에 예외 처리
- **로깅**: 적절한 로그 레벨과 구조화된 메시지

## 📞 지원 및 문의

### 기술 지원
- **🐛 버그 리포트**: GitHub Issues
- **💡 기능 제안**: GitHub Discussions  
- **📚 API 문의**: Swagger UI 문서 참조
- **📧 기술 지원**: 개발팀 Slack 채널

### 문서 및 리소스
- **📖 API 문서**: http://vector-api.20.249.191.180.nip.io/docs
- **🔧 모니터링**: http://vector-api.20.249.191.180.nip.io/vector-status
- **❤️ 헬스체크**: http://vector-api.20.249.191.180.nip.io/health

---

## 📝 라이선스

이 프로젝트는 소상공인의 성장과 데이터 기반 의사결정을 지원하는 목적으로 개발되었습니다.

---

**💡 핵심 가치**: AI와 데이터의 힘으로 소상공인의 성공을 돕습니다!  
**🎯 미션**: 모든 소상공인이 데이터 기반으로 스마트한 경영 결정을 내릴 수 있도록 지원합니다.