[fix] 보증금 로직 수정

backend/pirocheck/src/main/java/backend/pirocheck/Deposit/controller/DepositController.java

@@ -3,19 +3,23 @@
 
 import backend.pirocheck.Deposit.dto.DepositResDto;
 import backend.pirocheck.Deposit.service.DepositService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 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.RestController;
 
+@Tag(name = "보증금 관리", description = "수강생 보증금/차감/방어권 관련 API")
 @RestController
 @RequestMapping("/api/deposit")
 @RequiredArgsConstructor
 public class DepositController {
 
     private final DepositService depositService;
 
+    @Operation(summary = "보증금 조회", description = "해당 유저의 현재 보증금, 차감 내역, 방어권 금액을 반환합니다.")
     @GetMapping("/{userId}")
     public DepositResDto getDeposit(@PathVariable Long userId) {
         return depositService.getDeposit(userId);

backend/pirocheck/src/main/java/backend/pirocheck/Deposit/dto/DepositResDto.java

@@ -1,6 +1,7 @@
 package backend.pirocheck.Deposit.dto;
 
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Getter;
@@ -11,9 +12,16 @@
 @NoArgsConstructor
 @AllArgsConstructor
 public class DepositResDto {
+    @Schema(description = "현재 보증금 잔액", example = "110000")
     private int amount;
+
+    @Schema(description = "과제 차감 총액", example = "10000")
     private int descentAssignment;
+
+    @Schema(description = "출석 차감 총액", example = "10000")
     private int descentAttendance;
+
+    @Schema(description = "방어권 보상 총액", example = "10000")
     private int ascentDefence;
 
 }

backend/pirocheck/src/main/java/backend/pirocheck/Deposit/entity/Deposit.java

@@ -32,14 +32,14 @@ public void updateAmounts(int descentAssignment, int descentAttendance, int asce
         this.ascentDefence = ascentDefence;
 
         int calculateAmount = 120000 - descentAssignment - descentAttendance + ascentDefence;
-        this.amount = Math.min(calculateAmount, 120000);  // 12만원 넘어가지 않도록
+        this.amount = Math.max(0, Math.min(calculateAmount, 120000));  // 0 이상 12만원 이하
     }
 
     // 방어권 업데이트
     public void updateDefence(int newAscentDefence) {
         this.ascentDefence = newAscentDefence;
         int calculateAmount = 120000 - this.descentAssignment - this.descentAttendance + newAscentDefence;
-        this.amount = Math.min(calculateAmount, 120000);
+        this.amount = Math.max(0, Math.min(calculateAmount, 120000));  // 0 이상 12만원 이하
 
     }
 

backend/pirocheck/src/main/java/backend/pirocheck/ManageStudents/Controller/ManageStudentsController.java

@@ -4,11 +4,14 @@
 import backend.pirocheck.ManageStudents.dto.response.ManageStudentDetailResDto;
 import backend.pirocheck.ManageStudents.dto.response.ManageStudentsListResDto;
 import backend.pirocheck.ManageStudents.service.ManageStudentsService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
 import java.util.List;
 
+@Tag(name = "수강생 관리", description = "관리자가 수강생을 조회하고 방어권을 수정하는 API")
 @RestController
 @RequestMapping("/api/admin/managestudent")
 @RequiredArgsConstructor
@@ -17,18 +20,21 @@ public class ManageStudentsController {
     private final ManageStudentsService manageStudentsService;
 
     // 수강생 리스트 조회
+    @Operation(summary = "수강생 리스트 조회", description = "이름에 따라 수강생 리스트를 검색합니다.")
     @GetMapping("")
     public List<ManageStudentsListResDto> getStudents(@RequestParam(required = false) String name) {
         return manageStudentsService.searchMembers(name);
     }
 
     // 수강생 상세 조회
+    @Operation(summary = "수강생 상세 조회", description = "studentId로 해당 수강생의 보증금, 방어권, 과제 정보를 조회합니다.")
     @GetMapping("/{studentId}")
     public ManageStudentDetailResDto getStudentDetail(@PathVariable Long studentId) {
         return manageStudentsService.getMemberDetail(studentId);
     }
 
     // 방어권 업데이트
+    @Operation(summary = "방어권 수정", description = "studentId에 해당하는 수강생의 보증금 방어권 금액을 수정합니다.")
     @PatchMapping("/{studentId}/defence")
     public void updateDefence(@PathVariable Long studentId, @RequestBody DefenceUpdateReqDto req) {
         manageStudentsService.updateDefence(studentId, req.getDefence());

backend/pirocheck/src/main/java/backend/pirocheck/ManageStudents/dto/request/DefenceUpdateReqDto.java

@@ -1,11 +1,15 @@
 package backend.pirocheck.ManageStudents.dto.request;
 
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Getter;
 import lombok.Setter;
 
 @Getter
 @Setter
 public class DefenceUpdateReqDto {
+
+    @Schema(description = "방어권 금액", example = "20000")
     private int defence;
+
 }

backend/pirocheck/src/main/java/backend/pirocheck/ManageStudents/dto/response/ManageStudentDetailResDto.java

@@ -1,6 +1,6 @@
 package backend.pirocheck.ManageStudents.dto.response;
 
-import jakarta.transaction.Transactional;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Builder;
 import lombok.Getter;
 
@@ -10,8 +10,15 @@
 @Builder
 public class ManageStudentDetailResDto {
 
+    @Schema(description = "수강생 이름", example = "김피로")
     private String name;
+
+    @Schema(description = "현재 보증금 잔액", example = "11000")
     private int deposit;
+
+    @Schema(description = "방어권 금액", example = "10000")
     private int defence; // 방어권
+
+    @Schema(description = "과제 제목 리스트", example = "[\"제로초 인강\", \"토스 클론\"]")
     private List<String> assignmentTitles; // 과제 제목 리스트
 }

backend/pirocheck/src/main/java/backend/pirocheck/User/controller/UserController.java

@@ -5,15 +5,19 @@
 import backend.pirocheck.User.entity.User;
 import backend.pirocheck.User.repository.UserRepository;
 import backend.pirocheck.User.service.UserService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.servlet.http.HttpServletResponse;
 import jakarta.servlet.http.HttpSession;
+import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
 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.RestController;
 
+@Tag(name = "유저 인증", description = "로그인 / 로그아웃 API")
 @RestController
 @RequestMapping("/api")
 @RequiredArgsConstructor
@@ -22,8 +26,9 @@ public class UserController {
     private final UserService userService;
 
     // 로그인
+    @Operation(summary = "로그인", description = "사용자 이름과 비밀번호로 로그인하고 세션을 생성합니다.")
     @PostMapping("/login")
-    public ResponseEntity<LoginResponse> login(@RequestBody LoginRequest request, HttpSession session) {
+    public ResponseEntity<LoginResponse> login(@RequestBody @Valid LoginRequest request, HttpSession session) {
         User user = userService.login(request.getName(), request.getPassword());
 
         //세션에 로그인 정보 저장
@@ -34,6 +39,7 @@ public ResponseEntity<LoginResponse> login(@RequestBody LoginRequest request, Ht
     }
 
     // 로그아웃
+    @Operation(summary = "로그아웃", description = "세션을 종료하여 로그아웃합니다.")
     @PostMapping("/logout")
     public ResponseEntity<Void> logout(HttpSession session) {
         session.invalidate(); // 세션 종료 (메모리에서 삭제)

backend/pirocheck/src/main/java/backend/pirocheck/User/dto/request/LoginRequest.java

@@ -1,12 +1,19 @@
 package backend.pirocheck.User.dto.request;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.NotBlank;
 import lombok.Getter;
 import lombok.Setter;
 
 @Getter
 @Setter
 public class LoginRequest {
 
+    @Schema(description = "사용자 이름", example = "김피로")
+    @NotBlank(message = "이름을 입력해주세요.")
     private String name;
+
+    @Schema(description = "비밀번호", example = "qwer1234!")
+    @NotBlank(message = "비밀번호를 입력해주세요.")
     private String password;
 }

backend/pirocheck/src/main/java/backend/pirocheck/User/dto/response/LoginResponse.java

@@ -2,13 +2,19 @@
 
 
 import backend.pirocheck.User.entity.User;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Getter;
 
 @Getter
 public class LoginResponse {
 
+    @Schema(description = "유저 고유 ID", example = "1")
     private Long id;
+
+    @Schema(description = "유저 이름", example = "김피로")
     private String name;
+
+    @Schema(description = "유저 권한", example = "MEMBER")
     private String role;
 
     public LoginResponse(User user) {