kt-event-marketing-fe/README.md

# KT 이벤트 파트너
- AI 기반 소상공인 마케팅 지원 서비스

## 1. 소개

KT 이벤트 파트너는 소상공인이 AI를 활용하여 효과적인 이벤트를 쉽게 기획하고 관리할 수 있도록 지원하는 플랫폼입니다.
매장 정보와 AI 추천을 기반으로 이벤트를 생성하고, SNS 콘텐츠를 자동 생성하며, 다양한 채널로 배포하고, 실시간으로 성과를 분석할 수 있습니다.

### 1.1 핵심 기능

- **AI 기반 이벤트 추천**: 매장 정보, 업종, 지역 트렌드를 분석하여 최적의 이벤트 아이디어 제공
- **자동 콘텐츠 생성**: AI가 생성한 이벤트 내용을 바탕으로 SNS 이미지 자동 생성
- **다중 채널 배포**: KT 유휴 채널(우리동네TV, 링고비즈, 지니TV)과 다양한 SNS 채널로 원클릭 배포
- **참여자 관리**: 이벤트 참여자 접수 및 당첨자 추첨 기능
- **실시간 성과 분석**: 조회수, 참여율, ROI 등 실시간 대시보드 제공

### 1.2 MVP 산출물

- **발표자료**: https://www.miricanvas.com/v2/design2/v/7102e2d0-53b3-4a4a-9c93-7042a7706357
- **설계결과**:
  - [유저스토리](design/userstory.md)
  - [논리 아키텍처](design/backend/logical/logical-architecture.md)
  - [UI/UX 설계서](design/frontend/uiux-design.md)
  - [API 설계서](design/backend/api/API-설계서.md)
- **Git Repo**:
  - **프론트엔드**: https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing-fe.git
  - **백엔드**: https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing.git
- **시연 동영상**: https://drive.google.com/file/d/1VYd7NEG-DBdSKyU7hRtVfAaNHF4lBpWy/view?usp=sharing

## 2. 시스템 아키텍처

### 2.1 전체 구조

프론트엔드(Next.js)와 마이크로서비스 백엔드(Spring Boot)로 구성된 애플리케이션입니다.
Event-Driven 아키텍처와 CQRS 패턴을 적용하여 확장성과 성능을 고려한 설계입니다.

### 2.2 마이크로서비스 구성

- **User Service**: 사용자 인증 및 매장정보 관리
- **Event Service**: 이벤트 생성, 수정, 삭제, 조회 및 전체 플로우 오케스트레이션
- **AI Service**: AI 기반 트렌드 분석 및 이벤트 추천
- **Content Service**: SNS 콘텐츠(이미지) 자동 생성
- **Distribution Service**: 다중 채널(네이버, 카카오톡, 인스타그램) 배포
- **Participation Service**: 이벤트 참여자 접수 및 당첨자 관리
- **Analytics Service**: 실시간 성과 분석 및 통합 대시보드

### 2.3 기술 스택

- **프론트엔드**: Next.js 14, React 18, TypeScript 5, Material UI v6, React Query, Zustand 4.5
- **백엔드**: Spring Boot 3.3, Java 21, Kafka (Event Bus + Job Queue)
- **인프라**: Azure Kubernetes Service (AKS), Azure Container Registry (ACR)
- **CI/CD**: GitHub Actions, Argo CD
- **백킹 서비스**:
  - **Database**: PostgreSQL
  - **Cache**: Redis
  - **Message Queue**: Kafka

## 3. 로컬 실행 가이드

### 3.1 사전 요구사항

- **Node.js**: 18.x 이상
- **npm**: 9.x 이상
- **Git**: 2.x 이상

### 3.2 프로젝트 클론

```bash
git clone https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing-fe.git
cd kt-event-marketing-fe

git clone https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing.git
cd kt-event-marketing
```

### 3.3 환경 변수 설정

`.env.example` 파일을 복사하여 `.env.local` 파일을 생성합니다:

```bash
cp .env.example .env.local
```

`.env.local` 파일을 열어 백엔드 API 호스트를 설정합니다:

```env
# API Hosts (로컬 개발 환경)
NEXT_PUBLIC_USER_HOST=http://localhost:8081
NEXT_PUBLIC_EVENT_HOST=http://localhost:8080
NEXT_PUBLIC_CONTENT_HOST=http://localhost:8084
NEXT_PUBLIC_AI_HOST=http://localhost:8083
NEXT_PUBLIC_PARTICIPATION_HOST=http://localhost:8084
NEXT_PUBLIC_DISTRIBUTION_HOST=http://localhost:8085
NEXT_PUBLIC_ANALYTICS_HOST=http://localhost:8086

# API Version prefix
NEXT_PUBLIC_API_VERSION=api
```

> **참고**: 백엔드 서비스가 다른 포트나 호스트에서 실행 중이라면 해당 주소로 변경하세요.

### 3.4 의존성 설치

```bash
npm install
```

### 3.5 개발 서버 실행

```bash
npm run dev
```

