feat : 유저 조회 기능 추가

gotcha-domain/src/main/java/gotcha_domain/user/User.java

@@ -58,8 +58,6 @@ public class User extends BaseTimeEntity {
     @Setter
     private LocalDateTime lastLogout;
 
-//    private Boolean isLocked; // UserStatus로 대체
-
     @Setter
     private int level;
 

gotcha-user/src/main/java/gotcha_user/service/UserService.java

@@ -12,6 +12,8 @@
 import gotcha_user.exceptionCode.UserExceptionCode;
 import gotcha_user.repository.UserRepository;
 import lombok.RequiredArgsConstructor;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.Pageable;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 
@@ -30,6 +32,11 @@ public class UserService {
 
     private static final long NICKNAME_VERIFY_EXPIRATION_TIME = 10 * 60;
 
+    @Transactional(readOnly = true)
+    public Page<User> findAllUsers(Pageable pageable) {
+        return userRepository.findAll(pageable);
+    }
+
     @Transactional(readOnly = true)
     public void checkNickname(String nickname) {
         if (userRepository.existsByNickname(nickname)) {

gotcha/src/main/java/Gotcha/domain/report/repository/UserReportRepository.java

@@ -15,4 +15,6 @@ public interface UserReportRepository extends JpaRepository<UserReport, Long> {
                 WHERE (:keyword IS NULL OR :keyword = '' OR LOWER(u.nickname) LIKE LOWER(CONCAT(:keyword, '%')))
             """)
     Page<UserReport> findAllByNickname(@Param("keyword") String keyword, Pageable pageable);
+
+    int countByUser_Id(Long userId);
 }

gotcha/src/main/java/Gotcha/domain/report/service/UserReportService.java

@@ -40,6 +40,10 @@ public void reportUser(UserReportReq reportReq, SecurityUserDetails userDetails)
         userReportRepository.save(userReport);
     }
 
+    public int countReportByUserId(Long userId) {
+        return userReportRepository.countByUser_Id(userId);
+    }
+
     public UserReport findUserReportById(Long reportId){
         return userReportRepository.findById(reportId)
                 .orElseThrow(() -> new CustomException(ReportExceptionCode.REPORT_NOT_FOUND));

gotcha/src/main/java/Gotcha/domain/sanction/api/SanctionApi.java

@@ -11,9 +11,10 @@
 import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
+import jakarta.validation.constraints.Min;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.RequestBody;
-
+import org.springframework.web.bind.annotation.RequestParam;
 
 
 @Tag(name = "[관리자 제재 API]", description = "관리자용 사용자 제재 관련 API")
@@ -95,4 +96,88 @@ public interface SanctionApi {
     ResponseEntity<SanctionRes> applySanction(
             @Valid @RequestBody SanctionReq sanctionReq,
             SecurityUserDetails userDetails);
+
+    @Operation(
+            summary = "사용자 목록 반환 API",
+            description = """
+    관리자 전용 사용자 조회 API입니다.
+
+    **조회 규칙**
+    - nickname 파라미터가 없는 경우: 전체 사용자 목록을 페이지 단위로 조회합니다.
+    - nickname 파라미터가 있는 경우: 해당 닉네임과 정확히 일치하는 유저 1명만 반환합니다.
+      - 이때 page 파라미터는 반드시 0이어야 합니다.
+    """
+    )
+    @SecurityRequirement(name = "bearerAuth")
+    @ApiResponses({
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "사용자 목록 조회 성공",
+                    content = @Content(
+                            mediaType = "application/json",
+                            examples = @ExampleObject(
+                                    value = """
+                                {
+                                    "content": [
+                                        {
+                                            "nickname": "다06fn6",
+                                            "createDate": "2025-09-03",
+                                            "email": "test30@naver.com",
+                                            "reportedCount": 1,
+                                            "warningCount": 1
+                                        }
+                                    ],
+                                    "page": {
+                                        "size": 6,
+                                        "number": 0,
+                                        "totalElements": 1,
+                                        "totalPages": 1
+                                    }
+                                }
+                                """
+                            )
+                    )
+            ),
+
+            @ApiResponse(
+                    responseCode = "400",
+                    description = "닉네임 검색 시 page 값이 0이 아닌 경우",
+                    content = @Content(
+                            mediaType = "application/json",
+                            examples = @ExampleObject(
+                                    value = """
+                                {
+                                    "code": "SANCTION-400-002",
+                                    "status": "BAD_REQUEST",
+                                    "message": "검색 시 page 값은 0이어야 합니다."
+                                }
+                                """
+                            )
+                    )
+            ),
+
+            @ApiResponse(
+                    responseCode = "404",
+                    description = "존재하지 않는 사용자 조회 시",
+                    content = @Content(
+                            mediaType = "application/json",
+                            examples = @ExampleObject(
+                                    value = """
+                                {
+                                    "code": "USER-404-001",
+                                    "status": "NOT_FOUND",
+                                    "message": "존재하지 않는 사용자입니다."
+                                }
+                                """
+                            )
+                    )
+            )
+    })
+
+    ResponseEntity<?> getUserList(
+            SecurityUserDetails userDetails,
+            @RequestParam(value = "nickname", required = false) String nickname,
+            @RequestParam(value = "page", defaultValue = "0") @Min(0) Integer page
+    );
+
 }

gotcha/src/main/java/Gotcha/domain/sanction/controller/SanctionController.java

@@ -5,37 +5,49 @@
 import Gotcha.domain.sanction.dto.SanctionRes;
 import Gotcha.domain.sanction.service.SanctionService;
 import gotcha_domain.auth.SecurityUserDetails;
+import gotcha_user.service.UserService;
 import jakarta.validation.Valid;
+import jakarta.validation.constraints.Min;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
 import java.security.Principal;
 
 @RestController
-@RequestMapping("/api/v1/admin/sanctions")
+@RequestMapping("/api/v1/admin")
 @RequiredArgsConstructor
 public class SanctionController implements SanctionApi {
-
     private final SanctionService sanctionService;
 
-
-    @PostMapping
+    @PostMapping("/sanctions")
     @PreAuthorize("hasRole('ADMIN')")
     public ResponseEntity<SanctionRes> applySanction(
             @Valid @RequestBody SanctionReq sanctionReq,
-       @AuthenticationPrincipal SecurityUserDetails userDetails) {
+            @AuthenticationPrincipal SecurityUserDetails userDetails) {
 
         String adminId = userDetails.getUuid();
 
         SanctionRes response = sanctionService.sanctionUser(sanctionReq, adminId);
 
         return ResponseEntity.status(HttpStatus.CREATED).body(response);
     }
+
+    @GetMapping("/user/list")
+    @PreAuthorize("hasRole('ADMIN')")
+    public ResponseEntity<?> getUserList(
+            @AuthenticationPrincipal SecurityUserDetails userDetails,
+            @RequestParam(value = "nickname", required = false) String nickname,
+            @RequestParam(value = "page", defaultValue = "0") @Min(0) Integer page
+    ) {
+        return ResponseEntity.ok(sanctionService.getSanctionUsers(nickname, page));
+    }
 }

gotcha/src/main/java/Gotcha/domain/sanction/dto/SanctionUserListRes.java

@@ -0,0 +1,12 @@
+package Gotcha.domain.sanction.dto;
+
+import java.time.LocalDate;
+
+public record SanctionUserListRes(
+        String nickname,
+        LocalDate createDate,
+        String email,
+        int reportedCount,
+        int warningCount
+) {
+}

gotcha/src/main/java/Gotcha/domain/sanction/exception/SanctionExceptionCode.java

@@ -6,7 +6,8 @@
 
 @AllArgsConstructor
 public enum SanctionExceptionCode implements ExceptionCode {
-    NOT_SUSPENDED_USER(HttpStatus.BAD_REQUEST, "SANCTION-400-001", "해당 유저는 정지 상태가 아닙니다.");
+    NOT_SUSPENDED_USER(HttpStatus.BAD_REQUEST, "SANCTION-400-001", "해당 유저는 정지 상태가 아닙니다."),
+    INVALID_PAGE_FOR_SEARCH(HttpStatus.BAD_REQUEST, "SANCTION-400-002", "검색 시 page 값은 0이어야 합니다.");
 
     private final HttpStatus status;
     private final String code;

gotcha/src/main/java/Gotcha/domain/sanction/service/SanctionService.java

@@ -1,8 +1,11 @@
 package Gotcha.domain.sanction.service;
 
+import static Gotcha.domain.sanction.exception.SanctionExceptionCode.INVALID_PAGE_FOR_SEARCH;
+
 import Gotcha.domain.report.service.UserReportService;
 import Gotcha.domain.sanction.dto.SanctionReq;
 import Gotcha.domain.sanction.dto.SanctionRes;
+import Gotcha.domain.sanction.dto.SanctionUserListRes;
 import Gotcha.domain.sanction.exception.SanctionExceptionCode;
 import Gotcha.domain.sanction.repository.SanctionRepository;
 import gotcha_common.exception.CustomException;
@@ -12,7 +15,11 @@
 import gotcha_domain.user.User;
 import gotcha_domain.user.UserStatus;
 import gotcha_user.service.UserService;
+import java.util.List;
 import lombok.RequiredArgsConstructor;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.PageImpl;
+import org.springframework.data.domain.PageRequest;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 
@@ -21,10 +28,46 @@
 @Service
 @RequiredArgsConstructor
 public class SanctionService {
-
     private final SanctionRepository sanctionRepository;
     private final UserService userService;
     private final UserReportService userReportService;
+    private final Integer USERS_PER_PAGE = 6;
+
+    @Transactional(readOnly = true)
+    public Page<SanctionUserListRes> getSanctionUsers(String nickname, int page) {
+        boolean isSearchModeByNickname = nickname != null && !nickname.isBlank();
+
+        Page<User> users = isSearchModeByNickname
+                ? searchUser(nickname, page)
+                : findAllUsers(page);
+
+        return users.map(this::toResponse);
+    }
+
+    private Page<User> searchUser(String nickname, int page) {
+        if (page != 0) {
+            throw new CustomException(INVALID_PAGE_FOR_SEARCH);
+        }
+
+        User user = userService.findUserByNickname(nickname);
+        return new PageImpl<>(List.of(user), PageRequest.of(0, USERS_PER_PAGE), 1);
+    }
+
+    private Page<User> findAllUsers(int page) {
+        return userService.findAllUsers( PageRequest.of(page, USERS_PER_PAGE));
+    }
+
+
+    private SanctionUserListRes toResponse(User user) {
+        return new SanctionUserListRes(
+                user.getNickname(),
+                user.getCreatedAt().toLocalDate(),
+                user.getEmail(),
+                userReportService.countReportByUserId(user.getId()),
+                user.getWarningCount()
+        );
+    }
+
 
     @Transactional
     public SanctionRes sanctionUser(SanctionReq sanctionReq, String adminId) {