[FEAT] 소셜 로그인 및 인증 api 구현

src/main/java/com/mr/domain/auth/controller/AuthController.java

@@ -1,35 +1,95 @@
 package com.mr.domain.auth.controller;
 
-import com.mr.domain.auth.dto.AuthRequestDTO;
-import com.mr.domain.auth.dto.AuthResponseDTO;
+import com.mr.domain.auth.dto.req.AuthRequestDTO;
+import com.mr.domain.auth.dto.res.AuthResponseDTO;
 import com.mr.domain.auth.entity.enums.SocialType;
 import com.mr.domain.auth.service.AuthService;
 import com.mr.global.apipayload.ApiResponse;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.security.SecurityRequirements;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
-import org.springframework.context.annotation.Profile;
+import org.springframework.http.HttpHeaders;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestHeader;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
+import com.mr.global.security.SecurityUtil;
 
+@Tag(name = "Auth API", description = "인증 및 소셜 로그인 관련 API")
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/auth")
-@Profile({"local", "dev"})
 public class AuthController {
 
     private final AuthService authService;
 
     @SecurityRequirements
+    @Operation(
+            summary = "소셜 로그인 / 회원가입 API",
+            description = "카카오 및 구글 OAuth Access Token을 받아 로그인을 진행하고, 서비스 전용 JWT 토큰을 발급합니다."
+    )
     @PostMapping("/login/{socialType}")
     public ApiResponse<AuthResponseDTO.LoginResponse> socialLogin(
+            @Parameter(description = "소셜 로그인 제공자 (KAKAO, GOOGLE)", example = "KAKAO")
             @PathVariable(name = "socialType") SocialType socialType,
-            @RequestBody @Valid AuthRequestDTO.SocialLoginRequest request
+            @RequestBody @Valid AuthRequestDTO.SocialLoginRequest request,
+            @RequestHeader(value = HttpHeaders.USER_AGENT, defaultValue = "Unknown Device") String deviceInfo
     ) {
-        AuthResponseDTO.LoginResponse response = authService.socialLogin(socialType, request.accessToken());
+        AuthResponseDTO.LoginResponse response = authService.socialLogin(socialType, request.accessToken(), deviceInfo);
         return ApiResponse.onSuccess(response);
     }
+    @SecurityRequirements
+    @Operation(summary = "토큰 재발급 API", description = "만료된 Access Token을 Refresh Token을 이용해 재발급합니다.")
+    @PostMapping("/reissue")
+    public ApiResponse<AuthResponseDTO.TokenInfo> reissue(
+            @RequestBody @Valid AuthRequestDTO.TokenRefreshRequest request
+    ) {
+        AuthResponseDTO.TokenInfo tokenInfo = authService.reissueToken(request.refreshToken());
+        return ApiResponse.onSuccess(tokenInfo);
+    }
+
+    @Operation(
+            summary = "소셜 계정 추가 연동 API",
+            description = "현재 로그인된 사용자의 계정에 새로운 소셜 계정(카카오/구글)을 추가로 연동합니다."
+    )
+    @PostMapping("/link/{socialType}")
+    public ApiResponse<AuthResponseDTO.TokenInfo> linkSocialAccount(
+            @Parameter(description = "연동할 소셜 제공자 (KAKAO, GOOGLE)", example = "GOOGLE")
+            @PathVariable(name = "socialType") SocialType socialType,
+            @RequestBody @Valid AuthRequestDTO.SocialLoginRequest request,
+            @RequestHeader(value = HttpHeaders.USER_AGENT, defaultValue = "Unknown Device") String deviceInfo
+    ) {
+        Long userId = SecurityUtil.getCurrentUserId();
+        AuthResponseDTO.TokenInfo tokenInfo = authService.linkSocialAccount(userId, socialType, request.accessToken(), deviceInfo);
+        return ApiResponse.onSuccess(tokenInfo);
+    }
+
+    @Operation(
+            summary = "로그아웃 API",
+            description = "현재 요청 기기의 Refresh Token 세션을 선택적으로 만료 처리합니다."
+    )
+    @PostMapping("/logout")
+    public ApiResponse<Void> logout(
+            @RequestBody @Valid AuthRequestDTO.LogoutRequest request
+    ) {
+        Long userId = SecurityUtil.getCurrentUserId();
+        authService.logout(userId, request.refreshToken());
+        return ApiResponse.onSuccess(null);
+    }
+
+    @Operation(
+            summary = "회원 탈퇴 API",
+            description = "사용자 계정을 탈퇴 처리하고 저장된 소셜 인증 정보 및 Refresh Token 세션을 완전히 삭제합니다."
+    )
+    @PostMapping("/withdraw")
+    public ApiResponse<Void> withdraw() {
+        Long userId = SecurityUtil.getCurrentUserId();
+        authService.withdraw(userId);
+        return ApiResponse.onSuccess(null);
+    }
 }

