feat: OCR 실행 이력 저장과 HR 검토 API 구현

[hywznn]

왜 필요한가요?

Refs #8
Closes #95

HR이 여권·외국인등록증 OCR을 요청하면 Server가 실행 이력을 안전하게 보관하고, AI 응답을 다시 검증한 뒤 HR 검토까지 통제해야 합니다. AI Runtime은 Server DB에 직접 접근하거나 업무 데이터를 자동 확정하지 않습니다.

구조 정리

• 근로자 명단 Import는 #116으로 main에 분리·병합했습니다.
• 이 PR의 변경분에서는 Import 코드·문서·테스트를 제거했습니다.
• 최신 main의 Import Migration V30·V31 다음에는 #117이 V32를 사용합니다.
• 이 OCR PR은 [Worker Link][P0] 근로자 링크 전달 완료 기록·조회 API 구현 #117 다음 순서인 V33·V34를 사용하므로 [Worker Link][P0] 근로자 링크 전달 완료 기록·조회 API 구현 #117 병합 후 병합합니다.

무엇이 바뀌나요?

실행 복구

• OCR 실행 이력과 DocumentOcrExecutionRequested Outbox 이벤트를 같은 트랜잭션에 저장합니다.
• 메모리 ThreadPool 의존을 제거했습니다.
• 서버가 중단되면 만료된 Outbox lease를 다른 worker가 회수합니다.
• 중단 당시 RUNNING이던 실행도 같은 runtime_request_id로 재처리해 완료 또는 실패 상태로 수렴합니다.

HR 검토

• 검토 요청에 corrected_fields를 추가했습니다.
• OCR 원본과 HR 수정값을 서로 다른 AES-256-GCM 암호문으로 저장합니다.
• 감사로그에는 실제 개인정보가 아니라 수정한 field key만 기록합니다.
• APPROVE는 OCR 검토 완료를 의미하며 Worker·Document·Agent slot을 자동 수정하지 않습니다.

Runtime 응답 검증

• 여권·ARC별 필수 field를 확인합니다.
• 날짜를 ISO YYYY-MM-DD로 파싱합니다.
• 여권 국가와 Template ID, ARC Template ID와 앞·뒷면을 대조합니다.
• SUCCEEDED인데 fields가 비었거나 Template 정보가 모순되면 거부합니다.

주요 API

• POST /api/v1/documents/{documentId}/ocr-runs
• GET /api/v1/documents/{documentId}/ocr-runs/{ocrRunId}
• GET /api/v1/documents/{documentId}/ocr-runs/latest
• POST /api/v1/documents/{documentId}/ocr-runs/{ocrRunId}/review

검토 요청 예시:

{
  "expected_version": 2,
  "decision": "APPROVE",
  "corrected_fields": {
    "passport_number": "M12345678"
  }
}

응답의 result.fields는 AI 원본이고 corrected_fields는 HR 수정값입니다.

Migration

• V33__create_document_ocr_run.sql
• V34__prepare_document_ocr_run_rls.sql

검증

• 최신 main 기반으로 OCR commit만 재구성
• feat: OCR 실행 이력 저장과 HR 검토 API 구현 #112 diff에 Worker Import 파일이 없음을 확인
• ./gradlew clean test
• OCR API 권한·사업장 격리·멱등성 통합 테스트
• Outbox lease 만료 및 서버 중단 후 OCR 복구 테스트
• HR 수정값 암호화·감사로그 비노출 테스트
• 빈 성공 결과·잘못된 날짜·Template·문서 면 계약 테스트
• PostgreSQL 17 Migration·tenant context·RLS·Import 공존 테스트
• [Worker Link][P0] 근로자 링크 전달 완료 기록·조회 API 구현 #117 병합 후 최신 main에서 Migration·전체 테스트 재검증

병합 전 남은 연동 조건

• AI #23을 feat/DB_to_SERVER에 병합
• AI Stateless OCR 브랜치를 develop 대상으로 PR 생성·검증
• 실제 파일로 Server ↔ AI smoke test
• Client OCR 실행·polling·수정·검토 화면 연결
• 대표 OCR E2E 확인

위 조건 전까지 AI_OCR_ENABLED=false, DOCUMENT_OCR_ENABLED=false를 유지합니다. Server 코드는 준비되지만 실제 OCR 서비스 활성화는 별도 확인이 필요합니다.