diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..07c85e2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,177 @@ +# CONTRIBUTING.md + +SnapFig 프로젝트에 기여해 주셔서 감사합니다! 🙏 +이 가이드는 이슈 등록, 기능 제안, 버그 수정, PR 제출 등 기여 과정을 안내합니다. + +--- + +## 📋 목차 + +1. [기여 전 읽어주세요](#🤔-기여-전-읽어주세요) +2. [이슈 등록하기](#🐞-이슈-등록하기) +3. [새 기능 제안하기](#🎉-새-기능-제안하기) +4. [개발 환경 설정](#🛠️-개발-환경-설정) +5. [브랜치 네이밍](#🌿-브랜치-네이밍) +6. [커밋 메시지 형식](#📝-커밋-메시지-형식) +7. [Pull Request(PR) 절차](#🔀-pull-requestpr-절차) +8. [코드 스타일 & 테스트](#💅-코드-스타일--테스트) +9. [환경 변수 및 빌드 설정](#⚙️-환경-변수-및-빌드-설정) +10. [리뷰 & 머지](#✅-리뷰--머지) +11. [문의 및 연락](#📞-문의-및-연락) + +--- + +## 🤔 기여 전 읽어주세요 + +- `main` 브랜치는 프로덕션용으로, 직접 커밋을 금지합니다. +- 모든 개발은 `develop` 브랜치에서 시작합니다. +- 기능 개발, 버그 수정 전 반드시 이 가이드를 숙지해 주세요. + +--- + +## 🐞 이슈 등록하기 + +1. 저장소 우측 상단의 **“Issues”** 탭 클릭 +2. **Bug Report** 템플릿 선택 +3. 문제 상황 재현 방법, 기대 동작, 실제 동작, 스크린샷(또는 로그) 포함 + +--- + +## 🎉 새 기능 제안하기 + +1. **Feature Request** 템플릿 선택 +2. 제안하려는 기능 설명, 목적, 참고 자료(모바일 앱 흐름도, 목업 등) 포함 +3. 가능하다면 구현 아이디어나 간단한 설계도 제안 + +--- + +## 🛠 개발 환경 설정 + +```bash +# 저장소 클론 +git clone https://github.com/CommitBang/Frontend.git +cd Frontend + +# Flutter 패키지 설치 +flutter pub get +``` + +- Flutter SDK 3.7.2 이상, Dart SDK 3.0 이상 권장 +- IDE: Android Studio, VS Code 등 Flutter 지원 에디터 + +--- + +## 🌿 브랜치 네이밍 + +- feature/<설명>: 새로운 기능 개발 +- bugfix/<설명>: 버그 수정 +- hotfix/<설명>: 긴급 수정 + +``` +예시 +feature/ocr-text-highlighting +bugfix/pdf-render-error +``` + +--- + +## 📝 커밋 메시지 형식 + +```text +<타입>: <설명> +[선택사항: 본문] +``` + +- type: feat, fix, docs, style, refactor, test, chore +- scope: 변경한 모듈 또는 기능 영역 (예: pdf_viewer, ocr_service) +- 예시 + +```text +feat(pdf_viewer): 주석–Figure 팝업 UI 구현 + +- Figure tap 시 모달 팝업으로 상세 이미지 표시 +- 관련 테스트 케이스 추가 +``` + +--- + +## 🔀 Pull Request(PR) 절차 + +1. 이슈(버그/기능) 등록 또는 기존 이슈 선택 +2. develop 브랜치에서 본인 작업 브랜치 생성 +3. 작업 완료 후 커밋 & 푸시 +4. GitHub에서 New Pull Request 클릭 +5. PR 템플릿 작성 +6. 리뷰어 지정 후 리뷰 요청 + +--- + +## 💅 코드 스타일 & 테스트 + +### 코드 포멧팅 + +```bash +flutter format +``` + +### 정적 분석 + +```bash +flutter analyze +``` + +### 테스트 실행 + +- 단위 테스트 + +```bash +flutter test test/unit +``` + +- 위젯 테스트 + +```bash +flutter test test/widget +``` + +- 통합 테스트 + +```bash +flutter test integration_test/ +``` + +### 모든 변경 사항에 대해 테스트 추가 및 기존 테스트 통과 확인 + +--- + +## ⚙️ 환경 변수 및 빌드 설정 + +1. 프로젝트 루트에 .env 파일 생성 + +```env +OCR_BASE_URL= +OPENAI_API_KEY= +GOOGLE_GEMINI_KEY= +``` + +2. Isar 모델 코드 생성 + +```bash +flutter packages pub run build_runner build --delete-conflicting-outputs + +``` + +3. OCR 서버는 POST /api/v1/analyze 엔드포인트를 제공해야 합니다. +4. + +--- + +## ✅ 리뷰 & 머지 + +- PR은 최소 2명 이상의 리뷰어 승인 필요 +- 리뷰 코멘트 반영 후 develop 브랜치에 머지 +- main 브랜치로 머지는 릴리즈 담당자가 수행 + +--- + +## 📞 문의 및 연락 \ No newline at end of file diff --git a/LICENSE b/LICENSE index 261eeb9..49ee4f5 100644 --- a/LICENSE +++ b/LICENSE @@ -1,3 +1,25 @@ +MIT License + +Copyright (c) 2025 CommitBang + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the “Software”), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. +======= Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ diff --git a/README.md b/README.md index 0f57cdd..293a665 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,142 @@ [![iOS](https://img.shields.io/badge/iOS-000000?style=for-the-badge&logo=ios&logoColor=white)](https://developer.apple.com/ios/) [![Android](https://img.shields.io/badge/Android-3DDC84?style=for-the-badge&logo=android&logoColor=white)](https://developer.android.com) -> 🎓 대학생을 위한 스마트 PDF 학습 도구 +## 📖 프로젝트 소개 -Snapfig는 OCR 기술과 AI를 활용하여 대학생들이 전공서적을 더욱 효율적으로 학습할 수 있도록 지원하는 크로스 플랫폼 모바일 애플리케이션입니다. +SnapFig은 대학생들이 전공 서적을 보다 효율적으로 학습할 수 있도록 돕는 크로스플랫폼 모바일 애플리케이션입니다. +OCR 기반 텍스트 추출, PDF 문서 구조 자동 분석, 주석–Figure 매핑 & 팝업 기능을 제공하여 +사용자가 중요한 내용과 그림을 빠르게 찾아보고 관리할 수 있게 합니다. + +--- + +## 목차 + +- [주요 기능](#-주요-기능) +- [기술 스택](#-기술-스택) +- [시작하기](#-시작하기) +- [환경 설정](#-환경-설정) +- [프로젝트 구조](#프로젝트-구조) + - [주요 디렉토리 설명](#주요-디렉토리-설명) +- [사용 방법](#-사용-방법) +- [팀원 구성](#-팀원-구성) +- [프로젝트 계획서](#-프로젝트-계획서) +- [Branch 전략](#branch-전략) + - [브랜치 구조](#브랜치-구조) + - [작업 흐름](#작업-흐름) + - [커밋 메시지 규칙](#커밋-메시지-규칙) +- [기여 방법](#-기여-방법) +- [라이선스](#-라이선스) + +--- + +## 🚀 주요 기능 + +### 🔍 OCR 기반 텍스트 추출 + +- **Figure 및 참조 인식** + 문서 내 Figure와 관련 참조를 자동으로 연결 + +### 🤖 AI 기반 Figure 분석 + +- **다중 AI 프로바이더 지원** + OpenAI GPT-4, Google Gemini 연동 +- **인터랙티브 Figure 분석** + 터치로 Figure 선택 시 AI 분석 제공 +- **실시간 질의응답** + Figure에 대한 질문과 AI 답변 + +--- + +## 🛠️ 기술 스택 + +### Frontend + +- **Framework**: Flutter 3.7.2+ +- **Language**: Dart 3.0+ +- **Architecture**: MVVM (Model-View-ViewModel) +- **State Management**: ChangeNotifier, InheritedWidget +- **Database**: Isar (NoSQL local database) + +### 핵심 의존성 + +```yaml +dependencies: + flutter: sdk + pdfrx: ^1.1.28 + isar: ^3.1.0+1 + file_picker: ^10.1.9 + http: ^1.4.0 + shared_preferences: ^2.5.3 + path_provider: ^2.1.5 +``` + +--- + +## 🚀 시작하기 + +### 필수 요구사항 + +- Flutter SDK 3.7.2 이상 +- Dart SDK 3.0 이상 +- Android Studio 또는 VS Code +- iOS 개발 시 Xcode + +### 설치 방법 + +1. **저장소 클론** + +```bash +git clone https://github.com/CommitBang/Frontend.git +cd Frontend +``` + +2. **의존성 설치** + +```bash +flutter pub get +``` + +3. **코드 생성 (Isar 데이터베이스)** + +```bash +flutter packages pub run build_runner build +``` + +4. **환경 변수 설정** + 프로젝트 루트에 `.env` 파일 생성: + +```env +OCR_BASE_URL=your_ocr_server_url +``` + +5. **앱 실행** + +```bash +flutter run +``` + +--- + +## ⚙️ 환경 설정 + +### OCR 서비스 설정 + +OCR 기능을 사용하려면 백엔드 OCR 서버가 필요합니다: + +1. OCR 서버 URL을 `.env` 파일에 설정 +2. 서버는 다음 엔드포인트를 제공해야 합니다: + +- `POST /api/v1/analyze`: PDF 분석 + +### AI 기능 설정 + +1. 앱 내 설정에서 AI 프로바이더 구성 +2. 지원되는 프로바이더: + +- **OpenAI**: API 키 필요 ([platform.openai.com](https://platform.openai.com/api-keys)) +- **Google Gemini**: API 키 필요 ([console.cloud.google.com](https://console.cloud.google.com)) + +--- ## ✨ 주요 기능 @@ -85,7 +218,7 @@ flutter run ### OCR 서비스 설정 OCR 기능을 사용하려면 백엔드 OCR 서버가 필요합니다: 1. OCR 서버 URL을 `.env` 파일에 설정 -2. 서버는 다음 엔드포인트를 제공해야 합니다: +2. 서버는 다음 엔드포인트를 제공해야 합니다: (https://github.com/CommitBang/PDFRecognitionAPI) - `POST /api/v1/analyze`: PDF 분석 ### AI 기능 설정 @@ -98,6 +231,140 @@ OCR 기능을 사용하려면 백엔드 OCR 서버가 필요합니다: ``` lib/ +├── core/ +│ ├── constants/ +│ │ ├── app_constants.dart +│ │ └── theme_constants.dart +│ └── theme/ +│ ├── app_theme.dart +│ ├── color_scheme.dart +│ ├── text_theme.dart +│ └── theme.dart +│ +├── features/ +│ ├── home/ +│ │ ├── screens/ +│ │ │ ├── documents_widget.dart +│ │ │ ├── home_widget.dart +│ │ │ └── recent_widget.dart +│ │ └── widgets/ +│ │ ├── add_document_button.dart +│ │ ├── empty_files_icon.dart +│ │ ├── home_components.dart +│ │ ├── pdf_card.dart +│ │ ├── pdf_list_item.dart +│ │ └── show_rename_dialog.dart +│ │ +│ └── pdf_viewer/ +│ ├── models/ +│ │ ├── figure_info.dart +│ │ ├── ocr_text_block.dart +│ │ ├── pdf_document_model.dart ← 이동됨 +│ │ ├── pdf_layout_model.dart ← 이동됨 +│ │ └── pdf_page_model.dart ← 이동됨 +│ ├── screens/ +│ │ └── pdf_viewer_screen.dart +│ └── widgets/ +│ ├── figure_list_panel.dart +│ ├── ocr_overlay_painter.dart +│ └── pdf_page_viewer.dart +│ +├── shared/ +│ ├── services/ +│ │ ├── ocr_core/ +│ │ │ ├── ocr_core.dart +│ │ │ ├── ocr_provider.dart +│ │ │ └── ocr_result.dart +│ │ │ +│ │ ├── pdf_core/ +│ │ │ ├── models/ +│ │ │ │ ├── implement/ +│ │ │ │ │ ├── layout_impl.dart +│ │ │ │ │ ├── layout_impl.g.dart +│ │ │ │ │ ├── page_impl.dart +│ │ │ │ │ ├── page_impl.g.dart +│ │ │ │ │ ├── pdf_impl.dart +│ │ │ │ │ └── pdf_impl.g.dart +│ │ │ │ ├── interface/ +│ │ │ │ │ ├── base_layout.dart +│ │ │ │ │ ├── base_page.dart +│ │ │ │ │ └── base_pdf.dart +│ │ │ │ └── models.dart +│ │ │ ├── provider/ +│ │ │ │ ├── inherited_pdf_provider_widget.dart +│ │ │ │ ├── pdf_provider.dart +│ │ │ │ └── pdf_provider_impl.dart +│ │ │ └── pdf_core.dart +│ │ │ +│ │ ├── ocr_service.dart +│ │ └── pdf_service.dart +│ │ +│ └── widgets/ +│ └── document_card.dart +│ +└── main.dart + +test/ +├── unit/ +├── widget/ +└── integration/ + +assets/ +├── images/ +├── fonts/ +├── icons/ +└── sample.pdf/ + +``` + +### 주요 디렉토리 설명 + +| 디렉토리 | 하위 디렉토리 | 설명 | +|---------------|------------------------|------------------------| +| **core/** | constants/ | 앱 전체에서 사용되는 상수 정의 | +| | theme/ | 앱의 디자인 시스템 및 테마 관련 코드 | +| | utils/ | 재사용 가능한 유틸리티 함수들 | +| **features/** | auth/, home/, profile/ | 각 기능별로 독립적인 모듈 구성 | +| | */screens/ | 각 기능의 화면 구현 | +| | */widgets/ | 각 기능의 위젯 구현 | +| | */models/ | 각 기능의 데이터 모델 | +| **shared/** | widgets/ | 여러 기능에서 공통으로 사용되는 컴포넌트 | +| | services/ | 재사용 가능한 서비스 | +| **test/** | unit/ | 단위 테스트 | +| | widget/ | 위젯 테스트 | +| | integration/ | 통합 테스트 | +| **assets/** | images/ | 이미지 리소스 | +| | fonts/ | 폰트 파일 | +| | icons/ | 아이콘 리소스 | + +--- + +## 🎯 사용 방법 + +### 1. PDF 문서 추가 + +- 홈 화면에서 "새 문서 추가" 버튼 클릭 +- 기기에서 PDF 파일 선택 +- 자동으로 OCR 처리 시작 + +### 2. Figure 분석 + +- PDF 뷰어에서 Figure 영역 터치 +- "Ask AI" 버튼으로 AI 분석 요청 +- 드래그 가능한 채팅 창에서 질의응답 + +### 3. 문서 관리 + +- 최근 문서에서 빠른 접근 +- 문서 이름 변경 및 삭제 +- 읽던 페이지 자동 저장 + +--- + +## Branch 전략 + +### 브랜치 구조 +======= ├── core/ # 앱 전체 공통 요소 │ ├── constants/ # 상수 정의 │ └── theme/ # 테마 및 디자인 시스템 @@ -112,7 +379,6 @@ lib/ │ ├── pdf_core/ # PDF 데이터 관리 │ └── navigation_service/ # 내비게이션 관리 └── widgets/ # 재사용 가능한 위젯 -``` ### 주요 서비스 @@ -150,19 +416,6 @@ flutter test flutter test integration_test/ ``` -## 🤝 기여하기 -1. Fork the Project -2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`) -3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`) -4. Push to the Branch (`git push origin feature/AmazingFeature`) -5. Open a Pull Request - -### 개발 가이드라인 -- XP(eXtreme Programming) 방법론 준수 -- 페어 프로그래밍 권장 -- 테스트 주도 개발(TDD) 실천 -- 코드 리뷰 필수 - ### 브랜치 전략 - `main`: 프로덕션 브랜치 - `develop`: 개발 브랜치 @@ -183,12 +436,24 @@ flutter test integration_test/ | chore | 빌드 업무 수정 | chore: 패키지 버전 업데이트 | #### 커밋 메시지 형식 - ``` <타입>: <설명> [선택사항: 본문] ``` +## 🤝 기여 방법 + +1. **Fork & Clone** 저장소 +2. **브랜치 네이밍**: `feature/*`, `bugfix/*` +3. **커밋 메시지**: 위의 커밋메시지 규칙 확인 +4. **PR 전 확인**: +- [CONTRIBUTING.md](./CONTRIBUTING.md) +- `.github/ISSUE_TEMPLATE/` 템플릿 사용 + +5. **리뷰 프로세스**: 최소 두 명의 리뷰어 승인 후 Merge + +--- + ## 📄 라이선스 -이 프로젝트는 APACH 라이선스 하에 배포됩니다. 자세한 내용은 [LICENSE](LICENSE) 파일을 참조하세요. \ No newline at end of file +이 프로젝트는 MIT 라이선스 하에 배포됩니다. 자세한 내용은 [LICENSE](LICENSE) 파일을 참조하세요. diff --git a/docs/api-reference.md b/docs/api-reference.md new file mode 100644 index 0000000..36e06ac --- /dev/null +++ b/docs/api-reference.md @@ -0,0 +1,3 @@ +백엔드(또는 AI 서버) 주요 REST/GraphQL 엔드포인트 정리 + +요청·응답 예시, 인증 방식, 에러 코드 표 \ No newline at end of file diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..7b90002 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,3 @@ +전체 시스템 구조 다이어그램 (클라이언트 ↔ 서버, 모듈 간 데이터 플로우) + +주요 컴포넌트 설명 (PDF 처리, OCR, AI 분석, DB 등) \ No newline at end of file diff --git a/docs/design-decisions.md b/docs/design-decisions.md new file mode 100644 index 0000000..de45361 --- /dev/null +++ b/docs/design-decisions.md @@ -0,0 +1,3 @@ +주요 설계 선택 배경 (왜 MVVM? 왜 Isar? 왜 FastAPI?) + +대안 검토 및 Trade-off 요약 \ No newline at end of file diff --git a/docs/development-process.md b/docs/development-process.md new file mode 100644 index 0000000..8b77a86 --- /dev/null +++ b/docs/development-process.md @@ -0,0 +1,29 @@ +# 개발 프로세스 + +## 개발 방법론 + +- **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% \ No newline at end of file diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..9c4d715 --- /dev/null +++ b/docs/faq.md @@ -0,0 +1 @@ +자주 묻는 질문과 답변 (설치 오류, 권한 설정, 빌드 시 이슈 등) \ No newline at end of file diff --git a/docs/features.md b/docs/features.md new file mode 100644 index 0000000..12c5c6e --- /dev/null +++ b/docs/features.md @@ -0,0 +1,25 @@ +# 주요 기능 + +1. **OCR 기반 텍스트 추출** + - 스캔된 PDF 문서에서 텍스트 블록 검출 + - 페이지별, 단락별 텍스트 데이터 자동 저장 + +2. **챕터 자동 인식 & 목차 생성** + - PDF Layout 분석을 통해 헤더 및 페이지 번호 추출 + - 자동 목차 트리 구조 생성 및 사이드바 네비게이션 제공 + +3. **주석–Figure 자동 매핑 & 팝업** + - 문서 내 주석(예: "Figure 3.1") 참조 정보를 파싱 + - 관련 Figure 이미지를 팝업 뷰로 표시하여 즉시 조회 가능 + +4. **AI 기반 인터랙티브 Figure 분석** + - 터치하여 선택한 Figure를 OpenAI GPT-4, Google Gemini로 분석 + - Figure 설명 생성 및 실시간 Q&A 지원 + +5. **학습 관리 기능** + - 즐겨찾기, 하이라이트, 메모 저장 + - 읽던 페이지 자동 복원 및 최근 문서 리스트 제공 + +6. **다크 모드 & 접근성 지원** + - 다크/라이트 테마 전환 + - 텍스트 크기 조절, VoiceOver/TalkBack 최적화 \ No newline at end of file diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 0000000..f5c7def --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1 @@ +프로젝트 내 용어 정의 (e.g. “Figure 매핑”, “OCR Overlay” 등) \ No newline at end of file diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..b2fd649 --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1 @@ +향후 계획 및 로드맵 \ No newline at end of file diff --git a/docs/tech-stack.md b/docs/tech-stack.md new file mode 100644 index 0000000..4e54b21 --- /dev/null +++ b/docs/tech-stack.md @@ -0,0 +1,23 @@ +# 기술 스택 + +## Front-end + +- **Framework**: Flutter 3.7.2+ (Dart 3.0+) +- **Architecture**: MVVM (ChangeNotifier, InheritedWidget) +- **UI**: Material Design, Custom Themes +- **PDF 라이브러리**: pdfrx +- **OCR**: Google ML Kit, Tesseract (pytesseract) +- **State Management**: Provider 패턴 +- **Local DB**: Isar (NoSQL) + +## Back-end + +### 주요 패키지 + +```yaml +file_picker: ^10.1.9 +shared_preferences: ^2.5.3 +path_provider: ^2.1.5 +vector_math: ^2.1.0 +http: ^1.4.0 +dio: ^4.0.0 \ No newline at end of file