src/main/java/com/mr/domain/auth/dto/OAuthUserInfo.java

@@ -0,0 +1,9 @@
+package com.mr.domain.auth.dto;
+
+import lombok.Builder;
+
+@Builder
+public record OAuthUserInfo(
+        String socialId,
+        String profileImgUrl
+) {}

src/main/java/com/mr/domain/auth/dto/AuthRequestDTO.java → src/main/java/com/mr/domain/auth/dto/req/AuthRequestDTO.java

@@ -1,4 +1,4 @@
-package com.mr.domain.auth.dto;
+package com.mr.domain.auth.dto.req;
 
 import jakarta.validation.constraints.NotBlank;
 
@@ -13,4 +13,9 @@ public record TokenRefreshRequest(
             @NotBlank(message = "Refresh Token은 필수 입력값입니다.")
             String refreshToken
     ) {}
+
+    public record LogoutRequest(
+            @NotBlank(message = "Refresh Token은 필수 입력값입니다.")
+            String refreshToken
+    ) {}
 }

src/main/java/com/mr/domain/auth/dto/AuthResponseDTO.java → src/main/java/com/mr/domain/auth/dto/res/AuthResponseDTO.java

@@ -1,4 +1,4 @@
-package com.mr.domain.auth.dto;
+package com.mr.domain.auth.dto.res;
 
 import lombok.Builder;
 
@@ -11,11 +11,19 @@ public record TokenResponse(
             Long accessTokenExpiresInSeconds
     ) {}
 
+    @Builder
+    public record TokenInfo(
+            String accessToken,
+            String refreshToken,
+            Long accessTokenExpiresInSeconds
+    ) {}
+
     @Builder
     public record LoginResponse(
             Long userId,
             String nickname,
             boolean isNewUser,
+            boolean isOnboardingCompleted,
             TokenResponse tokenInfo
     ) {}
 }

src/main/java/com/mr/domain/auth/dto/res/GoogleUserResponse.java

@@ -0,0 +1,9 @@
+package com.mr.domain.auth.dto.res;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+public record GoogleUserResponse(
+        String id,
+        String picture,
+        String email
+) {}

src/main/java/com/mr/domain/auth/dto/res/KakaoUserResponse.java

@@ -0,0 +1,18 @@
+package com.mr.domain.auth.dto.res;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+public record KakaoUserResponse(
+        Long id,
+        @JsonProperty("kakao_account")
+        KakaoAccount kakaoAccount
+) {
+    public record KakaoAccount(
+            Profile profile
+    ) {}
+
+    public record Profile(
+            @JsonProperty("profile_image_url")
+            String profileImageUrl
+    ) {}
+}

src/main/java/com/mr/domain/auth/entity/SocialAuth.java

@@ -1,20 +1,19 @@
 package com.mr.domain.auth.entity;
 
-import com.mr.domain.auth.exception.AuthErrorStatus;
 import com.mr.domain.auth.entity.enums.SocialType;
