v4:코드모듈화_20260123

README.md

@@ -1,145 +1,308 @@
-# 글벗 Light v3.0
+# 글벗 (Geulbeot) v4.0
 
-AI 기반 문서 자동화 시스템 — 9단계 RAG 파이프라인 + 웹 편집기 + HWP 변환
+**AI 기반 문서 자동화 시스템 — GPD 총괄기획실**
 
-## 🎯 개요
+다양한 형식의 자료(PDF·HWP·이미지·Excel 등)를 입력하면, AI가 RAG 파이프라인으로 분석한 뒤
+선택한 문서 유형(기획서·보고서·발표자료 등)에 맞는 표준 HTML 문서를 자동 생성합니다.
+생성된 문서는 웹 편집기에서 수정하고, HTML / PDF / HWP로 출력합니다.
 
-다양한 형식의 입력 문서(PDF, HWP, 이미지, 동영상 등)를 분석하여 표준 HTML 보고서를 자동 생성하고, 웹 편집기로 수정한 뒤 HTML/PDF/HWP로 출력하는 시스템입니다.
+---
 
-## 📁 프로젝트 구조
+## 🏗 아키텍처 (Architecture)
+
+### 핵심 흐름
 
 ```
-geulbeot_3rd/
-├── app.py                              # Flask 메인 서버 (579줄)
-├── api_config.py                       # API 키 로더
-├── converters/
-│   ├── pipeline/                       # 9단계 RAG 파이프라인
-│   │   ├── router.py                   # 분기 판단 (긴/짧은 문서)
-│   │   ├── step1_convert.py            # 파일→PDF 변환 (783줄)
-│   │   ├── step2_extract.py            # 텍스트/이미지 추출 (788줄)
-│   │   ├── step3_domain.py             # 도메인 분석 (265줄)
-│   │   ├── step4_chunk.py              # 청킹 (356줄)
-│   │   ├── step5_rag.py                # RAG 임베딩 (141줄)
-│   │   ├── step6_corpus.py             # 코퍼스 생성 (231줄)
-│   │   ├── step7_index.py              # 인덱싱 + 목차 생성 (504줄)
-│   │   ├── step8_content.py            # 콘텐츠 생성 (1020줄)
-│   │   └── step9_html.py              # HTML 생성 (1248줄)
-│   ├── html_to_hwp.py                 # 보고서→HWP 변환 (572줄)
-│   └── html_to_hwp_briefing.py        # 기획서→HWP 변환 (572줄)
-├── prompts/
-│   ├── step1_extract.txt              # 구조 추출 프롬프트
-│   ├── step1_5_plan.txt               # 배치 계획 프롬프트
-│   └── step2_generate.txt             # HTML 생성 프롬프트
-├── static/
-│   ├── css/editor.css                 # 편집기 스타일
-│   └── js/editor.js                   # 편집기 기능
-├── templates/
-│   ├── index.html                     # 메인 UI
-│   └── hwp_guide.html                # HWP 변환 가이드
-├── output/assets/                     # 이미지 에셋
-├── requirements.txt
-├── Procfile
-└── railway.json
+자료 입력 (파일/폴더)
+    │
+    ▼
+RAG 파이프라인 (9단계) ─── 공통 처리
+    │
+    ▼
+문서 유형 선택
+    ├─ 기획서        (기본)
+    ├─ 보고서        (기본)
+    ├─ 발표자료      (기본)
+    └─ 사용자 등록   (확장 가능)
+    │
+    ▼
+글벗 표준 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 파이프라인 (파일 변환 → 추출 → 도메인 분석 → 청킹 → 임베딩 → 코퍼스 → 인덱싱 → 콘텐츠 생성 → HTML 조립)
+  - 문서 유형별 생성: 기획서 (Claude 3단계), 보고서 (Gemini 2단계)
+  - AI 편집: 전체 수정 (`/refine`), 부분 수정 (`/refine-selection`)
+  - HWP 변환: HTML 스타일 분석 → 역할 매핑 → HWPX 생성
+  - PDF 변환: WeasyPrint 기반
+
+### 2. Frontend (순수 JavaScript)
+
+- **Features**:
+  - 웹 WYSIWYG 편집기 — 브라우저에서 생성된 문서 직접 수정
+  - 페이지 넘김·들여쓰기·정렬 등 서식 도구
+  - HTML / PDF / HWP 다운로드
+
+### 3. 변환 엔진 (Converters)
+
+- **RAG 파이프라인**: 9단계 — 파일 형식 통일 → 텍스트·이미지 추출 → 도메인 분석 → 의미 단위 청킹 → RAG 임베딩 → 코퍼스 구축 → FAISS 인덱싱 → 콘텐츠 생성 → HTML 조립
+- **분량 자동 판단**: 5,000자 기준 — 긴 문서는 전체 파이프라인, 짧은 문서는 축약 파이프라인
+- **HWP 변환**: pyhwpx 기반 + v4에서 추가된 스타일 분석기·HWPX 생성기·매핑 모듈
+
+### 4. 주요 시나리오 (Core Scenarios)
+
+1. **기획서 생성**: 텍스트 또는 파일을 입력하면, RAG 분석 후 Claude API가 구조 추출 → 페이지 배치 계획 → 글벗 표준 HTML 기획서를 생성. 1~N페이지 옵션 지원
+2. **보고서 생성**: 폴더 경로의 자료들을 RAG 파이프라인으로 분석하고, Gemini API가 섹션별 콘텐츠 초안 → 표지·목차·간지·별첨이 포함된 다페이지 HTML 보고서를 생성
+3. **AI 편집**: 생성된 문서를 웹 편집기에서 확인 후, "이 부분을 표로 바꿔줘" 같은 피드백으로 전체 또는 선택 부분을 AI가 수정
+4. **HWP 내보내기**: 글벗 HTML을 스타일 분석기가 요소별 역할을 분류하고, HWP 스타일로 매핑하여 서식이 유지된 HWP 파일로 변환
+
+### 프로세스 플로우
+
+#### RAG 파이프라인 (공통)
 
 ```mermaid
