## 1. 기능 한계 원인 분석 및 최선 대응 방안

본 섹션은 클라이언트 사이드 HWP 미리보기가 원본 문서와 완전히 일치하지 못하는 **구조적·기술적 원인**을 분석하고, 각 한계에 대해 현실적으로 취할 수 있는 **최선의 대응 방안**을 정리합니다.

---

### 1.1 한계의 근본 원인: HWP 포맷의 비공개 독점 규격

HWP(한글과컴퓨터 워드프로세서) 파일 포맷은 **공개된 국제 표준(ISO/IEC)이 아닌 한컴의 독점 바이너리 규격**입니다.

* **공개 문서의 한계**: 한컴은 일부 규격 문서(`HWP 5.0 File Format Specification`)를 공개했으나, 이는 전체 규격의 약 60~70% 수준이며 도형(Shape) 세부 속성, 필드 코드, 고급 서식 등 대부분의 복잡한 요소는 문서화되지 않았습니다.
* **버전별 파편화**: HWP 파일은 버전(97/2002/2007/2010/2022 등)마다 내부 구조가 다르며, 버전 간 호환성 처리가 매우 복잡합니다.
* **오픈소스 파서의 한계**: 현재 사용 중인 `hwp.js`(버전 0.0.3)는 커뮤니티 기반의 역공학(Reverse Engineering) 결과물로, 기본적인 텍스트·표·이미지만 처리하며 고급 기능 구현이 부재합니다.

> **결론**: 브라우저 단에서 네이티브 한글 프로그램 수준의 완벽한 재현은 현재 기술로는 구조적으로 불가능합니다.

---

### 1.2 항목별 한계 원인 및 대응 방안

#### ① 도형(Shape) 위치 및 크기 오차

| 구분 | 내용 |
|---|---|
| **한계** | HWP 도형의 절대 좌표는 `vertRelTo`(세로 기준), `horzRelTo`(가로 기준) 등 복합적인 기준점 체계로 계산되며, 기준점이 문단·쪽·종이·단·표·셀 등 9가지 이상. 이 모든 경우를 역공학으로 완전 파악하기 불가능 |
| **현재 대응** | `vertRelTo` 0(종이), 1(쪽), 2(문단) 3가지 케이스만 구현. DOM 트리 상위 탐색으로 실제 페이지 요소 발굴 후 좌표 배치 |
| **최선 대응** | ① 현재 구현 유지(오차는 있으나 대략적 위치는 맞음) ② 도형이 매우 중요한 경우 **서버 사이드 변환(LibreOffice → PDF)** 방식으로 전환 |

#### ② 선(Line) 도형 방향 오차

| 구분 | 내용 |
|---|---|
| **한계** | HWP Line 도형은 bounding box 안에서의 정확한 시작점(x1,y1)·끝점(x2,y2) 좌표를 별도 payload에 저장하는데, `hwp.js` 파서는 이 payload를 파싱하지 않음 |
| **현재 대응** | bounding box의 가로/세로 비율(aspect ratio)로 방향을 **추론**: 비율 < 0.15 → 수평선, 비율 > 6.5 → 수직선, 그 외 → 대각선 |
| **최선 대응** | ① 현재 추론 방식 유지 (대부분의 실용적 케이스 커버) ② `hwp.js` 파서를 포크(fork)하여 `ShapeComponent` payload의 `startX/Y`, `endX/Y` 필드를 직접 파싱하는 고도화 개발 |

#### ③ 이미지(Picture) 렌더링 실패 시 텍스트 유실

| 구분 | 내용 |
|---|---|
| **한계** | HWP 문서에서 이미지와 텍스트가 같은 문단(Paragraph)에 혼재할 때, 이미지 파싱 실패 시 JavaScript `forEach` 루프가 중단되어 이후 텍스트가 통째로 누락 |
| **현재 대응** | `drawControl()` 호출을 `try-catch`로 감싸 오류를 무시하고 나머지 텍스트를 계속 처리하도록 방어 코드 추가 |
| **최선 대응** | ① 현재 방어 코드 유지 ② 이미지 로드 실패 시 `[그림 영역]` placeholder를 표시하여 레이아웃 유지 |

#### ④ WMF/EMF 벡터 이미지 렌더링 품질

| 구분 | 내용 |
|---|---|
| **한계** | WMF(Windows Metafile)는 브라우저 표준 이미지 포맷이 아닌 Windows 전용 벡터 포맷. `wmf.js`로 Canvas 변환하면 일부 GDI 명령어가 누락되거나 색상·선 굵기가 다르게 표현됨 |
| **현재 대응** | SheetJS의 `wmf.js`로 Canvas 렌더링 후 PNG DataURL로 변환하여 `backgroundImage`에 바인딩 |
| **최선 대응** | ① 현재 방식 유지 ② WMF가 매우 중요한 경우 서버에서 `LibreOffice` 또는 `ImageMagick`으로 SVG/PNG 변환 후 제공 |

