feat: PDF·HWP 문서 미리보기 API 구현

[hywznn]

왜 필요한가요?

Refs #186

데모 합성 문서의 품질을 HR 화면에서 빠르게 확인하려면 원본을 매번 내려받지 않고 브라우저에서 미리볼 수 있어야 합니다. 기존 /content API는 모든 파일을 첨부 다운로드로 반환하고, 브라우저가 직접 열 수 없는 HWP·HWPX의 변환 경로도 없었습니다.

무엇이 바뀌나요?

• GET /api/v1/files/{fileId}/preview를 추가했습니다.
• PDF·JPG·PNG·WEBP는 원본을 Content-Disposition: inline으로 반환합니다.
• HWP·HWPX는 Server가 권한을 확인한 뒤 AI의 POST /api/v1/documents/convert를 호출하여 PDF로 반환합니다.
• 변환 기능은 File 모듈의 Port와 AI Integration Adapter로 분리했습니다.
• AI 비활성·장애는 503, 손상된 문서는 422, 미지원 형식은 415로 구분합니다.
• 다른 사업장 파일은 기존과 동일하게 404로 숨깁니다.
• 원본 다운로드 API는 변경하지 않았고, 미리보기 결과를 DB나 파일 저장소에 남기지 않습니다.
• 별도 Flyway Migration은 없습니다.

설정·문서

• AI_DOCUMENT_CONVERSION_ENDPOINT
• AI_DOCUMENT_CONVERSION_TIMEOUT (기본 60초)
• docs/file-preview.md에 Swagger 확인 방법과 합성 문서 품질 체크리스트를 작성했습니다.
• HWP·HWPX 변환에는 AI Runtime의 문서 변환 기능과 LibreOffice 설정이 필요합니다.

검증

• PDF inline 응답과 보안 헤더
• HWP·HWPX multipart 변환 계약과 PDF signature 검증
• AI 비활성 시 503
• 손상 문서 422 및 미지원 형식 415
• 타 사업장 파일 404
• feat(demo-data): 합성 근로자 전체 문서 원본 적재 #183 병합 후 최신 main 반영
• ./gradlew clean test 성공 (585 tests)

#183 합성 문서 시각 검수

PDF·이미지 대표 문서와 장문 영문 이름을 실제 PNG로 렌더링해 글자 잘림·겹침·OCR 영역을 확인했습니다. 이 범위는 정상입니다.

다만 합성 HWP fixture를 AI와 동일한 LibreOffice 변환 경로로 확인하면 읽을 수 없는 60페이지 PDF가 생성됩니다. 따라서 Server 미리보기 계약과 회귀 테스트는 완료했지만, HWP 실제 변환 품질과 HWPX Runtime Smoke Test가 끝날 때까지 Draft를 유지합니다. 상세 체크리스트는 #186에서 관리합니다.

후속 범위

• HWP fixture 또는 AI 변환 경로 보완
• AI Runtime을 켠 HWPX 실제 변환 Smoke Test
• Server 계약 확정 후 Client 문서 상세의 미리보기 버튼 연결