[Document] 통합 문서함·파일 업로드·문서 준비도 구현

[hywznn]

한 줄 요약

HR이 파일을 한 번 안전하게 올리고, 사업장 문서함에서 찾고, 특정 업무에 필요한 서류가 준비됐는지 확인한 뒤 근로자 요청 초안을 만들 수 있게 합니다.

이 이슈는 파일 원본과 문서 메타데이터의 연결을 담당합니다. 근로자별 서류 등록·수정은 #5가 담당합니다.

사용자가 하는 일

1. HR이 파일을 업로드합니다.
2. 서버가 확장자·크기·사업장 권한을 검사하고 fileId를 반환합니다.
3. HR이 근로자 서류에 fileId를 연결합니다.
4. 업무카드에서 필요한 서류의 준비 상태를 확인합니다.
5. 부족한 서류가 있으면 근로자에게 보낼 요청 초안을 저장합니다.

소유 API

• POST /files — 공통 파일 업로드
• GET /documents — 사업장 통합 문서함 조회
• GET /tasks/{taskId}/document-readiness — 업무별 준비도 확인
• PUT /tasks/{taskId}/document-request-draft — 문서 요청 초안 저장

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

API	요청	응답 (성공)	오류	허용 역할
POST /files	Multipart: file, purpose, taskId?, workerId?	201: fileId, name, mimeType, size, scanStatus	400/401/403/413/415/422	ADMIN, HR
GET /documents	Query: workerId?, taskId?, documentType?, status?, expiryBefore?, page?, size?	200: items, page, size, totalElements	400/401/403	ADMIN, HR, VIEWER
GET /tasks/{taskId}/document-readiness	Path: taskId	200: required, available, missing, expired, completionBlocked	401/403/404	ADMIN, HR, VIEWER
PUT /tasks/{taskId}/document-request-draft	Path: taskId / Body: language, documentTypes, message, expectedVersion	200: draftId, version, reviewStatus	400/401/403/404/409/422	ADMIN, HR

초보자용 구현 순서

1. StoredFile 메타데이터와 FileStorage 인터페이스를 정의합니다.
2. Local 저장 구현과 테스트용 Fake 구현을 만듭니다.
3. 업로드 검증 후 fileId만 반환하는 API를 만듭니다.
4. WorkerDocument와 파일 참조를 연결합니다.
5. 문서함 검색·필터·페이지네이션을 구현합니다.
6. Workflow Catalog의 필수 서류와 보유 서류를 비교해 준비도를 계산합니다.
7. 요청 초안은 승인 전 내부 데이터로만 저장합니다.
8. 정상·권한·타 사업장·악성 파일명·용량 초과 테스트를 작성합니다.

보안·구현 규칙

• 파일명으로 저장 경로를 만들지 않고 서버가 생성한 ID를 사용합니다.
• 허용 확장자, MIME type, 크기 제한을 서버에서 검사합니다.
• 다운로드 권한은 항상 company_id와 역할을 다시 검사합니다.
• 원본 신분증 이미지와 계약서 전문을 AI로 보내지 않습니다.
• 로그에 파일 본문·민감한 파일명·다운로드 URL을 남기지 않습니다.
• S3 호환 저장소로 교체할 수 있도록 Controller가 Local 경로를 알지 않게 합니다.

완료 조건

• 다른 사업장의 파일·문서를 조회하거나 연결할 수 없습니다.
• 잘못된 파일은 일관된 오류 형식과 request_id로 거부됩니다.
• 문서 준비도 결과에 준비됨·누락·만료 임박 사유가 구분됩니다.
• 요청 초안 저장만으로 Worker Link나 메시지가 자동 발송되지 않습니다.
• Swagger 예시와 통합 테스트가 있습니다.
• 파일 생성·연결·초안 변경이 감사 로그에 남습니다.

이번 이슈에서 하지 않는 것

• OCR 전체 구현
• 바이러스 검사 인프라 운영
• 외부기관 자동 제출
• 대용량 미디어 저장

선행/후속 관계

• 선행: [Foundation] Spring Boot 개발·검증 기반 정리 #3, [Auth & Security] JWT 인증·사업장 권한·멀티테넌시 구현 #4, [Worker] 근로자 기본정보·서류 메타데이터 API 구현 #5, [Task Workflow] 업무카드·체크리스트·상태 전이 구현 #6
• 연결: [Worker Link] 로그인 없는 근로자 보안 링크와 응답 구현 #7, [Approval & Audit] 승인·반려·외부제출·증빙·완료·감사 로그 구현 #11
• 상위 목표: [EPIC] FOWOCO Server Roadmap · Controlled AI Workflow MVP #2

저장소 경계 · 2026-07-22

• FileStorage port, upload 상태, document readiness 계산과 실제 제출 증빙은 server가 소유합니다.
• 필요한 document/checklist 정의의 원본은 exact version으로 고정한 fowoco/knowledge Workflow Catalog입니다.
• Server는 Catalog 정의와 실제 Worker/Document/Task 데이터를 비교해 projection만 만들며 Catalog YAML을 독자 수정하지 않습니다.
• OCR, 모델 기반 문서 분류, Prompt는 이 이슈 범위가 아닙니다.