-flowchart TB
-    subgraph INPUT["📥 Input"]
-        direction TB
-        A["🗂️ 문서 입력\nPDF, HWP, 이미지, 동영상"] --> B["step1: 파일 변환\nPDF 통일"]
-        B --> C["step2: 텍스트/이미지 추출\n(GPT API)"]
-        C --> D{"router.py\n분량 판단\n5000자 기준"}
-        D -->|"긴 문서"| E["step3: 도메인 분석"]
-        D -->|"짧은 문서"| H
-        E --> F["step4: 청킹"]
-        F --> G["step5: RAG 임베딩"]
-        G --> H["step6: 코퍼스 생성"]
-        H --> I["step7: 인덱싱 + 목차 생성\n(GPT API)"]
-    end
+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
 
-    subgraph OUTPUT["📤 Output"]
-        direction TB
-        I --> J["step8: 콘텐츠 생성\n(Gemini API)"]
-        J --> K["step9: HTML 생성\n(Gemini API)"]
-    end
+    A[/"📂 자료 입력 (파일/폴더)"/]:::process
+    B["step1: 파일 변환\n모든 형식 → PDF 통일"]:::process
+    C["step2: 텍스트·이미지 추출\n⚡ GPT API"]:::aiGpt
+    D{"분량 판단\n5,000자 기준"}:::decision
 
-    subgraph EDIT["✏️ Edit"]
-        direction TB
-        K --> M["웹 편집기\neditor.js"]
-        K --> N["AI 편집\n/refine (Claude API)"]
-    end
+    E["step3: 도메인 분석"]:::process
+    F["step4: 의미 단위 청킹"]:::process
+    G["step5: RAG 임베딩 ⚡ GPT"]:::aiGpt
+    H["step6: 코퍼스 생성"]:::process
 
-    subgraph EXPORT["📦 Export"]
-        direction TB
-        M & N --> P["HTML / PDF"]
-        M & N --> Q["HWP 변환\nhtml_to_hwp.py"]
-    end
+    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
 ```
 
-## 🌐 API 라우트
+#### 문서 유형별 생성 → 편집 → 출력
 
-| 라우트 | 메서드 | 기능 |
-|--------|--------|------|
-| `/` | GET | 메인 페이지 |
-| `/generate` | POST | 기획서 생성 (1단계→1.5단계→2단계) |
-| `/generate-report` | POST | 보고서 생성 (9단계 파이프라인) |
-| `/refine` | POST | AI 전체 수정 |
-| `/refine-selection` | POST | AI 부분 수정 |
-| `/export-hwp` | POST | HWP 변환 |
-| `/download/html` | POST | HTML 다운로드 |
-| `/download/pdf` | POST | PDF 다운로드 |
-| `/health` | GET | 서버 상태 확인 |
+```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
 
