# 글벗 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/` | DELETE | 문서 유형 삭제 | | `/api/doc-types/analyze` | POST | 문서 유형 분석 (단일) | | `/api/doc-types/analyze-stream` | POST | 문서 유형 분석 (SSE 스트리밍) | | `/api/doc-types//template` | GET | 템플릿 조회 | | `/api/doc-types//template` | PUT | 템플릿 연결 | ### 템플릿 관리 | API | 메서드 | 설명 | |-----|--------|------| | `/templates` | GET | 템플릿 목록 | | `/api/templates` | GET | 템플릿 목록 (API) | | `/api/templates/` | GET | 템플릿 상세 | | `/api/templates/` | DELETE | 템플릿 삭제 | | `/analyze-template` | POST | HWPX → 템플릿 추출 | | `/delete-template/` | 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/` | 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() - **원인**: `

` 안에 `

    ` 삽입 → 브라우저가 구조 깨뜨림 - **증상**: 개조식 내용에 스타일 미적용 ### 🔴 버그 #3: 제목 빈칸 - **위치**: content_analyzer.py - **원인**: placeholder 이름 불일치 (TITLE vs TITLE_R1_C2) - **증상**: 제목이 채워지지 않음 --- ## 9. 다음 단계 ### 즉시 수정 (버그 3건) 1. template_manager.py — 표 인덱스 매핑 2. custom_doc_type.py — inline context에서 `
      ` 금지 3. content_analyzer.py — TITLE placeholder 이름 ### 미구현 기능 - ② 웹 문서 수집 (크롤링) - ④ 반영 수준 선택 (UI만 존재, 백엔드 미연결) - ⑦ 발표자료 생성 - ⑮ PPT 출력 - ⑯ 서버 업로드/공유 --- *이 문서를 읽은 AI/개발자는 버그 수정 또는 미구현 기능 개발부터 시작할 수 있습니다.*