shared-dg04-hi/hi-backend
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
hi-backend/README.md
lsh9672 e4d87cc98a feat : cors추가
2025-06-19 13:01:58 +09:00

16 KiB
Raw Blame History

하이오더 리뷰 피드백 시스템 🍽️

Spring Boot Java React Azure License

📖 프로젝트 개요

하이오더 리뷰 피드백 시스템은 소상공인을 위한 AI 기반 고객 피드백 관리 솔루션입니다. 다양한 플랫폼의 리뷰를 자동 수집·분석하고, AI가 생성한 맞춤형 실행계획을 통해 매장 운영 개선을 지원합니다.

🎯 핵심 가치

  • AI 피드백 마스터: 피드백 분석 결과를 비용, 효과, 우선순위를 고려한 단계별 실행 계획으로 변환
  • 멀티플랫폼 리뷰 통합관리: 하이오더, 네이버, 카카오 등 주요 플랫폼 리뷰 자동 수집·통합
  • 리뷰 시각화: 고객 리뷰를 시각화하여 객관적 분석 지원

🏗️ 시스템 아키텍처

마이크로서비스 구조

┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│   프론트엔드     │  │ Nginx Ingress   │  │  인증/인가 서비스 │
│   (React SPA)   │◄─┤   Controller    │◄─┤ (Azure AD B2C) │
└─────────────────┘  └─────────────────┘  └─────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
┌───────▼──────┐    ┌─────────▼──────┐    ┌─────────▼──────┐
│ 회원관리서비스 │    │ 매장운영서비스  │    │ 리뷰관리서비스  │
│ (Member)     │    │ (Store)        │    │ (Review)       │
└──────────────┘    └────┬───────────┘    └────────────────┘
        │                │                         │
        │                ▼                         │
┌───────▼──────┐    ┌─────────▼──────┐    ┌─────────▼──────┐
│ AI분석서비스  │    │  Azure Event   │    │ 취향추천서비스  │
│ (Analytics)  │    │      Hub       │    │ (Recommend)    │
└──────────────┘    └─────┬──────────┘    └────────────────┘
                          │
                   ┌──────▼──────┐
                   │  외부 리뷰   │
                   │  수집 서비스  │
                   │ (네이버/카카오/│
                   │   구글 API)  │
                   └─────────────┘

기술 스택

백엔드

  • Framework: Spring Boot 3.4.0, Java 21
  • Architecture: Clean Architecture (Hexagonal)
  • Database: Azure PostgreSQL (서비스별 독립 DB)
  • Cache: Azure Redis Cache
  • Messaging: Azure Event Hub
  • AI Services: OpenAI GPT, Claude AI, Azure Cognitive Services

프론트엔드

  • Framework: React 18+, Material-UI
  • State Management: React Hooks
  • Deployment: Azure Static Web Apps

인프라 (Azure Cloud)

  • Container: Azure Kubernetes Service (AKS)
  • Ingress: Nginx Ingress Controller
  • Authentication: Azure AD B2C
  • Messaging: Azure Event Hub (외부 리뷰 수집)
  • Storage: Azure Blob Storage
  • Monitoring: Azure Monitor, Application Insights
  • CI/CD: Azure DevOps

🚀 주요 기능

👥 고객 기능

  • 취향 기반 음식점 추천: AI가 분석한 개인 취향과 위치 기반 맞춤 추천
  • 영수증 리뷰 작성: 영수증 인증을 통한 신뢰성 있는 리뷰 시스템
  • 리뷰 반응 및 댓글: 다른 고객과의 소통을 통한 커뮤니티 형성
  • 태그 기반 매장 필터링: 알레르기, 비건, 반려동물 동반 등 세부 조건 검색

🏪 점주 기능

  • AI 피드백 분석: 리뷰 감정분석, 키워드 추출, 개선점 도출
  • 실행계획 수립: 단기/중기/장기 개선 계획 자동 생성 및 관리
  • 멀티플랫폼 리뷰 통합: Event Hub를 통한 네이버, 카카오, 구글 리뷰 자동 수집
  • 매장 운영 분석: 시간대별 주문 통계, 고객 연령대/성별 분석
  • 리뷰 댓글 관리: 고객 리뷰에 대한 사장님 답변 기능

🤖 AI 기능

  • 감정 분석: 리뷰의 긍정/부정/중립 감정 자동 분류
  • 키워드 추출: 맛, 서비스, 분위기 등 카테고리별 핵심 키워드 추출
  • 개선 제안: 비용 대비 효과를 고려한 구체적 개선 방안 제시
  • 트렌드 분석: 업종별, 지역별 트렌드 분석 및 벤치마킹

