[AI Run][P0] 발화문 입력과 누락 Slot 답변 API 구현

[hywznn]

한 줄 목표

업무 요청 화면에서 발화문 하나를 접수하고, Agent 분석 후 부족한 Slot 질문을 화면에 보여 주고 답변을 다시 받습니다.

사용자 흐름

1. HR이 체류연장 준비 태그를 누르고 발화문을 입력합니다.
2. 선택 태그가 있으면 Client가 발화문, INTENT_TAG 형태의 문자열 하나로 합칩니다.
3. Client는 Server에 instruction 하나만 전송합니다.
4. Agent가 requiredFieldKeys를 반환하면 Server가 #74를 통해 허용된 DB 정보만 조회합니다.
5. DB로 채울 수 없는 Slot은 질문으로 화면에 반환합니다.
6. HR 답변을 저장하고 새 AiAttempt로 Agent를 다시 호출합니다.

API 범위

요청 생성

POST /api/v1/ai-runs

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

• 별도 intentHint 필드는 사용하지 않습니다.
• Client는 위 instruction 하나만 보냅니다. Server는 Runtime JSON에 requestId와 phase를 추가하고, attemptId·version·deadline은 내부에서만 관리합니다.
• 응답은 202 Accepted + aiRunId입니다.

상태·질문 조회

GET /api/v1/ai-runs/{aiRunId}

• detectedIntent, status, analysisOutcome
• questions[{slotKey, label, inputType, required}]

Slot 답변 제출

POST /api/v1/ai-runs/{aiRunId}/answers

{
  "expectedVersion": 2,
  "answers": {
    "new_contract_end_date": "2027-12-31",
    "monthly_wage": "2500000"
  }
}

MVP 규칙

• 한 요청은 근로자 한 명만 처리합니다.
• Client는 근로자 UUID를 보내지 않습니다.
• Agent는 SQL이나 DB에 직접 접근하지 않고 requiredFieldKeys만 반환합니다.
• Server가 JWT의 companyId 범위에서 근로자와 허용된 필드를 조회합니다.
• Slot 타입과 검증 규칙은 Knowledge/Workflow Catalog를 따릅니다.
• 답변 제출은 새 AiAttempt를 만들며, Agent 결과만으로 Task를 자동 승인하지 않습니다.

완료 조건

• 단일 instruction으로 AiRun을 생성하고 202 + aiRunId를 반환합니다.
• 태그가 선택된 경우 발화문, INTENT_TAG가 그대로 저장·전달됩니다.
• Agent가 분석한 Intent와 부족한 Slot 질문을 조회할 수 있습니다.
• HR 답변을 형식 검증 후 저장하고 분석을 재개합니다.
• 다른 사업장의 AiRun 접근을 차단합니다.
• OpenAPI와 정상·권한·유효성·버전 충돌 테스트를 작성합니다.

관계

• Parent: [AI Run] 비동기 실행 상태·재시도·멱등성 구현 #24
• HTTP Runtime 기반: [AI 연동] AI Runtime HTTP 연결과 장애 격리 구현 #56
• DB Slot 조회·Agent 재호출: [AI Run][P0] Agent 요청 Slot 조회·재호출 오케스트레이션 구현 #74
• Agent PLAN/ANALYZE 계약: [Agent Contract][P0] PLAN·ANALYZE와 Slot 요청 계약 ai#6
• Flyway: #76의 V11 병합 후 #24가 V12 사용