add logical architecture

design/backend/logical/logical-architecture.md

@@ -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

design/backend/logical/logical-architecture.mmd

@@ -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