# 글벗 (Geulbeot) v10.0

**백엔드 재구조화 + 프론트 모듈화 + 도메인 지식 시스템 + 데모 모드**

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

v10에서는 코드베이스를 전면 재구조화했습니다.
백엔드는 handlers를 doc·template 서브패키지로 분리하고,
프론트엔드는 3,700줄짜리 index.html을 781줄로 축소하며 JS 9개 모듈로 분리했습니다.
토목 14개 세부분야 도메인 지식 시스템과 시연용 데모 모드를 추가했습니다.

---

## 🏗 아키텍처 (Architecture)

### 핵심 흐름

```
자료 입력 (파일/폴더)
    │
    ▼
도메인 지식 선택 (v10 신규) ─── 토목 14개 분야 + DX + 보고서 가이드
    │
    ▼
작성 방식 선택 ─── 형식만 변경 / 내용 재구성 / 신규 작성
    │
    ▼
RAG 파이프라인 (9단계) ─── 공통 처리 + 도메인 프롬프트
    │
    ▼
문서 유형 선택
    ├─ 기획서        (기본)
    ├─ 보고서        (기본)
    ├─ 발표자료      (기본)
    └─ 사용자 등록   (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), 사용자 정의 유형
  - AI 편집: 전체 수정 (`/refine`), 부분 수정 (`/refine-selection`)
  - 문서 유형 분석·등록: HWPX → 12종 도구 추출 → 시맨틱 매핑 → 스타일 생성 → 유형 CRUD
  - 도메인 지식 관리 (v10 신규): 토목 14분야 + DX + 보고서 가이드
  - HWP/PDF 변환

### 2. Frontend (v10 모듈화)

- **index.html**: 3,763줄 → **781줄** — HTML 셸만 유지
- **main.css**: 1,825줄 — 인라인 CSS 전부 외부 분리
- **JS 9개 모듈**:

| 모듈 | 줄 수 | 역할 |
|------|-------|------|
| editor.js | 1,208 | 웹 WYSIWYG 편집기 |
| doc_type.js | 587 | 문서 유형 선택·CRUD |
| generator.js | 483 | 기획서·보고서 생성 호출 |
| demo_mode.js | 370 | 시연용 데모 모드 |
| domain_selector.js | 287 | 도메인 지식 선택 모달 |
| template.js | 188 | 템플릿 관리 UI |
| ai_edit.js | 142 | AI 편집 (전체·부분) |
| modals.js | 134 | 공통 모달 컴포넌트 |
| ui.js | 91 | UI 유틸리티 |
| export.js | 71 | HTML/PDF/HWP 다운로드 |

### 3. 백엔드 패키지 구조 (v10 재구조화)

```
handlers/
├── briefing/          기획서 생성
├── report/            보고서 생성
├── doc/               ★ v10 — 문서 유형 서브패키지
│   ├── doc_type_analyzer.py     AI 맥락·구조 분석
│   ├── content_analyzer.py      placeholder 분석
│   └── custom_doc_type.py       사용자 유형 문서 생성
└── template/          ★ v10 — 템플릿 서브패키지
    ├── processor.py             기본 관리
    ├── doc_template_analyzer.py 12종 도구 오케스트레이터
    ├── semantic_mapper.py       요소 의미 판별
    ├── style_generator.py       CSS 생성
    ├── template_manager.py      CRUD + template.html 조립
    └── tools/                   HWPX 추출 도구 12종
