글벗 (Geulbeot) v8.0

문서 유형 분석·등록 + HWPX 추출 도구 12종 + 템플릿 고도화

다양한 형식의 자료(PDF·HWP·이미지·Excel 등)를 입력하면, AI가 RAG 파이프라인으로 분석한 뒤 선택한 문서 유형(기획서·보고서·발표자료 등)에 맞는 표준 HTML 문서를 자동 생성합니다. 생성된 문서는 웹 편집기에서 수정하고, HTML / PDF / HWP로 출력합니다.

v8에서는 문서 유형 분석·등록 시스템을 구축했습니다. HWPX 파일을 업로드하면 12종의 추출 도구가 XML을 코드 기반으로 파싱하고, 시맨틱 매퍼가 요소 의미를 판별한 뒤, 스타일 생성기가 CSS를 산출하여 사용자 정의 문서 유형으로 등록합니다. 등록된 유형은 기획서·보고서와 동일하게 문서 생성에 사용됩니다.

---

🏗 아키텍처 (Architecture)

핵심 흐름

자료 입력 (파일/폴더)
    │
    ▼
작성 방식 선택 ─── 형식만 변경 / 내용 재구성 / 신규 작성
    │
    ▼
RAG 파이프라인 (9단계) ─── 공통 처리
    │
    ▼
문서 유형 선택
    ├─ 기획서        (기본)
    ├─ 보고서        (기본)
    ├─ 발표자료      (기본)
    └─ 사용자 등록   (v8 — HWPX 분석 → 자동 등록)
    │
    ▼
글벗 표준 HTML 생성 ◀── 템플릿 스타일 + 시맨틱 맵 참조
    │
    ▼
웹 편집기 (수기 편집 / AI 편집)
    │
    ▼
출력 (HTML / PDF / HWP)

1. Backend (Python Flask)

• Language: Python 3.13
• Web Framework: Flask 3.0 — 웹 서버 엔진, API 라우팅
• AI:
  • Claude API (Anthropic) — 기획서 생성, AI 편집, 문서 유형 맥락 분석
  • OpenAI API — RAG 임베딩, 인덱싱, 텍스트 추출
  • Gemini API — 보고서 콘텐츠·HTML 생성
• Features:
  • 자료 입력 → 9단계 RAG 파이프라인
  • 문서 유형별 생성: 기획서 (Claude), 보고서 (Gemini), 사용자 정의 유형 (v8 신규)
  • AI 편집: 전체 수정 (/refine), 부분 수정 (/refine-selection)
  • 문서 유형 분석·등록 (v8 신규): HWPX 업로드 → 12종 도구 추출 → 시맨틱 매핑 → 스타일 생성 → 유형 CRUD
  • HWPX 템플릿 관리: 추출·저장·교체·삭제
  • HWP 변환: 하이브리드 방식
  • PDF 변환: WeasyPrint 기반

2. Frontend (순수 JavaScript)

• Features:
  • 웹 WYSIWYG 편집기 — 생성된 문서 직접 수정
  • 작성 방식 선택 탭: 형식만 변경 / 내용 재구성 / 신규 작성
  • 문서 유형 선택 UI: 기본 3종 + 사용자 등록 유형 동적 표시
  • 템플릿 관리 UI: 사이드바 목록·선택·삭제, 요소별 체크박스
  • HTML / PDF / HWP 다운로드

3. 변환 엔진 (Converters)

• RAG 파이프라인: 9단계 — 파일 형식 통일 → 텍스트·이미지 추출 → 도메인 분석 → 의미 단위 청킹 → RAG 임베딩 → 코퍼스 구축 → FAISS 인덱싱 → 콘텐츠 생성 → HTML 조립
• 분량 자동 판단: 5,000자 기준
• HWP 변환 (하이브리드): HTML 분석 → pyhwpx 변환 → HWPX 스타일 주입 → 표 열 너비 수정

4. HWPX 추출 도구 12종 (v8 신규)

HWPX XML에서 특정 항목을 코드 기반으로 추출하는 모듈 패키지 (handlers/tools/):

도구	대상	추출 내용
page_setup	§7 용지/여백	pagePr, margin, 용지 크기
font	§3 글꼴	fontface → 폰트명·유형 매핑
char_style	§4 글자 모양	charPr 28개 속성 전체
para_style	§5 문단 모양	paraPr 23개 속성 전체
border_fill	§2 테두리/배경	borderFill, 색상·선 종류
table	§6 표	tbl, tc, 병합·너비·셀 구조
header_footer	§8 머리말/꼬리말	headerFooter 영역
section	§9 구역 정의	secPr, 다단, 페이지 속성
style_def	스타일 정의	styles 목록 (charPr + paraPr 조합)
numbering	번호매기기	글머리표·번호 체계
image	이미지	그리기 객체, 크기·위치
content_order	본문 순서	section*.xml 문단·표·이미지 순서

