# HWP/HWPX ↔ HTML/CSS 도메인 가이드

> **목적**: HWPX에서 문서 유형·스타일·템플릿을 추출하거나, HTML → HWPX → HWP 변환 시  
> 하드코딩 없이 이 가이드를 참조하여 정확한 매핑을 수행한다.  
> **출처**: 한글과컴퓨터 공식 "글 문서 파일 구조 5.0" (revision 1.3, 2018-11-08)  
> **범위**: HWP 5.0 바이너리 스펙의 개념 체계 + HWPX XML 태그 + HTML/CSS 매핑

---

## 0. 문서 형식 관계

```
HWP (바이너리)          HWPX (XML)              HTML/CSS
─────────────────   ─────────────────────   ─────────────────
Compound File       ZIP Archive             단일 HTML 파일
├─ FileHeader       ├─ META-INF/            ├─ <head>
├─ DocInfo          │   └─ manifest.xml     │   ├─ <meta>
│  (글꼴, 스타일,   ├─ Contents/            │   └─ <style>
│   테두리/배경,     │   ├─ header.xml       └─ <body>
│   글자모양 등)     │   │  (DocInfo 대응)       ├─ 헤더 영역
├─ BodyText/        │   ├─ section0.xml     │   ├─ 본문
│  └─ Section0      │   │  (본문 대응)       │   └─ 푸터 영역
├─ BinData/         │   └─ section1.xml     └─ @page CSS
│  └─ 이미지 등     ├─ BinData/
└─ PrvImage         │   └─ 이미지 파일
                    └─ version.xml
```

**핵심**: HWP 바이너리의 레코드 구조와 HWPX XML의 엘리먼트는 1:1 대응한다.  
이 가이드는 두 형식의 공통 개념 체계를 기준으로, CSS 변환까지 연결한다.

---

## 1. 단위 체계

### 1.1 HWPUNIT (글 내부 단위)

HWP는 1/7200 인치를 기본 단위로 사용한다.

| 변환 대상 | 공식 | 예시 |
|-----------|------|------|
| HWPUNIT → mm | `hwpunit / 7200 * 25.4` | 7200 → 25.4mm (= 1인치) |
| HWPUNIT → pt | `hwpunit / 7200 * 72` | 7200 → 72pt |
| HWPUNIT → px (96dpi) | `hwpunit / 7200 * 96` | 7200 → 96px |
| mm → HWPUNIT | `mm / 25.4 * 7200` | 25.4mm → 7200 |
| pt → HWPUNIT | `pt / 72 * 7200` | 10pt → 1000 |

```python
def hwpunit_to_mm(hwpunit):  return hwpunit / 7200 * 25.4
def hwpunit_to_pt(hwpunit):  return hwpunit / 7200 * 72
def hwpunit_to_px(hwpunit):  return hwpunit / 7200 * 96
def mm_to_hwpunit(mm):       return mm / 25.4 * 7200
```

### 1.2 글자 크기 (CharShape)

HWP의 글자 크기는 HWPUNIT 단위이지만 100배 스케일이 적용되어 있다.

| HWP 값 | 실제 크기 | CSS |
|--------|----------|-----|
| 1000 | 10pt | `font-size: 10pt` |
| 1200 | 12pt | `font-size: 12pt` |
| 2400 | 24pt | `font-size: 24pt` |

```python
def charsize_to_pt(hwp_size):  return hwp_size / 100  # 1000 → 10pt
```

### 1.3 COLORREF (색상)

HWP는 0x00BBGGRR 형식(리틀 엔디안 BGR). CSS는 #RRGGBB.

| HWP COLORREF | 분해 | CSS |
|-------------|------|-----|
| 0x00000000 | R=0, G=0, B=0 | `#000000` (검정) |
| 0x00FF0000 | R=0, G=0, B=255 | `#0000ff` (파랑) |
| 0x0000FF00 | R=0, G=255, B=0 | `#00ff00` (초록) |
| 0x000000FF | R=255, G=0, B=0 | `#ff0000` (빨강) |
| 0x00FFFFFF | R=255, G=255, B=255 | `#ffffff` (흰색) |

```python
def colorref_to_css(colorref):
    r = colorref & 0xFF
    g = (colorref >> 8) & 0xFF
    b = (colorref >> 16) & 0xFF
    return f'#{r:02x}{g:02x}{b:02x}'
```

