CLAP-108 Add: 작업 요청 및 조회에 대한 명세 추가

parkjaehak · parkjaehak · commit d42e522f1efc · 2025-01-24T21:48:31.000+09:00
diff --git a/src/main/java/clap/server/adapter/inbound/web/dto/task/AttachmentRequest.java b/src/main/java/clap/server/adapter/inbound/web/dto/task/AttachmentRequest.java
@@ -1,7 +1,13 @@
 package clap.server.adapter.inbound.web.dto.task;
 
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
 public record AttachmentRequest(
+        @Schema(description = "파일 ID", example = "45")
         Long fileId,
-        String fileUrl) {
+
+        @Schema(description = "파일 URL", example = "https://example.com/file.png")
+        String fileUrl
+) {
 }
diff --git a/src/main/java/clap/server/adapter/inbound/web/dto/task/CreateTaskRequest.java b/src/main/java/clap/server/adapter/inbound/web/dto/task/CreateTaskRequest.java
@@ -1,18 +1,30 @@
 package clap.server.adapter.inbound.web.dto.task;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.validation.constraints.NotBlank;
 import jakarta.validation.constraints.NotNull;
 
 import java.util.List;
 
+
+@Schema(description = "작업 생성 요청")
 public record CreateTaskRequest(
+        @Schema(description = "카테고리 ID")
         @NotNull
         Long categoryId,
+
+        @Schema(description = "메인 카테고리 ID")
         @NotNull
         Long mainCategoryId,
+
+        @Schema(description = "작업 제목")
         @NotBlank
         String title,
+
+        @Schema(description = "작업 설명")
         String description,
+
+        @Schema(description = "첨부 파일 URL 목록", example = "[\"https://example.com/file1.png\", \"https://example.com/file2.pdf\"]")
         List<@NotBlank String> fileUrls
 ) {
 }
diff --git a/src/main/java/clap/server/adapter/inbound/web/dto/task/FilterTaskListRequest.java b/src/main/java/clap/server/adapter/inbound/web/dto/task/FilterTaskListRequest.java
@@ -2,25 +2,39 @@
 
 
 import clap.server.adapter.outbound.persistense.entity.task.constant.TaskStatus;
+import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.validation.constraints.NotNull;
 import org.springframework.beans.factory.annotation.Value;
 
 import java.util.List;
 
