[Feat] 문서 새 버전 업로드 API 추가

[Gimini-3]

변경 사항

• POST /api/documents/{documentId}/versions 새 버전 업로드 API를 추가했습니다.
• 현재 Version과 동일한 파일은 409 DOCUMENT_VERSION_SAME_CONTENT로 거절합니다.
• 과거 Version 또는 다른 Document가 사용하는 동일 파일은 FileObject를 재사용합니다.
• Document 행 잠금과 처리 중 Version 부분 유니크 인덱스로 동시 요청을 보호합니다.
• 새 Version이 INDEXED되기 전까지 기존 current_version_id를 유지합니다.
• Version별 original_filename, content_type 저장과 기존 데이터 백필을 추가했습니다.
• 신규 문서와 후속 Version이 공통 FileObject 저장·재사용 로직을 사용하도록 분리했습니다.

배경

기존 POST /api/documents는 모든 업로드를 새로운 논리 Document로 생성하므로 기존 문서의 수정 파일을 버전으로 등록할 수 없었습니다. 문서의 동일성은 documentId와 호출 API로, 파일의 동일성은 전체 바이트의 SHA-256과 file_size로 분리했습니다.

문서

• PR 2.1 상세 설계
• Swagger·DB·MinIO 테스트 결과

검증

• ./gradlew test — BUILD SUCCESSFUL
• 같은 크기·다른 내용의 Version 생성 확인
• 현재 Version과 동일한 파일의 사전 거절 및 MinIO 미저장 확인
• 동일 파일을 새 Document에서 공유하는 FileObject 재사용 확인
• 과거 Version 파일로 되돌릴 때 기존 FileObject 재사용 확인
• MinIO Object 2개가 논리 Version 4개에서 공유되는 것 확인

영향

새 버전 접수까지만 포함하며 파싱·청킹·임베딩과 current_version_id 완료 전환은 후속 PR에서 처리합니다.

Closes #25

Summary by CodeRabbit

• 새로운 기능

  • 기존 문서에 새 버전을 업로드하는 API를 추가했습니다.
  • 파일 내용과 크기를 기준으로 동일 파일을 감지하고, 기존 파일을 재사용할 수 있습니다.
  • 새 버전 생성 시 임베딩 작업이 자동으로 등록됩니다.
  • 업로드 파일명과 콘텐츠 유형을 버전 정보에 보존합니다.

• 오류 처리

  • 동일 내용, 처리 중인 버전, 허용되지 않은 업로드 유형에 대한 명확한 오류 응답을 추가했습니다.

• 테스트 및 문서

  • 중복 업로드, 새 버전 생성, 과거 버전 재사용 시나리오를 검증하는 통합 테스트와 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: c0d2c31c-f8ae-4840-ab12-21d828e82a57

📥 Commits

Reviewing files that changed from the base of the PR and between 0833861 and 7c2b40d.

📒 Files selected for processing (21)

• .github/ISSUE_TEMPLATE/document-version-upload.md
• docs/pr-2.1-document-version-upload.md
• docs/test-results/pr-2.1-document-version-upload.md
• src/main/java/com/opensource/docgrid/domain/document/controller/DocumentUploadController.java
• src/main/java/com/opensource/docgrid/domain/document/dto/request/DocumentVersionUploadRequest.java
• src/main/java/com/opensource/docgrid/domain/document/dto/response/DocumentVersionUploadResponse.java
• 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/document/repository/DocumentRepository.java
• src/main/java/com/opensource/docgrid/domain/document/repository/DocumentVersionRepository.java
• src/main/java/com/opensource/docgrid/domain/document/service/DocumentVersionUploadFacade.java
• src/main/java/com/opensource/docgrid/domain/document/service/command/DocumentUploadService.java
• src/main/java/com/opensource/docgrid/domain/document/service/command/DocumentVersionUploadCommand.java
• src/main/java/com/opensource/docgrid/domain/document/service/command/DocumentVersionUploadService.java
• src/main/java/com/opensource/docgrid/domain/document/service/command/DocumentVersionUploadTransactionResult.java
• src/main/java/com/opensource/docgrid/domain/document/service/command/FileObjectResolutionService.java
• src/main/java/com/opensource/docgrid/global/exception/ErrorCode.java
• src/main/resources/db/migration/V30__add_document_version_upload_metadata.sql
• src/test/java/com/opensource/docgrid/domain/document/controller/DocumentUploadControllerTest.java
• src/test/java/com/opensource/docgrid/domain/document/integration/DocumentVersionUploadIntegrationTest.java
• src/test/java/com/opensource/docgrid/domain/document/service/command/DocumentUploadServiceTest.java