**HWPX XML에서의 색상**: `#RRGGBB` 형식으로 직접 기록됨 (변환 불필요).

---

## 2. 테두리/배경 (BorderFill)

> HWP: `HWPTAG_BORDER_FILL` (DocInfo 레코드)  
> HWPX: `<hh:borderFill>` (header.xml 내)  
> 용도: 표 셀, 문단, 쪽 테두리/배경에 공통 적용

### 2.1 테두리선 종류

| HWP 값 | 이름 | HWPX type 속성 | CSS border-style |
|--------|------|---------------|-----------------|
| 0 | 실선 | `SOLID` | `solid` |
| 1 | 긴 점선 | `DASH` | `dashed` |
| 2 | 점선 | `DOT` | `dotted` |
| 3 | -.-.-. | `DASH_DOT` | `dashed` (근사) |
| 4 | -..-.. | `DASH_DOT_DOT` | `dashed` (근사) |
| 5 | 긴 Dash | `LONG_DASH` | `dashed` |
| 6 | 큰 동그라미 | `CIRCLE` | `dotted` (근사) |
| 7 | 2중선 | `DOUBLE` | `double` |
| 8 | 가는선+굵은선 | `THIN_THICK` | `double` (근사) |
| 9 | 굵은선+가는선 | `THICK_THIN` | `double` (근사) |
| 10 | 가는+굵은+가는 | `THIN_THICK_THIN` | `double` (근사) |
| 11 | 물결 | `WAVE` | `solid` (근사) |
| 12 | 물결 2중선 | `DOUBLE_WAVE` | `double` (근사) |
| 13 | 두꺼운 3D | `THICK_3D` | `ridge` |
| 14 | 두꺼운 3D(역) | `THICK_3D_REV` | `groove` |
| 15 | 3D 단선 | `3D` | `outset` |
| 16 | 3D 단선(역) | `3D_REV` | `inset` |
| — | 없음 | `NONE` | `none` |

### 2.2 테두리선 굵기

| HWP 값 | 실제 굵기 | HWPX width 속성 | CSS border-width |
|--------|----------|----------------|-----------------|
| 0 | 0.1 mm | `0.1mm` | `0.1mm` ≈ `0.4px` |
| 1 | 0.12 mm | `0.12mm` | `0.12mm` ≈ `0.5px` |
| 2 | 0.15 mm | `0.15mm` | `0.15mm` ≈ `0.6px` |
| 3 | 0.2 mm | `0.2mm` | `0.2mm` ≈ `0.8px` |
| 4 | 0.25 mm | `0.25mm` | `0.25mm` ≈ `1px` |
| 5 | 0.3 mm | `0.3mm` | `0.3mm` ≈ `1.1px` |
| 6 | 0.4 mm | `0.4mm` | `0.4mm` ≈ `1.5px` |
| 7 | 0.5 mm | `0.5mm` | `0.5mm` ≈ `1.9px` |
| 8 | 0.6 mm | `0.6mm` | `0.6mm` ≈ `2.3px` |
| 9 | 0.7 mm | `0.7mm` | `0.7mm` ≈ `2.6px` |
| 10 | 1.0 mm | `1.0mm` | `1mm` ≈ `3.8px` |
| 11 | 1.5 mm | `1.5mm` | `1.5mm` ≈ `5.7px` |
| 12 | 2.0 mm | `2.0mm` | `2mm` ≈ `7.6px` |
| 13 | 3.0 mm | `3.0mm` | `3mm` ≈ `11.3px` |
| 14 | 4.0 mm | `4.0mm` | `4mm` ≈ `15.1px` |
| 15 | 5.0 mm | `5.0mm` | `5mm` ≈ `18.9px` |

```python
BORDER_WIDTH_MAP = {
    0: 0.1, 1: 0.12, 2: 0.15, 3: 0.2, 4: 0.25, 5: 0.3,
    6: 0.4, 7: 0.5,  8: 0.6,  9: 0.7, 10: 1.0, 11: 1.5,
    12: 2.0, 13: 3.0, 14: 4.0, 15: 5.0
}
def border_width_to_css(hwp_val):
    mm = BORDER_WIDTH_MAP.get(hwp_val, 0.12)
    return f'{mm}mm'  # 또는 mm * 3.7795px
```

### 2.3 테두리 4방향 순서

