PDF Helper (Rust + Tauri v2)

Office 파일을 PDF로 변환하고 병합하는 Windows 데스크톱 앱 + CLI — Rust 포팅 버전

기존 Python/PySide6 PDF Helper를 Rust + Tauri v2로 포팅한 프로젝트입니다.

주요 기능

• 파일 드래그 & 드롭: 탐색기에서 파일을 끌어다 놓으면 즉시 리스트에 추가
• 파일 선택 다이얼로그: 네이티브 파일 선택 (다중 선택, 형식별 필터)
• 파일 리스트 관리: 드래그로 순서 변경, 선택/전체 삭제, 우클릭 컨텍스트 메뉴
• 자동 엔진 감지: MS Office COM → LibreOffice CLI 순서로 자동 선택
• 개별 변환: MS Office COM 또는 LibreOffice CLI로 Office → PDF 변환 (a.xlsx → a_xlsx.pdf)
• 변환 후 병합: 비-PDF는 임시 디렉토리에서 변환, 기존 PDF와 함께 리스트 순서대로 병합 후 임시 파일 자동 삭제
• 실시간 진행률: 파일별/전체 진행률, ETA, 일시정지/취소
• CLI 지원: GUI 없이 커맨드라인에서 변환/병합 가능

지원 형식

형식	확장자	변환 엔진
Excel	.xlsx, .xls	MS Office COM / LibreOffice
PowerPoint	.pptx, .ppt	MS Office COM / LibreOffice
Word	.docx, .doc	MS Office COM / LibreOffice
OpenDocument	.odt, .ods, .odp	LibreOffice
PDF	.pdf	병합만 (변환 불필요)

포팅 이점

항목	Python (기존)	Rust + Tauri (현재)
배포 크기	~50MB+	~3MB
시작 시간	2~5초	<1초
메모리 사용	~200MB	~30MB
배포 방식	exe + 런타임	단일 exe / MSI
자동 업데이트	수동	Tauri 내장 updater

개발 환경 설정

필수 요구사항

• Rust (stable, 2021 edition)
• Node.js (v18+)
• Windows 10/11
• 변환 엔진 (하나 이상):
  • MS Office (Excel, Word, PowerPoint)
  • LibreOffice

GUI 앱 실행

# 의존성 설치
npm install

# 개발 모드 실행
npm run tauri dev

# 프로덕션 빌드
npm run tauri build

CLI 실행

# 엔진 감지
cargo run -p pdf-helper-cli -- engines

# 파일 변환
cargo run -p pdf-helper-cli -- convert file1.xlsx file2.pptx --output-dir ./output

# PDF 병합
cargo run -p pdf-helper-cli -- merge a.pdf b.pdf --output merged.pdf

# 변환 후 병합
cargo run -p pdf-helper-cli -- convert-merge file1.xlsx file2.pptx a.pdf --output result.pdf

# 도움말
cargo run -p pdf-helper-cli -- --help

릴리스 빌드:

cargo build -p pdf-helper-cli --release
# 실행 파일: target/release/pdf-helper.exe

테스트 / 린트

# 전체 workspace 테스트
cargo test --workspace

# 린트
cargo clippy --workspace

# 포맷 검사
cargo fmt --all --check

기술 스택

계층	기술	역할
프론트엔드	HTML/CSS/JS (Vanilla)	드래그앤드롭 UI, 파일 리스트, 진행률
코어 라이브러리	Rust (pdf-helper-core)	PDF 변환/병합 비즈니스 로직
GUI 프레임워크	Tauri v2	윈도우 관리, IPC, 시스템 API, 번들링
CLI	Rust (clap)	커맨드라인 인터페이스
COM 연동	windows-rs v0.58	MS Office COM 자동화 (IDispatch)
PDF 병합	lopdf v0.34	오브젝트 깊은 복사, 참조 재매핑, 메타데이터
LibreOffice	std::process::Command	soffice CLI 호출
에러 처리	thiserror	구조화된 에러 타입