---

📝 Walkthrough

Walkthrough

문서 버전 업로드 API와 처리 서비스를 추가했습니다. 파일 해시·크기 기반 재사용, 버전 번호 동시성 제어, 업로드 메타데이터 저장, PENDING EmbeddingJob 생성을 구현하고, 중복·되돌리기·저장소 재사용 시나리오를 테스트와 문서로 검증했습니다.

Changes

문서 버전 업로드

Layer / File(s)	Summary
업로드 계약과 저장 구조 .github/ISSUE_TEMPLATE/document-version-upload.md, docs/pr-2.1-document-version-upload.md, src/main/java/.../dto/*, src/main/java/.../entity/*, src/main/java/.../repository/*, src/main/resources/db/migration/*	버전 업로드 API 계약, 요청·응답 DTO, 버전별 파일 메타데이터, 백필 마이그레이션, 처리 중 버전의 조건부 유니크 인덱스와 오류 코드가 추가됐습니다.
파일 객체 해석과 저장소 재사용 src/main/java/.../service/command/FileObjectResolutionService.java, src/main/java/.../service/command/DocumentUploadService.java, src/main/java/.../service/DocumentVersionUploadFacade.java	파일 해시와 크기로 기존 FileObject를 조회·재사용하고, 신규 저장 후보의 채택 여부에 따라 MinIO 객체를 정리하도록 구성했습니다. 기존 문서 업로드 경로도 공통 해석 서비스와 메타데이터 저장을 사용합니다.
버전 업로드 오케스트레이션 src/main/java/.../controller/DocumentUploadController.java, src/main/java/.../service/command/DocumentVersionUploadService.java, src/main/java/.../service/command/DocumentVersionUploadCommand.java	multipart 엔드포인트에서 사용자와 문서를 전달받아 소유권·상태·파일 형식을 검증하고, 문서 잠금 후 새 버전과 PENDING EmbeddingJob을 생성해 201 응답을 반환합니다.
업로드 검증과 통합 검증 src/test/java/.../DocumentUploadControllerTest.java, src/test/java/.../DocumentVersionUploadIntegrationTest.java, docs/test-results/*	동일 콘텐츠 409 거절, 동일 크기·상이한 콘텐츠의 버전 증가, current version 유지, 과거 FileObject 재사용, 파일 메타데이터 저장을 테스트와 실행 결과 문서로 검증합니다.

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

Possibly related issues

• [Feat] 문서 업로드 접수 API 구현 #15 — 기존 문서 업로드와 공유되는 FileObject 재사용, MinIO 보상 처리, 버전 및 임베딩 작업 생성 흐름과 직접 연결됩니다.

Possibly related PRs

• DocGrid/backend#22 — 기존 문서 업로드의 파일 해시·크기 중복 처리와 업로드 서비스 구조를 확장·리팩터링합니다.
• DocGrid/backend#13 — 새 업로드 엔드포인트의 @CurrentUser 사용자 ID 주입과 인증 컨텍스트를 연결합니다.
• DocGrid/backend#17 — DocumentRepository의 잠금 조회 및 관련 저장소 변경과 코드 수준에서 연결됩니다.

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

---

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.}