| HWP 배열 인덱스 | HWPX 속성 | CSS 대응 |
|:---:|:---:|:---:|
| [0] | `<left>` / `<hh:left>` | `border-left` |
| [1] | `<right>` / `<hh:right>` | `border-right` |
| [2] | `<top>` / `<hh:top>` | `border-top` |
| [3] | `<bottom>` / `<hh:bottom>` | `border-bottom` |

### 2.4 채우기 (Fill) 정보

| 채우기 종류 (type 비트) | HWPX 엘리먼트 | CSS 대응 |
|:---:|:---:|:---:|
| 0x00 — 없음 | (없음) | `background: none` |
| 0x01 — 단색 | `<hh:windowBrush>` 또는 `<hh:colorFill>` | `background-color: #...` |
| 0x02 — 이미지 | `<hh:imgBrush>` | `background-image: url(...)` |
| 0x04 — 그러데이션 | `<hh:gradation>` | `background: linear-gradient(...)` |

**단색 채우기 구조** (가장 빈번):
```xml
<!-- HWPX header.xml -->
<hh:borderFill id="4">
  <hh:slash .../>
  <hh:backSlash .../>
  <hh:left type="SOLID" width="0.12mm" color="#000000"/>
  <hh:right type="SOLID" width="0.12mm" color="#000000"/>
  <hh:top type="SOLID" width="0.12mm" color="#000000"/>
  <hh:bottom type="SOLID" width="0.12mm" color="#000000"/>
  <hh:diagonal .../>
  <hh:fillBrush>
    <hh:windowBrush faceColor="#E8F5E9" hatchColor="none" .../>
  </hh:fillBrush>
</hh:borderFill>
```

```css
/* CSS 대응 */
.cell-bf4 {
  border-left: 0.12mm solid #000000;
  border-right: 0.12mm solid #000000;
  border-top: 0.12mm solid #000000;
  border-bottom: 0.12mm solid #000000;
  background-color: #E8F5E9;
}
```

### 2.5 HWPX borderFill → CSS 변환 함수 (의사 코드)

```python
def borderfill_to_css(bf_element):
    """HWPX <hh:borderFill> 엘리먼트 → CSS 딕셔너리"""
    css = {}
    
    for side in ['left', 'right', 'top', 'bottom']:
        el = bf_element.find(f'hh:{side}')
        if el is None:
            css[f'border-{side}'] = 'none'
            continue
        
        btype = el.get('type', 'NONE')
        width = el.get('width', '0.12mm')
        color = el.get('color', '#000000')
        
        if btype == 'NONE':
            css[f'border-{side}'] = 'none'
        else:
            css_style = BORDER_TYPE_MAP.get(btype, 'solid')
            css[f'border-{side}'] = f'{width} {css_style} {color}'
    
    # 배경
    fill = bf_element.find('.//hh:windowBrush')
    if fill is not None:
        face = fill.get('faceColor', 'none')
        if face and face != 'none':
            css['background-color'] = face
    
    return css
```

---

## 3. 글꼴 (FaceName)

> HWP: `HWPTAG_FACE_NAME` (DocInfo)  
> HWPX: `<hh:fontface>` → `<hh:font>` (header.xml)  
> CSS: `font-family`

### 3.1 언어별 글꼴 시스템

HWP는 한글·영문·한자·일어·기타·기호·사용자 총 7개 언어 슬롯에 각각 다른 글꼴을 지정한다.

| 언어 인덱스 | HWPX lang 속성 | 주요 글꼴 예시 |
|:---:|:---:|:---:|
| 0 | `HANGUL` | 맑은 고딕, 나눔고딕 |
| 1 | `LATIN` | Arial, Times New Roman |
| 2 | `HANJA` | (한글 글꼴 공유) |
| 3 | `JAPANESE` | MS Mincho |
| 4 | `OTHER` | — |
| 5 | `SYMBOL` | Symbol, Wingdings |
| 6 | `USER` | — |

**CSS 매핑**: 일반적으로 한글(0)과 영문(1) 글꼴을 `font-family` 스택으로 결합.

```css
/* HWPX: hangul="맑은 고딕" latin="Arial" */
font-family: "맑은 고딕", Arial, sans-serif;
```

### 3.2 글꼴 관련 HWPX 구조

```xml
<!-- header.xml -->
<hh:fontfaces>
  <hh:fontface lang="HANGUL">
    <hh:font face="맑은 고딕" type="TTF" id="0"/>
  </hh:fontface>
  <hh:fontface lang="LATIN">
    <hh:font face="Arial" type="TTF" id="0"/>
  </hh:fontface>
  ...
</hh:fontfaces>
```

