[deploy] develop -> main

src/main/java/DGU_AI_LAB/admin_be/domain/alarm/controller/docs/AlarmApi.java

@@ -13,7 +13,7 @@
 import jakarta.validation.Valid;
 import org.springframework.http.ResponseEntity;
 
-@Tag(name = "Slack 및 E-mail", description = "Slack 및 Email 알림 API")
+@Tag(name = "0. Slack 및 E-mail", description = "Slack 및 Email 알림 API")
 public interface AlarmApi {
 
     @Operation(

src/main/java/DGU_AI_LAB/admin_be/domain/containerImage/controller/docs/ContainerImageApi.java

@@ -15,10 +15,10 @@
 
 import java.util.List;
 
-@Tag(name = "이미지 관리", description = "컨테이너 이미지 생성 및 조회 API")
+@Tag(name = "2. 이미지 관리", description = "컨테이너 이미지 조회 API")
 public interface ContainerImageApi {
 
-    @Operation(summary = "이미지 생성", description = "새로운 컨테이너 이미지를 등록합니다.")
+    @Operation(summary = "이미지 생성", description = "새로운 컨테이너 이미지를 등록합니다. -> 관리자용으로 만들어졌으니, 수정 필요합니다. ")
     @ApiResponse(responseCode = "200", description = "이미지 생성 성공",
             content = @Content(schema = @Schema(implementation = ContainerImageResponseDTO.class)))
     ResponseEntity<ContainerImageResponseDTO> createImage(

src/main/java/DGU_AI_LAB/admin_be/domain/dashboard/controller/docs/DashBoardApi.java

@@ -18,7 +18,7 @@
 import org.springframework.web.bind.annotation.RequestParam;
 
 
-@Tag(name = "사용자 대시보드 API", description = "대시보드용 API")
+@Tag(name = "2. 사용자 대시보드 API", description = "대시보드용 API")
 @RequestMapping("/api/dashboard")
 public interface DashBoardApi {
 

src/main/java/DGU_AI_LAB/admin_be/domain/groups/controller/GroupController.java

@@ -1,5 +1,6 @@
 package DGU_AI_LAB.admin_be.domain.groups.controller;
 
+import DGU_AI_LAB.admin_be.domain.groups.controller.docs.GroupApi;
 import DGU_AI_LAB.admin_be.domain.groups.dto.request.CreateGroupRequestDTO;
 import DGU_AI_LAB.admin_be.domain.groups.dto.response.GroupResponseDTO;
 import DGU_AI_LAB.admin_be.domain.groups.service.GroupService;
@@ -16,7 +17,7 @@
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/groups")
-public class GroupController {
+public class GroupController implements GroupApi {
 
     private final GroupService groupService;
 

src/main/java/DGU_AI_LAB/admin_be/domain/groups/controller/docs/GroupApi.java

@@ -0,0 +1,32 @@
+package DGU_AI_LAB.admin_be.domain.groups.controller.docs;
+
+import DGU_AI_LAB.admin_be.domain.groups.dto.request.CreateGroupRequestDTO;
+import DGU_AI_LAB.admin_be.global.common.SuccessResponse;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.*;
+
+@Tag(name = "2. 그룹 API", description = "사용자용 그룹 목록 조회, 그룹 생성 API")
+public interface GroupApi {
+
+    @Operation(summary = "모든 그룹 목록 조회", description = "시스템에 등록된 모든 그룹의 정보를 조회합니다. 사용 신청 단계에서 이 목록을 조회하고, 그룹을 선택할 수 있습니다.")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "성공"),
+            @ApiResponse(responseCode = "404", description = "조회된 그룹 정보 없음")
+    })
+    @GetMapping
+    ResponseEntity<SuccessResponse<?>> getGroups();
+
+    @Operation(summary = "새로운 그룹 생성", description = "새로운 그룹을 생성하고 DB에 저장합니다.")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "201", description = "생성 성공"),
+            @ApiResponse(responseCode = "400", description = "잘못된 요청 (필수 필드 누락 등)"),
+            @ApiResponse(responseCode = "409", description = "중복된 GID를 가진 그룹이 이미 존재함")
+    })
+    @PostMapping
+    ResponseEntity<SuccessResponse<?>> createGroup(@RequestBody @Valid CreateGroupRequestDTO dto);
+}

src/main/java/DGU_AI_LAB/admin_be/domain/groups/dto/request/CreateGroupRequestDTO.java

@@ -1,15 +1,19 @@
 package DGU_AI_LAB.admin_be.domain.groups.dto.request;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.validation.constraints.NotBlank;
 import jakarta.validation.constraints.NotNull;
 import jakarta.validation.constraints.Positive;
 import lombok.Builder;
 
+@Schema(description = "1. 그룹 생성 요청 DTO")
 @Builder
 public record CreateGroupRequestDTO(
+        @Schema(description = "할당할 우분투 GID (Group ID)", example = "1001")
         @NotNull @Positive
         Long ubuntuGid,
 
+        @Schema(description = "생성할 그룹명", example = "developers")
         @NotBlank
         String groupName
 ) {

src/main/java/DGU_AI_LAB/admin_be/domain/pod/controller/docs/PodApi.java

@@ -10,7 +10,7 @@
 
 import java.util.List;
 
-@Tag(name = "Kubernetes Pods", description = "쿠버네티스 Pod 조회 API")
+@Tag(name = "0. Kubernetes Pods", description = "쿠버네티스 Pod 조회 API")
 public interface PodApi {
 
     @Operation(

src/main/java/DGU_AI_LAB/admin_be/domain/portRequests/entity/PortRequests.java

@@ -0,0 +1,46 @@
+package DGU_AI_LAB.admin_be.domain.portRequests.entity;
+
+import DGU_AI_LAB.admin_be.domain.requests.entity.Request;
+import DGU_AI_LAB.admin_be.domain.resourceGroups.entity.ResourceGroup;
+import DGU_AI_LAB.admin_be.global.common.BaseTimeEntity;
+import jakarta.persistence.*;
+import jakarta.validation.constraints.Max;
+import jakarta.validation.constraints.Min;
+import lombok.*;
+
+@Entity
+@Table(name = "port_requests", uniqueConstraints = {
+    @UniqueConstraint(columnNames = {"port_number", "rsgroup_id"})
+})
+@Getter
+@NoArgsConstructor(access = AccessLevel.PROTECTED)
+@AllArgsConstructor
+@Builder
+public class PortRequests extends BaseTimeEntity {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    @Column(name = "port_request_id")
+    private Long portRequestId;
+
+    @Column(name = "port_number", nullable = false)
+    @Min(1)
+    @Max(65535)
+    private Integer portNumber;
+
+    @Column(name = "usage_purpose", nullable = false, length = 1000)
+    private String usagePurpose;
+
+    @Column(name = "is_active", nullable = false)
+    @Builder.Default
+    private Boolean isActive = true;
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "request_id", nullable = false)
+    private Request request;
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "rsgroup_id", nullable = false)
+    private ResourceGroup resourceGroup;
+
+}

src/main/java/DGU_AI_LAB/admin_be/domain/requests/controller/AdminRequestController.java

@@ -1,5 +1,6 @@
 package DGU_AI_LAB.admin_be.domain.requests.controller;
 
+import DGU_AI_LAB.admin_be.domain.requests.controller.docs.AdminRequestApi;
 import DGU_AI_LAB.admin_be.domain.requests.dto.request.ApproveModificationDTO;
 import DGU_AI_LAB.admin_be.domain.requests.dto.request.ApproveRequestDTO;
 import DGU_AI_LAB.admin_be.domain.requests.dto.request.RejectRequestDTO;
@@ -20,7 +21,7 @@
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/admin/requests")
-public class AdminRequestController {
+public class AdminRequestController implements AdminRequestApi {
 
     private final AdminRequestCommandService adminRequestCommandService;
     private final AdminRequestQueryService adminRequestQueryService;
@@ -44,6 +45,15 @@ public ResponseEntity<List<ContainerInfoDTO>> getAllActiveContainers() {
         return ResponseEntity.ok(adminRequestQueryService.getAllActiveContainers());
     }
 
+    /**
+     * 모든 요청 목록 조회 (관리자용)
+     * 모든 상태의 Request 목록을 반환합니다.
+     */
+    @GetMapping
+    public ResponseEntity<List<SaveRequestResponseDTO>> getAllRequests() {
+        return ResponseEntity.ok(adminRequestQueryService.getAllRequests());
+    }
+
     /**
      * 신규 신청 목록 조회 (관리자용)
      * PENDING 상태의 Request 목록을 반환합니다.

src/main/java/DGU_AI_LAB/admin_be/domain/requests/controller/ConfigRequestController.java

@@ -1,5 +1,6 @@
 package DGU_AI_LAB.admin_be.domain.requests.controller;
 
+import DGU_AI_LAB.admin_be.domain.requests.controller.docs.ConfigRequestApi;
 import DGU_AI_LAB.admin_be.domain.requests.dto.response.AcceptInfoResponseDTO;
 import DGU_AI_LAB.admin_be.domain.requests.service.ConfigRequestService;
 import lombok.RequiredArgsConstructor;
@@ -9,7 +10,7 @@
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/requests/config")
-public class ConfigRequestController {
+public class ConfigRequestController implements ConfigRequestApi {
 
     private final ConfigRequestService configRequestService;
 

src/main/java/DGU_AI_LAB/admin_be/domain/requests/controller/docs/AcceptInfoApi.java

@@ -9,7 +9,7 @@
 import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.http.ResponseEntity;
 
-@Tag(name = "Config Server용 승인 정보 관리", description = "Ubuntu username별 승인 정보 조회 API")
+@Tag(name = "0. Config Server용 승인 정보 관리", description = "Ubuntu username별 승인 정보 조회 API")
 public interface AcceptInfoApi {
 
     @Operation(

src/main/java/DGU_AI_LAB/admin_be/domain/requests/controller/docs/AdminRequestApi.java

@@ -1,58 +1,74 @@
 package DGU_AI_LAB.admin_be.domain.requests.controller.docs;
 
+import DGU_AI_LAB.admin_be.domain.requests.dto.request.ApproveModificationDTO;
 import DGU_AI_LAB.admin_be.domain.requests.dto.request.ApproveRequestDTO;
 import DGU_AI_LAB.admin_be.domain.requests.dto.request.RejectRequestDTO;
+import DGU_AI_LAB.admin_be.domain.requests.dto.response.ChangeRequestResponseDTO;
+import DGU_AI_LAB.admin_be.domain.requests.dto.response.ContainerInfoDTO;
+import DGU_AI_LAB.admin_be.domain.requests.dto.response.ResourceUsageDTO;
 import DGU_AI_LAB.admin_be.domain.requests.dto.response.SaveRequestResponseDTO;
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.media.ArraySchema;
-import io.swagger.v3.oas.annotations.media.Content;
-import io.swagger.v3.oas.annotations.media.Schema;
 import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
 import org.springframework.http.ResponseEntity;
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.web.bind.annotation.*;
 
 import java.util.List;
 
-@Tag(name = "관리자용 서버 사용 신청 관리", description = "관리자용 서버 사용 신청 관리 API")
+@Tag(name = "1. 관리자 서버 사용 신청 처리", description = "관리자용 서버 사용 신청 관리 API")
 public interface AdminRequestApi {
 
-    @Operation(
-            summary = "모든 신청 목록 조회",
-            description = "상태에 상관없이 모든 사용 신청을 조회합니다."
-    )
-    @ApiResponse(
-            responseCode = "200", description = "조회 성공",
-            content = @Content(array = @ArraySchema(schema = @Schema(implementation = SaveRequestResponseDTO.class)))
-    )
+    @Operation(summary = "변경 요청 승인", description = "사용자의 변경 요청을 승인합니다.")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "성공"),
+            @ApiResponse(responseCode = "404", description = "변경 요청을 찾을 수 없음"),
+            @ApiResponse(responseCode = "409", description = "요청 상태가 PENDING이 아님")
+    })
+    @PatchMapping("/change/approve")
+    ResponseEntity<Void> approveModification(
+            @AuthenticationPrincipal(expression = "userId") Long adminId,
+            @RequestBody @Valid ApproveModificationDTO dto
+    );
+
+    @Operation(summary = "모든 리소스 사용량 조회", description = "현재 사용 중인 컨테이너들의 리소스 사용량을 조회합니다.")
+    @GetMapping("/usage")
+    ResponseEntity<List<ResourceUsageDTO>> getAllResourceUsage();
+
+    @Operation(summary = "모든 컨테이너 정보 조회", description = "현재 활성화된 모든 컨테이너의 상세 정보를 조회합니다.")
+    @GetMapping("/containers")
+    ResponseEntity<List<ContainerInfoDTO>> getAllActiveContainers();
+
+    @Operation(summary = "모든 요청 목록 조회", description = "모든 상태의 사용자 요청 목록을 조회합니다.")
+    @GetMapping
     ResponseEntity<List<SaveRequestResponseDTO>> getAllRequests();
 
-    @Operation(
-            summary = "신청 승인",
-            description = "해당 신청의 상태를 FULFILLED로 변경하고 approvedAt을 현재 시각으로 설정합니다. expiresAt, volumeSizeGiB, imageId, rsgroupId를 갱신합니다."
-    )
-    @ApiResponse(
-            responseCode = "200", description = "승인 성공",
-            content = @Content(schema = @Schema(implementation = SaveRequestResponseDTO.class))
-    )
-    ResponseEntity<SaveRequestResponseDTO> approve(
-            @io.swagger.v3.oas.annotations.parameters.RequestBody(
-                    description = "승인 DTO", required = true
-            )
-            ApproveRequestDTO dto
-    );
+    @Operation(summary = "신규 신청 목록 조회", description = "PENDING 상태의 신규 사용자 신청 목록을 조회합니다.")
+    @GetMapping("/new")
+    ResponseEntity<List<SaveRequestResponseDTO>> getNewRequests();
 
-    @Operation(
-            summary = "신청 거절",
-            description = "해당 신청의 상태를 DENIED로 변경하고 관리 코멘트를 기록합니다."
-    )
-    @ApiResponse(
-            responseCode = "200", description = "거절 성공",
-            content = @Content(schema = @Schema(implementation = SaveRequestResponseDTO.class))
-    )
-    ResponseEntity<SaveRequestResponseDTO> reject(
-            @io.swagger.v3.oas.annotations.parameters.RequestBody(
-                    description = "거절 DTO", required = true
-            )
-            RejectRequestDTO dto
-    );
+    @Operation(summary = "변경 요청 목록 조회", description = "PENDING 상태의 사용자 변경 요청 목록을 조회합니다.")
+    @GetMapping("/change")
+    ResponseEntity<List<ChangeRequestResponseDTO>> getChangeRequests();
+
+    @Operation(summary = "신규 신청 승인", description = "신규 사용자 신청을 승인하고, 계정 및 리소스를 할당합니다.")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "성공"),
+            @ApiResponse(responseCode = "404", description = "요청을 찾을 수 없음"),
+            @ApiResponse(responseCode = "409", description = "요청 상태가 PENDING이 아님"),
+            @ApiResponse(responseCode = "502", description = "외부 서버 오류")
+    })
+    @PatchMapping("/approval")
+    ResponseEntity<SaveRequestResponseDTO> approve(@RequestBody @Valid ApproveRequestDTO dto);
+
+    @Operation(summary = "신규 신청 거절", description = "신규 사용자 신청을 거절합니다.")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "성공"),
+            @ApiResponse(responseCode = "404", description = "요청을 찾을 수 없음"),
+            @ApiResponse(responseCode = "409", description = "요청 상태가 PENDING 또는 FULFILLED가 아님")
+    })
+    @PatchMapping("/reject")
+    ResponseEntity<SaveRequestResponseDTO> reject(@RequestBody @Valid RejectRequestDTO dto);
 }

src/main/java/DGU_AI_LAB/admin_be/domain/requests/controller/docs/ConfigRequestApi.java

@@ -0,0 +1,51 @@
+package DGU_AI_LAB.admin_be.domain.requests.controller.docs;
+
+import DGU_AI_LAB.admin_be.domain.requests.dto.response.AcceptInfoResponseDTO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+
+@Tag(name = "0. Config Server용 API", description = "내부 Config Server 연동을 위한 API")
+@RequestMapping("/api/requests/config")
+public interface ConfigRequestApi {
+
+    @Operation(summary = "우분투 계정명 사용 가능 여부 확인", description = "지정된 우분투 계정명이 사용 가능한지 확인합니다.")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "성공",
+                    content = @io.swagger.v3.oas.annotations.media.Content(
+                            mediaType = "application/json",
+                            examples = {
+                                    @io.swagger.v3.oas.annotations.media.ExampleObject(
+                                            name = "사용 가능",
+                                            value = "{\"available\": true}"
+                                    ),
+                                    @io.swagger.v3.oas.annotations.media.ExampleObject(
+                                            name = "사용 불가능",
+                                            value = "{\"available\": false}"
+                                    )
+                            }
+                    )
+            )
+    })
+    @GetMapping("/check-username")
+    ResponseEntity<?> checkUbuntuUsername(
+            @RequestParam @Parameter(description = "확인할 우분투 계정명", example = "toni") String username
+    );
+
+    @Operation(summary = "요청 승인 정보 조회", description = "지정된 우분투 계정명에 대한 승인된 요청 정보를 조회합니다.")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "성공"),
+            @ApiResponse(responseCode = "404", description = "승인된 요청을 찾을 수 없음")
+    })
+    @GetMapping("/{username}")
+    ResponseEntity<AcceptInfoResponseDTO> getAcceptInfo(
+            @PathVariable @Parameter(description = "승인 정보 조회 대상 계정명", example = "toni") String username
+    );
+}

src/main/java/DGU_AI_LAB/admin_be/domain/requests/controller/docs/RequestApi.java

@@ -16,7 +16,7 @@
 
 import java.util.List;
 
-@Tag(name = "서버 사용 신청", description = "서버 사용 신청 API")
+@Tag(name = "2. 서버 사용 신청", description = "서버 사용 신청 API")
 public interface RequestApi {
 
     @Operation(