[REFACTOR/#234] 예원 리팩토링

src/main/java/com/assu/server/domain/admin/service/AdminService.java

@@ -8,7 +8,6 @@
 import com.assu.server.domain.user.entity.enums.Major;
 import com.assu.server.domain.user.entity.enums.University;
 
-// PaperQueryServiceImpl 이 AdminService 참조 중 -> 순환참조 문제 발생하지 않도록 주의
 public interface AdminService {
 	List<Admin> findMatchingAdmins(University university, Department department, Major major);
 

src/main/java/com/assu/server/domain/mapping/controller/StudentAdminController.java

@@ -6,6 +6,7 @@
 import com.assu.server.global.apiPayload.code.status.SuccessStatus;
 import com.assu.server.global.util.PrincipalDetails;
 import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.core.annotation.AuthenticationPrincipal;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -15,21 +16,27 @@
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/admin/dashBoard")
+@Tag(name = "관리자 대시보드 API", description = "어드민 전용 통계 및 대시보드 데이터 조회 API")
 public class StudentAdminController {
+
     private final StudentAdminService studentAdminService;
+
     @Operation(
             summary = "누적 가입자 수 조회 API",
-            description = "admin으로 접근해주세요."
+            description = "# [v1.0 (2025-09-02)](https://www.notion.so/_-24c1197c19ed8062be94fc08619b760f)\n" +
+                    "- 관리자(Admin) 권한으로 접근하여 현재까지의 총 누적 가입자 수를 조회합니다."
     )
     @GetMapping
     public BaseResponse<StudentAdminResponseDTO.CountAdminAuthResponseDTO> getCountAdmin(
             @AuthenticationPrincipal PrincipalDetails pd
-            ) {
+    ) {
         return BaseResponse.onSuccess(SuccessStatus._OK, studentAdminService.getCountAdminAuth(pd.getId()));
     }
+
     @Operation(
             summary = "신규 한 달 가입자 수 조회 API",
-            description = "admin으로 접근해주세요."
+            description = "# [v1.0 (2025-09-02)](https://www.notion.so/_-24c1197c19ed805db80fca98c38849d1)\n" +
+                    "- 이번 달(매달 1일 초기화) 기준 신규 가입한 사용자 수를 조회합니다."
     )
     @GetMapping("/new")
     public BaseResponse<StudentAdminResponseDTO.NewCountAdminResponseDTO> getNewStudentCountAdmin(
@@ -40,37 +47,37 @@ public BaseResponse<StudentAdminResponseDTO.NewCountAdminResponseDTO> getNewStud
 
     @Operation(
             summary = "오늘 제휴 사용자 수 조회 API",
-            description = "admin으로 접근해주세요."
+            description = "# [v1.0 (2025-09-02)](https://www.notion.so/_-24e1197c19ed80a283b1c336a1c3df72)\n" +
+                    "- 금일 제휴 서비스를 이용한 총 사용자 수를 조회합니다."
     )
     @GetMapping("/countUser")
     public BaseResponse<StudentAdminResponseDTO.CountUsagePersonResponseDTO> getCountUser(
             @AuthenticationPrincipal PrincipalDetails pd
     ){
         return BaseResponse.onSuccess(SuccessStatus._OK, studentAdminService.getCountUsagePerson(pd.getId()));
     }
+
     @Operation(
             summary = "제휴업체 누적별 1위 업체 조회 API",
-            description = "adminId로 접근해주세요."
+            description = "# [v1.0 (2025-09-02)](https://www.notion.so/_1-2ef1197c19ed8010a49ce6313d137b4f)\n" +
+                    "- 제휴 이용 횟수가 가장 많은 1위 업체의 정보를 조회합니다."
     )
-        @GetMapping("/top")
-        public BaseResponse<StudentAdminResponseDTO.CountUsageResponseDTO> getTopUsage(
-                @AuthenticationPrincipal PrincipalDetails pd
+    @GetMapping("/top")
+    public BaseResponse<StudentAdminResponseDTO.CountUsageResponseDTO> getTopUsage(
+            @AuthenticationPrincipal PrincipalDetails pd
     ) {
-            return BaseResponse.onSuccess(SuccessStatus._OK, studentAdminService.getCountUsage(pd.getId()));
-        }
-
-        /**
-         * 제휴 업체별 누적 제휴 이용 현황 리스트 반환 (사용량 내림차순)
-         */
-        @Operation(
-                summary = "제휴업체 누적 사용 수 내림차순 조회 API",
-                description = "adminId로 접근해주세요."
-        )
-        @GetMapping("/usage")
-        public BaseResponse<StudentAdminResponseDTO.CountUsageListResponseDTO> getUsageList(
-                @AuthenticationPrincipal PrincipalDetails pd
-        ) {
-            return BaseResponse.onSuccess(SuccessStatus._OK, studentAdminService.getCountUsageList(pd.getId()));
-        }
+        return BaseResponse.onSuccess(SuccessStatus._OK, studentAdminService.getCountUsage(pd.getId()));
+    }
 
-}
+    @Operation(
+            summary = "제휴업체 누적 사용 수 내림차순 조회 API",
+            description = "# [v1.0 (2025-09-02)](https://www.notion.so/_-24e1197c19ed802b92eff5d4dc4dbe82)\n" +
+                    "- 모든 제휴 업체의 누적 사용 현황을 사용량 내림차순 리스트로 반환합니다."
+    )
+    @GetMapping("/usage")
+    public BaseResponse<StudentAdminResponseDTO.CountUsageListResponseDTO> getUsageList(
+            @AuthenticationPrincipal PrincipalDetails pd
+    ) {
+        return BaseResponse.onSuccess(SuccessStatus._OK, studentAdminService.getCountUsageList(pd.getId()));
+    }
+}

src/main/java/com/assu/server/domain/mapping/dto/StoreUsageWithPaper.java

@@ -0,0 +1,8 @@
+package com.assu.server.domain.mapping.dto;
+
+public record StoreUsageWithPaper(
+        Long paperId,
+        Long storeId,
+        String storeName,
+        Long usageCount
+) {}

src/main/java/com/assu/server/domain/mapping/dto/StudentAdminResponseDTO.java

@@ -1,60 +1,70 @@
 package com.assu.server.domain.mapping.dto;
 
-import java.util.List;
-import lombok.AllArgsConstructor;
+import com.assu.server.domain.admin.entity.Admin;
+import com.assu.server.domain.partnership.entity.Paper;
 import lombok.Builder;
-import lombok.Getter;
-import lombok.NoArgsConstructor;
+import java.util.List;
 
 public class StudentAdminResponseDTO {
 
-    @Getter
-    @NoArgsConstructor
-    @AllArgsConstructor
     @Builder
-    public static class CountAdminAuthResponseDTO{ // admin에 따른 총 누적 가입자 수
-        private Long studentCount;
-        private Long adminId;
-        private String adminName;
+    public record CountAdminAuthResponseDTO(
+            Long studentCount,
+            Long adminId,
+            String adminName
+    ) {
+        public static CountAdminAuthResponseDTO from(Long adminId, Long total, String adminName) {
+            return new CountAdminAuthResponseDTO(total, adminId, adminName);
+        }
     }
-    @Getter
-    @NoArgsConstructor
-    @AllArgsConstructor
+
     @Builder
-    public static class NewCountAdminResponseDTO{ //신규 가입자수 (매달 1일 초기화)
-        private Long newStudentCount;
-        private Long adminId;
-        private String adminName;
+    public record NewCountAdminResponseDTO(
+            Long newStudentCount,
+            Long adminId,
+            String adminName
+    ) {
+        public static NewCountAdminResponseDTO from(Long adminId, Long total, String adminName) {
+            return new NewCountAdminResponseDTO(total, adminId, adminName);
+        }
     }
 
-    @Getter
-    @NoArgsConstructor
-    @AllArgsConstructor
     @Builder
-    public static class CountUsagePersonResponseDTO{
-        private Long usagePersonCount;
-        private Long adminId;
-        private String adminName;
+    public record CountUsagePersonResponseDTO(
+            Long usagePersonCount,
+            Long adminId,
+            String adminName
+    ) {
+        public static CountUsagePersonResponseDTO from(Long adminId, Long total, String adminName) {
+            return new CountUsagePersonResponseDTO(total, adminId, adminName);
+        }
     }
 
-    @Getter
-    @NoArgsConstructor
-    @AllArgsConstructor
     @Builder
-    public static class CountUsageResponseDTO{ //제휴 업체별 누적 제휴 이용현황
-        private Long usageCount;
-        private Long adminId;
-        private String adminName;
-        private Long storeId;
-        private String storeName;
-
+    public record CountUsageResponseDTO(
+            Long usageCount,
+            Long adminId,
+            String adminName,
+            Long storeId,
+            String storeName
+    ) {
+        public static CountUsageResponseDTO from(Admin admin, Paper paper, Long total) {
+            return CountUsageResponseDTO.builder()
+                    .usageCount(total)
+                    .adminId(admin.getId())
+                    .adminName(admin.getName())
+                    .storeId(paper.getStore().getId())
+                    .storeName(paper.getStore().getName())
+                    .build();
+        }
     }
-    @Getter
-    @NoArgsConstructor
-    @AllArgsConstructor
+
     @Builder
-    public static class CountUsageListResponseDTO {
-        private List<CountUsageResponseDTO> items; // 사용량 내림차순 정렬됨
+    public record CountUsageListResponseDTO(
+            List<CountUsageResponseDTO> items
+    ) {
+        public static CountUsageListResponseDTO from(List<CountUsageResponseDTO> countUsageList) {
+            return new CountUsageListResponseDTO(countUsageList);
+        }
     }
-
-}
+}