[AI Integration][P0] Renewal 근로자 안내 REVIEW_REQUIRED 계약 수용

[hywznn]

배경

AI #44는 Language Assistant 미구성·호출 실패·대상 언어 검토 필요 시 근로자용 placeholder를 만들지 않고 다음처럼 fail-closed 반환합니다.

{
 "scenario": "ask_worker",
 "status": "READY_FOR_REVIEW",
 "outcome": "REVIEW_REQUIRED",
 "workerRequestMessage": null,
 "guideReviewRequired": true,
 "guideFailureCode": "LANGUAGE_ASSISTANT_NOT_CONFIGURED",
 "caseSignals": ["REVIEW_WORKER_GUIDE"]
}

현재 Server origin/main은 이 응답을 그대로 수용하지 못합니다.

• RenewalRunResponse에 신규 guide 필드 없음
• RenewalRuntimeContractValidator.CASE_SIGNALS에 REVIEW_WORKER_GUIDE 없음
• scenario=ask_worker이면 항상 workerRequestMessage 비어 있지 않아야 한다고 검증
• 결과 적용부가 Agent의 안내 검토 상태를 Task/업무 메타데이터에 별도로 보존하지 않음

따라서 AI #44는 이 Server 계약이 들어오기 전에는 병합/배포하면 안 됩니다.

Server 작업

• RenewalRunResponse에 guideReviewRequired, guideFailureCode 추가
• failure code 길이·문자 allow-list 검증
• REVIEW_WORKER_GUIDE를 허용 Case Signal에 추가
• ask_worker 정상 경로 검증
  • guideReviewRequired=false
  • workerRequestMessage 비어 있지 않음
  • 기존 Worker 안내 초안 저장 가능
• ask_worker 검토 경로 검증
  • guideReviewRequired=true
  • outcome=REVIEW_REQUIRED
  • status=READY_FOR_REVIEW
  • workerRequestMessage=null
  • caseSignals에 REVIEW_WORKER_GUIDE
  • 자동 WorkerLink/SMS/안내 초안 확정 금지
• guideFailureCode와 검토 필요 상태를 renewal_execution 메타데이터·감사 로그에 보존
• HR이 안내를 검토·수정한 뒤에만 기존 승인/WorkerLink 발급 흐름 진행
• 정상 안내·미구성·Provider 예외·번역 failed·warning 계약 테스트
• AI feat: 사업장 회원가입과 초기 관리자 계정 생성 구현 #44 브랜치와 Server 실제 HTTP smoke

상태 전이 주의

현재 RenewalExecutionResultApplier는 Agent 응답의 status/outcome을 그대로 Task 상태로 적용하지 않고 Slot·체크리스트와 critical fingerprint로 상태를 계산합니다.

안내 검토가 필요한 경우 NEEDS_INFO로 잘못 회귀하거나 DocumentRequestDraft를 저장하지 않도록, Server가 사용할 실제 HR 검토 상태와 다음 행동을 명시적으로 결정해야 합니다. 자동 발송과 자동 승인은 금지합니다.

완료 조건

• AI #44의 fail-closed 응답이 Runtime validator를 통과
• Worker 안내 초안·WorkerLink·SMS가 자동 생성/발송되지 않음
• HR 화면에서 안내 실패 사유와 검토 행동을 확인 가능
• HR 검토 후에만 근로자 안내 흐름 재개
• 기존 정상 WAITING_WORKER 경로 회귀 없음

Refs fowoco/ai#44
Refs fowoco/ai#42

[hywznn]

AI #44 병합 후 실제 Server ↔ AI HTTP Smoke Test를 완료했습니다.

• AI: develop 병합 커밋 06e29e5
• Server: main 병합 커밋 b3a2624
• Bearer 인증 포함 POST /internal/v1/workflows/renewal/run: 200
• Server POST /api/v1/tasks/{taskId}/renewal-run: 200
• 결과: REVIEW_REQUIRED, REVIEW_WORKER_GUIDE, guideReviewRequired=true, guideFailureCode=LANGUAGE_ASSISTANT_NOT_CONFIGURED
• 기존 NEEDS_INFO Task는 잘못 회귀하지 않고 HR 검토용 DRAFT로 전환
• 자동 안내 초안·Worker Link·SMS 생성 없음
• 승인 전 Worker Link 발급: 422 TASK_NOT_APPROVED
• HR 초안 작성 → 승인 요청 → 승인 후 Worker Link 발급: 성공, deliveryStatus=NOT_SENT
• Server 단계 로그: RENEWAL_RUNTIME_CALL status=SUCCESS 확인
• AI 관련 계약 테스트 22개 통과

실제 병합 버전 간 계약과 fail-closed 흐름이 정상 동작하므로 이슈를 완료 처리합니다.

[hywznn]

병합 후 계약·실통신 검증 결과

검증 일시: 2026-08-15

검증 대상

• Server PR feat: 근로자 안내 실패를 HR 검토로 안전하게 전환 #179 병합 커밋: b3a2624
• AI PR fix(agent): 근로자 안내 실패를 HR 검토로 안전하게 전환 ai#44 병합 커밋: 06e29e5
• 검증 경로: 실제 Server RemoteRenewalRuntimeClient → RenewalRuntimeContractValidator → 실제 AI FastAPI POST /internal/v1/workflows/renewal/run

자동 테스트

Server 병합 커밋에서 다음 핵심 계약·통합 테스트를 실행했습니다.

• RenewalRuntimeContractValidatorTest
• RemoteRenewalRuntimeClientWireMockTest
• RenewalExecutionIntegrationTest
• 결과: BUILD SUCCESSFUL

AI 병합 커밋에서 다음을 실행했습니다.

• tests/agents/test_workflow_bridges.py
• tests/api/test_workflows_endpoint.py
• 결과: 12 passed
• 변경 파일 Ruff: 통과

Server PR #179의 GitHub CI와 PostgreSQL 16 검증도 성공 상태를 확인했습니다.

실제 Server → AI HTTP Smoke

Language Assistant 미구성 조건으로 실제 AI 프로세스를 실행하고 Server의 실제 HTTP Client와 Validator를 통해 호출했습니다.

AI 응답 핵심값:

{
 "intent": "EXPIRY_RENEWAL",
 "workflowId": "WF-STY-001",
 "status": "READY_FOR_REVIEW",
 "outcome": "REVIEW_REQUIRED",
 "scenario": "ask_worker",
 "workerRequestMessage": null,
 "guideReviewRequired": true,
 "guideFailureCode": "LANGUAGE_ASSISTANT_NOT_CONFIGURED",
 "caseSignals": ["REVIEW_WORKER_GUIDE"]
}

확인 결과:

• Server가 신규 guide 필드를 역직렬화함
• REVIEW_WORKER_GUIDE를 허용함
• 안내 검토 경로에서 workerRequestMessage=null을 허용함
• Server Runtime Validator가 전체 응답 계약을 통과시킴
• 요청·시도·Task ID와 WF-STY-001 일치 검증 통과
• Bearer Token 누락 요청은 AI에서 401로 거부됨
• Server 안내 검토 상태 적용 회귀 테스트 통과

결론

AI 안내 생성 실패를 임시 근로자 문구로 대체하지 않고 Server의 HR 검토 흐름으로 안전하게 전달하는 #162 계약이 병합 후 정상 동작합니다.

로컬 실제 Server↔AI 계약 스모크까지 통과했으므로 이 이슈를 완료 처리합니다. Kubernetes 배포 환경의 실제 Provider·DB 포함 E2E는 배포 검증 범위에서 별도로 확인합니다.

Refs #179
Refs fowoco/ai#44