fix(agent): 근로자 안내 실패를 HR 검토로 안전하게 전환

[hywznn]

Closes#42

왜 필요한가요?

2026-08-13 E2E QA에서 Language Assistant가 미구성되거나 대상 언어 생성에 실패해도 Renewal Graph가 한국어·영어 placeholder를 근로자 발송문으로 확정하는 문제가 확인됐습니다.

이 경로는 alien_registration_number, both_missing 같은 내부 Slot·검증 키까지 노출할 수 있었습니다. 원인은 LanguageGuideBridge 실패를 placeholder로 숨긴 뒤 mark_ask_worker()가 발송 가능한 문장을 새로 만드는 fail-open 동작이었습니다.

무엇이 바뀌나요?

• Language Assistant 미구성·호출 예외·검토 필요 결과를 fail-closed 처리
• 안전하지 않은 안내는 다음 결과로 반환
  • outcome=REVIEW_REQUIRED
  • status=READY_FOR_REVIEW
  • workerRequestMessage=null
  • caseSignals=["REVIEW_WORKER_GUIDE"]
• 응답에 발송 차단 상태를 추가
  • guideReviewRequired
  • guideFailureCode
• 정상 생성·검증을 통과한 쉬운 한국어와 대상 언어만 WAITING_WORKER로 사용
• 내부 Slot·문서 조합 키로 placeholder 근로자 문장을 만들던 로직 제거

응답 예시

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

OCR 재개 계약 테스트

같은 taskId를 사용해 아래 흐름을 API 테스트로 고정했습니다.

1차 Renewal run
→ 정상 베트남어 안내
→ WAITING_WORKER
2차 Renewal run
+ 같은 taskId
+ 승인 OCR 5개 필드
+ 계약·근무 Slot
→ REVIEW_REQUIRED
→ READY_FOR_REVIEW
→ 등록 문서 4종 status=generated
→ OCR 여권번호가 통합신청서 values에 반영

이 테스트는 AI가 Server 이벤트를 소비한다는 뜻이 아닙니다. WorkerDocument 채택·OCR 실행/승인·동일 Task 재호출·생성 파일 영속화는 Server #160 범위입니다.

검증

• 현재 develop 기반 전체: 628 passed, 6 failed, 1 skipped
  • 실패 4건: 기본 설치에 Qdrant 선택 의존성 없음
  • 실패 2건: macOS에 PowerShell 없음
• 환경 의존 파일 분리 core: 617 passed, 1 skipped
• 변경 Python 파일 Ruff: 통과
• git diff --check: 통과

병합 전 확인

• Server가 REVIEW_WORKER_GUIDE를 자동 발송하지 않고 HR 검토로 처리
• Server가 신규 guideReviewRequired, guideFailureCode를 허용
• Knowledge #51의 Catalog 표시명 계약과 후속 연결
• 실제 Language Provider 성공/실패 staging smoke
• Server #160의 승인 OCR → 동일 Task 재호출 → 생성 파일 저장 smoke

포맷 주의

현재 Renewal 등록 문서 4종은 실제 구현대로 format=hwp입니다. HWPX가 데모 완료 조건이면 Server 변환 또는 AI generator 변경을 별도로 결정해야 합니다. 이 PR은 HWPX 완료를 주장하지 않습니다.

Refs fowoco/server#160
Refs fowoco/knowledge#51

[hywznn]

Server origin/main 호환성을 추가 확인했습니다.

현재 Server는 아래 이유로 이 PR의 fail-closed 응답을 거부합니다.

1. REVIEW_WORKER_GUIDE가 허용 Case Signal 목록에 없음
2. scenario=ask_worker이면 workerRequestMessage를 무조건 요구함
3. 신규 guideReviewRequired, guideFailureCode를 아직 모델·감사 이력에 보존하지 않음

Server 후속 이슈를 별도로 만들었으며, 해당 계약 반영 전까지 이 PR은 Draft를 유지합니다. AI 코드·단위/API 테스트는 완료됐지만 현재 배포 Server와의 실통신은 아직 통과 조건이 아닙니다.

[BcKmini]

리뷰

diff 확인했습니다. Fail-open → fail-closed 전환, 설계 방향 좋습니다.

• LanguageGuideBridge가 미구성/예외/검증실패 시 이전처럼 내부 slot·validation 키(alien_registration_number, both_missing 등)로 placeholder 문장을 만들지 않고, worker_request_message=None + guide_review_required=True + 안전한 guide_failure_code로 명확히 닫음
• mark_ask_worker도 동일하게 fail-closed로 정리, case_signals=["REVIEW_WORKER_GUIDE"]로 HR 검토 신호만 남김
• 테스트가 미구성/예외/번역실패 세 갈래를 각각 커버하고, 승인 OCR로 같은 taskId 재호출해 실제 초안 생성까지 이어지는 통합 테스트도 있음

머지 전에 짚어야 할 점 — PR 본문 체크리스트가 전부 미체크 상태입니다:

• Server가 guideReviewRequired/guideFailureCode 필드를 아직 인식 못 하면, 이 PR 머지 후 근로자는 이전엔 (부정확하더라도) 안내 문구를 받았는데 이제는 아무 발송도 안 되고 HR 검토 화면도 없으면 그냥 조용히 멈추는 회귀가 생길 수 있습니다.
• Knowledge #51 연동, 실제 Language Provider staging smoke, Server #160 스모크도 미확인 상태입니다.

베이스가 develop이라 즉시 프로덕션에 나가는 건 아닐 걸로 보이지만, Server 쪽 대응 없이 main으로 승격되면 위 회귀가 실제로 발생할 수 있으니 머지 타이밍은 Server #160/체크리스트 진행 상황 보고 판단해주세요.