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 구현)
• 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)