[AI Run] 비동기 실행 상태·재시도·멱등성 구현

[hywznn]

한 줄 목표

AI 분석 요청을 Server DB에 남는 비동기 AiRun resource로 생성·조회·재시도하고, HR이 채택한 candidate만 Task로 만들도록 구현합니다.

사용자 흐름

1. POST /api/v1/ai-runs가 요청·Idempotency-Key를 저장하고 202 + aiRunId 반환
2. Durable worker가 attempt를 만들고 [AI Integration] AiRuntimeClient·계약 검증·장애 격리 구현 #8 AiRuntimeClient 호출
3. Server가 Runtime 응답을 다시 검증하고 candidate 저장
4. Client가 GET /api/v1/ai-runs/{aiRunId}로 기술 상태와 분석 outcome 조회
5. HR이 candidate-decisions로 후보를 채택/폐기
6. 채택 후보만 NEEDS_INFO 또는 READY_FOR_REVIEW Task가 되며 승인·발송은 별도 command

소유 API

• POST /api/v1/ai-runs
• GET /api/v1/ai-runs/{aiRunId}
• POST /api/v1/ai-runs/{aiRunId}/retry
• POST /api/v1/ai-runs/{aiRunId}/candidate-decisions

POST /tasks/analyze, /task-analyses/{id}/confirm, /ai-runs/{id}/confirm은 canonical API가 아닙니다.

기술 상태와 분석 결과

종류	값	의미
AiRun status	QUEUED, RUNNING, RETRYING, SUCCEEDED, FAILED	Server의 실행·복구 상태
analysisOutcome	NEEDS_INFO, REVIEW_REQUIRED	정상 분석 결과와 HR의 다음 행동

낮은 confidence, ambiguity, missing slot은 FAILED가 아닙니다. Runtime 호출·Schema·deadline처럼 기술적으로 결과를 신뢰할 수 없을 때만 실패합니다.

수동 retry는 같은 Run에서 FAILED → RETRYING으로 전이하고 새 AiAttempt를 만듭니다. 이전 attempt 기록은 수정·삭제하지 않습니다.

저장할 정보

• id, companyId, actor, masked input/hash, Idempotency-Key hash
• status, analysisOutcome, attempt/retry count, nextAttemptAt, @Version
• candidate와 validation error, 채택/폐기 decision, Task reference
• requestId, attemptId, traceId, latencyMs, error code
• backend/agent/model/prompt/contextPack/workflowCatalog/contract/knowledge version

민감 원문, 전체 Prompt, Provider secret은 저장하지 않습니다.

구현 범위

• AiRun/AiAttempt/Candidate/Decision migration과 repository
• 같은 company+Idempotency-Key+payload는 같은 Run 반환
• 같은 key의 다른 payload는 409
• [Reliability] 이벤트 유실 방지·재처리 기반 구현 #25 durable event로 queue·restart recovery
• [AI Integration] AiRuntimeClient·계약 검증·장애 격리 구현 #8 client 호출과 server-side response revalidation
• retryable/terminal error taxonomy와 전체 deadline
• 멈춘 RUNNING lease/timeout 복구
• candidate decision version·권한·business rule 검증
• 같은 decision 재전송에서 Task 중복 방지 unique constraint

Retry 소유권

• Server retry: 같은 AiRun에 새로운 AiAttempt를 영속 생성하고 202 + 같은 aiRunId 반환
• AI Runtime retry: 한 attempt 내부의 제한된 Provider retry
• RemoteAiRuntimeClient 투명 retry 금지; 총 호출 횟수가 곱해지지 않게 함
• 같은 retry Idempotency-Key의 반복 호출은 AiAttempt 하나만 생성

완료 조건

• 생성 API가 즉시 재조회 가능한 aiRunId를 반환합니다.
• status와 outcome이 섞이지 않고 허용/금지 전이가 테스트됩니다.
• 중복 요청·decision·서버 재시작에도 Run/Task가 하나입니다.
• 잘못된 JSON·핵심값 손실·민감정보가 candidate나 자동 발송으로 이어지지 않습니다.
• OpenAPI에 성공·누락정보·검토필요·실패·409/422 예시가 있습니다.

경계 밖

• Prompt·Provider·Structured generation: fowoco/ai
• Knowledge content: fowoco/knowledge
• Approval/Worker Link: [Approval & Audit] 승인·반려·외부제출·증빙·완료·감사 로그 구현 #11, [Worker Link] 로그인 없는 근로자 보안 링크와 응답 구현 #7

관계

• Hard blocker: GitHub native blocked by 참조
• Integration prerequisite: [AI Integration] AiRuntimeClient·계약 검증·장애 격리 구현 #8, [Reliability] 이벤트 유실 방지·재처리 기반 구현 #25
• Parent: [EPIC] FOWOCO Server Roadmap · Controlled AI Workflow MVP #2