• 추출 실패 시 None 반환 (디폴트값 절대 생성 안 함)
• 모든 단위 변환은 hwpx_utils 사용 (hwpunit→mm, charsize→pt)
• hwpx_domain_guide.md 기준 준수

5. 문서 유형 분석·등록 (v8 신규)

HWPX 업로드 → 자동 분석 → 사용자 정의 문서 유형 등록:

1. DocTemplateAnalyzer: HWPX 압축 해제 → 12종 도구로 코드 기반 추출
2. SemanticMapper: 추출 결과에서 요소 의미 판별 (헤더표/푸터표/제목블록/데이터표/섹션)
3. StyleGenerator: 추출값 → CSS 생성 (charPr→클래스, paraPr→클래스, 폰트 매핑, 줄간격)
4. ContentAnalyzer: template_info + semantic_map → content_prompt.json (placeholder 의미·유형·작성 패턴)
5. DocTypeAnalyzer: AI로 맥락(목적/문서유형)과 구조 가이드(섹션별 작성법) 분석 — 레이아웃은 코드 추출
6. TemplateManager: 템플릿 CRUD (생성·조회·삭제·교체), template.html 조립
7. CustomDocType: 등록된 유형으로 실제 문서 생성 — template.html에 사용자 콘텐츠 채움

6. 주요 시나리오 (Core Scenarios)

1. 기획서 생성: RAG 분석 후 Claude API가 구조 추출 → 배치 → 글벗 표준 HTML 생성
2. 보고서 생성: RAG 파이프라인 → Gemini API가 다페이지 HTML 보고서 생성
3. 사용자 정의 문서 생성 (v8 신규): 등록된 유형의 template.html + content_prompt.json을 기반으로, 사용자 입력 내용을 정리·재구성하여 문서 생성
4. 문서 유형 등록 (v8 신규): HWPX 업로드 → 12종 도구 추출 → 시맨틱 매핑 → CSS 생성 → config.json + template.html + semantic_map.json + style.json 자동 저장
5. AI 편집: 웹 편집기에서 전체·부분 수정
6. HWP 내보내기: 하이브리드 변환

프로세스 플로우

RAG 파이프라인 (공통)

flowchart TD
    classDef process fill:#e8f4fd,stroke:#1a365d,stroke-width:1.5px,color:#1a365d
    classDef decision fill:#fffde7,stroke:#f9a825,stroke-width:2px,color:#333
    classDef aiGpt fill:#d4edda,stroke:#10a37f,stroke-width:2px,color:#155724
    classDef startEnd fill:#1a365d,stroke:#1a365d,color:#fff,stroke-width:2px

    A[/"📂 자료 입력 (파일/폴더)"/]:::process
    B["step1: 파일 변환\n모든 형식 → PDF 통일"]:::process
    C["step2: 텍스트·이미지 추출\n⚡ GPT API"]:::aiGpt
    D{"분량 판단\n5,000자 기준"}:::decision

    E["step3: 도메인 분석"]:::process
    F["step4: 의미 단위 청킹"]:::process
    G["step5: RAG 임베딩 ⚡ GPT"]:::aiGpt
    H["step6: 코퍼스 생성"]:::process

    I["step7: FAISS 인덱싱 + 목차 ⚡ GPT"]:::aiGpt
    J(["📋 분석 완료 → 문서 유형 선택"]):::startEnd

    A --> B --> C --> D
    D -->|"≥ 5,000자"| E --> F --> G --> H --> I
    D -->|"< 5,000자"| I
    I --> J

전체 워크플로우 (v8 시점)

