From a26dc9d19a8d740532a6431ae243dadb6c41f7a1 Mon Sep 17 00:00:00 2001 From: JuhwanLee99 Date: Sat, 14 Jun 2025 00:47:48 +0900 Subject: [PATCH 1/3] =?UTF-8?q?docs:=20=EB=AC=B8=EC=84=9C=ED=99=94(readme,?= =?UTF-8?q?=20contributing,=20license)=20=EC=B4=88=EC=95=88=20=EC=9E=91?= =?UTF-8?q?=EC=84=B1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTRIBUTING.md | 119 +++++++++++++++++++++++ LICENSE | 21 ++++ README.md | 248 +++++++++++++++++++++++++++++++++++------------- 3 files changed, 321 insertions(+), 67 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..030355c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,119 @@ +# CONTRIBUTING.md + +SnapFig 프로젝트에 기여해 주셔서 감사합니다! 🙏 +이 가이드는 이슈 등록, 기능 제안, 버그 수정, PR 제출 등 기여 과정을 안내합니다. + +--- + +## 📋 목차 + +1. [기여 전 읽어주세요](#-기여-전-읽어주세요) +2. [이슈 등록하기](#-이슈-등록하기) +3. [새 기능 제안하기](#-새-기능-제안하기) +4. [개발 환경 설정](#-개발-환경-설정) +5. [브랜치 네이밍](#-브랜치-네이밍) +6. [커밋 메시지 형식](#-커밋-메시지-형식) +7. [Pull Request(PR) 절차](#-pull-requestpr-절차) +8. [코드 스타일 & 테스트](#-코드-스타일--테스트) +9. [리뷰 & 머지](#-리뷰--머지) +10. [문의 및 연락](#-문의-및-연락) + +--- + +## 🤔 기여 전 읽어주세요 + +- 본 저장소의 **`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 및 Dart 최신 버전 권장 +- 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. 리뷰어 지정 후 리뷰 요청 + +--- + +## 💅 코드 스타일 & 테스트 + +--- + +## ✅ 리뷰 & 머지 + +- PR은 최소 2명 이상의 리뷰어 승인 필요 +- 리뷰 코멘트 반영 후 develop 브랜치에 머지 +- main 브랜치로 머지는 릴리즈 담당자가 수행 + +--- + +## 📞 문의 및 연락 \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..ade98d5 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +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. \ No newline at end of file diff --git a/README.md b/README.md index 68767e4..7ea4ea3 100644 --- a/README.md +++ b/README.md @@ -6,89 +6,146 @@ [![Tests](https://img.shields.io/badge/Tests-Passing-brightgreen?style=for-the-badge)](https://github.com/CommitBang/Frontend/actions) [![Coverage](https://img.shields.io/badge/Coverage-85%25-brightgreen?style=for-the-badge)](https://github.com/CommitBang/Frontend/actions) +## 📖 프로젝트 소개 + +SnapFig은 대학생들이 전공 서적을 보다 효율적으로 학습할 수 있도록 돕는 크로스플랫폼 모바일 애플리케이션입니다. +OCR 기반 텍스트 추출, PDF 문서 구조 자동 분석, 주석–Figure 매핑 & 팝업 기능을 제공하여 +사용자가 중요한 내용과 그림을 빠르게 찾아보고 관리할 수 있게 합니다. + +--- + ## 목차 +- [주요 기능](#-주요-기능) +- [기술 스택](#-기술-스택) +- [설치 및 실행](#-설치-및-실행) - [프로젝트 구조](#프로젝트-구조) - [주요 디렉토리 설명](#주요-디렉토리-설명) +- [팀원 구성](#-팀원-구성) +- [프로젝트 계획서](#-프로젝트-계획서) - [Branch 전략](#branch-전략) - [브랜치 구조](#브랜치-구조) - [작업 흐름](#작업-흐름) - [커밋 메시지 규칙](#커밋-메시지-규칙) +- [기여 방법](#-기여-방법) +- [라이선스](#-라이선스) + +--- + +## 🚀 주요 기능 + +- **OCR 기반 텍스트 추출** + 스캔된 PDF에서도 텍스트를 정확히 인식하여 디지털 텍스트로 변환 +- **챕터 자동 인식 & 목차 생성** + 문서 구조를 분석해 자동으로 목차를 구성하고 챕터별 이동 지원 +- **주석–Figure 자동 매핑 & 팝업** + 본문 주석을 탭하면 관련 Figure 팝업으로 즉시 확인 +- **학습 관리** + 즐겨찾기, 하이라이트, 메모 기능으로 중요 내용을 저장·관리 + +--- + +## 🛠 기술 스택 + +- **Flutter & Dart** +- **PDF 처리**: pdfrx +- **파일 선택**: file_picker +- **경로 관리**: path +- **수학 연산**: vector_math +- **상태 관리**: Provider 패턴 +- **CI/CD**: GitHub Actions + +--- + +## 📱 설치 및 실행 + +```bash +# 1. 저장소 클론 +git clone https://github.com/CommitBang/Frontend.git +cd Frontend + +# 2. Flutter 패키지 설치 +flutter pub get + +# 3. 앱 실행 +flutter run +``` ## 프로젝트 구조 ``` + lib/ ├── core/ -│ ├── constants/ -│ │ ├── app_constants.dart -│ │ └── theme_constants.dart -│ └── theme/ -│ ├── app_theme.dart -│ ├── color_scheme.dart -│ ├── text_theme.dart -│ └── theme.dart +│ ├── 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 +│ ├── 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 +│ ├── 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 @@ -103,7 +160,6 @@ assets/ ├── icons/ └── sample.pdf/ - ``` ### 주요 디렉토리 설명 @@ -126,6 +182,50 @@ assets/ | | fonts/ | 폰트 파일 | | | icons/ | 아이콘 리소스 | +## 👥 팀원 구성 + +| 이름 | 역할 | 주요 기술 스택 | +|-----|-------------------------------|-----------------------------| +| 박철오 | QA 및 리뷰어, Back-end | Python, Java, Data Science | +| 차현준 | 문서 담당자, Back-end | Java, Python, Spring Boot | +| 이주환 | 문서 담당자, Front-end | Flutter, Dart, pdfrx | +| 이재호 | 프로젝트 매니저, QA 및 리뷰어, Front-end | iOS, SwiftUI, C++, Embedded | + +## 📄 프로젝트 계획서 + +### 1. 프로젝트 개요 및 목적 + +- **목적**: 전공 서적의 복잡한 PDF 문서에서 핵심 텍스트·Figure를 자동 추출하여 + 빠르고 효율적인 학습 경험 제공 + +### 2. 주요 산출물 + +- 크로스플랫폼 Flutter 앱 +- 반응형 UI/UX 디자인 +- 주석–Figure 매핑 알고리즘 및 팝업 UI +- 챕터 구조 자동 인식 및 목차 생성 모듈 +- OCR 엔진 통합 및 텍스트 기반 설명 생성 API + +### 3. 조직 구조 + +| 이름 | 역할 | 기술 스택 | +|-----|-------------------------------|-----------------------------| +| 이재호 | 프로젝트 매니저, QA 및 리뷰어, Front-end | C++, Embedded, SwiftUI, iOS | +| 박철오 | QA 및 리뷰어, Back-end | Data Science, Java, Python | +| 차현준 | 문서 담당자, Back-end | Java, Python, Spring Boot | +| 이주환 | 문서 담당자, Front-end | Flutter, Java, Python | + +### 4. 일정 및 WBS 요약 + +| 단계 | 기간 | 주요 작업 | +|------------|--------------------|------------------------------------| +| 요구사항 분석 | 2025-04-29 ~ 05-04 | 기능 요구사항 정의 및 문서화 | +| 시스템 설계 | 2025-05-05 ~ 05-09 | API 설계, DB 스키마 설계, UI 플로우 차트 작성 | +| 개발 (백엔드) | 2025-05-03 ~ 05-09 | OCR 모듈, 챕터 인식, 텍스트 처리 API 개발 | +| 개발 (프론트엔드) | 2025-05-07 ~ 05-19 | Flutter 앱 초기 구조, PDF 뷰어 & 팝업 UI 구현 | +| 통합 및 테스트 | 2025-05-20 ~ 05-25 | 단위/통합 테스트, 디바이스 테스트 | +| 배포 및 문서화 | 2025-05-24 ~ 05-28 | 앱 스토어 패키징, 사용자 매뉴얼 작성 + ## Branch 전략 ### 브랜치 구조 @@ -160,6 +260,20 @@ assets/ #### 커밋 메시지 형식 ``` + <타입>: <설명> [선택사항: 본문] -``` \ No newline at end of file + +``` + +## 🤝 기여 방법 + +1. **Fork & Clone** 저장소 +2. **브랜치 네이밍**: `feature/*`, `bugfix/*` +3. **커밋 메시지**: `type(scope): 설명` +4. **PR 전 확인**: + +- [CONTRIBUTING.md](./CONTRIBUTING.md) +- `.github/ISSUE_TEMPLATE/` 템플릿 사용 + +5. **리뷰 프로세스**: 최소 두 명의 리뷰어 승인 후 Merge \ No newline at end of file From d9bdd168e262301649d61508f566d5b4e648316c Mon Sep 17 00:00:00 2001 From: JuhwanLee99 Date: Sat, 14 Jun 2025 01:24:27 +0900 Subject: [PATCH 2/3] =?UTF-8?q?docs:=20=EB=AC=B8=EC=84=9C=ED=99=94(readme,?= =?UTF-8?q?=20contributing)=20=EB=82=B4=EC=9A=A9=20=EC=88=98=EC=A0=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTRIBUTING.md | 86 ++++++++++++++++++++++++----- README.md | 144 ++++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 194 insertions(+), 36 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 030355c..07c85e2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,24 +7,25 @@ SnapFig 프로젝트에 기여해 주셔서 감사합니다! 🙏 ## 📋 목차 -1. [기여 전 읽어주세요](#-기여-전-읽어주세요) -2. [이슈 등록하기](#-이슈-등록하기) -3. [새 기능 제안하기](#-새-기능-제안하기) -4. [개발 환경 설정](#-개발-환경-설정) -5. [브랜치 네이밍](#-브랜치-네이밍) -6. [커밋 메시지 형식](#-커밋-메시지-형식) -7. [Pull Request(PR) 절차](#-pull-requestpr-절차) -8. [코드 스타일 & 테스트](#-코드-스타일--테스트) -9. [리뷰 & 머지](#-리뷰--머지) -10. [문의 및 연락](#-문의-및-연락) +1. [기여 전 읽어주세요](#🤔-기여-전-읽어주세요) +2. [이슈 등록하기](#🐞-이슈-등록하기) +3. [새 기능 제안하기](#🎉-새-기능-제안하기) +4. [개발 환경 설정](#🛠️-개발-환경-설정) +5. [브랜치 네이밍](#🌿-브랜치-네이밍) +6. [커밋 메시지 형식](#📝-커밋-메시지-형식) +7. [Pull Request(PR) 절차](#🔀-pull-requestpr-절차) +8. [코드 스타일 & 테스트](#💅-코드-스타일--테스트) +9. [환경 변수 및 빌드 설정](#⚙️-환경-변수-및-빌드-설정) +10. [리뷰 & 머지](#✅-리뷰--머지) +11. [문의 및 연락](#📞-문의-및-연락) --- ## 🤔 기여 전 읽어주세요 -- 본 저장소의 **`main`** 브랜치는 프로덕션용으로, 직접 커밋 금지 -- 모든 개발은 **`develop`** 브랜치에서 시작합니다 -- 기능 개발, 버그 수정 등 기여 전 이 가이드를 반드시 숙지해 주세요 +- `main` 브랜치는 프로덕션용으로, 직접 커밋을 금지합니다. +- 모든 개발은 `develop` 브랜치에서 시작합니다. +- 기능 개발, 버그 수정 전 반드시 이 가이드를 숙지해 주세요. --- @@ -55,7 +56,7 @@ cd Frontend flutter pub get ``` -- Flutter SDK 및 Dart 최신 버전 권장 +- Flutter SDK 3.7.2 이상, Dart SDK 3.0 이상 권장 - IDE: Android Studio, VS Code 등 Flutter 지원 에디터 --- @@ -83,6 +84,7 @@ bugfix/pdf-render-error - type: feat, fix, docs, style, refactor, test, chore - scope: 변경한 모듈 또는 기능 영역 (예: pdf_viewer, ocr_service) +- 예시 ```text feat(pdf_viewer): 주석–Figure 팝업 UI 구현 @@ -106,6 +108,62 @@ feat(pdf_viewer): 주석–Figure 팝업 UI 구현 ## 💅 코드 스타일 & 테스트 +### 코드 포멧팅 + +```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. + --- ## ✅ 리뷰 & 머지 diff --git a/README.md b/README.md index 7ea4ea3..fe1955f 100644 --- a/README.md +++ b/README.md @@ -18,9 +18,11 @@ OCR 기반 텍스트 추출, PDF 문서 구조 자동 분석, 주석–Figure - [주요 기능](#-주요-기능) - [기술 스택](#-기술-스택) -- [설치 및 실행](#-설치-및-실행) +- [시작하기](#-시작하기) +- [환경 설정](#-환경-설정) - [프로젝트 구조](#프로젝트-구조) - [주요 디렉토리 설명](#주요-디렉토리-설명) +- [사용 방법](#-사용-방법) - [팀원 구성](#-팀원-구성) - [프로젝트 계획서](#-프로젝트-계획서) - [Branch 전략](#branch-전략) @@ -34,43 +36,113 @@ OCR 기반 텍스트 추출, PDF 문서 구조 자동 분석, 주석–Figure ## 🚀 주요 기능 -- **OCR 기반 텍스트 추출** - 스캔된 PDF에서도 텍스트를 정확히 인식하여 디지털 텍스트로 변환 -- **챕터 자동 인식 & 목차 생성** - 문서 구조를 분석해 자동으로 목차를 구성하고 챕터별 이동 지원 -- **주석–Figure 자동 매핑 & 팝업** - 본문 주석을 탭하면 관련 Figure 팝업으로 즉시 확인 -- **학습 관리** - 즐겨찾기, 하이라이트, 메모 기능으로 중요 내용을 저장·관리 +### 🔍 OCR 기반 텍스트 추출 + +- **Figure 및 참조 인식** + 문서 내 Figure와 관련 참조를 자동으로 연결 + +### 🤖 AI 기반 Figure 분석 + +- **다중 AI 프로바이더 지원** + OpenAI GPT-4, Google Gemini 연동 +- **인터랙티브 Figure 분석** + 터치로 Figure 선택 시 AI 분석 제공 +- **실시간 질의응답** + Figure에 대한 질문과 AI 답변 --- -## 🛠 기술 스택 +## 🛠️ 기술 스택 + +### Frontend -- **Flutter & Dart** -- **PDF 처리**: pdfrx -- **파일 선택**: file_picker -- **경로 관리**: path -- **수학 연산**: vector_math -- **상태 관리**: Provider 패턴 -- **CI/CD**: GitHub Actions +- **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 -# 1. 저장소 클론 git clone https://github.com/CommitBang/Frontend.git cd Frontend +``` + +2. **의존성 설치** -# 2. Flutter 패키지 설치 +```bash flutter pub get +``` + +3. **코드 생성 (Isar 데이터베이스)** + +```bash +flutter packages pub run build_runner build +``` -# 3. 앱 실행 +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)) + +--- + ## 프로젝트 구조 ``` @@ -182,6 +254,30 @@ assets/ | | fonts/ | 폰트 파일 | | | icons/ | 아이콘 리소스 | +--- + +## 🎯 사용 방법 + +### 1. PDF 문서 추가 + +- 홈 화면에서 "새 문서 추가" 버튼 클릭 +- 기기에서 PDF 파일 선택 +- 자동으로 OCR 처리 시작 + +### 2. Figure 분석 + +- PDF 뷰어에서 Figure 영역 터치 +- "Ask AI" 버튼으로 AI 분석 요청 +- 드래그 가능한 채팅 창에서 질의응답 + +### 3. 문서 관리 + +- 최근 문서에서 빠른 접근 +- 문서 이름 변경 및 삭제 +- 읽던 페이지 자동 저장 + +--- + ## 👥 팀원 구성 | 이름 | 역할 | 주요 기술 스택 | @@ -276,4 +372,8 @@ assets/ - [CONTRIBUTING.md](./CONTRIBUTING.md) - `.github/ISSUE_TEMPLATE/` 템플릿 사용 -5. **리뷰 프로세스**: 최소 두 명의 리뷰어 승인 후 Merge \ No newline at end of file +5. **리뷰 프로세스**: 최소 두 명의 리뷰어 승인 후 Merge + +--- + +## 📄 라이선스 \ No newline at end of file From ad204c31a327a1c9f85800908556219cc862af0a Mon Sep 17 00:00:00 2001 From: JuhwanLee99 Date: Sat, 14 Jun 2025 01:44:46 +0900 Subject: [PATCH 3/3] =?UTF-8?q?docs:=20=EB=AC=B8=EC=84=9C=ED=99=94(wiki)?= =?UTF-8?q?=20=EB=82=B4=EC=9A=A9=20=EC=B4=88=EC=95=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/api-reference.md | 3 +++ docs/architecture.md | 3 +++ docs/design-decisions.md | 3 +++ docs/development-process.md | 29 +++++++++++++++++++++++++++++ docs/faq.md | 1 + docs/features.md | 25 +++++++++++++++++++++++++ docs/glossary.md | 1 + docs/roadmap.md | 1 + docs/tech-stack.md | 23 +++++++++++++++++++++++ 9 files changed, 89 insertions(+) create mode 100644 docs/api-reference.md create mode 100644 docs/architecture.md create mode 100644 docs/design-decisions.md create mode 100644 docs/development-process.md create mode 100644 docs/faq.md create mode 100644 docs/features.md create mode 100644 docs/glossary.md create mode 100644 docs/roadmap.md create mode 100644 docs/tech-stack.md 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