[Fix] 최초 인덱싱 구간에서 DocumentStatus.INDEXING이 노출되지 않음

[Gimini-3]

📌 배경

GET /api/documents/{id}/status를 0.25초 간격으로 폴링해도 documentStatus가 UPLOADED → INDEXED로 직행하고 INDEXING을 거치지 않았습니다. Document.markIndexing() 호출부가 재시도·복구 서비스 두 곳뿐이고 정상 업로드 경로에는 없었기 때문입니다.

🔧 변경 내용

파싱 시작 Transaction(DocumentChunkTransactionService.prepare)에서 문서 상태도 함께 INDEXING으로 전환합니다. 단 검색 가능한 Version이 없는 경우로 한정합니다.

경로	document.status	INDEXING 노출	검색 영향
최초 업로드	UPLOADED	✅	없음 (아직 미검색)
INDEXED 문서 재인덱싱	INDEXED 유지	❌	보존
FAILED 문서 재시도	FAILED→UPLOADED	✅	없음 (검색 불가 상태)

왜 재인덱싱은 제외했나

검색 경로가 문서 상태로 대상을 거릅니다.

• VectorSearchRepository.findTopK — AND d.status = 'INDEXED'
• AccessibleDocumentQueryService.SEARCHABLE_STATUSES — [INDEXED]

재인덱싱 중 상태를 바꾸면 기존에 검색되던 문서가 새 Version을 처리하는 동안 검색 결과에서 이탈합니다. Document.activateIndexedVersion()의 "포인터와 문서 상태를 함께 변경해 검색 조건이 중간 상태를 관찰하지 않게 한다"는 주석과도 어긋납니다.

왜 currentVersion == null이 아닌가

currentVersion은 업로드 접수 시점에 이미 설정되므로(DocumentUploadService) null 검사로는 최초 인덱싱을 구분할 수 없습니다. markUploaded()가 FAILED일 때만 호출된다는 점을 확인해 status == UPLOADED로 조건을 확정했습니다.

실패 경로는 IndexingFailureTransitionService가 이미 INDEXING을 FAILED 전이 허용 상태로 처리하고 있어 추가 변경이 없습니다. 스키마에 status CHECK 제약이 없어 마이그레이션도 불필요합니다.

✅ 검증

런타임 E2E — 실행 중인 구버전 앱(8080)과 이 브랜치 코드(8081)가 같은 DB에서 Job을 경쟁해 대조 실험이 됐습니다.

doc#15  UPLOADED → INDEXED              [구버전 워커]
doc#16  UPLOADED → INDEXED              [구버전 워커]
doc#17  UPLOADED → INDEXED              [구버전 워커]
doc#18  UPLOADED → INDEXING → INDEXED   ★[이 브랜치 워커]

로그 교차 확인 결과 이 브랜치 워커(workerId=14)가 처리한 건 jobId=23 → documentId=18 하나뿐이며, 정확히 INDEXING이 관찰된 문서입니다.

재인덱싱 회귀 — 이 브랜치 워커가 처리한 10회 모두 처리 중에도 documentStatus가 INDEXED 유지. 검색 가용성 보존 확인.

테스트 — 단위 테스트 10/10 통과. 조건 없이 markIndexing()을 호출하도록 되돌리면 회귀 테스트만 실패하는 것을 확인했습니다(뮤테이션 검증).

전체 스위트는 987개 중 977개 통과이며, 실패 10건은 Redis 미기동 1건과 실행 중인 앱의 워커가 테스트 Job을 낚아채며 생긴 정리 FK 위반·데드락 9건으로 단정 실패는 0건입니다.

📎 참고

이 작업 중 기존 버그를 발견해 별도 등록했습니다 — #233 (LocalDocumentIndexingE2ETest 의미 검색에서 DOCX 누락, develop 기준으로도 실패).

closes #230

[coderabbitai]

Important

Review available on request

• 🔍 Trigger review

Reviews should be triggered manually for repositories with fewer than 10 stars. Select Trigger review above or comment @coderabbitai review to review the latest changes. For a full review, comment @coderabbitai full review.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 9f7bb3a3-739d-4048-b585-12e45c06e8c6

---

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