flowchart TD
    classDef decision fill:#fffde7,stroke:#f9a825,stroke-width:2px,color:#333
    classDef aiClaude fill:#fff3cd,stroke:#d97706,stroke-width:2px,color:#856404
    classDef aiGemini fill:#d6eaf8,stroke:#4285f4,stroke-width:2px,color:#1a4d8f
    classDef editStyle fill:#fff3e0,stroke:#ef6c00,stroke-width:1.5px,color:#e65100
    classDef exportStyle fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1.5px,color:#4a148c
    classDef startEnd fill:#1a365d,stroke:#1a365d,color:#fff,stroke-width:2px
    classDef planned fill:#f5f5f5,stroke:#999,stroke-width:1px,stroke-dasharray: 5 5,color:#999
    classDef newModule fill:#e0f2f1,stroke:#00695c,stroke-width:2px,color:#004d40
    classDef uiNew fill:#e8eaf6,stroke:#3949ab,stroke-width:2px,color:#1a237e

    A(["📂 자료 입력"]):::startEnd

    W{"작성 방식 선택"}:::uiNew
    W1["📄 형식만 변경"]:::uiNew
    W2["🔄 내용 재구성"]:::uiNew
    W3["✨ 신규 작성"]:::uiNew

    R["RAG 파이프라인\n9단계 공통 처리"]:::startEnd

    B{"문서 유형 선택"}:::decision

    C["기획서 생성\n⚡ Claude API"]:::aiClaude
    D["보고서 생성\n⚡ Gemini API"]:::aiGemini
    E["발표자료\n예정"]:::planned
    U["사용자 정의 유형\ntemplate.html 기반\n(v8 신규)"]:::newModule

    T["📋 템플릿 + 시맨틱 맵\nstyle.json\nsemantic_map.json\ncontent_prompt.json"]:::newModule

    G["글벗 표준 HTML"]:::startEnd

    H{"편집 방식"}:::decision
    I["웹 편집기\n수기 편집"]:::editStyle
    J["AI 편집\n전체·부분 수정\n⚡ Claude API"]:::aiClaude

    K{"출력 형식"}:::decision
    L["HTML / PDF"]:::exportStyle
    M["HWP 변환\n하이브리드"]:::exportStyle
    N["PPT\n예정"]:::planned
    O(["✅ 최종 산출물"]):::startEnd

    A --> W
    W --> W1 & W2 & W3
    W1 & W2 & W3 --> R
    R --> B

    B -->|"기획서"| C --> G
    B -->|"보고서"| D --> G
    B -->|"발표자료"| E -.-> G
    B -->|"사용자 유형"| U --> G

    T -.->|"스타일·구조 참조"| U

    G --> H
    H -->|"수기"| I --> K
    H -->|"AI"| J --> K
    K -->|"웹/인쇄"| L --> O
    K -->|"HWP"| M --> O
    K -->|"PPT"| N -.-> O

문서 유형 등록 (v8 신규)

flowchart TD
    classDef process fill:#e8f4fd,stroke:#1a365d,stroke-width:1.5px,color:#1a365d
    classDef newModule fill:#fff3e0,stroke:#ef6c00,stroke-width:2px,color:#e65100
    classDef aiNode fill:#d4edda,stroke:#10a37f,stroke-width:2px,color:#155724
    classDef dataStore fill:#e0f2f1,stroke:#00695c,stroke-width:1.5px,color:#004d40
    classDef startEnd fill:#1a365d,stroke:#1a365d,color:#fff,stroke-width:2px

    A(["📄 HWPX 업로드"]):::startEnd
    B["DocTemplateAnalyzer\n12종 tools 코드 추출"]:::newModule
    C["SemanticMapper\n요소 의미 판별\n헤더표/푸터표/제목블록/데이터표"]:::newModule
    D["StyleGenerator\n추출값 → CSS 생성\ncharPr·paraPr·폰트 매핑"]:::newModule
    E["ContentAnalyzer\nplaceholder 의미·유형\ncontent_prompt.json"]:::newModule
    F["DocTypeAnalyzer\n⚡ AI 맥락·구조 분석\nconfig.json"]:::aiNode
    G["TemplateManager\ntemplate.html 조립"]:::newModule

    H[("📋 templates/user/\ntemplates/{tpl_id}/\ndoc_types/{type_id}/")]:::dataStore

    A --> B --> C --> D --> E
    B --> F
    C & D & E & F --> G --> H

---

🔄 v7 → v8 변경사항