---

## 4. 글자 모양 (CharShape)

> HWP: `HWPTAG_CHAR_SHAPE` (DocInfo, 72바이트)  
> HWPX: `<hh:charPr>` (header.xml charProperties 내)  
> CSS: font-*, color, text-decoration 등

### 4.1 주요 속성 매핑

| HWP 필드 | HWPX 속성 | CSS 속성 | 비고 |
|----------|----------|---------|------|
| 글꼴 ID [7] | `fontRef` | `font-family` | 언어별 참조 |
| 장평 [7] | `ratio` | `font-stretch` | 50%~200% |
| 자간 [7] | `spacing` | `letter-spacing` | -50%~50%, pt 변환 필요 |
| 기준 크기 | `height` | `font-size` | 값/100 = pt |
| 글자 색 | `color` 속성 | `color` | COLORREF → #RRGGBB |
| 밑줄 색 | `underline color` | `text-decoration-color` | |
| 진하게(bit 1) | `bold="true"` | `font-weight: bold` | |
| 기울임(bit 0) | `italic="true"` | `font-style: italic` | |
| 밑줄(bit 2-3) | `underline type` | `text-decoration: underline` | |
| 취소선(bit 18-20) | `strikeout type` | `text-decoration: line-through` | |
| 위첨자(bit 15) | `supscript` | `vertical-align: super; font-size: 70%` | |
| 아래첨자(bit 16) | `subscript` | `vertical-align: sub; font-size: 70%` | |

### 4.2 HWPX charPr 구조 예시

```xml
<hh:charPr id="1" height="1000" bold="false" italic="false"
           underline="NONE" strikeout="NONE" color="#000000">
  <hh:fontRef hangul="0" latin="0" hanja="0" japanese="0"
              other="0" symbol="0" user="0"/>
  <hh:ratio hangul="100" latin="100" .../>
  <hh:spacing hangul="0" latin="0" .../>
  <hh:relSz hangul="100" latin="100" .../>
  <hh:offset hangul="0" latin="0" .../>
</hh:charPr>
```

---

## 5. 문단 모양 (ParaShape)

> HWP: `HWPTAG_PARA_SHAPE` (DocInfo, 54바이트)  
> HWPX: `<hh:paraPr>` (header.xml paraProperties 내)  
> CSS: text-align, margin, line-height, text-indent 등

### 5.1 정렬 방식

| HWP 값 (bit 2-4) | HWPX 속성값 | CSS text-align |
|:---:|:---:|:---:|
| 0 | `JUSTIFY` | `justify` |
| 1 | `LEFT` | `left` |
| 2 | `RIGHT` | `right` |
| 3 | `CENTER` | `center` |
| 4 | `DISTRIBUTE` | `justify` (근사) |
| 5 | `DISTRIBUTE_SPACE` | `justify` (근사) |

### 5.2 줄 간격 종류

| HWP 값 | HWPX 속성값 | CSS line-height | 비고 |
|:---:|:---:|:---:|:---:|
| 0 | `PERCENT` | `160%` (예) | 글자 크기 기준 % |
| 1 | `FIXED` | `24pt` (예) | 고정 pt |
| 2 | `BETWEEN_LINES` | — | 여백만 지정 |
| 3 | `AT_LEAST` | — | 최소값 |

### 5.3 주요 속성 매핑

| HWP 필드 | HWPX 속성 | CSS 속성 | 단위 |
|----------|----------|---------|------|
| 왼쪽 여백 | `margin left` | `margin-left` / `padding-left` | HWPUNIT → mm |
| 오른쪽 여백 | `margin right` | `margin-right` / `padding-right` | HWPUNIT → mm |
| 들여쓰기 | `indent` | `text-indent` | HWPUNIT → mm |
| 문단 간격 위 | `spacing before` | `margin-top` | HWPUNIT → mm |
| 문단 간격 아래 | `spacing after` | `margin-bottom` | HWPUNIT → mm |
| 줄 간격 | `lineSpacing` | `line-height` | 종류에 따라 다름 |
| BorderFill ID | `borderFillIDRef` | border + background | ID로 참조 |

### 5.4 HWPX paraPr 구조 예시