📁 프로젝트 구조

hiorder-feedback-system/
├── backend/                          # 백엔드 마이크로서비스
│   ├── member-service/               # 회원관리 서비스
│   │   ├── member-biz/              # 비즈니스 로직
│   │   └── member-infra/            # 인프라스트럭처
│   ├── store-service/               # 매장운영 서비스
│   ├── review-service/              # 리뷰관리 서비스
│   ├── analytics-service/           # AI분석 서비스
│   ├── recommend-service/           # 추천 서비스
│   └── common/                      # 공통 라이브러리
├── frontend/                        # React 프론트엔드
│   ├── src/
│   │   ├── components/             # 재사용 컴포넌트
│   │   ├── pages/                  # 페이지 컴포넌트
│   │   ├── services/               # API 호출 서비스
│   │   └── utils/                  # 유틸리티 함수
│   └── public/
├── infrastructure/                  # Kubernetes 배포 설정
│   ├── k8s/                        # Kubernetes manifests
│   ├── helm/                       # Helm charts
│   └── terraform/                  # Infrastructure as Code
└── docs/                           # 프로젝트 문서
    ├── api/                        # API 문서
    ├── architecture/               # 아키텍처 설계서
    └── deployment/                 # 배포 가이드

🛠️ 로컬 개발 환경 설정

사전 요구사항

  • Java 21+
  • Node.js 18+
  • Docker & Docker Compose
  • PostgreSQL 14+
  • Redis 6+

백엔드 실행

  1. 저장소 클론
git clone https://github.com/your-org/hiorder-feedback-system.git
cd hiorder-feedback-system/backend
  1. 환경변수 설정
# .env 파일 생성
cp .env.example .env

# 필수 환경변수 설정
export POSTGRES_HOST=localhost
export POSTGRES_PORT=5432
export POSTGRES_DB=hiorder
export POSTGRES_USER=postgres
export POSTGRES_PASSWORD=password
export REDIS_HOST=localhost
export REDIS_PORT=6379
export OPENAI_API_KEY=your_openai_api_key
export AZURE_STORAGE_CONNECTION_STRING=your_azure_storage_connection
  1. 의존성 설치 및 빌드
./gradlew clean build
  1. 데이터베이스 초기화
docker-compose up -d postgres redis
./gradlew flywayMigrate
  1. 서비스 실행
# 모든 서비스 동시 실행
./gradlew bootRun --parallel

# 개별 서비스 실행
./gradlew :member-service:bootRun
./gradlew :store-service:bootRun
./gradlew :review-service:bootRun
./gradlew :analytics-service:bootRun
./gradlew :recommend-service:bootRun

프론트엔드 실행

  1. 프론트엔드 디렉토리로 이동
cd ../frontend
  1. 의존성 설치
npm install
  1. 환경변수 설정
# .env 파일 생성
echo "REACT_APP_API_BASE_URL=http://localhost:8080/api" > .env
echo "REACT_APP_AUTH_URL=http://localhost:8080/api/auth" >> .env
  1. 개발 서버 실행
npm start

🐳 Docker 실행

Docker Compose로 전체 시스템 실행

  1. Docker Compose 설정
cd docker
cp .env.example .env
# 환경변수 설정 후
  1. 전체 시스템 실행
docker-compose up -d
  1. 서비스 접근

☁️ Azure 클라우드 배포

사전 준비

  1. Azure CLI 설치 및 로그인
az login
az account set --subscription "your-subscription-id"
  1. 리소스 그룹 생성
az group create --name hiorder-feedback-rg --location koreacentral

AKS 클러스터 배포

  1. AKS 클러스터 생성
cd infrastructure/terraform
terraform init
terraform plan
terraform apply
  1. kubectl 설정
az aks get-credentials --resource-group hiorder-feedback-rg --name hiorder-aks
  1. 애플리케이션 배포
cd ../k8s
kubectl apply -f namespace.yaml
kubectl apply -f configmap/
kubectl apply -f secrets/
kubectl apply -f deployments/
kubectl apply -f services/
kubectl apply -f ingress/

모니터링 설정

  1. Application Insights 연결
az monitor app-insights component create \
  --app hiorder-insights \
  --location koreacentral \
  --resource-group hiorder-feedback-rg
  1. 대시보드 접근

📊 API 문서

Swagger UI 접근

Ingress 라우팅 구조

