[Worker] 근로자 기본정보·서류 메타데이터 API 구현 #5

한 줄 요약

HR이 업무에 필요한 최소한의 근로자 정보와 서류 상태를 사업장 범위 안에서 안전하게 관리하도록 API를 구현합니다.

데이터 범위

근로자 기본정보

• 표시 이름
• 국적
• 선호 언어
• 근무 상태
• 체류 만료일
• 계약 시작일·종료일
• 사업장 식별자

서류 상태

• 서류 유형
• 제출 여부
• 유효기간 또는 만료일
• 제출처
• 상태와 비고
• 파일 저장 참조값(선택)

구현 범위

• Worker, WorkerDocument 모델과 migration - WorkerSensitiveData은 후속 이슈에서 다룸
• 근로자 상태와 서류 유형 Enum 정의
• GET /workers — 검색·상태 필터·페이지네이션
• POST /workers
• GET /workers/{workerId}
• PATCH /workers/{workerId}
• POST /workers/{workerId}/documents
• PATCH /workers/{workerId}/documents/{documentId}
• 날짜 관계와 필수 필드 검증
• 사업장 범위와 역할 검사
• 민감정보 마스킹·암호화 경계 정의 → #48로 이관
• 파일 저장은 FileStorage 인터페이스로 분리하되 MVP는 메타데이터 중심으로 구현

개인정보 원칙

• AI 연동에 여권번호, 외국인등록번호, 전화번호, 계좌번호를 전달하지 않습니다.
• 민감정보가 필요하면 기본정보 테이블과 분리하고 암호화합니다.
• 목록 API는 업무에 불필요한 민감 필드를 반환하지 않습니다.
• 삭제가 필요한 경우 물리 삭제보다 정책에 따른 비활성화·보존을 우선 검토합니다.

완료 조건

• HR이 자신의 사업장 근로자를 등록·조회·수정할 수 있습니다.
• 체류 만료일과 계약기간을 유효한 날짜로 검증합니다.
• 근로자에게 서류 상태를 추가하고 갱신할 수 있습니다.
• 다른 사업장 사용자는 동일 ID를 알아도 접근할 수 없습니다.
• 목록 응답에 민감정보가 포함되지 않습니다.
• API·Service·Repository 통합 테스트가 존재합니다.
• Swagger에 요청·응답 예시와 필드 설명이 표시됩니다.

이번 이슈에서 하지 않는 것

• 대용량 원본 파일 업로드
• OCR과 자동 문서 분류
• 여권·외국인등록증 번호의 AI 전송
• 근로자 로그인

선행/후속 관계

• 선행 작업: 개발 기반, 인증·멀티테넌시
• 후속 작업: 업무카드 Context 조회, 근로자 보안 링크, [Worker] 근로자 민감정보(WorkerSensitiveData) 분리 저장·접근 제어 구현 #48
• 상위 목표: [EPIC] FOWOCO Server Roadmap · Controlled AI Workflow MVP #2

용어 도움말

• 마스킹: 값 전체 대신 일부만 보이게 만드는 처리입니다.
• 암호화: 권한이 있는 서버만 원래 값을 복원할 수 있도록 저장하는 방식입니다.
• 메타데이터: 파일 자체가 아니라 종류·상태·만료일 같은 설명 정보입니다.

2026-07-21 · 46개 API 명세 반영

이 이슈가 소유하는 API 6개

• GET /workers
• POST /workers
• GET /workers/{workerId}
• PATCH /workers/{workerId}
• POST /workers/{workerId}/documents
• PATCH /workers/{workerId}/documents/{documentId}

경계

이 이슈는 근로자 기본정보와 서류 메타데이터를 관리합니다. 공통 파일 업로드, 통합 문서함, 업무별 준비도와 요청 초안은 #13이 담당합니다. 먼저 메타데이터만으로 정상 동작하게 만들고, 파일은 fileId 참조로 연결합니다.