Files

453 lines
18 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 글벗 (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 내부 사용