[Feat] 문서 업로드 접수 API 구현

[Gimini-3]

변경 사항

• POST /api/documents multipart 업로드 API를 추가했습니다.
• TXT/Markdown 확장자, Content-Type, 파일 크기, 파일명 및 Path Traversal을 검증합니다.
• SHA-256 해시와 파일 크기를 기준으로 FileObject를 재사용합니다.
• UUID 기반 Object Key로 MinIO에 저장하고, DB 실패 시 신규 Object를 보상 삭제합니다.
• ON CONFLICT DO NOTHING과 UNIQUE (file_hash, file_size)로 동시 중복 업로드를 처리합니다.
• Document, 첫 DocumentVersion, active EmbeddingModel이 고정된 PENDING EmbeddingJob을 하나의 DB 트랜잭션에서 생성합니다.
• 파일 검증, 해시, Controller, 보상 처리, 순차·동시 중복 및 rollback 테스트를 추가했습니다.

영향 및 제외 범위

업로드 API는 파일 저장과 인덱싱 작업 접수까지만 담당합니다. 파싱, 청킹, 임베딩 호출 및 벡터 저장은 포함하지 않습니다.

검증

• 문서 업로드 관련 테스트: 23개 통과
• OpenSQL 실제 동시 업로드 및 rollback 통합 테스트 통과
• 실제 로컬 API 호출: HTTP 201
• 실제 MinIO Object 저장 및 DB 4개 테이블 연관관계 확인
• ./gradlew build -x test: 통과
• ./gradlew cleanTest test: 76개 중 74개 통과
  • 기존 CollectionPermissionCommandServiceTest의 캐시 호출 검증 2건이 실패하며, 이번 변경 범위와 무관하게 최신 develop에서 재현됩니다.

Closes #15

Summary by CodeRabbit

• 새로운 기능

  • TXT 및 Markdown 문서 업로드 기능을 추가했습니다.
  • 제목, 설명, 공개 범위와 함께 파일을 등록할 수 있습니다.
  • 업로드 파일의 크기, 형식, 확장자, 파일명을 자동 검증합니다.
  • 업로드 결과로 문서, 버전 및 임베딩 작업 상태를 확인할 수 있습니다.
  • 동일 파일을 자동으로 식별해 저장 공간을 절약합니다.
  • 업로드된 파일을 안전한 외부 저장소에 보관합니다.

• 버그 수정

  • 파일 업로드 실패 시 임시 저장 파일이 정리됩니다.
  • 용량 초과 및 업로드 오류가 명확한 오류 응답으로 제공됩니다.

