kt-event-marketing/analytics-service/test-backend.md

# Analytics Service 백엔드 테스트 결과서

## 1. 개요

### 1.1 테스트 목적
- **userId 기반 통합 성과 분석 API 개발 및 검증**
- 사용자 전체 이벤트를 통합하여 분석하는 4개 API 개발
- 기존 eventId 기반 API와 독립적으로 동작하는 구조 검증
- MVP 환경: 1:1 관계 (1 user = 1 store)

### 1.2 테스트 환경
- **프로젝트**: kt-event-marketing
- **서비스**: analytics-service
- **브랜치**: feature/analytics
- **빌드 도구**: Gradle 8.10
- **프레임워크**: Spring Boot 3.3.0
- **언어**: Java 21

### 1.3 테스트 일시
- **작성일**: 2025-10-28
- **컴파일 테스트**: 2025-10-28

---

## 2. 개발 범위

### 2.1 Repository 수정
**파일**: 3개 Repository 인터페이스

#### EventStatsRepository
```java
// 추가된 메소드
List<EventStats> findAllByUserId(String userId);
```
- **목적**: 특정 사용자의 모든 이벤트 통계 조회
- **위치**: `analytics-service/src/main/java/com/kt/event/analytics/repository/EventStatsRepository.java`

#### ChannelStatsRepository
```java
// 추가된 메소드
List<ChannelStats> findByEventIdIn(List<String> eventIds);
```
- **목적**: 여러 이벤트의 채널 통계 일괄 조회
- **위치**: `analytics-service/src/main/java/com/kt/event/analytics/repository/ChannelStatsRepository.java`

#### TimelineDataRepository
```java
// 추가된 메소드
List<TimelineData> findByEventIdInOrderByTimestampAsc(List<String> eventIds);

@Query("SELECT t FROM TimelineData t WHERE t.eventId IN :eventIds " +
       "AND t.timestamp BETWEEN :startDate AND :endDate " +
       "ORDER BY t.timestamp ASC")
List<TimelineData> findByEventIdInAndTimestampBetween(
    @Param("eventIds") List<String> eventIds,
    @Param("startDate") LocalDateTime startDate,
    @Param("endDate") LocalDateTime endDate
);
```
- **목적**: 여러 이벤트의 타임라인 데이터 조회
- **위치**: `analytics-service/src/main/java/com/kt/event/analytics/repository/TimelineDataRepository.java`

---

### 2.2 Response DTO 작성
**파일**: 4개 Response DTO

#### UserAnalyticsDashboardResponse
- **경로**: `com.kt.event.analytics.dto.response.UserAnalyticsDashboardResponse`
- **역할**: 사용자 전체 통합 성과 대시보드 응답
- **주요 필드**:
  - `userId`: 사용자 ID
  - `totalEvents`: 총 이벤트 수
  - `activeEvents`: 활성 이벤트 수
  - `overallSummary`: 전체 성과 요약 (AnalyticsSummary)
  - `channelPerformance`: 채널별 성과 (List<ChannelSummary>)
  - `overallRoi`: 전체 ROI 요약 (RoiSummary)
  - `eventPerformances`: 이벤트별 성과 목록 (EventPerformanceSummary)
  - `period`: 조회 기간 (PeriodInfo)

#### UserChannelAnalyticsResponse
- **경로**: `com.kt.event.analytics.dto.response.UserChannelAnalyticsResponse`
- **역할**: 사용자 전체 채널별 성과 분석 응답
- **주요 필드**:
  - `userId`: 사용자 ID
  - `totalEvents`: 총 이벤트 수
  - `channels`: 채널별 상세 분석 (List<ChannelAnalytics>)
  - `comparison`: 채널 간 비교 (ChannelComparison)
  - `period`: 조회 기간 (PeriodInfo)

#### UserRoiAnalyticsResponse
- **경로**: `com.kt.event.analytics.dto.response.UserRoiAnalyticsResponse`
- **역할**: 사용자 전체 ROI 상세 분석 응답
- **주요 필드**:
  - `userId`: 사용자 ID
  - `totalEvents`: 총 이벤트 수
  - `overallInvestment`: 전체 투자 내역 (InvestmentDetails)
  - `overallRevenue`: 전체 수익 내역 (RevenueDetails)
  - `overallRoi`: ROI 계산 (RoiCalculation)
  - `costEfficiency`: 비용 효율성 (CostEfficiency)
  - `projection`: 수익 예측 (RevenueProjection)
  - `eventRois`: 이벤트별 ROI (EventRoiSummary)
  - `period`: 조회 기간 (PeriodInfo)

