test/README.md

# 글벗 (Geulbeot) v7.0

**UI 고도화 — 템플릿 관리·작성 방식·문서 유형 선택 UI**

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

v7에서는 프론트엔드 UI를 고도화했습니다.
v6에서 백엔드로만 존재하던 템플릿 관리를 화면에서 직접 조작할 수 있게 되었고,
자료 활용 방식(형식 변경·재구성·신규 작성)과 문서 유형을 시각적으로 선택하는 UI가 추가되었습니다.

---

## 🏗 아키텍처 (Architecture)

### 핵심 흐름

```
자료 입력 (파일/폴더)
    │
    ▼
작성 방식 선택 ─── 형식만 변경 / 내용 재구성 / 신규 작성 (v7 신규)
    │
    ▼
RAG 파이프라인 (9단계) ─── 공통 처리
    │
    ▼
문서 유형 선택 ─── UI 리스트 (v7 신규)
    ├─ 기획서        (기본)
    ├─ 보고서        (기본)
    ├─ 발표자료      (기본)
    └─ 사용자 등록   (확장 가능)
    │
    ▼
글벗 표준 HTML 생성 ◀── 템플릿 스타일 참조 + 요소 선택 (v7 신규)
    │
    ▼
웹 편집기 (수기 편집 / 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 3단계), 보고서 (Gemini 2단계)
  - AI 편집: 전체 수정 (`/refine`), 부분 수정 (`/refine-selection`)
  - HWPX 템플릿 분석·저장·관리
  - HWP 변환: 하이브리드 방식 — pyhwpx → HWPX 스타일 주입 → 표 열 너비 수정
  - PDF 변환: WeasyPrint 기반

### 2. Frontend (순수 JavaScript)

- **Features**:
  - 웹 WYSIWYG 편집기 — 브라우저에서 생성된 문서 직접 수정
  - 페이지 넘김·들여쓰기·정렬 등 서식 도구
  - HTML / PDF / HWP 다운로드
  - **작성 방식 선택 탭 (v7 신규)**: 📄 형식만 변경 / 🔄 내용의 재구성 / ✨ 문서 참고 신규 작성
  - **문서 유형 선택 UI (v7 신규)**: 기획서·보고서 라디오 리스트 + 배지 스타일
  - **템플릿 관리 UI (v7 신규)**: 사이드바에서 템플릿 업로드·선택·삭제, 적용할 요소 체크박스

### 3. 변환 엔진 (Converters)

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

### 4. 템플릿 관리

- **HWPX 파싱**: 업로드된 HWPX를 압축 해제하여 header.xml + section*.xml 구조 분석
- **자동 추출**: 폰트·문단·표·배경·테두리·페이지 설정
- **CSS 자동 생성**: 분석된 스타일 → CSS 변환
- **저장소**: `templates_store/` — meta.json + 원본 + 분석 결과
- **UI 연동 (v7 신규)**: 사이드바에서 목록 조회·선택·삭제, 요소별 적용 체크박스

### 5. 주요 시나리오 (Core Scenarios)

1. **기획서 생성**: 텍스트 또는 파일을 입력하면, RAG 분석 후 Claude API가 구조 추출 → 페이지 배치 계획 → 글벗 표준 HTML 기획서를 생성. 1~N페이지 옵션 지원
2. **보고서 생성**: 폴더 경로의 자료들을 RAG 파이프라인으로 분석하고, Gemini API가 섹션별 콘텐츠 초안 → 표지·목차·간지·별첨이 포함된 다페이지 HTML 보고서를 생성
3. **작성 방식 선택 (v7 신규)**: 업로드 자료를 어떻게 활용할지 3가지 모드 중 선택
   - 📄 **형식만 변경** — 원본 내용 유지, 글벗 양식으로만 변환
   - 🔄 **내용의 재구성** — 원본 기반으로 구조와 내용을 재구성 (기본값)
   - ✨ **문서 참고 신규 작성** — 원본을 참고 자료로만 활용, 새로 작성
4. **템플릿 적용**: 등록된 HWPX 템플릿을 선택하고, 적용할 요소(제목 스타일·표 스타일·색상 등)를 체크박스로 선택
5. **HWP 내보내기**: pyhwpx 변환 후 HWPX 스타일 주입 + 표 열 너비 정밀 수정

### 프로세스 플로우

#### RAG 파이프라인 (공통)

```mermaid
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
```

---

## 🔄 v6 → v7 변경사항

| 영역 | v6 | v7 |
|------|------|------|
| 작성 방식 | 없음 (무조건 재구성) | **3가지 모드 UI**: 형식 변경 / 재구성 / 신규 작성 |
| 문서 유형 선택 | 기획서·보고서 구분 없이 탭 | **문서 유형 라디오 리스트** + 배지 스타일 |
| 템플릿 관리 UI | API만 존재 (화면 없음) | **사이드바 UI**: 목록·선택·삭제 + 요소별 체크박스 |
| 템플릿 업로드 | API 직접 호출 | **모달 UI**: 파일 선택 + 이름 입력 + 업로드 |
| index.html | 2,974줄 | 3,400줄 (+426) |
| Python | 변경 없음 | 변경 없음 |

---

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

- **Phase 1**: RAG 파이프라인 — 9단계 파이프라인, 도메인 분석, 분량 자동 판단 (🔧 기본 구현)
- **Phase 2**: 문서 생성 — 기획서·보고서 AI 생성 + 글벗 표준 HTML 양식 (🔧 기본 구현)
- **Phase 3**: 출력 — HTML/PDF 다운로드, HWP 변환 (🔧 기본 구현)
- **Phase 4**: HWP/HWPX/HTML 매핑 — 스타일 분석·HWPX 생성·스타일 주입·표 주입 (🔧 기본 구현)
- **Phase 5**: 문서 유형 분석·등록 — HWPX 업로드 → AI 구조 분석 → 유형 CRUD + 확장 (예정)
- **Phase 6**: HWPX 템플릿 관리 — 파싱·스타일 추출·CSS 생성·저장·조회·삭제 (🔧 기본 구현)
- **Phase 7**: UI 고도화 — 작성 방식 선택, 문서 유형 UI, 템플릿 관리 UI (🔧 기본 구현 · 현재 버전)
- **Phase 8**: 백엔드 재구조화 + 배포 — 패키지 정리, API 키 공통화, 로깅, Docker (예정)

---

## 🚀 시작하기 (Getting Started)

### 사전 요구사항

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

### 환경 설정

```bash
# 저장소 클론 및 설정
git clone http://[Gitea주소]/kei/geulbeot-v7.git
cd geulbeot-v7

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

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

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

