📦 Initialize Geulbeot structure and merge Prompts & test projects

2026-03-05 11:32:29 +09:00
commit 555a954458
687 changed files with 205247 additions and 0 deletions
--- a/Code/geulbeot_9th/README.md
+++ b/Code/geulbeot_9th/README.md
@@ -0,0 +1,389 @@
+# 글벗 (Geulbeot) v9.0
+
+**표 매칭 안정화 + 인라인 아이콘 감지 + 프론트 외부 참조**
+
+다양한 형식의 자료(PDF·HWP·이미지·Excel 등)를 입력하면, AI가 RAG 파이프라인으로 분석한 뒤
+선택한 문서 유형(기획서·보고서·발표자료 등)에 맞는 표준 HTML 문서를 자동 생성합니다.
+생성된 문서는 웹 편집기에서 수정하고, HTML / PDF / HWP로 출력합니다.
+
+v9에서는 v8의 문서 유형 등록 시스템을 안정화했습니다.
+template.html 조립 시 표 매칭을 순차 커서 방식으로 개선하고,
+HWPX 인라인 아이콘(treatAsChar)을 감지하여 텍스트와 합치는 처리를 추가했습니다.
+프론트엔드는 CSS·JS를 외부 파일 참조로 전환하기 시작했습니다.
+
+---
+
+## 🏗 아키텍처 (Architecture)
+
+### 핵심 흐름
+
+```
+자료 입력 (파일/폴더)
+    │
+    ▼
+작성 방식 선택 ─── 형식만 변경 / 내용 재구성 / 신규 작성
+    │
+    ▼
+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
+  - HWPX 템플릿 관리: 추출·저장·교체·삭제
+  - HWP 변환: 하이브리드 방식
+  - PDF 변환: WeasyPrint 기반
+
+### 2. Frontend (순수 JavaScript)
+
+- **Features**:
+  - 웹 WYSIWYG 편집기 — 생성된 문서 직접 수정
+  - 작성 방식 선택 탭: 형식만 변경 / 내용 재구성 / 신규 작성
+  - 문서 유형 선택 UI: 기본 3종 + 사용자 등록 유형 동적 표시
+  - 템플릿 관리 UI: 사이드바 목록·선택·삭제, 요소별 체크박스
+  - HTML / PDF / HWP 다운로드
+  - CSS·JS 외부 파일 참조 전환 시작 (v9)
+
+### 3. 변환 엔진 (Converters)
+
+- **RAG 파이프라인**: 9단계 — 파일 형식 통일 → 텍스트·이미지 추출 → 도메인 분석 → 의미 단위 청킹 → RAG 임베딩 → 코퍼스 구축 → FAISS 인덱싱 → 콘텐츠 생성 → HTML 조립
+- **분량 자동 판단**: 5,000자 기준
+- **HWP 변환 (하이브리드)**: HTML 분석 → pyhwpx 변환 → HWPX 스타일 주입 → 표 열 너비 수정
+
+### 4. HWPX 추출 도구 12종
+
+`handlers/tools/` — HWPX XML에서 코드 기반 추출: page_setup, font, char_style, para_style, border_fill, table, header_footer, section, style_def, numbering, image, content_order
+
+### 5. 문서 유형 분석·등록
+
+HWPX 업로드 → DocTemplateAnalyzer (12종 도구 추출) → SemanticMapper (의미 판별) → StyleGenerator (CSS 생성) → ContentAnalyzer (placeholder 분석) → DocTypeAnalyzer (AI 맥락) → TemplateManager (template.html 조립) → CustomDocType (문서 생성)
+
+### 6. 주요 시나리오 (Core Scenarios)
+
+1. **기획서 생성**: RAG 분석 후 Claude API가 구조 추출 → 배치 → 글벗 표준 HTML 생성
+2. **보고서 생성**: RAG 파이프라인 → Gemini API가 다페이지 HTML 보고서 생성
+3. **사용자 정의 문서 생성**: 등록된 유형의 template.html + content_prompt.json 기반, 사용자 입력 정리·재구성
+4. **문서 유형 등록**: HWPX 업로드 → 자동 분석 → config.json + template.html + semantic_map.json + style.json 저장
+5. **AI 편집**: 웹 편집기에서 전체·부분 수정
+6. **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
+```
+
+#### 전체 워크플로우 (v9 시점)
+
+```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
+
+    A(["📂 자료 입력"]):::startEnd
+
+    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["📋 템플릿 + 시맨틱 맵\nstyle.json\nsemantic_map.json\ncontent_prompt.json"]:::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 --> W
+    W --> W1 & W2 & W3
+    W1 & W2 & W3 --> 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
+```
+
+---
+
+## 🔄 v8 → v9 변경사항
+
+| 영역 | v8 | v9 |
+|------|------|------|
+| 표 매칭 | table_idx 기반 (오프셋 오류 가능) | **순차 커서 방식** — table_idx 의존 제거, title_table 명시 제외 |
+| 인라인 아이콘 | 이미지로 처리 | **treatAsChar=1 감지** → 텍스트와 합쳐 paragraph로 처리 |
+| 프론트 구조 | CSS·JS 인라인 | **외부 파일 참조 시작** — editor.css link + editor.js script 태그 추가 |
+| template_manager | v5.3 | v5.4 — 순차 커서 + exclude_indices 개선 |
+| content_order | 이미지만 분류 | + `is_inline_icon` 필드, paragraph 합침 분기 |
+
+---
+
+## 🗺 상태 및 로드맵 (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 v5.4, content_order 개선, 독립 저장 (🔧 기본 구현 · 현재 버전)
+- **Phase 7**: 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-v9.git
+cd geulbeot-v9
+
+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_9th/
+├── app.py                              # Flask 웹 서버 — API 라우팅
+├── api_config.py                       # .env 환경변수 로더
+│
+├── domain/hwpx/                        # 도메인 지식
+│   ├── hwpx_domain_guide.md            #   HWPX 명세서 (§1~§11)
+│   └── hwpx_utils.py                  #   단위 변환
+│
+├── handlers/                           # 비즈니스 로직
+│   ├── common.py                       #   Claude API 호출
+│   ├── briefing/                       #   기획서 처리
+│   ├── report/                         #   보고서 처리
+│   ├── template/                       #   템플릿 기본 관리
+│   ├── doc_type_analyzer.py           #   문서 유형 AI 분석
+│   ├── doc_template_analyzer.py       #   HWPX → 12종 도구 추출
+│   ├── semantic_mapper.py             #   요소 의미 판별
+│   ├── style_generator.py            #   추출값 → CSS 생성
+│   ├── content_analyzer.py           #   placeholder 분석
+│   ├── template_manager.py           #   ★ v5.4 — 순차 커서 표 매칭
+│   ├── custom_doc_type.py            #   사용자 정의 유형 문서 생성
+│   └── tools/                          #   HWPX 추출 도구 12종
+│       ├── content_order.py           #   ★ v9 — 인라인 아이콘 감지
+│       └── (page_setup, font, char_style, para_style, border_fill,
+│            table, header_footer, section, style_def, numbering, image)
+│
+├── converters/                         # 변환 엔진
+│   ├── pipeline/                       #   9단계 RAG 파이프라인
+│   └── (style_analyzer, hwpx_generator, hwp_style_mapping,
+│        hwpx_style_injector, hwpx_table_injector,
+│        html_to_hwp, html_to_hwp_briefing)
+│
+├── templates/
+│   ├── default/doc_types/             #   기본 유형 (briefing·report·presentation)
+│   ├── user/                           #   사용자 등록 데이터
+│   │   ├── doc_types/{type_id}/       #     config.json + content_prompt.json
+│   │   └── templates/{tpl_id}/        #     meta·style·semantic_map·template.html
+│   └── index.html                     #   ★ v9 — 외부 CSS·JS 참조 시작
+│
+├── static/
+│   ├── js/editor.js
+│   └── css/editor.css
+│
+├── .env / .env.sample
+├── .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 + 한글 프로그램 필수
+- 발표자료: config.json만 존재, 실제 생성 미구현
+- 사용자 유형 생성: template.html 기반 채움 (AI 창작 아닌 정리·재구성)
+- 프론트 외부 참조: editor.css·editor.js만 분리, 나머지는 index.html 인라인
+
+---
+
+## 📊 코드 규모
+
+| 영역 | 줄 수 |
+|------|-------|
+| Python 전체 | 18,940 (+23) |
+| 프론트엔드 (JS + CSS + HTML) | 5,267 |
+| **합계** | **~24,200** |
+
+---
+
+## 📝 버전 이력
+
+| 버전 | 핵심 변경 |
+|------|----------|
+| v1 | Flask + Claude API 기획서 생성기 |
+| v2 | 웹 편집기 추가 |
+| v3 | 9단계 RAG 파이프라인 + HWP 변환 |
+| v4 | 코드 모듈화 (handlers 패키지) + 스타일 분석기·HWPX 생성기 |
+| v5 | HWPX 스타일 주입 + 표 열 너비 정밀 변환 |
+| v6 | HWPX 템플릿 분석·저장·관리 |
+| v7 | UI 고도화 — 작성 방식·문서 유형·템플릿 관리 UI |
+| v8 | 문서 유형 분석·등록 + HWPX 추출 도구 12종 + 템플릿 고도화 |
+| **v9** | **표 매칭 안정화 + 인라인 아이콘 감지 + 프론트 외부 참조** |
+
+---
+
+## 📝 라이선스
+
+Private — GPD 내부 사용