-
+@Schema(description = "작업 필터링 요청")
 public record FilterTaskListRequest(
 
+        @Schema(description = "검색 기간 (단위: 시간)", example = "1, 24, 168, 730, 2190 (1시간, 24시간, 1주일, 1개월, 3개월)")
         Integer term,
+
+        @Schema(description = "카테고리 ID 목록", example = "[1, 2, 3]")
         @NotNull
         List<Long> categoryIds,
+
+        @Schema(description = "메인 카테고리 ID 목록", example = "[10, 20, 30]")
         @NotNull
         List<Long> mainCategoryIds,
+
+        @Schema(description = "작업 제목", example = "작업 제목")
         @NotNull
         String title,
+
+        @Schema(description = "사용자 닉네임", example = "atom.park")
         @NotNull
         String nickName,
+
+        @Schema(description = "작업 상태 목록", example = "[\"REQUESTED\", \"IN_PROGRESS\"]")
         @NotNull
         List<TaskStatus> taskStatus,
+
+        @Schema(description = "정렬 기준", implementation = OrderRequest.class)
         @NotNull
         OrderRequest orderRequest
 ) {
diff --git a/src/main/java/clap/server/adapter/inbound/web/dto/task/OrderRequest.java b/src/main/java/clap/server/adapter/inbound/web/dto/task/OrderRequest.java
@@ -1,10 +1,11 @@
 package clap.server.adapter.inbound.web.dto.task;
 
-import jakarta.validation.constraints.NotNull;
+import io.swagger.v3.oas.annotations.media.Schema;
 
 public record OrderRequest(
-        @NotNull
-        String target,
-        @NotNull
-        String type
+        @Schema(description = "정렬 기준 (REQUESTED_AT/FINISHED_AT)", example = "REQUESTED_AT")
+        String sortBy,
+
+        @Schema(description = "정렬 방향 (ASC/DESC)", example = "ASC")
+        String sortDirection
 ) {}
diff --git a/src/main/java/clap/server/adapter/inbound/web/dto/task/UpdateTaskRequest.java b/src/main/java/clap/server/adapter/inbound/web/dto/task/UpdateTaskRequest.java
@@ -1,20 +1,34 @@
 package clap.server.adapter.inbound.web.dto.task;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.validation.constraints.NotBlank;
 import jakarta.validation.constraints.NotNull;
 
 import java.util.List;
 
+@Schema(description = "작업 업데이트 요청")
 public record UpdateTaskRequest(
+
+        @Schema(description = "작업 ID", example = "123")
         @NotNull
         Long taskId,
+
+        @Schema(description = "카테고리 ID", example = "1")
         @NotNull
         Long categoryId,
+
+        @Schema(description = "메인 카테고리 ID", example = "10")
         @NotNull
         Long mainCategoryId,
+
+        @Schema(description = "작업 제목", example = "업데이트된 제목")
         @NotBlank
         String title,
+
+        @Schema(description = "작업 설명", example = "업데이트된 설명.")
         String description,
+
+        @Schema(description = "첨부 파일 요청 목록", implementation = AttachmentRequest.class)
         List<AttachmentRequest> attachmentRequests
-) {
-}
+) {}
+
diff --git a/src/main/java/clap/server/adapter/inbound/web/task/FindTaskController.java b/src/main/java/clap/server/adapter/inbound/web/task/FindTaskController.java
@@ -27,12 +27,11 @@
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/tasks")
-@Slf4j
 public class FindTaskController {
     private final FindTaskDetailsUsecase taskDetailsUsecase;
     private final FindTaskListUsecase taskListUsecase;
 
-    @Operation(summary = "내가 요청한 작업 목록 조회 (filtering, paging, sorting")
+    @Operation(summary = "사용자 요청 작업 목록 조회")
     @Secured({"ROLE_USER"})
     @GetMapping("/requests")
     public ResponseEntity<Page<FindTaskListResponse>> getRequestedTaskList(
@@ -41,18 +40,6 @@ public ResponseEntity<Page<FindTaskListResponse>> getRequestedTaskList(
             @ModelAttribute FilterTaskListRequest filterTaskListRequest,
             @AuthenticationPrincipal SecurityUserDetails userInfo){
         Pageable pageable = PageRequest.of(page, pageSize);
-
-        log.info("요청된 파라미터 - page: {}, pageSize: {}, userId: {}", page, pageSize, userInfo.getUserId());
-        log.info("FilterTaskListRequest - term: {}, categoryIds: {}, mainCategoryIds: {}, title: {}, nickName: {}, taskStatus: {}, orderRequest: {}",
-                filterTaskListRequest.term(),
-                filterTaskListRequest.categoryIds(),
-                filterTaskListRequest.mainCategoryIds(),
-                filterTaskListRequest.title(),
-                filterTaskListRequest.nickName(),
-                filterTaskListRequest.taskStatus(),
-                filterTaskListRequest.orderRequest());
-        log.info("isEmpty={}", filterTaskListRequest.nickName().isEmpty());
-
         return ResponseEntity.ok(taskListUsecase.findRequestedTaskList(userInfo.getUserId(), pageable, filterTaskListRequest));
     }
     @Operation(summary = "요청한 작업 상세 조회")
diff --git a/src/main/java/clap/server/adapter/outbound/persistense/repository/task/TaskCustomRepositoryImpl.java b/src/main/java/clap/server/adapter/outbound/persistense/repository/task/TaskCustomRepositoryImpl.java
@@ -36,8 +36,8 @@ public Page<TaskEntity> findRequestedTaskList(Long requesterId, Pageable pageabl
         String nickName = findTaskListRequest.nickName();
         List<TaskStatus> taskStatuses = findTaskListRequest.taskStatus();
         Integer termHours = findTaskListRequest.term();
-        String sortTarget = findTaskListRequest.orderRequest().target();
-        String sortType = findTaskListRequest.orderRequest().type();
+        String sortBy = findTaskListRequest.orderRequest().sortBy();
+        String sortDirection = findTaskListRequest.orderRequest().sortDirection();
 
         if (termHours != null) {
             LocalDateTime fromDate = LocalDateTime.now().minusHours(termHours);
@@ -59,7 +59,7 @@ public Page<TaskEntity> findRequestedTaskList(Long requesterId, Pageable pageabl
             whereClause.and(taskEntity.taskStatus.in(taskStatuses));
         }
 
-        OrderSpecifier<?> orderSpecifier = getOrderSpecifier(sortTarget, sortType);
+        OrderSpecifier<?> orderSpecifier = getOrderSpecifier(sortBy, sortDirection);
 
         List<TaskEntity> result = queryFactory
                 .selectFrom(taskEntity)
@@ -75,13 +75,13 @@ public Page<TaskEntity> findRequestedTaskList(Long requesterId, Pageable pageabl
         return new PageImpl<>(result, pageable, total);
     }
 
-    private OrderSpecifier<?> getOrderSpecifier(String sortTarget, String sortType) {
-        DateTimePath<LocalDateTime> sortColumn = switch (sortTarget) {
+    private OrderSpecifier<?> getOrderSpecifier(String sortBy, String sortDirection) {
+        DateTimePath<LocalDateTime> sortColumn = switch (sortBy) {
             case "REQUESTED_AT" -> taskEntity.updatedAt;
             case "FINISHED_AT" -> taskEntity.completedAt;
             default -> taskEntity.updatedAt;
         };
-        return "ASC".equalsIgnoreCase(sortType)
+        return "ASC".equalsIgnoreCase(sortDirection)
                 ? new OrderSpecifier<>(ASC, sortColumn)
                 : new OrderSpecifier<>(DESC, sortColumn);
     }
diff --git a/src/main/java/clap/server/application/service/Task/CreateTaskService.java b/src/main/java/clap/server/application/service/Task/CreateTaskService.java
@@ -1,4 +1,4 @@
-package clap.server.application.Task;
+package clap.server.application.service.Task;
 
 import clap.server.adapter.inbound.web.dto.task.CreateTaskRequest;
 import clap.server.adapter.inbound.web.dto.task.CreateTaskResponse;
diff --git a/src/main/java/clap/server/application/service/Task/FindTaskDetailsService.java b/src/main/java/clap/server/application/service/Task/FindTaskDetailsService.java
@@ -1,4 +1,4 @@
-package clap.server.application.Task;
+package clap.server.application.service.Task;
 
 import clap.server.adapter.inbound.web.dto.task.FindTaskDetailsResponse;
 import clap.server.adapter.outbound.persistense.entity.task.TaskEntity;
diff --git a/src/main/java/clap/server/application/service/Task/FindTaskListService.java b/src/main/java/clap/server/application/service/Task/FindTaskListService.java
@@ -1,4 +1,4 @@
-package clap.server.application.Task;
+package clap.server.application.service.Task;
 
 import clap.server.adapter.inbound.web.dto.task.FilterTaskListRequest;
 import clap.server.adapter.inbound.web.dto.task.FindTaskListResponse;
diff --git a/src/main/java/clap/server/application/service/Task/UpdateTaskService.java b/src/main/java/clap/server/application/service/Task/UpdateTaskService.java
@@ -1,4 +1,4 @@
-package clap.server.application.Task;
+package clap.server.application.service.Task;
 
 import clap.server.adapter.inbound.web.dto.task.UpdateTaskRequest;
 import clap.server.adapter.inbound.web.dto.task.UpdateTaskResponse;
diff --git a/src/main/java/clap/server/exception/code/TaskErrorCode.java b/src/main/java/clap/server/exception/code/TaskErrorCode.java
@@ -9,6 +9,7 @@
 public enum TaskErrorCode implements BaseErrorCode {
     TASK_NOT_FOUND(HttpStatus.NOT_FOUND, "TASK_001", "작업을 찾을 수 없습니다."),
     CATEGORY_NOT_FOUND(HttpStatus.NOT_FOUND, "TASK_002", "카테고리를 찾을 수 없습니다."),
+    TASK_STATUS_MISMATCH(HttpStatus.BAD_REQUEST, "TASK_003", "작업 상태가 일치하지 않습니다.");
     ;
 
     private final HttpStatus httpStatus;

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-package clap.server.application.Task;`
	`1`	`+package clap.server.application.service.Task;`
`2`	`2`
`3`	`3`	`import clap.server.adapter.inbound.web.dto.task.CreateTaskRequest;`
`4`	`4`	`import clap.server.adapter.inbound.web.dto.task.CreateTaskResponse;`