### .env 작성

```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    # 보고서 콘텐츠 생성
```

### 실행

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

---

## 📂 프로젝트 구조

```
geulbeot_7th/
├── app.py                          # Flask 웹 서버 — API 라우팅
├── api_config.py                   # .env 환경변수 로더
│
├── handlers/                       # 비즈니스 로직
│   ├── common.py                   #   Claude API 호출, JSON/HTML 추출
│   ├── briefing/                   #   기획서 처리 (구조추출 → 배치 → HTML)
│   ├── report/                     #   보고서 처리 (RAG 파이프라인 연동)
│   └── template/                   #   템플릿 관리 (HWPX 파싱·분석·CRUD)
│
├── 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_store/                # 등록된 템플릿 저장소
│
├── static/
│   ├── js/editor.js                # 웹 WYSIWYG 편집기
│   └── css/editor.css              # 편집기 스타일
├── templates/
│   ├── index.html                  # ★ v7 고도화 — 작성 방식·문서 유형·템플릿 UI
│   └── hwp_guide.html             # HWP 변환 가이드
│
├── .env / .env.sample              # API 키 관리
├── .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 + 한글 프로그램 필수
- 문서 유형: 기획서·보고서만 구현, 발표자료·사용자 등록 유형 미구현
- 작성 방식: UI만 구현, 백엔드 로직 미연동 (모드별 프롬프트 분기 예정)
- 템플릿 → 문서 생성 연동: 아직 미연결 (선택·체크는 가능, 생성 시 자동 적용은 예정)
- 레거시 잔존: prompts/ 디렉토리

---

## 📊 코드 규모

| 영역 | 줄 수 |
|------|-------|
| Python 전체 | 11,500 |
| 프론트엔드 (JS + CSS + HTML) | 4,904 (+1,045) |
| **합계** | **~16,400** |

---

## 📝 버전 이력

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

---

## 📝 라이선스

Private — GPD 내부 사용