```

### 4. 도메인 지식 시스템 (v10 신규)

- **domain_api.py** (456줄): 도메인 지식 관리 API + 파이프라인 래퍼
- **domain_config.json**: 카테고리 구조 정의 (계층형 선택)
- **토목 14개 세부분야**: 측량·해석·교량·터널·도로·구조·지반·시공·공정원가·품질환경·안전·통신·BIM·기획
- **DX (디지털 전환)**: 스마트 건설, AI/IoT
- **보고서 가이드**: 현안보고서 구조, 작성 가이드
- **도메인 선택 UI**: 체크박스 모달 → 선택된 .txt 합쳐서 RAG 파이프라인에 도메인 프롬프트로 전달

### 5. 데모 모드 (v10 신규)

- **demo_mode.js**: `DEMO_MODE = true` 시 실제 API 호출 없이 샘플 문서 표시
- **샘플 HTML 4종**: 기획서 1p·2p, 보고서, 발표자료
- 시연·발표용 — 목차 애니메이션 + 가짜 생성 프로세스

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

1. **기획서 생성**: RAG 분석 후 Claude API가 글벗 표준 HTML 생성
2. **보고서 생성**: RAG 파이프라인 → Gemini API가 다페이지 HTML 보고서 생성
3. **사용자 정의 문서 생성**: 등록된 유형의 template.html 기반 정리·재구성
4. **문서 유형 등록**: HWPX 업로드 → 자동 분석 → 유형 CRUD
5. **도메인 지식 적용 (v10 신규)**: 분야 선택 → RAG 파이프라인에 전문 용어·기준 주입
6. **데모 시연 (v10 신규)**: API 없이 샘플 문서로 전체 워크플로우 시연
7. **AI 편집 / HWP 내보내기**

### 프로세스 플로우

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

#### 전체 워크플로우 (v10 시점)

```mermaid
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
    classDef domainStyle fill:#fce4ec,stroke:#c62828,stroke-width:2px,color:#b71c1c

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

    DOM["🏗️ 도메인 지식 선택\n토목 14분야 + DX\n(v10 신규)"]:::domainStyle

    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 기반"]:::newModule

    T["📋 템플릿 + 시맨틱 맵"]:::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 --> DOM --> W
    W --> W1 & W2 & W3
    W1 & W2 & W3 --> R

    DOM -.->|"도메인 프롬프트"| 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
```

#### 문서 유형 등록

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

---

## 🔄 v9 → v10 변경사항

| 영역 | v9 | v10 |
|------|------|------|
| handlers 구조 | 평탄 (루트에 7개 모듈) | **handlers/doc/ + handlers/template/** 서브패키지로 분리 |
| 프론트 index.html | 3,763줄 (인라인 CSS·JS) | **781줄** — HTML 셸만 유지 |
| CSS | 인라인 | **static/css/main.css** (1,825줄) 외부 분리 |
| JS | editor.js 단일 | **9개 모듈** 분리 (doc_type·generator·demo_mode 등) |
| 도메인 지식 | 없음 | **domain_api.py** + domain_config.json + 토목 14분야 txt |
| 도메인 선택 UI | 없음 | **domain_selector.js** — 체크박스 모달 |
| 데모 모드 | 없음 | **demo_mode.js** + 샘플 HTML 4종 |
| 보고서 가이드 | 없음 | **domain/report_guide/** — 현안보고서 구조·작성법 |
| 레거시 정리 | prompts/ 잔존 | **prompts/ 삭제** |

---

## 🗺 상태 및 로드맵 (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, content_order, 독립 저장 (🔧 기본 구현)
- **Phase 7**: UI 고도화 — 프론트 모듈화, 데모 모드, 도메인 선택기 (🔧 기본 구현 · 현재 버전)
- **Phase 8**: 백엔드 재구조화 — handlers 서브패키지 분리, 레거시 정리 (🔧 기본 구현 · 현재 버전)

---

## 🚀 시작하기 (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-v10.git
cd geulbeot-v10

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 접속
```

### 데모 모드

API 키 없이 시연하려면 `static/js/demo_mode.js`에서 `DEMO_MODE = true` 확인 후 실행.
샘플 문서(기획서 2종 + 보고서 + 발표자료)가 자동 표시됩니다.

---

## 📂 프로젝트 구조

