From 1e3760e85bf6623dde21a6d2a7decfbd9ab1c91c Mon Sep 17 00:00:00 2001
From: SWPARK <35442832+parksewon@users.noreply.github.com>
Date: Fri, 31 Oct 2025 13:31:32 +0900
Subject: [PATCH] Create README.md

---
 README.md | 449 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 449 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0c82b6b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,449 @@
+# 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
+  - **manifest**: [추가 예정]
+- **시연 동영상**: [추가 예정]
+
+## 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**: 이선민 (복치)