# HWPX 문서 자동화 (Korean Word Document Automation)

한글 문서(HWP/HWPX)를 **프로그래밍으로 자동 생성 및 편집**하는 스킬입니다.
OWPML(Open Word Processing Markup Language) 기반 파싱/생성을 지원합니다.

## Overview

**한글 전용** 한국 기업/기관에서 필수적인 문서:
- 계약서, 제안서, 보고서
- 공문, 공고, 공시
- 양식, 신청서, 신청 문서

을 **엑셀 데이터, 템플릿을 기반으로 자동 생성**합니다.

> **핵심**: 사용자가 "100개 계약서 템플릿에서 고객 데이터로 한글 계약서 100개 생성해줘"라고 말하면,
> 3초 안에 100개의 HWPX 파일을 받을 수 있어야 합니다.

---

## HWPX 포맷 개요

### HWP vs HWPX
```
HWP (한글 2014 이전)
- 바이너리 포맷 (.hwp)
- 한글 자체 포맷
- 역호환성 우수

HWPX (한글 2014 이후) ← 권장
- XML 기반 포맷 (.hwpx)
- Open Document Format 유사 구조
- 프로그래밍 처리 용이
- 한글 최신 버전 필수
```

### HWPX 구조
```
document.hwpx
└─ [ZIP 아카이브]
   ├─ [Content_Types].xml      ← 파일 타입 정의
   ├─ _rels/
   │  └─ .rels                 ← 관계 정의
   ├─ word/
   │  ├─ document.xml          ← 본문 내용
   │  ├─ header1.xml           ← 머리글
   │  ├─ footer1.xml           ← 바닥글
   │  ├─ fontTable.xml         ← 폰트
   │  ├─ styles.xml            ← 스타일
   │  ├─ numbering.xml         ← 번호 매김
   │  └─ media/                ← 이미지
   │     ├─ image1.jpg
   │     └─ image2.png
   └─ customXml/               ← 메타데이터
      └─ properties.xml
```

---

## 주요 기능

### 1. 템플릿 기반 문서 생성 (Mail Merge)

**프로세스:**
```
템플릿.hwpx (플레이스홀더 포함)
+ 데이터.xlsx (고객 정보, 계약 조건 등)
↓
자동 생성 (병합)
↓
100개_계약서.zip (각각 계약서_001.hwpx, 계약서_002.hwpx, ...)
```

**예시:**
```
템플릿 내 플레이스홀더:
{{고객명}} / {{계약금액}} / {{계약기간}}

데이터:
| 고객명 | 계약금액 | 계약기간 |
| 김씨 | 500만원 | 2024.04~06 |
| 이씨 | 1000만원 | 2024.05~12 |

결과:
[계약서_001.hwpx] → 김씨, 500만원, 2024.04~06
[계약서_002.hwpx] → 이씨, 1000만원, 2024.05~12
```

### 2. 문서 내용 추출

**HWPX → 텍스트/데이터 변환**
```
input: 계약서.hwpx
↓
추출: 텍스트, 표 데이터, 이미지 메타데이터
↓
output: 텍스트 파일, CSV, JSON
```

### 3. 스타일 및 서식 유지

**자동 생성 후에도:**
- 글꼴 (서울남산체, 맑은고딕 등)
- 크기 및 색상
- 정렬 (좌측, 중앙, 우측)
- 들여쓰기, 줄 간격
- 표, 글머리, 번호 매김

모두 **원본 템플릿 그대로** 유지됩니다.

### 4. 조건부 콘텐츠 (Optional Blocks)

**예시:**
```
if (계약유형 == "용역비"){
  → "용역비 청구서" 섹션 포함
} else if (계약유형 == "정기보수"){
  → "정기보수 계약 조건" 섹션 포함
}
```

---

## 사용 사례

### 1. 계약서 자동 생성 (법무/계약 부서)
```
입력:
- 계약서 템플릿 (템플릿.hwpx)
- 고객 데이터 (고객_100명.xlsx)

처리:
- {{고객명}}, {{계약금액}}, {{기간}} 자동 치환
- 금액: 숫자→한글 변환 (예: 500만원 → "오백만원")

출력:
- 계약서_001.hwpx ~ 계약서_100.hwpx (100개 파일)
```

### 2. 공시/공문 일괄 발송 (공공기관)
```
입력:
- 공시문 템플릿
- 공시 대상 목록 (100개 기관)

처리:
- 각 기관명, 주소, 담당자 자동 입력
- 발송 번호, 날짜 자동 생성

출력:
- 100개의 개별 공문 HWPX
```

### 3. 신청서 대량 작성 (HR/교무)
```
입력:
- 입사지원서 또는 수강신청서 템플릿
- 지원자 정보 (CSV)

처리:
- 이름, 나이, 경력, 희망부서 자동 입력

출력:
- 각 지원자별 신청서 (완성)
```

---

## OWPML 기본 구조

