kt-event-marketing/design/backend/database/ai-service.md

AI Service 데이터베이스 설계서

📋 데이터설계 요약

서비스 특성

• 서비스명: AI Service
• 아키텍처: Clean Architecture
• 데이터 저장소: Redis Cache Only (PostgreSQL 미사용)
• 특징: Stateless 서비스, AI API 결과 캐싱 전략

데이터 구조 개요

AI Service는 외부 AI API(Claude)와 연동하여 이벤트 추천을 생성하는 서비스로, 영속적인 데이터 저장이 필요하지 않습니다. 모든 데이터는 Redis 캐시를 통해 임시 저장되며, TTL 만료 시 자동 삭제됩니다.

캐시 키 패턴	용도	TTL	데이터 형식
ai:recommendation:{eventId}	AI 추천 결과	1시간	JSON (AIRecommendationResult)
ai:job:status:{jobId}	AI 작업 상태	24시간	JSON (JobStatusResponse)
ai:trend:{industry}:{region}	트렌드 분석 결과	24시간	JSON (TrendAnalysis)

설계 근거

1. Stateless 설계: AI 추천은 요청 시마다 실시간 생성되므로 영속화 불필요
2. 성능 최적화: 동일한 조건의 반복 요청에 대한 캐시 히트율 향상
3. 비용 절감: AI API 호출 비용 절감을 위한 캐싱 전략
4. TTL 관리: 추천의 시의성 유지를 위한 적절한 TTL 설정

---

1. 캐시 데이터베이스 설계 (Redis)

1.1 AI 추천 결과 캐시

캐시 키: ai:recommendation:{eventId}

TTL: 3600초 (1시간)

데이터 구조:

{
  "eventId": "uuid-string",
  "trendAnalysis": {
    "industryTrends": [
      {
        "keyword": "string",
        "relevance": 0.95,
        "description": "string"
      }
    ],
    "regionalTrends": [...],
    "seasonalTrends": [...]
  },
  "recommendations": [
    {
      "optionNumber": 1,
      "concept": "string",
      "title": "string",
      "description": "string",
      "targetAudience": "string",
      "duration": {
        "recommendedDays": 7,
        "recommendedPeriod": "주중"
      },
      "mechanics": {
        "type": "DISCOUNT",
        "details": "string"
      },
      "promotionChannels": ["string"],
      "estimatedCost": {
        "min": 500000,
        "max": 1000000,
        "breakdown": {
          "promotion": 300000,
          "gift": 500000
        }
      },
      "expectedMetrics": {
        "newCustomers": {
          "min": 50.0,
          "max": 100.0
        },
        "revenueIncrease": {
          "min": 10.0,
          "max": 20.0
        },
        "roi": {
          "min": 150.0,
          "max": 250.0
        }
      },
      "differentiator": "string"
    }
  ],
  "generatedAt": "2025-10-29T10:00:00",
  "expiresAt": "2025-10-29T11:00:00",
  "aiProvider": "CLAUDE"
}

용도: AI 추천 결과를 캐싱하여 동일한 이벤트에 대한 반복 요청 시 AI API 호출 생략

캐싱 전략:

• Cache-Aside 패턴
• 캐시 미스 시 AI API 호출 후 결과 저장
• TTL 만료 시 자동 삭제하여 최신 트렌드 반영

---

1.2 작업 상태 캐시

캐시 키: ai:job:status:{jobId}

TTL: 86400초 (24시간)

데이터 구조:

{
  "jobId": "uuid-string",
  "status": "PROCESSING",
  "progress": 50,
  "message": "트렌드 분석 중...",
  "createdAt": "2025-10-29T10:00:00"
}

상태 값:

• PENDING: 작업 대기 중
• PROCESSING: 작업 진행 중
• COMPLETED: 작업 완료
• FAILED: 작업 실패

용도: 비동기 AI 작업의 상태를 추적하여 클라이언트가 진행 상황 확인

캐싱 전략:

• Write-Through 패턴
• 상태 변경 시 즉시 캐시 업데이트
• 완료/실패 후 24시간 동안 상태 조회 가능

---

1.3 트렌드 분석 캐시

캐시 키: ai:trend:{industry}:{region}

TTL: 86400초 (24시간)

데이터 구조:

{
  "industryTrends": [
    {
      "keyword": "친환경",
      "relevance": 0.95,
      "description": "지속가능성과 환경 보호에 대한 관심 증가"
    }
  ],
  "regionalTrends": [
    {
      "keyword": "로컬 맛집",
      "relevance": 0.88,
      "description": "지역 특산물과 전통 음식에 대한 관심"
    }
  ],
  "seasonalTrends": [
    {
      "keyword": "겨울 따뜻함",
      "relevance": 0.82,
      "description": "추운 날씨에 따뜻한 음식 선호"
    }
  ]
}

용도: 업종 및 지역별 트렌드 분석 결과를 캐싱하여 AI API 호출 최소화

캐싱 전략:

