feat: 이메일 인증 기능 구현

.gitignore

@@ -46,4 +46,9 @@ src/main/generated/
 /.cursor/
 
 ### AntiGravity ###
-/.agent/
+/.agent/
+
+### claude ###
+/.claude/
+CLAUDE.md
+/.ai/

build.gradle

@@ -46,6 +46,9 @@ dependencies {
         exclude group: 'io.swagger.core.v3', module: 'swagger-annotations'
     }
 
+	implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
+	implementation 'software.amazon.awssdk:ses:2.29.46'
+
 	compileOnly 'org.projectlombok:lombok'
 
 	developmentOnly 'org.springframework.boot:spring-boot-devtools'
@@ -63,7 +66,7 @@ dependencies {
 	testImplementation 'org.springframework.boot:spring-boot-starter-test'
 	testImplementation 'org.springframework.security:spring-security-test'
 
-	testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
+    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
 }
 
 dependencyManagement {

src/main/java/com/dreamteam/alter/AlterApplication.java

@@ -4,10 +4,12 @@
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 import org.springframework.data.jpa.repository.config.EnableJpaAuditing;
 import org.springframework.retry.annotation.EnableRetry;
+import org.springframework.scheduling.annotation.EnableAsync;
 
 @SpringBootApplication
 @EnableJpaAuditing
 @EnableRetry
+@EnableAsync
 public class AlterApplication {
 
 	public static void main(String[] args) {

src/main/java/com/dreamteam/alter/adapter/inbound/general/email/dto/SendEmailVerificationCodeRequestDto.java

@@ -0,0 +1,20 @@
+package com.dreamteam.alter.adapter.inbound.general.email.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.Email;
+import jakarta.validation.constraints.NotBlank;
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+@Getter
+@NoArgsConstructor
+@AllArgsConstructor
+@Schema(description = "이메일 인증 코드 발송 요청")
+public class SendEmailVerificationCodeRequestDto {
+
+    @NotBlank
+    @Email
+    @Schema(description = "인증할 이메일 주소", example = "user@example.com")
+    private String email;
+}

src/main/java/com/dreamteam/alter/adapter/inbound/general/email/dto/VerifyEmailVerificationCodeRequestDto.java

@@ -0,0 +1,26 @@
+package com.dreamteam.alter.adapter.inbound.general.email.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.Email;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.Pattern;
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+@Getter
+@NoArgsConstructor
+@AllArgsConstructor
+@Schema(description = "이메일 인증 코드 검증 요청")
+public class VerifyEmailVerificationCodeRequestDto {
+
+    @NotBlank
+    @Email
+    @Schema(description = "인증할 이메일 주소", example = "user@example.com")
+    private String email;
+
+    @NotBlank
+    @Pattern(regexp = "^[0-9]{6}$", message = "인증 코드는 6자리 숫자여야 합니다.")
+    @Schema(description = "수신한 인증 코드 6자리", example = "123456")
+    private String code;
+}

src/main/java/com/dreamteam/alter/adapter/inbound/general/email/dto/VerifyEmailVerificationCodeResponseDto.java

@@ -0,0 +1,16 @@
+package com.dreamteam.alter.adapter.inbound.general.email.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+@Getter
+@NoArgsConstructor
+@AllArgsConstructor
+@Schema(description = "이메일 인증 성공 응답")
+public class VerifyEmailVerificationCodeResponseDto {
+
+    @Schema(description = "이메일 인증 세션 토큰", example = "a1b2c3d4-e5f6-4a09-8c13-1b2a3d4e5f6a")
+    private String verificationToken;
+}

src/main/java/com/dreamteam/alter/adapter/inbound/general/user/controller/UserPublicController.java

@@ -55,6 +55,7 @@ public class UserPublicController implements UserPublicControllerSpec {
     @Resource(name = "resetPassword")
     private final ResetPasswordUseCase resetPassword;
 
+
     @Override
     @PostMapping("/signup-session")
     public ResponseEntity<CommonApiResponse<CreateSignupSessionResponseDto>> createSignupSession(
@@ -135,4 +136,5 @@ public ResponseEntity<CommonApiResponse<Void>> resetPassword(
         resetPassword.execute(request);
         return ResponseEntity.ok(CommonApiResponse.empty());
     }
+
 }

src/main/java/com/dreamteam/alter/adapter/inbound/general/user/controller/UserPublicControllerSpec.java

@@ -62,10 +62,6 @@ public interface UserPublicControllerSpec {
                 mediaType = "application/json",
                 schema = @Schema(implementation = ErrorResponse.class),
                 examples = {
-                    @ExampleObject(
-                        name = "이메일 중복",
-                        value = "{\"code\" : \"A004\"}"
-                    ),
                     @ExampleObject(
                         name = "소셜 플랫폼 ID 중복",
                         value = "{\"code\" : \"A005\"}"
@@ -139,6 +135,10 @@ public interface UserPublicControllerSpec {
                     @ExampleObject(
                         name = "존재하지 않는 사용자",
                         value = "{\"success\": false, \"code\" : \"B011\", \"message\" : \"존재하지 않는 사용자입니다.\"}"
+                    ),
+                    @ExampleObject(
+                        name = "이메일 미등록 사용자",
+                        value = "{\"success\": false, \"code\" : \"A015\", \"message\" : \"이메일이 등록되지 않은 사용자입니다.\"}"
                     )
                 }))
     })
@@ -171,6 +171,10 @@ public interface UserPublicControllerSpec {
                     @ExampleObject(
                         name = "존재하지 않는 사용자",
                         value = "{\"success\": false, \"code\" : \"B011\", \"message\" : \"존재하지 않는 사용자입니다.\"}"
+                    ),
+                    @ExampleObject(
+                        name = "이메일 미등록 사용자",
+                        value = "{\"success\": false, \"code\" : \"A015\", \"message\" : \"이메일이 등록되지 않은 사용자입니다.\"}"
                     )
                 }))
     })