### Document 기본 형태
```xml
<?xml version="1.0" encoding="UTF-8"?>
<w:document xmlns:w="...">
  <w:body>
    <!-- 문단 -->
    <w:p>
      <w:pPr>
        <!-- 문단 속성 (정렬, 들여쓰기 등) -->
      </w:pPr>
      <w:r>
        <!-- 글자 (run) -->
        <w:rPr>
          <!-- 글자 속성 (글꼴, 크기, 색상) -->
        </w:rPr>
        <w:t>텍스트 내용</w:t>
      </w:r>
    </w:p>

    <!-- 표 -->
    <w:tbl>
      <w:tblPr>
        <!-- 표 속성 -->
      </w:tblPr>
      <w:tr>
        <!-- 행 -->
        <w:tc>
          <!-- 셀 -->
          <w:p><w:r><w:t>내용</w:t></w:r></w:p>
        </w:tc>
      </w:tr>
    </w:tbl>
  </w:body>
</w:document>
```

---

## 절대 규칙 (Hard Rules)

### 1. 플레이스홀더 포맷
```
권장 형식:
{{필드명}} (쌍중괄호)
또는
${필드명} (달러 표기)

예:
계약 당사자: {{계약업체명}}
계약 금액: {{계약금액}}

주의: 한글 필드명 사용 가능 but 영문 권장 (호환성)
```

### 2. 데이터 타입별 처리
```
텍스트: 그대로 삽입
숫자: 콤마 포맷 (예: 1000000 → 1,000,000)
금액: 한글 변환 옵션 (예: 500만원)
날짜: 포맷 지정 (예: 2024.04.01)
이미지: URL 또는 경로 지정
```

### 3. 한글 특수 처리
```
- 글꼴: 한글 문서는 반드시 한글 지원 글꼴 사용
  (서울남산체, 맑은고딕, NotoSansKR 등)
- 문자 집합: UTF-8 (표준)
- 자모 분리 방지: 조합형이 아닌 완성형 사용
- 세로쓰기: 지원하지만 호환성 낮음 (권장하지 않음)
```

### 4. 성능
```
- 단일 문서: 수 ms (빠름)
- 100개 문서: 1~3초
- 1000개 문서: 10~30초

대량 생성 시 배치 처리 권장
```

### 5. 보안
```
- 비밀번호 보호: HWPX는 기본 암호화 미지원
  → 따로 암호화 필요 (또는 읽기 전용)
- 민감 정보: 생성 후 파일 접근 제어 필수
- 감사 로그: 생성 기록 보관 권장
```

---

## 출력 형식

### HWPX 파일
```
document.hwpx (표준 형식)
또는
document.hwp (한글 2014 이하 호환성)
```

### 배치 생성 결과
```
generated_documents/
├─ contract_001.hwpx
├─ contract_002.hwpx
├─ contract_003.hwpx
├─ ...
├─ contract_100.hwpx
└─ [생성 로그.txt]
   - 각 파일 생성 시간
   - 오류 내역 (있으면)
```

---

## 워크플로우

### 단일 문서 생성
```
1. 템플릿 HWPX 준비
2. 데이터 입력 (JSON 또는 직접 제공)
3. 플레이스홀더 치환
4. 결과 HWPX 생성
5. 검증 (글꼴, 표 등)
```

### 배치 문서 생성
```
1. 템플릿 HWPX 준비
2. 데이터 파일 준비 (Excel/CSV)
3. 배치 처리 시작 (행별 문서 생성)
4. 진행 상황 표시
5. 완성 ZIP 다운로드
6. 오류 리포트 제공
```

---

## 트러블슈팅

| 증상 | 원인 | 해결 |
|------|------|------|
| 한글 깨짐 | 인코딩 오류 (UTF-8 미사용) | UTF-8 인코딩 확인 |
| 글꼴 미지원 | 한글 미지원 글꼴 | 서울남산체, 맑은고딕 등으로 변경 |
| 플레이스홀더 안 바뀜 | 필드명 오타 | 데이터 키와 템플릿 필드 일치 확인 |
| 표 깨짐 | 테이블 구조 복잡 | 단순한 표 구조 권장 |
| 이미지 미표시 | 경로 오류 또는 지원하지 않는 포맷 | JPG/PNG 사용, 절대 경로 확인 |
| 파일 열기 실패 | HWPX 손상 또는 한글 버전 미지원 | 최신 한글 버전으로 열기 |

---

## 기술 사양

### 지원 환경
```
- 한글 2014 이상
- Python 3.8+ (lxml, zipfile 라이브러리)
- Java (Apache POI HWPX 확장)
```

### 지원 요소
```
✅ 본문 텍스트
✅ 글자 스타일 (글꼴, 크기, 색상, 볼드, 이탤릭)
✅ 문단 스타일 (정렬, 들여쓰기, 줄 간격)
✅ 표 (병합, 셀 배경 색)
✅ 글머리/번호 매김
✅ 이미지 (JPG, PNG)
✅ 머리글/바닥글
✅ 페이지 번호
⚠️ 필드 (조건부 삽입 제한적)
❌ 양식/서식 (미지원)
❌ VBA 매크로 (미지원)
```

---

## 프롬프트 예시

```
"100개의 개인용역계약서를 한글로 자동 생성해줘.

[템플릿]
- 파일: contract_template.hwpx
- 플레이스홀더:
  {{용역업체명}}, {{대표자}}, {{주소}},
  {{용역금액}}, {{계약기간}}, {{담당자}}

[데이터]
- customers.xlsx (고객 100명 정보)
  
[요구사항]
- 금액은 숫자→한글 변환
  (예: 5000000 → "오백만원")
- 날짜 포맷: YYYY.MM.DD
- 완성된 HWPX 100개를 ZIP으로 압축

생성 후 오류 로그도 포함해줘."
```