영역	v7	v8
문서 유형 등록	없음	HWPX → 자동 분석 → 유형 CRUD (doc_type_analyzer + custom_doc_type)
HWPX 추출	template/processor.py 단일	handlers/tools/ 12종 모듈 (폰트·문단·표·테두리·이미지 등)
시맨틱 매핑	없음	semantic_mapper — 요소 의미 판별 (헤더/푸터/제목/데이터표)
스타일 생성	CSS 자동 생성 (기초)	style_generator v2.1 — charPr 28개·paraPr 23개 전체 CSS 클래스
콘텐츠 분석	없음	content_analyzer — placeholder 의미·유형·작성 패턴 추출
템플릿 관리	분석·저장·CRUD	template_manager v5.2 — content_order 기반 본문 조립, 독립 저장 구조
도메인 지식	없음	domain/hwpx/ — hwpx_utils + hwpx_domain_guide.md
기본 문서유형	하드코딩	config.json 3종 (briefing·report·presentation)
사용자 유형	없음	templates/user/ 디렉토리 (doc_types + templates 분리)
신규 API	—	/api/doc-types CRUD, /api/templates CRUD, /api/doc-types/analyze-stream
app.py	354줄	682줄 (+328)
Python 전체	11,500줄	18,917줄 (+7,417)

---

🗺 상태 및 로드맵 (Status & Roadmap)

• Phase 1: RAG 파이프라인 — 9단계 파이프라인, 도메인 분석, 분량 자동 판단 (🔧 기본 구현)
• Phase 2: 문서 생성 — 기획서·보고서·사용자 정의 유형 AI 생성 (🔧 기본 구현)
• Phase 3: 출력 — HTML/PDF 다운로드, HWP 변환 (🔧 기본 구현)
• Phase 4: HWP/HWPX/HTML 매핑 — 스타일 분석·HWPX 생성·스타일 주입·표 주입 (🔧 기본 구현)
• Phase 5: 문서 유형 분석·등록 — HWPX → 12종 도구 추출 → 시맨틱 매핑 → 유형 CRUD (🔧 기본 구현 · 현재 버전)
• Phase 6: HWPX 템플릿 관리 — template_manager v5.2, content_order 기반 조립, 독립 저장 (🔧 기본 구현 · 현재 버전)
• Phase 7: UI 고도화 — 작성 방식·문서 유형·템플릿 관리 UI (🔧 기본 구현)
• Phase 8: 백엔드 재구조화 + 배포 — 패키지 정리, API 키 공통화, 로깅, Docker (예정)

---

🚀 시작하기 (Getting Started)

사전 요구사항

• Python 3.10+
• Claude API 키 (Anthropic) — 기획서 생성, AI 편집, 문서 유형 분석
• OpenAI API 키 — RAG 파이프라인
• Gemini API 키 — 보고서 콘텐츠·HTML 생성
• pyhwpx — HWP 변환 시 (Windows + 한글 프로그램 필수)

환경 설정

# 저장소 클론
git clone http://[Gitea주소]/kei/geulbeot-v8.git
cd geulbeot-v8

# 가상환경
python -m venv venv
venv\Scripts\activate        # Windows

# 패키지 설치
pip install -r requirements.txt

# 환경변수
cp .env.sample .env
# .env 파일을 열어 실제 API 키 입력

.env 작성

CLAUDE_API_KEY=sk-ant-your-key-here    # 기획서 생성, AI 편집, 유형 분석
GPT_API_KEY=sk-proj-your-key-here      # RAG 파이프라인
GEMINI_API_KEY=AIzaSy-your-key-here    # 보고서 콘텐츠 생성

실행

python app.py
# → http://localhost:5000 접속

---

📂 프로젝트 구조

