[Feat] Embedding Job Attempt 시작 기록

[Gimini-3]

🔍️ 작업 내용

• Closes [Feature] Embedding Job Attempt 시작 기록 #63

✨ 상세 설명

• POST /admin/indexing-jobs/{jobId}/attempts 관리자 API를 추가했습니다.
  • 현재 유효한 PROCESSING Job의 Worker ID·Claim Token·Lease를 검증합니다.
  • 최초 Attempt 생성은 201 Created, 같은 현재 Claim 재전송은 기존 Attempt와 200 OK를 반환합니다.
• Job 행을 JPA Pessimistic Write Lock으로 먼저 잠가 Claim 소유권 교체와 Job별 Attempt 번호 할당을 직렬화했습니다.
• Claim Token을 멱등성 키로 Attempt에 저장하고 (embedding_job_id, claim_token) 유일성 제약을 V34 Migration으로 추가했습니다.
  • 기존 Legacy Attempt와의 호환성을 위해 신규 컬럼은 nullable Expand Migration으로 유지합니다.
• Attempt Entity·Repository·Command Service·Request/Response DTO·Converter와 EMBEDDING-JOB-001~005 오류 계약을 추가했습니다.
• Claim Token은 성공 응답, 오류 메시지, 로그에 노출하지 않습니다.
• 신규 설정, Secret, 외부 서비스 연결, Build Task 변경은 없습니다.

검증:

• ./gradlew test --tests 'com.opensource.docgrid.domain.worker.entity.EmbeddingJobAttemptTest' --tests 'com.opensource.docgrid.domain.embedding.converter.EmbeddingJobAttemptConverterTest' --tests 'com.opensource.docgrid.domain.embedding.service.command.EmbeddingJobAttemptServiceTest' --tests 'com.opensource.docgrid.domain.embedding.controller.IndexingJobAdminControllerTest' --tests 'com.opensource.docgrid.domain.embedding.service.command.EmbeddingJobClaimServiceTest' --tests 'com.opensource.docgrid.domain.embedding.entity.EmbeddingJobTest'
• 격리 OpenSQL: ./gradlew test --tests '*EmbeddingJobAttemptIntegrationTest'
• 격리 OpenSQL: ./gradlew clean build
• 격리 OpenSQL: ./gradlew claimConcurrencyTest

🛠️ 추후 리팩토링 및 고도화 계획

• Attempt 성공·실패 종료, Job 완료·실패 상태 전이는 후속 실행 단계에서 추가합니다.
• Lease 회수·재Claim 기능도 동일하게 Job을 먼저 잠그는 순서를 유지해야 합니다.
• Worker 직접 호출 구조로 확장할 때 Machine Credential과 Worker Instance ID를 인증 Principal에 바인딩합니다.

📸 스크린샷 (선택)

• Backend API 및 DB Transaction 변경으로 별도 화면 스크린샷은 없습니다.

💬 리뷰 요구사항

• Job → Attempt 순서의 잠금 계약과 동일 Claim 동시 요청의 멱등 처리 경계를 중점적으로 확인해 주세요.
• V34 nullable 컬럼이 기존 Row를 유지하면서 신규 Service에서만 non-null Token을 기록하는 배포 호환성을 확인해 주세요.
• 최초 201과 재전송 200의 응답 Body가 동일하고 Token이 제외되는 API 계약을 확인해 주세요.

Summary by CodeRabbit

• 새로운 기능

  • Embedding Job 실행 Attempt를 시작하는 관리자 API를 추가했습니다.
  • 최초 요청은 생성 결과를 반환하고, 동일 요청 재전송 시 기존 Attempt를 중복 없이 반환합니다.
  • Attempt 번호와 시작 상태, 워커 정보를 확인할 수 있습니다.

• 오류 처리

  • 작업 상태, 소유권, Lease 만료 및 존재 여부를 검증하고 상황별 오류 응답을 제공합니다.

• 데이터베이스

  • Attempt별 Claim Token 기록과 중복 방지 제약을 추가했습니다.

• 문서 및 테스트

  • 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: 5513553c-e4e7-41f8-be66-e66a112ab164

📥 Commits

Reviewing files that changed from the base of the PR and between bd441f3 and 2b612fa.

📒 Files selected for processing (16)

