배경
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 업로드가 실제로 필요하므로 지원을 추가합니다.
참고
완료 조건
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·크기·파일 시그니처 정책과 다운로드 권한을 함께 검증합니다.
배경
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 업로드가 실제로 필요하므로 지원을 추가합니다.
참고
완료 조건
2026-08-04 · PWF3 문서함 보완 원칙
단건 응답은 화면이 목록 전체를 다시 받지 않아도 검토·반려를 수행할 수 있도록 다음 값을 함께 반환합니다.
version: 수정 충돌을 막는expectedVersion의 기준값서로 다른 상태를 하나의
status에 섞지 않습니다.StoredFile.scanStatusWorkerDocument— enum·DB 제약 변경은 #60 소유GET /tasks/{taskId}/document-readiness가 계산HWP/HWPX 허용 시 확장자만 믿지 않고 MIME·크기·파일 시그니처 정책과 다운로드 권한을 함께 검증합니다.