fletimageanalysis/docs/developer_guide.md

개발자 가이드

PDF 도면 분석기의 개발 및 확장을 위한 가이드입니다.

목차

1. 프로젝트 구조
2. 개발 환경 설정
3. 모듈 구조
4. API 참조
5. 확장 가이드
6. 기여하기

프로젝트 구조

fletimageanalysis/
├── main.py                 # 메인 애플리케이션 진입점
├── config.py               # 설정 관리 모듈
├── pdf_processor.py        # PDF 처리 및 이미지 변환
├── gemini_analyzer.py      # Gemini API 연동
├── ui_components.py        # UI 컴포넌트 정의
├── utils.py                # 유틸리티 함수들
├── setup.py                # 설치 스크립트
├── test_project.py         # 테스트 스크립트
├── requirements.txt        # Python 의존성
├── .env.example            # 환경 변수 템플릿
├── README.md               # 프로젝트 개요
├── LICENSE                 # 라이선스
├── project_plan.md         # 프로젝트 계획
├── uploads/                # 업로드된 파일 저장
├── results/                # 분석 결과 저장
├── assets/                 # 정적 자산
└── docs/                   # 문서
    ├── user_guide.md       # 사용자 가이드
    └── developer_guide.md  # 개발자 가이드

개발 환경 설정

필수 요구사항

• Python 3.9+
• pip 최신 버전
• Google Gemini API 키

개발 환경 구성

1. 저장소 클론

git clone <repository-url>
cd fletimageanalysis

2. 가상 환경 생성

python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

3. 개발 의존성 설치

pip install -r requirements.txt
pip install black flake8 pytest  # 개발 도구

4. 환경 설정

cp .env.example .env
# .env 파일에서 GEMINI_API_KEY 설정

코드 스타일

프로젝트는 다음 코딩 스타일을 따릅니다:

• 포맷터: Black
• 린터: Flake8
• 라인 길이: 88자
• 문서화: Google 스타일 docstring

# 코드 포맷팅
black .

# 코드 검사
flake8 .

# 테스트 실행
python test_project.py

모듈 구조

1. config.py - 설정 관리

class Config:
    """애플리케이션 설정 클래스"""

    # 기본 설정
    APP_TITLE = "PDF 도면 분석기"
    APP_VERSION = "1.0.0"

    # API 설정
    GEMINI_API_KEY = os.getenv("GEMINI_API_KEY")
    GEMINI_MODEL = "gemini-2.5-flash"

    # 파일 설정
    MAX_FILE_SIZE_MB = 50
    ALLOWED_EXTENSIONS = ["pdf"]

주요 기능:

• 환경 변수 로드
• 설정 유효성 검사
• 경로 관리

2. pdf_processor.py - PDF 처리

class PDFProcessor:
    """PDF 파일 처리 클래스"""

    def validate_pdf_file(self, file_path: str) -> bool:
        """PDF 파일 유효성 검사"""

    def convert_pdf_page_to_image(self, file_path: str, page_number: int) -> Image:
        """PDF 페이지를 PIL Image로 변환"""

    def pdf_page_to_base64(self, file_path: str, page_number: int) -> str:
        """PDF 페이지를 base64 문자열로 변환"""

주요 기능:

• PDF 파일 검증
• 페이지별 이미지 변환
• Base64 인코딩
• 메타데이터 추출

3. gemini_analyzer.py - API 연동

class GeminiAnalyzer:
    """Gemini API 이미지 분석 클래스"""

    def analyze_image_from_base64(self, base64_data: str, prompt: str) -> str:
        """Base64 이미지 데이터 분석"""

    def analyze_pdf_images(self, base64_images: list, prompt: str) -> dict:
        """여러 PDF 페이지 일괄 분석"""

주요 기능:

• API 클라이언트 관리
• 이미지 분석 요청
• 응답 처리
• 오류 처리

4. ui_components.py - UI 컴포넌트

class UIComponents:
    """UI 컴포넌트 클래스"""

    @staticmethod
    def create_app_bar() -> ft.AppBar:
        """애플리케이션 상단 바 생성"""

    @staticmethod
    def create_file_upload_section() -> ft.Container:
        """파일 업로드 섹션 생성"""

주요 기능:

• 재사용 가능한 UI 컴포넌트
• Material Design 스타일
• 이벤트 핸들러 정의

5. utils.py - 유틸리티

class FileUtils:
    """파일 관련 유틸리티"""

class AnalysisResultSaver:
    """분석 결과 저장"""

class DateTimeUtils:
    """날짜/시간 유틸리티"""

주요 기능:

• 파일 조작
• 결과 저장
• 텍스트 처리
• 검증 함수

API 참조

PDFProcessor

validate_pdf_file(file_path: str) -> bool

PDF 파일의 유효성을 검사합니다.

매개변수:

• file_path: PDF 파일 경로