geulbeot_8th/
├── app.py                              # Flask 웹 서버 — API 라우팅 (682줄)
├── api_config.py                       # .env 환경변수 로더
│
├── domain/                             # ★ v8 신규 — 도메인 지식
│   └── hwpx/
│       ├── hwpx_domain_guide.md        #   HWPX 명세서 (§1~§11)
│       └── hwpx_utils.py              #   단위 변환 (hwpunit→mm, charsize→pt)
│
├── handlers/                           # 비즈니스 로직
│   ├── common.py                       #   Claude API 호출, JSON/HTML 추출
│   ├── briefing/                       #   기획서 처리
│   ├── report/                         #   보고서 처리
│   ├── template/                       #   템플릿 기본 관리
│   │
│   ├── doc_type_analyzer.py           #   ★ v8 — 문서 유형 AI 분석 (맥락·구조)
│   ├── doc_template_analyzer.py       #   ★ v8 — HWPX → 12종 도구 추출 오케스트레이터
│   ├── semantic_mapper.py             #   ★ v8 — 요소 의미 판별 (헤더/푸터/제목/데이터표)
│   ├── style_generator.py            #   ★ v8 — 추출값 → CSS 클래스 생성
│   ├── content_analyzer.py           #   ★ v8 — placeholder 의미·유형·작성 패턴
│   ├── template_manager.py           #   ★ v8 — 템플릿 CRUD + template.html 조립
│   ├── custom_doc_type.py            #   ★ v8 — 사용자 정의 유형 문서 생성
│   │
│   └── tools/                          #   ★ v8 — HWPX 추출 도구 12종
│       ├── page_setup.py              #     §7 용지/여백
│       ├── font.py                    #     §3 글꼴
│       ├── char_style.py             #     §4 글자 모양 (charPr 28개)
│       ├── para_style.py             #     §5 문단 모양 (paraPr 23개)
│       ├── border_fill.py            #     §2 테두리/배경
│       ├── table.py                   #     §6 표 (병합·너비·셀)
│       ├── header_footer.py          #     §8 머리말/꼬리말
│       ├── section.py                #     §9 구역 정의
│       ├── style_def.py              #     스타일 정의
│       ├── numbering.py              #     번호매기기/글머리표
│       ├── image.py                   #     이미지/그리기 객체
│       └── content_order.py          #     본문 콘텐츠 순서
│
├── converters/                         # 변환 엔진
│   ├── pipeline/                       #   9단계 RAG 파이프라인
│   ├── style_analyzer.py             #   HTML 요소 역할 분류
│   ├── hwpx_generator.py             #   HWPX 파일 직접 생성
│   ├── hwp_style_mapping.py          #   역할 → HWP 스타일 매핑
│   ├── hwpx_style_injector.py        #   HWPX 커스텀 스타일 주입
│   ├── hwpx_table_injector.py        #   HWPX 표 열 너비 정밀 수정
│   ├── html_to_hwp.py                #   보고서 → HWP 변환
│   └── html_to_hwp_briefing.py       #   기획서 → HWP 변환
│
├── templates/                          # 문서 유형 + UI
│   ├── default/doc_types/             #   기본 유형 설정
│   │   ├── briefing/config.json       #     기획서
│   │   ├── report/config.json         #     보고서
│   │   └── presentation/config.json   #     발표자료
│   ├── user/                           #   ★ v8 — 사용자 등록 데이터
│   │   ├── doc_types/{type_id}/       #     config.json + content_prompt.json
│   │   └── templates/{tpl_id}/        #     meta.json + style.json + semantic_map.json + template.html
│   ├── hwp_guide.md
│   ├── hwp_html_defaults.json
│   └── index.html                     #   메인 UI
│
├── static/
│   ├── js/editor.js                    # 웹 WYSIWYG 편집기
│   └── css/editor.css                  # 편집기 스타일
│
├── .env / .env.sample
├── .gitignore
├── requirements.txt
├── Procfile
└── README.md

---

🎨 글벗 표준 HTML 양식

항목	사양
용지	A4 인쇄 최적화 (210mm × 297mm)
폰트	Noto Sans KR (Google Fonts)
색상	Navy 계열 (#1a365d 기본)
구성	page-header → lead-box → section → data-table → bottom-box → page-footer
인쇄	@media print 대응, break-after: page 페이지 분리

---

⚠️ 알려진 제한사항

• 로컬 경로 하드코딩: D:\for python\... 잔존 (router.py, app.py)
• API 키 분산: 파이프라인 각 step에 개별 정의 (공통화 미완)
• HWP 변환: Windows + pyhwpx + 한글 프로그램 필수
• 발표자료: config.json만 존재, 실제 생성 미구현
• 사용자 유형 생성: template.html 기반 채움만 (AI 창작 아닌 정리·재구성)
• 레거시 잔존: prompts/ 디렉토리, templates/hwp_guide.html → .md 전환 중

---

📊 코드 규모

영역	줄 수
Python 전체	18,917 (+7,417)
프론트엔드 (JS + CSS + HTML)	5,269 (+365)
합계	~24,200

---

📝 버전 이력

버전	핵심 변경
v1	Flask + Claude API 기획서 생성기
v2	웹 편집기 추가
v3	9단계 RAG 파이프라인 + HWP 변환
v4	코드 모듈화 (handlers 패키지) + 스타일 분석기·HWPX 생성기
v5	HWPX 스타일 주입 + 표 열 너비 정밀 변환
v6	HWPX 템플릿 분석·저장·관리
v7	UI 고도화 — 작성 방식·문서 유형·템플릿 관리 UI
v8	문서 유형 분석·등록 + HWPX 추출 도구 12종 + 템플릿 고도화

---

📝 라이선스

Private — GPD 내부 사용