Repository navigation
[Document] 통합 문서함·파일 업로드·문서 준비도 구현 #13
Description
한 줄 요약
HR이 파일을 한 번 안전하게 올리고, 사업장 문서함에서 찾고, 특정 업무에 필요한 서류가 준비됐는지 확인한 뒤 근로자 요청 초안을 만들 수 있게 합니다.
이 이슈는 파일 원본과 문서 메타데이터의 연결을 담당합니다. 근로자별 서류 등록·수정은 #5가 담당합니다.
사용자가 하는 일
- HR이 파일을 업로드합니다.
- 서버가 확장자·크기·사업장 권한을 검사하고
fileId를 반환합니다. - HR이 근로자 서류에
fileId를 연결합니다. - 업무카드에서 필요한 서류의 준비 상태를 확인합니다.
- 부족한 서류가 있으면 근로자에게 보낼 요청 초안을 저장합니다.
소유 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 |
초보자용 구현 순서
StoredFile메타데이터와FileStorage인터페이스를 정의합니다.- Local 저장 구현과 테스트용 Fake 구현을 만듭니다.
- 업로드 검증 후
fileId만 반환하는 API를 만듭니다. WorkerDocument와 파일 참조를 연결합니다.- 문서함 검색·필터·페이지네이션을 구현합니다.
- Workflow Catalog의 필수 서류와 보유 서류를 비교해 준비도를 계산합니다.
- 요청 초안은 승인 전 내부 데이터로만 저장합니다.
- 정상·권한·타 사업장·악성 파일명·용량 초과 테스트를 작성합니다.
보안·구현 규칙
- 파일명으로 저장 경로를 만들지 않고 서버가 생성한 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/knowledgeWorkflow Catalog입니다. - Server는 Catalog 정의와 실제 Worker/Document/Task 데이터를 비교해 projection만 만들며 Catalog YAML을 독자 수정하지 않습니다.
- OCR, 모델 기반 문서 분류, Prompt는 이 이슈 범위가 아닙니다.
Activity
chaeliki commentedon Jul 28, 2026
2026-07-28 · #13 완료
PR #57에서 소유 API 4개(파일 업로드,
통합 문서함 조회, 서류 준비도, 문서 요청 초안)를 모두 구현·통합 테스트했습니다.
file/document패키지 분리 (docs/project-structure.md 기준)완료 조건 중 후속으로 넘긴 것
"만료 임박" 구분은 #60에서 SubmissionStatus
확정값이 정해진 뒤 그 값을 재사용해 반영할 예정입니다 ([Worker] WorkerDocument-Task 연결 (누락 범위 추가) #60 완료 후 다시 갈아엎어야 할 수 있어 보류).
findByIdAndCompanyId로 구조적으로차단되지만, 이를 증명하는 통합 테스트는 아직 없습니다.
나머지는 정상 완료됐습니다.
PR #57이 머지되면 이 이슈가 자동으로 닫힙니다.