+import com.mr.domain.auth.exception.AuthErrorStatus;
+import com.mr.domain.user.entity.User;
 import com.mr.global.apipayload.exception.GeneralException;
 import com.mr.global.entity.BaseCreatedEntity;
 import jakarta.persistence.*;
 import java.time.LocalDateTime;
-import java.time.ZoneId;
 import lombok.AccessLevel;
 import lombok.Builder;
 import lombok.Getter;
 import lombok.NoArgsConstructor;
 
 @Getter
 @Entity
-// TODO: 추후 User 도메인 완성 시 인덱스 추가
 @Table(
         name = "social_auth",
         uniqueConstraints = {
@@ -29,9 +28,9 @@ public class SocialAuth extends BaseCreatedEntity {
     @Column(name = "social_auth_id")
     private Long id;
 
-    // TODO: User연결 예정
-    @Column(name = "user_id", nullable = false)
-    private Long userId;
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "user_id", nullable = false)
+    private User user;
 
     @Enumerated(EnumType.STRING)
     @Column(name = "social_type", nullable = false, length = 20)
@@ -40,9 +39,6 @@ public class SocialAuth extends BaseCreatedEntity {
     @Column(name = "social_id", nullable = false, length = 100)
     private String socialId;
 
-    @Column(name = "refresh_token", length = 1000)
-    private String refreshToken;
-
     @Column(name = "refresh_token_hash", length = 64, unique = true)
     private String refreshTokenHash;
 
@@ -53,72 +49,91 @@ public class SocialAuth extends BaseCreatedEntity {
     private String deviceInfo;
 
     @Builder(access = AccessLevel.PRIVATE)
-    private SocialAuth(Long userId, SocialType socialType, String socialId, String refreshToken,
+    private SocialAuth(User user, SocialType socialType, String socialId,
                        String refreshTokenHash, LocalDateTime expiredAt, String deviceInfo) {
 
-        validateUserAccount(userId);
-        validateUserAccount(socialType);
-        validateUserAccount(socialId);
+        validateUser(user);
+        validateSocialType(socialType);
+        validateSocialId(socialId);
 
-        this.userId = userId;
+        this.user = user;
         this.socialType = socialType;
         this.socialId = socialId;
-        this.refreshToken = refreshToken;
         this.refreshTokenHash = refreshTokenHash;
         this.expiredAt = expiredAt;
-        this.deviceInfo = deviceInfo;
+        this.deviceInfo = sanitizeDeviceInfo(deviceInfo);
+    }
+
+    private static String sanitizeDeviceInfo(String deviceInfo) {
+        if (deviceInfo == null || deviceInfo.isBlank()) {
+            return "Unknown Device";
+        }
+        String trimmed = deviceInfo.trim();
+        return trimmed.length() > 255 ? trimmed.substring(0, 255) : trimmed;
     }
 
-    public static SocialAuth create(Long userId, SocialType socialType, String socialId,
-                                    String encryptedToken, String tokenHash, LocalDateTime expiredAt, String deviceInfo) {
+    public static SocialAuth create(User user, SocialType socialType, String socialId,
+                                    String tokenHash, LocalDateTime expiredAt, String deviceInfo) {
 
-        validateTokenValue(encryptedToken);
         validateTokenValue(tokenHash);
         validateExpiryTime(expiredAt);
 
         return SocialAuth.builder()
-                .userId(userId)
+                .user(user)
                 .socialType(socialType)
                 .socialId(socialId)
-                .refreshToken(encryptedToken)
                 .refreshTokenHash(tokenHash)
                 .expiredAt(expiredAt)
                 .deviceInfo(deviceInfo)
                 .build();
     }
 
-    private static void validateUserAccount(Object value) {
-        if (value == null || (value instanceof String && ((String) value).trim().isEmpty())) {
+    private static void validateUser(User user) {
+        if (user == null) {
+            throw new GeneralException(AuthErrorStatus.INVALID_AUTH_REQUEST);
+        }
+    }
+
+    private static void validateSocialType(SocialType socialType) {
+        if (socialType == null) {
+            throw new GeneralException(AuthErrorStatus.INVALID_AUTH_REQUEST);
+        }
+    }
+
+    private static void validateSocialId(String socialId) {
+        if (socialId == null || socialId.isBlank()) {
             throw new GeneralException(AuthErrorStatus.INVALID_AUTH_REQUEST);
         }
     }
 
     private static void validateTokenValue(String token) {
-        if (token == null || token.trim().isEmpty()) {
+        if (token == null || token.isBlank()) {
             throw new GeneralException(AuthErrorStatus.TOKEN_MISSING);
         }
     }
 
     private static void validateExpiryTime(LocalDateTime expiredAt) {
-        if (expiredAt == null || !expiredAt.isAfter(LocalDateTime.now(ZoneId.of("Asia/Seoul")))) {
+        if (expiredAt == null || !expiredAt.isAfter(LocalDateTime.now())) {
             throw new GeneralException(AuthErrorStatus.INVALID_TOKEN_EXPIRY);
         }
     }
 
-    public void updateRefreshToken(String encryptedToken, String tokenHash, LocalDateTime newExpiredAt, String deviceInfo) {
-        validateTokenValue(encryptedToken);
+    public void updateRefreshToken(String tokenHash, LocalDateTime newExpiredAt, String deviceInfo) {
         validateTokenValue(tokenHash);
         validateExpiryTime(newExpiredAt);
 
-        this.refreshToken = encryptedToken;
         this.refreshTokenHash = tokenHash;
         this.expiredAt = newExpiredAt;
-        this.deviceInfo = deviceInfo;
+        this.deviceInfo = sanitizeDeviceInfo(deviceInfo);
     }
 
     public void expireToken() {
-        this.refreshToken = null;
         this.refreshTokenHash = null;
-        this.expiredAt = LocalDateTime.now(ZoneId.of("Asia/Seoul")); // null 대신 현재 시각 기록
+        this.deviceInfo = null;
+        this.expiredAt = LocalDateTime.now();
+    }
+
+    public boolean isExpired() {
+        return this.expiredAt == null || !this.expiredAt.isAfter(LocalDateTime.now());
     }
 }

src/main/java/com/mr/domain/auth/entity/enums/SocialType.java

@@ -1,6 +1,6 @@
 package com.mr.domain.auth.entity.enums;
 
 public enum SocialType {
-    kakao,
-    google
+    KAKAO,
+    GOOGLE
 }

src/main/java/com/mr/domain/auth/exception/AuthErrorStatus.java

@@ -22,8 +22,12 @@ public enum AuthErrorStatus implements BaseCode {
     // 리소스 부재
     SOCIAL_AUTH_NOT_FOUND(HttpStatus.NOT_FOUND, "AUTH_404_01", "해당 사용자의 소셜 인증 기록을 찾을 수 없습니다."),
 
-    // 데이터 무결성ㅇ
-    ALREADY_LINKED_SOCIAL_ACCOUNT(HttpStatus.CONFLICT, "AUTH_409_01", "이미 다른 계정에 연동되어 있는 소셜 계정입니다.");
+    // 데이터 무결성
+    ALREADY_LINKED_SOCIAL_ACCOUNT(HttpStatus.CONFLICT, "AUTH_409_01", "이미 다른 계정에 연동되어 있는 소셜 계정입니다."),
+
+    // 외부 소셜 연동 오류
+    OAUTH_CLIENT_ERROR(HttpStatus.UNAUTHORIZED, "AUTH_401_04", "소셜 로그인 인증에 실패했거나 유효하지 않은 소셜 액세스 토큰입니다."),
+    OAUTH_SERVER_ERROR(HttpStatus.SERVICE_UNAVAILABLE, "AUTH_503_01", "소셜 인증 제공자(카카오/구글) 서버와의 통신에 실패했습니다.");
 
     private final HttpStatus status;
     private final String code;