• Cache-Aside 패턴
• 동일 업종/지역 조합에 대한 반복 분석 방지
• 하루 단위 TTL로 최신 트렌드 유지

---

2. Redis 데이터 구조 설계

2.1 Redis 키 명명 규칙

ai:recommendation:{eventId}        # AI 추천 결과
ai:job:status:{jobId}              # 작업 상태
ai:trend:{industry}:{region}       # 트렌드 분석

2.2 Redis 설정

# application.yml
spring:
  redis:
    host: ${REDIS_HOST:localhost}
    port: ${REDIS_PORT:6379}
    password: ${REDIS_PASSWORD:}
    timeout: 3000ms
    lettuce:
      pool:
        max-active: 8
        max-idle: 8
        min-idle: 2
        max-wait: -1ms

# 캐시 TTL 설정
cache:
  ttl:
    recommendation: 3600    # 1시간
    job-status: 86400      # 24시간
    trend: 86400           # 24시간

2.3 캐시 동시성 제어

Distributed Lock:

• Redis의 SETNX 명령을 사용한 분산 락
• 동일한 이벤트에 대한 중복 AI 호출 방지

// 예시: Redisson을 사용한 분산 락
RLock lock = redisson.getLock("ai:lock:event:" + eventId);
try {
    if (lock.tryLock(10, 60, TimeUnit.SECONDS)) {
        // AI API 호출 및 캐시 저장
    }
} finally {
    lock.unlock();
}

---

3. 캐시 무효화 전략

3.1 TTL 기반 자동 만료

캐시 타입	TTL	만료 이유
추천 결과	1시간	트렌드 변화 반영 필요
작업 상태	24시간	작업 완료 후 장기 보관 불필요
트렌드 분석	24시간	일간 트렌드 변화 반영

3.2 수동 무효화 트리거

• 이벤트 삭제 시: 해당 이벤트의 추천 캐시 삭제
• 시스템 업데이트 시: 전체 캐시 초기화 (관리자 기능)

---

4. 성능 최적화 전략

4.1 캐시 히트율 최적화

목표 캐시 히트율: 70% 이상

최적화 방안:

1. 프리페칭: 인기 업종/지역 조합의 트렌드를 사전 캐싱
2. 지능형 TTL: 접근 빈도에 따른 동적 TTL 조정
3. Warm-up: 서비스 시작 시 주요 데이터 사전 로딩

4.2 메모리 효율성

예상 메모리 사용량:

• 추천 결과: ~50KB/건
• 작업 상태: ~1KB/건
• 트렌드 분석: ~10KB/건

메모리 관리:

• 최대 메모리 제한: 1GB
• 만료 정책: volatile-lru (TTL이 있는 키만 LRU 제거)

---

5. 모니터링 지표

5.1 캐시 성능 지표

지표	목표	측정 방법
캐시 히트율	≥70%	(hits / (hits + misses)) × 100
평균 응답 시간	<50ms	Redis 명령 실행 시간 측정
메모리 사용률	<80%	used_memory / maxmemory
키 개수	<100,000	DBSIZE 명령

5.2 알림 임계값

• 캐시 히트율 < 50%: 경고
• 메모리 사용률 > 80%: 경고
• 평균 응답 시간 > 100ms: 경고
• Redis 연결 실패: 심각

---

6. 재해 복구 전략

6.1 데이터 손실 대응

특성: 캐시 데이터는 손실되어도 서비스 정상 동작

• Redis 장애 시 AI API 직접 호출로 대체
• Circuit Breaker 패턴으로 장애 격리
• Fallback 메커니즘으로 기본 추천 제공

6.2 Redis 고가용성

구성: Redis Sentinel 또는 Cluster

• Master-Slave 복제
• 자동 Failover
• 읽기 부하 분산

---

7. 보안 고려사항

7.1 데이터 보호

• 네트워크 암호화: TLS/SSL 연결
• 인증: Redis PASSWORD 설정
• 접근 제어: Redis ACL을 통한 명령 제한

7.2 민감 정보 처리

• AI API 키: 환경 변수로 관리 (캐시 저장 금지)
• 개인정보: 캐시에 저장하지 않음 (이벤트 ID만 사용)

---

8. 결론

AI Service는 완전한 Stateless 아키텍처를 채택하여 Redis 캐시만을 사용합니다. 이는 다음과 같은 장점을 제공합니다:

✅ 확장성: 서버 인스턴스 추가 시 상태 동기화 불필요 ✅ 성능: AI API 호출 비용 절감 및 응답 시간 단축 ✅ 단순성: 데이터베이스 스키마 관리 부담 제거 ✅ 유연성: 캐시 정책 변경 시 서비스 재시작 불필요

PostgreSQL 미사용 이유:

• AI 추천은 실시간 생성 데이터로 영속화 가치 낮음
• 이력 관리는 Analytics Service에서 담당
• 캐시 TTL로 데이터 신선도 보장

다음 단계: Redis 클러스터 구성 및 모니터링 대시보드 설정