[Document][P1] 합성 문서 품질 보완과 PDF·HWP 미리보기 지원

[hywznn]

한 줄 목표

PR #183이 적재한 합성 문서의 데이터·화면 품질을 후속 보완하고, HR이 PDF·이미지·HWP·HWPX를 다운로드하지 않고 문서 상세 화면에서 미리볼 수 있게 합니다.

왜 필요한가요?

현재 Client #333은 PNG·JPG만 화면에서 미리보고 PDF·HWP·HWPX는 다운로드만 합니다. Server의 GET /api/v1/files/{fileId}/content도 항상 attachment로 응답합니다.

PDF는 브라우저에서 바로 표시할 수 있지만 HWP·HWPX는 브라우저가 직접 렌더링하지 못하므로 PDF 변환 결과가 필요합니다. AI 저장소에는 /api/v1/documents/convert와 HWP/HWPX → PDF 변환 경로가 있으므로 Server가 권한 확인과 장애 처리를 담당합니다.

작업 범위

1. 합성 문서 품질 보완

• Worker DB의 이름·국적·날짜와 문서 본문·메타데이터 일치 검증
• 여권·외국인등록증·계약서·연장신청서의 글자 잘림, 빈 필드, 겹침 여부 점검
• 실제 기관 문양·실제 개인정보를 사용하지 않고 DEMO / NOT VALID 표식 유지
• OCR 대상 필드 위에 워터마크나 장식이 겹치지 않도록 검증
• HWP·HWPX·PDF가 실제 형식으로 열리고 핵심 입력값이 보이는지 확인
• 품질 부족 fixture를 문서 유형별 체크리스트로 기록하고 순차 보완

2. 미리보기 API

• GET /api/v1/files/{fileId}/preview
• PNG·JPG·WEBP·PDF는 기존 파일을 권한 확인 후 inline 응답
• HWP·HWPX는 AI 문서 변환 API를 통해 PDF로 변환해 응답
• 응답은 Content-Type: application/pdf 또는 원본 이미지 MIME, Content-Disposition: inline
• 기존 다운로드 API와 원본 파일은 변경하지 않음
• 변환 결과를 자동 승인·외부 발송하지 않음

3. 보안·장애 처리

• 기존 ActorContext와 company_id 검증을 재사용하고 타 사업장은 404
• storage key와 서버 절대경로를 노출하지 않음
• Cache-Control: no-store, X-Content-Type-Options: nosniff 유지
• 파일 크기·변환 응답 크기·timeout 제한
• 지원하지 않는 형식은 415 또는 422, 변환기 비활성·장애는 503으로 구분
• AI 변환 실패 시 원본 문서와 DB 상태를 변경하지 않음

구현 방향

Client 문서 상세
→ Server preview API
→ 회사·파일 권한 확인
→ PDF·이미지: 원본 inline 반환
→ HWP·HWPX: AI /api/v1/documents/convert 호출
→ 변환된 PDF를 inline 반환

MVP에서는 변환 파일을 DB에 영구 저장하지 않고 요청 시 생성합니다. 반복 변환 캐시와 별도 preview_file_id는 성능 문제가 확인될 때 후속 작업으로 분리합니다. 따라서 이번 이슈는 Flyway 변경 없이 진행합니다.

2026-08-16 실제 품질 확인

• PDF·PNG·JPG: 대표 여권, ARC, 고용허가서, 계약서, 체류지 증명 및 장문 영문 이름까지 렌더링 확인 완료
• PDF 계약서: 2페이지 구성, 글자 잘림·겹침 없음
• OCR 영역: DEMO 표시가 핵심 필드를 가리지 않음
• HWP: AI와 동일한 LibreOffice 경로에서 PDF 136,363 bytes가 생성됐지만 깨진 문자 60페이지로 사용 불가
• HWPX 3종: 최신 AI main의 실제 HwpxToPdfConverter에서 모두 source file could not be loaded로 실패
• Server 전체 ./gradlew clean test: 성공
• 결론: Server의 권한·HTTP·오류 계약은 정상이나 AI 렌더링 경로 보완 전 HWP/HWPX 미리보기 활성화·병합은 보류

완료 조건

• feat(demo-data): 합성 근로자 전체 문서 원본 적재 #183 합성 fixture의 PDF·이미지 대표 문서 시각 검수
• PDF와 이미지 미리보기 200
• HWP fixture 변환 품질 보완
• HWPX 미리보기 실제 Runtime Smoke Test 통과
• 다른 사업장 파일 미리보기 404
• 변환 장애 시 503과 안전한 오류 코드 반환
• 원본 다운로드 API 회귀 없음
• OpenAPI 요청·응답·오류 계약 반영
• 단위·통합 테스트 및 최신 main 전체 테스트

연계

• PR feat(demo-data): 합성 근로자 전체 문서 원본 적재 #183 병합 완료
• 구현 PR feat: PDF·HWP 문서 미리보기 API 구현 #187
• 기존 Client #333은 이미지 미리보기와 원본 다운로드까지만 완료
• Server API가 준비된 뒤 Client 문서 상세 연결은 별도 Client 이슈로 요청
• AI 변환 기능 자체를 Server에 복제하지 않고 AI 변환 계약을 재사용

[hywznn]

미리보기 API 구현을 Draft PR #187로 올렸습니다.

• PDF·이미지: 브라우저 inline 응답
• HWP·HWPX: AI 문서 변환 API를 통해 PDF 미리보기
• 타 사업장 404, 손상 문서 422, AI 비활성·장애 503
• DB·Flyway 변경 없음
• 로컬 ./gradlew clean test 성공

합성 문서 원본의 값 정합성·글꼴·잘림 보완은 PR #183과 파일이 겹치므로, #183 병합 후 이 이슈의 품질 체크리스트로 이어서 진행합니다.