```xml
<hh:paraPr id="0" align="JUSTIFY">
  <hh:margin left="0" right="0" indent="0"/>
  <hh:spacing before="0" after="0" 
              lineSpacingType="PERCENT" lineSpacing="160"/>
  <hh:border borderFillIDRef="1" 
             left="0" right="0" top="0" bottom="0"/>
  <hh:autoSpacing eAsianEng="false" eAsianNum="false"/>
</hh:paraPr>
```

---

## 6. 표 (Table) 구조

> HWP: `HWPTAG_TABLE` (본문 레코드)  
> HWPX: `<hp:tbl>` (section*.xml 내)  
> HTML: `<table>`, `<tr>`, `<td>`/`<th>`

### 6.1 표 속성 매핑

| HWP 필드 | HWPX 속성 | HTML/CSS 대응 | 비고 |
|----------|----------|-------------|------|
| RowCount | `rowCnt` | (행 수) | |
| nCols | `colCnt` | (열 수) | `<colgroup>` 참조 |
| CellSpacing | `cellSpacing` | `border-spacing` | HWPUNIT16 |
| 안쪽 여백 | `cellMargin` left/right/top/bottom | `padding` | |
| BorderFill ID | `borderFillIDRef` | 표 전체 테두리 | |
| 쪽나눔(bit 0-1) | `pageBreak` | `page-break-inside` | 0=avoid, 1=auto |
| 제목줄 반복(bit 2) | `repeatHeader` | `<thead>` 출력 | |

### 6.2 열 너비

```xml
<!-- HWPX -->
<hp:tbl colCnt="3" rowCnt="5" ...>
  <hp:colSz>
    <hp:widthList>8504 8504 8504</hp:widthList>  <!-- HWPUNIT -->
  </hp:colSz>
  ...
</hp:tbl>
```

```html
<!-- HTML 변환 -->
<colgroup>
  <col style="width: 33.33%">  <!-- 8504 / 총합 * 100 -->
  <col style="width: 33.33%">
  <col style="width: 33.33%">
</colgroup>
```

### 6.3 셀 (Cell) 속성

| HWP 필드 | HWPX 속성 | HTML 속성 | 비고 |
|----------|----------|----------|------|
| Column 주소 | `colAddr` | — | 0부터 시작 |
| Row 주소 | `rowAddr` | — | 0부터 시작 |
| 열 병합 개수 | `colSpan` | `colspan` | 1 = 병합 없음 |
| 행 병합 개수 | `rowSpan` | `rowspan` | 1 = 병합 없음 |
| 셀 폭 | `width` | `width` | HWPUNIT |
| 셀 높이 | `height` | `height` | HWPUNIT |
| 셀 여백 [4] | `cellMargin` | `padding` | HWPUNIT16 → mm |
| BorderFill ID | `borderFillIDRef` | `border` + `background` | 셀별 스타일 |

### 6.4 HWPX 셀 구조 예시

```xml
<hp:tc colAddr="0" rowAddr="0" colSpan="2" rowSpan="1"
       width="17008" height="2400" borderFillIDRef="4">
  <hp:cellMargin left="510" right="510" top="142" bottom="142"/>
  <hp:cellAddr colAddr="0" rowAddr="0"/>
  <hp:subList ...>
    <hp:p ...>
      <!-- 셀 내용 -->
    </hp:p>
  </hp:subList>
</hp:tc>
```

```html
<!-- HTML 변환 -->
<td colspan="2" style="
  width: 60mm;
  height: 8.5mm;
  padding: 0.5mm 1.8mm;
  border: 0.12mm solid #000;
  background-color: #E8F5E9;
">셀 내용</td>
```

### 6.5 병합 셀 처리 규칙

HWP/HWPX에서 병합된 셀은 **왼쪽 위 셀만 존재**하고, 병합에 포함된 다른 셀은 아예 없다.
HTML에서는 colspan/rowspan으로 표현하고, 병합된 위치의 `<td>`를 생략한다.

```
HWPX: colSpan="2", rowSpan="3" at (col=0, row=0)
 → 이 셀이 col 0~1, row 0~2를 차지
 → col=1/row=0, col=0/row=1, col=1/row=1, col=0/row=2, col=1/row=2 셀은 없음

HTML: <td colspan="2" rowspan="3">...</td>
 → 해당 행/열 위치에서 <td> 생략
```

---

## 7. 용지 설정 (PageDef / SecPr)

> HWP: `HWPTAG_PAGE_DEF` (구역 정의 하위)  
> HWPX: `<hp:secPr>` → `<hp:pageDef>` (section*.xml 내)  
> CSS: `@page`, `@media print`