도메인/경로                     → 서비스
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
/                             → Frontend (React SPA)
/api/auth/*                   → Member Service
/api/members/*                → Member Service
/api/stores/*                 → Store Service
/api/reviews/*                → Review Service
/api/analytics/*              → Analytics Service
/api/recommend/*              → Recommend Service

외부 리뷰 수집 아키텍처

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   네이버     │    │   카카오     │    │   구글      │
│  리뷰 API   │    │  리뷰 API   │    │ 리뷰 API    │
└──────┬──────┘    └──────┬──────┘    └──────┬──────┘
       │                  │                  │
       └──────────────────┼──────────────────┘
                          │
                    ┌─────▼─────┐
                    │   Store   │
                    │  Service  │
                    └─────┬─────┘
                          │
                    ┌─────▼─────┐
                    │   Azure   │
                    │ Event Hub │
                    └─────┬─────┘
                          │
                    ┌─────▼─────┐
                    │  Review   │
                    │ Service   │
                    └───────────┘

주요 API 엔드포인트

인증 API

POST /api/auth/login          # 로그인
POST /api/auth/logout         # 로그아웃
POST /api/members/register    # 회원가입
POST /api/auth/refresh        # 토큰 갱신

매장 관리 API

GET    /api/stores/my         # 내 매장 목록
POST   /api/stores           # 매장 등록
PUT    /api/stores/{id}      # 매장 수정
DELETE /api/stores/{id}      # 매장 삭제

리뷰 관리 API

GET    /api/reviews/stores/{storeId}  # 매장 리뷰 조회
POST   /api/reviews                  # 리뷰 작성
PUT    /api/reviews/{id}             # 리뷰 수정
DELETE /api/reviews/{id}             # 리뷰 삭제
POST   /api/reviews/{id}/reactions   # 리뷰 반응

AI 분석 API

GET /api/analytics/stores/{storeId}           # 매장 분석 정보
GET /api/analytics/stores/{storeId}/feedback  # AI 피드백
GET /api/action-plans/stores/{storeId}        # 실행계획 목록
POST /api/action-plans                        # 실행계획 저장

🧪 테스트

단위 테스트 실행

./gradlew test

통합 테스트 실행

./gradlew integrationTest

API 테스트

# Postman Collection 실행
newman run docs/api/hiorder-api-tests.postman_collection.json

성능 테스트

# K6 성능 테스트
k6 run tests/performance/load-test.js

🔒 보안

인증 및 권한

  • JWT 토큰 기반 인증
  • Azure AD B2C 통합
  • Role-based Access Control (RBAC)
  • API Rate Limiting

데이터 보호

  • TLS 1.3 암호화 통신
  • 개인정보 마스킹 처리
  • 데이터베이스 암호화
  • 정기적 보안 스캔

📈 모니터링 및 로깅

메트릭 수집

  • Application Metrics: Spring Boot Actuator
  • Infrastructure Metrics: Azure Monitor
  • Custom Metrics: Micrometer + Prometheus

로그 관리

  • Structured Logging: Logback + JSON
  • Log Aggregation: Azure Log Analytics
  • Distributed Tracing: Azure Application Insights

알림 설정

  • Error Rate: > 5%
  • Response Time: > 2s
  • CPU Usage: > 80%
  • Memory Usage: > 85%

🤝 기여 가이드

개발 프로세스

  1. 이슈 생성: GitHub Issues에서 버그 리포트 또는 기능 요청
  2. 브랜치 생성: feature/기능명 또는 bugfix/이슈번호
  3. 코드 작성: 코딩 컨벤션 준수
  4. 테스트 작성: 단위 테스트 및 통합 테스트
  5. Pull Request: 코드 리뷰 요청
  6. 배포: 승인 후 develop → staging → main 순서로 배포

코딩 컨벤션

  • Java: Google Java Style Guide
  • JavaScript: ESLint + Prettier
  • Git Commit: Conventional Commits

코드 리뷰 체크리스트

  • 비즈니스 로직이 올바르게 구현되었는가?
  • 테스트 커버리지가 80% 이상인가?
  • 보안 취약점이 없는가?
  • 성능에 문제가 없는가?
  • 문서가 업데이트되었는가?

📝 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다.

👥 팀 소개

개발팀

  • PO: 이상현 "해달" - 제품 기획 및 비즈니스 로직
  • UI/UX: 이서연 "공감왕" - 사용자 경험 설계
  • Frontend: 김동현 "화면킹" - React 개발
  • Backend: 장혁진 "API왕" - Spring Boot 개발
  • DevOps: 오성민 "안정왕" - 인프라 및 배포
  • AI/ML: 이지원 "AI왕" - AI 모델 개발
  • Data: 김태현 "데이터킹" - 데이터 분석
  • QA: 박서준 "품질왕" - 품질 보증

📞 문의 및 지원

⭐ 이 프로젝트가 도움이 되셨다면 Star를 눌러주세요!

Made with ❤️ by KTDS Team