#### UserTimelineAnalyticsResponse
- **경로**: `com.kt.event.analytics.dto.response.UserTimelineAnalyticsResponse`
- **역할**: 사용자 전체 시간대별 참여 추이 분석 응답
- **주요 필드**:
  - `userId`: 사용자 ID
  - `totalEvents`: 총 이벤트 수
  - `interval`: 시간 간격 단위 (hourly, daily, weekly, monthly)
  - `dataPoints`: 시간대별 데이터 포인트 (List<TimelineDataPoint>)
  - `trend`: 추세 분석 (TrendAnalysis)
  - `peakTime`: 피크 시간대 정보 (PeakTimeInfo)
  - `period`: 조회 기간 (PeriodInfo)

---

### 2.3 Service 개발
**파일**: 4개 Service 클래스

#### UserAnalyticsService
- **경로**: `com.kt.event.analytics.service.UserAnalyticsService`
- **역할**: 사용자 전체 이벤트 통합 성과 대시보드 서비스
- **주요 기능**:
  - `getUserDashboardData()`: 사용자 전체 대시보드 데이터 조회
  - Redis 캐싱 (TTL: 30분)
  - 전체 성과 요약 계산 (참여자, 조회수, 참여율, 전환율)
  - 채널별 성과 통합 집계
  - 전체 ROI 계산
  - 이벤트별 성과 목록 생성
- **특징**:
  - 모든 이벤트의 메트릭을 합산하여 통합 분석
  - 채널명 기준으로 그룹화하여 채널 성과 집계
  - BigDecimal 타입으로 금액 정확도 보장

#### UserChannelAnalyticsService
- **경로**: `com.kt.event.analytics.service.UserChannelAnalyticsService`
- **역할**: 사용자 전체 이벤트의 채널별 성과 통합 서비스
- **주요 기능**:
  - `getUserChannelAnalytics()`: 사용자 전체 채널 분석 데이터 조회
  - Redis 캐싱 (TTL: 30분)
  - 채널별 메트릭 집계 (조회수, 참여자, 클릭, 전환)
  - 채널 성과 지표 계산 (참여율, 전환율, CTR, ROI)
  - 채널 비용 분석 (조회당/클릭당/획득당 비용)
  - 채널 간 비교 분석 (최고 성과, 평균 지표)
- **특징**:
  - 채널명 기준으로 그룹화하여 통합 집계
  - 다양한 정렬 옵션 지원 (participants, views, engagement_rate, conversion_rate, roi)
  - 채널 필터링 기능

#### UserRoiAnalyticsService
- **경로**: `com.kt.event.analytics.service.UserRoiAnalyticsService`
- **역할**: 사용자 전체 이벤트의 ROI 통합 분석 서비스
- **주요 기능**:
  - `getUserRoiAnalytics()`: 사용자 전체 ROI 분석 데이터 조회
  - Redis 캐싱 (TTL: 30분)
  - 전체 투자 금액 집계 (콘텐츠 제작, 운영, 배포 비용)
  - 전체 수익 집계 (직접 판매, 예상 판매)
  - ROI 계산 (순이익, ROI %)
  - 비용 효율성 분석 (참여자당 비용/수익)
  - 수익 예측 (현재 수익 기반 최종 수익 예측)
- **특징**:
  - BigDecimal로 금액 정밀 계산
  - 이벤트별 ROI 순위 제공
  - 선택적 수익 예측 기능

#### UserTimelineAnalyticsService
- **경로**: `com.kt.event.analytics.service.UserTimelineAnalyticsService`
- **역할**: 사용자 전체 이벤트의 시간대별 추이 통합 서비스
- **주요 기능**:
  - `getUserTimelineAnalytics()`: 사용자 전체 타임라인 분석 데이터 조회
  - Redis 캐싱 (TTL: 30분)
  - 시간 간격별 데이터 집계 (hourly, daily, weekly, monthly)
  - 추세 분석 (증가/감소/안정)
  - 피크 시간대 식별 (최대 참여자 시점)
- **특징**:
  - 시간대별로 정규화하여 데이터 집계
  - 전반부/후반부 비교를 통한 성장률 계산
  - 메트릭별 필터링 지원

---

### 2.4 Controller 개발
**파일**: 4개 Controller 클래스

