DOCS/journey/troubleshooting/251010_skill_rag_file_hwp_support.md

skill-rag-file HWP 지원 구현

작성일: 2025-10-10 작성자: Claude (로컬 개발자) 상태: 실행 예정

목표

skill-rag-file에 HWP 파일 처리 기능 추가 (LibreOffice CLI 방식)

현재 상태

미지원 확인

• config.py:33-36 - ALLOWED_EXTENSIONS에 .hwp 누락
• text_extractor.py:15-57 - extract()에 .hwp 처리 로직 없음
• Dockerfile:6-9 - LibreOffice 미설치

선택한 방식

LibreOffice CLI 래퍼 (무료, 크로스 플랫폼)

• HWP → PDF 변환 후 텍스트 추출
• 명령어: soffice --headless --convert-to pdf <hwp파일> --outdir <경로>
• 출처: /DOCS/ideas/250916_HWP-PDF_변환_전략_분석.md

구현 계획

1. Dockerfile 수정

• 위치: skill-rag-file/Dockerfile:6-9
• 추가: libreoffice --headless 설치

2. config.py 수정

• 위치: skill-rag-file/app/core/config.py:33-36
• 추가: ".hwp" to ALLOWED_EXTENSIONS

3. text_extractor.py 수정

• 위치: skill-rag-file/app/services/text_extractor.py
• extract() 메서드:15-57 - .hwp 분기 추가
• 신규 메서드 - _extract_hwp(file_path) 추가
  • subprocess로 soffice 호출
  • HWP → PDF 변환
  • PyPDF2로 텍스트 추출

4. 배포

• docker-compose down && up --build
• Gitea Actions 자동 배포

테스트 방법

로컬 테스트

# LibreOffice 설치 (Ubuntu)
apt-get install -y libreoffice --no-install-recommends

# 변환 테스트
soffice --headless --convert-to pdf test.hwp --outdir /tmp

API 테스트

# 파일 업로드
curl -X POST http://localhost:8508/api/v1/upload \
  -H "Authorization: Bearer {TOKEN}" \
  -F "file=@test.hwp" \
  -F "user_uuid={UUID}"

주의사항

1. 변환 품질: 리버스 엔지니어링 기반, 레이아웃 깨질 수 있음
2. 성능: soffice 프로세스 시작 오버헤드 있음
3. Dockerfile 크기: LibreOffice 추가 시 ~300MB 증가
4. 에러 처리: subprocess 실패 시 적절한 로그 필요

참고 문서

• /DOCS/ideas/250916_HWP-PDF_변환_전략_분석.md - 전략 분석
• /DOCS/300_architecture/311_FastAPI_구조_원칙.md - 계층 분리 원칙