[Docs] 권한 블록 설계 문서 보강 - #81
Conversation
|
Warning Review limit reached
Next review available in: 44 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (4)
📝 WalkthroughWalkthrough컬렉션 CRUD와 권한 부여·회수·판단·관리 설계 문서 5개가 엔티티, 서비스, 리포지토리, DTO, 컨트롤러, 캐시 처리 및 테스트 결과를 포함하도록 보강되었다. Changes컬렉션 및 권한 설계
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested labels: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/design/kangcheolung-`#16-collection-crud.md:
- Around line 160-166: 문서 추가 흐름의 addDocument에서 컬렉션을 조회한 뒤 ACTIVE 상태인지 검증하고,
DELETED 컬렉션에는 문서를 추가할 수 없도록 명시하세요. 단건 조회 흐름도 동일한 ACTIVE 검증 또는 삭제 상태 제외 조회를 적용하도록
명시하고, 삭제된 컬렉션의 추가·조회 응답을 테스트로 고정하세요. 대상 사이트는
docs/design/kangcheolung-#16-collection-crud.md 160-166(anchor),
192-195(sibling)이며 두 위치 모두 해당 변경을 반영해야 합니다.
In `@docs/design/kangcheolung-`#18-permission-grant-revoke.md:
- Line 158: 권한 위임 정책을 ADMIN 위임자까지 허용할지 하나로 확정하고,
docs/design/kangcheolung-#18-permission-grant-revoke.md 158행의 설계 설명과
docs/design/kangcheolung-#16-collection-crud.md 186-187행의 canWriteCollection()
설명을 동일한 정책으로 수정하세요. 확정한 정책에 맞춰 CollectionController의 OpenAPI owner-only 설명, 서비스
권한 검사, 관련 테스트도 일관되게 갱신하세요.
- Around line 9-11: 캐시 대상 정책을 USER 권한과 OWNER 소유권 중 무엇을 포함할지 확정하고 모든 문서에서 동일하게
명시하세요. docs/design/kangcheolung-#18-permission-grant-revoke.md의 9-11행은 캐시 대상
설명을, 50-56행은 source of truth와 소유권 캐시 설명을, 102-104행은 OWNER source의 실제 생성·조회·무효화
규칙을 확정된 정책에 맞게 수정하세요. docs/design/kangcheolung-#21-permission-query-service.md
17-23행도 같은 정책으로 갱신해 검색 pre-filter와 최종 권한 판단이 일치하도록 하세요.
In `@docs/design/kangcheolung-`#29-collection-management.md:
- Line 119: The design document’s related comments at
docs/design/kangcheolung-#29-collection-management.md:119-119 and
docs/design/kangcheolung-#29-collection-management.md:224-224 incorrectly claim
empty JPQL IN parameters are safely executed. Update both comments to remove
that assertion and state that removeDocument() deletes the document link, then
skips cache invalidation when the permission/source ID list is empty; retain the
distinction that non-empty IDs use document-scoped invalidation rather than
collection-wide invalidation.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 4ec3ebd4-54d0-42e2-ad86-8c0816d29c5c
📒 Files selected for processing (5)
docs/design/kangcheolung-#16-collection-crud.mddocs/design/kangcheolung-#18-permission-grant-revoke.mddocs/design/kangcheolung-#21-permission-query-service.mddocs/design/kangcheolung-#24-document-permission-check.mddocs/design/kangcheolung-#29-collection-management.md
| public CollectionDocumentResponse addDocument(Long collectionId, Long userId, AddDocumentRequest request) { | ||
| DocumentCollection collection = collectionRepository.findById(collectionId) | ||
| .orElseThrow(() -> new DocGridException(ErrorCode.COLLECTION_NOT_FOUND)); | ||
|
|
||
| ```json | ||
| { | ||
| "id": 3, | ||
| "name": "설계 문서", | ||
| "description": "설계 관련 문서 모음", | ||
| "visibility": "PRIVATE", | ||
| "status": "ACTIVE", | ||
| "ownerId": 1 | ||
| } | ||
| ``` | ||
| if (!permissionQueryService.canWriteCollection(userId, collectionId)) { | ||
| throw new DocGridException(ErrorCode.PERMISSION_DENIED); | ||
| } |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
soft-deleted 컬렉션의 접근을 ACTIVE 상태로 제한하세요.
현재 흐름은 findById() 후 상태를 확인하지 않고 문서를 추가하며, 단건 조회도 동일하게 ID만 조회합니다. #29의 soft delete가 DELETED 상태를 남기는 계약이라면 삭제된 컬렉션에 문서를 추가하거나 메타데이터를 조회할 수 있습니다. ACTIVE 검증을 공통 서비스/repository에 추가하고 삭제 상태의 응답을 테스트로 고정하세요.
docs/design/kangcheolung-#16-collection-crud.md#L160-L166: 문서 추가 전ACTIVE상태 검증을 명시하세요.docs/design/kangcheolung-#16-collection-crud.md#L192-L195: 단건 조회도 삭제 상태를 제외하도록 명시하세요.
📍 Affects 1 file
docs/design/kangcheolung-#16-collection-crud.md#L160-L166(this comment)docs/design/kangcheolung-#16-collection-crud.md#L192-L195
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/design/kangcheolung-`#16-collection-crud.md around lines 160 - 166, 문서
추가 흐름의 addDocument에서 컬렉션을 조회한 뒤 ACTIVE 상태인지 검증하고, DELETED 컬렉션에는 문서를 추가할 수 없도록
명시하세요. 단건 조회 흐름도 동일한 ACTIVE 검증 또는 삭제 상태 제외 조회를 적용하도록 명시하고, 삭제된 컬렉션의 추가·조회 응답을
테스트로 고정하세요. 대상 사이트는 docs/design/kangcheolung-#16-collection-crud.md
160-166(anchor), 192-195(sibling)이며 두 위치 모두 해당 변경을 반영해야 합니다.
| `#16`에서 컬렉션 CRUD 기본을 만들었지만, 아직 "누가 이 컬렉션/문서를 볼 수 있는지"를 실제로 부여·회수하는 API가 없었다. 이번 이슈는 그 권한 부여/회수 API와, 검색 pre-filter를 빠르게 만들기 위한 `user_document_access_cache` 갱신 로직을 만든다. | ||
|
|
||
| RAG 명세 초반에 이미 정리된 3단계 캐싱 전략(`project_docgrid_specs.md` 메모리 참고)이 여기서 구현된다: **USER 대상 권한만 캐시에 저장**하고, ROLE/DEPARTMENT는 구성원이 동적으로 바뀌므로 캐시하지 않고 매번 live 조회한다. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
캐시 대상 정책을 하나의 불변식으로 정리하세요.
#18은 USER 권한만 캐시한다고 설명하면서도 Javadoc과 AccessSourceType.OWNER는 소유권 캐시를 포함한다고 기술합니다. 반면 #21은 USER만 캐시한다고 단정합니다. OWNER 캐시를 실제로 생성·조회·무효화하는지 결정하고, 검색 pre-filter와 최종 권한 판단 문서를 동일한 정책으로 맞춰야 합니다.
docs/design/kangcheolung-#18-permission-grant-revoke.md#L9-L11: 캐시 대상 설명을 수정하세요.docs/design/kangcheolung-#18-permission-grant-revoke.md#L50-L56: source of truth 및 소유권 캐시 설명을 일치시키세요.docs/design/kangcheolung-#18-permission-grant-revoke.md#L102-L104:OWNERsource의 실제 생성·사용 규칙을 명시하세요.docs/design/kangcheolung-#21-permission-query-service.md#L17-L23: 확정된 캐시 정책에 맞춰 수정하세요.
📍 Affects 2 files
docs/design/kangcheolung-#18-permission-grant-revoke.md#L9-L11(this comment)docs/design/kangcheolung-#18-permission-grant-revoke.md#L50-L56docs/design/kangcheolung-#18-permission-grant-revoke.md#L102-L104docs/design/kangcheolung-#21-permission-query-service.md#L17-L23
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/design/kangcheolung-`#18-permission-grant-revoke.md around lines 9 - 11,
캐시 대상 정책을 USER 권한과 OWNER 소유권 중 무엇을 포함할지 확정하고 모든 문서에서 동일하게 명시하세요.
docs/design/kangcheolung-#18-permission-grant-revoke.md의 9-11행은 캐시 대상 설명을,
50-56행은 source of truth와 소유권 캐시 설명을, 102-104행은 OWNER source의 실제 생성·조회·무효화 규칙을
확정된 정책에 맞게 수정하세요. docs/design/kangcheolung-#21-permission-query-service.md
17-23행도 같은 정책으로 갱신해 검색 pre-filter와 최종 권한 판단이 일치하도록 하세요.
| ``` | ||
|
|
||
| ### 컬렉션 권한 회수 | ||
| **권한을 부여하려면 권한 부여자(`grantorId`)가 이미 `canAdminCollection`이어야 한다** — `#21`의 `PermissionQueryService`를 여기서도 재사용한다. `#16`의 `owner`만 되던 것과 달리, 이제 ADMIN 권한을 가진 사람(소유자 포함, ADMIN으로 위임받은 사람도 포함)이 다른 사람에게 권한을 나눠줄 수 있다. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
권한 위임 정책을 문서·컨트롤러·서비스에서 일치시키세요.
설계 문서는 ADMIN 권한 위임자가 권한을 부여하거나 컬렉션을 수정할 수 있다고 설명하지만, 제공된 CollectionController.java의 API 설명은 해당 동작을 owner-only로 명시합니다. 실제 정책을 하나로 결정한 뒤 서비스 권한 검사, OpenAPI 설명, 문서와 테스트를 모두 맞춰야 합니다.
docs/design/kangcheolung-#18-permission-grant-revoke.md#L158-L158: ADMIN 위임 허용 여부를 확정하고 API 계약과 일치시키세요.docs/design/kangcheolung-#16-collection-crud.md#L186-L187:canWriteCollection()기반 권한 모델이 owner-only 설명과 충돌하지 않도록 수정하세요.
📍 Affects 2 files
docs/design/kangcheolung-#18-permission-grant-revoke.md#L158-L158(this comment)docs/design/kangcheolung-#16-collection-crud.md#L186-L187
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/design/kangcheolung-`#18-permission-grant-revoke.md at line 158, 권한 위임
정책을 ADMIN 위임자까지 허용할지 하나로 확정하고,
docs/design/kangcheolung-#18-permission-grant-revoke.md 158행의 설계 설명과
docs/design/kangcheolung-#16-collection-crud.md 186-187행의 canWriteCollection()
설명을 동일한 정책으로 수정하세요. 확정한 정책에 맞춰 CollectionController의 OpenAPI owner-only 설명, 서비스
권한 검사, 관련 테스트도 일관되게 갱신하세요.
CodeRabbit 리뷰 검증 결과 확인된 사항 반영: - #16: findById()가 status를 필터링하지 않아 삭제된 컬렉션에도 addDocument/getCollection이 가능한 갭을 명시적으로 기록 - #18: AccessSourceType.OWNER가 엔티티 Javadoc과 달리 실제로는 어디서도 생성되지 않는 dead value임을 확인 후 정정, Swagger @operation description이 "owner만 가능"이라 적혀있지만 실제로는 canAdminCollection/canAdminDocument로 ADMIN 위임자도 통과하는 불일치를 TODO로 기록 - #29: 빈 IN 절이 JPQL 자체로 안전하다는 잘못된 설명을 제거하고, 실제로는 UserDocumentAccessCacheService의 명시적 isEmpty() 가드가 처리한다는 정확한 설명으로 교체
grantCollectionPermission/revokeCollectionPermission/grantDocumentPermission/ revokeDocumentPermission의 @operation description이 "소유자(owner)만 가능" 이라고 적혀 있었으나, 실제 서비스 코드는 canAdminCollection()/canAdminDocument()로 판단해 ADMIN 위임자도 통과시킨다. 로직 변경 없이 설명 문구만 실제 동작에 맞게 수정.
1 participant
Summary
docs/test-results/kangcheolung-#21-permission-query-service.md의 실제 Swagger 검증 로그 발췌, 에러 케이스 표, 설계 결정 요약, 남은 이슈/TODO 섹션 추가closes #80
Test plan
domain/collection,domain/permission) 대조 검증ErrorCode.java와 대조 확인Summary by CodeRabbit
새 기능
문서화