486 lines
24 KiB
Plaintext
486 lines
24 KiB
Plaintext
# 글벗 Light v2.0 — 전체 프로젝트 구조
|
|
|
|
> 작성일: 2025-02-06
|
|
> 기준: app.py + 전체 소스코드 분석 완료
|
|
|
|
---
|
|
|
|
## 1. 프로젝트 개요
|
|
|
|
**글벗**은 HWPX(한글) 문서를 HTML로 변환하고, AI가 내용을 채워 전문 문서를 생성하는 시스템.
|
|
|
|
### 핵심 원칙
|
|
- **HWPX 1:1 재현**: 원본 양식을 그대로 HTML로 변환
|
|
- **하드코딩 제로**: 모든 스타일은 HWPX에서 추출
|
|
- **템플릿 기반**: 양식은 유지, 내용만 AI가 채움
|
|
|
|
---
|
|
|
|
## 2. 전체 아키텍처 (16개 기능)
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ 【 글벗 Light v2.0 】 │
|
|
├──────────────────┬─────────────────────────────┬────────────────────────────┤
|
|
│ │ │ │
|
|
│ 【 INPUT 】 │ 【 PROCESS 】 │ 【 OUTPUT 】 │
|
|
│ 원본 데이터 │ 핵심 엔진 │ 결과물 │
|
|
│ │ │ │
|
|
│ ① 로컬 문서 RAG화 │ ┌─────────────────┐ │ ⑤ 기획서 생성 ✅ │
|
|
│ ✅ 구현완료 │ │ │ │ 1p / 1p+첨부 │
|
|
│ hwp,pdf,ppt │ │ HWPX ↔ HTML │ │ │
|
|
│ → 텍스트 추출 │ │ 변환 엔진 │ │ ⑥ 보고서 생성 ✅ │
|
|
│ │ │ │ │ 표지/목차/본문 │
|
|
│ ② 웹 문서 수집 │ │ ✅ 구현완료 │ │ │
|
|
│ ❌ 미구현 │ │ │ │ ⑦ 발표자료 생성 ⏳ │
|
|
│ │ └────────┬────────┘ │ (준비중) │
|
|
│ ③ HTML 표준화 │ │ │ │
|
|
│ ❓ 미확인 │ ▼ │ ⑧ 신규 문서유형 ✅ │
|
|
│ │ ┌─────────────────┐ │ HWPX 업로드 → 등록 │
|
|
│ ④ 반영 수준 선택 │ │ │ │ │
|
|
│ ❓ 미확인 │ │ 【 EDIT 】 │ │ │
|
|
│ │ │ 편집 엔진 │ │ │
|
|
│ │ │ │ │ │
|
|
│ │ │ ⑨ 웹 편집기 ✅ │ │ │
|
|
│ │ │ ⑩ AI 편집 ✅ │ │ │
|
|
│ │ │ ⑪ 신규템플릿 ✅ │ │ │
|
|
│ │ │ │ │ │
|
|
│ │ └─────────────────┘ │ │
|
|
└──────────────────┴─────────────────────────────┴────────────────────────────┘
|
|
│
|
|
▼
|
|
┌───────────────────────────────┐
|
|
│ 【 EXPORT 】 │
|
|
├───────────────────────────────┤
|
|
│ ⑫ HTML ✅ ⑬ PDF ✅ │
|
|
│ ⑭ HWPX/HWP ✅ ⑮ PPT ❌ │
|
|
└───────────────────────────────┘
|
|
│
|
|
▼
|
|
┌───────────────────────────────┐
|
|
│ 【 SERVER 】 │
|
|
│ ⑯ 서버 업로드/공유 ❌ │
|
|
└───────────────────────────────┘
|
|
```
|
|
|
|
### 기능별 구현 현황
|
|
|
|
| # | 구분 | 기능 | 상태 | 구현 위치 |
|
|
|---|------|------|------|-----------|
|
|
| 1 | INPUT | 로컬 문서 RAG화 | ✅ 완료 | converters/pipeline/* |
|
|
| 2 | INPUT | 웹 문서 수집 | ❌ 미구현 | - |
|
|
| 3 | INPUT | HTML 표준화 | ❓ 미확인 | - |
|
|
| 4 | INPUT | 반영 수준 선택 | ⏳ UI만 존재 | index.html (추후 개발) |
|
|
| 5 | OUTPUT | 기획서 생성 | ✅ 완료 | handlers/briefing/ |
|
|
| 6 | OUTPUT | 보고서 생성 | ✅ 완료 | handlers/report/ |
|
|
| 7 | OUTPUT | 발표자료 생성 | ⏳ 준비중 | config.json (enabled:false) |
|
|
| 8 | OUTPUT | 신규 문서유형 | ✅ 완료 | handlers/doc_type_analyzer |
|
|
| 9 | EDIT | 웹 편집기 | ✅ 완료 | static/js/editor.js |
|
|
| 10 | EDIT | AI 편집 | ✅ 완료 | /refine, /refine-selection |
|
|
| 11 | EDIT | 신규 템플릿 | ✅ 완료 | handlers/template_manager |
|
|
| 12 | EXPORT | HTML | ✅ 완료 | app.py /download/html |
|
|
| 13 | EXPORT | PDF | ✅ 완료 | app.py /download/pdf |
|
|
| 14 | EXPORT | HWPX/HWP | ✅ 완료 | converters/html_to_hwp* |
|
|
| 15 | EXPORT | PPT | ❌ 미구현 | - |
|
|
| 16 | SERVER | 서버 업로드 | ❌ 미구현 | - |
|
|
|
|
---
|
|
|
|
## 3. 폴더 구조 (전체)
|
|
|
|
```
|
|
글벗/
|
|
│
|
|
├── app.py ✅ Flask 메인 (25개 API 엔드포인트)
|
|
│
|
|
├── handlers/ ✅ 【PROCESS】 핵심 처리 모듈
|
|
│ ├── __init__.py
|
|
│ ├── common.py ✅ AI 호출 공통 (call_claude 등)
|
|
│ │
|
|
│ │── 【프로세서 4종】
|
|
│ ├── briefing/ ✅ 기획서 처리
|
|
│ │ ├── processor.py BriefingProcessor
|
|
│ │ └── prompts/
|
|
│ │ ├── step1_extract.txt 구조 추출
|
|
│ │ ├── step1_5_plan.txt 배치 계획
|
|
│ │ └── step2_generate.txt HTML 생성
|
|
│ │
|
|
│ ├── report/ ✅ 보고서 처리
|
|
│ │ ├── processor.py ReportProcessor
|
|
│ │ └── prompts/
|
|
│ │ └── refine_selection.txt 부분 수정
|
|
│ │
|
|
│ ├── template/ ✅ 템플릿 처리 (v3)
|
|
│ │ ├── processor.py TemplateProcessor
|
|
│ │ ├── html_table_template_css.txt
|
|
│ │ └── prompts/
|
|
│ │ └── analyze_template.txt
|
|
│ │
|
|
│ ├── custom_doc_type.py ✅ 사용자 정의 문서 (user_*)
|
|
│ │
|
|
│ │── 【HWPX 분석 파이프라인】
|
|
│ ├── doc_type_analyzer.py ✅ 6단계 SSE 오케스트레이터
|
|
│ ├── doc_template_analyzer.py ✅ tools/ 호출 → template_info
|
|
│ ├── template_manager.py ✅ template.html 생성/저장/로드
|
|
│ ├── style_generator.py ✅ template_info → CSS
|
|
│ ├── semantic_mapper.py ✅ 표 역할 분류
|
|
│ ├── content_analyzer.py ✅ content_prompt.json 생성
|
|
│ │
|
|
│ └── tools/ ✅ HWPX 파싱 도구 (12개)
|
|
│ ├── page_setup.py §7 용지/여백
|
|
│ ├── char_style.py §4 글자 모양 → cpr-*
|
|
│ ├── para_style.py §5 문단 모양 → ppr-*
|
|
│ ├── border_fill.py §2 테두리/배경 → bf-*
|
|
│ ├── table.py §6 표
|
|
│ ├── header_footer.py §8 머리말/꼬리말
|
|
│ ├── content_order.py 본문 순서
|
|
│ ├── font.py §3 글꼴
|
|
│ ├── style_def.py 스타일 정의
|
|
│ ├── numbering.py 번호매기기
|
|
│ ├── image.py 이미지
|
|
│ └── section.py §9 구역
|
|
│
|
|
├── converters/ ✅ 【EXPORT】 변환 모듈
|
|
│ ├── __init__.py
|
|
│ │
|
|
│ │── 【HTML → HWP 변환】
|
|
│ ├── html_to_hwp.py ✅ 일반 문서 → HWP
|
|
│ ├── html_to_hwp_briefing.py ✅ 기획서 → HWP
|
|
│ ├── hwp_style_mapping.py ✅ 스타일 매핑 정의
|
|
│ ├── hwpx_style_injector.py ✅ HWPX 스타일 주입
|
|
│ ├── hwpx_table_injector.py ✅ HWPX 표 주입
|
|
│ ├── style_analyzer.py ✅ HTML 스타일 분석
|
|
│ │
|
|
│ │── 【미사용】
|
|
│ ├── hwpx_generator.py ❌ 미사용 (독립 실행용/개발중)
|
|
│ │
|
|
│ └── pipeline/ ✅ 【INPUT】 RAG 파이프라인
|
|
│ ├── router.py 분기 처리
|
|
│ ├── step1_convert.py 파일 변환 (hwp,pdf,ppt→pdf)
|
|
│ ├── step2_extract.py 텍스트/이미지 추출
|
|
│ ├── step3_domain.py 도메인 분석
|
|
│ ├── step4_chunk.py 청킹
|
|
│ ├── step5_rag.py RAG 검색
|
|
│ ├── step6_corpus.py 코퍼스 구축
|
|
│ ├── step7_index.py 인덱싱
|
|
│ ├── step8_content.py 콘텐츠 생성
|
|
│ └── step9_html.py HTML 생성
|
|
│
|
|
├── domain/ ✅ 도메인 유틸리티
|
|
│ └── hwpx/
|
|
│ ├── hwpx_domain_guide.md HWPX ↔ HTML 매핑 스펙 (§1~§11)
|
|
│ └── hwpx_utils.py 단위 변환 함수
|
|
│
|
|
├── static/ ✅ 【EDIT】 웹 편집기
|
|
│ ├── js/
|
|
│ │ └── editor.js ✅ 편집기 (1208줄)
|
|
│ │ · 폰트/크기/색상/정렬
|
|
│ │ · 굵게/기울임/밑줄/취소선
|
|
│ │ · 표/그림/구분선 삽입
|
|
│ │ · 지능형 정렬 (smartAlign)
|
|
│ │ · 새 페이지 / 전 페이지 이동
|
|
│ │ · Undo/Redo
|
|
│ │
|
|
│ └── css/
|
|
│ └── editor.css ✅ 편집기 스타일 (296줄)
|
|
│
|
|
├── templates/ ✅ UI + 데이터 저장소
|
|
│ ├── index.html ✅ 메인 UI (3765줄)
|
|
│ │
|
|
│ │── 【미사용 - 삭제 가능】
|
|
│ ├── hwp_guide.md ❌ 미사용
|
|
│ ├── hwp_html_defaults.json ❌ 미사용
|
|
│ │
|
|
│ ├── default/doc_types/ ✅ 기본 문서 유형 (3개)
|
|
│ │ ├── briefing/config.json 기획서 ✅
|
|
│ │ ├── report/config.json 보고서 ✅
|
|
│ │ └── presentation/config.json 발표자료 ⏳ (enabled:false)
|
|
│ │
|
|
│ └── user/ ✅ 사용자 정의 저장
|
|
│ ├── doc_types/{type_id}/
|
|
│ │ ├── config.json
|
|
│ │ └── content_prompt.json
|
|
│ └── templates/{tpl_id}/
|
|
│ ├── template.html
|
|
│ ├── style.json
|
|
│ ├── meta.json
|
|
│ └── semantic_map.json
|
|
│
|
|
├── output/ ⚠️ 임시 출력 (.gitignore 권장)
|
|
│ └── assets/*.png
|
|
│
|
|
└── prompts/ ❌ 미사용 (중복 - 삭제 가능)
|
|
├── step1_extract.txt = briefing/prompts/ 와 동일
|
|
├── step1_5_plan.txt
|
|
└── step2_generate.txt
|
|
```
|
|
|
|
---
|
|
|
|
## 4. API 엔드포인트 (25개)
|
|
|
|
### 메인
|
|
| API | 메서드 | 설명 |
|
|
|-----|--------|------|
|
|
| `/` | GET | 메인 페이지 (index.html) |
|
|
| `/health` | GET | 헬스 체크 |
|
|
|
|
### 문서 유형 관리
|
|
| API | 메서드 | 설명 |
|
|
|-----|--------|------|
|
|
| `/api/doc-types` | GET | 문서 유형 목록 |
|
|
| `/api/doc-types` | POST | 문서 유형 저장 |
|
|
| `/api/doc-types/<id>` | DELETE | 문서 유형 삭제 |
|
|
| `/api/doc-types/analyze` | POST | 문서 유형 분석 (단일) |
|
|
| `/api/doc-types/analyze-stream` | POST | 문서 유형 분석 (SSE 스트리밍) |
|
|
| `/api/doc-types/<id>/template` | GET | 템플릿 조회 |
|
|
| `/api/doc-types/<id>/template` | PUT | 템플릿 연결 |
|
|
|
|
### 템플릿 관리
|
|
| API | 메서드 | 설명 |
|
|
|-----|--------|------|
|
|
| `/templates` | GET | 템플릿 목록 |
|
|
| `/api/templates` | GET | 템플릿 목록 (API) |
|
|
| `/api/templates/<id>` | GET | 템플릿 상세 |
|
|
| `/api/templates/<id>` | DELETE | 템플릿 삭제 |
|
|
| `/analyze-template` | POST | HWPX → 템플릿 추출 |
|
|
| `/delete-template/<id>` | DELETE | 템플릿 삭제 (구버전) |
|
|
|
|
### 문서 생성
|
|
| API | 메서드 | 설명 |
|
|
|-----|--------|------|
|
|
| `/generate` | POST | 문서 생성 (briefing/report/template/custom) |
|
|
| `/generate-report` | POST | 보고서 생성 |
|
|
|
|
### 편집 (EDIT)
|
|
| API | 메서드 | 설명 |
|
|
|-----|--------|------|
|
|
| `/refine` | POST | AI 전체 수정 |
|
|
| `/refine-selection` | POST | AI 부분 수정 |
|
|
| `/analyze-styles` | POST | HTML 스타일 분석 |
|
|
|
|
### 다운로드 (EXPORT)
|
|
| API | 메서드 | 설명 |
|
|
|-----|--------|------|
|
|
| `/download/html` | POST | HTML 다운로드 |
|
|
| `/download/pdf` | POST | PDF 다운로드 (weasyprint) |
|
|
| `/export-hwp` | POST | HWP/HWPX 다운로드 |
|
|
|
|
### 기타
|
|
| API | 메서드 | 설명 |
|
|
|-----|--------|------|
|
|
| `/assets/<filename>` | GET | 로컬 에셋 서빙 |
|
|
| `/hwp-script` | GET | HWP 변환 안내 |
|
|
|
|
---
|
|
|
|
## 5. 모듈 연결도
|
|
|
|
```
|
|
app.py (Flask)
|
|
│
|
|
┌──────────┬─────────────────┼─────────────────┬──────────┐
|
|
│ │ │ │ │
|
|
▼ ▼ ▼ ▼ ▼
|
|
┌────────┐ ┌────────┐ ┌──────────┐ ┌────────┐ ┌────────┐
|
|
│briefing│ │ report │ │ template │ │ custom │ │doc_type│
|
|
│Processor│ │Processor│ │Processor │ │DocType │ │Analyzer│
|
|
└───┬────┘ └───┬────┘ └────┬─────┘ └───┬────┘ └───┬────┘
|
|
│ │ │ │ │
|
|
│ ▼ │ │ │
|
|
│ ┌──────────┐ │ │ │
|
|
│ │converters│ │ │ │
|
|
│ │/pipeline │ │ │ │
|
|
│ │ (RAG 9단계)│ │ │ │
|
|
│ └──────────┘ │ │ │
|
|
│ │ │ │
|
|
│ ▼ ▼ ▼
|
|
│ ┌─────────────────────────────────────┐
|
|
│ │ template_manager │
|
|
│ │ ┌─────────────────────────────────┐│
|
|
│ │ │ doc_template_analyzer ││
|
|
│ │ │ └─ tools/* (12개) ││
|
|
│ │ │ └─ domain/hwpx ││
|
|
│ │ ├─────────────────────────────────┤│
|
|
│ │ │ style_generator ││
|
|
│ │ │ semantic_mapper ││
|
|
│ │ │ content_analyzer ││
|
|
│ │ └─────────────────────────────────┘│
|
|
│ └─────────────────────────────────────┘
|
|
│
|
|
│ ┌─────────────────────────────────────────────────────┐
|
|
└───▶│ converters/ (EXPORT) │
|
|
├─────────────────────────────────────────────────────┤
|
|
│ html_to_hwp_briefing ◀── doc_type == 'briefing' │
|
|
│ html_to_hwp ◀── 그 외 │
|
|
│ │ │
|
|
│ ├── hwp_style_mapping │
|
|
│ ├── hwpx_style_injector │
|
|
│ ├── hwpx_table_injector │
|
|
│ └── style_analyzer │
|
|
└─────────────────────────────────────────────────────┘
|
|
|
|
┌─────────────────────────────────────────────┐
|
|
│ static/ (EDIT 모듈) │
|
|
├─────────────────────────────────────────────┤
|
|
│ js/editor.js (1208줄) │
|
|
│ · 포맷 바 (폰트, 크기, 색상, 정렬) │
|
|
│ · 삽입 (표, 그림, 구분선) │
|
|
│ · 페이지 관리 (새페이지, 이동) │
|
|
│ · Undo/Redo │
|
|
│ │
|
|
│ css/editor.css (296줄) │
|
|
│ · 포맷 바 스타일 │
|
|
│ · 편집 모드 하이라이트 │
|
|
└─────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 6. 핵심 파이프라인
|
|
|
|
### Phase A: 문서 유형 등록 (1회)
|
|
```
|
|
HWPX 업로드 + 이름 입력
|
|
│
|
|
▼
|
|
doc_type_analyzer.analyze() [SSE 6단계]
|
|
│
|
|
├─ Step 1: _parse_hwpx() HWPX ZIP 해제
|
|
├─ Step 2: _extract_layout() 레이아웃 추출
|
|
├─ Step 3: _analyze_context() [AI] 맥락 분석
|
|
├─ Step 4: _analyze_structure() [AI] 구조 분석
|
|
├─ Step 5: template_manager.extract_and_save()
|
|
│ ├─ doc_template_analyzer.analyze()
|
|
│ │ └─ tools/* (12개 파싱 도구)
|
|
│ ├─ semantic_mapper.generate()
|
|
│ ├─ style_generator.generate_css()
|
|
│ └─ content_analyzer.generate()
|
|
└─ Step 6: save_doc_type() 저장
|
|
|
|
저장 위치:
|
|
templates/user/doc_types/{type_id}/
|
|
├─ config.json
|
|
└─ content_prompt.json
|
|
templates/user/templates/{tpl_id}/
|
|
├─ template.html
|
|
├─ style.json
|
|
├─ meta.json
|
|
└─ semantic_map.json
|
|
```
|
|
|
|
### Phase B: 문서 생성 (매번)
|
|
```
|
|
내용 입력 + 문서유형 선택
|
|
│
|
|
├─ doc_type == 'briefing'
|
|
│ └─ BriefingProcessor.generate()
|
|
│ Step 1: 구조 추출 [AI]
|
|
│ Step 1.5: 배치 계획 [AI]
|
|
│ Step 2: HTML 생성 [AI]
|
|
│
|
|
├─ doc_type == 'report'
|
|
│ └─ ReportProcessor.generate()
|
|
│ └─ converters/pipeline/router
|
|
│ └─ 9단계 RAG 파이프라인
|
|
│
|
|
├─ doc_type == 'template'
|
|
│ └─ TemplateProcessor.generate()
|
|
│
|
|
└─ doc_type.startswith('user_')
|
|
└─ CustomDocTypeProcessor.generate()
|
|
├─ config.json 로드
|
|
├─ template.html 로드
|
|
├─ content_prompt.json 로드
|
|
├─ [AI] placeholder 채우기
|
|
└─ _fill_template()
|
|
```
|
|
|
|
### Phase C: EXPORT
|
|
```
|
|
HTML 결과물
|
|
│
|
|
├─ /download/html → 그대로 다운로드
|
|
│
|
|
├─ /download/pdf → weasyprint 변환
|
|
│
|
|
└─ /export-hwp
|
|
├─ doc_type == 'briefing'
|
|
│ └─ html_to_hwp_briefing.py
|
|
└─ 그 외
|
|
└─ html_to_hwp.py
|
|
├─ hwp_style_mapping
|
|
├─ hwpx_style_injector
|
|
└─ hwpx_table_injector
|
|
```
|
|
|
|
---
|
|
|
|
## 7. 파일별 사용 현황
|
|
|
|
### 사용 중 (유지)
|
|
| 위치 | 파일 수 | 비고 |
|
|
|------|---------|------|
|
|
| handlers/ | 20개 | 전부 사용 |
|
|
| handlers/tools/ | 12개 | 전부 사용 |
|
|
| converters/ | 9개 | hwpx_generator.py 제외 |
|
|
| converters/pipeline/ | 10개 | 전부 사용 |
|
|
| domain/hwpx/ | 2개 | 전부 사용 |
|
|
| static/ | 2개 | 전부 사용 (EDIT 모듈) |
|
|
| templates/index.html | 1개 | 메인 UI |
|
|
| templates/default/ | 3개 | 기본 문서유형 |
|
|
| templates/user/ | 가변 | 사용자 데이터 |
|
|
|
|
### 미사용 (삭제 가능)
|
|
| 파일 | 이유 |
|
|
|------|------|
|
|
| `converters/hwpx_generator.py` | 어디서도 import 안 됨 |
|
|
| `templates/hwp_guide.md` | 어디서도 참조 안 됨 |
|
|
| `templates/hwp_html_defaults.json` | 어디서도 참조 안 됨 |
|
|
| `prompts/` (루트 폴더) | handlers/briefing/prompts/와 중복 |
|
|
|
|
### .gitignore 권장
|
|
```
|
|
output/
|
|
*/__pycache__/
|
|
*.pyc
|
|
```
|
|
|
|
---
|
|
|
|
## 8. 현재 버그 (3건)
|
|
|
|
### 🔴 버그 #1: 표 누락
|
|
- **위치**: template_manager.py
|
|
- **원인**: content_order의 table_idx가 header/footer 표 포함된 전체 리스트에 매핑
|
|
- **증상**: 본문 표가 사라짐
|
|
|
|
### 🔴 버그 #2: CSS 탈락
|
|
- **위치**: custom_doc_type.py _fill_template()
|
|
- **원인**: `<p><span>` 안에 `<ul>` 삽입 → 브라우저가 구조 깨뜨림
|
|
- **증상**: 개조식 내용에 스타일 미적용
|
|
|
|
### 🔴 버그 #3: 제목 빈칸
|
|
- **위치**: content_analyzer.py
|
|
- **원인**: placeholder 이름 불일치 (TITLE vs TITLE_R1_C2)
|
|
- **증상**: 제목이 채워지지 않음
|
|
|
|
---
|
|
|
|
## 9. 다음 단계
|
|
|
|
### 즉시 수정 (버그 3건)
|
|
1. template_manager.py — 표 인덱스 매핑
|
|
2. custom_doc_type.py — inline context에서 `<ul>` 금지
|
|
3. content_analyzer.py — TITLE placeholder 이름
|
|
|
|
### 미구현 기능
|
|
- ② 웹 문서 수집 (크롤링)
|
|
- ④ 반영 수준 선택 (UI만 존재, 백엔드 미연결)
|
|
- ⑦ 발표자료 생성
|
|
- ⑮ PPT 출력
|
|
- ⑯ 서버 업로드/공유
|
|
|
|
---
|
|
|
|
*이 문서를 읽은 AI/개발자는 버그 수정 또는 미구현 기능 개발부터 시작할 수 있습니다.* |