브라우저에서 [http://localhost:3000](http://localhost:3000)으로 접속하여 애플리케이션을 확인합니다.

### 3.6 빌드 및 타입 체크

```bash
# TypeScript 타입 체크
npm run type-check

# 프로덕션 빌드
npm run build

# 프로덕션 서버 실행
npm run start
```

## 4. Docker 빌드 및 로컬 실행

### 4.1 Docker 이미지 빌드

```bash
docker build -t kt-event-marketing-frontend:latest .
```

### 4.2 Docker 컨테이너 실행

```bash
docker run -p 8080:8080 kt-event-marketing-frontend:latest
```

브라우저에서 [http://localhost:8080](http://localhost:8080)으로 접속합니다.

### 4.3 Health Check 확인

```bash
curl http://localhost:8080/health
```

## 5. Kubernetes 배포 가이드

### 5.1 사전 준비

#### 5.1.1 Azure 로그인

```bash
az login
az account show
```

#### 5.1.2 AKS 자격 증명 설정

```bash
az aks get-credentials --resource-group <리소스그룹명> --name aks-digitalgarage-01
kubectl cluster-info
```

#### 5.1.3 Namespace 생성

```bash
kubectl create namespace kt-event-marketing
```

#### 5.1.4 ImagePullSecret 생성

ACR에서 이미지를 가져오기 위한 시크릿을 생성합니다:

```bash
kubectl create secret docker-registry kt-event-marketing-frontend \
  --docker-server=acrdigitalgarage01.azurecr.io \
  --docker-username=<ACR_USERNAME> \
  --docker-password=<ACR_PASSWORD> \
  --namespace=kt-event-marketing
```

### 5.2 이미지 빌드 및 푸시

#### 5.2.1 이미지 빌드

```bash
docker build -t kt-event-marketing-frontend:latest .
```

#### 5.2.2 ACR 태깅

```bash
docker tag kt-event-marketing-frontend:latest \
  acrdigitalgarage01.azurecr.io/kt-event-marketing/kt-event-marketing-frontend:latest
```

#### 5.2.3 ACR 로그인

```bash
az acr login --name acrdigitalgarage01
```

#### 5.2.4 이미지 푸시

```bash
docker push acrdigitalgarage01.azurecr.io/kt-event-marketing/kt-event-marketing-frontend:latest
```

### 5.3 Kubernetes 배포

#### 5.3.1 ConfigMap 수정 (선택 사항)

배포 환경에 맞게 백엔드 API 호스트를 수정합니다:

```bash
# ConfigMap 편집
kubectl edit configmap cm-kt-event-marketing-frontend -n kt-event-marketing
```

또는 `deployment/k8s/configmap.yaml` 파일을 직접 수정한 후 적용합니다.

#### 5.3.2 매니페스트 적용

```bash
# 모든 매니페스트 일괄 적용
kubectl apply -f deployment/k8s/
```

또는 개별적으로 적용:

```bash
kubectl apply -f deployment/k8s/configmap.yaml
kubectl apply -f deployment/k8s/service.yaml
kubectl apply -f deployment/k8s/deployment.yaml
kubectl apply -f deployment/k8s/ingress.yaml
```

### 5.4 배포 확인

#### 5.4.1 Pod 상태 확인

```bash
kubectl get pods -n kt-event-marketing -l app=kt-event-marketing-frontend
```

#### 5.4.2 Service 확인

```bash
kubectl get svc kt-event-marketing-frontend -n kt-event-marketing
```

#### 5.4.3 Ingress 확인

```bash
kubectl get ingress kt-event-marketing-frontend -n kt-event-marketing
```

#### 5.4.4 로그 확인

```bash
kubectl logs -n kt-event-marketing -l app=kt-event-marketing-frontend --tail=100 -f
```

### 5.5 접속 테스트

1. 프론트 페이지 주소 구하기:

```
kubens {namespace}
k get svc 
```
2. 로그인
 - ID : dodari@naver.com
 - PW : p1234567890

> **참고**: External IP는 환경에 따라 다를 수 있습니다. 다음 명령으로 확인하세요:
> ```bash
> kubectl get svc ingress-nginx-controller -n ingress-nginx
> ```

## 6. 재배포 가이드

### 6.1 코드 수정 후 재배포

```bash
# 1. 이미지 빌드
docker build -t kt-event-marketing-frontend:latest .

# 2. ACR 태깅
docker tag kt-event-marketing-frontend:latest \
  acrdigitalgarage01.azurecr.io/kt-event-marketing/kt-event-marketing-frontend:latest

# 3. 이미지 푸시
docker push acrdigitalgarage01.azurecr.io/kt-event-marketing/kt-event-marketing-frontend:latest

# 4. Kubernetes Deployment 재시작
kubectl rollout restart deployment kt-event-marketing-frontend -n kt-event-marketing

# 5. 롤아웃 상태 확인
kubectl rollout status deployment/kt-event-marketing-frontend -n kt-event-marketing
```

### 6.2 ConfigMap 수정 후 재배포

```bash
# ConfigMap 수정
kubectl apply -f deployment/k8s/configmap.yaml

# Pod 재시작
kubectl rollout restart deployment kt-event-marketing-frontend -n kt-event-marketing
```

### 6.3 롤백

```bash
# 이전 버전으로 롤백
kubectl rollout undo deployment/kt-event-marketing-frontend -n kt-event-marketing

# 롤아웃 히스토리 확인
kubectl rollout history deployment/kt-event-marketing-frontend -n kt-event-marketing
```

## 7. 트러블슈팅

### 7.1 Pod가 Running 상태가 아닌 경우

#### ImagePullBackOff 에러

```bash
# ImagePullSecret 확인
kubectl get secret kt-event-marketing-frontend -n kt-event-marketing

# Secret 재생성
kubectl delete secret kt-event-marketing-frontend -n kt-event-marketing
kubectl create secret docker-registry kt-event-marketing-frontend \
  --docker-server=acrdigitalgarage01.azurecr.io \
  --docker-username=<ACR_USERNAME> \
  --docker-password=<ACR_PASSWORD> \
  --namespace=kt-event-marketing
```

#### CrashLoopBackOff 에러

```bash
# Pod 로그 확인
kubectl logs -n kt-event-marketing -l app=kt-event-marketing-frontend --tail=100

# 이전 컨테이너 로그 확인
kubectl logs -n kt-event-marketing -l app=kt-event-marketing-frontend --previous
```

### 7.2 Ingress로 접속이 안 되는 경우

```bash
# Ingress Controller 확인
kubectl get svc ingress-nginx-controller -n ingress-nginx

# Ingress 상태 확인
kubectl describe ingress kt-event-marketing-frontend -n kt-event-marketing

# Service Endpoint 확인
kubectl get endpoints kt-event-marketing-frontend -n kt-event-marketing
```

### 7.3 ConfigMap이 적용되지 않는 경우

```bash
# Pod 내부 확인
kubectl exec -n kt-event-marketing -it $(kubectl get pod -n kt-event-marketing -l app=kt-event-marketing-frontend -o jsonpath='{.items[0].metadata.name}') \
  -- cat /usr/share/nginx/html/runtime-env.js
```

## 8. 개발 가이드

### 8.1 프로젝트 구조

```
kt-event-marketing-fe/
├── src/
│   ├── app/              # Next.js App Router 페이지
│   ├── components/       # React 컴포넌트
│   ├── hooks/            # Custom React Hooks
│   ├── lib/              # 유틸리티 함수 및 설정
│   ├── services/         # API 서비스 레이어
│   ├── store/            # Zustand 상태 관리
│   └── types/            # TypeScript 타입 정의
├── public/               # 정적 파일
├── design/               # 설계 문서
├── deployment/           # 배포 관련 파일
│   ├── container/        # Nginx 설정
│   └── k8s/              # Kubernetes 매니페스트
├── Dockerfile            # Docker 이미지 빌드 파일
└── package.json          # 프로젝트 의존성
```

### 8.2 코딩 컨벤션

- **TypeScript**: 타입 안정성을 위해 엄격한 타입 체크 사용
- **ESLint**: Next.js 표준 ESLint 설정 적용
- **Prettier**: 코드 포맷팅 자동화
- **Component**: 함수형 컴포넌트 + React Hooks 사용
- **State Management**: Zustand 활용 (전역 상태), React Query (서버 상태)

### 8.3 API 통신

- **Axios**: HTTP 클라이언트
- **React Query**: 서버 상태 관리 및 캐싱
- **환경 변수**: `NEXT_PUBLIC_*` 접두사 사용

### 8.4 스타일링

- **Material UI**: 주요 UI 컴포넌트 라이브러리
- **Emotion**: CSS-in-JS (Material UI 기본 엔진)
- **반응형 디자인**: Mobile-first 접근 (375px 기준)

## 9. 참고 자료

### 9.1 내부 문서

- [유저스토리](design/userstory.md)
- [논리 아키텍처](design/backend/logical/logical-architecture.md)
- [UI/UX 설계서](design/frontend/uiux-design.md)
- [API 매핑 설계서](design/frontend/api-mapping.md)
- [스타일 가이드](design/frontend/style-guide.md)
- [Kubernetes 배포 가이드](deployment/k8s/deploy-k8s-guide.md)

### 9.2 기술 문서

- [Next.js Documentation](https://nextjs.org/docs)
- [React Documentation](https://react.dev/)
- [Material UI](https://mui.com/)
- [React Query](https://tanstack.com/query/latest)
- [Zustand](https://zustand-demo.pmnd.rs/)

## 10. 팀

- **Product Owner**, **Content Service Developer**: 김채리 (체리)
- **Scrum Master**, **Participation Service Developer**: 김도연 (도다리)
- **DevOps Engineer**, **User Service Developer**: 장원호 (티모)
- **Analytics Service Developer**: 양효원 (와와)
- **AI Service Developer**: 박세원 (뚜이)
- **Event Service Developer**: 송하영 (홍차)
- **Distribution Service Developer**: 이선민 (복치)