[AI Run] 발화문 분석과 누락 정보 API·실행 이력 구현

[hywznn]

왜 필요한가요?

Refs #77
Refs #24

프론트가 자연어 업무 요청을 보내도 이를 접수·조회하거나, Agent가 요청한 DB Slot을 보충한 뒤 HR의 추가 답변을 다시 전달할 API와 영속 리소스가 없었습니다.

무엇이 바뀌나요?

• POST /api/v1/ai-runs: 단일 instruction과 Idempotency-Key를 받아 202로 접수합니다.
• GET /api/v1/ai-runs/{aiRunId}: 실행 상태, 분석 결과, 질문, 후보를 조회합니다.
• POST /api/v1/ai-runs/{aiRunId}/answers: HR 답변을 저장하고 새 AiAttempt로 ANALYZE를 재호출합니다.
• V12: ai_run, ai_attempt, ai_question, ai_candidate와 tenant-aware FK·UNIQUE를 추가합니다.
• V14: PostgreSQL RLS 정책을 준비합니다. V13은 feat: 근로자 보안 링크(Worker Link) 발급, 안내, 문서제출, 응답제출 구현 #76 Worker Link가 소유합니다.
• PLAN → CONTEXT_REQUIRED → Server Slot 조회 → ANALYZE → NEEDS_INFO/REVIEW_REQUIRED 흐름을 연결합니다.
• 같은 사업장·같은 Idempotency-Key·같은 발화문은 기존 Run을 반환하고, 다른 발화문이면 409를 반환합니다.
• 생성과 답변 제출은 감사로그에 기록합니다.

Intent 입력 계약

• 빠른 선택 태그는 Client 입력창에 예시 문구를 채우는 UI 기능으로만 사용합니다.
• Client는 사용자가 최종 작성한 발화문만 instruction으로 전송합니다.
• intentHint 필드와 , EXPIRY_RENEWAL 같은 Intent 접미사는 사용하지 않습니다.
• Server는 Intent를 추가하거나 별도로 판정하지 않고 같은 instruction을 AI Runtime에 전달합니다.
• 최종 Intent는 Runtime 응답의 detectedIntent를 저장·반환합니다.
• POST /api/v1/ai-runs의 외부 API 구조는 변경되지 않습니다.

{
  "instruction": "응웬반안 체류연장 준비해줘"
}

데모 범위와 후속 작업

현재 PR은 대표 흐름을 빠르게 검증하기 위한 최소 세로 구현입니다. DB transaction을 닫은 뒤 Runtime을 호출하지만, 호출 완료 후 202를 반환하는 동기식 demo runner입니다. 서버 재시작에도 자동 복구되는 durable worker·retry·candidate decision은 #24 후속 범위로 남깁니다.

실제 AI Runtime은 아직 AI #6의 최소 camelCase 계약을 구현하지 않아 현재 422를 반환합니다. Server fixture 기반 왕복은 통과했으며 AI #6 반영 후 실제 Runtime smoke test를 다시 수행합니다.

검증

• ./gradlew clean test — BUILD SUCCESSFUL
• 원문 instruction 전달과 intentHint 미전송 확인
• 태그 없는 발화문에도 Runtime의 detectedIntent가 최종 Intent로 저장되는지 확인
• PostgreSQL 17에서 전체 테스트 — BUILD SUCCESSFUL
• 단일 근로자 3 Attempt 대표 흐름 검증
• 멱등성 재요청 및 payload 충돌 검증
• 타 사업장 AiRun 404 검증
• 감사로그와 PostgreSQL schema·tenant 격리·RLS 계약 검증

브라우저 통합 검증

• 실제 Client 요청에서 Idempotency-Key CORS preflight 차단을 발견했습니다.
• CorsConfig 허용 헤더와 OPTIONS 통합 테스트를 추가했습니다.
• Client → Server → AiRun 저장 → 실제 AI Runtime 호출 → 실패 결과 화면 표시까지 확인했습니다.
• 현재 실제 Runtime은 AI [Task Workflow] 업무카드·체크리스트·상태 전이 구현 #6 미반영으로 INVALID_REQUEST_CONTRACT를 반환합니다.
• 성공 질문·답변·후보 흐름은 AiRunApiIntegrationTest와 Client 테스트로 검증했습니다.

병합 전 확인

• 현재 PR head의 전체 테스트
• Intent 태그 없는 원문 전달 계약 반영
• #76의 canonical public path·업로드 멱등성·CORS 리뷰 반영 후 먼저 병합
• feat: 근로자 보안 링크(Worker Link) 발급, 안내, 문서제출, 응답제출 구현 #76 병합 후 최신 main rebase 및 PostgreSQL 재검증
• AI [Task Workflow] 업무카드·체크리스트·상태 전이 구현 #6 계약 반영 후 실제 Server ↔ Runtime smoke test