```
geulbeot_10th/
├── app.py                              # Flask 웹 서버 — API 라우팅
├── api_config.py                       # .env 환경변수 로더
├── domain_api.py                       # ★ v10 — 도메인 지식 관리 API
├── domain_config.json                  # ★ v10 — 도메인 카테고리 구조
│
├── domain/                             # 도메인 지식
│   ├── hwpx/                           #   HWPX 명세서 + 유틸
│   ├── civil/                          #   ★ v10 — 토목 분야
│   │   ├── general.txt                #     토목 일반
│   │   ├── dx.txt                     #     DX (디지털 전환)
│   │   └── specialties/              #     14개 세부분야
│   │       ├── survey.txt · road.txt · bridge.txt · tunnel.txt
│   │       ├── structure.txt · geotechnical.txt · construction.txt
│   │       ├── schedule_cost.txt · quality_env.txt · safety.txt
│   │       ├── communication.txt · bim.txt · planning.txt
│   │       └── anlysis.txt
│   └── report_guide/                  #   ★ v10 — 보고서 작성 가이드
│
├── handlers/                           # 비즈니스 로직 (★ v10 재구조화)
│   ├── common.py
│   ├── briefing/                       #   기획서 처리
│   ├── report/                         #   보고서 처리
│   ├── doc/                            #   ★ v10 서브패키지 — 문서 유형
│   │   ├── doc_type_analyzer.py
│   │   ├── content_analyzer.py
│   │   └── custom_doc_type.py
│   └── template/                       #   ★ v10 서브패키지 — 템플릿
│       ├── processor.py · template_manager.py
│       ├── doc_template_analyzer.py · semantic_mapper.py
│       ├── style_generator.py
│       └── tools/                      #   HWPX 추출 도구 12종
│
├── converters/                         # 변환 엔진
│   ├── pipeline/                       #   9단계 RAG 파이프라인
│   └── (style_analyzer, hwpx_*, html_to_hwp*)
│
├── templates/
│   ├── default/doc_types/             #   기본 유형 (briefing·report·presentation)
│   ├── user/                           #   사용자 등록 데이터
│   └── index.html                     #   ★ v10 — 781줄 (HTML 셸만)
│
├── static/                             # ★ v10 프론트 모듈화
│   ├── css/
│   │   ├── main.css                   #   1,825줄 (인라인 CSS 분리)
│   │   └── editor.css                 #   편집기 스타일
│   ├── js/
│   │   ├── editor.js                  #   WYSIWYG 편집기
│   │   ├── doc_type.js                #   문서 유형 선택·CRUD
│   │   ├── generator.js               #   문서 생성 호출
│   │   ├── demo_mode.js               #   시연용 데모
│   │   ├── domain_selector.js         #   도메인 지식 선택
│   │   ├── template.js                #   템플릿 관리
│   │   ├── ai_edit.js                 #   AI 편집
│   │   ├── modals.js                  #   공통 모달
│   │   ├── ui.js                      #   UI 유틸리티
│   │   └── export.js                  #   다운로드
│   └── result/                         #   ★ v10 — 데모 샘플 HTML 4종
│
├── .env / .env.sample
├── .gitignore
├── 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` 페이지 분리 |

---

## ⚠️ 알려진 제한사항

- API 키 분산: 파이프라인 각 step에 개별 정의 (공통화 미완)
- HWP 변환: Windows + pyhwpx + 한글 프로그램 필수
- 발표자료: config.json만 존재, 실제 생성 미구현
- 도메인 지식: 토목 분야만 구축 (타 분야 확장 가능)
- 도메인 → RAG 연동: 선택된 도메인 프롬프트 주입 경로 완성 중

---

## 📊 코드 규모

| 영역 | 줄 수 |
|------|-------|
| Python 전체 | 19,402 (+462) |
| 프론트엔드 (JS + CSS + HTML) | 6,463 (+1,196) |
| 도메인 지식 (txt) | 1,225 |
| **합계** | **~27,100** |

---

## 📝 버전 이력

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

---

## 📝 라이선스

Private — GPD 내부 사용