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

[hywznn]

한 줄 목표

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

사용자 흐름

1. HR이 체류연장 준비 태그를 누르고 발화문을 입력합니다.
2. 빠른 선택 태그는 입력창에 예시 문구를 채우는 UI 용도로만 사용합니다.
3. Client는 사용자가 최종 작성한 발화문을 instruction 하나로 전송합니다.
4. Agent가 requiredFieldKeys를 반환하면 Server가 #74를 통해 허용된 DB 정보만 조회합니다.
5. DB로 채울 수 없는 Slot은 질문으로 화면에 반환합니다.
6. HR 답변을 저장하고 새 AiAttempt로 Agent를 다시 호출합니다.

API 범위

요청 생성

POST /api/v1/ai-runs

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

• 별도 intentHint 필드는 사용하지 않습니다.
• Client와 Server는 instruction 뒤에 Intent 코드를 붙이지 않습니다.
• Server는 Intent를 별도로 판정하지 않고 Runtime 응답의 detectedIntent를 최종 Intent로 사용합니다.
• 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 태그가 덧붙지 않습니다.
• 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 사용

2026-08-05 · 완료 상태

• 구현 Draft PR: [AI Run] 발화문 분석과 누락 정보 API·실행 이력 구현 #82
• 구현된 초안: POST /api/v1/ai-runs, GET /api/v1/ai-runs/{aiRunId}, POST /api/v1/ai-runs/{aiRunId}/answers
• PostgreSQL V12/V14, 멱등성, tenant 격리, OpenAPI, 통합 테스트가 PR에 포함되어 있습니다.
• PR #82가 main에 병합되었습니다.
• 실제 AI Runtime 호출은 Server까지 도달하지만, 현재 AI Runtime이 PLAN 요청을 아직 받지 못해 422 INVALID_REQUEST_CONTRACT가 발생합니다. 계약 Owner인 fowoco/ai#6 반영 뒤 성공 경로를 다시 확인합니다.
• feat: 근로자 보안 링크(Worker Link) 발급, 안내, 문서제출, 응답제출 구현 #76 병합 후 #82를 최신 main에 맞추고 PostgreSQL 17 전체 테스트를 통과했습니다.