프로젝트 구조

rust-pdf-helper/
├── Cargo.toml                     # Workspace 루트
├── crates/
│   └── pdf-helper-core/           # 코어 라이브러리 (순수 비즈니스 로직)
│       └── src/
│           ├── lib.rs
│           ├── error.rs            # thiserror 기반 에러 타입
│           ├── events.rs           # 이벤트 구조체 + ProgressHandler 트레이트
│           ├── engine/
│           │   ├── mod.rs          # 엔진 타입 정의
│           │   └── detector.rs     # 레지스트리/파일시스템 탐색
│           ├── converters/
│           │   ├── mod.rs          # Converter 트레이트, 배치 변환, 변환후병합
│           │   ├── office_com.rs   # MS Office COM (IDispatch)
│           │   └── libreoffice.rs  # LibreOffice CLI
│           ├── merger.rs           # PDF 병합 (lopdf)
│           └── file_mgmt.rs        # 파일 검증/메타데이터
├── src-tauri/                     # Tauri GUI 앱 (core에 의존)
│   └── src/
│       ├── main.rs                # 엔트리포인트
│       ├── lib.rs                 # Tauri 앱 빌더
│       └── commands/              # 얇은 IPC 래퍼
│           ├── convert.rs         # TauriProgressHandler + 변환
│           ├── engine.rs          # 엔진 감지
│           ├── file_mgmt.rs       # 파일 검증
│           └── merge.rs           # 병합/변환후병합
├── src-cli/                       # CLI 바이너리 (core에 의존)
│   └── src/
│       └── main.rs                # clap 서브커맨드 + CliProgressHandler
├── src/                           # 프론트엔드 (HTML/CSS/JS)
│   ├── index.html
│   ├── main.js
│   ├── styles.css
│   ├── components/
│   │   ├── file-list.js
│   │   └── progress.js
│   └── utils/
│       └── format.js
└── docs/                          # PDCA 문서

아키텍처

GUI와 CLI 모두 동일한 pdf-helper-core 라이브러리를 사용합니다. 진행률 보고는 ProgressHandler 트레이트로 추상화되어, Tauri는 이벤트 emit으로, CLI는 stdout 출력으로 각각 구현합니다.

IPC 커맨드 목록

커맨드	모듈	설명
validate_files	file_mgmt	파일 경로 검증 (존재/권한/형식)
get_file_info	file_mgmt	파일 메타데이터 조회
get_supported_extensions	file_mgmt	지원 확장자 목록
detect_engines	engine	모든 엔진 감지 (캐시)
get_engine_status	engine	선택된 엔진 상태
refresh_engines	engine	캐시 초기화 후 재감지
convert_files	convert	배치 PDF 변환 (비동기)
validate_pdfs	merge	PDF 유효성 검증
merge_pdfs	merge	PDF 병합
convert_and_merge	merge	변환 → 병합 (비동기)

CLI 서브커맨드

커맨드	설명	예시
engines	사용 가능한 변환 엔진 표시	pdf-helper engines
convert	Office 파일을 PDF로 변환	pdf-helper convert a.xlsx b.pptx -o ./out
merge	PDF 파일 병합	pdf-helper merge a.pdf b.pdf -o merged.pdf
convert-merge	변환 후 병합	pdf-helper convert-merge a.xlsx b.pdf -o result.pdf

개발 이력

PDCA (Plan-Design-Do-Check-Act) 방법론으로 개발되었습니다.

기능	Match Rate	성공 기준	코드
file-management	92.9%	8/8	+1,851줄
engine-detect	95.0%	7/7	+633줄
pdf-convert	91.7%	8/8	+938줄
pdf-merge	90.0%	6/6	+528줄
합계	92.4%	29/29	+3,950줄

Rust 단위 테스트: 34개 통과

라이선스

MIT