### 7.1 용지 크기 사전 정의

| 용지 이름 | 가로 (mm) | 세로 (mm) | HWPUNIT (가로×세로) |
|----------|----------|----------|:---:|
| A4 | 210 | 297 | 59528 × 84188 |
| A3 | 297 | 420 | 84188 × 119055 |
| B5 | 176 | 250 | 49896 × 70866 |
| Letter | 215.9 | 279.4 | 61200 × 79200 |
| Legal | 215.9 | 355.6 | 61200 × 100800 |

### 7.2 여백 매핑

```xml
<!-- HWPX section0.xml -->
<hp:secPr>
  <hp:pageDef width="59528" height="84188"
              landscape="NARROWLY">  <!-- 좁게 = 세로 -->
    <hp:margin left="8504" right="8504"
               top="5668" bottom="4252"
               header="4252" footer="4252"
               gutter="0"/>
  </hp:pageDef>
</hp:secPr>
```

```css
/* CSS 변환 */
@page {
  size: A4 portrait;                    /* 210mm × 297mm */
  margin-top: 20mm;                     /* 5668 / 7200 * 25.4 ≈ 20mm */
  margin-bottom: 15mm;                  /* 4252 → 15mm */
  margin-left: 30mm;                    /* 8504 → 30mm */
  margin-right: 30mm;                   /* 8504 → 30mm */
}
/* 머리말/꼬리말 여백은 CSS에서 body padding으로 근사 */
```

### 7.3 용지 방향

| HWP 값 (bit 0) | HWPX 속성값 | CSS |
|:---:|:---:|:---:|
| 0 | `NARROWLY` (좁게) | `portrait` |
| 1 | `WIDELY` (넓게) | `landscape` |

---

## 8. 머리말/꼬리말 (Header/Footer)

> HWP: `HWPTAG_CTRL_HEADER` → 컨트롤 ID `head` / `foot`  
> HWPX: `<hp:headerFooter>` (section*.xml 내, 또는 별도 header/footer 영역)  
> HTML: 페이지 상단/하단 고정 영역

### 8.1 머리말/꼬리말 적용 범위

| HWP/HWPX 설정 | 의미 |
|:---:|:---:|
| 양쪽 | 모든 쪽에 동일 |
| 짝수쪽만 | 짝수 페이지 |
| 홀수쪽만 | 홀수 페이지 |

### 8.2 HTML 근사 표현

```html
<!-- 머리말 -->
<div class="page-header" style="
  position: absolute; top: 0; left: 0; right: 0;
  height: 15mm;    /* header margin 값 */
  padding: 0 30mm; /* 좌우 본문 여백 */
">
  <table class="header-table">...</table>
</div>

<!-- 꼬리말 -->
<div class="page-footer" style="
  position: absolute; bottom: 0; left: 0; right: 0;
  height: 15mm;    /* footer margin 값 */
  padding: 0 30mm;
">
  <span class="footer-text">페이지 번호</span>
</div>
```

---

## 9. 구역 정의 (Section)

> HWP: 구역 정의 컨트롤 (`secd`)  
> HWPX: `<hp:secPr>` (section*.xml 최상위)

### 9.1 구역 속성

| 속성 | HWPX | CSS/HTML 대응 | 비고 |
|------|------|-------------|------|
| 머리말 감춤 | `hideHeader` | header 영역 display:none | |
| 꼬리말 감춤 | `hideFooter` | footer 영역 display:none | |
| 텍스트 방향 | `textDirection` | `writing-mode` | 0=가로, 1=세로 |
| 단 정의 | `<hp:colDef>` | CSS `columns` / `column-count` | |
| 쪽 번호 | `pageStartNo` | 쪽 번호 출력 값 | 0=이어서 |

---

## 10. HTML → HWPX → HWP 변환 파이프라인

### 10.1 전체 흐름

```
[HTML (우리 출력)]
    ↓ (1) HTML 파싱 → CSS 속성 추출
[중간 표현 (JSON)]
    ↓ (2) 이 가이드의 역방향 매핑
[HWPX (XML ZIP)]
    ↓ (3) 한컴오피스 변환 도구
[HWP (바이너리)]
```

### 10.2 단계별 매핑 방향