#### UserAnalyticsDashboardController
- **경로**: `com.kt.event.analytics.controller.UserAnalyticsDashboardController`
- **엔드포인트**: `GET /api/v1/users/{userId}/analytics`
- **역할**: 사용자 전체 성과 대시보드 API
- **Request Parameters**:
  - `userId` (Path): 사용자 ID (필수)
  - `startDate` (Query): 조회 시작 날짜 (선택, ISO 8601 format)
  - `endDate` (Query): 조회 종료 날짜 (선택, ISO 8601 format)
  - `refresh` (Query): 캐시 갱신 여부 (선택, default: false)
- **Response**: `ApiResponse<UserAnalyticsDashboardResponse>`

#### UserChannelAnalyticsController
- **경로**: `com.kt.event.analytics.controller.UserChannelAnalyticsController`
- **엔드포인트**: `GET /api/v1/users/{userId}/analytics/channels`
- **역할**: 사용자 전체 채널별 성과 분석 API
- **Request Parameters**:
  - `userId` (Path): 사용자 ID (필수)
  - `channels` (Query): 조회할 채널 목록 (쉼표 구분, 선택)
  - `sortBy` (Query): 정렬 기준 (선택, default: participants)
  - `order` (Query): 정렬 순서 (선택, default: desc)
  - `startDate` (Query): 조회 시작 날짜 (선택)
  - `endDate` (Query): 조회 종료 날짜 (선택)
  - `refresh` (Query): 캐시 갱신 여부 (선택, default: false)
- **Response**: `ApiResponse<UserChannelAnalyticsResponse>`

#### UserRoiAnalyticsController
- **경로**: `com.kt.event.analytics.controller.UserRoiAnalyticsController`
- **엔드포인트**: `GET /api/v1/users/{userId}/analytics/roi`
- **역할**: 사용자 전체 ROI 상세 분석 API
- **Request Parameters**:
  - `userId` (Path): 사용자 ID (필수)
  - `includeProjection` (Query): 예상 수익 포함 여부 (선택, default: true)
  - `startDate` (Query): 조회 시작 날짜 (선택)
  - `endDate` (Query): 조회 종료 날짜 (선택)
  - `refresh` (Query): 캐시 갱신 여부 (선택, default: false)
- **Response**: `ApiResponse<UserRoiAnalyticsResponse>`

#### UserTimelineAnalyticsController
- **경로**: `com.kt.event.analytics.controller.UserTimelineAnalyticsController`
- **엔드포인트**: `GET /api/v1/users/{userId}/analytics/timeline`
- **역할**: 사용자 전체 시간대별 참여 추이 분석 API
- **Request Parameters**:
  - `userId` (Path): 사용자 ID (필수)
  - `interval` (Query): 시간 간격 단위 (선택, default: daily)
    - 값: hourly, daily, weekly, monthly
  - `startDate` (Query): 조회 시작 날짜 (선택)
  - `endDate` (Query): 조회 종료 날짜 (선택)
  - `metrics` (Query): 조회할 지표 목록 (쉼표 구분, 선택)
  - `refresh` (Query): 캐시 갱신 여부 (선택, default: false)
- **Response**: `ApiResponse<UserTimelineAnalyticsResponse>`

---

## 3. 컴파일 테스트

### 3.1 테스트 명령
```bash
./gradlew.bat analytics-service:compileJava
```

### 3.2 테스트 결과
**상태**: ✅ **성공 (BUILD SUCCESSFUL)**

**출력**:
```
> Task :common:generateEffectiveLombokConfig UP-TO-DATE
> Task :common:compileJava UP-TO-DATE
> Task :analytics-service:generateEffectiveLombokConfig
> Task :analytics-service:compileJava

BUILD SUCCESSFUL in 8s
4 actionable tasks: 2 executed, 2 up-to-date
```

### 3.3 오류 해결 과정

#### 3.3.1 초기 컴파일 오류 (19개)
**문제**: 기존 DTO 구조와 Service 코드 간 필드명/타입 불일치

**해결**:
1. **AnalyticsSummary**: totalInvestment, expectedRevenue 필드 제거
2. **ChannelSummary**: cost 필드 제거
3. **RoiSummary**: BigDecimal 타입 사용
4. **InvestmentDetails**: totalAmount → total 변경, 필드명 수정 (contentCreation, operation, distribution)
5. **RevenueDetails**: totalRevenue → total 변경, 필드명 수정 (directSales, expectedSales)
6. **RoiCalculation**: totalInvestment, totalRevenue 필드 제거
7. **TrendAnalysis**: direction → overallTrend 변경
8. **PeakTimeInfo**: participants → value 변경, metric, description 추가
9. **ChannelPerformance**: participationRate 필드 제거
10. **ChannelCosts**: totalCost → distributionCost 변경, costPerParticipant → costPerAcquisition 변경
11. **ChannelComparison**: mostEfficient, highestEngagement → averageMetrics로 통합
12. **RevenueProjection**: projectedRevenue → projectedFinalRevenue 변경, basedOn 필드 추가