반환값:

• bool: 유효한 PDF인지 여부

get_pdf_info(file_path: str) -> dict

PDF 파일의 메타데이터를 조회합니다.

반환값:

{
    'page_count': int,
    'metadata': dict,
    'file_size': int,
    'filename': str
}

GeminiAnalyzer

analyze_image_from_base64(base64_data: str, prompt: str) -> str

Base64 이미지를 분석합니다.

매개변수:

• base64_data: Base64로 인코딩된 이미지
• prompt: 분석 요청 텍스트

반환값:

• str: 분석 결과 텍스트

AnalysisResultSaver

save_analysis_results(pdf_filename, analysis_results, pdf_info, analysis_settings) -> str

분석 결과를 텍스트 파일로 저장합니다.

반환값:

• str: 저장된 파일 경로

확장 가이드

새로운 분석 모드 추가

1. UI 업데이트

# ui_components.py에서 새 라디오 버튼 추가
ft.Radio(value="new_mode", label="새로운 모드")

2. 분석 로직 추가

# main.py의 run_analysis()에서 프롬프트 설정
elif self.analysis_mode.value == "new_mode":
    prompt = "새로운 분석 모드의 프롬프트"

새로운 파일 형식 지원

1. 설정 업데이트

# config.py
ALLOWED_EXTENSIONS = ["pdf", "docx"]  # 새 형식 추가

2. 처리기 확장

# 새로운 처리 클래스 구현
class DOCXProcessor:
    def validate_docx_file(self, file_path: str) -> bool:
        # DOCX 검증 로직
        pass

새로운 AI 모델 지원

1. 설정 추가

# config.py
ALTERNATIVE_MODEL = "claude-3-5-sonnet"

2. 분석기 확장

class ClaudeAnalyzer:
    def analyze_image(self, image_data: str) -> str:
        # Claude API 연동 로직
        pass

UI 컴포넌트 확장

1. 새 컴포넌트 추가

# ui_components.py
@staticmethod
def create_advanced_settings_section() -> ft.Container:
    """고급 설정 섹션"""
    return ft.Container(...)

2. 메인 UI에 통합

# main.py의 build_ui()에서 새 컴포넌트 추가

기여하기

기여 프로세스

1. 이슈 생성

   • 새 기능이나 버그 리포트
   • 명확한 설명과 예시 제공

2. 브랜치 생성

git checkout -b feature/new-feature
git checkout -b bugfix/fix-issue

3. 개발 및 테스트

# 개발 후 테스트 실행
python test_project.py
black .
flake8 .

4. 커밋 및 푸시

git add .
git commit -m "feat: add new feature"
git push origin feature/new-feature

5. Pull Request 생성
   • 명확한 제목과 설명
   • 변경사항 설명
   • 테스트 결과 포함

커밋 메시지 규칙

• feat: 새로운 기능
• fix: 버그 수정
• docs: 문서 업데이트
• style: 코드 스타일 변경
• refactor: 코드 리팩토링
• test: 테스트 추가/수정
• chore: 기타 작업

코드 리뷰 체크리스트

• [ ] 코드 스타일 준수 (Black, Flake8)
• [ ] 테스트 통과
• [ ] 문서화 완료
• [ ] 타입 힌트 추가
• [ ] 에러 처리 적절
• [ ] 성능 고려
• [ ] 보안 검토

디버깅

로깅 설정

import logging

# 개발 시 상세 로깅
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

일반적인 디버깅 시나리오

1. API 연결 문제

# gemini_analyzer.py에서 연결 테스트
if not analyzer.validate_api_connection():
    logger.error("API 연결 실패")

2. 파일 처리 오류

# pdf_processor.py에서 상세 오류 정보
try:
    doc = fitz.open(file_path)
except Exception as e:
    logger.error(f"PDF 열기 실패: {e}")

3. UI 업데이트 문제

# main.py에서 스레드 안전 업데이트
def safe_ui_update():
    def update():
        # UI 업데이트 코드
        self.page.update()

    self.page.run_thread(update)

성능 최적화

메모리 관리

1. 대용량 PDF 처리

# 페이지별 순차 처리
for page_num in range(total_pages):
    # 메모리 해제
    del previous_image
    gc.collect()

2. 이미지 크기 최적화

# 적절한 줌 레벨 선택
zoom = min(2.0, target_width / pdf_width)

API 호출 최적화

1. 요청 배치 처리

# 여러 페이지를 하나의 요청으로 처리
combined_prompt = f"다음 {len(images)}개 이미지를 분석..."

2. 캐싱 구현

# 분석 결과 캐시
@lru_cache(maxsize=100)
def cached_analysis(image_hash: str, prompt: str) -> str:
    return analyzer.analyze_image(image_data, prompt)

---

더 자세한 정보나 질문이 있으시면 GitHub Issues에서 문의해 주세요.