[Import] 근로자 파일 가져오기·행 검증·재처리 구현 #14

우선순위 결정 · 2026-07-21

이 기능은 중요하지만 M3 대표 AI Workflow 시나리오의 선행 조건은 아닙니다. 현재 서버가 공통 기반과 /health만 구현된 상태이므로, 인증·Workflow·비동기 AI Run·승인·Worker Link·장애 복구를 먼저 완성하기 위해 M4/P1으로 이동합니다.

M3 데모에서 파일 Import가 필수라는 제품 결정이 생기면 #2의 Golden Scenario와 함께 우선순위를 다시 검토합니다. 구현 범위와 보안 기준 자체는 아래 내용대로 유지합니다.

한 줄 요약

HR이 Excel·CSV 근로자 명단을 업로드하고, 열 매핑과 오류 행을 검토한 뒤 선택한 정상 행만 안전하게 등록할 수 있게 합니다.

사용자가 하는 일

1. 파일을 업로드해 가져오기 작업을 만듭니다.
2. 이름·국적·언어·체류 만료일 같은 열을 시스템 필드에 연결합니다.
3. 서버가 각 행을 검증하고 오류 이유를 보여줍니다.
4. HR이 오류 값을 수정하거나 제외할 행을 선택합니다.
5. 정상 행만 확정 등록하고 실패 행은 다시 시도합니다.

소유 API

• POST /api/v1/imports
• GET /api/v1/imports/{importId}
• PUT /api/v1/imports/{importId}/mappings
• POST /api/v1/imports/{importId}/validate
• PATCH /api/v1/imports/{importId}/rows
• POST /api/v1/imports/{importId}/commit
• POST /api/v1/imports/{importId}/retry

상세 요청·응답 예시는 Notion API 명세를 따릅니다.

상태 흐름

UPLOADED → MAPPED → REVIEW_REQUIRED 또는 READY → COMMITTED

실패한 행만 고친 뒤 다시 검증할 수 있어야 하며, 같은 확정 요청이 재전송돼도 근로자가 중복 등록되지 않아야 합니다.

초보자용 구현 순서

1. ImportJob, ImportRow, ColumnMapping 모델과 migration을 만듭니다.
2. 파서는 Controller 밖의 인터페이스로 분리합니다.
3. 원본 행과 수정 값을 분리해 보존합니다.
4. 날짜·Enum·필수값·중복 후보를 행 단위로 검증합니다.
5. 검증 결과에 행 번호, 필드, 오류 코드, 쉬운 설명을 반환합니다.
6. commit에서 선택된 정상 행만 명확한 Transaction 정책으로 등록합니다.
7. Idempotency-Key 또는 동등한 중복 방지 키를 적용합니다.
8. 부분 실패·재시도·다른 사업장 접근 테스트를 작성합니다.

보안·개인정보 규칙

• 허용된 CSV/XLSX 형식과 최대 행·열·파일 크기를 제한합니다.
• 수식 주입, Zip bomb, 경로 조작, 비정상 인코딩을 방어합니다.
• 외국인등록번호·여권번호·계좌번호 열은 가져오기 대상에서 제외하거나 명시적으로 차단합니다.
• 원본 파일의 보존기간과 폐기 시점을 설정값으로 관리합니다.
• AI를 사용해 행을 자동 확정하지 않습니다.
• 오류 응답과 로그에는 전체 행 원문을 남기지 않습니다.

완료 조건

• 정상 행과 오류 행이 한눈에 구분됩니다.
• 오류를 수정하고 같은 작업에서 재검증할 수 있습니다.
• 선택하지 않은 행과 오류 행은 등록되지 않습니다.
• 재시도해도 동일 근로자가 중복 생성되지 않습니다.
• 타 사업장 ImportJob에 접근할 수 없습니다.
• 확정 결과와 실패 사유, actor, request_id가 감사 로그에 남습니다.
• 0건·대용량 경계·부분 실패 통합 테스트가 있습니다.

이번 이슈에서 하지 않는 것

• OCR 기반 문서 인식
• 임의 Excel 매크로 실행
• AI가 데이터 오류를 자동 수정
• 백그라운드 대규모 ETL 플랫폼

선행/후속 관계

• 선행: [Foundation] Spring Boot 개발·검증 기반 정리 #3, [Auth & Security] JWT 인증·사업장 권한·멀티테넌시 구현 #4, [Worker] 근로자 기본정보·서류 메타데이터 API 구현 #5, 파일 업로드는 [Document] 통합 문서함·파일 업로드·문서 준비도 구현 #13
• 병합 순서: #95의 V30/V31 다음에 이 이슈의 V32/V33을 적용합니다. 기능 자체는 OCR에 의존하지 않습니다.
• 후속: [E2E] 제품 대표 복합 요청 시나리오·데모 런북 완성 #10
• 상위 목표: [EPIC] FOWOCO Server Roadmap · Controlled AI Workflow MVP #2