| 단계 | 입력 | 출력 | 참조할 가이드 섹션 |
|:---:|:---:|:---:|:---:|
| HTML → HWPX | CSS border | `<hh:borderFill>` 생성 | §2 역방향 |
| HTML → HWPX | CSS font | `<hh:charPr>` + `<hh:fontface>` | §3, §4 역방향 |
| HTML → HWPX | CSS text-align 등 | `<hh:paraPr>` | §5 역방향 |
| HTML → HWPX | `<table>` | `<hp:tbl>` + `<hp:tc>` | §6 역방향 |
| HTML → HWPX | @page CSS | `<hp:pageDef>` | §7 역방향 |
| HTML → HWPX | header/footer div | `<hp:headerFooter>` | §8 역방향 |

### 10.3 CSS → HWPX 역변환 예시

```python
def css_border_to_hwpx(css_border):
    """'0.12mm solid #000000' → HWPX 속성"""
    parts = css_border.split()
    width = parts[0]  # '0.12mm'
    style = parts[1]  # 'solid'
    color = parts[2]  # '#000000'
    
    hwpx_type = CSS_TO_BORDER_TYPE.get(style, 'SOLID')
    return {
        'type': hwpx_type,
        'width': width,
        'color': color
    }

CSS_TO_BORDER_TYPE = {
    'solid': 'SOLID', 'dashed': 'DASH', 'dotted': 'DOT',
    'double': 'DOUBLE', 'ridge': 'THICK_3D', 'groove': 'THICK_3D_REV',
    'outset': '3D', 'inset': '3D_REV', 'none': 'NONE'
}
```

### 10.4 HWPX ZIP 구조 생성

```
output.hwpx (ZIP)
├── META-INF/
│   └── manifest.xml          ← 파일 목록
├── Contents/
│   ├── header.xml            ← DocInfo (글꼴, 스타일, borderFill)
│   ├── section0.xml          ← 본문 (문단, 표, 머리말/꼬리말)
│   └── content.hpf           ← 콘텐츠 메타
├── BinData/                  ← 이미지 등
├── Preview/
│   └── PrvImage.png          ← 미리보기
└── version.xml               ← 버전 정보
```

**header.xml 필수 구조**:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<hh:head xmlns:hh="...">
  <hh:beginNum .../>
  <hh:refList>
    <hh:fontfaces>...</hh:fontfaces>       <!-- §3 -->
    <hh:borderFills>...</hh:borderFills>   <!-- §2 -->
    <hh:charProperties>...</hh:charProperties>  <!-- §4 -->
    <hh:tabProperties>...</hh:tabProperties>
    <hh:numberingProperties>...</hh:numberingProperties>
    <hh:bulletProperties>...</hh:bulletProperties>
    <hh:paraProperties>...</hh:paraProperties>  <!-- §5 -->
    <hh:styles>...</hh:styles>
  </hh:refList>
</hh:head>
```

**section0.xml 필수 구조**:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<hp:sec xmlns:hp="...">
  <hp:secPr>
    <hp:pageDef .../>          <!-- §7 -->
    <hp:headerFooter .../>     <!-- §8 -->
  </hp:secPr>
  <hp:p paraPrIDRef="0" styleIDRef="0">   <!-- 문단 -->
    <hp:run charPrIDRef="0">
      <hp:t>텍스트</hp:t>
    </hp:run>
  </hp:p>
  <hp:p ...>
    <hp:ctrl>
      <hp:tbl ...>...</hp:tbl>  <!-- §6 -->
    </hp:ctrl>
  </hp:p>
</hp:sec>
```

---

## 11. 시스템 적용 가이드

### 11.1 적용 대상 모듈

| 모듈 | 파일 | 이 가이드 활용 방식 |
|------|------|:---:|
| **doc_template_analyzer.py** | HWPX → HTML 템플릿 추출 | §2,6,7,8 정방향 (HWPX→CSS) |
| **template_manager.py** | 추출된 스타일 저장/로드 | §2 borderFill ID 매핑 |
| **custom_doc_type.py** | HTML 문서 생성 | §2,4,5 CSS 값 참조 |
| **hwpx_converter.py** (예정) | HTML → HWPX 변환 | §2~8 역방향 (CSS→HWPX) |
| **hwp_converter.py** (예정) | HWPX → HWP 변환 | §1 단위 변환 |

### 11.2 하드코딩 제거 전략

**현재 문제 (AS-IS)**:
```python
# doc_template_analyzer.py에 하드코딩됨
border_css = "2px solid var(--primary)"
header_bg = "#E8F5E9"
```