[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: 0d7c34a3-2805-48c0-99d5-a8c2bfc25f6a

📥 Commits

Reviewing files that changed from the base of the PR and between 371c8e3 and b345d2c.

📒 Files selected for processing (31)

• .gitignore
• src/main/java/com/opensource/docgrid/domain/document/config/DocumentUploadProperties.java
• src/main/java/com/opensource/docgrid/domain/document/controller/DocumentUploadController.java
• src/main/java/com/opensource/docgrid/domain/document/dto/request/DocumentUploadRequest.java
• src/main/java/com/opensource/docgrid/domain/document/dto/response/DocumentUploadResponse.java
• src/main/java/com/opensource/docgrid/domain/document/entity/Document.java
• src/main/java/com/opensource/docgrid/domain/document/entity/FileObject.java
• src/main/java/com/opensource/docgrid/domain/document/repository/DocumentVersionRepository.java
• src/main/java/com/opensource/docgrid/domain/document/repository/FileObjectRepository.java
• src/main/java/com/opensource/docgrid/domain/document/service/DocumentUploadFacade.java
• src/main/java/com/opensource/docgrid/domain/document/service/FileHashService.java
• src/main/java/com/opensource/docgrid/domain/document/service/FileValidationService.java
• src/main/java/com/opensource/docgrid/domain/document/service/ValidatedFile.java
• src/main/java/com/opensource/docgrid/domain/document/service/command/DocumentUploadCommand.java
• src/main/java/com/opensource/docgrid/domain/document/service/command/DocumentUploadService.java
• src/main/java/com/opensource/docgrid/domain/document/service/command/DocumentUploadTransactionResult.java
• src/main/java/com/opensource/docgrid/domain/document/storage/FileStorageService.java
• src/main/java/com/opensource/docgrid/domain/document/storage/MinioStorageService.java
• src/main/java/com/opensource/docgrid/domain/document/storage/StoredFile.java
• src/main/java/com/opensource/docgrid/domain/embedding/repository/EmbeddingJobRepository.java
• src/main/java/com/opensource/docgrid/global/exception/DocGridException.java
• src/main/java/com/opensource/docgrid/global/exception/ErrorCode.java
• src/main/java/com/opensource/docgrid/global/exception/GlobalExceptionHandler.java
• src/main/resources/application.yml
• src/main/resources/db/migration/V29__add_file_object_deduplication_constraint.sql
• src/test/java/com/opensource/docgrid/domain/document/controller/DocumentUploadControllerTest.java
• src/test/java/com/opensource/docgrid/domain/document/integration/DocumentUploadIntegrationTest.java
• src/test/java/com/opensource/docgrid/domain/document/service/DocumentUploadFacadeTest.java
• src/test/java/com/opensource/docgrid/domain/document/service/FileHashServiceTest.java
• src/test/java/com/opensource/docgrid/domain/document/service/FileValidationServiceTest.java
• src/test/java/com/opensource/docgrid/domain/document/service/command/DocumentUploadServiceTest.java

---

📝 Walkthrough

Walkthrough

TXT·Markdown 파일 업로드 API가 추가되었다. 파일 검증과 SHA-256 계산, MinIO 저장, 중복 파일 재사용, 문서·버전·임베딩 작업 생성, 실패 시 보상 삭제 및 관련 테스트가 구현되었다.

Changes

문서 업로드 기능

Layer / File(s)	Summary
업로드 계약과 파일 검증 .gitignore, src/main/java/com/opensource/docgrid/domain/document/config/..., src/main/java/com/opensource/docgrid/domain/document/dto/..., src/main/java/com/opensource/docgrid/domain/document/service/File*, src/main/java/com/opensource/docgrid/global/exception/..., src/main/resources/application.yml	멀티파트 요청 DTO, 10MB 설정, TXT·Markdown 파일명·크기·Content-Type 검증, SHA-256 계산 및 업로드 관련 오류 처리가 추가되었다.
파일 저장과 중복 제거 src/main/java/com/opensource/docgrid/domain/document/storage/..., src/main/java/com/opensource/docgrid/domain/document/entity/FileObject.java, src/main/java/com/opensource/docgrid/domain/document/repository/FileObjectRepository.java, src/main/resources/db/migration/...	MinIO 저장·삭제 구현과 file_hash·file_size 기반 파일 객체 조회 및 원자적 중복 삽입 방지가 추가되었다.
업로드 트랜잭션과 엔터티 생성 src/main/java/com/opensource/docgrid/domain/document/service/command/..., src/main/java/com/opensource/docgrid/domain/document/repository/..., src/main/java/com/opensource/docgrid/domain/embedding/repository/..., src/main/java/com/opensource/docgrid/domain/document/entity/Document.java	파일 객체를 결정한 뒤 문서, 첫 버전, 현재 버전, PENDING 임베딩 작업을 생성하고 결과를 반환하는 트랜잭션 서비스가 추가되었다.
API 연결과 후보 파일 정리 src/main/java/com/opensource/docgrid/domain/document/controller/DocumentUploadController.java, src/main/java/com/opensource/docgrid/domain/document/service/DocumentUploadFacade.java	POST /api/documents 엔드포인트와 업로드 오케스트레이션이 연결되며, 실패하거나 후보 파일이 채택되지 않을 때 저장 파일을 삭제한다.
업로드 흐름 검증 src/test/java/com/opensource/docgrid/domain/document/...	컨트롤러 인증·응답, 파일 검증·해시, 중복 업로드, 동시성, 롤백 및 보상 삭제 시나리오 테스트가 추가되었다.

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

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant DocumentUploadController
  participant DocumentUploadFacade
  participant FileStorageService
  participant DocumentUploadService
  participant Database
  Client->>DocumentUploadController: multipart 문서 업로드
  DocumentUploadController->>DocumentUploadFacade: userId와 요청 전달
  DocumentUploadFacade->>FileStorageService: 후보 파일 저장
  DocumentUploadFacade->>DocumentUploadService: 업로드 트랜잭션 실행
  DocumentUploadService->>Database: FileObject, Document, Version, EmbeddingJob 저장
  DocumentUploadService-->>DocumentUploadFacade: 업로드 결과 반환
  DocumentUploadFacade-->>DocumentUploadController: 후보 정리 후 응답 반환
  DocumentUploadController-->>Client: 201 Created

Loading

Possibly related PRs

• DocGrid/backend#2: 업로드 관련 ErrorCode, DocGridException, 전역 예외 처리를 확장한다.
• DocGrid/backend#6: FileObject 스키마와 파일 중복 제거 제약을 직접 연결한다.
• DocGrid/backend#13: 업로드 컨트롤러의 @CurrentUser 사용자 ID 주입과 연결된다.

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

---

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