Skip to content

[Feat] 문서 인덱싱 상태 조회 API 구현 - #37

Merged
Gimini-3 merged 3 commits into
developfrom
feature/36
Jul 20, 2026
Merged

[Feat] 문서 인덱싱 상태 조회 API 구현#37
Gimini-3 merged 3 commits into
developfrom
feature/36

Conversation

@Gimini-3

@Gimini-3 Gimini-3 commented Jul 19, 2026

Copy link
Copy Markdown
Contributor

🔍 작업 내용

  • Closes [Feat] 문서 인덱싱 상태 조회 API 구현 #36
  • GET /api/documents/{documentId}/status 문서 인덱싱 상태 조회 API 추가
  • 현재 검색 가능한 INDEXED 버전과 처리 중 버전·EmbeddingJob 상태 반환
  • 기존 PermissionQueryService.canReadDocument()를 통한 읽기 권한 검증
  • 상태 불일치 및 삭제 문서 예외 처리

✨ 상세 설명

조회 응답 계약

  • 최초 Version 처리 중: currentVersion=null, Version 1을 processingVersion으로 반환
  • 후속 Version 처리 중: 기존 INDEXED currentVersion과 새 processingVersion을 함께 반환
  • 처리 완료: processingVersion=null

조회 일관성

Document, 현재 Version, 처리 중 Version, 활성 EmbeddingJob을 하나의 JPQL Projection 쿼리로 조회합니다. Worker 상태 전환 중 서로 다른 시점의 Version과 Job 상태가 섞이지 않도록 한 SQL 조회 스냅샷을 사용합니다.

처리 중 Version에 활성 Job이 없거나 활성 Job이 중복되면 DOCUMENT-STATUS-001 오류로 처리해 데이터 불일치를 정상 응답으로 숨기지 않습니다.

🧪 테스트

  • Converter 단위 테스트
  • Query Service 권한·예외·상태 불일치 테스트
  • Controller 인증·응답 계약 테스트
  • 실제 OpenSQL 기반 Projection Repository 테스트
  • ./gradlew test — 143개 통과, 실패 0, 오류 0
  • ./gradlew build — BUILD SUCCESSFUL

📚 문서

  • docs/gimin-#36-document-indexing-status.md

💬 리뷰 요청사항

  • 최초 Version이 처리 중일 때 currentVersion을 null로 반환하는 계약
  • 단일 Projection 조회와 상태 불일치 감지 범위
  • 문서 읽기 권한을 상태 조회 권한으로 재사용한 정책

Summary by CodeRabbit

  • 새 기능

    • 문서의 인덱싱 상태를 조회하는 API를 추가했습니다.
    • 현재 검색 가능한 버전과 처리 중인 버전, 작업 상태를 확인할 수 있습니다.
    • 최초 업로드 처리와 새 버전 처리 상황을 구분해 상태를 제공합니다.
  • 문서화

    • 인증, 권한, 응답 형식, 오류 처리 및 상태 판정 기준을 문서화했습니다.
  • 버그 수정

    • 권한이 없거나 존재하지 않는 문서 조회 시 적절한 오류를 반환합니다.
    • 인덱싱 상태 정보가 일관되지 않은 경우 서버 오류로 명확히 처리합니다.

@coderabbitai

coderabbitai Bot commented Jul 19, 2026

Copy link
Copy Markdown

Review Change Stack

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 03eaa403-84c3-4e91-95e7-5f809d519b3b

📥 Commits

Reviewing files that changed from the base of the PR and between c471395 and 14fedb1.

📒 Files selected for processing (14)
  • docs/gimin-#36-document-indexing-status.md
  • src/main/java/com/opensource/docgrid/domain/document/controller/DocumentQueryController.java
  • src/main/java/com/opensource/docgrid/domain/document/converter/DocumentStatusConverter.java
  • src/main/java/com/opensource/docgrid/domain/document/dto/response/CurrentVersionStatusResponse.java
  • src/main/java/com/opensource/docgrid/domain/document/dto/response/DocumentStatusResponse.java
  • src/main/java/com/opensource/docgrid/domain/document/dto/response/ProcessingVersionStatusResponse.java
  • src/main/java/com/opensource/docgrid/domain/document/repository/DocumentRepository.java
  • src/main/java/com/opensource/docgrid/domain/document/repository/DocumentStatusProjection.java
  • src/main/java/com/opensource/docgrid/domain/document/service/query/DocumentQueryService.java
  • src/main/java/com/opensource/docgrid/global/exception/ErrorCode.java
  • src/test/java/com/opensource/docgrid/domain/document/controller/DocumentQueryControllerTest.java
  • src/test/java/com/opensource/docgrid/domain/document/converter/DocumentStatusConverterTest.java
  • src/test/java/com/opensource/docgrid/domain/document/repository/DocumentStatusRepositoryTest.java
  • src/test/java/com/opensource/docgrid/domain/document/service/query/DocumentQueryServiceTest.java

