Repository navigation
[Document][P0] 문서 상세 조회·상태 표현·HWP/HWPX 업로드 보완 #80
Description
배경
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·크기·파일 시그니처 정책과 다운로드 권한을 함께 검증합니다.
Activity
[-][Document] GET /documents API 개선 — version 누락, 단건조회 부재, HWP 업로드 지원[/-][+][Document] GET /documents API 개선 version 누락, 단건조회 부재, HWP 업로드 지원[/+]BcKmini commentedon Aug 4, 2026
#227/#228에서 서류 등록이랑 파일 연결은 이미 붙임
3번(HWP/HWPX)도 추가되면
FileUploadModal(#158, 지금 HWP 업로드가 데모로만 동작 중)을 실제 업로드로 연결 예정[-][Document] GET /documents API 개선 version 누락, 단건조회 부재, HWP 업로드 지원[/-][+][Document][P0] 문서 상세 조회·상태 표현·HWP/HWPX 업로드 보완[/+]hywznn commentedon Aug 6, 2026
OCR 연동 저장 구조 조율 요청
Server 기준 이슈: #95
@chaeliki 추천안을 구체적으로 정리했습니다.
채린님께 저장 구조를 새로 설계해 달라고 요청드리는 것이 아니라, 제가 OCR 연동을 구현하되 기존 Document·민감정보 작업과 충돌하지 않는지만 확인받고 싶습니다.
관련 AI 계약 변경: fowoco/ai#20
추천 구조
worker_document에는 OCR 개인정보 컬럼을 추가하지 않습니다.document_ocr_run에 분리합니다.worker_sensitive_data로 자동 복사하지 않고, 승인된 OCR 결과에서만 사용합니다. 실제 개인정보를 사용하는 Pilot 전 #48에서 저장 필요성을 다시 결정합니다.이렇게 분리하면 #80의 문서 조회·업로드 범위를 유지하면서 OCR 재실행 이력과 승인 전 후보값을 별도로 관리할 수 있습니다.
역할
제가 다음 범위를 맡겠습니다.
AiOcrClient와 HTTP Adapterdocument_ocr_run설계·Migration확인 부탁드리는 내용
workerDocumentId,fileId를 OCR 입력 기준으로 사용해도 되는지worker_document를 수정하지 않고 별도 OCR 실행 테이블로 분리해도 문서 도메인상 문제가 없는지#80 병합 전에는 Document 관련 파일과 Migration을 수정하지 않고, 병합 후 최신 main에서 Flyway 버전을 예약해 시작하겠습니다.
chaeliki commentedon Aug 6, 2026
workerDocumentId, fileId를 OCR 입력으로 쓰시는 것 문제없습니다.
GET /documents/{documentId} 응답(DocumentDetailResponse)에서
worker_document_id, file_id 그대로 가져다 쓰시면 됩니다
worker_document를 안 건드리고 document_ocr_run으로 분리하는 것 -> 매우좋아용
이름/책임 겹치는 부분 없어보여요!