[Document][P0] 문서 상세 조회·상태 표현·HWP/HWPX 업로드 보완

[chaeliki]

배경

fowoco/client PR #174, #228에서 fowoco/server의 통합 문서함 API(#13)를
실제 화면에 연동하며 발견된 문제들을 정리합니다.

1. GET /documents 응답에 version 필드 누락

PATCH /workers/{workerId}/documents/{documentId}는 expected_version이
필수인데, GET /documents 응답(DocumentItemResponse)에 이 값이 없어
DocumentDetailPage의 확인/반려 버튼이 실제 연동이 안 되고 있습니다.
WorkerDocument 도메인엔 이미 version이 있어 응답 DTO
노출만 하면 해결됩니다.

2. 단건 조회 API 부재

GET /documents/{documentId}가 없어서, 프론트가 전체 목록을 받아
worker_document_id로 직접 찾는 방식으로 우회하고 있습니다.

3. HWP/HWPX 업로드 지원 추가

POST /files가 image/jpeg·png·webp, application/pdf만 허용합니다.
HWP/HWPX 업로드가 실제로 필요하므로 지원을 추가합니다.

참고

• 통합 문서함/근로자 서류 실제 API 연동 (Document) client#174, 통합 문서함/근로자 서류 실제 Document API 연동 client#175, feat: WorkerDetailPage에 근로자 서류 등록 + 파일 업로드 실연동 client#228, [Document] HWP/HWPX 문서 파일 업로드 UI 및 API 연동 client#158

완료 조건

• DocumentItemResponse에 version 필드 추가
• GET /documents/{documentId} 단건 조회 API 신설
• HWP/HWPX MIME 타입을 ALLOWED_MIME_TYPES에 추가

2026-08-04 · PWF3 문서함 보완 원칙

단건 응답은 화면이 목록 전체를 다시 받지 않아도 검토·반려를 수행할 수 있도록 다음 값을 함께 반환합니다.

• version: 수정 충돌을 막는 expectedVersion의 기준값
• Worker·Task 참조와 문서 유형
• 제출 상태와 만료일
• 연결된 파일의 ID·표시 파일명·MIME·크기·검사 상태

서로 다른 상태를 하나의 status에 섞지 않습니다.

상태	소유 모델
파일 검사 상태	StoredFile.scanStatus
근로자 서류 제출 상태	WorkerDocument — enum·DB 제약 변경은 #60 소유
유효·만료 판단	서류 만료일을 기준으로 Server가 계산
업무 준비도	기존 GET /tasks/{taskId}/document-readiness가 계산

HWP/HWPX 허용 시 확장자만 믿지 않고 MIME·크기·파일 시그니처 정책과 다운로드 권한을 함께 검증합니다.

[BcKmini]

#227/#228에서 서류 등록이랑 파일 연결은 이미 붙임

• 등록하는 문서는 등록 응답에서 바로 version을 받아서 파일 연결 가능

3번(HWP/HWPX)도 추가되면 FileUploadModal(#158, 지금 HWP 업로드가 데모로만 동작 중)을 실제 업로드로 연결 예정