• docs/design/gimin-#63-embedding-job-attempt-start.md
• src/main/java/com/opensource/docgrid/domain/embedding/controller/IndexingJobAdminController.java
• src/main/java/com/opensource/docgrid/domain/embedding/converter/EmbeddingJobAttemptConverter.java
• src/main/java/com/opensource/docgrid/domain/embedding/dto/request/StartEmbeddingJobAttemptRequest.java
• src/main/java/com/opensource/docgrid/domain/embedding/dto/response/StartedEmbeddingJobAttemptResponse.java
• src/main/java/com/opensource/docgrid/domain/embedding/repository/EmbeddingJobRepository.java
• src/main/java/com/opensource/docgrid/domain/embedding/service/command/EmbeddingJobAttemptService.java
• src/main/java/com/opensource/docgrid/domain/worker/entity/EmbeddingJobAttempt.java
• src/main/java/com/opensource/docgrid/domain/worker/repository/EmbeddingJobAttemptRepository.java
• src/main/java/com/opensource/docgrid/global/exception/ErrorCode.java
• src/main/resources/db/migration/V34__add_claim_token_to_embedding_job_attempts.sql
• src/test/java/com/opensource/docgrid/domain/embedding/controller/IndexingJobAdminControllerTest.java
• src/test/java/com/opensource/docgrid/domain/embedding/converter/EmbeddingJobAttemptConverterTest.java
• src/test/java/com/opensource/docgrid/domain/embedding/integration/EmbeddingJobAttemptIntegrationTest.java
• src/test/java/com/opensource/docgrid/domain/embedding/service/command/EmbeddingJobAttemptServiceTest.java
• src/test/java/com/opensource/docgrid/domain/worker/entity/EmbeddingJobAttemptTest.java

---

📝 Walkthrough

Walkthrough

유효한 Claim Token을 사용해 Embedding Job Attempt를 시작하는 관리자 API, 소유권·Lease 검증, 멱등 재생, Attempt 번호 증가, DB 잠금·유일성 제약 및 관련 테스트를 추가했습니다.

Changes

Embedding Job Attempt 시작

Layer / File(s)	Summary
Attempt 계약과 저장 구조 docs/design/..., src/main/java/com/opensource/docgrid/domain/embedding/dto/..., src/main/java/com/opensource/docgrid/domain/worker/..., src/main/resources/db/migration/..., src/main/java/com/opensource/docgrid/global/exception/ErrorCode.java	Claim Token 기반 요청·응답과 Attempt 저장 구조, Job 쓰기 잠금 조회, 오류 코드, nullable 컬럼 및 Job+Token 유일 제약을 추가했습니다.
Attempt 시작 서비스와 관리자 API src/main/java/com/opensource/docgrid/domain/embedding/controller/..., src/main/java/com/opensource/docgrid/domain/embedding/service/..., src/main/java/com/opensource/docgrid/domain/embedding/converter/...	PROCESSING 상태, 소유 Worker, Claim Token, Lease를 검증하고 동일 Claim은 기존 Attempt로 재생하며 새 Claim은 다음 번호의 STARTED Attempt를 생성합니다. Controller는 생성 시 201, 재생 시 200을 반환합니다.
Attempt 단위·API 계약 검증 src/test/java/com/opensource/docgrid/domain/embedding/controller/..., src/test/java/com/opensource/docgrid/domain/embedding/service/..., src/test/java/com/opensource/docgrid/domain/embedding/converter/..., src/test/java/com/opensource/docgrid/domain/worker/entity/...	생성·재생·오류·입력 검증·보안 응답, 응답 필드 비노출, 엔티티 상태 전이를 단위 테스트로 검증합니다.
DB 잠금·멱등 동시성 검증 src/test/java/com/opensource/docgrid/domain/embedding/integration/...	DB 제약, Repository 조회, Job 행 잠금, Claim 세대별 번호 증가와 동시 요청의 생성 1회·재생 1회 수렴을 통합 테스트로 검증합니다.

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

Sequence Diagram(s)

sequenceDiagram
  participant Worker
  participant AdminAPI
  participant AttemptService
  participant JobDB
  participant AttemptDB
  Worker->>AdminAPI: Attempt 시작 요청
  AdminAPI->>AttemptService: jobId, workerId, claimToken 전달
  AttemptService->>JobDB: PROCESSING Job 쓰기 잠금
  AttemptService->>AttemptDB: 동일 Job·Claim Attempt 조회
  AttemptDB-->>AttemptService: 기존 Attempt 또는 없음
  AttemptService->>AttemptDB: 신규 STARTED Attempt 저장
  AttemptService-->>AdminAPI: 생성 또는 재생 결과
  AdminAPI-->>Worker: 201 또는 200 응답

Loading

Possibly related PRs

• DocGrid/backend#2: 신규 EMBEDDING-JOB-* 오류 코드가 공통 예외 처리 흐름과 연결됩니다.
• DocGrid/backend#6: 기존 embedding_job_attempts 모델에 Claim Token과 유일성 로직을 확장합니다.
• DocGrid/backend#49: Claim·Lease 및 claim_token 계약이 Attempt 시작 검증의 기반이 됩니다.

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

---

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