[Workflow][P0] Worker 제출 서류 채택부터 OCR·Renewal 초안 생성까지 연결

[hywznn]

배경

2026-08-13 E2E QA에서 근로자 제출 파일을 HR이 채택해 WorkerDocument가 생성되는 것까지 확인했지만, 이후 OCR 요청과 Renewal 문서 초안 생성이 자동으로 이어지지 않았습니다.

Server #157 병합으로 다음 연결은 이미 완료됐습니다.

• 구조화 답변 제출 → Outbox → Renewal 재실행
• OCR 승인 → Outbox → 동일 Case의 Renewal Task 재실행

남은 단절은 다음 두 곳입니다.

1. 제출 파일 채택 → OCR 실행 요청
2. Worker 답변·OCR 승인 후 Renewal 결과가 generate일 때 문서 초안 생성

목표 흐름

HR 제출 파일 채택
→ WorkerDocumentAdopted Outbox 이벤트
→ OCR 요청·실행
→ HR이 OCR 결과 확인·수정·승인
→ DocumentOcrApproved Outbox 이벤트
→ 승인된 OCR 값을 Renewal Context에 병합
→ 기존 Task·Case를 유지한 채 Renewal 재실행
→ HWP/HWPX 초안 저장
→ HR 최종 검토

OCR 추출값은 Worker 원본 개인정보 컬럼에 자동 덮어쓰지 않습니다. 기존 암호화 OCR 결과를 Renewal Context에서 읽고, 최종 문서도 HR 검토 전에는 발송하지 않습니다.

작업 범위

• WorkerDocument 채택 이벤트를 같은 트랜잭션의 Outbox에 기록
• 채택 문서별 OCR 요청을 멱등 처리
• 여권·외국인등록증만 OCR 대상으로 처리
• OCR 비활성·지원하지 않는 국가·Runtime 실패 상태를 Outbox/OCR 이력에서 확인 가능하게 처리
• Worker 답변 및 OCR 승인 Continuation에서 generate 결과 문서 초안 저장 허용
• 승인된 OCR 원본·HR 수정값을 Renewal Context에서만 사용하고 Worker 개인정보 자동 수정 금지
• 같은 채택 이벤트 재처리 시 event ID를 OCR Idempotency-Key로 사용
• 문서 생성 결과가 준비되면 필수정보 누락이 없는 Task를 NEEDS_INFO로 되돌리지 않고 HR 검토 상태로 전환

완료 조건

• 근로자 제출 파일을 HR이 채택하면 별도 OCR 요청 API 호출 없이 OCR Run이 생성됨
• OCR 결과를 HR이 승인하면 별도 Renewal 실행 API 호출 없이 기존 Task가 재실행됨
• 모든 Slot이 충족되면 생성 문서가 기존 stored_file·worker_document에 연결됨
• 자동 발송·자동 최종 승인은 발생하지 않음
• H2·PostgreSQL 16 전체 테스트 590개 통과
• 실제 OCR·Renewal Provider를 활성화한 Staging E2E 통과

DB·협업 경계

• 기존 Outbox, document_ocr_run, task.business_data, stored_file, worker_document를 재사용
• 신규 Flyway Migration 없음
• Client의 OCR 검토 화면과 AI Runtime 계약 변경은 이 이슈에서 수정하지 않음

구현 PR

• Draft PR feat: 채택 문서 OCR와 Renewal 초안 생성을 연결 #163

[hywznn]

AI/Agent 경계 확인 결과를 공유합니다.

AI에서 확인된 재개 계약

AI POST /internal/v1/workflows/renewal/run은 이미 다음 요청을 수용합니다.

• 기존 taskId
• Server가 승인 후 다시 읽은 ocrResult
• HR/DB에서 보충한 slots

AI #42 작업 브랜치에서 다음 API 시나리오를 회귀 테스트로 고정했습니다.

1차 run
→ 동일 taskId 발급
→ 근로자 안내 대기

2차 run
+ 같은 taskId
+ 승인 OCR 5개 필드
+ 계약·근무 Slot
→ 기존 Task 재개
→ outcome=REVIEW_REQUIRED
→ status=READY_FOR_REVIEW
→ scenario=generate
→ 등록 템플릿 4종 status=generated
→ OCR passport_number가 통합신청서 values에 반영

환경 의존 테스트를 제외한 AI core 결과는 624 passed, 1 skipped, 변경 파일 Ruff 통과입니다.

따라서 #160에서 Server가 담당할 핵심은 다음입니다.

• WorkerDocument 채택 → OCR Run 생성
• HR 승인 OCR 값을 조회해 ocrResult로 구성
• 기존 Case/Task의 taskId와 현재 HR/DB Slot을 함께 AI에 재전달
• generatedDocuments를 stored_file·worker_document에 멱등 저장
• 저장 후 Task를 HR 최종 검토 상태로 유지

포맷 확인 필요

현재 Renewal Graph의 등록 템플릿 4종 생성 결과는 format=hwp입니다. AI 저장소에는 HWPX 템플릿/편집 기능도 있지만 Renewal 생성기는 현재 HWP를 선택합니다.

완료 조건을 반드시 HWPX로 고정한다면 병합 전에 아래 중 하나를 결정해야 합니다.

1. Server가 생성 HWP를 기존 변환 API로 HWPX 변환 후 저장
2. AI Renewal generator를 HWPX 생성으로 변경하고 4종 필드 매핑 회귀 테스트 추가

현재 AI #42 테스트는 실제 구현 사실에 맞춰 HWP 4종 생성을 검증하며, HWPX 생성 완료를 주장하지 않습니다.

Refs fowoco/ai#42