Merge pull request #173 from checkmo2025/refactor/172/modify-swagger-schema

zjhj0814 · web-flow · commit cd7030e30935 · 2026-02-22T23:58:38.000+09:00
[REFACTOR] swagger schema 수정
diff --git a/src/main/java/checkmo/clubManagement/internal/service/ClubManagementQueryFacade.java b/src/main/java/checkmo/clubManagement/internal/service/ClubManagementQueryFacade.java
@@ -28,7 +28,9 @@
 import java.util.EnumSet;
 import java.util.List;
 import java.util.Map;
+import java.util.Objects;
 import java.util.Optional;
+import java.util.stream.Collectors;
 import java.util.stream.IntStream;
 import lombok.RequiredArgsConstructor;
 import org.springframework.stereotype.Service;
@@ -197,13 +199,26 @@ public ClubRecommendationList recommend(String memberId) {
         List<ClubRecommendation> result
                 = clubManagementQueryService.recommend(interestCategories, lastActivityAt, memberId);
 
+        // 추천 결과 기반으로 클럽 정보 배치 조회
+        List<Long> clubIds = ExtractHelper.extractDistinctList(result, ClubRecommendation::getClubId);
+        List<Club> clubs = clubManagementQueryService.retrieveClubs(clubIds);
+        Map<Long, Club> clubMap = clubs.stream().collect(Collectors.toMap(Club::getId, c -> c));
+
         List<ClubResponseDTO.ClubRecommendation> recommendations = IntStream.range(0, result.size())
                 .mapToObj(i -> {
                     ClubRecommendation rec = result.get(i);
+                    Club club = clubMap.get(rec.getClubId());
+                    if (club == null) {
+                        // 추천 결과에 클럽 정보가 없는 경우는 무시 (정상적으로는 발생하지 않아야 함)
+                        return null;
+                    }
+                    ClubDetailWithMyStatus clubDTO = ClubResponseDTO.ClubDetailWithMyStatus.builder()
+                            .club(ClubManagementConverter.toClubDetailDTO(club, false))
+                            .myStatus(MyClubMemberStatus.NONE)
+                            .build();
                     return ClubResponseDTO.ClubRecommendation.builder()
                             .rank(i + 1)
-                            .clubId(rec.getClubId())
-                            .clubName(rec.getClubName())
+                            .clubInfo(clubDTO)
                             .overlapCount(rec.getOverlapCount())
                             .activeMemberCount(rec.getActiveMemberCount())
                             .lastActivityAt(rec.getLastActivityAt())
@@ -212,7 +227,7 @@ public ClubRecommendationList recommend(String memberId) {
                 .toList();
 
         return ClubResponseDTO.ClubRecommendationList.builder()
-                .recommendations(recommendations)
+                .recommendations(recommendations.stream().filter(Objects::nonNull).toList())
                 .build();
     }
 
diff --git a/src/main/java/checkmo/clubManagement/internal/service/query/ClubManagementQueryService.java b/src/main/java/checkmo/clubManagement/internal/service/query/ClubManagementQueryService.java
@@ -28,6 +28,13 @@ public List<Club> retrieveClubs(ClubRequestDTO.ClubSearchFilter filter, Long cur
         return clubRepository.searchClubs(filter, cursorId, pageSize);
     }
 
+    public List<Club> retrieveClubs(List<Long> clubIds) {
+        if (clubIds == null || clubIds.isEmpty()) {
+            return List.of();
+        }
+        return clubRepository.findAllById(clubIds);
+    }
+
     public boolean isDuplicateClubName(String clubName) {
         return clubRepository.existsByName(clubName.trim());
     }
diff --git a/src/main/java/checkmo/clubManagement/web/dto/ClubResponseDTO.java b/src/main/java/checkmo/clubManagement/web/dto/ClubResponseDTO.java
@@ -80,14 +80,14 @@ public static ClubContactItem from(ClubContact clubContact) {
     public static class ClubDetail {
         private Long clubId;
         private String name;
-        @JsonInclude(JsonInclude.Include.NON_NULL) // 독서모임 검색
+        @JsonInclude(JsonInclude.Include.NON_NULL) // 독서모임 검색, 추천
         private String description;
         private String profileImageUrl;
         private boolean isOpen;
         private String region;
         private List<ClubCategoryItem> category;
         private List<ClubParticipantTypeItem> participantTypes;
-        @JsonInclude(JsonInclude.Include.NON_NULL) // 독서모임 검색
+        @JsonInclude(JsonInclude.Include.NON_NULL) // 독서모임 검색, 추천
         private List<ClubContactItem> links;
     }
 
@@ -176,10 +176,8 @@ public static class ClubRecommendationList {
     public static class ClubRecommendation {
         @Schema(description = "정렬 순서", example = "1")
         private int rank;
-        @Schema(description = "추천하는 모임 ID", example = "12345")
-        private Long clubId;
-        @Schema(description = "추천하는 모임 이름", example = "책읽는 사람들")
-        private String clubName;
+        @Schema(description = "추천 모임의 상세 정보")
+        private ClubDetailWithMyStatus clubInfo;
         @Schema(description = "멤버의 선호 카테고리와 모임의 카테고리 간의 겹치는 항목 수(모임 추천 기능 확인을 위해 넣은 필드로, 안정됐다고 판단되면 사라질 수 있습니다) ", example = "3")
         private Long overlapCount;
         @Schema(description = "모임의 활성화 상태인 클럽 멤버 수(모임 추천 기능 확인을 위해 넣은 필드로, 안정됐다고 판단되면 사라질 수 있습니다)", example = "150")
diff --git a/src/main/java/checkmo/clubMeeting/internal/service/ClubMeetingQueryFacade.java b/src/main/java/checkmo/clubMeeting/internal/service/ClubMeetingQueryFacade.java
@@ -57,7 +57,7 @@ public BookShelfResponseDTO.BookShelfList retrieveBookShelfList(
             String memberId,
             Long cursorId
     ) {
-        validateClubAndClubMembership(clubId, memberId);
+        MembershipInfo clubMembership = validateClubAndClubMembership(clubId, memberId);
 
         CursorResult<Meeting> meetingCursorResult = CursorPagingHelper.getPage(
                 pageSize -> clubMeetingQueryService.retrieveMeetings(clubId, cursorId, pageSize),
@@ -73,6 +73,7 @@ public BookShelfResponseDTO.BookShelfList retrieveBookShelfList(
                 .bookShelfInfoList(mapMeetingsToBookshelfInfo(meetings, bookInfoMap))
                 .hasNext(meetingCursorResult.hasNext())
                 .nextCursor(meetingCursorResult.nextCursor())
+                .staff(clubMembership.isStaff())
                 .build();
     }
 
diff --git a/src/main/java/checkmo/clubMeeting/web/dto/bookshelf/BookShelfResponseDTO.java b/src/main/java/checkmo/clubMeeting/web/dto/bookshelf/BookShelfResponseDTO.java
@@ -20,6 +20,14 @@ public static class BookShelfList {
         private List<BookShelfInfo> bookShelfInfoList;
         private boolean hasNext;
         private Long nextCursor;
+
+        @Getter(AccessLevel.NONE)
+        private boolean staff;
+
+        @JsonProperty("isStaff")
+        public boolean isStaff() {
+            return staff;
+        }
     }
 
     @Getter
diff --git a/src/main/java/checkmo/clubNotice/internal/converter/ClubNoticeConverter.java b/src/main/java/checkmo/clubNotice/internal/converter/ClubNoticeConverter.java
@@ -24,7 +24,7 @@ public static Notice toNotice(ClubNoticeRequestDTO.CreateClubNotice request, Not
         return Notice.builder()
                 .title(request.getTitle())
                 .content(request.getContent())
-                .important(request.isImportant())
+                .pinned(request.isPinned())
                 .tag(tag)
                 .meetingId(request.getMeetingId())
                 .clubId(clubId)
@@ -64,7 +64,7 @@ public static ClubNoticeResponseDTO.ClubNoticePreview toClubNoticePreview(Notice
         return ClubNoticePreview.builder()
                 .id(notice.getId())
                 .title(notice.getTitle())
-                .important(notice.isImportant())
+                .pinned(notice.isPinned())
                 .tagItem(ClubNoticeTagItem.from(notice.getTag()))
                 .createdAt(notice.getCreatedAt())
                 .build();
@@ -79,7 +79,7 @@ public static ClubNoticeResponseDTO.ClubNoticeDetail toClubNoticeDetail(
                 .id(notice.getId())
                 .title(notice.getTitle())
                 .content(notice.getContent())
-                .important(notice.isImportant())
+                .pinned(notice.isPinned())
                 .tag(ClubNoticeTagItem.from(notice.getTag()))
                 .imageUrls(notice.getImageUrls())
                 .createdAt(notice.getCreatedAt())
diff --git a/src/main/java/checkmo/clubNotice/internal/entity/Notice.java b/src/main/java/checkmo/clubNotice/internal/entity/Notice.java
@@ -43,7 +43,8 @@ public class Notice extends BaseEntity {
     @Column(length = 1000)
     private String content;
 
-    private boolean important;
+    @Column(name = "is_pinned")
+    private boolean pinned;
 
     @Enumerated(EnumType.STRING)
     @Column(nullable = false)
@@ -72,12 +73,12 @@ public class Notice extends BaseEntity {
     public void update(
             String title,
             String content,
-            boolean important,
+            boolean pinned,
             Long meetingId
     ) {
         this.title = title;
         this.content = content;
-        this.important = important;
+        this.pinned = pinned;
         this.meetingId = meetingId;
         this.tag = NoticeTag.decideTag(this.vote != null, meetingId != null);
     }
@@ -126,7 +127,7 @@ public List<String> replaceImages(List<String> images) {
         if (images == null) {
             return List.of(); // null이면 변경 없음
         }
-        
+
         if (images.size() > MAX_IMAGE_COUNT) {
             throw new ClubNoticeException(ClubNoticeErrorStatus.NOTICE_IMAGE_LIMIT_EXCEEDED);
         }
diff --git a/src/main/java/checkmo/clubNotice/internal/exception/ClubNoticeErrorStatus.java b/src/main/java/checkmo/clubNotice/internal/exception/ClubNoticeErrorStatus.java
@@ -12,6 +12,7 @@ public enum ClubNoticeErrorStatus implements BaseErrorCode {
     // 공지사항
     NOTICE_NOT_FOUND(HttpStatus.NOT_FOUND, "NOTICE_400", "공지사항을 찾을 수 없습니다."),
     MEETING_NOT_IN_CLUB(HttpStatus.BAD_REQUEST, "NOTICE_401", "공지사항의 모임이 해당 동아리에 속해있지 않습니다."),
+    PINNED_NOTICE_LIMIT_EXCEEDED(HttpStatus.BAD_REQUEST, "NOTICE_402", "고정 공지사항은 최대 5개까지 설정할 수 있습니다."),
 
     // 투표
     INSUFFICIENT_VOTE_ITEMS(HttpStatus.BAD_REQUEST, "VOTE_400", "투표 항목이 2개 미만입니다."),
diff --git a/src/main/java/checkmo/clubNotice/internal/repository/NoticeRepository.java b/src/main/java/checkmo/clubNotice/internal/repository/NoticeRepository.java
@@ -18,7 +18,9 @@ public interface NoticeRepository extends JpaRepository<Notice, Long> {
 
     @Query("SELECT n FROM Notice n "
             + "WHERE n.clubId = :clubId "
-            + "AND n.important = :important "
+            + "AND n.pinned = :pinned "
             + "ORDER BY n.createdAt DESC, n.id DESC ")
-    Page<Notice> findAllByClubIdAndImportant(Long clubId, boolean important, Pageable pageable);
+    Page<Notice> findAllByClubIdAndPinned(Long clubId, boolean pinned, Pageable pageable);
+
+    long countByClubIdAndPinnedTrue(Long clubId);
 }
diff --git a/src/main/java/checkmo/clubNotice/internal/service/ClubNoticeQueryFacade.java b/src/main/java/checkmo/clubNotice/internal/service/ClubNoticeQueryFacade.java
@@ -55,13 +55,13 @@ public ClubNoticePreviewList retrieveClubNoticeList(
             Long clubId,
             String memberId,
             int page,
-            boolean important
+            boolean pinned
     ) {
         clubManagementAPI.validateClub(clubId);
         clubManagementAPI.fetchMembershipInfo(clubId, memberId);
 
         PageResult<Notice> noticePageResult = PagePagingHelper.getPage(
-                pageable -> clubNoticeQueryService.retrieveNotices(clubId, important, pageable),
+                pageable -> clubNoticeQueryService.retrieveNotices(clubId, pinned, pageable),
                 page,
                 DEFAULT_PAGE_SIZE
         );
diff --git a/src/main/java/checkmo/clubNotice/internal/service/command/ClubNoticeCommandService.java b/src/main/java/checkmo/clubNotice/internal/service/command/ClubNoticeCommandService.java
@@ -29,6 +29,8 @@
 @RequiredArgsConstructor
 public class ClubNoticeCommandService {
 
+    private static final int MAX_PINNED_COUNT = 5;
+
     private final ClubManagementAPI clubManagementAPI;
     private final ClubMeetingAPI clubMeetingAPI;
 
@@ -45,6 +47,10 @@ public Notice createNotice(Long clubId, String memberId, CreateClubNotice reques
         if (tag.isMeeting() && !clubMeetingAPI.isMeetingInClub(clubId, request.getMeetingId())) {
             throw new ClubNoticeException(ClubNoticeErrorStatus.MEETING_NOT_IN_CLUB);
         }
+        if (request.isPinned()) {
+            validatePinnedLimit(clubId);
+        }
+
         Notice notice = ClubNoticeConverter.toNotice(request, tag, clubId);
         notice.replaceImages(request.getImageUrls());
         CreateClubVote vote = request.getVote();
@@ -89,10 +95,13 @@ public void updateNotice(Long clubId, Long noticeId, String memberId, UpdateClub
         if (request.getMeetingId() != null && !clubMeetingAPI.isMeetingInClub(clubId, request.getMeetingId())) {
             throw new ClubNoticeException(ClubNoticeErrorStatus.MEETING_NOT_IN_CLUB);
         }
+        if (!notice.isPinned() && request.isPinned()) {
+            validatePinnedLimit(clubId);
+        }
         notice.update(
                 request.getTitle(),
                 request.getContent(),
-                request.isImportant(),
+                request.isPinned(),
                 request.getMeetingId()
         );
         if (request.getVote() != null) {
@@ -106,6 +115,13 @@ public void updateNotice(Long clubId, Long noticeId, String memberId, UpdateClub
         }
     }
 
+    private void validatePinnedLimit(Long clubId) {
+        long pinnedCount = noticeRepository.countByClubIdAndPinnedTrue(clubId);
+        if (pinnedCount >= MAX_PINNED_COUNT) {
+            throw new ClubNoticeException(ClubNoticeErrorStatus.PINNED_NOTICE_LIMIT_EXCEEDED);
+        }
+    }
+
     public void deleteNotice(Long clubId, String memberId, Long noticeId) {
         clubManagementAPI.validateClub(clubId);
         clubManagementAPI.validateStaffClubMember(clubId, memberId);
diff --git a/src/main/java/checkmo/clubNotice/internal/service/query/ClubNoticeQueryService.java b/src/main/java/checkmo/clubNotice/internal/service/query/ClubNoticeQueryService.java
@@ -21,8 +21,8 @@ public Optional<Notice> retrieveNoticeDetailWithVoteAndClubMemberVotes(Long club
         return noticeRepository.findWithVoteAndClubMemberVotesByIdAndClubId(noticeId, clubId);
     }
 
-    public Page<Notice> retrieveNotices(Long clubId, boolean important, Pageable pageable) {
-        return noticeRepository.findAllByClubIdAndImportant(clubId, important, pageable);
+    public Page<Notice> retrieveNotices(Long clubId, boolean pinned, Pageable pageable) {
+        return noticeRepository.findAllByClubIdAndPinned(clubId, pinned, pageable);
     }
 
     public Notice validateNotice(Long clubId, Long noticeId) throws ClubNoticeException {
diff --git a/src/main/java/checkmo/clubNotice/web/controller/ClubNoticeController.java b/src/main/java/checkmo/clubNotice/web/controller/ClubNoticeController.java
@@ -47,10 +47,10 @@ public ApiResponse<ClubNoticePreviewList> getNoticeList(
             @CurrentId String memberId,
             @PathVariable Long clubId,
             @RequestParam(defaultValue = "1") int page,
-            @RequestParam(required = false, defaultValue = "false") boolean important
+            @RequestParam(name = "is-pinned", defaultValue = "false") boolean pinned
     ) {
         return ApiResponse.onSuccess(
-                clubNoticeQueryFacade.retrieveClubNoticeList(clubId, memberId, page, important));
+                clubNoticeQueryFacade.retrieveClubNoticeList(clubId, memberId, page, pinned));
     }
 
     @Operation(summary = "공지사항 상세 조회", description = "공지사항 상세 정보를 조회합니다.")
diff --git a/src/main/java/checkmo/clubNotice/web/dto/ClubNoticeRequestDTO.java b/src/main/java/checkmo/clubNotice/web/dto/ClubNoticeRequestDTO.java
@@ -1,5 +1,6 @@
 package checkmo.clubNotice.web.dto;
 
+import com.fasterxml.jackson.annotation.JsonProperty;
 import jakarta.validation.Valid;
 import jakarta.validation.constraints.AssertTrue;
 import jakarta.validation.constraints.Max;
@@ -10,6 +11,7 @@
 import java.time.LocalDateTime;
 import java.util.HashSet;
 import java.util.List;
+import lombok.AccessLevel;
 import lombok.Getter;
 import lombok.NoArgsConstructor;
 
@@ -23,12 +25,18 @@ public static class CreateClubNotice {
         @NotNull(message = "공지사항 내용은 null이 될 수 없습니다.")
         @Size(max = 1000, message = "공지사항 내용은 1000자 이하로 입력해주세요.")
         private String content;
-        private boolean important;
+        @Getter(AccessLevel.NONE)
+        private boolean pinned;
         private Long meetingId;
         @Size(max = 5, message = "공지사항 이미지는 최대 5개까지 가능합니다.")
         private List<@NotBlank(message = "공지사항 이미지 URL은 비어있을 수 없습니다.") String> imageUrls;
         @Valid
         private CreateClubVote vote;
+
+        @JsonProperty("isPinned")
+        public boolean isPinned() {
+            return pinned;
+        }
     }
 
     @Getter
@@ -70,13 +78,19 @@ public static class UpdateClubNotice {
         @NotNull(message = "공지사항 내용은 null이 될 수 없습니다.")
         @Size(max = 1000, message = "공지사항 내용은 1000자 이하로 입력해주세요.")
         private String content;
-        private boolean important;
+        @Getter(AccessLevel.NONE)
+        private boolean pinned;
         private Long meetingId;
         @Size(max = 5, message = "공지사항 이미지는 최대 5개까지 가능합니다.")
         private List<@NotBlank(message = "공지사항 이미지 URL은 비어있을 수 없습니다.") String> imageUrls;
         // 미포함/null -> 이미지 변경 X, 빈 리스트 -> 이미지 모두 삭제, 값 있음 -> 이미지 교체
         @Valid
         private UpdateClubVote vote;
+
+        @JsonProperty("isPinned")
+        public boolean isPinned() {
+            return pinned;
+        }
     }
 
     @Getter
diff --git a/src/main/java/checkmo/clubNotice/web/dto/ClubNoticeResponseDTO.java b/src/main/java/checkmo/clubNotice/web/dto/ClubNoticeResponseDTO.java
@@ -35,9 +35,15 @@ public static class ClubNoticePreviewList {
     public static final class ClubNoticePreview {
         private Long id;
         private String title;
-        private boolean important;
+        @Getter(AccessLevel.NONE)
+        private boolean pinned;
         private ClubNoticeTagItem tagItem;
         private LocalDateTime createdAt;
+
+        @JsonProperty("isPinned")
+        public boolean isPinned() {
+            return pinned;
+        }
     }
 
     @Getter
@@ -64,14 +70,20 @@ public static final class ClubNoticeDetail {
         private Long id;
         private String title;
         private String content;
-        private boolean important;
+        @Getter(AccessLevel.NONE)
+        private boolean pinned;
         private ClubNoticeTagItem tag;
         private List<String> imageUrls;
         private LocalDateTime createdAt;
         @JsonInclude(JsonInclude.Include.NON_NULL)
         private DetailInfo meetingDetail; // 모임 공지인 경우에만 포함
         @JsonInclude(JsonInclude.Include.NON_NULL)
         private VoteDetail voteDetail; // 투표 공지인 경우에만 포함
+
+        @JsonProperty("isPinned")
+        public boolean isPinned() {
+            return pinned;
+        }
     }
 
     @Getter
diff --git a/src/main/resources/application.yml b/src/main/resources/application.yml
diff --git a/src/main/resources/db/migration/V20260222__rename_notice_important_to_is_pinned.sql b/src/main/resources/db/migration/V20260222__rename_notice_important_to_is_pinned.sql

Original file line number	Diff line number	Diff line change
`@@ -28,6 +28,13 @@ public List<Club> retrieveClubs(ClubRequestDTO.ClubSearchFilter filter, Long cur`
`28`	`28`	`return clubRepository.searchClubs(filter, cursorId, pageSize);`
`29`	`29`	`}`
`30`	`30`
	`31`	`+ public List<Club> retrieveClubs(List<Long> clubIds) {`
	`32`	`+ if (clubIds == null \|\| clubIds.isEmpty()) {`
	`33`	`+ return List.of();`
	`34`	`+ }`
	`35`	`+ return clubRepository.findAllById(clubIds);`
	`36`	`+ }`
	`37`	`+`
`31`	`38`	`public boolean isDuplicateClubName(String clubName) {`
`32`	`39`	`return clubRepository.existsByName(clubName.trim());`
`33`	`40`	`}`