**해결 방향 (TO-BE)**:
```python
# style.json에서 추출된 borderFill 참조
bf = style['border_fills']['3']  # id=3
border_css = f"{bf['top']['width']} {bf['top']['css_style']} {bf['top']['color']}"
# → "0.12mm solid #000000"

header_bf = style['border_fills']['4']  # id=4 (헤더 배경 포함)
header_bg = header_bf.get('background', 'none')
# → "#E8F5E9"
```

### 11.3 이 가이드를 코드에서 참조하는 방식

이 문서(`hwpx_domain_guide.md`)는 다음과 같이 활용한다:

1. **변환 테이블을 JSON으로 추출** → `hwpx_mappings.json`
   - 테두리선 종류, 굵기, 색상 변환 등의 룩업 테이블
   
2. **변환 함수 라이브러리** → `hwpx_utils.py`
   - `hwpunit_to_mm()`, `borderfill_to_css()`, `css_border_to_hwpx()` 등
   
3. **AI 프롬프트 컨텍스트** → 문서 유형/구조 분석 시 참조
   - "이 HWPX의 borderFill id=3은 실선 0.12mm 검정이므로 표 일반 셀에 해당"
   
4. **검증 기준** → 변환 결과물 검증 시 정확성 확인
   - 추출된 CSS가 원본 HWPX의 스펙과 일치하는지

---

## 부록 A. 빠른 참조 — HWPX XML 태그 ↔ HWP 레코드 대응

| HWP 레코드 (Tag ID) | HWPX XML 엘리먼트 | 위치 |
|---------------------|------------------|------|
| HWPTAG_DOCUMENT_PROPERTIES | `<hh:beginNum>` 등 | header.xml |
| HWPTAG_ID_MAPPINGS | (암묵적) | header.xml |
| HWPTAG_FACE_NAME | `<hh:font>` | header.xml > fontfaces |
| HWPTAG_BORDER_FILL | `<hh:borderFill>` | header.xml > borderFills |
| HWPTAG_CHAR_SHAPE | `<hh:charPr>` | header.xml > charProperties |
| HWPTAG_TAB_DEF | `<hh:tabPr>` | header.xml > tabProperties |
| HWPTAG_NUMBERING | `<hh:numbering>` | header.xml > numberingProperties |
| HWPTAG_BULLET | `<hh:bullet>` | header.xml > bulletProperties |
| HWPTAG_PARA_SHAPE | `<hh:paraPr>` | header.xml > paraProperties |
| HWPTAG_STYLE | `<hh:style>` | header.xml > styles |
| HWPTAG_PARA_HEADER | `<hp:p>` | section*.xml |
| HWPTAG_TABLE | `<hp:tbl>` | section*.xml > p > ctrl |
| (셀 속성) | `<hp:tc>` | section*.xml > tbl > tr > tc |
| HWPTAG_PAGE_DEF | `<hp:pageDef>` | section*.xml > secPr |
| (머리말/꼬리말) | `<hp:headerFooter>` | section*.xml > secPr |

## 부록 B. 빠른 참조 — CSS → HWPX 역변환

| CSS 속성 | HWPX 대응 | 변환 공식 |
|----------|----------|----------|
| `font-family` | `<hh:font face="...">` | 첫 번째 값 → hangul, 두 번째 → latin |
| `font-size: 10pt` | `<hh:charPr height="1000">` | pt × 100 |
| `font-weight: bold` | `bold="true"` | |
| `font-style: italic` | `italic="true"` | |
| `color: #1a365d` | `color="#1a365d"` | 동일 |
| `text-align: center` | `align="CENTER"` | 대문자 |
| `margin-left: 30mm` | `left="8504"` | mm → HWPUNIT |
| `line-height: 160%` | `lineSpacing="160"` + `type="PERCENT"` | |
| `border: 1px solid #000` | `<hh:borderFill>` 내 각 방향 | §2 참조 |
| `background-color: #E8F5E9` | `<hh:windowBrush faceColor="...">` | |
| `padding: 2mm 5mm` | `<hp:cellMargin top="567" left="1417">` | mm → HWPUNIT |
| `width: 210mm` | `width="59528"` | mm → HWPUNIT |
| `@page { size: A4 }` | `<hp:pageDef width="59528" height="84188">` | |

---

*이 가이드는 한글과컴퓨터의 "글 문서 파일 구조 5.0 (revision 1.3)"을 참고하여 작성되었습니다.*