-## 🤖 활용 AI
+    A(["📋 RAG 분석 결과"]):::startEnd
+    B{"문서 유형 선택"}:::decision
 
-| 단계 | AI | 역할 |
-|------|-----|------|
-| step2 (추출) | GPT | PDF에서 텍스트/이미지 메타데이터 추출 |
-| step7 (목차) | GPT | 인덱싱 및 목차 자동 생성 |
-| step8 (콘텐츠) | Gemini | 섹션별 본문 초안 생성 |
-| step9 (HTML) | Gemini | 최종 HTML 보고서 생성 |
-| 기획서 생성 | Claude | HTML 구조 추출 + 변환 |
-| AI 편집 | Claude | 피드백 반영 수정 |
+    C["기획서 생성\n구조추출→배치→HTML\n⚡ Claude API"]:::aiClaude
+    D["보고서 생성\n콘텐츠→HTML 조립\n⚡ Gemini API"]:::aiGemini
+    E["발표자료 생성\n예정"]:::planned
+    F["사용자 등록 유형\n확장 가능"]:::planned
+
+    G["글벗 표준 HTML\nA4·Navy·Noto Sans KR"]:::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 --> B
+    B -->|"기획서"| C --> G
+    B -->|"보고서"| D --> G
+    B -->|"발표자료"| E -.-> G
+    B -->|"확장"| F -.-> G
+
+    G --> H
+    H -->|"수기"| I --> K
+    H -->|"AI"| J --> K
+    K -->|"웹/인쇄"| L --> O
+    K -->|"HWP"| M --> O
+    K -->|"PPT"| N -.-> O
+```
+
+---
+
+## 🔄 v3 → v4 변경사항
+
+| 영역 | v3 | v4 |
+|------|------|------|
+| app.py | 모든 로직 포함 (579줄) | 라우팅 전담 (291줄) |
+| 비즈니스 로직 | app.py 내부 | handlers/ 패키지로 분리 (briefing + report + common) |
+| 프롬프트 | prompts/ 공용 1곳 | handlers/*/prompts/ 모듈별 분리 |
+| HWP 변환 | pyhwpx 직접 변환만 | + 스타일 분석기·HWPX 생성기·매핑 모듈 추가 |
+| 환경설정 | 없음 | .env + api_config.py (python-dotenv) |
+
+---
+
+## 🗺 상태 및 로드맵 (Status & Roadmap)
+
+- **Phase 1**: RAG 파이프라인 — 9단계 파이프라인, 도메인 분석, 분량 자동 판단 (🔧 기본 구현 · 현재 버전)
+- **Phase 2**: 문서 생성 — 기획서·보고서 AI 생성 + 글벗 표준 HTML 양식 (🔧 기본 구현)
+- **Phase 3**: 출력 — HTML/PDF 다운로드, HWP 변환 (🔧 기본 구현)
+- **Phase 4**: HWP/HWPX/HTML 매핑 — 스타일 분석기, HWPX 생성기, 역할→HWP 매핑 (🔧 기본 구현)
+- **Phase 5**: 문서 유형 분석·등록 — HWPX 업로드 → AI 구조 분석 → 유형 CRUD + 확장 (예정)
+- **Phase 6**: HWPX 템플릿 관리 — 파싱·시맨틱 매핑·스타일 추출·표 매칭·콘텐츠 주입 (예정)
+- **Phase 7**: UI 고도화 — 프론트 모듈화, 데모 모드, AI 편집 개선, 도메인 선택기 (예정)
+- **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-v4.git
+cd geulbeot-v4
+
+# 가상환경
+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_4th/
+├── app.py                          # Flask 웹 서버 — API 라우팅
+├── api_config.py                   # .env 환경변수 로더
+│
+├── handlers/                       # 비즈니스 로직
+│   ├── common.py                   #   Claude API 호출, JSON/HTML 추출
+│   ├── briefing/                   #   기획서 처리
+│   │   ├── processor.py            #     구조추출 → 배치계획 → HTML 생성
+│   │   └── prompts/                #     각 단계별 AI 프롬프트
+│   └── report/                     #   보고서 처리
+│       ├── processor.py            #     RAG 파이프라인 연동 + AI 편집
+│       └── prompts/
+│
+├── converters/                     # 변환 엔진
+│   ├── pipeline/                   #   9단계 RAG 파이프라인
+│   │   ├── router.py               #     분량 판단 (5,000자 기준)
+│   │   └── step1 ~ step9          #     변환→추출→분석→청킹→임베딩→코퍼스→인덱싱→콘텐츠→HTML
+│   ├── style_analyzer.py          #   HTML 요소 역할 분류 (v4 신규)
+│   ├── hwpx_generator.py          #   HWPX 파일 직접 생성 (v4 신규)
+│   ├── hwp_style_mapping.py       #   역할 → HWP 스타일 매핑 (v4 신규)
+│   ├── html_to_hwp.py             #   보고서 → HWP 변환
+│   └── html_to_hwp_briefing.py    #   기획서 → HWP 변환
+│
+├── static/
+│   ├── js/editor.js                # 웹 WYSIWYG 편집기
+│   └── css/editor.css              # 편집기 스타일
+├── templates/
+│   ├── index.html                  # 메인 UI
+│   └── hwp_guide.html             # HWP 변환 가이드
+│
+├── .env / .env.sample              # API 키 관리
+├── .gitignore
+├── requirements.txt
+├── Procfile                        # 배포 설정 (Gunicorn)
+└── README.md
+```
+
+---
 
 ## 🎨 글벗 표준 HTML 양식
 
