[Feat] 문서 인덱싱 완료 및 검색 가능 Version 전환

[Gimini-3]

🔍️ 작업 내용

• 관리자 전용 문서 인덱싱 완료 API를 추가했습니다.
  • POST /admin/indexing-jobs/{jobId}/attempts/{attemptId}/complete
• 완료 요청을 하나의 트랜잭션에서 처리하도록 구현했습니다.
  • Job → Version → Document 순서로 잠금
  • Attempt 소유권, worker/token, lease, 최신 Version, embedding model, embedding 완전성 검증
  • Attempt를 SUCCESS, Job/Version/Document를 INDEXED로 전환
  • 이전 Version의 ACTIVE embedding을 STALE로 전환
  • 인덱싱 완료 이벤트를 정확히 한 번 저장
• 동일 worker/token/attempt의 재요청은 상태 변경 없이 기존 완료 결과를 반환하도록 멱등 재생을 지원합니다.
• 인덱싱 완료 전후의 검색 대상 전환, 동시 완료 요청, 트랜잭션 롤백을 통합 테스트로 검증했습니다.
• 구현 설계와 실행된 테스트 결과 문서를 추가했습니다.

Closes #84

✨ 상세 설명

• 최초 완료와 멱등 재생 경로를 분리했습니다.
• 최초 완료에서는 lease와 최신 Version 여부를 엄격하게 검증합니다.
• 이미 성공한 동일 Attempt의 재생은 lease 만료, 후속 Version 생성, model 비활성화 이후에도 기존 완료 결과만 반환하며 상태를 변경하지 않습니다.
• 완료 시각은 DB의 microsecond 정밀도에 맞춰 정규화해 응답과 저장값을 일치시킵니다.
• 외부 I/O 없이 DB 상태 전이만 트랜잭션 경계 안에서 수행합니다.

✅ 검증

• ./gradlew clean build
  • 432 tests, failures 0, errors 0
• PostgreSQL 14 + pgvector 기반 OpenSQL 통합 검증
  • Repository 계약
  • 검색 대상 Version 전환
  • 동시 완료 요청
  • DB 오류 발생 시 전체 롤백
• git diff --check

Gradle 기본 설정에 따라 benchmark, minio-integration, claim-concurrency 태그 테스트는 위 빌드에서 제외됩니다.

📚 문서

• docs/design/Gimini-3-#84-document-indexing-completion.md
• docs/test-results/Gimini-3-#84-document-indexing-completion.md

💬 리뷰 요구사항

• 최초 완료와 멱등 재생의 검증 순서가 의도한 재시도 계약을 만족하는지 확인 부탁드립니다.
• Job → Version → Document 잠금 순서와 이전 Version embedding의 STALE 전환 범위를 중점적으로 확인 부탁드립니다.

Summary by CodeRabbit

• 새로운 기능

  • 문서 인덱싱 완료 API를 추가했습니다.
  • 인덱싱이 완료된 문서 버전을 검색 대상으로 자동 활성화합니다.
  • 완료 결과와 처리 시간을 확인할 수 있습니다.
  • 이미 완료된 요청은 중복 처리 없이 안전하게 재현됩니다.

• 개선 사항

  • 잘못된 상태, 오래된 버전, 데이터 불일치에 대한 오류 안내를 강화했습니다.
  • 기존 검색 데이터는 새 버전 활성화 시 비활성화됩니다.
  • 완료 처리 중 오류 발생 시 변경 사항이 자동으로 되돌아갑니다.

• 검증

  • 동시 요청, 중복 이벤트, 검색 결과 및 데이터 복구 시나리오를 검증했습니다.

[coderabbitai]

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: cbad1b7d-b819-4767-831b-4f8e938f5e12

📥 Commits

Reviewing files that changed from the base of the PR and between fc290c5 and 26dd221.

📒 Files selected for processing (22)

