fix: 컬렉션 권한 엔티티 오버로드 방어 로직 추가 및 Swagger 설명 정정

canReadCollection/canWriteCollection/canAdminCollection의 엔티티
오버로드가 호출부의 soft-delete 필터링에만 의존하고 있어, 호출부가
필터링을 빠뜨린 엔티티를 넘기면 삭제된 컬렉션도 권한이 통과될 수
있었다. validateActiveCollection()을 엔티티 오버로드 진입 지점에
추가해 추가 쿼리 없이 자체 방어하도록 한다(CodeRabbit 리뷰 반영).

addDocument()의 Swagger description도 canWriteCollection()이 WRITE뿐
아니라 ADMIN 권한자도 통과시킨다는 실제 동작에 맞게 정정한다.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: kangcheolung

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

@@ -97,7 +97,7 @@ public ResponseEntity<ApiResponse<CollectionResponse>> getCollection(
 
     @Operation(
             summary = "컬렉션에 문서 추가",
-            description = "컬렉션에 문서를 추가합니다. 컬렉션 쓰기 권한(WRITE, 소유자 포함)이 있는 사용자만 가능합니다. 이미 추가된 문서면 409를 반환합니다."
+            description = "컬렉션에 문서를 추가합니다. 컬렉션 쓰기 권한(WRITE 또는 ADMIN, 소유자 포함)이 있는 사용자만 가능합니다. 이미 추가된 문서면 409를 반환합니다."
     )
     @PostMapping("/{collectionId}/documents")
     public ResponseEntity<ApiResponse<CollectionDocumentResponse>> addDocument(

src/main/java/com/opensource/docgrid/domain/permission/service/query/PermissionQueryService.java

@@ -251,8 +251,9 @@ public boolean canReadCollection(Long userId, Long collectionId) {
         return canReadCollection(userId, getActiveCollection(collectionId));
     }
 
-    // 이미 조회된 컬렉션 엔티티로 판단 — 호출부가 이미 non-deleted 엔티티임을 보장해야 함
+    // 이미 조회된 컬렉션 엔티티로 판단 — soft-delete된 엔티티면 COLLECTION_NOT_FOUND
     public boolean canReadCollection(Long userId, DocumentCollection collection) {
+        validateActiveCollection(collection);
         if (collection.getOwner().getId().equals(userId)) return true;
         if (collection.getVisibility() == VisibilityType.PUBLIC) return true;
         Long collectionId = collection.getId();
@@ -267,6 +268,7 @@ public boolean canWriteCollection(Long userId, Long collectionId) {
     }
 
     public boolean canWriteCollection(Long userId, DocumentCollection collection) {
+        validateActiveCollection(collection);
         if (collection.getOwner().getId().equals(userId)) return true;
         Long collectionId = collection.getId();
         if (collectionPermissionRepository.existsUserWritePermission(userId, collectionId)) return true;
@@ -280,6 +282,7 @@ public boolean canAdminCollection(Long userId, Long collectionId) {
     }
 
     public boolean canAdminCollection(Long userId, DocumentCollection collection) {
+        validateActiveCollection(collection);
         if (collection.getOwner().getId().equals(userId)) return true;
         Long collectionId = collection.getId();
         if (collectionPermissionRepository.existsUserAdminPermission(userId, collectionId)) return true;
@@ -288,15 +291,19 @@ public boolean canAdminCollection(Long userId, DocumentCollection collection) {
     }
 
     // collectionId로 조회하되, status가 DELETED인 컬렉션은 필터링해서 제외한다 (없는 것으로 취급).
-    // → DELETED가 아닌 컬렉션만 찾아서 반환하고, 없거나 DELETED면 COLLECTION_NOT_FOUND를 던진다.
-    // collectionId로 조회하는 다른 지점에서도 이 필터링을 동일하게 적용해야
-    // "삭제된 컬렉션을 살아있는 것처럼" 취급하는 구멍이 생기지 않는다.
     private DocumentCollection getActiveCollection(Long collectionId) {
         return collectionRepository.findById(collectionId)
                 .filter(c -> c.getStatus() != CollectionStatus.DELETED)
                 .orElseThrow(() -> new DocGridException(ErrorCode.COLLECTION_NOT_FOUND));
     }
 
+    // 엔티티 오버로드 방어 로직 — 호출부가 soft-delete 필터를 빠뜨리고 넘긴 엔티티도 여기서 최종 차단한다(추가 조회 없음).
+    private void validateActiveCollection(DocumentCollection collection) {
+        if (collection.getStatus() == CollectionStatus.DELETED) {
+            throw new DocGridException(ErrorCode.COLLECTION_NOT_FOUND);
+        }
+    }
+
     private double ms(long fromNano) {
         return (System.nanoTime() - fromNano) / 1_000_000.0;
     }