[Feat/#70] 사물함 신청 API 추가

api/app-api/src/main/java/kr/ac/kookmin/stream/api/app/event/locker/AppLockerApi.java

@@ -3,7 +3,9 @@
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import kr.ac.kookmin.stream.api.app.AppApiUser;
+import kr.ac.kookmin.stream.api.app.event.locker.request.LockerApplyRequest;
 import kr.ac.kookmin.stream.api.app.event.locker.request.LockerPeriodParams;
+import kr.ac.kookmin.stream.api.app.event.locker.response.LockerApplyResponse;
 import kr.ac.kookmin.stream.api.app.event.locker.response.LockerSectionDetailResponse;
 import kr.ac.kookmin.stream.api.app.event.locker.response.LockerSectionListResponse;
 import kr.ac.kookmin.stream.api.common.dto.ApiResponse;
@@ -18,7 +20,7 @@
  * 스웨거 문서용 어노테이션만 이쪽에 두고 컨트롤러에는 라우팅과 본문만 남긴다. 경로 매핑과
  * 파라미터 바인딩(@{@code ModelAttribute}, @{@code PathVariable} 등)은 구현체에 둔다.
  */
-@Tag(name = "사물함", description = "학생 앱 사물함 구역·배치 조회")
+@Tag(name = "사물함", description = "학생 앱 사물함 구역·배치 조회와 신청")
 public interface AppLockerApi {
 
     /** 구역별 전체·선택 가능 사물함 수와 표시 상태. */
@@ -43,4 +45,12 @@ ApiResponse<LockerSectionDetailResponse> getSectionLockers(
         Long sectionId,
         @ParameterObject LockerPeriodParams params
     );
+
+    /** 고른 사물함을 신청하고 즉시 배정한다. */
+    @Operation(summary = "사물함 신청",
+        description = "게시된 운영 회차에서 고른 사물함을 신청하고 즉시 배정한다. 운영 회차당 한 개만 신청할 수 있고 "
+            + "신청 후에는 취소하거나 변경할 수 없다. 같은 사물함에 동시에 신청하면 먼저 완료된 신청만 성공한다.")
+    @ApiErrorCode(type = CommonErrorCode.class, codes = {"INVALID_INPUT"})
+    @ApiErrorCode(type = LockerErrorCode.class, codes = {"LOCKER_PERIOD_NOT_FOUND", "LOCKER_ALREADY_ASSIGNED"})
+    ApiResponse<LockerApplyResponse> apply(AppApiUser apiUser, LockerApplyRequest request);
 }

api/app-api/src/main/java/kr/ac/kookmin/stream/api/app/event/locker/AppLockerController.java

@@ -4,22 +4,27 @@
 import java.util.List;
 import java.util.Set;
 import kr.ac.kookmin.stream.api.app.AppApiUser;
+import kr.ac.kookmin.stream.api.app.event.locker.request.LockerApplyRequest;
 import kr.ac.kookmin.stream.api.app.event.locker.request.LockerPeriodParams;
+import kr.ac.kookmin.stream.api.app.event.locker.response.LockerApplyResponse;
 import kr.ac.kookmin.stream.api.app.event.locker.response.LockerSectionDetailResponse;
 import kr.ac.kookmin.stream.api.app.event.locker.response.LockerSectionListResponse;
 import kr.ac.kookmin.stream.api.common.dto.ApiResponse;
 import kr.ac.kookmin.stream.event.domain.locker.domain.Locker;
 import kr.ac.kookmin.stream.event.domain.locker.domain.LockerSectionSummary;
+import kr.ac.kookmin.stream.event.domain.locker.service.LockerApplicationService;
 import kr.ac.kookmin.stream.event.domain.locker.service.LockerService;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.ModelAttribute;
 import org.springframework.web.bind.annotation.PathVariable;
+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;
 
 /**
- * 학생 앱의 사물함 구역·배치 조회 API.
+ * 학생 앱의 사물함 구역·배치 조회와 신청 API.
  * <p>
  * 선택 가능 여부와 내 사물함 표시는 조회 결과를 응답 DTO에서 맞춰봐서 만든다. 미게시 회차·없는 구역
  * 판정은 구역 조회가 하므로 신청 조회보다 먼저 호출해야 404가 앞선다.
@@ -30,6 +35,7 @@
 public class AppLockerController implements AppLockerApi {
 
     private final LockerService lockerService;
+    private final LockerApplicationService lockerApplicationService;
 
     @Override
     @GetMapping("/sections")
@@ -62,4 +68,15 @@ public ApiResponse<LockerSectionDetailResponse> getSectionLockers(
 
         return ApiResponse.success(LockerSectionDetailResponse.of(lockers, appliedLockerIds, myLockerId));
     }
+
+    @Override
+    @PostMapping("/applications")
+    public ApiResponse<LockerApplyResponse> apply(
+        AppApiUser apiUser,
+        @Valid @RequestBody LockerApplyRequest request
+    ) {
+        return ApiResponse.success(
+            LockerApplyResponse.from(lockerApplicationService.apply(apiUser.userId(), request.toCommand()))
+        );
+    }
 }

api/app-api/src/main/java/kr/ac/kookmin/stream/api/app/event/locker/request/LockerApplyRequest.java

@@ -0,0 +1,20 @@
+package kr.ac.kookmin.stream.api.app.event.locker.request;
+
+import jakarta.validation.constraints.NotNull;
+import kr.ac.kookmin.stream.event.domain.locker.domain.LockerApplyCommand;
+
+/**
+ * @param lockerPeriodId 신청할 운영 회차. 구역 조회에 쓴 회차 식별자를 그대로 보낸다
+ */
+public record LockerApplyRequest(
+    @NotNull(message = "사물함 운영 회차를 입력해 주세요.")
+    Long lockerPeriodId,
+
+    @NotNull(message = "신청할 사물함을 선택해 주세요.")
+    Long lockerId
+) {
+
+    public LockerApplyCommand toCommand() {
+        return new LockerApplyCommand(lockerPeriodId, lockerId);
+    }
+}

api/app-api/src/main/java/kr/ac/kookmin/stream/api/app/event/locker/response/LockerApplyResponse.java

@@ -0,0 +1,23 @@
+package kr.ac.kookmin.stream.api.app.event.locker.response;
+
+import java.time.LocalDate;
+import kr.ac.kookmin.stream.event.domain.locker.domain.LockerApplicationResult;
+
+public record LockerApplyResponse(
+    Long lockerApplicationId,
+    Long lockerId,
+    String lockerLabel,
+    LocalDate usageStartDate,
+    LocalDate usageEndDate
+) {
+
+    public static LockerApplyResponse from(LockerApplicationResult result) {
+        return new LockerApplyResponse(
+            result.application().getId(),
+            result.locker().getId(),
+            result.locker().getLockerLabel(),
+            result.period().getUsageStartAt(),
+            result.period().getUsageEndAt()
+        );
+    }
+}

core/domain/event/src/main/java/kr/ac/kookmin/stream/event/domain/locker/domain/LockerApplication.java

@@ -1,5 +1,6 @@
 package kr.ac.kookmin.stream.event.domain.locker.domain;
 
+import java.time.LocalDateTime;
 import lombok.AccessLevel;
 import lombok.AllArgsConstructor;
 import lombok.EqualsAndHashCode;
@@ -14,8 +15,24 @@ public class LockerApplication {
     private Long lockerPeriodId;
     private Long memberId;
     private Long lockerId;
+    private LocalDateTime appliedAt;
 
-    public static LockerApplication of(Long id, Long lockerPeriodId, Long memberId, Long lockerId) {
-        return new LockerApplication(id, lockerPeriodId, memberId, lockerId);
+    public static LockerApplication of(
+        Long id,
+        Long lockerPeriodId,
+        Long memberId,
+        Long lockerId,
+        LocalDateTime appliedAt
+    ) {
+        return new LockerApplication(id, lockerPeriodId, memberId, lockerId, appliedAt);
+    }
+
+    /**
+     * 새 신청을 만든다. 식별자는 저장 시 부여된다. 승인 절차 없이 신청이 곧 배정이다.
+     *
+     * @param appliedAt 신청 시각. 클라이언트가 보내지 않고 서버 시각으로 기록한다
+     */
+    public static LockerApplication create(Long lockerPeriodId, Long memberId, Long lockerId, LocalDateTime appliedAt) {
+        return new LockerApplication(null, lockerPeriodId, memberId, lockerId, appliedAt);
     }
 }

core/domain/event/src/main/java/kr/ac/kookmin/stream/event/domain/locker/domain/LockerApplicationResult.java

@@ -0,0 +1,7 @@
+package kr.ac.kookmin.stream.event.domain.locker.domain;
+
+/**
+ * 사물함 신청 결과. 생성된 신청과 배정된 사물함, 사용 기간을 알려줄 운영 회차를 함께 돌려준다.
+ */
+public record LockerApplicationResult(LockerApplication application, Locker locker, LockerPeriod period) {
+}

core/domain/event/src/main/java/kr/ac/kookmin/stream/event/domain/locker/domain/LockerApplyCommand.java

@@ -0,0 +1,7 @@
+package kr.ac.kookmin.stream.event.domain.locker.domain;
+
+/**
+ * 사물함 신청 요청. 신청할 운영 회차와 고른 사물함을 담는다.
+ */
+public record LockerApplyCommand(Long lockerPeriodId, Long lockerId) {
+}

core/domain/event/src/main/java/kr/ac/kookmin/stream/event/domain/locker/domain/LockerErrorCode.java

@@ -12,7 +12,8 @@
 public enum LockerErrorCode implements ErrorCode {
 
     LOCKER_PERIOD_NOT_FOUND(ErrorStatus.NOT_FOUND, "사물함 운영 회차를 찾을 수 없습니다."),
-    LOCKER_SECTION_NOT_FOUND(ErrorStatus.NOT_FOUND, "사물함 구역을 찾을 수 없습니다.");
+    LOCKER_SECTION_NOT_FOUND(ErrorStatus.NOT_FOUND, "사물함 구역을 찾을 수 없습니다."),
+    LOCKER_ALREADY_ASSIGNED(ErrorStatus.CONFLICT, "다른 사용자가 먼저 신청한 사물함입니다.");
 
     private final int status;
     private final String message;

core/domain/event/src/main/java/kr/ac/kookmin/stream/event/domain/locker/repository/LockerApplicationRepository.java

@@ -0,0 +1,32 @@
+package kr.ac.kookmin.stream.event.domain.locker.repository;
+
+import java.util.Optional;
+import java.util.Set;
+import kr.ac.kookmin.stream.event.domain.locker.domain.LockerApplication;
+
+/**
+ * 사물함 신청 저장소. 운영 회차·구역·사물함은 {@link LockerRepository}가 맡는다.
+ */
+public interface LockerApplicationRepository {
+
+    /**
+     * 해당 운영 회차에 이 사물함이 이미 신청되었는지.
+     */
+    boolean existsByLocker(Long lockerPeriodId, Long lockerId);
+
+    /**
+     * 해당 운영 회차에 이미 신청된 사물함 식별자.
+     */
+    Set<Long> findAppliedLockerIds(Long lockerPeriodId);
+
+    /**
+     * 해당 운영 회차에서 회원이 신청한 사물함 식별자. 회차당 한 건만 신청할 수 있고 취소가 없어 최대 하나다.
+     */
+    Optional<Long> findAppliedLockerId(Long lockerPeriodId, Long memberId);
+
+    /**
+     * 신청을 저장한다. 같은 회차의 같은 사물함에 먼저 저장된 신청이 있으면
+     * {@link kr.ac.kookmin.stream.event.domain.locker.domain.LockerErrorCode#LOCKER_ALREADY_ASSIGNED}로 실패한다.
+     */
+    LockerApplication save(LockerApplication application);
+}

core/domain/event/src/main/java/kr/ac/kookmin/stream/event/domain/locker/repository/LockerRepository.java

@@ -2,10 +2,13 @@
 
 import java.util.List;
 import java.util.Optional;
-import java.util.Set;
 import kr.ac.kookmin.stream.event.domain.locker.domain.Locker;
+import kr.ac.kookmin.stream.event.domain.locker.domain.LockerPeriod;
 import kr.ac.kookmin.stream.event.domain.locker.domain.LockerSection;
 
+/**
+ * 사물함 운영 회차·구역·사물함 저장소. 사물함 신청은 {@link LockerApplicationRepository}가 맡는다.
+ */
 public interface LockerRepository {
 
     /**
@@ -15,6 +18,11 @@ public interface LockerRepository {
 
     boolean existsSection(Long sectionId);
 
+    /**
+     * 게시된 운영 회차 한 건. 아직 공개하지 않은 회차는 없는 것으로 본다.
+     */
+    Optional<LockerPeriod> findPublishedPeriodById(Long lockerPeriodId);
+
     /**
      * 전체 구역을 식별자 오름차순으로 조회한다.
      */
@@ -34,14 +42,4 @@ public interface LockerRepository {
      * 사물함 한 건. 삭제된 사물함은 없는 것으로 본다.
      */
     Optional<Locker> findLockerById(Long lockerId);
-
-    /**
-     * 해당 운영 회차에 이미 신청된 사물함 식별자.
-     */
-    Set<Long> findAppliedLockerIds(Long lockerPeriodId);
-
-    /**
-     * 해당 운영 회차에서 회원이 신청한 사물함 식별자. 회차당 한 건만 신청할 수 있고 취소가 없어 최대 하나다.
-     */
-    Optional<Long> findAppliedLockerId(Long lockerPeriodId, Long memberId);
 }

core/domain/event/src/main/java/kr/ac/kookmin/stream/event/domain/locker/service/LockerApplicationService.java

@@ -0,0 +1,13 @@
+package kr.ac.kookmin.stream.event.domain.locker.service;
+
+import kr.ac.kookmin.stream.event.domain.locker.domain.LockerApplicationResult;
+import kr.ac.kookmin.stream.event.domain.locker.domain.LockerApplyCommand;
+
+/** 사물함 신청. 구역·배치 조회는 {@link LockerService}가 맡는다. */
+public interface LockerApplicationService {
+
+    /**
+     * 고른 사물함을 신청하고 즉시 배정한다. 같은 사물함에 동시에 신청하면 먼저 저장된 신청만 성공한다.
+     */
+    LockerApplicationResult apply(Long memberId, LockerApplyCommand command);
+}

core/domain/event/src/main/java/kr/ac/kookmin/stream/event/domain/locker/service/impl/LockerApplicationServiceImpl.java

@@ -0,0 +1,58 @@
+package kr.ac.kookmin.stream.event.domain.locker.service.impl;
+
+import java.time.LocalDateTime;
+import kr.ac.kookmin.stream.common.BusinessException;
+import kr.ac.kookmin.stream.event.domain.locker.domain.Locker;
+import kr.ac.kookmin.stream.event.domain.locker.domain.LockerApplication;
+import kr.ac.kookmin.stream.event.domain.locker.domain.LockerApplicationResult;
+import kr.ac.kookmin.stream.event.domain.locker.domain.LockerApplyCommand;
+import kr.ac.kookmin.stream.event.domain.locker.domain.LockerErrorCode;
+import kr.ac.kookmin.stream.event.domain.locker.domain.LockerPeriod;
+import kr.ac.kookmin.stream.event.domain.locker.repository.LockerApplicationRepository;
+import kr.ac.kookmin.stream.event.domain.locker.repository.LockerRepository;
+import kr.ac.kookmin.stream.event.domain.locker.service.LockerApplicationService;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+@Service
+@RequiredArgsConstructor
+class LockerApplicationServiceImpl implements LockerApplicationService {
+
+    private final LockerRepository lockerRepository;
+    private final LockerApplicationRepository lockerApplicationRepository;
+
+    @Override
+    @Transactional
+    public LockerApplicationResult apply(Long memberId, LockerApplyCommand command) {
+        LockerPeriod period = getPublishedPeriod(command.lockerPeriodId());
+        Locker locker = getSelectableLocker(period.getId(), command.lockerId());
+
+        LockerApplication application = lockerApplicationRepository.save(
+            LockerApplication.create(period.getId(), memberId, locker.getId(), LocalDateTime.now())
+        );
+        return new LockerApplicationResult(application, locker, period);
+    }
+
+    /** 게시된 운영 회차. 아직 공개하지 않은 회차는 학생에게 없는 것으로 보여야 하므로 구역 조회와 같은 기준으로 거른다. */
+    private LockerPeriod getPublishedPeriod(Long lockerPeriodId) {
+        return lockerRepository.findPublishedPeriodById(lockerPeriodId)
+            .orElseThrow(() -> new BusinessException(LockerErrorCode.LOCKER_PERIOD_NOT_FOUND));
+    }
+
+    /**
+     * 해당 운영 회차에 선택할 수 있는 사물함. 구역 조회와 같은 기준({@link Locker#isSelectable})으로 판정한다.
+     * <p>
+     * 흔한 경우를 먼저 거르는 검사일 뿐이다. 이 검사와 저장 사이에 끼어든 신청은 저장 시 유니크 제약이 막는다.
+     */
+    private Locker getSelectableLocker(Long lockerPeriodId, Long lockerId) {
+        // 구역 상세에서 선택 가능한 사물함만 고를 수 있어 정상 흐름에서는 없는 사물함이 들어오지 않는다
+        Locker locker = lockerRepository.findLockerById(lockerId)
+            .orElseThrow(() -> new IllegalArgumentException("존재하지 않는 사물함입니다. lockerId=" + lockerId));
+
+        if (!locker.isSelectable(lockerApplicationRepository.existsByLocker(lockerPeriodId, lockerId))) {
+            throw new BusinessException(LockerErrorCode.LOCKER_ALREADY_ASSIGNED);
+        }
+        return locker;
+    }
+}

core/domain/event/src/main/java/kr/ac/kookmin/stream/event/domain/locker/service/impl/LockerServiceImpl.java

@@ -11,6 +11,7 @@
 import kr.ac.kookmin.stream.event.domain.locker.domain.LockerSection;
 import kr.ac.kookmin.stream.event.domain.locker.domain.LockerSectionSummary;
 import kr.ac.kookmin.stream.event.domain.locker.domain.SectionAvailabilityStatus;
+import kr.ac.kookmin.stream.event.domain.locker.repository.LockerApplicationRepository;
 import kr.ac.kookmin.stream.event.domain.locker.repository.LockerRepository;
 import kr.ac.kookmin.stream.event.domain.locker.service.LockerService;
 import lombok.RequiredArgsConstructor;
@@ -22,13 +23,14 @@
 class LockerServiceImpl implements LockerService {
 
     private final LockerRepository lockerRepository;
+    private final LockerApplicationRepository lockerApplicationRepository;
 
     @Override
     @Transactional(readOnly = true)
     public List<LockerSectionSummary> getSections(Long lockerPeriodId) {
         requirePublishedPeriod(lockerPeriodId);
 
-        Set<Long> appliedLockerIds = lockerRepository.findAppliedLockerIds(lockerPeriodId);
+        Set<Long> appliedLockerIds = lockerApplicationRepository.findAppliedLockerIds(lockerPeriodId);
         Map<Long, List<Locker>> lockersBySection = getLockerMapBySectionId();
 
         return lockerRepository.findAllSections().stream()
@@ -51,7 +53,7 @@ public List<Locker> getSectionLockers(Long lockerPeriodId, Long sectionId) {
 
     @Override
     public Set<Long> getAppliedLockerIds(Long lockerPeriodId) {
-        return lockerRepository.findAppliedLockerIds(lockerPeriodId);
+        return lockerApplicationRepository.findAppliedLockerIds(lockerPeriodId);
     }
 
     @Override
@@ -62,7 +64,7 @@ public Map<Long, List<Locker>> getLockerMapBySectionId() {
 
     @Override
     public Optional<Locker> getLockerByMemberId(Long lockerPeriodId, Long memberId) {
-        return lockerRepository.findAppliedLockerId(lockerPeriodId, memberId)
+        return lockerApplicationRepository.findAppliedLockerId(lockerPeriodId, memberId)
             .flatMap(lockerRepository::findLockerById);
     }