kt-event-marketing/design/backend/class/participation-service-result.md

# Participation Service 클래스 설계 결과

## 📋 개요

**Backend Developer (최수연 "아키텍처")**

Participation Service의 클래스 설계를 완료했습니다. Layered Architecture 패턴을 적용하여 이벤트 참여와 당첨자 추첨 기능을 담당하는 서비스를 설계했습니다.

## 🎯 설계 원칙 준수

### 1. 아키텍처 패턴
- ✅ **Layered Architecture** 적용
  - Presentation Layer (Controller)
  - Application Layer (Service, DTO)
  - Domain Layer (Entity, Repository)
  - Infrastructure Layer (Kafka, Config)

### 2. 공통 컴포넌트 참조
- ✅ BaseTimeEntity 상속 (Participant, DrawLog)
- ✅ ApiResponse<T> 사용 (모든 API 응답)
- ✅ PageResponse<T> 사용 (페이징 응답)
- ✅ BusinessException 상속 (ParticipationException)
- ✅ ErrorCode 인터페이스 사용

### 3. 유저스토리 및 API 매핑
- ✅ API 설계서와 일관성 유지
- ✅ Controller 메소드와 API 경로 매핑 완료

## 📦 패키지 구조

```
com.kt.event.participation/
├── presentation/
│   └── controller/
│       ├── ParticipationController.java    # 이벤트 참여 API
│       ├── WinnerController.java           # 당첨자 추첨 API
│       └── DebugController.java            # 디버그 API
│
├── application/
│   ├── service/
│   │   ├── ParticipationService.java       # 참여 비즈니스 로직
│   │   └── WinnerDrawService.java          # 추첨 비즈니스 로직
│   └── dto/
│       ├── ParticipationRequest.java       # 참여 요청 DTO
│       ├── ParticipationResponse.java      # 참여 응답 DTO
│       ├── DrawWinnersRequest.java         # 추첨 요청 DTO
│       └── DrawWinnersResponse.java        # 추첨 응답 DTO
│
├── domain/
│   ├── participant/
│   │   ├── Participant.java                # 참여자 엔티티
│   │   └── ParticipantRepository.java      # 참여자 레포지토리
│   └── draw/
│       ├── DrawLog.java                    # 추첨 로그 엔티티
│       └── DrawLogRepository.java          # 추첨 로그 레포지토리
│
├── exception/
│   └── ParticipationException.java         # 참여 관련 예외 (7개 서브 클래스)
│
└── infrastructure/
    ├── kafka/
    │   ├── KafkaProducerService.java       # Kafka 프로듀서
    │   └── event/
    │       └── ParticipantRegisteredEvent.java  # 참여자 등록 이벤트
    └── config/
        └── SecurityConfig.java             # 보안 설정
```

## 🏗️ 주요 컴포넌트

### Presentation Layer

#### ParticipationController
- **POST** `/events/{eventId}/participate` - 이벤트 참여
- **GET** `/events/{eventId}/participants` - 참여자 목록 조회
- **GET** `/events/{eventId}/participants/{participantId}` - 참여자 상세 조회

#### WinnerController
- **POST** `/events/{eventId}/draw-winners` - 당첨자 추첨
- **GET** `/events/{eventId}/winners` - 당첨자 목록 조회

### Application Layer

#### ParticipationService
**핵심 비즈니스 로직:**
- 이벤트 참여 처리
- 중복 참여 체크 (eventId + phoneNumber)
- 참여자 ID 자동 생성 (prt_YYYYMMDD_XXX)
- Kafka 이벤트 발행
- 참여자 목록/상세 조회

#### WinnerDrawService
**핵심 비즈니스 로직:**
- 당첨자 추첨 실행
- 가중치 추첨 풀 생성 (매장 방문 5배 보너스)
- 추첨 로그 저장 (재추첨 방지)
- 당첨자 목록 조회

### Domain Layer

#### Participant 엔티티
- 참여자 정보 관리
- 중복 방지 (UK: event_id + phone_number)
- 매장 방문 보너스 (5배 응모권)
- 당첨자 상태 관리 (isWinner, winnerRank, wonAt)
- 도메인 로직:
  - `generateParticipantId()` - 참여자 ID 생성
  - `calculateBonusEntries()` - 보너스 응모권 계산
  - `markAsWinner()` - 당첨자 설정

#### DrawLog 엔티티
- 추첨 이력 관리
- 재추첨 방지 (eventId당 1회만 추첨)
- 추첨 알고리즘 기록 (WEIGHTED_RANDOM)
- 추첨 메타데이터 (총 참여자, 당첨자 수, 보너스 적용 여부)

### Infrastructure Layer