-- A4 인쇄 최적화 (210mm × 297mm)
-- Noto Sans KR 폰트
-- Navy 계열 색상 (#1a365d 기본)
-- 구성: page-header, lead-box, section, data-table, bottom-box, footer
+| 항목 | 사양 |
+|------|------|
+| 용지 | 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` 페이지 분리 |
 
-## 🖥️ 로컬 실행
+---
 
-```bash
-pip install -r requirements.txt
-python app.py
-```
+## ⚠️ 알려진 제한사항
 
-http://localhost:5000 접속
+- 로컬 경로 하드코딩: `D:\for python\...` 잔존 (router.py, app.py)
+- API 키 분산: 파이프라인 각 step에 개별 정의 (공통화 미완)
+- HWP 변환: Windows + pyhwpx + 한글 프로그램 필수
+- 문서 유형: 기획서·보고서만 구현, 발표자료·사용자 등록 유형 미구현
+- 레거시 잔존: prompts/ 디렉토리, dkdl.py 테스트 코드
 
-## 🔑 API 키 설정
+---
 
-`api_keys.json` 파일을 프로젝트 루트에 생성:
+## 📊 코드 규모
 
-```json
-{
-    "CLAUDE_API_KEY": "sk-ant-...",
-    "GPT_API_KEY": "sk-proj-...",
-    "GEMINI_API_KEY": "AIzaSy..."
-}
-```
+| 영역 | 줄 수 |
+|------|-------|
+| Python 전체 | 9,780 |
+| 프론트엔드 (JS + CSS + HTML) | 3,859 |
+| **합계** | **~13,600** |
 
-> ⚠️ `api_keys.json`은 `.gitignore`에 포함되어 Git에 올라가지 않습니다.
+---
 
-## 📝 v1 → v3 변경 이력
+## 📝 버전 이력
 
-| 버전 | 변경 내용 |
+| 버전 | 핵심 변경 |
 |------|----------|
-| v1 | Flask + Claude API 기획서 생성기 (12파일, 422줄) |
-| v2 | 웹 편집기 추가 (editor.js, editor.css) |
-| v3 | 9단계 RAG 파이프라인 + HWP 변환 추가 (40파일+, 6000줄+) |
+| v1 | Flask + Claude API 기획서 생성기 |
+| v2 | 웹 편집기 추가 |
+| v3 | 9단계 RAG 파이프라인 + HWP 변환 |
+| **v4** | **코드 모듈화 (handlers 패키지) + 스타일 분석기·HWPX 생성기** |
+
+---
 
 ## 📝 라이선스