[Feat] 컬렉션 트리(하위 컬렉션) 지원 + 관련 권한 개선

backend/src/main/java/com/opensource/docgrid/domain/collection/controller/CollectionController.java

@@ -47,19 +47,25 @@ public class CollectionController {
     private final CollectionQueryService collectionQueryService;
 
     @Operation(
-            summary = "내 컬렉션 목록 조회",
-            description = "현재 로그인한 사용자가 소유한 ACTIVE 상태의 컬렉션 목록을 반환합니다."
+            summary = "컬렉션 목록 조회",
+            description = "현재 로그인한 사용자가 읽을 수 있는 ACTIVE 상태의 컬렉션을 최신 생성순으로 페이지 조회합니다. " +
+                    "소유한 컬렉션, PUBLIC 컬렉션, 직접·역할·부서 단위로 권한을 부여받은 컬렉션(부모 컬렉션 상속 포함)을 모두 포함합니다. " +
+                    "keyword를 입력하면 이름·설명에 포함된 것만 필터링합니다."
     )
     @GetMapping
-    public ResponseEntity<ApiResponse<List<CollectionResponse>>> getMyCollections(
-            @Parameter(hidden = true) @CurrentUser Long userId) {
-        return ResponseUtils.ok(collectionQueryService.getMyCollections(userId));
+    public ResponseEntity<ApiResponse<PageResponse<CollectionResponse>>> getCollections(
+            @Parameter(hidden = true) @CurrentUser Long userId,
+            @RequestParam(required = false) String keyword,
+            @RequestParam(defaultValue = "0") @Min(0) int page,
+            @RequestParam(defaultValue = "20") @Min(1) @Max(100) int size) {
+        return ResponseUtils.ok(collectionQueryService.getCollections(userId, keyword, page, size));
     }
 
     @Operation(
             summary = "컬렉션 삭제",
             description = "컬렉션을 soft delete합니다. 소유자(owner)만 가능합니다. " +
-                    "소속 권한(collection_permissions)이 모두 삭제되고, USER 대상 권한이 있었다면 캐시도 무효화됩니다."
+                    "하위 컬렉션 전체와 그 안의 문서 매핑까지 함께 삭제됩니다(cascade). " +
+                    "대상 전체의 소속 권한(collection_permissions)이 모두 삭제되고, USER 대상 권한이 있었다면 캐시도 무효화됩니다."
     )
     @DeleteMapping("/{collectionId}")
     public ResponseEntity<ApiResponse<Void>> deleteCollection(
@@ -105,6 +111,18 @@ public ResponseEntity<ApiResponse<CollectionResponse>> getCollection(
         return ResponseUtils.ok(collectionQueryService.getCollection(userId, collectionId));
     }
 
+    @Operation(
+            summary = "직계 자식 컬렉션 목록 조회",
+            description = "이 컬렉션 바로 아래에 있는 하위 컬렉션 목록을 반환합니다. 하위 컬렉션 자체까지만 반환하며, " +
+                    "더 아래 단계를 보려면 반환된 하위 컬렉션 ID로 이 API를 다시 호출해야 합니다."
+    )
+    @GetMapping("/{collectionId}/children")
+    public ResponseEntity<ApiResponse<List<CollectionResponse>>> getChildren(
+            @PathVariable Long collectionId,
+            @Parameter(hidden = true) @CurrentUser Long userId) {
+        return ResponseUtils.ok(collectionQueryService.getChildren(userId, collectionId));
+    }
+
     @Operation(
             summary = "컬렉션 문서 목록 조회",
             description = "컬렉션을 읽을 수 있는 사용자가 개별 문서 읽기 권한도 가진 항목만 추가 최신순으로 페이지 조회합니다. " +

backend/src/main/java/com/opensource/docgrid/domain/collection/repository/CollectionDocumentRepository.java

@@ -17,6 +17,9 @@ public interface CollectionDocumentRepository extends JpaRepository<CollectionDo
 
     List<CollectionDocument> findAllByCollectionId(Long collectionId);
 
+    // cascade 삭제용 — 대상 컬렉션 ID 목록(자기 자신+후손 전체)에 속한 문서 매핑 전체 조회
+    List<CollectionDocument> findAllByCollectionIdIn(List<Long> collectionIds);
+
     /**
      * 권한 선필터를 통과한 컬렉션 문서를 현재 버전 Metadata와 함께 페이지 조회한다.
      */

backend/src/main/java/com/opensource/docgrid/domain/collection/repository/CollectionRepository.java

@@ -2,13 +2,121 @@
 
 import java.util.List;
 
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.Pageable;
 import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
 
 import com.opensource.docgrid.domain.collection.entity.DocumentCollection;
 import com.opensource.docgrid.domain.collection.enums.CollectionStatus;
 
 public interface CollectionRepository extends JpaRepository<DocumentCollection, Long> {
 
-    // 소유자 기준 상태별 컬렉션 목록 조회 (GET /collections)
-    List<DocumentCollection> findAllByOwnerIdAndStatus(Long ownerId, CollectionStatus status);
+    /**
+     * 사용자가 읽을 수 있는 컬렉션 ID 전체 (GET /collections pre-filter).
+     * 4가지 접근 경로: OWNER / PUBLIC / USER 직접 권한 / ROLE·DEPARTMENT live(부모 컬렉션 체인 상속 포함).
+     * ACTIVE 상태만 대상으로 하며, keyword가 있으면 이름·설명 부분일치로도 필터링한다(keyword는 null 가능).
+     */
+    @Query(value = """
+            WITH RECURSIVE collection_ancestors AS (
+                SELECT id AS collection_id, id AS ancestor_id FROM collections
+                UNION ALL
+                SELECT ca.collection_id, c.parent_collection_id AS ancestor_id
+                FROM collection_ancestors ca
+                JOIN collections c ON c.id = ca.ancestor_id
+                WHERE c.parent_collection_id IS NOT NULL
+            )
+            SELECT c.id FROM collections c
+            WHERE c.owner_user_id = :userId AND c.status = 'ACTIVE'
+              AND (:keyword IS NULL OR c.name ILIKE CONCAT('%', :keyword, '%') OR c.description ILIKE CONCAT('%', :keyword, '%'))
+            UNION
+            SELECT c.id FROM collections c
+            WHERE c.visibility = 'PUBLIC' AND c.status = 'ACTIVE'
+              AND (:keyword IS NULL OR c.name ILIKE CONCAT('%', :keyword, '%') OR c.description ILIKE CONCAT('%', :keyword, '%'))
+            UNION
+            SELECT c.id FROM collections c
+              JOIN collection_permissions cp ON cp.collection_id = c.id
+            WHERE cp.target_type = 'USER' AND cp.user_id = :userId AND cp.can_read = true
+              AND (cp.expires_at IS NULL OR cp.expires_at > NOW())
+              AND c.status = 'ACTIVE'
+              AND (:keyword IS NULL OR c.name ILIKE CONCAT('%', :keyword, '%') OR c.description ILIKE CONCAT('%', :keyword, '%'))
+            UNION
+            SELECT c.id FROM collections c
+              JOIN collection_ancestors ca ON ca.collection_id = c.id
+              JOIN collection_permissions cp ON cp.collection_id = ca.ancestor_id
+              JOIN user_roles ur ON ur.role_id = cp.role_id
+            WHERE cp.target_type = 'ROLE' AND ur.user_id = :userId AND cp.can_read = true
+              AND (cp.expires_at IS NULL OR cp.expires_at > NOW())
+              AND c.status = 'ACTIVE'
+              AND (:keyword IS NULL OR c.name ILIKE CONCAT('%', :keyword, '%') OR c.description ILIKE CONCAT('%', :keyword, '%'))
+            UNION
+            SELECT c.id FROM collections c
+              JOIN collection_ancestors ca ON ca.collection_id = c.id
+              JOIN collection_permissions cp ON cp.collection_id = ca.ancestor_id
+              JOIN users u ON u.department_id = cp.department_id
+            WHERE cp.target_type = 'DEPARTMENT' AND u.id = :userId AND cp.can_read = true
+              AND (cp.expires_at IS NULL OR cp.expires_at > NOW())
+              AND c.status = 'ACTIVE'
+              AND (:keyword IS NULL OR c.name ILIKE CONCAT('%', :keyword, '%') OR c.description ILIKE CONCAT('%', :keyword, '%'))
+            """, nativeQuery = true)
+    List<Long> findReadableCollectionIds(@Param("userId") Long userId, @Param("keyword") String keyword);
+
+    // pre-filter로 걸러진 ID를 받아 정렬·페이징만 담당 (GET /collections)
+    @Query("SELECT c FROM DocumentCollection c JOIN FETCH c.owner WHERE c.id IN :ids")
+    Page<DocumentCollection> findAllByIdIn(@Param("ids") List<Long> ids, Pageable pageable);
+
+    // 직계 자식 컬렉션 목록 조회 (GET /collections/{id}/children)
+    List<DocumentCollection> findAllByParentCollectionIdAndStatus(Long parentCollectionId, CollectionStatus status);
+
+    /**
+     * 자기 자신 + 모든 조상 컬렉션 ID (권한 상속 판단용).
+     * 삭제된 조상도 결과에 포함한다 — 삭제된 컬렉션은 권한이 비어있어 무해하고,
+     * status 필터를 넣으면 중간 조상이 삭제됐을 때 그 위 조상으로 체인이 끊기는 문제가 생긴다.
+     */
+    @Query(value = """
+            WITH RECURSIVE ancestors AS (
+                SELECT id, parent_collection_id FROM collections WHERE id = :collectionId
+                UNION ALL
+                SELECT c.id, c.parent_collection_id
+                FROM collections c
+                JOIN ancestors a ON c.id = a.parent_collection_id
+            )
+            SELECT id FROM ancestors
+            """, nativeQuery = true)
+    List<Long> findAncestorIdsInclusive(@Param("collectionId") Long collectionId);
+
+    /**
+     * 자기 자신 + 모든 후손 컬렉션 ID (cascade 삭제 대상 판단용).
+     */
+    @Query(value = """
+            WITH RECURSIVE descendants AS (
+                SELECT id, parent_collection_id FROM collections WHERE id = :collectionId
+                UNION ALL
+                SELECT c.id, c.parent_collection_id
+                FROM collections c
+                JOIN descendants d ON c.parent_collection_id = d.id
+            )
+            SELECT id FROM descendants
+            """, nativeQuery = true)
+    List<Long> findDescendantIdsInclusive(@Param("collectionId") Long collectionId);
+
+    /**
+     * 문서가 속한 모든 컬렉션(N:M) + 그 컬렉션들 각각의 조상 전체 ID (문서 권한 상속 판단용).
+     */
+    @Query(value = """
+            WITH RECURSIVE ancestors AS (
+                SELECT c.id, c.parent_collection_id
+                FROM collections c
+                WHERE c.id IN (
+                    SELECT DISTINCT cd.collection_id FROM collection_documents cd WHERE cd.document_id = :documentId
+                )
+                UNION ALL
+                SELECT c.id, c.parent_collection_id
+                FROM collections c
+                JOIN ancestors a ON c.id = a.parent_collection_id
+            )
+            SELECT DISTINCT id FROM ancestors
+            """, nativeQuery = true)
+    List<Long> findEffectiveCollectionIdsForDocument(@Param("documentId") Long documentId);
 }

backend/src/main/java/com/opensource/docgrid/domain/collection/service/command/CollectionCommandService.java

@@ -53,7 +53,11 @@ public CollectionResponse createCollection(Long userId, CreateCollectionRequest
         DocumentCollection parentCollection = null; // 상위 폴더 지정은 선택 사항이라 null로 초기화
         if (request.parentCollectionId() != null) {
             parentCollection = collectionRepository.findById(request.parentCollectionId())
+                    .filter(c -> c.getStatus() != CollectionStatus.DELETED)
                     .orElseThrow(() -> new DocGridException(ErrorCode.COLLECTION_NOT_FOUND));
+            if (!permissionQueryService.canWriteCollection(userId, parentCollection)) {
+                throw new DocGridException(ErrorCode.PERMISSION_DENIED);
+            }
         }
 
         VisibilityType visibility = request.visibility() != null ? request.visibility() : VisibilityType.PRIVATE;
@@ -102,25 +106,34 @@ public CollectionDocumentResponse addDocument(Long collectionId, Long userId, Ad
         return collectionConverter.toDocumentResponse(collectionDocument);
     }
 
-    // 컬렉션 soft delete — 소유자만 가능
+    // 컬렉션 soft delete — 소유자만 가능. 하위 컬렉션 전체와 그 안의 문서 매핑까지 cascade로 함께 삭제한다.
+    // owner 체크는 삭제 대상 최상위(root)에서만 하고 하위 각각은 재확인하지 않는다
+    // (구글드라이브 공유폴더 삭제와 동일한 멘탈모델 — root에 대한 권한으로 하위 전체가 지워짐).
     public void deleteCollection(Long collectionId, Long userId) {
-        DocumentCollection collection = collectionRepository.findById(collectionId)
+        DocumentCollection root = collectionRepository.findById(collectionId)
                 .filter(c -> c.getStatus() != CollectionStatus.DELETED)
                 .orElseThrow(() -> new DocGridException(ErrorCode.COLLECTION_NOT_FOUND));
 
-        if (!collection.getOwner().getId().equals(userId)) {
+        if (!root.getOwner().getId().equals(userId)) {
             throw new DocGridException(ErrorCode.PERMISSION_DENIED);
         }
 
-        // 폴더에 속한 모든 권한 삭제 및 캐시 무효화
-        List<CollectionPermission> permissions = collectionPermissionRepository.findAllByCollectionId(collectionId);
+        List<Long> targetIds = collectionRepository.findDescendantIdsInclusive(collectionId); // 자기 자신 포함
+
+        // 대상 전체(자기 자신+하위)에 속한 권한 삭제 및 캐시 무효화
+        List<CollectionPermission> permissions = collectionPermissionRepository.findAllByCollectionIdIn(targetIds);
         permissions.stream()
                 .filter(p -> p.getTargetType() == PermissionTargetType.USER)
             // 컬렉션 권한이 USER 대상인 경우에만 캐시 무효화
                 .forEach(p -> cacheService.bulkRevokeBySource(AccessSourceType.DIRECT_COLLECTION_PERMISSION, p.getId()));
         collectionPermissionRepository.deleteAll(permissions); // 컬렉션 권한 삭제
 
-        collection.markDeleted(LocalDateTime.now()); // 폴더 상태를 DELETED로 변경
+        // 대상 전체(자기 자신+하위)의 문서 매핑 삭제
+        List<CollectionDocument> mappings = collectionDocumentRepository.findAllByCollectionIdIn(targetIds);
+        collectionDocumentRepository.deleteAll(mappings);
+
+        LocalDateTime now = LocalDateTime.now();
+        collectionRepository.findAllById(targetIds).forEach(c -> c.markDeleted(now)); // 대상 전체 상태를 DELETED로 변경
     }
 
     // 컬렉션에서 문서 제거 — 소유자만 가능

backend/src/main/java/com/opensource/docgrid/domain/collection/service/query/CollectionQueryService.java

@@ -39,6 +39,10 @@ public class CollectionQueryService {
             Sort.Order.desc("addedAt"),
             Sort.Order.desc("id")
     );
+    private static final Sort COLLECTION_SORT = Sort.by(
+            Sort.Order.desc("createdAt"),
+            Sort.Order.desc("id")
+    );
 
     private final CollectionRepository collectionRepository;
     private final CollectionDocumentRepository collectionDocumentRepository;
@@ -57,10 +61,37 @@ public CollectionResponse getCollection(Long userId, Long collectionId) {
         return collectionConverter.toResponse(collection);
     }
 
-    // 내 컬렉션 목록 조회 (ACTIVE 상태만)
-    public List<CollectionResponse> getMyCollections(Long userId) {
-        return collectionRepository.findAllByOwnerIdAndStatus(userId, CollectionStatus.ACTIVE)
+    /**
+     * 사용자가 읽을 수 있는 컬렉션 목록 페이지 조회 (owner + PUBLIC + 권한부여 + 부모 상속, ACTIVE만).
+     * keyword가 있으면 이름·설명 부분일치로도 필터링한다.
+     */
+    public PageResponse<CollectionResponse> getCollections(Long userId, String keyword, int page, int size) {
+        Pageable pageable = PageRequest.of(page, size, COLLECTION_SORT);
+        List<Long> readableIds = collectionRepository.findReadableCollectionIds(userId, keyword);
+        if (readableIds.isEmpty()) {
+            return PageResponse.from(Page.empty(pageable), List.of());
+        }
+
+        Page<DocumentCollection> collections = collectionRepository.findAllByIdIn(readableIds, pageable);
+        List<CollectionResponse> content = collections.getContent().stream()
+                .map(collectionConverter::toResponse)
+                .toList();
+        return PageResponse.from(collections, content);
+    }
+
+    // 직계 자식 컬렉션 목록 조회 — 부모 읽기 권한 확인 후, 자식 각각의 읽기 권한도 확인
+    // (자식 owner/visibility가 부모와 다를 수 있으므로 부모 권한만으로 자식을 노출하면 안 됨)
+    public List<CollectionResponse> getChildren(Long userId, Long collectionId) {
+        DocumentCollection parent = collectionRepository.findById(collectionId)
+                .filter(c -> c.getStatus() != CollectionStatus.DELETED)
+                .orElseThrow(() -> new DocGridException(ErrorCode.COLLECTION_NOT_FOUND));
+        if (!permissionQueryService.canReadCollection(userId, parent)) {
+            throw new DocGridException(ErrorCode.PERMISSION_DENIED);
+        }
+
+        return collectionRepository.findAllByParentCollectionIdAndStatus(collectionId, CollectionStatus.ACTIVE)
                 .stream()
+                .filter(child -> permissionQueryService.canReadCollection(userId, child))
                 .map(collectionConverter::toResponse)
                 .toList();
     }