#### KafkaProducerService
- **Topic**: `participant-registered-events`
- 참여자 등록 이벤트 발행
- 비동기 처리로 메인 로직 영향 최소화

## 🔍 예외 처리

### ParticipationException 계층
1. **DuplicateParticipationException** - 중복 참여
2. **EventNotFoundException** - 이벤트 없음
3. **EventNotActiveException** - 이벤트 비활성
4. **ParticipantNotFoundException** - 참여자 없음
5. **AlreadyDrawnException** - 이미 추첨 완료
6. **InsufficientParticipantsException** - 참여자 부족
7. **NoWinnersYetException** - 당첨자 미추첨

## 🔗 관계 설계

### 상속 관계
```
BaseTimeEntity
├── Participant (domain.participant)
└── DrawLog (domain.draw)

BusinessException
└── ParticipationException
    ├── DuplicateParticipationException
    ├── EventNotFoundException
    ├── EventNotActiveException
    ├── ParticipantNotFoundException
    ├── AlreadyDrawnException
    ├── InsufficientParticipantsException
    └── NoWinnersYetException
```

### 의존 관계
```
ParticipationController → ParticipationService
WinnerController → WinnerDrawService

ParticipationService → ParticipantRepository
ParticipationService → KafkaProducerService

WinnerDrawService → ParticipantRepository
WinnerDrawService → DrawLogRepository

KafkaProducerService → ParticipantRegisteredEvent
```

## 📊 데이터 처리 흐름

### 이벤트 참여 흐름
```
1. 클라이언트 → POST /events/{eventId}/participate
2. ParticipationController → ParticipationService.participate()
3. 중복 참여 체크 (existsByEventIdAndPhoneNumber)
4. 참여자 ID 생성 (findMaxSequenceByDatePrefix)
5. Participant 엔티티 생성 및 저장
6. Kafka 이벤트 발행 (ParticipantRegisteredEvent)
7. ParticipationResponse 반환
```

### 당첨자 추첨 흐름
```
1. 클라이언트 → POST /events/{eventId}/draw-winners
2. WinnerController → WinnerDrawService.drawWinners()
3. 추첨 완료 여부 확인 (existsByEventId)
4. 참여자 목록 조회 (findByEventIdAndIsWinnerFalse)
5. 가중치 추첨 풀 생성 (createDrawPool)
6. 무작위 셔플 및 당첨자 선정
7. 당첨자 상태 업데이트 (markAsWinner)
8. DrawLog 저장
9. DrawWinnersResponse 반환
```

## ✅ 검증 결과

### PlantUML 문법 검사
```
✓ participation-service.puml - No syntax errors
✓ participation-service-simple.puml - No syntax errors
```

### 설계 검증 항목
- ✅ 유저스토리와 매칭
- ✅ API 설계서와 일관성
- ✅ 내부 시퀀스 설계서와 일관성
- ✅ Layered Architecture 패턴 적용
- ✅ 공통 컴포넌트 참조
- ✅ 클래스 프로퍼티/메소드 명시
- ✅ 클래스 간 관계 표현
- ✅ API-Controller 메소드 매핑

## 📁 산출물

### 생성된 파일
1. **design/backend/class/participation-service.puml**
   - 상세 클래스 다이어그램
   - 모든 프로퍼티와 메소드 포함
   - 관계 및 의존성 상세 표현

2. **design/backend/class/participation-service-simple.puml**
   - 요약 클래스 다이어그램
   - 패키지 구조 중심
   - API 매핑 정보 포함

## 🎯 특징 및 강점

### 1. 데이터 중심 설계
- 중복 참여 방지 (DB 제약조건)
- 참여자 ID 자동 생성
- 추첨 이력 관리

### 2. 단순한 비즈니스 로직
- 복잡한 외부 의존성 없음
- 자체 완결적인 도메인 로직
- 명확한 책임 분리

### 3. 이벤트 기반 통합
- Kafka를 통한 느슨한 결합
- 비동기 이벤트 발행
- 서비스 장애 격리

### 4. 가중치 추첨 알고리즘
- 매장 방문 보너스 (5배 응모권)
- 공정한 무작위 추첨
- 추첨 이력 관리

## 🔄 다음 단계

1. ✅ **클래스 설계 완료**
2. 🔜 **데이터베이스 설계** - ERD 작성 필요
3. 🔜 **백엔드 개발** - 실제 코드 구현
4. 🔜 **단위 테스트** - 테스트 코드 작성

---

**작성자**: Backend Developer (최수연 "아키텍처")
**작성일**: 2025-10-29
**설계 패턴**: Layered Architecture
**검증 상태**: ✅ 완료