hgzero/develop/dev/package-structure-notification.md

# Notification Service - 패키지 구조도

## 아키텍처 패턴
- **Layered Architecture**: 단순하고 명확한 계층 구조

## 패키지 구조

```
notification/
└── src/
    └── main/
        ├── java/
        │   └── com/
        │       └── unicorn/
        │           └── hgzero/
        │               └── notification/
        │                   ├── NotificationApplication.java
        │                   │
        │                   ├── domain/                      # Domain Layer
        │                   │   ├── Notification.java        # 알림 Entity
        │                   │   ├── NotificationRecipient.java  # 수신자 Entity
        │                   │   └── NotificationSetting.java # 알림 설정 Entity
        │                   │
        │                   ├── repository/                  # Data Access Layer
        │                   │   ├── NotificationRepository.java
        │                   │   ├── NotificationRecipientRepository.java
        │                   │   └── NotificationSettingRepository.java
        │                   │
        │                   ├── service/                     # Business Logic Layer
        │                   │   ├── NotificationService.java # 알림 비즈니스 로직
        │                   │   ├── EmailTemplateService.java # 이메일 템플릿 렌더링
        │                   │   └── EmailClient.java        # 이메일 발송 클라이언트
        │                   │
        │                   ├── controller/                  # Presentation Layer
        │                   │   ├── NotificationController.java # Public API
        │                   │   └── NotificationSettingsController.java # 설정 API
        │                   │
        │                   ├── event/                       # Event Handler Layer
        │                   │   ├── EventHandler.java       # Event Hub 이벤트 핸들러
        │                   │   ├── event/
        │                   │   │   ├── MeetingCreatedEvent.java  # 회의 생성 이벤트
        │                   │   │   └── TodoAssignedEvent.java    # Todo 할당 이벤트
        │                   │   └── processor/
        │                   │       └── EventProcessorService.java # Processor 라이프사이클
        │                   │
        │                   ├── dto/                         # Data Transfer Objects
        │                   │   ├── request/
        │                   │   │   ├── SendNotificationRequest.java
        │                   │   │   └── UpdateSettingsRequest.java
        │                   │   └── response/
        │                   │       ├── NotificationResponse.java
        │                   │       ├── NotificationListResponse.java
        │                   │       └── SettingsResponse.java
        │                   │
        │                   ├── config/                      # Configuration Layer
        │                   │   ├── EventHubConfig.java     # Event Hub 설정
        │                   │   ├── BlobStorageConfig.java  # Blob Storage 설정
        │                   │   ├── RetryConfig.java        # 재시도 정책 설정
        │                   │   ├── SecurityConfig.java     # Spring Security 설정
        │                   │   ├── SwaggerConfig.java      # Swagger 설정
        │                   │   └── EmailConfig.java        # Email 설정
        │                   │
        │                   └── exception/                   # Exception Handling
        │                       ├── GlobalExceptionHandler.java
        │                       ├── NotificationException.java
        │                       └── EventProcessingException.java
        │
        └── resources/
            ├── application.yml                             # 메인 설정 파일
            ├── application-dev.yml                         # 개발 환경 설정
            ├── application-prod.yml                        # 운영 환경 설정
            └── templates/                                  # Email Templates
                ├── meeting-invitation.html                 # 회의 초대 템플릿
                ├── todo-assigned.html                      # Todo 할당 템플릿
                └── reminder.html                           # 리마인더 템플릿
```

## 주요 클래스 역할

### Domain Layer
- **Notification**: 알림 정보 엔티티 (알림ID, 유형, 상태, 발송일시)
- **NotificationRecipient**: 수신자별 알림 상태 (발송완료, 실패, 재시도)
- **NotificationSetting**: 사용자별 알림 설정 (채널, 유형, 방해금지 시간대)

### Repository Layer
- **NotificationRepository**: 알림 이력 조회/저장
- **NotificationRecipientRepository**: 수신자별 상태 관리
- **NotificationSettingRepository**: 알림 설정 관리

### Service Layer
- **NotificationService**: 알림 발송 비즈니스 로직, 중복 방지, 재시도 관리
- **EmailTemplateService**: Thymeleaf 템플릿 렌더링
- **EmailClient**: SMTP 이메일 발송, 에러 처리

### Controller Layer
- **NotificationController**: 알림 발송 API, 알림 이력 조회 API
- **NotificationSettingsController**: 알림 설정 조회/업데이트 API

### Event Handler Layer
- **EventHandler**: Event Hub 이벤트 수신 및 처리 (Consumer<EventContext> 구현)
- **EventProcessorService**: EventProcessorClient 라이프사이클 관리
- **MeetingCreatedEvent**: 회의 생성 이벤트 DTO
- **TodoAssignedEvent**: Todo 할당 이벤트 DTO

### Config Layer
- **EventHubConfig**: EventProcessorClient Bean 생성, CheckpointStore 설정
- **BlobStorageConfig**: Azure Blob Storage 연결 설정
- **RetryConfig**: @EnableRetry, ExponentialBackOffPolicy 설정
- **SecurityConfig**: JWT 인증, CORS 설정
- **SwaggerConfig**: OpenAPI 문서화 설정
- **EmailConfig**: JavaMailSender 설정

## 의존성 흐름
```
Controller → Service → Repository → Entity
              ↓
        EmailClient
              ↓
     EmailTemplateService

EventHandler → Service → Repository
```

## 기술 스택
- **Framework**: Spring Boot 3.3.0, Java 21
- **Database**: PostgreSQL (JPA/Hibernate)
- **Messaging**: Azure Event Hubs
- **Storage**: Azure Blob Storage (Checkpoint)
- **Email**: Spring Mail (SMTP)
- **Template**: Thymeleaf
- **Retry**: Spring Retry
- **Security**: Spring Security + JWT
- **Documentation**: SpringDoc OpenAPI

## 특징
1. **Layered Architecture**: 계층 분리로 명확한 역할과 책임
2. **Event-Driven**: Azure Event Hubs 기반 비동기 처리
3. **Retry Mechanism**: Exponential Backoff 기반 재시도
4. **Template Engine**: Thymeleaf로 동적 이메일 생성
5. **Idempotency**: 이벤트 ID 기반 중복 발송 방지
6. **Monitoring**: Actuator Health Check, Metrics

---

**작성일**: 2025-10-23
**작성자**: 준호 (Backend Developer)