Developer Guide

프로젝트 구조

• Clean Architecture & Feature-First 패턴을 적용하여 확장성과 유지보수성을 확보했습니다.

  • lib/: 메인 소스 코드 (앱 진입점 및 기능별 모듈)
  • test/ · integration_test/: 단위·위젯·통합 테스트 코드
  • assets/: 이미지·아이콘·폰트·샘플 PDF 등 리소스
  • android/, ios/: 플랫폼별 네이티브 코드
  • docs/: 설계·가이드 문서

• lib/ 상세 구조

  • main.dart: 앱 실행 진입점
  • core/: 전역 상수, 테마, 유틸리티 함수 등 공통 요소
  • features/: 기능별 모듈
    • home/, pdf_viewer/, settings/ 등
    • 각 모듈은 models/ · screens/ · widgets/ 폴더로 구성
  • shared/: 재사용 가능한 서비스·위젯
    • services/: AI, OCR, PDF 처리, 내비게이션 등 비즈니스 로직
    • widgets/: 문서 카드 등 공통 UI 컴포넌트

• 테스트 구조

  • test/unit/, test/widget/, test/integration/로 기능별 테스트 구분
  • integration_test/에서 실제 PDF·OCR 프로바이더 통합 검증

• 데이터 흐름 (MVVM)

View (Widget)
    ↕️
ViewModel (Provider/ChangeNotifier)
    ↕️
Model (Service/Repository)
    ↕️
Data Source (API/Database)

코딩 컨벤션

• 커밋 메시지: type(scope): 설명
• 브랜치: feature/*, bugfix/*, hotfix/*
• Dart 스타일: flutter format, flutter analyze

파일 명명 규칙

• Screen: *_screen.dart (예: pdf_viewer_screen.dart)
• Widget: *_widget.dart 또는 기능명 (예: pdf_card.dart)
• Model: *_model.dart (예: document_model.dart)
• Service: *_service.dart (예: ai_service.dart)
• Provider: *_provider.dart (예: pdf_provider.dart)

클래스 명명 규칙

• Screen: *Screen (예: PDFViewerScreen)
• Widget: *Widget 또는 기능명 (예: PDFCard)
• Model: *Model (예: DocumentModel)
• Service: *Service (예: AIService)
• Provider: *Provider (예: PDFProvider)

디렉토리 구조 원칙

1. 기능별 분리: 각 기능은 독립적인 폴더로 관리
2. 계층별 분리: models, screens, widgets로 계층 분리
3. 공통 요소 분리: shared 폴더에서 재사용 가능한 요소 관리
4. 테스트 구조 일치: lib 구조와 동일한 test 구조 유지

빌드 스크립트

• 모델 코드 생성: build_runner
• 린트 & 포맷: flutter analyze / flutter format

테스트 실행

• 단위 테스트: flutter test test/unit
• 위젯 테스트: flutter test test/widget
• 통합 테스트: flutter test integration_test/

개발 프로세스

개발 방법론

• Agile (XP): 2주 스프린트, 데일리 스탠드업, 페어 프로그래밍
• 공동 소유권: 모든 코드에 팀원 모두가 기여 가능

브랜치 전략

• main: 프로덕션 코드
• develop: 통합 개발 브랜치
• feature/*: 기능 개발
• bugfix/*: 버그 수정
• hotfix/*: 긴급 수정

CI/CD 파이프라인

1. GitHub Actions
   • Push 시 develop 브랜치 빌드 & 테스트 자동 실행
   • PR 생성 시 lint, format, unit/widget 테스트 수행
2. Docker: 백엔드 컨테이너 이미지 자동 빌드
3. 배포: main 브랜치 merge 시 도커 허브 및 서버 배포 트리거

코드 리뷰 & 품질 관리

• PR 리뷰: 최소 2명 승인 후 merge
• Lint: flutter analyze, flake8
• Format: flutter format, black
• 테스트 커버리지: 최소 80%