북곽툴즈 개발기 ② 한컴오피스 COM으로 모든 문서 변환하기

북곽툴즈 개발기.

학교는 hwp 천지

가장 필요한 도구는 문서 변환이었다. 학교에서 오가는 파일은 대부분 hwp이고, 제출은 PDF나 docx로 해야 하는 경우가 많다. 한셀(xlsx류)과 한쇼(pptx류)도 마찬가지다.

문제는 한글 문서를 다른 도구로 변환하면 표나 글상자, 줄간격 같은 게 곧잘 깨진다는 것이다.

왜 한컴오피스인가

선택지를 두고 고민했다.

• LibreOffice 헤드리스 변환. 무료지만 한글 hwp 레이아웃 재현이 약하다.
• CloudConvert 같은 외부 변환 API. 품질은 괜찮아도 파일을 제3자 서버에 업로드해야 하고, 요청 수 제한과 비용이 붙는다.

둘 다 내가 세운 원칙(한글 레이아웃을 정확히, 파일을 외부로 보내지 않기)과 맞지 않았다. 결국 한글 문서를 가장 정확히 다루는 건 한컴오피스 자신이다. 그래서 한컴오피스가 설치된 윈도우에서 COM 자동화로 직접 변환하기로 했다. 한컴오피스는 한글·한셀·한쇼를 외부 프로그램이 제어할 수 있는 COM 인터페이스로 열어둔다.

세 개의 엔진

문서 종류마다 담당 프로그램이 다르다.

• 한글: HWPFrame.HwpObject — 문서류 (hwp, hwpx, doc, docx, rtf, odt, txt 등)
• 한셀: HCell.Application — 스프레드시트 (xls, xlsx, csv, ods 등), 엑셀과 호환되는 모델
• 한쇼: HShow.Application — 프레젠테이션 (ppt, pptx, odp), 파워포인트와 호환되는 모델

변환은 같은 종류군 안에서만 된다. hwp를 xlsx로 바꾸는 식의 변환은 의미가 없으니 처음부터 막았다.

변환 매트릭스

입력 확장자를 넣으면 가능한 출력 목록과 각 출력의 SaveAs 방식이 나오도록 매트릭스를 하나로 정리했다. UI는 파일을 올리면 입력 형식을 감지해 변환 가능한 출력만 드롭다운으로 보여준다.

const ENGINES = [
  {
    engine: "hwp",
    inputs: ["hwp", "hwpx", "hml", "doc", "docx", "rtf", "odt", "txt"],
    save: {
      pdf:  { method: "saveas", format: "PDF" },
      docx: { method: "saveas", format: "OOXML" },
      hwpx: { method: "saveas", format: "HWPX" },
      txt:  { method: "saveas", format: "UNICODE" },
      // ...
    },
  },
  // cell, show ...
];

한글은 SaveAs 포맷을 문자열("PDF", "OOXML", "HWPX" 등)로 받고, 한셀·한쇼는 숫자 enum으로 받는다(xlsx=51, pptx=24처럼). PDF만 해도 엔진마다 호출 방식이 달라서, 이런 차이를 매트릭스 한곳에 모아두니 나중에 훨씬 편했다.

변환 API

서버 API는 단순하다. 파일을 받아 입력·출력 조합을 매트릭스로 해석하고, 해당 엔진의 PowerShell 스크립트로 COM을 호출한 뒤 결과 파일을 돌려준다.

const conversion = resolveConversion(inputExt, to);   // 엔진 + SaveAs 방식
// ... 임시 폴더에 입력 저장
await convert(conversion.engine, conversion.save, inputPath, outputPath);
// ... 결과 파일 응답으로 반환

PowerShell에 경로를 직접 문자열로 끼워 넣으면 공백·한글 경로에서 escape 문제가 터지기 쉽다. 그래서 경로와 포맷은 전부 환경변수로 넘겼다. 그리고 입력·출력 파일을 담는 작업 폴더는 변환이 끝나면(성공이든 실패든) 바로 삭제한다. 서버에 파일을 남기지 않겠다는 약속을 코드로 지킨 셈이다.