📝 Walkthrough

Walkthrough

문서 인덱싱 상태 조회 API가 추가되었다. 읽기 권한을 검증하고, 현재 INDEXED 버전과 처리 중 버전·활성 작업 상태를 Projection으로 조회해 응답하며, 상태 불일치와 문서 오류를 구분한다.

Changes

문서 인덱싱 상태 조회

Layer / File(s) Summary
상태 응답 계약과 조회 모델
docs/gimin-#36-document-indexing-status.md, src/main/java/com/opensource/docgrid/domain/document/dto/response/*, src/main/java/com/opensource/docgrid/domain/document/repository/DocumentStatusProjection.java
문서 상태, 현재 버전, 처리 중 버전과 작업 상태의 응답 구조 및 반환 규칙을 정의하고 Projection 계약을 추가했다.
Projection 조회와 상태 검증
src/main/java/com/opensource/docgrid/domain/document/repository/DocumentRepository.java, src/main/java/com/opensource/docgrid/domain/document/service/query/DocumentQueryService.java, src/main/java/com/opensource/docgrid/global/exception/ErrorCode.java, src/test/java/com/opensource/docgrid/domain/document/repository/DocumentStatusRepositoryTest.java, src/test/java/com/opensource/docgrid/domain/document/service/query/DocumentQueryServiceTest.java
단일 JPQL 조회로 문서·버전·활성 작업 상태를 가져오고, 권한·문서 존재·삭제·중복 행·상태 불일치를 검증한다. 관련 Repository 및 Service 테스트를 추가했다.
HTTP 응답 변환과 엔드포인트
src/main/java/com/opensource/docgrid/domain/document/controller/DocumentQueryController.java, src/main/java/com/opensource/docgrid/domain/document/converter/DocumentStatusConverter.java, src/test/java/com/opensource/docgrid/domain/document/controller/DocumentQueryControllerTest.java, src/test/java/com/opensource/docgrid/domain/document/converter/DocumentStatusConverterTest.java
GET /api/documents/{documentId}/status 엔드포인트와 Projection 변환을 구현하고, 인증·권한 오류 및 버전별 응답 형태를 검증한다.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant DocumentQueryController
  participant DocumentQueryService
  participant DocumentRepository
  participant DocumentStatusConverter
  Client->>DocumentQueryController: GET /api/documents/{documentId}/status
  DocumentQueryController->>DocumentQueryService: getDocumentStatus(userId, documentId)
  DocumentQueryService->>DocumentRepository: findDocumentStatus(...)
  DocumentRepository-->>DocumentQueryService: DocumentStatusProjection
  DocumentQueryService->>DocumentStatusConverter: toResponse(projection)
  DocumentStatusConverter-->>DocumentQueryService: DocumentStatusResponse
  DocumentQueryService-->>DocumentQueryController: DocumentStatusResponse
  DocumentQueryController-->>Client: 200 OK or mapped error
Loading

Possibly related PRs

  • DocGrid/backend#13: @CurrentUser를 통한 인증 사용자 ID 주입과 상태 조회 Controller의 호출 흐름이 연결된다.
  • DocGrid/backend#23: PermissionQueryService.canReadDocument를 통한 문서 읽기 권한 검증과 연결된다.

Suggested labels: ✨ Feature

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feature/36

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@Gimini-3
Gimini-3 marked this pull request as ready for review July 20, 2026 05:56
@Gimini-3
Gimini-3 merged commit 3087fe0 into develop Jul 20, 2026
1 check passed
@Gimini-3 Gimini-3 self-assigned this Jul 20, 2026
@Gimini-3 Gimini-3 added the ✨ Feature 기능 개발 label Jul 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

✨ Feature 기능 개발

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feat] 문서 인덱싱 상태 조회 API 구현

1 participant