From dc4c8aff2e2983cd4d6b2d38fe94081427f58390 Mon Sep 17 00:00:00 2001 From: Hyowon Yang Date: Fri, 31 Oct 2025 10:53:06 +0900 Subject: [PATCH] =?UTF-8?q?readme.md=20=EC=83=9D=EC=84=B1=20=EB=B0=8F=20?= =?UTF-8?q?=EC=83=98=ED=94=8C=EB=8D=B0=EC=9D=B4=ED=84=B0=20=EC=B6=94?= =?UTF-8?q?=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 804 ++++++++++++++++++ .../src/main/resources/sample-data.json | 58 ++ claude/frontend-readme.md | 1 + claude/readme-example.md | 168 ++++ 4 files changed, 1031 insertions(+) create mode 100644 README.md create mode 100644 claude/frontend-readme.md create mode 100644 claude/readme-example.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..bd8ea5c --- /dev/null +++ b/README.md @@ -0,0 +1,804 @@ +# KT AI 기반 소상공인 이벤트 자동 생성 서비스 (Backend) + +> **AI 기반 이벤트 자동 생성 및 관리 서비스의 백엔드 시스템** +> +> 마이크로서비스 아키텍처 기반으로 설계된 확장 가능한 이벤트 관리 플랫폼 + +[![License](https://img.shields.io/badge/license-Educational-blue.svg)]() +[![Java](https://img.shields.io/badge/Java-21-orange.svg)](https://openjdk.org/projects/jdk/21/) +[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.3.0-brightgreen.svg)](https://spring.io/projects/spring-boot) +[![Kubernetes](https://img.shields.io/badge/Kubernetes-AKS-blue.svg)](https://azure.microsoft.com/en-us/products/kubernetes-service) + +## 🚀 빠른 시작 (Quick Start) + +### 사전 요구사항 +```bash +Java 21, Gradle 8.x, Docker & Docker Compose +``` + +### 3단계 실행 +```bash +# 1. 백킹 서비스 시작 (PostgreSQL, Redis, Kafka) +docker-compose up -d + +# 2. 프로젝트 빌드 +./gradlew clean build -x test + +# 3. 서비스 실행 (IntelliJ 실행 프로파일 또는 명령줄) +# IntelliJ: .run/*.run.xml 프로파일 사용 +# 명령줄: java -jar {service-name}/build/libs/{service-name}.jar +``` + +### 동작 확인 +```bash +# Health Check +curl http://localhost:8080/actuator/health # Event Service +curl http://localhost:8081/actuator/health # User Service + +# Swagger UI +http://localhost:8080/swagger-ui.html +``` + +--- + +## 📋 목차 +- [1. 소개](#1-소개) +- [2. 프로젝트 구조](#2-프로젝트-구조) +- [3. 시스템 아키텍처](#3-시스템-아키텍처) +- [4. 로컬 개발 환경 설정](#4-로컬-개발-환경-설정) +- [5. Docker 컨테이너 빌드 및 실행](#5-docker-컨테이너-빌드-및-실행) +- [6. Kubernetes 배포](#6-kubernetes-배포) +- [7. CI/CD](#7-cicd) +- [8. 테스트](#8-테스트) +- [9. 모니터링 및 로깅](#9-모니터링-및-로깅) +- [10. 트러블슈팅](#10-트러블슈팅) +- [11. 개발 참고 자료](#11-개발-참고-자료) +- [12. 팀](#12-팀) +- [13. 라이선스](#13-라이선스) +- [14. 문의](#14-문의) + +--- + +## 1. 소개 +KT AI 기반 소상공인 이벤트 자동 생성 서비스는 고객 유치와 매출 증대를 위한 이벤트를 하고 싶지만, 기획·제작·운영 역량과 시간이 부족한 소상공인 및 중소기업의 업무를 지원하는 AI 기반 자동화 서비스입니다. + +본 저장소는 **백엔드 마이크로서비스**를 포함하며, Spring Boot 3.3.0 기반의 7개 독립 서비스로 구성됩니다. + +### 1.1 관련 저장소 + +| 구분 | 설명 | 저장소 URL | +|------|------|-----------| +| **사내 통합** | 설계 문서 및 통합 관리 | [https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing](https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing) | +| **백엔드** | Spring Boot 마이크로서비스 (현재 저장소) | [https://github.com/ktds-dg0501/kt-event-marketing](https://github.com/ktds-dg0501/kt-event-marketing) | +| **프론트엔드** | React 기반 웹 애플리케이션 | [https://github.com/ktds-dg0501/kt-event-marketing-fe](https://github.com/ktds-dg0501/kt-event-marketing-fe) | +| **K8s Manifest** | Kubernetes 배포 매니페스트 | {Manifest Repo} | + +### 1.2 핵심 기능 +- **AI 이벤트 기획**: 업종과 목적에 맞는 이벤트 자동 기획 +- **이벤트 콘텐츠 생성**: AI 기반 이미지 및 텍스트 콘텐츠 자동 생성 +- **참여자 관리**: 이벤트 참여자 등록 및 당첨자 추첨 자동화 +- **실시간 분석**: 이벤트 진행 상황 및 성과 실시간 모니터링 +- **다채널 배포**: 다양한 채널로 이벤트 자동 배포 + +### 1.3 MVP 산출물 +- **발표자료**: {발표자료 링크} +- **설계결과**: + - [유저스토리](https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing/src/branch/main/design/userstory.md) + - [UI/UX 설계서](https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing/src/branch/main/design/uiux/uiux.md) + - [아키텍처 패턴](https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing/src/branch/main/design/pattern/architecture-pattern.md) + - [High-Level 아키텍처](https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing/src/branch/main/design/high-level-architecture.md) + - [API 설계서](https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing/src/branch/main/design/backend/api/) + - [논리 아키텍처](https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing/src/branch/main/design/backend/logical/) + - [시퀀스 설계](https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing/src/branch/main/design/backend/sequence/) + - [클래스 설계](https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing/src/branch/main/design/backend/class/) + - [데이터베이스 설계](https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing/src/branch/main/design/backend/database/) + - [프론트엔드 설계](https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing/src/branch/main/design/frontend/) +- **Git Repository**: + - **사내 통합 저장소**: https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing + - **백엔드 (GitHub)**: https://github.com/ktds-dg0501/kt-event-marketing.git + - **프론트엔드 (GitHub)**: https://github.com/ktds-dg0501/kt-event-marketing-fe.git + - **K8s Manifest**: {Manifest Repo} +- **시연 동영상**: {시연 동영상 링크} + +## 2. 프로젝트 구조 + +### 2.1 디렉토리 구조 +``` +kt-event-marketing/ +├── user-service/ # 사용자 인증 및 회원 관리 +├── event-service/ # 이벤트 생성, 관리, 스케줄링 +├── content-service/ # AI 콘텐츠 생성 (Python) +├── ai-service/ # AI 이벤트 추천 및 분석 +├── participation-service/ # 참여자 관리 및 당첨자 추첨 +├── analytics-service/ # 통계 분석 +├── distribution-service/ # 다채널 배포 +├── .run/ # IntelliJ 실행 프로파일 +├── design/ # 설계 문서 +│ ├── userstory.md +│ ├── uiux/ +│ ├── backend/ +│ │ ├── api/ # API 설계서 +│ │ ├── logical/ # 논리 아키텍처 +│ │ ├── sequence/ # 시퀀스 다이어그램 +│ │ ├── class/ # 클래스 다이어그램 +│ │ └── database/ # 데이터베이스 설계 +│ ├── frontend/ +│ ├── pattern/ +│ └── high-level-architecture.md +├── deployment/ +│ ├── container/ # Docker 관련 파일 +│ ├── k8s/ # Kubernetes 매니페스트 +│ └── cicd/ # CI/CD 파이프라인 +├── docker-compose.yml # 백킹 서비스 실행 +└── README.md # 본 문서 +``` + +## 3. 시스템 아키텍처 + +### 3.1 전체 구조 +마이크로서비스 아키텍처 기반의 백엔드 서비스와 React 기반 프론트엔드로 구성된 웹 애플리케이션 + +``` +┌─────────────────┐ +│ 프론트엔드 │ +│ (React) │ +└────────┬────────┘ + │ + ┌────┴─────────────────────────────┐ + │ API Gateway (Ingress) │ + └────┬─────────────────────────────┘ + │ + ┌────┴────────────────────────────────────────────┐ + │ 백엔드 서비스 │ + ├──────────┬──────────┬──────────┬──────────────┤ + │ User │ Event │ Content │ Participation│ + │ Service │ Service │ Service │ Service │ + ├──────────┼──────────┼──────────┼──────────────┤ + │ AI │Analytics │Distribution│ │ + │ Service │ Service │ Service │ │ + └──────────┴──────────┴──────────┴──────────────┘ + │ │ │ + ┌────┴───────────┴───────────┴────┐ + │ 백킹 서비스 │ + ├──────────┬──────────┬───────────┤ + │PostgreSQL│ Redis │ Kafka │ + └──────────┴──────────┴───────────┘ +``` + +### 3.2 마이크로서비스 구성 + +| 서비스 | 포트 | 설명 | API Path | +|--------|------|------|----------| +| **user-service** | 8081 | 사용자 인증 및 회원 관리 | /api/v1/users | +| **event-service** | 8080 | 이벤트 생성 및 관리, 스케줄링 | /api/v1/events, /api/v1/jobs | +| **content-service** | 8085 | AI 기반 콘텐츠 생성 (이미지, 텍스트) | /api/v1/content | +| **ai-service** | 8083 | AI 이벤트 추천 및 분석 | /api/v1/ai-service | +| **participation-service** | 8084 | 이벤트 참여자 관리 및 당첨자 추첨 | /api/v1/participations, /api/v1/winners | +| **analytics-service** | 8086 | 이벤트 및 사용자 통계 분석 | /api/v1/events/.../analytics, /api/v1/users/.../analytics | +| **distribution-service** | 8087 | 다채널 이벤트 배포 | /api/v1/distribution | + +### 4.3 기술 스택 +- **백엔드**: + - Java 21 + - Spring Boot 3.3.0 + - Spring Data JPA + - Spring Security + - Spring Kafka + - MapStruct + - OpenAPI (Swagger) +- **프론트엔드**: {React 버전 및 주요 라이브러리} +- **인프라**: + - Azure Kubernetes Service (AKS) + - Azure Container Registry (ACR) + - Ingress Controller +- **CI/CD**: GitHub Actions, Jenkins +- **백킹 서비스**: + - **Database**: PostgreSQL (서비스별 독립 DB) + - **Cache**: Redis (서비스별 독립 DB) + - **Message Queue**: Apache Kafka + +## 4. 로컬 개발 환경 설정 + +### 4.1 사전 요구사항 +- Java 21 +- Gradle 8.x +- Docker & Docker Compose +- PostgreSQL, Redis, Kafka (Docker로 설치 가능) + +### 4.2 백킹 서비스 설치 + +#### 4.2.1 Docker Compose로 백킹 서비스 설치 +프로젝트 루트에 있는 `docker-compose.yml` 사용: + +```bash +# 모든 백킹 서비스 시작 (PostgreSQL, Redis, Kafka) +docker-compose up -d + +# 상태 확인 +docker-compose ps + +# 로그 확인 +docker-compose logs -f +``` + +#### 4.2.2 개별 설치 (선택사항) + +**PostgreSQL 설치** +```bash +# 각 서비스별 데이터베이스 생성 +docker run -d \ + --name postgres-user \ + -e POSTGRES_USER=admin \ + -e POSTGRES_PASSWORD=Passw0rd \ + -e POSTGRES_DB=user_db \ + -p 5432:5432 \ + postgres:15 + +docker run -d \ + --name postgres-event \ + -e POSTGRES_USER=admin \ + -e POSTGRES_PASSWORD=Passw0rd \ + -e POSTGRES_DB=event_db \ + -p 5433:5432 \ + postgres:15 + +docker run -d \ + --name postgres-participation \ + -e POSTGRES_USER=admin \ + -e POSTGRES_PASSWORD=Passw0rd \ + -e POSTGRES_DB=participation_db \ + -p 5434:5432 \ + postgres:15 + +docker run -d \ + --name postgres-analytics \ + -e POSTGRES_USER=admin \ + -e POSTGRES_PASSWORD=Passw0rd \ + -e POSTGRES_DB=analytics_db \ + -p 5435:5432 \ + postgres:15 +``` + +**Redis 설치** +```bash +docker run -d \ + --name redis \ + -p 6379:6379 \ + redis:7-alpine +``` + +**Kafka 설치** +```bash +# Zookeeper +docker run -d \ + --name zookeeper \ + -p 2181:2181 \ + -e ZOOKEEPER_CLIENT_PORT=2181 \ + confluentinc/cp-zookeeper:latest + +# Kafka +docker run -d \ + --name kafka \ + -p 9092:9092 \ + -e KAFKA_ZOOKEEPER_CONNECT=localhost:2181 \ + -e KAFKA_ADVERTISED_LISTENERS=PLAINTEXT://localhost:9092 \ + -e KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR=1 \ + confluentinc/cp-kafka:latest +``` + +### 4.3 애플리케이션 빌드 및 실행 + +#### 4.3.1 전체 프로젝트 빌드 +```bash +# 프로젝트 루트에서 실행 +./gradlew clean build -x test + +# 테스트 포함 빌드 +./gradlew clean build +``` + +#### 4.3.2 개별 서비스 빌드 및 실행 + +**서비스별 빌드** +```bash +# User Service +./gradlew :user-service:clean :user-service:build -x test + +# Event Service +./gradlew :event-service:clean :event-service:build -x test + +# Content Service (Python) +cd content-service +pip install -r requirements.txt + +# AI Service +./gradlew :ai-service:clean :ai-service:build -x test + +# Participation Service +./gradlew :participation-service:clean :participation-service:build -x test + +# Analytics Service +./gradlew :analytics-service:clean :analytics-service:build -x test + +# Distribution Service +./gradlew :distribution-service:clean :distribution-service:build -x test +``` + +**서비스 실행** + +IntelliJ IDEA를 사용하는 경우: +1. `.run` 디렉토리에 있는 실행 프로파일 사용 +2. 각 서비스별 실행 프로파일 선택 후 실행 + +명령줄에서 실행: +```bash +# User Service +java -jar user-service/build/libs/user-service.jar + +# Event Service +java -jar event-service/build/libs/event-service.jar + +# Content Service (Python) +cd content-service +python app.py + +# AI Service +java -jar ai-service/build/libs/ai-service.jar + +# Participation Service +java -jar participation-service/build/libs/participation-service.jar + +# Analytics Service +java -jar analytics-service/build/libs/analytics-service.jar + +# Distribution Service +java -jar distribution-service/build/libs/distribution-service.jar +``` + +#### 4.3.3 서비스 동작 확인 +```bash +# User Service Health Check +curl http://localhost:8081/actuator/health + +# Event Service Health Check +curl http://localhost:8080/actuator/health + +# Content Service Health Check +curl http://localhost:8085/health + +# AI Service Health Check +curl http://localhost:8083/actuator/health + +# Participation Service Health Check +curl http://localhost:8084/actuator/health + +# Analytics Service Health Check +curl http://localhost:8086/actuator/health + +# Distribution Service Health Check +curl http://localhost:8087/actuator/health +``` + +#### 4.3.4 API 문서 확인 +각 서비스의 Swagger UI 접근: +- User Service: http://localhost:8081/swagger-ui.html +- Event Service: http://localhost:8080/swagger-ui.html +- AI Service: http://localhost:8083/swagger-ui.html +- Participation Service: http://localhost:8084/swagger-ui.html +- Analytics Service: http://localhost:8086/swagger-ui.html +- Distribution Service: http://localhost:8087/swagger-ui.html + +## 5. Docker 컨테이너 빌드 및 실행 + +### 5.1 컨테이너 이미지 빌드 + +#### 5.1.1 Java 서비스 이미지 빌드 +```bash +# User Service +docker build \ + --build-arg SERVICE_NAME=user-service \ + -f user-service/Dockerfile \ + -t acrdigitalgarage01.azurecr.io/kt-event/user-service:latest . + +# Event Service +docker build \ + --build-arg SERVICE_NAME=event-service \ + -f event-service/Dockerfile \ + -t acrdigitalgarage01.azurecr.io/kt-event/event-service:latest . + +# AI Service +docker build \ + --build-arg SERVICE_NAME=ai-service \ + -f ai-service/Dockerfile \ + -t acrdigitalgarage01.azurecr.io/kt-event/ai-service:latest . + +# Participation Service +docker build \ + --build-arg SERVICE_NAME=participation-service \ + -f participation-service/Dockerfile \ + -t acrdigitalgarage01.azurecr.io/kt-event/participation-service:latest . + +# Analytics Service +docker build \ + --build-arg SERVICE_NAME=analytics-service \ + -f analytics-service/Dockerfile \ + -t acrdigitalgarage01.azurecr.io/kt-event/analytics-service:latest . + +# Distribution Service +docker build \ + --build-arg SERVICE_NAME=distribution-service \ + -f distribution-service/Dockerfile \ + -t acrdigitalgarage01.azurecr.io/kt-event/distribution-service:latest . +``` + +#### 5.1.2 Python 서비스 이미지 빌드 +```bash +# Content Service +docker build \ + -f content-service/Dockerfile \ + -t acrdigitalgarage01.azurecr.io/kt-event/content-service:latest \ + content-service/ +``` + +### 5.2 컨테이너 실행 + +#### 5.2.1 Docker Compose로 전체 실행 +```bash +# deployment/container 디렉토리로 이동 +cd deployment/container + +# 전체 서비스 시작 +docker-compose up -d + +# 상태 확인 +docker-compose ps + +# 로그 확인 +docker-compose logs -f +``` + +#### 5.2.2 개별 컨테이너 실행 +```bash +# User Service +docker run -d \ + --name user-service \ + -p 8081:8081 \ + -e DB_HOST=host.docker.internal \ + -e DB_PORT=5432 \ + -e DB_NAME=user_db \ + -e REDIS_HOST=host.docker.internal \ + -e KAFKA_BOOTSTRAP_SERVERS=host.docker.internal:9092 \ + acrdigitalgarage01.azurecr.io/kt-event/user-service:latest + +# Event Service +docker run -d \ + --name event-service \ + -p 8080:8080 \ + -e DB_HOST=host.docker.internal \ + -e DB_PORT=5433 \ + -e DB_NAME=event_db \ + -e REDIS_HOST=host.docker.internal \ + -e KAFKA_BOOTSTRAP_SERVERS=host.docker.internal:9092 \ + acrdigitalgarage01.azurecr.io/kt-event/event-service:latest +``` + +자세한 컨테이너 실행 가이드는 [run-container-guide-back.md](deployment/container/run-container-guide-back.md)를 참조하세요. + +## 6. Kubernetes 배포 + +### 6.1 사전 요구사항 +- Azure CLI 설치 및 로그인 +- kubectl 설치 +- AKS 클러스터 접근 권한 + +### 6.2 Azure 로그인 및 AKS 연결 +```bash +# Azure 로그인 +az login + +# AKS Credential 가져오기 +az aks get-credentials \ + --resource-group rg-digitalgarage-01 \ + --name aks-digitalgarage-01 + +# 연결 확인 +kubectl cluster-info +``` + +### 6.3 네임스페이스 생성 +```bash +# 네임스페이스 생성 +kubectl create namespace kt-event-marketing + +# 네임스페이스 확인 +kubectl get namespace kt-event-marketing +``` + +### 6.4 백킹 서비스 설치 (Kubernetes) + +#### 6.4.1 PostgreSQL 설치 +```bash +# Helm 저장소 추가 +helm repo add bitnami https://charts.bitnami.com/bitnami +helm repo update + +# User Service용 DB +helm install user-postgresql bitnami/postgresql \ + --namespace kt-event-marketing \ + --set global.postgresql.auth.postgresPassword=Passw0rd \ + --set global.postgresql.auth.username=admin \ + --set global.postgresql.auth.password=Passw0rd \ + --set global.postgresql.auth.database=user_db + +# Event Service용 DB +helm install event-postgresql bitnami/postgresql \ + --namespace kt-event-marketing \ + --set global.postgresql.auth.postgresPassword=Passw0rd \ + --set global.postgresql.auth.username=admin \ + --set global.postgresql.auth.password=Passw0rd \ + --set global.postgresql.auth.database=event_db + +# Participation Service용 DB +helm install participation-postgresql bitnami/postgresql \ + --namespace kt-event-marketing \ + --set global.postgresql.auth.postgresPassword=Passw0rd \ + --set global.postgresql.auth.username=admin \ + --set global.postgresql.auth.password=Passw0rd \ + --set global.postgresql.auth.database=participation_db + +# Analytics Service용 DB +helm install analytics-postgresql bitnami/postgresql \ + --namespace kt-event-marketing \ + --set global.postgresql.auth.postgresPassword=Passw0rd \ + --set global.postgresql.auth.username=admin \ + --set global.postgresql.auth.password=Passw0rd \ + --set global.postgresql.auth.database=analytics_db +``` + +#### 6.4.2 Redis 설치 +```bash +helm install redis bitnami/redis \ + --namespace kt-event-marketing \ + --set auth.password=Passw0rd \ + --set master.persistence.enabled=false \ + --set replica.replicaCount=0 +``` + +#### 6.4.3 Kafka 설치 +```bash +helm install kafka bitnami/kafka \ + --namespace kt-event-marketing \ + --set persistence.enabled=false \ + --set zookeeper.persistence.enabled=false +``` + +### 6.5 컨테이너 이미지 푸시 + +#### 6.5.1 ACR 로그인 +```bash +az acr login --name acrdigitalgarage01 +``` + +#### 6.5.2 이미지 푸시 +```bash +# 모든 서비스 이미지 푸시 +docker push acrdigitalgarage01.azurecr.io/kt-event/user-service:latest +docker push acrdigitalgarage01.azurecr.io/kt-event/event-service:latest +docker push acrdigitalgarage01.azurecr.io/kt-event/content-service:latest +docker push acrdigitalgarage01.azurecr.io/kt-event/ai-service:latest +docker push acrdigitalgarage01.azurecr.io/kt-event/participation-service:latest +docker push acrdigitalgarage01.azurecr.io/kt-event/analytics-service:latest +docker push acrdigitalgarage01.azurecr.io/kt-event/distribution-service:latest +``` + +### 6.6 Kubernetes 매니페스트 배포 + +#### 6.6.1 Secret 및 ConfigMap 생성 +```bash +# Common Secret 생성 +kubectl apply -f deployment/k8s/common/secret-common.yaml -n kt-event-marketing + +# Common ConfigMap 생성 +kubectl apply -f deployment/k8s/common/cm-common.yaml -n kt-event-marketing + +# Image Pull Secret 생성 +kubectl apply -f deployment/k8s/common/secret-imagepull.yaml -n kt-event-marketing +``` + +#### 6.6.2 서비스별 배포 +```bash +# User Service +kubectl apply -f deployment/k8s/user-service/ -n kt-event-marketing + +# Event Service +kubectl apply -f deployment/k8s/event-service/ -n kt-event-marketing + +# Content Service +kubectl apply -f deployment/k8s/content-service/ -n kt-event-marketing + +# AI Service +kubectl apply -f deployment/k8s/ai-service/ -n kt-event-marketing + +# Participation Service +kubectl apply -f deployment/k8s/participation-service/ -n kt-event-marketing + +# Analytics Service +kubectl apply -f deployment/k8s/analytics-service/ -n kt-event-marketing + +# Distribution Service +kubectl apply -f deployment/k8s/distribution-service/ -n kt-event-marketing + +# Ingress 생성 +kubectl apply -f deployment/k8s/common/ingress.yaml -n kt-event-marketing +``` + +#### 6.6.3 배포 확인 +```bash +# Pod 상태 확인 +kubectl get pods -n kt-event-marketing + +# Service 확인 +kubectl get svc -n kt-event-marketing + +# Ingress 확인 +kubectl get ingress -n kt-event-marketing + +# Pod 로그 확인 +kubectl logs -f -n kt-event-marketing +``` + +자세한 Kubernetes 배포 가이드는 [deploy-k8s-guide.md](deployment/k8s/deploy-k8s-guide.md)를 참조하세요. + +## 7. CI/CD + +### 7.1 GitHub Actions CI/CD +GitHub Actions를 사용한 자동 빌드 및 배포 파이프라인이 구성되어 있습니다. + +**워크플로우 파일**: `.github/workflows/` + +**주요 단계**: +1. 코드 체크아웃 +2. Java 환경 설정 +3. Gradle 빌드 +4. Docker 이미지 빌드 +5. ACR에 이미지 푸시 +6. AKS에 배포 + +### 7.2 Jenkins CI/CD +Jenkins를 사용한 CI/CD 파이프라인 구성이 가능합니다. + +자세한 CI/CD 가이드는 [CICD-GUIDE.md](deployment/cicd/CICD-GUIDE.md)를 참조하세요. + +## 8. 테스트 + +### 8.1 프론트엔드 접근 +```bash +# Ingress External IP 확인 +kubectl get ingress -n kt-event-marketing + +# 브라우저에서 접근 +http:// +``` + +### 8.2 API 테스트 +```bash +# User Service API 테스트 +curl http:///api/v1/users/health + +# Event Service API 테스트 +curl http:///api/v1/events + +# API 문서 확인 +http:///api/v1/users/swagger-ui.html +``` + +### 8.3 테스트 계정 +- **ID**: test@example.com +- **PW**: Test123!@# + +## 9. 모니터링 및 로깅 + +### 9.1 애플리케이션 로그 확인 +```bash +# 특정 서비스 로그 확인 +kubectl logs -f deployment/user-service -n kt-event-marketing + +# 전체 로그 스트리밍 +kubectl logs -f -l app=kt-event-marketing -n kt-event-marketing +``` + +### 9.2 Health Check +각 서비스는 Spring Boot Actuator를 통해 헬스 체크를 제공합니다: +- `/actuator/health`: 서비스 헬스 상태 +- `/actuator/info`: 서비스 정보 +- `/actuator/metrics`: 메트릭 정보 + +## 10. 트러블슈팅 + +### 10.1 일반적인 문제 + +**문제: Pod가 CrashLoopBackOff 상태** +```bash +# Pod 상세 정보 확인 +kubectl describe pod -n kt-event-marketing + +# 로그 확인 +kubectl logs -n kt-event-marketing + +# 이전 컨테이너 로그 확인 +kubectl logs -n kt-event-marketing --previous +``` + +**문제: 데이터베이스 연결 실패** +- Secret 및 ConfigMap의 환경 변수 확인 +- 데이터베이스 서비스 상태 확인 +- 네트워크 정책 및 방화벽 규칙 확인 + +**문제: 이미지 Pull 실패** +- ACR 로그인 확인 +- Image Pull Secret 확인 +- 이미지 이름 및 태그 확인 + +### 10.2 유용한 명령어 +```bash +# 전체 리소스 확인 +kubectl get all -n kt-event-marketing + +# 특정 리소스 재시작 +kubectl rollout restart deployment/ -n kt-event-marketing + +# ConfigMap 확인 +kubectl get configmap -n kt-event-marketing + +# Secret 확인 +kubectl get secret -n kt-event-marketing +``` + +## 11. 개발 참고 자료 + +### 11.1 프로젝트 문서 +- [유저스토리](https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing/src/branch/main/design/userstory.md) +- [UI/UX 설계서](https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing/src/branch/main/design/uiux/uiux.md) +- [아키텍처 패턴](https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing/src/branch/main/design/pattern/architecture-pattern.md) +- [High-Level 아키텍처](https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing/src/branch/main/design/high-level-architecture.md) +- [API 설계서](https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing/src/branch/main/design/backend/api/) +- [논리 아키텍처](https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing/src/branch/main/design/backend/logical/) +- [시퀀스 설계](https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing/src/branch/main/design/backend/sequence/) +- [클래스 설계](https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing/src/branch/main/design/backend/class/) +- [데이터베이스 설계서](https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing/src/branch/main/design/backend/database/) +- [프론트엔드 설계](https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing/src/branch/main/design/frontend/) +- [개발 변경 이력](https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing/src/branch/main/DEVELOP_CHANGELOG.md) + +### 11.2 가이드 문서 +- [백킹 서비스 설치 방법](backing-service/) +- [컨테이너 이미지 빌드](deployment/container/build-image.md) +- [Kubernetes 배포 가이드](deployment/k8s/deploy-k8s-guide.md) +- [CI/CD 가이드](deployment/cicd/CICD-GUIDE.md) + +## 12. 팀 + +### 12.1 Product Owner +- **갑빠** - Value Oriented, Interactive, Iterative를 중시하는 애자일 전문가 + +### 12.2 Scrum Master +- **한준석 "퍼실리테이터"** - 소통과 팀워크를 중시하는 스크럼 마스터 + +### 12.3 개발팀 +- **이미준 "도그냥"** - 서비스 기획자 (Lead) +- **Flynn "플린"** - 플랫폼 기획자 +- **이소영 "그로스해커"** - 마케팅 전략가 +- **박민지 "픽셀"** - UI/UX 디자이너 +- **김태현 "리액트킹"** - 프론트엔드 개발자 +- **최수연 "아키텍처"** - 백엔드 개발자 +- **정현우 "데이터마법사"** - 데이터 사이언티스트 +- **박영자 "전문 아키텍트"** - 시스템 아키텍트 +- **송근정 "데브옵스 마스터"** - DevOps 엔지니어 + +### 12.4 사용자 대표 +- **정우진 "사장님"** - 소상공인 대표 (테스트 및 피드백) + +## 13. 라이선스 +이 프로젝트는 교육 목적으로 작성되었습니다. + +## 14. 문의 +프로젝트 관련 문의사항은 GitHub Issues를 통해 등록해 주세요. diff --git a/analytics-service/src/main/resources/sample-data.json b/analytics-service/src/main/resources/sample-data.json index b6c1269..e191691 100644 --- a/analytics-service/src/main/resources/sample-data.json +++ b/analytics-service/src/main/resources/sample-data.json @@ -32,6 +32,17 @@ "startDate": "2025-01-01T00:00:00", "endDate": "2025-01-08T23:59:00", "createdAt": "2024-12-28T09:00:00" + }, + { + "eventId": "evt_2025020104", + "eventTitle": "2월 신메뉴 출시 기념", + "storeId": "store_001", + "totalInvestment": 2000000, + "expectedRevenue": 3000000, + "status": "DRAFT", + "startDate": "2025-02-01T00:00:00", + "endDate": "2025-02-28T23:59:00", + "createdAt": "2025-01-25T09:00:00" } ], "distributions": [ @@ -136,6 +147,40 @@ "distributionCostRatio": 0.15 } ] + }, + { + "eventId": "evt_2025020104", + "completedAt": null, + "channels": [ + { + "channel": "우리동네TV", + "channelType": "TV", + "status": "DRAFT", + "expectedViews": 0, + "distributionCostRatio": 0 + }, + { + "channel": "지니TV", + "channelType": "TV", + "status": "DRAFT", + "expectedViews": 0, + "distributionCostRatio": 0 + }, + { + "channel": "링고비즈", + "channelType": "CALL", + "status": "DRAFT", + "expectedViews": 0, + "distributionCostRatio": 0 + }, + { + "channel": "SNS", + "channelType": "SNS", + "status": "DRAFT", + "expectedViews": 0, + "distributionCostRatio": 0 + } + ] } ], "participants": [ @@ -177,6 +222,19 @@ "지니TV": 20, "링고비즈": 10 } + }, + { + "eventId": "evt_2025020104", + "participantRange": { + "start": 0, + "end": 0 + }, + "channelWeights": { + "SNS": 0, + "우리동네TV": 0, + "지니TV": 0, + "링고비즈": 0 + } } ], "config": { diff --git a/claude/frontend-readme.md b/claude/frontend-readme.md new file mode 100644 index 0000000..1becba2 --- /dev/null +++ b/claude/frontend-readme.md @@ -0,0 +1 @@ +404: Not Found \ No newline at end of file diff --git a/claude/readme-example.md b/claude/readme-example.md new file mode 100644 index 0000000..46edd89 --- /dev/null +++ b/claude/readme-example.md @@ -0,0 +1,168 @@ +# 마이구독 서비스 (LifeSub) + +## 1. 소개 +마이구독은 다양한, 증가하는 생활 구독 서비스를 한 곳에서 편리하게 관리할 수 있는 애플리케이션입니다. +사용자가 구독 중인 서비스를 한눈에 확인하고, 월별 구독료를 관리하며, 새로운 구독 서비스를 추천받을 수 있습니다. + +### 1.1 핵심 기능 +- **구독 관리**: 다양한 구독 서비스를 한 곳에서 관리 +- **비용 분석**: 월별 구독료 총액 및 수준 확인 (Liker, Collector, Addict) +- **맞춤형 추천**: 사용자의 지출 패턴 기반 새로운 구독 서비스 추천 + +### 1.2 MVP 산출물 +- **발표자료**: {발표자료 링크} +- **설계결과**: {설계결과 링크} +- **Git Repo**: + - **프론트엔드**: https://github.com/cna-bootcamp/lifesub-web.git + - **백엔드**: https://github.com/cna-bootcamp/lifesub.git + - **manifest**: https://github.com/cna-bootcamp/lifesub-manifest.git +- **시연 동영상**: {시연 동영상 링크} + +## 2. 시스템 아키텍처 + +### 2.1 전체 구조 +프론트엔드와 마이크로서비스 백엔드로 구성된 웹 애플리케이션 +{전체 서비스와 관계를 표현한 Context Map이나 논리아키텍처} + +### 2.2 마이크로서비스 구성 +- **회원 서비스 (Member)**: 사용자 인증 및 토큰 관리 +- **구독 서비스 (MySub)**: 구독 정보 관리 및 카테고리 관리 +- **추천 서비스 (Recommend)**: 사용자 맞춤형 구독 서비스 추천 + +### 2.3 기술 스택 +- **프론트엔드**: React, Material UI, React Router +- **백엔드**: Spring Boot, Java +- **인프라**: Azure Kubernetes Service (AKS), Azure Container Registry +- **CI/CD**: Jenkins, Podman (컨테이너 빌드) +- **코드 품질**: SonarQube +- **백킹 서비스**: + - **Database**: PostgreSQL + - **Message Queue**: RabbitMQ + - **기타**: Redis + +## 3. 백킹 서비스 설치 +1. Database 설치 + ```bash + # Helm 저장소 추가 + helm repo add bitnami https://charts.bitnami.com/bitnami + helm repo update + + # Member 서비스용 DB + helm install member bitnami/postgresql \ + --set global.postgresql.auth.postgresPassword=Passw0rd \ + --set global.postgresql.auth.username=admin \ + --set global.postgresql.auth.password=Passw0rd \ + --set global.postgresql.auth.database=member + + # MySub 서비스용 DB + helm install mysub bitnami/postgresql \ + --set global.postgresql.auth.postgresPassword=Passw0rd \ + --set global.postgresql.auth.username=admin \ + --set global.postgresql.auth.password=Passw0rd \ + --set global.postgresql.auth.database=mysub + + # Recommend 서비스용 DB + helm install recommend bitnami/postgresql \ + --set global.postgresql.auth.postgresPassword=Passw0rd \ + --set global.postgresql.auth.username=admin \ + --set global.postgresql.auth.password=Passw0rd \ + --set global.postgresql.auth.database=recommend + ``` + +2. Message Queue 설치 + 설치 방법 + {MQ별 설치 방법 안내} + + + +## 4. 빌드 및 배포 + +### 4.1 프론트엔드 빌드 및 배포 +1. 컨테이너 이미지 빌드 + ```bash + docker build \ + --build-arg PROJECT_FOLDER="." \ + --build-arg REACT_APP_MEMBER_URL="http://api.example.com/member" \ + --build-arg REACT_APP_MYSUB_URL="http://api.example.com/mysub" \ + --build-arg REACT_APP_RECOMMEND_URL="http://api.example.com/recommend" \ + --build-arg BUILD_FOLDER="deployment/container" \ + --build-arg EXPORT_PORT="18080" \ + -f deployment/container/Dockerfile-lifesub-web \ + -t {Image Registry주소}/lifesub/lifesub-web:latest . + ``` + +2. 이미지 푸시 + ```bash + docker push {Image Registry주소}/lifesub/lifesub-web:latest + ``` + +3. Kubernetes 배포 + ```bash + kubectl apply -f deployment/manifest/ + ``` + +### 4.2 백엔드 빌드 및 배포 +1. 애플리케이션 빌드 + ```bash + # 각 서비스 모듈을 개별적으로 빌드 + ./gradlew :member:clean :member:build -x test + ./gradlew :mysub-infra:clean :mysub-infra:build -x test + ./gradlew :recommend:clean :recommend:build -x test + ``` + +2. 컨테이너 이미지 빌드 (각 서비스별로 수행) + ```bash + # Member 서비스 + docker build \ + --build-arg BUILD_LIB_DIR="member/build/libs" \ + --build-arg ARTIFACTORY_FILE="member.jar" \ + -f deployment/Dockerfile \ + -t {Image Registry주소}/lifesub/member:latest . + + # MySub 서비스 + docker build \ + --build-arg BUILD_LIB_DIR="mysub-infra/build/libs" \ + --build-arg ARTIFACTORY_FILE="mysub.jar" \ + -f deployment/Dockerfile \ + -t {Image Registry주소}/lifesub/mysub:latest . + + # Recommend 서비스 + docker build \ + --build-arg BUILD_LIB_DIR="recommend/build/libs" \ + --build-arg ARTIFACTORY_FILE="recommend.jar" \ + -f deployment/Dockerfile \ + -t {Image Registry주소}/lifesub/recommend:latest . + ``` + +3. 이미지 푸시 + ```bash + docker push {Image Registry주소}/lifesub/member:latest + docker push {Image Registry주소}/lifesub/mysub:latest + docker push {Image Registry주소}/lifesub/recommend:latest + ``` + +4. Kubernetes 배포 + ```bash + kubectl apply -f deployment/manifest/ + ``` + +### 4.3 테스트 +1) 프론트 페이지 주소 구하기 +``` +kubens {namespace} +k get svc +``` + +2) 로그인 +- ID: user01 ~ user05 +- PW: P@ssw0rd$ + +## 5. 팀 + +- 오유진 "피오" - Product Owner +- 강동훈 "테키" - Tech Lead +- 김민지 "유엑스" - UX Designer +- 이준혁 "백개" - Backend Developer +- 박소연 "프개" - Frontend Developer +- 최진우 "큐에이" - QA Engineer +- 정해린 "데브옵스" - DevOps Engineer