#### ⑤ 복잡한 표(Table) 레이아웃 재현 한계

| 구분 | 내용 |
|---|---|
| **한계** | HWP 표의 셀 병합(merge), 대각선 테두리, 배경 그라데이션, 표 캡션, 표 안의 표(nested table) 등 고급 서식이 파서에서 누락됨 |
| **현재 대응** | 기본 셀 너비/높이/패딩/테두리/세로정렬을 파싱하여 `<table><tr><td>` 구조로 렌더링 |
| **최선 대응** | ① 현재 방식으로 대부분의 단순 표는 재현 가능 ② 복잡한 표 서식이 필수인 경우 서버 사이드 변환 방식 권고 |

#### ⑥ 폰트 장평(Font Metrics) 불일치로 인한 줄바꿈 차이

| 구분 | 내용 |
|---|---|
| **한계** | 한글 문서의 줄바꿈은 한컴 전용 폰트 렌더러의 글자 너비 계산값 기준. 웹 폰트(Noto KR 등)는 같은 포인트 크기라도 글자 너비가 미세하게 달라 줄바꿈 위치가 틀어짐 |
| **현재 대응** | `@font-face`로 한글 기본 폰트(바탕, 돋움 등)를 Noto KR 웹 폰트에 매핑하여 최대한 근접하게 표시 |
| **최선 대응** | ① 서버에 한컴 폰트(HCR 폰트 등)를 woff2로 변환하여 직접 서빙 ② 완벽한 재현이 필요하면 서버 사이드 PDF 변환 방식 필수 |

---

### 1.3 대응 방식 비교: 클라이언트 사이드 vs 서버 사이드

현재 구현은 **클라이언트 사이드** 방식입니다. 아래는 두 방식의 장단점 비교입니다.

| 항목 | 클라이언트 사이드 (현재) | 서버 사이드 (LibreOffice/PDF 변환) |
|---|---|---|
| **재현 정확도** | ★★☆☆☆ (기본 요소만 재현) | ★★★★☆ (원본에 매우 근접) |
| **서버 부하** | 없음 (브라우저가 처리) | 높음 (변환 프로세스 실행) |
| **응답 속도** | 빠름 (별도 변환 없음) | 느림 (변환 후 전달) |
| **오프라인 지원** | 가능 | 불가 |
| **유지보수 비용** | 높음 (파서 직접 관리) | 낮음 (LibreOffice가 처리) |
| **도형/수식/고급서식** | ❌ 미지원 | ✅ 대부분 지원 |
| **서버 요구사항** | 없음 | LibreOffice 설치 필요 |

---

### 1.4 최선 대응 전략 권고

현재 PM 시스템의 **HWP 미리보기 목적**(`첨부 파일의 대략적인 내용 확인`)을 고려한 권고안입니다.

#### 전략 A: 현재 방식 유지 + 점진적 개선 (권고)

```
현재 클라이언트 사이드 방식 유지
    ├─ 텍스트/표/이미지 기본 재현 가능
    ├─ 서버 부하 없음
    ├─ 복잡한 도형/수식 → "[그림 영역]" placeholder로 표시
    └─ 사용자에게 "정확한 확인은 원본 다운로드" 안내 제공
```

#### 전략 B: 하이브리드 방식 (장기 권고)

```
1차 시도: 클라이언트 사이드 hwp.js 렌더링 (빠름)
    ↓ 렌더링 오류 또는 복잡한 문서 감지 시
2차 폴백: "PDF로 보기" 버튼으로 서버 사이드 변환 안내
    ↓ 서버에서 LibreOffice를 통해 HWP → PDF 변환
PDF 뷰어로 고품질 렌더링 제공
```

> 현재 시스템에는 이미 **"PDF로 보기"** 폴백 버튼이 구현되어 있어 전략 B의 기반은 갖춰진 상태입니다.

#### 전략 C: 완전 서버 사이드 전환 (고정밀도 요구 시)

```
HWP 파일 업로드
    → 서버(LibreOffice headless)에서 HWP → PDF/SVG 변환
    → 변환된 PDF를 PDF.js로 고품질 렌더링
```

* **장점**: 원본 문서와 가장 높은 일치율 보장
* **단점**: 서버에 LibreOffice 설치 및 운영 필요, 변환 시간 소요(파일당 2~10초)

---

### 1.5 사용자 안내 메시지 권고

미리보기와 원본 문서 간 차이가 있을 수 있음을 사용자에게 명확히 안내하는 것이 중요합니다.

```
💡 한글 문서(.hwp) 미리보기는 브라우저에서 직접 렌더링하는 방식으로,
   복잡한 도형·수식·특수 서식은 원본과 다르게 표시될 수 있습니다.
   정확한 내용 확인이 필요한 경우 [파일 다운로드] 또는 [PDF로 보기]를 이용해 주세요.
```