mirror of
https://github.com/ktds-dg0501/kt-event-marketing-fe.git
synced 2025-12-06 06:16:24 +00:00
README.md 작성
This commit is contained in:
Hyowon Yang
parent
6331ab3fde
commit
edc189a7e0
3
.idea/.gitignore
generated
vendored
Normal file
3
.idea/.gitignore
generated
vendored
Normal file
@ -0,0 +1,3 @@
|
||||
# 디폴트 무시된 파일
|
||||
/shelf/
|
||||
/workspace.xml
|
||||
9
.idea/kt-event-marketing-fe.iml
generated
Normal file
9
.idea/kt-event-marketing-fe.iml
generated
Normal file
@ -0,0 +1,9 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<module type="JAVA_MODULE" version="4">
|
||||
<component name="NewModuleRootManager" inherit-compiler-output="true">
|
||||
<exclude-output />
|
||||
<content url="file://$MODULE_DIR$" />
|
||||
<orderEntry type="inheritedJdk" />
|
||||
<orderEntry type="sourceFolder" forTests="false" />
|
||||
</component>
|
||||
</module>
|
||||
6
.idea/misc.xml
generated
Normal file
6
.idea/misc.xml
generated
Normal file
@ -0,0 +1,6 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project version="4">
|
||||
<component name="ProjectRootManager" version="2" languageLevel="JDK_23" default="true" project-jdk-name="23" project-jdk-type="JavaSDK">
|
||||
<output url="file://$PROJECT_DIR$/out" />
|
||||
</component>
|
||||
</project>
|
||||
8
.idea/modules.xml
generated
Normal file
8
.idea/modules.xml
generated
Normal file
@ -0,0 +1,8 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project version="4">
|
||||
<component name="ProjectModuleManager">
|
||||
<modules>
|
||||
<module fileurl="file://$PROJECT_DIR$/.idea/kt-event-marketing-fe.iml" filepath="$PROJECT_DIR$/.idea/kt-event-marketing-fe.iml" />
|
||||
</modules>
|
||||
</component>
|
||||
</project>
|
||||
7
.idea/vcs.xml
generated
Normal file
7
.idea/vcs.xml
generated
Normal file
@ -0,0 +1,7 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project version="4">
|
||||
<component name="VcsDirectoryMappings">
|
||||
<mapping directory="" vcs="Git" />
|
||||
<mapping directory="$PROJECT_DIR$" vcs="Git" />
|
||||
</component>
|
||||
</project>
|
||||
449
README.md
Normal file
449
README.md
Normal file
@ -0,0 +1,449 @@
|
||||
# KT 이벤트 파트너
|
||||
- AI 기반 소상공인 마케팅 지원 서비스
|
||||
|
||||
## 1. 소개
|
||||
|
||||
KT AI 기반 소상공인 이벤트 자동 생성 서비스는 소상공인이 AI를 활용하여 효과적인 이벤트를 쉽게 기획하고 관리할 수 있도록 지원하는 플랫폼입니다.
|
||||
매장 정보와 AI 추천을 기반으로 이벤트를 생성하고, SNS 콘텐츠를 자동 생성하며, 다양한 채널로 배포하고, 실시간으로 성과를 분석할 수 있습니다.
|
||||
|
||||
### 1.1 핵심 기능
|
||||
|
||||
- **AI 기반 이벤트 추천**: 매장 정보, 업종, 지역 트렌드를 분석하여 최적의 이벤트 아이디어 제공
|
||||
- **자동 콘텐츠 생성**: AI가 생성한 이벤트 내용을 바탕으로 SNS 이미지 자동 생성
|
||||
- **다중 채널 배포**: 네이버, 카카오톡, 인스타그램 등 다양한 SNS 채널로 원클릭 배포
|
||||
- **참여자 관리**: 이벤트 참여자 접수 및 당첨자 추첨 기능
|
||||
- **실시간 성과 분석**: 조회수, 참여율, ROI 등 실시간 대시보드 제공
|
||||
|
||||
### 1.2 MVP 산출물
|
||||
|
||||
- **발표자료**: [추가 예정]
|
||||
- **설계결과**:
|
||||
- [유저스토리](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, Material UI, React Query, Zustand
|
||||
- **백엔드**: Spring Boot, Java, Kafka (Event Bus + Job Queue)
|
||||
- **인프라**: Azure Kubernetes Service (AKS), Azure Container Registry (ACR)
|
||||
- **CI/CD**: Docker, Kubernetes
|
||||
- **백킹 서비스**:
|
||||
- **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**: 김채리 (체리)
|
||||
- **Scrum Master**: 김도연 (도다리)
|
||||
- **DevOps Engineer**: 장원호 (티모)
|
||||
- **Analytics Service Developer**: 양효원 (와와)
|
||||
- **AI Service Developer**: 박세원 (뚜이)
|
||||
- **Event Service Developer**: 송하영 (홍차)
|
||||
- **Distribution Service Developer**: 이선민 (복치)
|
||||
Loading…
x
Reference in New Issue
Block a user