• docs/design/Gimini-3-#84-document-indexing-completion.md
• docs/test-results/Gimini-3-#84-document-indexing-completion.md
• src/main/java/com/opensource/docgrid/domain/document/entity/Document.java
• src/main/java/com/opensource/docgrid/domain/document/entity/DocumentVersion.java
• src/main/java/com/opensource/docgrid/domain/embedding/controller/IndexingJobAdminController.java
• src/main/java/com/opensource/docgrid/domain/embedding/dto/request/CompleteDocumentIndexingRequest.java
• src/main/java/com/opensource/docgrid/domain/embedding/dto/response/DocumentIndexingCompletionResponse.java
• src/main/java/com/opensource/docgrid/domain/embedding/entity/EmbeddingJob.java
• src/main/java/com/opensource/docgrid/domain/embedding/repository/EmbeddingJobRepository.java
• src/main/java/com/opensource/docgrid/domain/embedding/repository/EmbeddingRepository.java
• src/main/java/com/opensource/docgrid/domain/embedding/service/command/DocumentIndexingCompletionService.java
• src/main/java/com/opensource/docgrid/domain/worker/entity/EmbeddingJobAttempt.java
• src/main/java/com/opensource/docgrid/domain/worker/repository/IndexingEventRepository.java
• src/main/java/com/opensource/docgrid/global/exception/ErrorCode.java
• src/test/java/com/opensource/docgrid/domain/document/entity/DocumentTest.java
• src/test/java/com/opensource/docgrid/domain/document/entity/DocumentVersionTest.java
• src/test/java/com/opensource/docgrid/domain/embedding/controller/IndexingJobAdminControllerTest.java
• src/test/java/com/opensource/docgrid/domain/embedding/entity/EmbeddingJobTest.java
• src/test/java/com/opensource/docgrid/domain/embedding/integration/DocumentIndexingCompletionIntegrationTest.java
• src/test/java/com/opensource/docgrid/domain/embedding/repository/IndexingCompletionRepositoryTest.java
• src/test/java/com/opensource/docgrid/domain/embedding/service/command/DocumentIndexingCompletionServiceTest.java
• src/test/java/com/opensource/docgrid/domain/worker/entity/EmbeddingJobAttemptTest.java

---

📝 Walkthrough

Walkthrough

문서 인덱싱 완료 API와 완료 서비스를 추가했다. 서비스는 실행 소유권과 Embedding Set을 검증한 뒤 Job, Attempt, Version, Document, Embedding, 이벤트를 하나의 Transaction으로 전환한다. 동일 실행의 재요청은 저장된 완료 결과를 재생한다.

Changes

문서 인덱싱 완료

Layer / File(s)	Summary
완료 계약과 도메인 상태 Guard src/main/java/com/opensource/docgrid/domain/document/..., src/main/java/com/opensource/docgrid/domain/embedding/dto/..., src/main/java/com/opensource/docgrid/domain/worker/entity/..., src/main/java/com/opensource/docgrid/global/exception/ErrorCode.java	완료 요청·응답 DTO를 추가했다. Document, DocumentVersion, EmbeddingJob, EmbeddingJobAttempt의 허용 상태 전이를 검증한다. 완료 관련 오류 코드를 추가했다.
완료 서비스와 저장소 검증 src/main/java/com/opensource/docgrid/domain/embedding/service/..., src/main/java/com/opensource/docgrid/domain/embedding/repository/..., src/main/java/com/opensource/docgrid/domain/worker/repository/..., src/test/java/com/opensource/docgrid/domain/embedding/service/..., src/test/java/com/opensource/docgrid/domain/embedding/repository/...	Job → Version → Document 잠금 순서로 실행 Context와 Embedding Set을 검증한다. 이전 ACTIVE Embedding을 STALE로 전환하고 상태 변경과 INDEXED 이벤트를 단일 Transaction으로 저장한다. 완료 재요청은 기존 결과를 재생한다.
관리자 완료 API 연결 src/main/java/com/opensource/docgrid/domain/embedding/controller/IndexingJobAdminController.java, src/test/java/com/opensource/docgrid/domain/embedding/controller/...	POST /{jobId}/attempts/{attemptId}/complete Endpoint를 추가했다. 입력 검증, 200 OK 응답, 오류 매핑, ADMIN 권한 및 민감 필드 비노출을 검증한다.
OpenSQL 통합 검증과 구현 기록 src/test/java/com/opensource/docgrid/domain/embedding/integration/..., docs/design/..., docs/test-results/...	최초 Version 공개, 새 Version 교체, 동시 완료의 단일 결과, 중복 이벤트 방지 및 이벤트 저장 실패 Rollback을 검증했다. 설계와 테스트 결과를 문서화했다.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Admin
  participant IndexingJobAdminController
  participant DocumentIndexingCompletionService
  participant Database
  Admin->>IndexingJobAdminController: 완료 요청 전송
  IndexingJobAdminController->>DocumentIndexingCompletionService: complete 호출
  DocumentIndexingCompletionService->>Database: Job, Version, Document 잠금 및 검증
  DocumentIndexingCompletionService->>Database: 상태 전환, Embedding 갱신, INDEXED 이벤트 저장
  Database-->>DocumentIndexingCompletionService: 완료 결과 반환
  DocumentIndexingCompletionService-->>IndexingJobAdminController: 완료 응답 반환
  IndexingJobAdminController-->>Admin: 200 OK

Loading

Possibly related PRs

• DocGrid/backend#6: 완료 처리에서 사용하는 문서 및 인덱싱 Entity 생명주기를 정의했다.
• DocGrid/backend#64: EmbeddingJobAttempt 생명주기와 Claim Token 기반 멱등성 계약을 제공한다.
• DocGrid/backend#83: 완료 서비스가 사용하는 Embedding Job 및 Version 처리 기반을 추가했다.

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/84

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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