[Docs] 권한 도메인 리포지토리/서비스 그룹 설명 주석 추가

backend/src/main/java/com/opensource/docgrid/domain/permission/repository/CollectionPermissionRepository.java

@@ -10,6 +10,10 @@
 
 public interface CollectionPermissionRepository extends JpaRepository<CollectionPermission, Long> {
 
+    /**
+     * 기본 조회 — 삭제/목록 용도 (3개)
+     */
+
     // 컬렉션에 속한 권한 전체 조회 (soft delete 시 캐시 무효화 + 권한 삭제용)
     List<CollectionPermission> findAllByCollectionId(Long collectionId);
 
@@ -32,6 +36,13 @@ public interface CollectionPermissionRepository extends JpaRepository<Collection
             """)
     List<CollectionPermission> findAllWithTargetsByCollectionId(@Param("collectionId") Long collectionId);
 
+    /**
+     * ① 문서 기준 live 체크 — ROLE/DEPARTMENT 대상만 (ROLE 3개 + DEPT 3개 = 6개)
+     *
+     * <p>문서가 속한 컬렉션에 걸린 권한을 확인한다. USER 대상은 캐시(UserDocumentAccessCache)로
+     * 판단하므로 여기 없음. 직속 컬렉션만 보고 조상 컬렉션 상속은 보지 않는다(④가 담당).
+     */
+
     // ROLE live — 사용자 역할 기반 컬렉션→문서 읽기 권한 존재 여부
     @Query("""
             SELECT COUNT(cp) > 0 FROM CollectionPermission cp
@@ -110,6 +121,12 @@ SELECT COUNT(cp) > 0 FROM CollectionPermission cp
             """)
     boolean existsDeptAdminPermissionForDocument(@Param("userId") Long userId, @Param("documentId") Long documentId);
 
+    /**
+     * ② 컬렉션 단건 — USER 대상 (3개)
+     *
+     * <p>"컬렉션 자체"에 대한 USER 직접 권한. 문서 캐시 대상이 아니라서 항상 라이브로 확인한다.
+     */
+
     // USER 직접 권한 — 컬렉션에 읽기 권한이 있는지 (canReadCollection 판단용)
     @Query("""
             SELECT COUNT(cp) > 0 FROM CollectionPermission cp
@@ -143,6 +160,12 @@ SELECT COUNT(cp) > 0 FROM CollectionPermission cp
             """)
     boolean existsUserAdminPermission(@Param("userId") Long userId, @Param("collectionId") Long collectionId);
 
+    /**
+     * ③ 컬렉션 단건 — ROLE/DEPARTMENT 대상 (ROLE 3개 + DEPT 3개 = 6개)
+     *
+     * <p>"컬렉션 자체"에 걸린 ROLE/DEPARTMENT 권한. 조상 컬렉션 상속은 보지 않음(④가 담당).
+     */
+
     // ROLE live — 사용자 역할 기반 컬렉션 읽기 권한 존재 여부 (canReadCollection 판단용)
     @Query("""
             SELECT COUNT(cp) > 0 FROM CollectionPermission cp
@@ -215,8 +238,12 @@ SELECT COUNT(cp) > 0 FROM CollectionPermission cp
             """)
     boolean existsDeptAdminPermissionForCollection(@Param("userId") Long userId, @Param("collectionId") Long collectionId);
 
-    // 컬렉션 트리 상속용 — 컬렉션 ID 목록(자기 자신+조상 또는 문서가 속한 컬렉션+조상) 중
-    // 하나라도 ROLE/DEPARTMENT 권한이 있으면 true. 기존 단일-ID 메서드는 그대로 두고 추가로 병행한다.
+    /**
+     * ④ 컬렉션 리스트(조상 체인) — ROLE/DEPARTMENT 대상 (ROLE 3개 + DEPT 3개 = 6개)
+     *
+     * <p>컬렉션 트리 상속용 — 컬렉션 ID 목록(자기 자신+조상 또는 문서가 속한 컬렉션+조상) 중
+     * 하나라도 ROLE/DEPARTMENT 권한이 있으면 true. 기존 단일-ID 메서드(③)는 그대로 두고 추가로 병행한다.
+     */
 
     @Query("""
             SELECT COUNT(cp) > 0 FROM CollectionPermission cp

backend/src/main/java/com/opensource/docgrid/domain/permission/repository/DocumentPermissionRepository.java

@@ -10,6 +10,10 @@
 
 public interface DocumentPermissionRepository extends JpaRepository<DocumentPermission, Long> {
 
+    /**
+     * 그룹 1 — 기본 조회 (1개)
+     */
+
     /**
      * 문서에 직접 부여된 권한을 대상·부여자 정보와 함께 최신순으로 조회한다.
      */
@@ -26,6 +30,14 @@ public interface DocumentPermissionRepository extends JpaRepository<DocumentPerm
             """)
     List<DocumentPermission> findAllWithTargetsByDocumentId(@Param("documentId") Long documentId);
 
+    /**
+     * 그룹 2 — ROLE/DEPARTMENT live 체크 (ROLE 3개 + DEPT 3개 = 6개)
+     *
+     * <p>문서 자체에 직접 걸린 예외 권한(document_permissions)만 확인한다. 중간 조인 테이블 없이
+     * dp.document.id로 바로 필터링 — CollectionPermissionRepository ①(컬렉션 경유)과 다름.
+     * USER 대상은 없음(캐시로 판단), 조상 리스트 버전도 없음(문서는 트리 구조가 아님).
+     */
+
     // ROLE live — 사용자 역할 기반 문서 읽기 권한 존재 여부
     @Query("""
             SELECT COUNT(dp) > 0 FROM DocumentPermission dp

backend/src/main/java/com/opensource/docgrid/domain/permission/repository/UserDocumentAccessCacheRepository.java

@@ -14,10 +14,21 @@
 
 public interface UserDocumentAccessCacheRepository extends JpaRepository<UserDocumentAccessCache, Long> {
 
+    /**
+     * 그룹 1 — 단건 조회 (1개)
+     */
+
     // 특정 권한 출처(sourceType + sourceId)의 캐시 단건 조회
     Optional<UserDocumentAccessCache> findByUserIdAndDocumentIdAndSourceTypeAndSourceId(
             Long userId, Long documentId, AccessSourceType sourceType, Long sourceId);
 
+    /**
+     * 그룹 2 — {@code @Modifying} 벌크 쓰기 (3개)
+     *
+     * <p>캐시를 직접 INSERT/UPDATE하는 유일한 그룹. 벌크 UPDATE는 영속성 컨텍스트를 거치지
+     * 않고 DB를 직접 치므로 clearAutomatically=true로 stale 엔티티를 방지한다.
+     */
+
     // 특정 권한 출처에서 파생된 캐시 전체 무효화 (invalidated_at 일괄 설정)
     @Modifying(clearAutomatically = true)
     @Query("""
@@ -56,6 +67,13 @@ int bulkUpdateBySource(@Param("userId") Long userId,
                            @Param("canAdmin") boolean canAdmin,
                            @Param("expiresAt") LocalDateTime expiresAt);
 
+    /**
+     * 그룹 3 — 벌크 INSERT 보조 조회 (1개)
+     *
+     * <p>bulkUpdateBySource로 기존 row를 갱신한 뒤, 여기서 "이미 캐시된 문서 ID"를 뽑아
+     * 신규 문서만 걸러서 saveAll()로 INSERT한다(유니크 제약 위반 방지).
+     */
+
     // 특정 권한 출처에서 이미 캐시된 문서 ID 목록 조회 (배치 INSERT 시 중복 방지용)
     @Query("""
             SELECT c.document.id FROM UserDocumentAccessCache c
@@ -66,6 +84,12 @@ List<Long> findDocumentIdsByUserIdAndSourceTypeAndSourceId(
             @Param("sourceType") AccessSourceType sourceType,
             @Param("sourceId") Long sourceId);
 
+    /**
+     * 그룹 4 — 유효성 존재 체크 (3개)
+     *
+     * <p>PermissionQueryService의 "3단계: USER 캐시" 판단에서 호출된다.
+     */
+
     // 유효한 읽기 캐시 존재 여부 (invalidated_at IS NULL, 만료 미포함)
     @Query("""
             SELECT COUNT(c) > 0 FROM UserDocumentAccessCache c

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

@@ -69,7 +69,7 @@ public List<CollectionPermissionResponse> getCollectionPermissions(Long userId,
                 .toList();
     }
 
-    // 문서 읽기 권한 판단 (5단계)
+    // 문서 읽기 권한 판단 (6단계)
     public boolean canReadDocument(Long userId, Long documentId) {
         long start = System.nanoTime();
         Document document = documentRepository.findById(documentId)
@@ -135,18 +135,20 @@ public boolean canReadDocument(Long userId, Long documentId) {
         return false;
     }
 
-    // 문서 쓰기 권한 판단 (4단계)
+    // 문서 쓰기 권한 판단 (5단계)
     public boolean canWriteDocument(Long userId, Long documentId) {
         long start = System.nanoTime();
         Document document = documentRepository.findById(documentId)
                 .orElseThrow(() -> new DocGridException(ErrorCode.DOCUMENT_NOT_FOUND));
 
+        // 1단계: 소유자
         long t1 = System.nanoTime();
         if (document.getOwner().getId().equals(userId)) {
             log.info("[PERM] canWrite owner=true doc={} user={} elapsed={}ms", documentId, userId, ms(start));
             return true;
         }
 
+        // 2단계: USER 캐시
         long t2 = System.nanoTime();
         double step1Ms = (t2 - t1) / 1_000_000.0;
         if (cacheRepository.existsValidWriteCache(userId, documentId)) {
@@ -155,6 +157,7 @@ public boolean canWriteDocument(Long userId, Long documentId) {
             return true;
         }
 
+        // 3단계: ROLE live
         long t3 = System.nanoTime();
         double step2Ms = (t3 - t2) / 1_000_000.0;
         if (documentPermissionRepository.existsRoleWritePermission(userId, documentId)
@@ -164,6 +167,7 @@ public boolean canWriteDocument(Long userId, Long documentId) {
             return true;
         }
 
+        // 4단계: DEPARTMENT live
         long t4 = System.nanoTime();
         double step3Ms = (t4 - t3) / 1_000_000.0;
         if (documentPermissionRepository.existsDeptWritePermission(userId, documentId)
@@ -188,18 +192,20 @@ public boolean canWriteDocument(Long userId, Long documentId) {
         return false;
     }
 
-    // 문서 관리 권한 판단 (4단계)
+    // 문서 관리 권한 판단 (5단계)
     public boolean canAdminDocument(Long userId, Long documentId) {
         long start = System.nanoTime();
         Document document = documentRepository.findById(documentId)
                 .orElseThrow(() -> new DocGridException(ErrorCode.DOCUMENT_NOT_FOUND));
 
+        // 1단계: 소유자
         long t1 = System.nanoTime();
         if (document.getOwner().getId().equals(userId)) {
             log.info("[PERM] canAdmin owner=true doc={} user={} elapsed={}ms", documentId, userId, ms(start));
             return true;
         }
 
+        // 2단계: USER 캐시
         long t2 = System.nanoTime();
         double step1Ms = (t2 - t1) / 1_000_000.0;
         if (cacheRepository.existsValidAdminCache(userId, documentId)) {
@@ -208,6 +214,7 @@ public boolean canAdminDocument(Long userId, Long documentId) {
             return true;
         }
 
+        // 3단계: ROLE live
         long t3 = System.nanoTime();
         double step2Ms = (t3 - t2) / 1_000_000.0;
         if (documentPermissionRepository.existsRoleAdminPermission(userId, documentId)
@@ -217,6 +224,7 @@ public boolean canAdminDocument(Long userId, Long documentId) {
             return true;
         }
 
+        // 4단계: DEPARTMENT live
         long t4 = System.nanoTime();
         double step3Ms = (t4 - t3) / 1_000_000.0;
         if (documentPermissionRepository.existsDeptAdminPermission(userId, documentId)