mirror of
https://github.com/ktds-dg0501/kt-event-marketing.git
synced 2025-12-06 08:46:23 +00:00
add logical architecture
This commit is contained in:
cherry2250
parent
bd07ef0cce
commit
597e3716e7
197
claude/common-principles.md
Normal file
197
claude/common-principles.md
Normal file
@ -0,0 +1,197 @@
|
|||||||
|
# 공통설계원칙
|
||||||
|
|
||||||
|
모든 설계 단계에서 공통으로 적용되는 핵심 원칙과 전략
|
||||||
|
|
||||||
|
## 🎯 핵심 원칙
|
||||||
|
|
||||||
|
### 1. 🚀 실행 우선 원칙
|
||||||
|
- **프롬프트 우선**: 바로 실행할 수 있는 프롬프트로 작업 시작
|
||||||
|
- **가이드 학습**: 원리와 방법론은 가이드로 깊이 있게 학습
|
||||||
|
- **점진적 이해**: 실행 → 결과 확인 → 원리 학습 순서
|
||||||
|
|
||||||
|
### 2. 🔄 병렬 처리 전략
|
||||||
|
- **서브 에이전트 활용**: Task 도구로 서비스별 동시 작업
|
||||||
|
- **의존성 기반 그룹화**: 의존 관계에 따른 순차/병렬 처리 결정
|
||||||
|
- **통합 검증**: 병렬 작업 완료 후 전체적 일관성 검증
|
||||||
|
|
||||||
|
### 3. 🏗️ 마이크로서비스 설계 원칙
|
||||||
|
- **서비스 독립성**: 캐시를 통한 직접 의존성 최소화
|
||||||
|
- **선택적 비동기**: 장시간 작업(AI 일정 생성)만 비동기 처리
|
||||||
|
- **캐시 우선**: Redis를 통한 성능 최적화
|
||||||
|
- **독립 배포**: 서비스별 독립적 배포 가능한 구조
|
||||||
|
|
||||||
|
### 4. 📝 표준화 원칙
|
||||||
|
- **PlantUML**: 모든 다이어그램 표준 (`!theme mono`)
|
||||||
|
- **OpenAPI 3.0**: API 명세 표준
|
||||||
|
- **자동 검증**: PlantUML, OpenAPI 문법 검사 필수
|
||||||
|
- **일관된 네이밍**: kebab-case 파일명, 표준화된 스키마명
|
||||||
|
|
||||||
|
### 5. ✅ 검증 우선 원칙
|
||||||
|
- **각 단계마다 자동 검증**: 품질 보장
|
||||||
|
- **실시간 피드백**: 오류 조기 발견 및 수정
|
||||||
|
- **CI/CD 통합**: 자동화된 검증 프로세스
|
||||||
|
- **PlantUML 스크립트 파일 생성 즉시 검사 실행**: 'PlantUML 문법 검사 가이드' 준용
|
||||||
|
|
||||||
|
### 6. 🚀 점진적 구현 원칙
|
||||||
|
- **MVP → 확장 → 고도화**: 단계별 접근
|
||||||
|
- **YAGNI 적용**: 꼭 필요한 기능만 구현(YAGNI원칙:You aren't gonna need it)
|
||||||
|
- **지속적 개선**: 피드백 기반 점진적 발전
|
||||||
|
|
||||||
|
## 🔧 의존성 분석 및 병렬 처리
|
||||||
|
|
||||||
|
### 의존성 분석 방법
|
||||||
|
|
||||||
|
1. **서비스 간 의존성 파악**
|
||||||
|
```
|
||||||
|
일정 서비스 → 프로파일 서비스 (멤버/여행 정보 조회)
|
||||||
|
일정 서비스 → 장소 서비스 (장소 정보 조회)
|
||||||
|
장소 서비스: 독립적 (외부 API만 사용)
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **의존성 기반 그룹화**
|
||||||
|
```
|
||||||
|
Group A (순차 처리): 프로파일 → 일정 서비스
|
||||||
|
Group B (독립 처리): 장소 서비스
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **에이전트 할당 및 병렬 처리**
|
||||||
|
```
|
||||||
|
Agent 1: Group A 담당
|
||||||
|
- 프로파일 서비스 설계
|
||||||
|
- 일정 서비스 설계 (프로파일 참조)
|
||||||
|
|
||||||
|
Agent 2: Group B 담당
|
||||||
|
- 장소 서비스 설계 (독립적)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 병렬 처리 적용 가이드
|
||||||
|
|
||||||
|
#### API 설계 단계
|
||||||
|
- **독립 서비스**: 각각 별도 에이전트
|
||||||
|
- **의존 서비스**: 동일 에이전트 내 순차 처리
|
||||||
|
- **공통 검증**: 모든 에이전트 완료 후 swagger-cli 검증
|
||||||
|
|
||||||
|
#### 시퀀스 설계 단계
|
||||||
|
- **외부 시퀀스**: 플로우별 병렬 처리 (각 플로우는 독립적)
|
||||||
|
- **내부 시퀀스**: 서비스별 병렬 처리 (서비스 내부는 독립적)
|
||||||
|
|
||||||
|
#### 클래스/데이터 설계 단계
|
||||||
|
- **의존성 그룹별**: 참조 관계가 있는 서비스들은 순차 처리
|
||||||
|
- **독립 서비스**: 병렬 처리
|
||||||
|
- **공통 클래스**: 모든 서비스 설계 완료 후 마지막 처리
|
||||||
|
|
||||||
|
## 🎨 PlantUML 작성 표준
|
||||||
|
|
||||||
|
### 기본 템플릿
|
||||||
|
```plantuml
|
||||||
|
@startuml
|
||||||
|
!theme mono
|
||||||
|
|
||||||
|
title [다이어그램 제목]
|
||||||
|
|
||||||
|
' 다이어그램 내용
|
||||||
|
@enduml
|
||||||
|
```
|
||||||
|
|
||||||
|
### 필수 검증
|
||||||
|
- **각 파일 생성 직후 PlantUML 문법 검사 수행**
|
||||||
|
- **파이프 방식 권장**: `cat "파일" | docker exec -i plantuml ...`
|
||||||
|
- **화살표 문법 주의**: sequence diagram에서 `..>` 사용 금지
|
||||||
|
|
||||||
|
### 스타일 가이드
|
||||||
|
- **폰트 크기**: 적절한 가독성 확보
|
||||||
|
- **색상 구분**: 서비스별, 레이어별 색상 구분
|
||||||
|
- **설명 추가**: note를 활용한 상세 설명
|
||||||
|
|
||||||
|
## 🔌 API 설계 표준
|
||||||
|
|
||||||
|
### 파일 구조
|
||||||
|
```
|
||||||
|
design/backend/api/{service-name}-api.yaml
|
||||||
|
```
|
||||||
|
|
||||||
|
### 필수 필드
|
||||||
|
```yaml
|
||||||
|
paths:
|
||||||
|
/endpoint:
|
||||||
|
get:
|
||||||
|
summary: API 목적 설명
|
||||||
|
operationId: 고유 식별자
|
||||||
|
x-user-story: 유저스토리 ID
|
||||||
|
x-controller: 담당 컨트롤러
|
||||||
|
tags: [API 그룹]
|
||||||
|
```
|
||||||
|
|
||||||
|
### 스키마 원칙
|
||||||
|
- **서비스별 독립**: 각 서비스 파일에 모든 스키마 포함
|
||||||
|
- **중복 허용**: 초기에는 중복을 허용하고 점진적으로 공통화
|
||||||
|
- **명확한 네이밍**: Request/Response DTO 네이밍 표준
|
||||||
|
|
||||||
|
## 🔄 시퀀스 설계 표준
|
||||||
|
|
||||||
|
### 외부 시퀀스 (서비스 간)
|
||||||
|
- **참여 서비스만**: 해당 플로우에 참여하는 서비스만 표시
|
||||||
|
- **API 호출 중심**: 서비스 간 API 호출 순서 표현
|
||||||
|
- **한글 설명**: 각 호출의 목적을 한글로 명시
|
||||||
|
|
||||||
|
### 내부 시퀀스 (서비스 내부)
|
||||||
|
- **모든 API 표시**: 해당 서비스의 모든 API 포함
|
||||||
|
- **내부 처리 흐름**: 컨트롤러 → 서비스 → 레포지토리 플로우
|
||||||
|
- **기술적 세부사항**: 캐시, DB 접근 등 포함
|
||||||
|
|
||||||
|
### 동기/비동기 구분
|
||||||
|
- **실선 (→)**: 동기 호출
|
||||||
|
- **점선 (->>)**: 비동기 호출
|
||||||
|
- **양방향**: 필요시에만 사용
|
||||||
|
|
||||||
|
## 📊 클래스 설계 표준
|
||||||
|
|
||||||
|
### 아키텍처 적용
|
||||||
|
- **Clean Architecture**: Port/Adapter 용어 대신 표준 Clean 용어 사용
|
||||||
|
- **멀티프로젝트**: 서비스별 독립 모듈
|
||||||
|
- **패키지 구조 표준**: 일관된 패키지 구조 적용
|
||||||
|
|
||||||
|
### 관계 표현
|
||||||
|
- **Generalization**: 상속 관계
|
||||||
|
- **Realization**: 인터페이스 구현
|
||||||
|
- **Dependency**: 의존 관계
|
||||||
|
- **Association**: 연관 관계
|
||||||
|
- **Aggregation/Composition**: 집약/합성 관계
|
||||||
|
|
||||||
|
### 상세 정보
|
||||||
|
- **프로퍼티와 메소드**: 모두 명시
|
||||||
|
- **접근 제한자**: 적절한 가시성 설정
|
||||||
|
- **타입 정보**: 정확한 데이터 타입 명시
|
||||||
|
|
||||||
|
## 🗄️ 데이터 설계 표준
|
||||||
|
|
||||||
|
### 서비스별 DB 분리
|
||||||
|
- **각 서비스마다 독립적인 데이터베이스**
|
||||||
|
- **서비스 간 데이터 공유 최소화**
|
||||||
|
- **캐시를 통한 성능 최적화**
|
||||||
|
|
||||||
|
### 클래스 설계와 일치
|
||||||
|
- **Entity 클래스와 테이블 매핑**
|
||||||
|
- **일관된 네이밍 컨벤션**
|
||||||
|
- **적절한 정규화 수준**
|
||||||
|
|
||||||
|
## 🚨 주의사항
|
||||||
|
|
||||||
|
### PlantUML 문법
|
||||||
|
- **sequence diagram에서 `..>` 사용 금지**
|
||||||
|
- **비동기는 `->>` 또는 `-->>` 사용**
|
||||||
|
- **테마는 반드시 `mono` 사용**
|
||||||
|
|
||||||
|
### 병렬 처리
|
||||||
|
- **의존성 분석 선행**: 병렬 처리 전 반드시 의존성 파악
|
||||||
|
- **순차 처리 필요시**: 무리한 병렬화보다는 안전한 순차 처리
|
||||||
|
- **검증 단계 필수**: 병렬 처리 후 통합 검증
|
||||||
|
|
||||||
|
### API 설계
|
||||||
|
- **유저스토리 ID 필수**: x-user-story 필드 누락 금지
|
||||||
|
- **Controller 명시**: x-controller 필드로 담당 컨트롤러 명시
|
||||||
|
- **스키마 완전성**: 모든 Request/Response 스키마 정의
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
💡 **이 원칙들은 모든 설계 단계에서 일관되게 적용되어야 하며, 각 단계별 세부 가이드에서 구체적으로 구현됩니다.**
|
||||||
64
claude/logical-architecture-design.md
Normal file
64
claude/logical-architecture-design.md
Normal file
@ -0,0 +1,64 @@
|
|||||||
|
# 논리아키텍처설계가이드
|
||||||
|
|
||||||
|
[요청사항]
|
||||||
|
- <작성원칙>을 준용하여 설계
|
||||||
|
- <작성순서>에 따라 설계
|
||||||
|
- [결과파일] 안내에 따라 파일 작성
|
||||||
|
- 완료 후 mermaid 스크립트 테스트 방법 안내
|
||||||
|
- https://mermaid.live/edit 에 접근
|
||||||
|
- 스크립트 내용을 붙여넣어 확인
|
||||||
|
|
||||||
|
[가이드]
|
||||||
|
<작성원칙>
|
||||||
|
- **유저스토리와 매칭**되어야 함. **불필요한 추가 설계 금지**
|
||||||
|
- UI/UX설계서의 '사용자 플로우'참조하여 설계
|
||||||
|
- '아키텍처패턴'에 선정된 클라우드 디자인 패턴을 적용하여 설계
|
||||||
|
- 사용자 관점의 컴포넌트 다이어그램 작성
|
||||||
|
- Context Map 스타일로 서비스 내부 구조는 생략하고 서비스 간 관계에 집중
|
||||||
|
- 클라이언트에서 API Gateway로는 단일 연결선으로 표현
|
||||||
|
<작성순서>
|
||||||
|
- 준비:
|
||||||
|
- 유저스토리, UI/UX설계서, 아키텍처패턴 분석 및 이해
|
||||||
|
- "@analyze --play" 프로토타입이 있는 경우 웹브라우저에서 실행하여 서비스 이해
|
||||||
|
- 실행:
|
||||||
|
- 논리아키텍처 설계서(logical-architecture.md) 작성: 아래 항목은 필수 포함하고 필요 시 항목 추가
|
||||||
|
- 개요: 설계 원칙, 핵심 컴포넌트 정의
|
||||||
|
- 서비스 아키텍처
|
||||||
|
- 서비스별 책임
|
||||||
|
- 서비스 간 통신 전략
|
||||||
|
- 주요 사용자 플로우
|
||||||
|
- 데이터 흐름 및 캐싱 전략
|
||||||
|
- 확장성 및 성능 고려사항
|
||||||
|
- 보안 고려사항
|
||||||
|
- 논리아키텍처 다이어그램
|
||||||
|
- Mermaid 형식으로 작성하며 별도 파일로 작성: logical-architecture.mmd
|
||||||
|
- <통신전략>과 <의존성 표현 방법>을 준수
|
||||||
|
- **Mermaid 스크립트 파일 검사 실행**: 'Mermaid문법검사가이드' 준용
|
||||||
|
- 검토:
|
||||||
|
- <작성원칙> 준수 검토
|
||||||
|
- 스쿼드 팀원 리뷰: 누락 및 개선 사항 검토
|
||||||
|
- 수정 사항 선택 및 반영
|
||||||
|
<통신 전략>
|
||||||
|
- **동기 통신**: 즉시 응답이 필요한 단순 조회
|
||||||
|
- **캐시 우선**: 자주 사용되는 데이터는 캐시에서 직접 읽기
|
||||||
|
- **비동기 처리**: 외부 API 다중 호출 등 장시간 작업
|
||||||
|
<의존성 표현 방법>
|
||||||
|
- 실선 화살표(→): 동기적 의존성 (필수)
|
||||||
|
- 비동기 화살표(->>): 비동기 의존성 (fire-and-forget)
|
||||||
|
- 점선 화살표(-->): 선택적 의존성 또는 느슨한 결합
|
||||||
|
- 양방향 화살표(↔): 상호 의존성
|
||||||
|
- 의존성 레이블에 목적 명시 (예: "멤버 정보 조회")
|
||||||
|
- 플로우 라벨 형식: [요청서비스약어]액션 (예: [Trip]AI 일정 생성 요청)
|
||||||
|
|
||||||
|
[참고자료]
|
||||||
|
- 유저스토리
|
||||||
|
- UI/UX설계서
|
||||||
|
- 프로토타입
|
||||||
|
- 아키텍처패턴
|
||||||
|
|
||||||
|
[예시]
|
||||||
|
- 논리아키텍처 다이어그램: https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/samples/sample-논리아키텍처.mmd
|
||||||
|
|
||||||
|
[결과파일]
|
||||||
|
- design/backend/logical/logical-architecture.md
|
||||||
|
- design/backend/logical/logical-architecture.mmd
|
||||||
300
claude/mermaid-guide.md
Normal file
300
claude/mermaid-guide.md
Normal file
@ -0,0 +1,300 @@
|
|||||||
|
# Mermaid문법검사가이드
|
||||||
|
|
||||||
|
## 개요
|
||||||
|
|
||||||
|
Mermaid 다이어그램의 문법 오류를 사전에 검출하여 렌더링 실패를 방지하기 위한 가이드입니다. Docker 기반 Mermaid CLI를 활용하여 로컬에서 빠르게 문법을 검증할 수 있습니다.
|
||||||
|
|
||||||
|
## Mermaid CLI 서버 설치 및 검사
|
||||||
|
|
||||||
|
### Docker로 Mermaid CLI 컨테이너 실행
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Mermaid CLI 컨테이너가 실행 중인지 확인
|
||||||
|
docker ps | grep mermaid-cli
|
||||||
|
|
||||||
|
# ⚠️ 중요: 첫 실행 시 이미지 다운로드를 먼저 진행 (큰 이미지로 인한 타임아웃 방지)
|
||||||
|
docker pull minlag/mermaid-cli:latest
|
||||||
|
|
||||||
|
# Mermaid CLI 컨테이너가 없으면 설치 및 실행 (root 권한으로 실행, 포트 48080 사용)
|
||||||
|
docker run -d --rm --name mermaid-cli -u root -p 48080:8080 --entrypoint sh minlag/mermaid-cli:latest -c "while true;do sleep 3600; done"
|
||||||
|
|
||||||
|
# 컨테이너 상태 확인
|
||||||
|
docker logs mermaid-cli
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 💡 Docker 이미지 다운로드 관련 주의사항
|
||||||
|
|
||||||
|
**첫 실행 시 발생할 수 있는 문제:**
|
||||||
|
- `minlag/mermaid-cli:latest` 이미지가 큰 용량(약 700MB+)이므로 다운로드에 시간이 오래 걸림
|
||||||
|
- `docker run` 명령 실행 시 이미지가 없으면 자동 다운로드하지만 타임아웃 발생 가능
|
||||||
|
- **해결방법**: `docker pull` 명령으로 이미지를 먼저 다운로드한 후 컨테이너 실행
|
||||||
|
|
||||||
|
**권장 실행 순서:**
|
||||||
|
1. `docker pull minlag/mermaid-cli:latest` (이미지 다운로드)
|
||||||
|
2. `docker run` 명령으로 컨테이너 실행
|
||||||
|
3. 필수 설정 진행
|
||||||
|
|
||||||
|
#### ⚠️ 중요: 최초 컨테이너 생성 후 필수 설정
|
||||||
|
|
||||||
|
Mermaid CLI는 Puppeteer를 사용하여 다이어그램을 렌더링하므로 Chromium 브라우저가 필요합니다.
|
||||||
|
컨테이너를 처음 생성한 후 다음 명령을 실행하여 필요한 패키지를 설치해야 합니다:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Chromium 및 필요한 종속성 설치
|
||||||
|
docker exec mermaid-cli sh -c "apk add --no-cache chromium chromium-chromedriver nss freetype harfbuzz ca-certificates ttf-freefont"
|
||||||
|
|
||||||
|
# Puppeteer가 사용할 설정 파일 생성
|
||||||
|
docker exec mermaid-cli sh -c "echo '{\"executablePath\": \"/usr/bin/chromium-browser\", \"args\": [\"--no-sandbox\", \"--disable-setuid-sandbox\", \"--disable-dev-shm-usage\"]}' > /tmp/puppeteer-config.json"
|
||||||
|
```
|
||||||
|
|
||||||
|
이 설정은 컨테이너가 실행되는 동안 유지되므로 한 번만 실행하면 됩니다.
|
||||||
|
|
||||||
|
문법검사 후 Container를 중지하지 않고 계속 사용함
|
||||||
|
|
||||||
|
## 문법 검사 방법
|
||||||
|
현재 OS에 맞게 수행.
|
||||||
|
|
||||||
|
### Linux/macOS 버전
|
||||||
|
**스크립트 파일(tools/check-mermaid.sh)을 이용하여 수행**
|
||||||
|
|
||||||
|
1. tools/check-mermaid.sh 파일 존재 여부 확인
|
||||||
|
2. 스크립트 파일이 없으면 "Mermaid문법검사기(Linux/Mac)"를 tools/check-mermaid.sh 파일로 다운로드하여 스크립트 파일을 만듦
|
||||||
|
3. 스크립트 파일이 있으면 그 스크립트 파일을 이용하여 검사
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. 스크립트 실행 권한 부여 (최초 1회)
|
||||||
|
chmod +x tools/check-mermaid.sh
|
||||||
|
|
||||||
|
# 2. 문법 검사 실행
|
||||||
|
./tools/check-mermaid.sh {검사할 파일}
|
||||||
|
|
||||||
|
# 예시
|
||||||
|
./tools/check-mermaid.sh design/backend/physical/physical-architecture.mmd
|
||||||
|
```
|
||||||
|
|
||||||
|
### Windows PowerShell 버전
|
||||||
|
**스크립트 파일(tools/check-mermaid.ps1)을 이용하여 수행**
|
||||||
|
|
||||||
|
1. tools/check-mermaid.ps1 파일 존재 여부 확인
|
||||||
|
2. 스크립트 파일이 없으면 "Mermaid문법검사기(Window)"를 tools/check-mermaid.ps1 파일로 다운로드하여 스크립트 파일을 만듦
|
||||||
|
3. 스크립트 파일이 있으면 그 스크립트 파일을 이용하여 검사
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
# 문법 검사 실행
|
||||||
|
.\tools\check-mermaid.ps1 {검사할 파일}
|
||||||
|
|
||||||
|
# 예시
|
||||||
|
.\tools\check-mermaid.ps1 design\backend\physical\physical-architecture.mmd
|
||||||
|
```
|
||||||
|
|
||||||
|
### 수동 검사 방법 (스크립트 없이)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. 고유 파일명 생성 (충돌 방지)
|
||||||
|
TEMP_FILE="/tmp/mermaid_$(date +%s)_$$.mmd"
|
||||||
|
|
||||||
|
# 2. 파일 복사
|
||||||
|
docker cp {검사할 파일} mermaid-cli:${TEMP_FILE}
|
||||||
|
|
||||||
|
# 3. 문법 검사 (Puppeteer 설정 파일 사용)
|
||||||
|
docker exec mermaid-cli sh -c "cd /home/mermaidcli && node_modules/.bin/mmdc -i ${TEMP_FILE} -o /tmp/output.svg -p /tmp/puppeteer-config.json -q"
|
||||||
|
|
||||||
|
# 4. 임시 파일 삭제
|
||||||
|
docker exec mermaid-cli rm -f ${TEMP_FILE} /tmp/output.svg
|
||||||
|
```
|
||||||
|
|
||||||
|
**주의**: Puppeteer 설정 파일(`/tmp/puppeteer-config.json`)이 있어야 합니다. 없다면 위의 "최초 컨테이너 생성 후 필수 설정"을 먼저 실행하세요.
|
||||||
|
|
||||||
|
### 검사 결과 해석
|
||||||
|
|
||||||
|
| 출력 | 의미 | 대응 방법 |
|
||||||
|
|------|------|-----------|
|
||||||
|
| "Success: Mermaid syntax is valid!" | 문법 오류 없음 ✅ | 정상, 렌더링 가능 |
|
||||||
|
| "Parse error on line X" | X번째 줄 구문 오류 ❌ | 해당 라인 문법 확인 |
|
||||||
|
| "Expecting 'XXX'" | 예상 토큰 오류 ❌ | 누락된 문법 요소 추가 |
|
||||||
|
| "Syntax error" | 일반 문법 오류 ❌ | 전체 구조 재검토 |
|
||||||
|
|
||||||
|
## Mermaid 다이어그램 타입별 주의사항
|
||||||
|
|
||||||
|
### 1. Graph/Flowchart
|
||||||
|
```mermaid
|
||||||
|
graph TB
|
||||||
|
%% 올바른 사용법 ✅
|
||||||
|
A[Node A] --> B[Node B]
|
||||||
|
C[Node C] -.-> D[Node D]
|
||||||
|
E[Node E] ==> F[Node F]
|
||||||
|
|
||||||
|
%% 주의사항
|
||||||
|
%% - 노드 ID에 공백 불가 (대신 [Label] 사용)
|
||||||
|
%% - subgraph와 end 개수 일치 필요
|
||||||
|
%% - 따옴표 안에서 특수문자 주의
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Sequence Diagram
|
||||||
|
```mermaid
|
||||||
|
sequenceDiagram
|
||||||
|
%% 올바른 사용법 ✅
|
||||||
|
participant A as Service A
|
||||||
|
participant B as Service B
|
||||||
|
|
||||||
|
A->>B: Request
|
||||||
|
B-->>A: Response
|
||||||
|
A->>+B: Call with activation
|
||||||
|
B-->>-A: Return with deactivation
|
||||||
|
|
||||||
|
%% 주의사항
|
||||||
|
%% - participant 선언 권장
|
||||||
|
%% - 활성화(+)/비활성화(-) 쌍 맞추기
|
||||||
|
%% - Note 블록 종료 확인
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Class Diagram
|
||||||
|
```mermaid
|
||||||
|
classDiagram
|
||||||
|
%% 올바른 사용법 ✅
|
||||||
|
class Animal {
|
||||||
|
+String name
|
||||||
|
+int age
|
||||||
|
+makeSound() void
|
||||||
|
}
|
||||||
|
|
||||||
|
class Dog {
|
||||||
|
+String breed
|
||||||
|
+bark() void
|
||||||
|
}
|
||||||
|
|
||||||
|
Animal <|-- Dog : inherits
|
||||||
|
|
||||||
|
%% 주의사항
|
||||||
|
%% - 메서드 괄호 필수
|
||||||
|
%% - 관계 표현 정확히
|
||||||
|
%% - 접근 제한자 기호 확인
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. State Diagram
|
||||||
|
```mermaid
|
||||||
|
stateDiagram-v2
|
||||||
|
%% 올바른 사용법 ✅
|
||||||
|
[*] --> Idle
|
||||||
|
Idle --> Processing : start
|
||||||
|
Processing --> Completed : finish
|
||||||
|
Processing --> Error : error
|
||||||
|
Error --> Idle : reset
|
||||||
|
Completed --> [*]
|
||||||
|
|
||||||
|
%% 주의사항
|
||||||
|
%% - [*]는 시작/종료 상태
|
||||||
|
%% - 상태 이름에 공백 불가
|
||||||
|
%% - 전이 레이블 콜론(:) 사용
|
||||||
|
```
|
||||||
|
|
||||||
|
## 일반적인 오류와 해결 방법
|
||||||
|
|
||||||
|
### 1. 괄호 불균형
|
||||||
|
```mermaid
|
||||||
|
%% 잘못된 예 ❌
|
||||||
|
graph TB
|
||||||
|
A[Node (with parenthesis)] %% 괄호 안에 괄호
|
||||||
|
|
||||||
|
%% 올바른 예 ✅
|
||||||
|
graph TB
|
||||||
|
A[Node with parenthesis]
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 특수 문자 이스케이프
|
||||||
|
```mermaid
|
||||||
|
%% 잘못된 예 ❌
|
||||||
|
graph TB
|
||||||
|
A[Security & Management] %% & 문자 직접 사용
|
||||||
|
|
||||||
|
%% 올바른 예 ✅
|
||||||
|
graph TB
|
||||||
|
A[Security & Management] %% HTML 엔티티 사용
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. subgraph/end 불일치
|
||||||
|
```mermaid
|
||||||
|
%% 잘못된 예 ❌
|
||||||
|
graph TB
|
||||||
|
subgraph One
|
||||||
|
A --> B
|
||||||
|
subgraph Two
|
||||||
|
C --> D
|
||||||
|
end %% Two만 닫힘, One은 안 닫힘
|
||||||
|
|
||||||
|
%% 올바른 예 ✅
|
||||||
|
graph TB
|
||||||
|
subgraph One
|
||||||
|
A --> B
|
||||||
|
subgraph Two
|
||||||
|
C --> D
|
||||||
|
end
|
||||||
|
end %% 모든 subgraph 닫기
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. 노드 참조 오류
|
||||||
|
```mermaid
|
||||||
|
%% 잘못된 예 ❌
|
||||||
|
graph TB
|
||||||
|
A --> UnknownNode %% 정의되지 않은 노드
|
||||||
|
|
||||||
|
%% 올바른 예 ✅
|
||||||
|
graph TB
|
||||||
|
A[Node A] --> B[Node B] %% 모든 노드 정의
|
||||||
|
```
|
||||||
|
|
||||||
|
## 컨테이너 관리
|
||||||
|
|
||||||
|
### 컨테이너 중지 및 삭제
|
||||||
|
```bash
|
||||||
|
# 컨테이너 중지
|
||||||
|
docker stop mermaid-cli
|
||||||
|
|
||||||
|
# 컨테이너 삭제
|
||||||
|
docker rm mermaid-cli
|
||||||
|
|
||||||
|
# 한 번에 중지 및 삭제
|
||||||
|
docker stop mermaid-cli && docker rm mermaid-cli
|
||||||
|
```
|
||||||
|
|
||||||
|
### 컨테이너 재시작
|
||||||
|
```bash
|
||||||
|
# 컨테이너 재시작
|
||||||
|
docker restart mermaid-cli
|
||||||
|
```
|
||||||
|
|
||||||
|
## 성능 최적화 팁
|
||||||
|
|
||||||
|
1. **컨테이너 유지**: 검사 후 컨테이너를 중지하지 않고 유지하여 다음 검사 시 빠르게 실행
|
||||||
|
2. **배치 검사**: 여러 파일을 연속으로 검사할 때 컨테이너 재시작 없이 진행
|
||||||
|
3. **로컬 파일 사용**: 네트워크 경로보다 로컬 파일 경로 사용 권장
|
||||||
|
|
||||||
|
## 문제 해결
|
||||||
|
|
||||||
|
### Docker 관련 오류
|
||||||
|
```bash
|
||||||
|
# Docker 데몬 실행 확인
|
||||||
|
docker ps
|
||||||
|
|
||||||
|
# Docker Desktop 시작 (Windows/Mac)
|
||||||
|
# Docker 서비스 시작 (Linux)
|
||||||
|
sudo systemctl start docker
|
||||||
|
```
|
||||||
|
|
||||||
|
### 권한 오류
|
||||||
|
```bash
|
||||||
|
# Linux/Mac에서 스크립트 실행 권한
|
||||||
|
chmod +x tools/check-mermaid.sh
|
||||||
|
|
||||||
|
# Docker 권한 (Linux)
|
||||||
|
sudo usermod -aG docker $USER
|
||||||
|
```
|
||||||
|
|
||||||
|
### 컨테이너 이미지 오류
|
||||||
|
```bash
|
||||||
|
# 이미지 재다운로드
|
||||||
|
docker pull minlag/mermaid-cli:latest
|
||||||
|
|
||||||
|
# 기존 컨테이너 삭제 후 재생성
|
||||||
|
docker stop mermaid-cli && docker rm mermaid-cli
|
||||||
|
```
|
||||||
83
claude/sample-logical-architecture.mmd
Normal file
83
claude/sample-logical-architecture.mmd
Normal file
@ -0,0 +1,83 @@
|
|||||||
|
graph TB
|
||||||
|
%% TripGen 논리 아키텍처 - Context Map
|
||||||
|
|
||||||
|
%% Client Layer
|
||||||
|
subgraph "Client Layer"
|
||||||
|
Mobile["모바일 클라이언트"]
|
||||||
|
end
|
||||||
|
|
||||||
|
%% Gateway Layer
|
||||||
|
subgraph "Gateway Layer"
|
||||||
|
Gateway["API Gateway<br/>• 인증/인가<br/>• 라우팅<br/>• 로드밸런싱"]
|
||||||
|
end
|
||||||
|
|
||||||
|
%% Service Layer
|
||||||
|
subgraph "Service Layer"
|
||||||
|
UserSvc["User Service<br/>• 사용자 인증<br/>• 프로필 관리<br/>• 세션 관리"]
|
||||||
|
TripSvc["Trip Service<br/>• 여행 관리<br/>• 멤버 설정<br/>• 일정 조회"]
|
||||||
|
AISvc["AI Service<br/>• 일정 생성<br/>• 맞춤 추천<br/>• 날씨 반영"]
|
||||||
|
LocationSvc["Location Service<br/>• 장소 검색<br/>• 상세 정보<br/>• 리뷰 통합"]
|
||||||
|
end
|
||||||
|
|
||||||
|
%% Data Layer
|
||||||
|
subgraph "Data Layer"
|
||||||
|
Cache["Redis Cache<br/>• 세션 정보<br/>• 장소 데이터<br/>• AI 결과"]
|
||||||
|
Queue["Message Queue<br/>• AI 작업 큐<br/>• Priority Queue<br/>• Location 비동기"]
|
||||||
|
end
|
||||||
|
|
||||||
|
%% External APIs
|
||||||
|
subgraph "External APIs"
|
||||||
|
Claude["Claude API"]
|
||||||
|
Kakao["카카오맵 API"]
|
||||||
|
Google["구글맵 API"]
|
||||||
|
Weather["날씨 API"]
|
||||||
|
end
|
||||||
|
|
||||||
|
%% Client to Gateway (단일 연결)
|
||||||
|
Mobile -->|HTTPS| Gateway
|
||||||
|
|
||||||
|
%% Gateway to Services (동기)
|
||||||
|
Gateway -->|인증/프로필| UserSvc
|
||||||
|
Gateway -->|여행 관리| TripSvc
|
||||||
|
Gateway -->|장소 검색| LocationSvc
|
||||||
|
|
||||||
|
%% Service Dependencies
|
||||||
|
TripSvc -.->|"AI 일정 생성 요청<br/>(비동기)"| Queue
|
||||||
|
Queue -.->|작업 처리| AISvc
|
||||||
|
|
||||||
|
%% AI Service Dependencies
|
||||||
|
AISvc -.->|"장소 정보 조회<br/>(Cache-Aside)"| Cache
|
||||||
|
AISvc -.->|"Location 요청<br/>(Async Fallback)"| Queue
|
||||||
|
Queue -.->|백그라운드 처리| LocationSvc
|
||||||
|
|
||||||
|
%% Cache Dependencies
|
||||||
|
UserSvc -.->|세션 관리| Cache
|
||||||
|
TripSvc -.->|여행 정보| Cache
|
||||||
|
LocationSvc -.->|장소 캐싱| Cache
|
||||||
|
|
||||||
|
%% External API Dependencies
|
||||||
|
AISvc -->|일정 생성| Claude
|
||||||
|
LocationSvc -->|장소 검색| Kakao
|
||||||
|
LocationSvc -->|상세/리뷰| Google
|
||||||
|
LocationSvc -->|날씨 조회| Weather
|
||||||
|
|
||||||
|
%% Styling
|
||||||
|
classDef client fill:#BFDBFE,stroke:#3B82F6,stroke-width:2px
|
||||||
|
classDef gateway fill:#2E86AB,stroke:#1E3A8A,stroke-width:2px,color:#fff
|
||||||
|
classDef user fill:#4ECDC4,stroke:#14B8A6,stroke-width:2px
|
||||||
|
classDef trip fill:#F18F01,stroke:#F97316,stroke-width:2px
|
||||||
|
classDef ai fill:#10B981,stroke:#059669,stroke-width:2px
|
||||||
|
classDef location fill:#8B5CF6,stroke:#7C3AED,stroke-width:2px,color:#fff
|
||||||
|
classDef cache fill:#F59E0B,stroke:#F97316,stroke-width:2px
|
||||||
|
classDef queue fill:#EC4899,stroke:#DB2777,stroke-width:2px
|
||||||
|
classDef external fill:#E5E7EB,stroke:#9CA3AF,stroke-width:2px
|
||||||
|
|
||||||
|
class Mobile client
|
||||||
|
class Gateway gateway
|
||||||
|
class UserSvc user
|
||||||
|
class TripSvc trip
|
||||||
|
class AISvc ai
|
||||||
|
class LocationSvc location
|
||||||
|
class Cache cache
|
||||||
|
class Queue queue
|
||||||
|
class Claude,Kakao,Google,Weather external
|
||||||
626
design/backend/logical/logical-architecture.md
Normal file
626
design/backend/logical/logical-architecture.md
Normal file
@ -0,0 +1,626 @@
|
|||||||
|
# KT AI 기반 소상공인 이벤트 자동 생성 서비스 - 논리 아키텍처
|
||||||
|
|
||||||
|
## 문서 정보
|
||||||
|
- **작성일**: 2025-10-21
|
||||||
|
- **버전**: 1.0
|
||||||
|
- **작성자**: System Architect
|
||||||
|
- **관련 문서**:
|
||||||
|
- [유저스토리](../../userstory.md)
|
||||||
|
- [아키텍처 패턴](../../pattern/architecture-pattern.md)
|
||||||
|
- [UI/UX 설계서](../../uiux/uiux.md)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 목차
|
||||||
|
1. [개요](#1-개요)
|
||||||
|
2. [서비스 아키텍처](#2-서비스-아키텍처)
|
||||||
|
3. [주요 사용자 플로우](#3-주요-사용자-플로우)
|
||||||
|
4. [데이터 흐름 및 캐싱 전략](#4-데이터-흐름-및-캐싱-전략)
|
||||||
|
5. [확장성 및 성능 고려사항](#5-확장성-및-성능-고려사항)
|
||||||
|
6. [보안 고려사항](#6-보안-고려사항)
|
||||||
|
7. [논리 아키텍처 다이어그램](#7-논리-아키텍처-다이어그램)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. 개요
|
||||||
|
|
||||||
|
### 1.1 설계 원칙
|
||||||
|
|
||||||
|
본 논리 아키텍처는 다음 원칙을 기반으로 설계되었습니다:
|
||||||
|
|
||||||
|
#### 유저스토리 기반 설계
|
||||||
|
- 20개 유저스토리와 정확히 매칭
|
||||||
|
- 불필요한 추가 기능 배제
|
||||||
|
- 비즈니스 요구사항 우선 반영
|
||||||
|
|
||||||
|
#### 마이크로서비스 아키텍처
|
||||||
|
- **서비스 독립성**: 각 서비스는 독립적으로 배포 및 확장 가능
|
||||||
|
- **캐시 우선 전략**: Redis를 통한 서비스 간 데이터 공유 최소화
|
||||||
|
- **선택적 비동기**: AI 및 이미지 생성 등 장시간 작업만 비동기 처리
|
||||||
|
- **느슨한 결합**: 서비스 간 직접 의존성 최소화
|
||||||
|
|
||||||
|
#### 클라우드 디자인 패턴 적용
|
||||||
|
- **Cache-Aside**: AI 응답, 이미지 생성 결과 캐싱 (응답 시간 90% 개선)
|
||||||
|
- **API Gateway**: 중앙집중식 인증/라우팅/Rate Limiting
|
||||||
|
- **Asynchronous Request-Reply**: AI 추천, 이미지 생성 비동기 처리
|
||||||
|
- **Circuit Breaker**: 7개 외부 API 장애 격리 (가용성 99% 목표)
|
||||||
|
|
||||||
|
### 1.2 핵심 컴포넌트 정의
|
||||||
|
|
||||||
|
#### Client Layer
|
||||||
|
- **Web/Mobile Client**: 반응형 React 애플리케이션
|
||||||
|
- Mobile First 설계 (60% 모바일 사용자)
|
||||||
|
- Progressive Web App (PWA) 지원
|
||||||
|
|
||||||
|
#### Gateway Layer
|
||||||
|
- **API Gateway**: Kong 또는 AWS API Gateway
|
||||||
|
- JWT 토큰 기반 인증/인가
|
||||||
|
- URL 기반 서비스 라우팅
|
||||||
|
- Rate Limiting (사용자당 100 req/min)
|
||||||
|
- 중앙집중식 로깅 및 모니터링
|
||||||
|
|
||||||
|
#### Service Layer (7개 마이크로서비스)
|
||||||
|
1. **User Service**: 사용자 인증 및 매장정보 관리
|
||||||
|
2. **Event Service**: 이벤트 CRUD 및 상태 관리
|
||||||
|
3. **AI Service**: 트렌드 분석 및 이벤트 추천
|
||||||
|
4. **Content Service**: SNS 이미지 자동 생성
|
||||||
|
5. **Distribution Service**: 다중 채널 배포 관리
|
||||||
|
6. **Participation Service**: 이벤트 참여 및 당첨자 관리
|
||||||
|
7. **Analytics Service**: 실시간 성과 대시보드
|
||||||
|
|
||||||
|
#### Data Layer
|
||||||
|
- **Redis Cache**:
|
||||||
|
- 세션 정보 (User)
|
||||||
|
- AI 추천 결과 (TTL 24시간)
|
||||||
|
- 이미지 생성 결과 (TTL 7일)
|
||||||
|
- 사업자번호 검증 결과 (TTL 7일)
|
||||||
|
- 대시보드 데이터 (TTL 5분)
|
||||||
|
- **Message Queue** (RabbitMQ/Kafka):
|
||||||
|
- AI 작업 큐 (비동기 처리)
|
||||||
|
- 이미지 생성 큐
|
||||||
|
- 배포 작업 큐
|
||||||
|
- **Database** (PostgreSQL):
|
||||||
|
- 서비스별 독립 데이터베이스
|
||||||
|
- User DB, Event DB, Participation DB, Analytics DB
|
||||||
|
|
||||||
|
#### External APIs
|
||||||
|
- **국세청 사업자등록정보 진위확인 API**: 사업자번호 검증
|
||||||
|
- **Claude API / GPT-4 API**: AI 트렌드 분석 및 이벤트 추천
|
||||||
|
- **Stable Diffusion / DALL-E API**: SNS 이미지 생성
|
||||||
|
- **우리동네TV API**: 영상 배포
|
||||||
|
- **링고비즈 API**: 연결음 업데이트
|
||||||
|
- **지니TV 광고 API**: TV 광고 배포
|
||||||
|
- **SNS APIs** (Instagram, Naver, Kakao): SNS 자동 포스팅
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 서비스 아키텍처
|
||||||
|
|
||||||
|
### 2.1 서비스별 책임
|
||||||
|
|
||||||
|
#### User Service
|
||||||
|
**핵심 책임**:
|
||||||
|
- 회원가입/로그인 (JWT 토큰 발급)
|
||||||
|
- 프로필 관리 (매장 정보 포함)
|
||||||
|
- 사업자번호 검증 (국세청 API 연동)
|
||||||
|
- 로그아웃 및 세션 관리
|
||||||
|
|
||||||
|
**관련 유저스토리**: UFR-USER-010, 020, 030, 040
|
||||||
|
|
||||||
|
**주요 기능**:
|
||||||
|
- JWT 기반 인증/인가
|
||||||
|
- Redis를 통한 세션 관리
|
||||||
|
- 사업자번호 검증 결과 캐싱 (TTL 7일)
|
||||||
|
- 매장 정보 CRUD
|
||||||
|
|
||||||
|
**데이터 저장**:
|
||||||
|
- User DB: users, stores 테이블
|
||||||
|
- Redis: 세션 정보, 사업자번호 검증 결과
|
||||||
|
|
||||||
|
#### Event Service
|
||||||
|
**핵심 책임**:
|
||||||
|
- 이벤트 CRUD 및 상태 관리
|
||||||
|
- 이벤트 생성 플로우 오케스트레이션
|
||||||
|
- 이벤트 목록 조회 및 필터링
|
||||||
|
- 이벤트 상세 정보 조회
|
||||||
|
|
||||||
|
**관련 유저스토리**: UFR-EVENT-010, 020, 030, 040, 050, 060, 070
|
||||||
|
|
||||||
|
**주요 기능**:
|
||||||
|
- 이벤트 생성 플로우 관리 (목적 선택 → AI 추천 → 콘텐츠 생성 → 배포)
|
||||||
|
- 이벤트 상태 관리 (진행중/예정/종료)
|
||||||
|
- 대시보드용 이벤트 목록 제공
|
||||||
|
- 이벤트 검색 및 필터링
|
||||||
|
|
||||||
|
**데이터 저장**:
|
||||||
|
- Event DB: events, event_objectives, event_prizes 테이블
|
||||||
|
|
||||||
|
#### AI Service
|
||||||
|
**핵심 책임**:
|
||||||
|
- 업종/지역/시즌 트렌드 분석
|
||||||
|
- 3가지 이벤트 기획안 자동 생성
|
||||||
|
- 예상 성과 계산 (참여자 수, 비용, ROI)
|
||||||
|
|
||||||
|
**관련 유저스토리**: UFR-AI-010
|
||||||
|
|
||||||
|
**주요 기능**:
|
||||||
|
- Claude/GPT-4 API 연동
|
||||||
|
- 비동기 처리 (Job 기반)
|
||||||
|
- 트렌드 분석 결과 캐싱 (TTL 24시간)
|
||||||
|
- 3가지 옵션 차별화 (저비용/중비용/고비용)
|
||||||
|
|
||||||
|
**처리 시간**:
|
||||||
|
- 캐시 HIT: 0.1초
|
||||||
|
- 캐시 MISS: 10초 이내 (비동기 Job 처리)
|
||||||
|
|
||||||
|
**데이터 저장**:
|
||||||
|
- Redis: AI 추천 결과 (TTL 24시간)
|
||||||
|
- Redis: Job 상태 정보 (TTL 1시간)
|
||||||
|
|
||||||
|
#### Content Service
|
||||||
|
**핵심 책임**:
|
||||||
|
- 3가지 스타일 SNS 이미지 자동 생성
|
||||||
|
- 플랫폼별 이미지 최적화 (Instagram, Naver, Kakao)
|
||||||
|
- 이미지 편집 기능 제공
|
||||||
|
|
||||||
|
**관련 유저스토리**: UFR-CONT-010, 020
|
||||||
|
|
||||||
|
**주요 기능**:
|
||||||
|
- Stable Diffusion/DALL-E API 연동
|
||||||
|
- 비동기 이미지 생성 (Job 기반)
|
||||||
|
- 3가지 스타일 카드 생성 (심플/화려한/트렌디)
|
||||||
|
- 생성 이미지 캐싱 및 CDN 업로드
|
||||||
|
|
||||||
|
**처리 시간**:
|
||||||
|
- 캐시 HIT: 0.1초
|
||||||
|
- 캐시 MISS: 5초 이내 (비동기 Job 처리)
|
||||||
|
|
||||||
|
**데이터 저장**:
|
||||||
|
- Redis: 이미지 생성 결과 (CDN URL, TTL 7일)
|
||||||
|
- CDN: 생성된 이미지 파일
|
||||||
|
|
||||||
|
#### Distribution Service
|
||||||
|
**핵심 책임**:
|
||||||
|
- 다중 채널 동시 배포 (우리동네TV, 링고비즈, 지니TV, SNS)
|
||||||
|
- 배포 상태 모니터링
|
||||||
|
- 채널별 독립적 처리 및 실패 재시도
|
||||||
|
|
||||||
|
**관련 유저스토리**: UFR-DIST-010, 020
|
||||||
|
|
||||||
|
**주요 기능**:
|
||||||
|
- 7개 외부 API 병렬 연동 (Circuit Breaker 적용)
|
||||||
|
- 채널별 독립 처리 (하나 실패해도 다른 채널 계속)
|
||||||
|
- 자동 재시도 (최대 3회)
|
||||||
|
- Fallback 전략 (배포 스킵 + 알림)
|
||||||
|
|
||||||
|
**처리 시간**: 1분 이내 (모든 채널 배포 완료)
|
||||||
|
|
||||||
|
**데이터 저장**:
|
||||||
|
- Event DB: distribution_logs 테이블
|
||||||
|
|
||||||
|
#### Participation Service
|
||||||
|
**핵심 책임**:
|
||||||
|
- 고객 이벤트 참여 접수
|
||||||
|
- 참여자 목록 관리
|
||||||
|
- 당첨자 자동 추첨
|
||||||
|
|
||||||
|
**관련 유저스토리**: UFR-PART-010, 020, 030
|
||||||
|
|
||||||
|
**주요 기능**:
|
||||||
|
- 중복 참여 체크 (전화번호 기반)
|
||||||
|
- 참여자 목록 조회 및 필터링
|
||||||
|
- 난수 기반 무작위 추첨
|
||||||
|
- 매장 방문 고객 가산점 옵션
|
||||||
|
|
||||||
|
**데이터 저장**:
|
||||||
|
- Participation DB: participants, winners 테이블
|
||||||
|
|
||||||
|
#### Analytics Service
|
||||||
|
**핵심 책임**:
|
||||||
|
- 실시간 성과 대시보드
|
||||||
|
- 채널별 성과 분석
|
||||||
|
- 투자 대비 수익률 계산
|
||||||
|
|
||||||
|
**관련 유저스토리**: UFR-ANAL-010
|
||||||
|
|
||||||
|
**주요 기능**:
|
||||||
|
- 다중 데이터 소스 통합 (7개 외부 API + 내부 서비스)
|
||||||
|
- 5분 간격 데이터 폴링 및 캐싱
|
||||||
|
- 실시간 차트 및 그래프 생성
|
||||||
|
- POS 시스템 연동 (선택)
|
||||||
|
|
||||||
|
**처리 시간**: 0.5초 (캐시 기반)
|
||||||
|
|
||||||
|
**데이터 저장**:
|
||||||
|
- Analytics DB: event_stats, channel_stats 테이블
|
||||||
|
- Redis: 대시보드 데이터 (TTL 5분)
|
||||||
|
|
||||||
|
### 2.2 서비스 간 통신 전략
|
||||||
|
|
||||||
|
#### 동기 통신 (Synchronous)
|
||||||
|
**사용 시나리오**: 즉시 응답이 필요한 단순 조회
|
||||||
|
|
||||||
|
- **User → Redis**: 세션 정보 조회
|
||||||
|
- **Event → User**: 사용자 정보 검증 (Token 검증은 API Gateway에서 처리)
|
||||||
|
- **Participation → Event**: 이벤트 정보 조회
|
||||||
|
- **Analytics → Event/Participation**: 통계 데이터 조회
|
||||||
|
|
||||||
|
**통신 방식**: REST API (HTTP/JSON)
|
||||||
|
|
||||||
|
#### 캐시 우선 전략 (Cache-Aside)
|
||||||
|
**사용 시나리오**: 자주 사용되는 데이터, 외부 API 결과
|
||||||
|
|
||||||
|
- **AI Service**: 트렌드 분석 및 이벤트 추천 결과
|
||||||
|
- 캐시 키: `ai:recommendation:{업종}:{지역}:{목적}`
|
||||||
|
- TTL: 24시간
|
||||||
|
- 히트율 목표: 80%
|
||||||
|
|
||||||
|
- **Content Service**: 생성된 이미지 URL
|
||||||
|
- 캐시 키: `content:image:{이벤트ID}:{스타일}`
|
||||||
|
- TTL: 7일
|
||||||
|
- 히트율 목표: 80%
|
||||||
|
|
||||||
|
- **User Service**: 사업자번호 검증 결과
|
||||||
|
- 캐시 키: `user:business:{사업자번호}`
|
||||||
|
- TTL: 7일
|
||||||
|
- 히트율 목표: 90%
|
||||||
|
|
||||||
|
- **Analytics Service**: 대시보드 데이터
|
||||||
|
- 캐시 키: `analytics:dashboard:{이벤트ID}`
|
||||||
|
- TTL: 5분
|
||||||
|
- 히트율 목표: 95%
|
||||||
|
|
||||||
|
**효과**:
|
||||||
|
- AI 응답 시간: 10초 → 0.1초 (99% 개선, 캐시 히트 시)
|
||||||
|
- 이미지 생성 시간: 5초 → 0.1초 (98% 개선, 캐시 히트 시)
|
||||||
|
- 대시보드 로딩 시간: 3초 → 0.5초 (83% 개선)
|
||||||
|
|
||||||
|
#### 비동기 처리 (Asynchronous Request-Reply)
|
||||||
|
**사용 시나리오**: 장시간 작업 (10초 이상 소요)
|
||||||
|
|
||||||
|
- **AI Service**: 트렌드 분석 + 이벤트 추천 (10초)
|
||||||
|
1. 클라이언트 → Event Service: POST /api/ai/recommendations
|
||||||
|
2. Event Service → AI Service: Job 생성
|
||||||
|
3. AI Service → 클라이언트: Job ID 즉시 반환 (0.1초)
|
||||||
|
4. 백그라운드: AI Service → Claude API (10초)
|
||||||
|
5. 폴링: 클라이언트 → Event Service: GET /api/jobs/{id} (5초 간격)
|
||||||
|
6. 완료: AI Service → 클라이언트: 최종 결과 반환
|
||||||
|
|
||||||
|
- **Content Service**: 이미지 생성 (5초)
|
||||||
|
1. 클라이언트 → Event Service: POST /api/content/images
|
||||||
|
2. Event Service → Content Service: Job 생성
|
||||||
|
3. Content Service → 클라이언트: Job ID 즉시 반환 (0.1초)
|
||||||
|
4. 백그라운드: Content Service → Stable Diffusion API (5초)
|
||||||
|
5. 폴링: 클라이언트 → Event Service: GET /api/jobs/{id} (3초 간격)
|
||||||
|
6. 완료: Content Service → 클라이언트: 최종 결과 반환
|
||||||
|
|
||||||
|
**Message Queue 사용**:
|
||||||
|
- RabbitMQ 또는 Kafka
|
||||||
|
- Priority Queue: AI 작업 우선순위 관리
|
||||||
|
- Dead Letter Queue: 실패 작업 처리
|
||||||
|
|
||||||
|
#### Circuit Breaker 패턴
|
||||||
|
**사용 시나리오**: 외부 API 장애 격리
|
||||||
|
|
||||||
|
- **적용 대상**: 7개 외부 API
|
||||||
|
- 국세청 API
|
||||||
|
- Claude/GPT-4 API
|
||||||
|
- Stable Diffusion/DALL-E API
|
||||||
|
- 우리동네TV API
|
||||||
|
- 링고비즈 API
|
||||||
|
- 지니TV API
|
||||||
|
- SNS APIs (Instagram, Naver, Kakao)
|
||||||
|
|
||||||
|
- **동작 방식**:
|
||||||
|
- Closed (정상): 실패율 5% 미만
|
||||||
|
- Open (차단): 실패율 5% 초과 시 Circuit Open → 모든 요청 Fallback
|
||||||
|
- Half-Open (테스트): 30초 후 1개 요청 시도 → 성공 시 Closed로 전환
|
||||||
|
|
||||||
|
- **Fallback 전략**:
|
||||||
|
- AI Service: 캐시된 이전 추천 결과 + 안내 메시지
|
||||||
|
- Distribution Service: 해당 채널 배포 스킵 + 알림
|
||||||
|
- User Service: 사업자번호 검증 스킵 (수동 확인으로 대체)
|
||||||
|
|
||||||
|
**효과**: 가용성 95% → 99% 개선
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 주요 사용자 플로우
|
||||||
|
|
||||||
|
### 3.1 이벤트 생성 플로우 (핵심 플로우)
|
||||||
|
|
||||||
|
```
|
||||||
|
1. [User] 07-이벤트목적선택
|
||||||
|
- 클라이언트 → API Gateway → Event Service
|
||||||
|
- Event: 목적 저장 (신규 고객 유치/재방문 유도/매출 증대/인지도 향상)
|
||||||
|
|
||||||
|
2. [AI] 08-AI이벤트추천
|
||||||
|
- 클라이언트 → API Gateway → Event Service → AI Service
|
||||||
|
- AI: Job ID 즉시 반환 (0.1초)
|
||||||
|
- 백그라운드: AI Service → Claude API (10초)
|
||||||
|
* 캐시 확인 (Cache-Aside)
|
||||||
|
* 캐시 MISS: Claude API 호출 → 결과 캐싱 (TTL 24시간)
|
||||||
|
- 폴링: 클라이언트 → Event Service (5초 간격)
|
||||||
|
- 완료: AI 추천 결과 (3가지 옵션) 반환
|
||||||
|
|
||||||
|
3. [Content] 09-SNS이미지생성
|
||||||
|
- 클라이언트 → API Gateway → Event Service → Content Service
|
||||||
|
- Content: Job ID 즉시 반환 (0.1초)
|
||||||
|
- 백그라운드: Content Service → Stable Diffusion API (5초)
|
||||||
|
* 캐시 확인 (Cache-Aside)
|
||||||
|
* 캐시 MISS: Stable Diffusion API 호출 → 이미지 CDN 업로드 → 결과 캐싱 (TTL 7일)
|
||||||
|
- 폴링: 클라이언트 → Event Service (3초 간격)
|
||||||
|
- 완료: 3가지 스타일 이미지 URL 반환
|
||||||
|
|
||||||
|
4. [Content] 10-콘텐츠편집
|
||||||
|
- 클라이언트 → API Gateway → Content Service
|
||||||
|
- Content: 텍스트/색상 편집 적용 → 새 이미지 생성
|
||||||
|
|
||||||
|
5. [Distribution] 11-배포채널선택
|
||||||
|
- 클라이언트 → API Gateway → Event Service
|
||||||
|
- Event: 배포 채널 정보 저장
|
||||||
|
|
||||||
|
6. [Event] 12-최종승인
|
||||||
|
- 클라이언트 → API Gateway → Event Service
|
||||||
|
- Event: 이벤트 생성 완료 → Distribution Service 호출
|
||||||
|
- Distribution: 다중 채널 배포 시작 (Circuit Breaker 적용)
|
||||||
|
* 우리동네TV API (영상 업로드)
|
||||||
|
* 링고비즈 API (연결음 업데이트)
|
||||||
|
* 지니TV API (광고 등록)
|
||||||
|
* SNS APIs (Instagram, Naver, Kakao 자동 포스팅)
|
||||||
|
- 배포 완료: 대시보드로 이동
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.2 고객 참여 플로우
|
||||||
|
|
||||||
|
```
|
||||||
|
1. [Participation] 15-이벤트참여
|
||||||
|
- 외부 채널 (SNS/TV/연결음) → 이벤트 발견
|
||||||
|
- 클라이언트 → API Gateway → Participation Service
|
||||||
|
- Participation: 중복 참여 체크 (전화번호 기반)
|
||||||
|
- 참여 접수 완료 → 응모 번호 발급
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.3 성과 분석 플로우
|
||||||
|
|
||||||
|
```
|
||||||
|
1. [Analytics] 17-실시간대시보드
|
||||||
|
- 클라이언트 → API Gateway → Analytics Service
|
||||||
|
- Analytics: 캐시 확인 (TTL 5분)
|
||||||
|
* 캐시 HIT: 즉시 반환 (0.5초)
|
||||||
|
* 캐시 MISS: 다중 데이터 소스 통합
|
||||||
|
- Participation Service: 참여자 데이터
|
||||||
|
- Distribution Service: 채널별 노출 수
|
||||||
|
- 외부 APIs: 우리동네TV, 지니TV, SNS 통계
|
||||||
|
- POS 시스템: 매출 데이터 (선택)
|
||||||
|
* 결과 캐싱 (TTL 5분)
|
||||||
|
- 실시간 차트/그래프 렌더링
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 데이터 흐름 및 캐싱 전략
|
||||||
|
|
||||||
|
### 4.1 데이터 흐름
|
||||||
|
|
||||||
|
#### 읽기 플로우 (Cache-Aside 패턴)
|
||||||
|
```
|
||||||
|
1. Application → Cache 확인
|
||||||
|
- Cache HIT: 캐시된 데이터 즉시 반환
|
||||||
|
- Cache MISS:
|
||||||
|
2. Application → Database/External API 조회
|
||||||
|
3. Database/External API → Application 데이터 반환
|
||||||
|
4. Application → Cache 데이터 저장 (TTL 설정)
|
||||||
|
5. Application → Client 데이터 반환
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 쓰기 플로우 (Write-Through 패턴)
|
||||||
|
```
|
||||||
|
1. Application → Database 쓰기
|
||||||
|
2. Database → Application 성공 응답
|
||||||
|
3. Application → Cache 무효화 또는 업데이트
|
||||||
|
4. Application → Client 성공 응답
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.2 캐싱 전략
|
||||||
|
|
||||||
|
#### Redis 캐시 구조
|
||||||
|
|
||||||
|
| 서비스 | 캐시 키 패턴 | 데이터 타입 | TTL | 예상 크기 | 히트율 목표 |
|
||||||
|
|--------|-------------|-----------|-----|----------|-----------|
|
||||||
|
| User | `user:session:{token}` | String | 7일 | 1KB | - |
|
||||||
|
| User | `user:business:{사업자번호}` | String | 7일 | 0.5KB | 90% |
|
||||||
|
| AI | `ai:recommendation:{업종}:{지역}:{목적}` | Hash | 24시간 | 10KB | 80% |
|
||||||
|
| Content | `content:image:{이벤트ID}:{스타일}` | String | 7일 | 0.2KB (URL) | 80% |
|
||||||
|
| Analytics | `analytics:dashboard:{이벤트ID}` | Hash | 5분 | 5KB | 95% |
|
||||||
|
| AI | `job:{jobId}` | Hash | 1시간 | 1KB | - |
|
||||||
|
| Content | `job:{jobId}` | Hash | 1시간 | 1KB | - |
|
||||||
|
|
||||||
|
#### Redis 메모리 산정
|
||||||
|
- **예상 동시 사용자**: 100명
|
||||||
|
- **예상 이벤트 수**: 50개
|
||||||
|
- **예상 캐시 항목 수**: 10,000개
|
||||||
|
- **예상 총 메모리**: 약 50MB (운영 환경 2GB 할당)
|
||||||
|
|
||||||
|
#### 캐시 무효화 전략
|
||||||
|
- **TTL 기반 자동 만료**: 대부분의 캐시
|
||||||
|
- **수동 무효화**: 이벤트 수정/삭제 시 관련 캐시 삭제
|
||||||
|
- **Lazy 무효화**: 데이터 변경 시 다음 조회 시점에 갱신
|
||||||
|
|
||||||
|
### 4.3 데이터베이스 전략
|
||||||
|
|
||||||
|
#### 서비스별 독립 데이터베이스
|
||||||
|
- **User DB**: users, stores
|
||||||
|
- **Event DB**: events, event_objectives, event_prizes, distribution_logs
|
||||||
|
- **Participation DB**: participants, winners
|
||||||
|
- **Analytics DB**: event_stats, channel_stats
|
||||||
|
|
||||||
|
#### 데이터 일관성 전략
|
||||||
|
- **Eventual Consistency**: 서비스 간 데이터는 최종 일관성 보장
|
||||||
|
- **Strong Consistency**: 서비스 내부 트랜잭션은 강한 일관성 보장
|
||||||
|
- **Saga 패턴**: 이벤트 생성 플로우 (보상 트랜잭션)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. 확장성 및 성능 고려사항
|
||||||
|
|
||||||
|
### 5.1 수평 확장 전략
|
||||||
|
|
||||||
|
#### 서비스별 확장 전략
|
||||||
|
| 서비스 | 초기 인스턴스 | 확장 조건 | 최대 인스턴스 | Auto-scaling 메트릭 |
|
||||||
|
|--------|-------------|----------|-------------|-------------------|
|
||||||
|
| User | 2 | CPU > 70% | 5 | CPU, 메모리 |
|
||||||
|
| Event | 2 | CPU > 70% | 10 | CPU, 메모리 |
|
||||||
|
| AI | 1 | Job Queue > 10 | 3 | Queue 길이 |
|
||||||
|
| Content | 1 | Job Queue > 10 | 3 | Queue 길이 |
|
||||||
|
| Distribution | 2 | CPU > 70% | 5 | CPU, 메모리 |
|
||||||
|
| Participation | 1 | CPU > 70% | 3 | CPU, 메모리 |
|
||||||
|
| Analytics | 1 | CPU > 70% | 3 | CPU, 메모리 |
|
||||||
|
|
||||||
|
#### Redis Cluster
|
||||||
|
- **초기 구성**: 3 노드 (Master 3, Replica 3)
|
||||||
|
- **확장**: 노드 추가를 통한 수평 확장
|
||||||
|
- **HA**: Redis Sentinel을 통한 자동 Failover
|
||||||
|
|
||||||
|
#### Database Replication
|
||||||
|
- **Primary-Replica 구조**: 읽기 부하 분산
|
||||||
|
- **읽기 확장**: Read Replica 추가 (필요 시)
|
||||||
|
- **쓰기 확장**: Sharding (Phase 2 이후)
|
||||||
|
|
||||||
|
### 5.2 성능 목표
|
||||||
|
|
||||||
|
#### 응답 시간 목표
|
||||||
|
| 기능 | 목표 시간 | 캐시 HIT | 캐시 MISS |
|
||||||
|
|------|----------|---------|----------|
|
||||||
|
| 로그인 | 0.5초 | - | - |
|
||||||
|
| 이벤트 목록 조회 | 0.3초 | - | - |
|
||||||
|
| AI 트렌드 분석 + 추천 | 0.1초 | ✅ | 10초 (비동기) |
|
||||||
|
| SNS 이미지 생성 | 0.1초 | ✅ | 5초 (비동기) |
|
||||||
|
| 다중 채널 배포 | 1분 | - | - |
|
||||||
|
| 대시보드 로딩 | 0.5초 | ✅ | 3초 |
|
||||||
|
|
||||||
|
#### 처리량 목표
|
||||||
|
- **동시 사용자**: 100명 (MVP 목표)
|
||||||
|
- **API 요청**: 1,000 req/min
|
||||||
|
- **AI 작업**: 10 jobs/min
|
||||||
|
- **이미지 생성**: 10 jobs/min
|
||||||
|
|
||||||
|
### 5.3 성능 최적화 기법
|
||||||
|
|
||||||
|
#### Frontend 최적화
|
||||||
|
- **Code Splitting**: 페이지별 번들 분할
|
||||||
|
- **Lazy Loading**: 차트 라이브러리 지연 로딩
|
||||||
|
- **CDN**: 정적 자산 CDN 배포
|
||||||
|
- **Compression**: Gzip/Brotli 압축
|
||||||
|
|
||||||
|
#### Backend 최적화
|
||||||
|
- **Connection Pooling**: 데이터베이스 연결 풀 관리
|
||||||
|
- **Query Optimization**: 인덱스 최적화, N+1 쿼리 방지
|
||||||
|
- **Batch Processing**: 대량 데이터 일괄 처리
|
||||||
|
- **Pagination**: 목록 조회 페이지네이션
|
||||||
|
|
||||||
|
#### Cache 최적화
|
||||||
|
- **Multi-Level Caching**: Browser Cache → CDN → Redis → Database
|
||||||
|
- **Cache Warming**: 자주 사용되는 데이터 사전 로딩
|
||||||
|
- **Cache Preloading**: 피크 시간 전 캐시 준비
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. 보안 고려사항
|
||||||
|
|
||||||
|
### 6.1 인증 및 인가
|
||||||
|
|
||||||
|
#### JWT 기반 인증
|
||||||
|
- **토큰 발급**: User Service에서 로그인 시 JWT 토큰 발급
|
||||||
|
- **토큰 검증**: API Gateway에서 모든 요청의 JWT 토큰 검증
|
||||||
|
- **토큰 저장**: Redis에 세션 정보 저장 (TTL 7일)
|
||||||
|
- **토큰 갱신**: Refresh Token 패턴 (선택)
|
||||||
|
|
||||||
|
#### 역할 기반 접근 제어 (RBAC)
|
||||||
|
- **역할**: OWNER (매장 사장님), CUSTOMER (이벤트 참여자)
|
||||||
|
- **권한 관리**: API별 필요 역할 정의
|
||||||
|
- **API Gateway 검증**: 요청자의 역할 확인
|
||||||
|
|
||||||
|
### 6.2 데이터 보안
|
||||||
|
|
||||||
|
#### 민감 정보 암호화
|
||||||
|
- **비밀번호**: bcrypt 해싱 (Cost Factor: 10)
|
||||||
|
- **사업자번호**: AES-256 암호화 저장
|
||||||
|
- **개인정보**: 전화번호 마스킹 (010-****-1234)
|
||||||
|
|
||||||
|
#### 전송 보안
|
||||||
|
- **HTTPS**: 모든 통신 TLS 1.3 암호화
|
||||||
|
- **API Key**: 외부 API 호출 시 안전한 Key 관리 (AWS Secrets Manager)
|
||||||
|
|
||||||
|
#### 데이터 접근 통제
|
||||||
|
- **Database**: 서비스별 독립 계정, 최소 권한 원칙
|
||||||
|
- **Redis**: 비밀번호 설정, ACL 적용
|
||||||
|
- **백업**: 암호화된 백업 저장
|
||||||
|
|
||||||
|
### 6.3 보안 모니터링
|
||||||
|
|
||||||
|
#### 위협 탐지
|
||||||
|
- **Rate Limiting**: API Gateway에서 사용자당 100 req/min
|
||||||
|
- **Brute Force 방지**: 로그인 5회 실패 시 계정 잠금 (삭제됨, 향후 추가 가능)
|
||||||
|
- **SQL Injection 방지**: Prepared Statement 사용
|
||||||
|
- **XSS 방지**: 입력 데이터 Sanitization
|
||||||
|
|
||||||
|
#### 로깅 및 감사
|
||||||
|
- **Access Log**: 모든 API 요청 로깅
|
||||||
|
- **Audit Log**: 민감 작업 (로그인, 이벤트 생성, 당첨자 추첨) 감사 로그
|
||||||
|
- **중앙집중식 로깅**: ELK Stack 또는 CloudWatch Logs
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. 논리 아키텍처 다이어그램
|
||||||
|
|
||||||
|
논리 아키텍처 다이어그램은 별도 Mermaid 파일로 작성되었습니다.
|
||||||
|
|
||||||
|
**파일 위치**: `logical-architecture.mmd`
|
||||||
|
|
||||||
|
**다이어그램 확인 방법**:
|
||||||
|
1. https://mermaid.live/edit 접속
|
||||||
|
2. `logical-architecture.mmd` 파일 내용 붙여넣기
|
||||||
|
3. 다이어그램 시각적 확인
|
||||||
|
|
||||||
|
**다이어그램 구성**:
|
||||||
|
- Client Layer: Web/Mobile Client
|
||||||
|
- Gateway Layer: API Gateway
|
||||||
|
- Service Layer: 7개 마이크로서비스
|
||||||
|
- Data Layer: Redis Cache, Message Queue, Databases
|
||||||
|
- External APIs: 7개 외부 API
|
||||||
|
|
||||||
|
**의존성 표현**:
|
||||||
|
- 실선 화살표 (→): 동기적 의존성
|
||||||
|
- 점선 화살표 (-.->): 비동기 의존성 또는 캐시 접근
|
||||||
|
- 화살표 레이블: 의존성 목적 명시
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 부록
|
||||||
|
|
||||||
|
### A. 참고 문서
|
||||||
|
- [유저스토리](../../userstory.md)
|
||||||
|
- [아키텍처 패턴](../../pattern/architecture-pattern.md)
|
||||||
|
- [UI/UX 설계서](../../uiux/uiux.md)
|
||||||
|
- [클라우드 디자인 패턴](../../../claude/cloud-design-patterns.md)
|
||||||
|
|
||||||
|
### B. 주요 결정사항
|
||||||
|
1. **Cache-Aside 패턴 채택**: AI 응답 시간 90% 개선 목표
|
||||||
|
2. **Asynchronous Request-Reply 패턴 채택**: AI/이미지 생성 비동기 처리
|
||||||
|
3. **Circuit Breaker 패턴 채택**: 외부 API 장애 격리
|
||||||
|
4. **서비스별 독립 Database**: 마이크로서비스 독립성 보장
|
||||||
|
5. **Redis 캐시 우선 전략**: 서비스 간 직접 의존성 최소화
|
||||||
|
|
||||||
|
### C. 향후 개선 방안 (Phase 2 이후)
|
||||||
|
1. **Saga 패턴**: 복잡한 분산 트랜잭션 관리
|
||||||
|
2. **CQRS 패턴**: 읽기/쓰기 분리로 대시보드 성능 최적화
|
||||||
|
3. **Event Sourcing**: 이벤트 변경 이력 추적 및 감사
|
||||||
|
4. **Service Mesh**: Istio를 통한 고급 트래픽 관리
|
||||||
|
5. **Database Sharding**: 쓰기 확장성 개선
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**문서 버전**: 1.0
|
||||||
|
**최종 수정일**: 2025-10-21
|
||||||
|
**작성자**: System Architect
|
||||||
128
design/backend/logical/logical-architecture.mmd
Normal file
128
design/backend/logical/logical-architecture.mmd
Normal file
@ -0,0 +1,128 @@
|
|||||||
|
graph TB
|
||||||
|
%% KT AI 기반 소상공인 이벤트 자동 생성 서비스 - 논리 아키텍처 (Context Map)
|
||||||
|
|
||||||
|
%% Client Layer
|
||||||
|
subgraph "Client Layer"
|
||||||
|
Mobile["Web/Mobile Client<br/>• React PWA<br/>• Mobile First<br/>• 반응형 디자인"]
|
||||||
|
end
|
||||||
|
|
||||||
|
%% Gateway Layer
|
||||||
|
subgraph "Gateway Layer"
|
||||||
|
Gateway["API Gateway<br/>• JWT 인증/인가<br/>• 라우팅<br/>• Rate Limiting<br/>• 중앙 로깅"]
|
||||||
|
end
|
||||||
|
|
||||||
|
%% Service Layer
|
||||||
|
subgraph "Service Layer"
|
||||||
|
UserSvc["User Service<br/>• 회원가입/로그인<br/>• 프로필 관리<br/>• 사업자번호 검증"]
|
||||||
|
EventSvc["Event Service<br/>• 이벤트 CRUD<br/>• 플로우 오케스트레이션<br/>• 상태 관리"]
|
||||||
|
AISvc["AI Service<br/>• 트렌드 분석<br/>• 3가지 이벤트 추천<br/>• 비동기 Job 처리"]
|
||||||
|
ContentSvc["Content Service<br/>• SNS 이미지 생성<br/>• 3가지 스타일<br/>• 비동기 Job 처리"]
|
||||||
|
DistSvc["Distribution Service<br/>• 다중 채널 배포<br/>• Circuit Breaker<br/>• 배포 모니터링"]
|
||||||
|
PartSvc["Participation Service<br/>• 이벤트 참여<br/>• 참여자 관리<br/>• 당첨자 추첨"]
|
||||||
|
AnalSvc["Analytics Service<br/>• 실시간 대시보드<br/>• 채널별 성과<br/>• ROI 분석"]
|
||||||
|
end
|
||||||
|
|
||||||
|
%% Data Layer
|
||||||
|
subgraph "Data Layer"
|
||||||
|
Cache["Redis Cache<br/>• 세션 정보<br/>• AI 추천 결과 (24h)<br/>• 이미지 URL (7d)<br/>• 대시보드 데이터 (5m)"]
|
||||||
|
Queue["Message Queue<br/>• AI 작업 큐<br/>• 이미지 생성 큐<br/>• 배포 작업 큐"]
|
||||||
|
UserDB["User DB<br/>• users<br/>• stores"]
|
||||||
|
EventDB["Event DB<br/>• events<br/>• distribution_logs"]
|
||||||
|
PartDB["Participation DB<br/>• participants<br/>• winners"]
|
||||||
|
AnalDB["Analytics DB<br/>• event_stats<br/>• channel_stats"]
|
||||||
|
end
|
||||||
|
|
||||||
|
%% External APIs
|
||||||
|
subgraph "External APIs"
|
||||||
|
TaxAPI["국세청 API<br/>사업자번호 검증"]
|
||||||
|
ClaudeAPI["Claude/GPT-4 API<br/>AI 트렌드 분석<br/>이벤트 추천"]
|
||||||
|
SDAPI["Stable Diffusion<br/>DALL-E API<br/>이미지 생성"]
|
||||||
|
UriAPI["우리동네TV API<br/>영상 배포"]
|
||||||
|
RingoAPI["링고비즈 API<br/>연결음 업데이트"]
|
||||||
|
GenieAPI["지니TV API<br/>TV 광고"]
|
||||||
|
SNSAPI["SNS APIs<br/>Instagram<br/>Naver<br/>Kakao"]
|
||||||
|
end
|
||||||
|
|
||||||
|
%% Client to Gateway (단일 연결)
|
||||||
|
Mobile -->|HTTPS| Gateway
|
||||||
|
|
||||||
|
%% Gateway to Services (동기)
|
||||||
|
Gateway -->|인증/프로필| UserSvc
|
||||||
|
Gateway -->|이벤트 관리| EventSvc
|
||||||
|
Gateway -->|참여자 관리| PartSvc
|
||||||
|
Gateway -->|성과 분석| AnalSvc
|
||||||
|
|
||||||
|
%% Event Service Dependencies
|
||||||
|
EventSvc -.->|"[Event]AI 추천 요청<br/>(Job 생성)"| Queue
|
||||||
|
Queue -.->|비동기 작업 처리| AISvc
|
||||||
|
|
||||||
|
EventSvc -.->|"[Event]이미지 생성 요청<br/>(Job 생성)"| Queue
|
||||||
|
Queue -.->|비동기 작업 처리| ContentSvc
|
||||||
|
|
||||||
|
EventSvc -->|배포 시작| DistSvc
|
||||||
|
|
||||||
|
%% AI Service Dependencies
|
||||||
|
AISvc -.->|"AI 추천 캐싱<br/>(Cache-Aside, 24h)"| Cache
|
||||||
|
AISvc -->|"트렌드 분석<br/>이벤트 추천<br/>(Circuit Breaker)"| ClaudeAPI
|
||||||
|
|
||||||
|
%% Content Service Dependencies
|
||||||
|
ContentSvc -.->|"이미지 URL 캐싱<br/>(Cache-Aside, 7d)"| Cache
|
||||||
|
ContentSvc -->|"이미지 생성<br/>(Circuit Breaker)"| SDAPI
|
||||||
|
|
||||||
|
%% Distribution Service Dependencies
|
||||||
|
DistSvc -->|"영상 배포<br/>(Circuit Breaker)"| UriAPI
|
||||||
|
DistSvc -->|"연결음 업데이트<br/>(Circuit Breaker)"| RingoAPI
|
||||||
|
DistSvc -->|"TV 광고<br/>(Circuit Breaker)"| GenieAPI
|
||||||
|
DistSvc -->|"SNS 자동 포스팅<br/>(Circuit Breaker)"| SNSAPI
|
||||||
|
|
||||||
|
%% User Service Dependencies
|
||||||
|
UserSvc -.->|세션 관리| Cache
|
||||||
|
UserSvc -.->|"사업자번호 캐싱<br/>(Cache-Aside, 7d)"| Cache
|
||||||
|
UserSvc -->|"사업자번호 검증<br/>(Circuit Breaker)"| TaxAPI
|
||||||
|
UserSvc -.->|사용자 정보| UserDB
|
||||||
|
|
||||||
|
%% Event Service Database
|
||||||
|
EventSvc -.->|이벤트 정보| EventDB
|
||||||
|
|
||||||
|
%% Participation Service Dependencies
|
||||||
|
PartSvc -.->|참여자 데이터| PartDB
|
||||||
|
PartSvc -->|이벤트 정보 조회| EventSvc
|
||||||
|
|
||||||
|
%% Analytics Service Dependencies
|
||||||
|
AnalSvc -.->|"대시보드 캐싱<br/>(Cache-Aside, 5m)"| Cache
|
||||||
|
AnalSvc -.->|통계 데이터| AnalDB
|
||||||
|
AnalSvc -->|이벤트 정보| EventSvc
|
||||||
|
AnalSvc -->|참여자 데이터| PartSvc
|
||||||
|
AnalSvc -->|배포 통계| DistSvc
|
||||||
|
AnalSvc -->|"채널별 노출 수<br/>(Circuit Breaker)"| UriAPI
|
||||||
|
AnalSvc -->|"채널별 노출 수<br/>(Circuit Breaker)"| GenieAPI
|
||||||
|
AnalSvc -->|"SNS 통계<br/>(Circuit Breaker)"| SNSAPI
|
||||||
|
|
||||||
|
%% Styling
|
||||||
|
classDef client fill:#BFDBFE,stroke:#3B82F6,stroke-width:2px
|
||||||
|
classDef gateway fill:#2E86AB,stroke:#1E3A8A,stroke-width:2px,color:#fff
|
||||||
|
classDef user fill:#4ECDC4,stroke:#14B8A6,stroke-width:2px
|
||||||
|
classDef event fill:#F18F01,stroke:#F97316,stroke-width:2px
|
||||||
|
classDef ai fill:#10B981,stroke:#059669,stroke-width:2px
|
||||||
|
classDef content fill:#8B5CF6,stroke:#7C3AED,stroke-width:2px,color:#fff
|
||||||
|
classDef dist fill:#EC4899,stroke:#DB2777,stroke-width:2px,color:#fff
|
||||||
|
classDef part fill:#F59E0B,stroke:#F97316,stroke-width:2px
|
||||||
|
classDef anal fill:#06B6D4,stroke:#0891B2,stroke-width:2px
|
||||||
|
classDef cache fill:#FCD34D,stroke:#F59E0B,stroke-width:2px
|
||||||
|
classDef queue fill:#FB923C,stroke:#EA580C,stroke-width:2px
|
||||||
|
classDef db fill:#A78BFA,stroke:#8B5CF6,stroke-width:2px,color:#fff
|
||||||
|
classDef external fill:#E5E7EB,stroke:#9CA3AF,stroke-width:2px
|
||||||
|
|
||||||
|
class Mobile client
|
||||||
|
class Gateway gateway
|
||||||
|
class UserSvc user
|
||||||
|
class EventSvc event
|
||||||
|
class AISvc ai
|
||||||
|
class ContentSvc content
|
||||||
|
class DistSvc dist
|
||||||
|
class PartSvc part
|
||||||
|
class AnalSvc anal
|
||||||
|
class Cache cache
|
||||||
|
class Queue queue
|
||||||
|
class UserDB,EventDB,PartDB,AnalDB db
|
||||||
|
class TaxAPI,ClaudeAPI,SDAPI,UriAPI,RingoAPI,GenieAPI,SNSAPI external
|
||||||
107
tools/check-mermaid.sh
Executable file
107
tools/check-mermaid.sh
Executable file
@ -0,0 +1,107 @@
|
|||||||
|
#!/bin/bash
|
||||||
|
# Mermaid Syntax Checker using Docker Container
|
||||||
|
# Similar to PlantUML checker - keeps container running for better performance
|
||||||
|
|
||||||
|
# Colors for output
|
||||||
|
RED='\033[0;31m'
|
||||||
|
GREEN='\033[0;32m'
|
||||||
|
YELLOW='\033[0;33m'
|
||||||
|
CYAN='\033[0;36m'
|
||||||
|
GRAY='\033[0;90m'
|
||||||
|
NC='\033[0m' # No Color
|
||||||
|
|
||||||
|
# Check if file path is provided
|
||||||
|
if [ -z "$1" ]; then
|
||||||
|
echo -e "${RED}Error: No file path provided${NC}"
|
||||||
|
echo "Usage: $0 <mermaid-file>"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
FILE_PATH="$1"
|
||||||
|
|
||||||
|
# Check if file exists
|
||||||
|
if [ ! -f "$FILE_PATH" ]; then
|
||||||
|
echo -e "${RED}Error: File not found: $FILE_PATH${NC}"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Get absolute path
|
||||||
|
ABSOLUTE_PATH=$(realpath "$FILE_PATH")
|
||||||
|
FILE_NAME=$(basename "$ABSOLUTE_PATH")
|
||||||
|
|
||||||
|
echo -e "\n${CYAN}Checking Mermaid syntax for: $FILE_NAME${NC}"
|
||||||
|
echo -e "${GRAY}$(printf '=%.0s' {1..60})${NC}"
|
||||||
|
|
||||||
|
# Check if mermaid container is running
|
||||||
|
CONTAINER_RUNNING=$(docker ps --filter "name=mermaid-cli" --format "{{.Names}}" 2>/dev/null)
|
||||||
|
|
||||||
|
if [ -z "$CONTAINER_RUNNING" ]; then
|
||||||
|
echo -e "${RED}Error: Mermaid CLI container is not running.${NC}"
|
||||||
|
echo -e "${YELLOW}Please follow the setup instructions in the Mermaid guide to start the container.${NC}"
|
||||||
|
echo -e "\n${CYAN}Quick setup commands:${NC}"
|
||||||
|
echo ""
|
||||||
|
echo -e "${GREEN}# 1. Start container with root privileges (port 48080)${NC}"
|
||||||
|
echo -e "${NC}docker run -d --rm --name mermaid-cli -u root -p 48080:8080 --entrypoint sh minlag/mermaid-cli:latest -c \"while true;do sleep 3600; done\"${NC}"
|
||||||
|
echo ""
|
||||||
|
echo -e "${GREEN}# 2. Install Chromium and dependencies${NC}"
|
||||||
|
echo -e "${NC}docker exec mermaid-cli sh -c \"apk add --no-cache chromium chromium-chromedriver nss freetype harfbuzz ca-certificates ttf-freefont\"${NC}"
|
||||||
|
echo ""
|
||||||
|
echo -e "${GREEN}# 3. Create Puppeteer configuration${NC}"
|
||||||
|
echo -e "${NC}docker exec mermaid-cli sh -c \"echo '{\\\"executablePath\\\": \\\"/usr/bin/chromium-browser\\\", \\\"args\\\": [\\\"--no-sandbox\\\", \\\"--disable-setuid-sandbox\\\", \\\"--disable-dev-shm-usage\\\"]}' > /tmp/puppeteer-config.json\"${NC}"
|
||||||
|
echo ""
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Set Puppeteer configuration file path
|
||||||
|
PUPPETEER_CONFIG_FILE="/tmp/puppeteer-config.json"
|
||||||
|
|
||||||
|
# Generate unique temp filename
|
||||||
|
TIMESTAMP=$(date +"%Y%m%d%H%M%S")
|
||||||
|
PID=$$
|
||||||
|
TEMP_FILE="/tmp/mermaid_${TIMESTAMP}_${PID}.mmd"
|
||||||
|
OUTPUT_FILE="/tmp/mermaid_${TIMESTAMP}_${PID}.svg"
|
||||||
|
|
||||||
|
# Copy file to container
|
||||||
|
echo -e "${GRAY}Copying file to container...${NC}"
|
||||||
|
docker cp "$ABSOLUTE_PATH" "mermaid-cli:$TEMP_FILE" >/dev/null 2>&1
|
||||||
|
|
||||||
|
if [ $? -ne 0 ]; then
|
||||||
|
echo -e "${RED}Error: Failed to copy file to container${NC}"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Run syntax check with Puppeteer configuration
|
||||||
|
echo -e "${GRAY}Running syntax check...${NC}"
|
||||||
|
OUTPUT=$(docker exec mermaid-cli sh -c "cd /home/mermaidcli && node_modules/.bin/mmdc -i '$TEMP_FILE' -o '$OUTPUT_FILE' -p '$PUPPETEER_CONFIG_FILE' -q" 2>&1)
|
||||||
|
EXIT_CODE=$?
|
||||||
|
|
||||||
|
if [ $EXIT_CODE -eq 0 ]; then
|
||||||
|
echo -e "\n${GREEN}Success: Mermaid syntax is valid!${NC}"
|
||||||
|
else
|
||||||
|
echo -e "\n${RED}Error: Mermaid syntax validation failed!${NC}"
|
||||||
|
echo -e "\n${RED}Error details:${NC}"
|
||||||
|
|
||||||
|
# Parse and display error messages
|
||||||
|
while IFS= read -r line; do
|
||||||
|
if [[ $line == *"Error:"* ]] || [[ $line == *"Parse error"* ]] || [[ $line == *"Expecting"* ]] || [[ $line == *"Syntax error"* ]]; then
|
||||||
|
echo -e " ${RED}$line${NC}"
|
||||||
|
elif [[ $line == *"line"* ]] && [[ $line =~ [0-9]+ ]]; then
|
||||||
|
echo -e " ${YELLOW}$line${NC}"
|
||||||
|
elif [[ ! -z "$line" ]]; then
|
||||||
|
echo -e " ${RED}$line${NC}"
|
||||||
|
fi
|
||||||
|
done <<< "$OUTPUT"
|
||||||
|
|
||||||
|
# Clean up and exit with error
|
||||||
|
docker exec mermaid-cli rm -f "$TEMP_FILE" "$OUTPUT_FILE" >/dev/null 2>&1
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Clean up temp files
|
||||||
|
echo -e "\n${GRAY}Cleaning up...${NC}"
|
||||||
|
docker exec mermaid-cli rm -f "$TEMP_FILE" "$OUTPUT_FILE" >/dev/null 2>&1
|
||||||
|
|
||||||
|
echo -e "\n${CYAN}Validation complete!${NC}"
|
||||||
|
|
||||||
|
# Note: Container is kept running for subsequent checks
|
||||||
|
# To stop: docker stop mermaid-cli && docker rm mermaid-cli
|
||||||
Loading…
x
Reference in New Issue
Block a user