#### 3.3.2 수정된 파일
- `UserAnalyticsService.java`: DTO 필드명 수정 (5곳)
- `UserChannelAnalyticsService.java`: DTO 필드명 수정, HashMap import 추가 (3곳)
- `UserRoiAnalyticsService.java`: DTO 필드명 수정, BigDecimal 타입 사용 (4곳)
- `UserTimelineAnalyticsService.java`: DTO 필드명 수정 (3곳)

---

## 4. API 설계 요약

### 4.1 API 엔드포인트 구조
```
/api/v1/users/{userId}/analytics
├─ GET /                     # 전체 통합 대시보드
├─ GET /channels             # 채널별 성과 분석
├─ GET /roi                  # ROI 상세 분석
└─ GET /timeline             # 시간대별 참여 추이
```

### 4.2 기존 API와의 비교
| 구분 | 기존 API | 신규 API |
|------|----------|----------|
| **기준** | eventId (개별 이벤트) | userId (사용자 전체) |
| **범위** | 단일 이벤트 | 사용자의 모든 이벤트 통합 |
| **엔드포인트** | `/api/v1/events/{eventId}/...` | `/api/v1/users/{userId}/...` |
| **캐시 TTL** | 3600초 (60분) | 1800초 (30분) |
| **데이터 집계** | 개별 이벤트 데이터 | 여러 이벤트 합산/평균 |

### 4.3 캐싱 전략
- **캐시 키 형식**: `analytics:user:{category}:{userId}`
- **TTL**: 30분 (1800초)
  - 여러 이벤트 통합으로 데이터 변동성이 높아 기존보다 짧게 설정
- **갱신 방식**: `refresh=true` 파라미터로 강제 갱신 가능
- **구현**: RedisTemplate + Jackson ObjectMapper

---

## 5. 주요 기능

### 5.1 데이터 집계 로직
#### 5.1.1 통합 성과 계산
- **참여자 수**: 모든 이벤트의 totalParticipants 합산
- **조회수**: 모든 이벤트의 totalViews 합산
- **참여율**: 전체 참여자 / 전체 조회수 * 100
- **전환율**: 전체 전환 / 전체 참여자 * 100

#### 5.1.2 채널 성과 집계
- **그룹화**: 채널명(channelName) 기준
- **메트릭 합산**: views, participants, clicks, conversions
- **비용 집계**: distributionCost 합산
- **ROI 계산**: (참여자 - 비용) / 비용 * 100

#### 5.1.3 ROI 계산
- **투자 금액**: 모든 이벤트의 totalInvestment 합산
- **수익**: 모든 이벤트의 expectedRevenue 합산
- **순이익**: 수익 - 투자
- **ROI**: (순이익 / 투자) * 100

#### 5.1.4 시간대별 집계
- **정규화**: interval에 따라 timestamp 정규화
  - hourly: 시간 단위로 truncate
  - daily: 일 단위로 truncate
  - weekly: 주 시작일로 정규화
  - monthly: 월 시작일로 정규화
- **데이터 포인트 합산**: 동일 시간대의 participants, views, engagement, conversions 합산

### 5.2 추세 분석
- **전반부/후반부 비교**: 데이터 포인트를 반으로 나누어 성장률 계산
- **추세 결정**:
  - 성장률 > 5%: "increasing"
  - 성장률 < -5%: "decreasing"
  - -5% ≤ 성장률 ≤ 5%: "stable"

### 5.3 피크 시간 식별
- **기준**: 참여자 수(participants) 최대 시점
- **정보**: timestamp, metric, value, description

---

## 6. 아키텍처 특징

### 6.1 계층 구조
```
Controller
    ↓
Service (비즈니스 로직)
    ↓
Repository (데이터 접근)
    ↓
Entity (JPA)
```

### 6.2 독립성 보장
- **기존 eventId 기반 API와 독립적 구조**
- **별도의 Controller, Service 클래스**
- **공통 Repository 재사용**
- **기존 DTO 구조 준수**

### 6.3 확장성
- **새로운 메트릭 추가 용이**: Service 레이어에서 계산 로직 추가
- **캐싱 전략 개별 조정 가능**: 각 Service마다 독립적인 캐시 키
- **채널/이벤트 필터링 지원**: 동적 쿼리 지원

