From e4d87cc98a5f11a5af89a43f82be86d163bc3d27 Mon Sep 17 00:00:00 2001 From: lsh9672 Date: Thu, 19 Jun 2025 13:01:58 +0900 Subject: [PATCH] =?UTF-8?q?feat=20:=20cors=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 466 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 464 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 0d7cd4e..fd61eeb 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,465 @@ -## hi-backend +# 하이오더 리뷰 피드백 시스템 🍽️ -sync test +[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.4.0-brightgreen.svg)](https://spring.io/projects/spring-boot) +[![Java](https://img.shields.io/badge/Java-21-orange.svg)](https://openjdk.java.net/) +[![React](https://img.shields.io/badge/React-18+-blue.svg)](https://reactjs.org/) +[![Azure](https://img.shields.io/badge/Azure-Cloud-blue.svg)](https://azure.microsoft.com/) +[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](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. **저장소 클론** +```bash +git clone https://github.com/your-org/hiorder-feedback-system.git +cd hiorder-feedback-system/backend +``` + +2. **환경변수 설정** +```bash +# .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 +``` + +3. **의존성 설치 및 빌드** +```bash +./gradlew clean build +``` + +4. **데이터베이스 초기화** +```bash +docker-compose up -d postgres redis +./gradlew flywayMigrate +``` + +5. **서비스 실행** +```bash +# 모든 서비스 동시 실행 +./gradlew bootRun --parallel + +# 개별 서비스 실행 +./gradlew :member-service:bootRun +./gradlew :store-service:bootRun +./gradlew :review-service:bootRun +./gradlew :analytics-service:bootRun +./gradlew :recommend-service:bootRun +``` + +### 프론트엔드 실행 + +1. **프론트엔드 디렉토리로 이동** +```bash +cd ../frontend +``` + +2. **의존성 설치** +```bash +npm install +``` + +3. **환경변수 설정** +```bash +# .env 파일 생성 +echo "REACT_APP_API_BASE_URL=http://localhost:8080/api" > .env +echo "REACT_APP_AUTH_URL=http://localhost:8080/api/auth" >> .env +``` + +4. **개발 서버 실행** +```bash +npm start +``` + +## 🐳 Docker 실행 + +### Docker Compose로 전체 시스템 실행 + +1. **Docker Compose 설정** +```bash +cd docker +cp .env.example .env +# 환경변수 설정 후 +``` + +2. **전체 시스템 실행** +```bash +docker-compose up -d +``` + +3. **서비스 접근** +- 프론트엔드: http://localhost:3000 +- 백엔드 API: http://localhost:8080/api +- Swagger UI: http://localhost:8080/swagger-ui.html + +## ☁️ Azure 클라우드 배포 + +### 사전 준비 + +1. **Azure CLI 설치 및 로그인** +```bash +az login +az account set --subscription "your-subscription-id" +``` + +2. **리소스 그룹 생성** +```bash +az group create --name hiorder-feedback-rg --location koreacentral +``` + +### AKS 클러스터 배포 + +1. **AKS 클러스터 생성** +```bash +cd infrastructure/terraform +terraform init +terraform plan +terraform apply +``` + +2. **kubectl 설정** +```bash +az aks get-credentials --resource-group hiorder-feedback-rg --name hiorder-aks +``` + +3. **애플리케이션 배포** +```bash +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 연결** +```bash +az monitor app-insights component create \ + --app hiorder-insights \ + --location koreacentral \ + --resource-group hiorder-feedback-rg +``` + +2. **대시보드 접근** +- Azure Portal에서 Application Insights 대시보드 확인 +- Grafana 대시보드: http://your-domain/grafana + +## 📊 API 문서 + +### Swagger UI 접근 +- 로컬: http://localhost:8080/swagger-ui.html +- 개발환경: https://dev-api.hiorder.com/swagger-ui.html +- 운영환경: https://api.hiorder.com/swagger-ui.html + +### 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 # 실행계획 저장 +``` + +## 🧪 테스트 + +### 단위 테스트 실행 +```bash +./gradlew test +``` + +### 통합 테스트 실행 +```bash +./gradlew integrationTest +``` + +### API 테스트 +```bash +# Postman Collection 실행 +newman run docs/api/hiorder-api-tests.postman_collection.json +``` + +### 성능 테스트 +```bash +# 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 라이선스](LICENSE) 하에 배포됩니다. + +## 👥 팀 소개 + +### 개발팀 +- **PO**: 이상현 "해달" - 제품 기획 및 비즈니스 로직 +- **UI/UX**: 이서연 "공감왕" - 사용자 경험 설계 +- **Frontend**: 김동현 "화면킹" - React 개발 +- **Backend**: 장혁진 "API왕" - Spring Boot 개발 +- **DevOps**: 오성민 "안정왕" - 인프라 및 배포 +- **AI/ML**: 이지원 "AI왕" - AI 모델 개발 +- **Data**: 김태현 "데이터킹" - 데이터 분석 +- **QA**: 박서준 "품질왕" - 품질 보증 + +## 📞 문의 및 지원 + +- **GitHub Issues**: [이슈 등록](https://github.com/your-org/hiorder-feedback-system/issues) +- **이메일**: hiorder-support@ktds.com +- **문서**: [프로젝트 위키](https://github.com/your-org/hiorder-feedback-system/wiki) + +--- + +⭐ 이 프로젝트가 도움이 되셨다면 Star를 눌러주세요! + +**Made with ❤️ by KTDS Team** \ No newline at end of file