[Feat/#97] 사물함 구역 배치·사진 저장과 구역 상세 응답 개편

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

@@ -35,10 +35,12 @@ ApiResponse<LockerSectionListResponse> getSections(
         @ParameterObject LockerPeriodParams params
     );
 
-    /** 구역에 속한 사물함의 배치 정보와 선택 가능 여부. */
+    /** 구역의 칸 배치 구조·사진과 사물함 선택 가능 여부. */
     @Operation(summary = "사물함 구역 상세 조회",
-        description = "구역에 속한 사물함의 배치도 위치와 선택 가능 여부를 조회한다. "
-            + "사물함이 사용 가능한 상태이고 해당 회차에 신청되지 않은 경우에만 선택할 수 있다.")
+        description = "구역의 칸 배치 구조(layout)와 실제 사진, 구역에 속한 사물함의 선택 가능 여부를 조회한다. "
+            + "layout의 칸 번호는 lockers[].lockerNumber와 같다. 배치 구조를 아직 등록하지 않은 구역이면 "
+            + "layout과 photoUrl이 null이다. 사물함이 사용 가능한 상태이고 해당 회차에 신청되지 않은 경우에만 "
+            + "선택할 수 있다.")
     @ApiErrorCode(type = CommonErrorCode.class, codes = {"INVALID_INPUT"})
     @ApiErrorCode(type = LockerErrorCode.class, codes = {"LOCKER_PERIOD_NOT_FOUND", "LOCKER_SECTION_NOT_FOUND"})
     ApiResponse<LockerSectionDetailResponse> getSectionLockers(

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

@@ -3,6 +3,7 @@
 import jakarta.validation.Valid;
 import java.time.LocalDate;
 import java.util.List;
+import java.util.Optional;
 import java.util.Set;
 import kr.ac.kookmin.stream.api.app.AppApiUser;
 import kr.ac.kookmin.stream.api.app.event.locker.request.LockerApplyRequest;
@@ -14,9 +15,12 @@
 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.LockerApplicationResult;
+import kr.ac.kookmin.stream.event.domain.locker.domain.LockerSectionDetail;
 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 kr.ac.kookmin.stream.file.domain.File;
+import kr.ac.kookmin.stream.file.service.FileService;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.ModelAttribute;
@@ -39,6 +43,7 @@ public class AppLockerController implements AppLockerApi {
 
     private final LockerService lockerService;
     private final LockerApplicationService lockerApplicationService;
+    private final FileService fileService;
 
     @Override
     @GetMapping("/sections")
@@ -63,13 +68,17 @@ public ApiResponse<LockerSectionDetailResponse> getSectionLockers(
         @Valid @ModelAttribute LockerPeriodParams params
     ) {
         Long lockerPeriodId = params.lockerPeriodId();
-        List<Locker> lockers = lockerService.getSectionLockers(lockerPeriodId, sectionId);
+        LockerSectionDetail detail = lockerService.getSectionDetail(lockerPeriodId, sectionId);
+        // 배치 구조를 아직 등록하지 않은 구역이면 사진도 없다
+        File photo = Optional.ofNullable(detail.layout())
+            .flatMap(layout -> fileService.findById(layout.getPhotoFileId()))
+            .orElse(null);
         Set<Long> appliedLockerIds = lockerService.getAppliedLockerIds(lockerPeriodId);
         Long myLockerId = lockerService.getLockerByMemberId(lockerPeriodId, apiUser.userId())
             .map(Locker::getId)
             .orElse(null);
 
-        return ApiResponse.success(LockerSectionDetailResponse.of(lockers, appliedLockerIds, myLockerId));
+        return ApiResponse.success(LockerSectionDetailResponse.of(detail, photo, appliedLockerIds, myLockerId));
     }
 
     @Override

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

@@ -5,10 +5,8 @@
 
 public record LockerResponse(
     Long lockerId,
-    String lockerLabel,
     int lockerNumber,
-    int rowNo,
-    int columnNo,
+    String lockerLabel,
     boolean isAvailable,
     boolean isMine
 ) {
@@ -20,10 +18,8 @@ public record LockerResponse(
     public static LockerResponse of(Locker locker, boolean applied, Long myLockerId) {
         return new LockerResponse(
             locker.getId(),
-            locker.getLockerLabel(),
             locker.getLockerNumber(),
-            locker.getRowNo(),
-            locker.getColumnNo(),
+            locker.getLockerLabel(),
             locker.isSelectable(applied),
             Objects.equals(locker.getId(), myLockerId)
         );

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

@@ -1,22 +1,61 @@
 package kr.ac.kookmin.stream.api.app.event.locker.response;
 
+import com.fasterxml.jackson.annotation.JsonRawValue;
+import io.swagger.v3.oas.annotations.media.Schema;
 import java.util.List;
 import java.util.Set;
-import kr.ac.kookmin.stream.event.domain.locker.domain.Locker;
+import kr.ac.kookmin.stream.api.common.StorageUrlBuilder;
+import kr.ac.kookmin.stream.event.domain.locker.domain.LockerSectionDetail;
+import kr.ac.kookmin.stream.event.domain.locker.domain.LockerSectionLayout;
+import kr.ac.kookmin.stream.file.domain.File;
 
-public record LockerSectionDetailResponse(List<LockerResponse> lockers) {
+/**
+ * @param layout   칸 배치 구조. 배치 구조를 아직 등록하지 않은 구역이면 {@code null}
+ * @param photoUrl 구역 실제 사진. 배치 구조를 아직 등록하지 않았거나 사진 파일이 삭제됐으면 {@code null}
+ */
+public record LockerSectionDetailResponse(
+    Long sectionId,
+    String section,
+    Layout layout,
+    String photoUrl,
+    List<LockerResponse> lockers
+) {
 
     /**
+     * @param photo            구역 사진 파일. 배치 구조를 아직 등록하지 않았거나 파일이 삭제됐으면 {@code null}
      * @param appliedLockerIds 해당 운영 회차에 이미 신청된 사물함 식별자
      * @param myLockerId       조회한 회원이 신청한 사물함. 신청하지 않았으면 {@code null}
      */
     public static LockerSectionDetailResponse of(
-        List<Locker> lockers,
+        LockerSectionDetail detail,
+        File photo,
         Set<Long> appliedLockerIds,
         Long myLockerId
     ) {
-        return new LockerSectionDetailResponse(lockers.stream()
-            .map(locker -> LockerResponse.of(locker, appliedLockerIds.contains(locker.getId()), myLockerId))
-            .toList());
+        return new LockerSectionDetailResponse(
+            detail.section().getId(),
+            detail.section().getLabel(),
+            detail.layout() == null ? null : Layout.from(detail.layout()),
+            StorageUrlBuilder.build(photo),
+            detail.lockers().stream()
+                .map(locker -> LockerResponse.of(locker, appliedLockerIds.contains(locker.getId()), myLockerId))
+                .toList()
+        );
+    }
+
+    /**
+     * @param version layout 형식 버전. 앱은 모르는 버전이면 그리지 않고 업데이트를 안내한다
+     * @param root    저장된 JSON을 해석하지 않고 그대로 끼워 넣는다
+     */
+    public record Layout(
+        int version,
+        @JsonRawValue
+        @Schema(type = "object", description = "root 블록 트리. 블록은 type으로 구분하고, 칸 번호는 lockers[].lockerNumber와 같다")
+        String root
+    ) {
+
+        public static Layout from(LockerSectionLayout layout) {
+            return new Layout(layout.getVersion(), layout.getLayout());
+        }
     }
 }

api/common-api/src/main/java/kr/ac/kookmin/stream/api/common/StorageUrlBuilder.java

@@ -9,6 +9,13 @@ public static String build(String fileKey) {
         return fileKey == null ? null : ApiConstants.STORAGE_BASE_URL + "/" + fileKey;
     }
 
+    /**
+     * file이 null이면(없거나 삭제된 파일) null을 돌려준다.
+     */
+    public static String build(File file) {
+        return file == null ? null : build(file.getFileKey());
+    }
+
     /**
      * fileId가 null이거나 filesById에 없으면(삭제된 파일) null을 돌려준다.
      */

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

@@ -0,0 +1,16 @@
+package kr.ac.kookmin.stream.event.domain.locker.domain;
+
+import java.util.List;
+
+/**
+ * 사물함 구역 상세 한 건. 칸 선택 화면이 구역 정보·배치 구조·사물함을 한 번에 받는다.
+ *
+ * @param layout  배치 구조와 사진. 아직 등록하지 않은 구역이면 {@code null}
+ * @param lockers 구역에 속한 사물함. 선택 가능 여부는 담지 않는다
+ */
+public record LockerSectionDetail(
+    LockerSection section,
+    LockerSectionLayout layout,
+    List<Locker> lockers
+) {
+}

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

@@ -0,0 +1,30 @@
+package kr.ac.kookmin.stream.event.domain.locker.domain;
+
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
+import lombok.EqualsAndHashCode;
+import lombok.Getter;
+
+/**
+ * 구역 상세 화면의 칸 배치 구조와 구역 사진. 구역마다 하나다.
+ * <p>
+ * 배치 구조에는 칸 위치와 창문·벽면 같은 고정 구조만 담는다. 선택 가능 여부처럼 신청할 때마다 바뀌는 칸 상태는
+ * 조회 시점에 사물함에서 계산하고, 둘은 사물함 번호({@link Locker#getLockerNumber()})로 잇는다.
+ */
+@Getter
+@EqualsAndHashCode
+@AllArgsConstructor(access = AccessLevel.PRIVATE)
+public class LockerSectionLayout {
+
+    private Long id;
+    private Long sectionId;
+    /** root 블록 트리 JSON 원문. 서버는 해석하지 않고 그대로 내려준다. */
+    private String layout;
+    /** layout 형식 버전. 블록 종류·필드가 바뀌면 올려서 옛 앱이 모르는 형식을 알아채게 한다. */
+    private int version;
+    private Long photoFileId;
+
+    public static LockerSectionLayout of(Long id, Long sectionId, String layout, int version, Long photoFileId) {
+        return new LockerSectionLayout(id, sectionId, layout, version, photoFileId);
+    }
+}

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

@@ -6,6 +6,7 @@
 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;
+import kr.ac.kookmin.stream.event.domain.locker.domain.LockerSectionLayout;
 
 /**
  * 사물함 운영 회차·구역·사물함 저장소. 사물함 신청은 {@link LockerApplicationRepository}가 맡는다.
@@ -17,8 +18,6 @@ public interface LockerRepository {
      */
     boolean existsPublishedPeriod(Long lockerPeriodId);
 
-    boolean existsSection(Long sectionId);
-
     /**
      * 게시된 운영 회차 한 건. 아직 공개하지 않은 회차는 없는 것으로 본다.
      */
@@ -34,6 +33,13 @@ public interface LockerRepository {
      */
     List<LockerSection> findAllSections();
 
+    Optional<LockerSection> findSectionById(Long sectionId);
+
+    /**
+     * 구역의 배치 구조와 사진. 아직 등록하지 않은 구역이면 비어 있다.
+     */
+    Optional<LockerSectionLayout> findLayoutBySectionId(Long sectionId);
+
     /**
      * 삭제되지 않은 사물함 전체를 조회한다. 구역별 집계는 서비스가 이 목록을 묶어 센다.
      */

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

@@ -5,6 +5,7 @@
 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.LockerSectionDetail;
 import kr.ac.kookmin.stream.event.domain.locker.domain.LockerSectionSummary;
 
 public interface LockerService {
@@ -15,12 +16,13 @@ public interface LockerService {
     List<LockerSectionSummary> getSections(Long lockerPeriodId);
 
     /**
-     * 구역에 속한 사물함을 배치도 순서(행 → 열)로 조회한다.
+     * 구역 정보와 배치 구조·사진, 구역에 속한 사물함을 함께 조회한다. 배치 구조를 아직 등록하지 않은 구역이면
+     * {@link LockerSectionDetail#layout()}이 {@code null}이다.
      * <p>
      * 선택 가능 여부는 담지 않는다. 판정은 {@link Locker#isSelectable(boolean)}이 갖고 있고, 신청 여부는
      * {@link #getAppliedLockerIds(Long)}로 함께 읽어 호출하는 쪽에서 맞춰본다.
      */
-    List<Locker> getSectionLockers(Long lockerPeriodId, Long sectionId);
+    LockerSectionDetail getSectionDetail(Long lockerPeriodId, Long sectionId);
 
     /**
      * 해당 운영 회차에 이미 신청된 사물함 식별자.

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

@@ -9,6 +9,7 @@
 import kr.ac.kookmin.stream.event.domain.locker.domain.Locker;
 import kr.ac.kookmin.stream.event.domain.locker.domain.LockerErrorCode;
 import kr.ac.kookmin.stream.event.domain.locker.domain.LockerSection;
+import kr.ac.kookmin.stream.event.domain.locker.domain.LockerSectionDetail;
 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;
@@ -44,11 +45,16 @@ public List<LockerSectionSummary> getSections(Long lockerPeriodId) {
     }
 
     @Override
-    public List<Locker> getSectionLockers(Long lockerPeriodId, Long sectionId) {
+    public LockerSectionDetail getSectionDetail(Long lockerPeriodId, Long sectionId) {
         requirePublishedPeriod(lockerPeriodId);
-        requireSection(sectionId);
+        LockerSection section = lockerRepository.findSectionById(sectionId)
+            .orElseThrow(() -> new BusinessException(LockerErrorCode.LOCKER_SECTION_NOT_FOUND));
 
-        return lockerRepository.findLockersBySectionId(sectionId);
+        return new LockerSectionDetail(
+            section,
+            lockerRepository.findLayoutBySectionId(sectionId).orElse(null),
+            lockerRepository.findLockersBySectionId(sectionId)
+        );
     }
 
     @Override
@@ -99,10 +105,4 @@ private void requirePublishedPeriod(Long lockerPeriodId) {
             throw new BusinessException(LockerErrorCode.LOCKER_PERIOD_NOT_FOUND);
         }
     }
-
-    private void requireSection(Long sectionId) {
-        if (!lockerRepository.existsSection(sectionId)) {
-            throw new BusinessException(LockerErrorCode.LOCKER_SECTION_NOT_FOUND);
-        }
-    }
 }

core/domain/event/src/test/java/kr/ac/kookmin/stream/event/domain/locker/service/impl/LockerApplicationServiceImplTest.java

@@ -23,6 +23,7 @@
 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.domain.LockerSection;
+import kr.ac.kookmin.stream.event.domain.locker.domain.LockerSectionLayout;
 import kr.ac.kookmin.stream.event.domain.locker.domain.LockerStatus;
 import kr.ac.kookmin.stream.event.domain.locker.repository.LockerApplicationRepository;
 import kr.ac.kookmin.stream.event.domain.locker.repository.LockerRepository;
@@ -359,12 +360,17 @@ public boolean existsPublishedPeriod(Long lockerPeriodId) {
         }
 
         @Override
-        public boolean existsSection(Long sectionId) {
+        public List<LockerSection> findAllSections() {
             throw new UnsupportedOperationException();
         }
 
         @Override
-        public List<LockerSection> findAllSections() {
+        public Optional<LockerSection> findSectionById(Long sectionId) {
+            throw new UnsupportedOperationException();
+        }
+
+        @Override
+        public Optional<LockerSectionLayout> findLayoutBySectionId(Long sectionId) {
             throw new UnsupportedOperationException();
         }