---

## 7. 검증 결과

### 7.1 컴파일 검증
- ✅ **Service 계층**: 4개 클래스 컴파일 성공
- ✅ **Controller 계층**: 4개 클래스 컴파일 성공
- ✅ **Repository 계층**: 3개 인터페이스 컴파일 성공
- ✅ **DTO 계층**: 4개 Response 클래스 컴파일 성공

### 7.2 코드 품질
- ✅ **Lombok 활용**: Builder 패턴, Data 클래스
- ✅ **로깅**: Slf4j 적용
- ✅ **트랜잭션**: @Transactional(readOnly = true)
- ✅ **예외 처리**: try-catch로 캐시 오류 대응
- ✅ **타입 안정성**: BigDecimal로 금액 처리

### 7.3 Swagger 문서화
- ✅ **@Tag**: API 그룹 정의
- ✅ **@Operation**: 엔드포인트 설명
- ✅ **@Parameter**: 파라미터 설명

---

## 8. 다음 단계

### 8.1 백엔드 개발 완료 항목
- ✅ Repository 쿼리 메소드 추가
- ✅ Response DTO 작성
- ✅ Service 로직 구현
- ✅ Controller API 개발
- ✅ 컴파일 검증

### 8.2 향후 작업
1. **백엔드 서버 실행 테스트** (Phase 1 완료 후)
   - 애플리케이션 실행 확인
   - API 엔드포인트 접근 테스트
   - Swagger UI 확인

2. **API 통합 테스트** (Phase 1 완료 후)
   - Postman/curl로 API 호출 테스트
   - 실제 데이터로 응답 검증
   - 에러 핸들링 확인

3. **프론트엔드 연동** (Phase 2)
   - 프론트엔드에서 4개 API 호출
   - 응답 데이터 바인딩
   - UI 렌더링 검증

---

## 9. 결론

### 9.1 성과
- ✅ **userId 기반 통합 분석 API 4개 개발 완료**
- ✅ **컴파일 성공**
- ✅ **기존 구조와 독립적인 설계**
- ✅ **확장 가능한 아키텍처**
- ✅ **MVP 환경 1:1 관계 (1 user = 1 store) 적용**

### 9.2 특이사항
- **기존 DTO 구조 재사용**: 새로운 DTO 생성 최소화
- **BigDecimal 타입 사용**: 금액 정확도 보장
- **캐싱 전략**: Redis 캐싱으로 성능 최적화 (TTL: 30분)

### 9.3 개발 시간
- **예상 개발 기간**: 3~4일
- **실제 개발 완료**: 1일 (컴파일 테스트까지)

---

## 10. 첨부

### 10.1 주요 파일 목록
```
analytics-service/src/main/java/com/kt/event/analytics/
├── repository/
│   ├── EventStatsRepository.java (수정)
│   ├── ChannelStatsRepository.java (수정)
│   └── TimelineDataRepository.java (수정)
├── dto/response/
│   ├── UserAnalyticsDashboardResponse.java (신규)
│   ├── UserChannelAnalyticsResponse.java (신규)
│   ├── UserRoiAnalyticsResponse.java (신규)
│   └── UserTimelineAnalyticsResponse.java (신규)
├── service/
│   ├── UserAnalyticsService.java (신규)
│   ├── UserChannelAnalyticsService.java (신규)
│   ├── UserRoiAnalyticsService.java (신규)
│   └── UserTimelineAnalyticsService.java (신규)
└── controller/
    ├── UserAnalyticsDashboardController.java (신규)
    ├── UserChannelAnalyticsController.java (신규)
    ├── UserRoiAnalyticsController.java (신규)
    └── UserTimelineAnalyticsController.java (신규)
```

### 10.2 API 목록
| No | HTTP Method | Endpoint | 설명 |
|----|-------------|----------|------|
| 1 | GET | `/api/v1/users/{userId}/analytics` | 사용자 전체 성과 대시보드 |
| 2 | GET | `/api/v1/users/{userId}/analytics/channels` | 사용자 전체 채널별 성과 분석 |
| 3 | GET | `/api/v1/users/{userId}/analytics/roi` | 사용자 전체 ROI 상세 분석 |
| 4 | GET | `/api/v1/users/{userId}/analytics/timeline` | 사용자 전체 시간대별 참여 추이 |

---

**작성자**: AI Backend Developer
**검토자**: -
**승인자**: -
**버전**: 1.0
**최종 수정일**: 2025-10-28