📦 Initialize Geulbeot structure and merge Prompts & test projects
This commit is contained in:
309
03. Code/geulbeot_4th/README.md
Normal file
309
03. Code/geulbeot_4th/README.md
Normal file
@@ -0,0 +1,309 @@
|
||||
# 글벗 (Geulbeot) v4.0
|
||||
|
||||
**AI 기반 문서 자동화 시스템 — GPD 총괄기획실**
|
||||
|
||||
다양한 형식의 자료(PDF·HWP·이미지·Excel 등)를 입력하면, AI가 RAG 파이프라인으로 분석한 뒤
|
||||
선택한 문서 유형(기획서·보고서·발표자료 등)에 맞는 표준 HTML 문서를 자동 생성합니다.
|
||||
생성된 문서는 웹 편집기에서 수정하고, HTML / PDF / HWP로 출력합니다.
|
||||
|
||||
---
|
||||
|
||||
## 🏗 아키텍처 (Architecture)
|
||||
|
||||
### 핵심 흐름
|
||||
|
||||
```
|
||||
자료 입력 (파일/폴더)
|
||||
│
|
||||
▼
|
||||
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 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
|
||||
```
|
||||
|
||||
#### 문서 유형별 생성 → 편집 → 출력
|
||||
|
||||
```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
|
||||
|
||||
A(["📋 RAG 분석 결과"]):::startEnd
|
||||
B{"문서 유형 선택"}:::decision
|
||||
|
||||
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 (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 + 한글 프로그램 필수
|
||||
- 문서 유형: 기획서·보고서만 구현, 발표자료·사용자 등록 유형 미구현
|
||||
- 레거시 잔존: prompts/ 디렉토리, dkdl.py 테스트 코드
|
||||
|
||||
---
|
||||
|
||||
## 📊 코드 규모
|
||||
|
||||
| 영역 | 줄 수 |
|
||||
|------|-------|
|
||||
| Python 전체 | 9,780 |
|
||||
| 프론트엔드 (JS + CSS + HTML) | 3,859 |
|
||||
| **합계** | **~13,600** |
|
||||
|
||||
---
|
||||
|
||||
## 📝 버전 이력
|
||||
|
||||
| 버전 | 핵심 변경 |
|
||||
|------|----------|
|
||||
| v1 | Flask + Claude API 기획서 생성기 |
|
||||
| v2 | 웹 편집기 추가 |
|
||||
| v3 | 9단계 RAG 파이프라인 + HWP 변환 |
|
||||
| **v4** | **코드 모듈화 (handlers 패키지) + 스타일 분석기·HWPX 생성기** |
|
||||
|
||||
---
|
||||
|
||||
## 📝 라이선스
|
||||
|
||||
Private — GPD 내부 사용
|
||||
Reference in New Issue
Block a user