src/main/java/com/dreamteam/alter/adapter/inbound/general/user/controller/UserSelfController.java

@@ -1,11 +1,17 @@
 package com.dreamteam.alter.adapter.inbound.general.user.controller;
 
 import com.dreamteam.alter.adapter.inbound.common.dto.CommonApiResponse;
+import com.dreamteam.alter.adapter.inbound.general.email.dto.SendEmailVerificationCodeRequestDto;
+import com.dreamteam.alter.adapter.inbound.general.email.dto.VerifyEmailVerificationCodeRequestDto;
+import com.dreamteam.alter.adapter.inbound.general.email.dto.VerifyEmailVerificationCodeResponseDto;
 import com.dreamteam.alter.adapter.inbound.general.user.dto.*;
 import com.dreamteam.alter.application.aop.AppActionContext;
+import com.dreamteam.alter.domain.email.port.inbound.SendEmailVerificationCodeUseCase;
+import com.dreamteam.alter.domain.email.port.inbound.VerifyEmailVerificationCodeUseCase;
 import com.dreamteam.alter.domain.user.context.AppActor;
 import com.dreamteam.alter.domain.user.port.inbound.*;
 import jakarta.annotation.Resource;
+import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.access.prepost.PreAuthorize;
@@ -39,6 +45,21 @@ public class UserSelfController implements UserSelfControllerSpec {
     @Resource(name = "deleteUserSelfCertificate")
     private final DeleteUserSelfCertificateUseCase deleteUserSelfCertificate;
 
+    @Resource(name = "registerEmail")
+    private final RegisterEmailUseCase registerEmail;
+
+    @Resource(name = "updateEmail")
+    private final UpdateEmailUseCase updateEmail;
+
+    @Resource(name = "removeEmail")
+    private final RemoveEmailUseCase removeEmail;
+
+    @Resource(name = "sendEmailVerificationCode")
+    private final SendEmailVerificationCodeUseCase sendEmailVerificationCode;
+
+    @Resource(name = "verifyEmailVerificationCode")
+    private final VerifyEmailVerificationCodeUseCase verifyEmailVerificationCode;
+
     @Override
     @GetMapping
     public ResponseEntity<CommonApiResponse<UserSelfInfoResponseDto>> getUserSelfInfo() {
@@ -99,4 +120,52 @@ public ResponseEntity<CommonApiResponse<Void>> deleteUserSelfCertificate(
         return ResponseEntity.ok(CommonApiResponse.empty());
     }
 
+    @Override
+    @PostMapping("/email")
+    public ResponseEntity<CommonApiResponse<Void>> registerEmail(
+        @Valid @RequestBody RegisterEmailRequestDto request
+    ) {
+        AppActor actor = AppActionContext.getInstance().getActor();
+
+        registerEmail.execute(actor, request.getEmailVerificationSessionId());
+        return ResponseEntity.ok(CommonApiResponse.empty());
+    }
+
+    @Override
+    @PutMapping("/email")
+    public ResponseEntity<CommonApiResponse<Void>> updateEmail(
+        @Valid @RequestBody RegisterEmailRequestDto request
+    ) {
+        AppActor actor = AppActionContext.getInstance().getActor();
+
+        updateEmail.execute(actor, request.getEmailVerificationSessionId());
+        return ResponseEntity.ok(CommonApiResponse.empty());
+    }
+
+    @Override
+    @DeleteMapping("/email")
+    public ResponseEntity<CommonApiResponse<Void>> removeEmail() {
+        AppActor actor = AppActionContext.getInstance().getActor();
+
+        removeEmail.execute(actor);
+        return ResponseEntity.ok(CommonApiResponse.empty());
+    }
+
+    @Override
+    @PostMapping("/email/send")
+    public ResponseEntity<CommonApiResponse<Void>> sendVerificationCode(
+            @Valid @RequestBody SendEmailVerificationCodeRequestDto request
+    ) {
+        sendEmailVerificationCode.execute(request);
+        return ResponseEntity.ok(CommonApiResponse.empty());
+    }
+
+    @Override
+    @PostMapping("/email/verify")
+    public ResponseEntity<CommonApiResponse<VerifyEmailVerificationCodeResponseDto>> verifyVerificationCode(
+            @Valid @RequestBody VerifyEmailVerificationCodeRequestDto request
+    ) {
+        return ResponseEntity.ok(CommonApiResponse.of(verifyEmailVerificationCode.execute(request)));
+    }
+
 }