diff --git a/LICENSE b/LICENSE index c390652..1a9337c 100644 --- a/LICENSE +++ b/LICENSE @@ -1,201 +1,25 @@ - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [2025] [CommitBang] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. +The MIT License (MIT) +===================== + +Copyright © `` `` + +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. diff --git a/README.md b/README.md index 26ea0cb..fd470d3 100644 --- a/README.md +++ b/README.md @@ -1,485 +1,242 @@ -# Snapfig Frontend +# SnapFig 📚✨ [![Flutter](https://img.shields.io/badge/Flutter-02569B?style=for-the-badge&logo=flutter&logoColor=white)](https://flutter.dev) [![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) +[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) -## 📖 프로젝트 소개 - -SnapFig은 대학생들이 전공 서적을 보다 효율적으로 학습할 수 있도록 돕는 크로스플랫폼 모바일 애플리케이션입니다. -OCR 기반 텍스트 추출, PDF 문서 구조 자동 분석, 주석–Figure 매핑 & 팝업 기능을 제공하여 -사용자가 중요한 내용과 그림을 빠르게 찾아보고 관리할 수 있게 합니다. +> **대학생을 위한 스마트 전공서적 학습 도우미** +> OCR과 AI를 활용해 전공서적의 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) +## 🎯 SnapFig이 해결하는 문제 -### 핵심 의존성 +**전공서적 학습의 어려움** +- 📖 복잡한 Figure와 텍스트 간의 연관성 파악이 어려움 +- 🔍 중요한 그림과 설명을 찾기 위해 페이지를 계속 넘나들어야 함 +- ❓ Figure에 대한 추가 설명이나 질문이 있어도 즉시 답을 얻기 어려움 -```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 -``` +**SnapFig의 해결책** +- 🤖 **AI 기반 Figure 분석**: 터치 한 번으로 Figure에 대한 상세한 설명 제공 +- 🔗 **스마트 Figure 매핑**: OCR로 자동 인식된 Figure와 참조 텍스트를 연결 +- 💬 **실시간 질의응답**: Figure에 대해 궁금한 점을 AI에게 바로 질문 --- -## 🚀 시작하기 +## ✨ 주요 기능 -### 필수 요구사항 +### 📱 메인 화면 - 문서 관리 +메인 화면 -- Flutter SDK 3.7.2 이상 -- Dart SDK 3.0 이상 -- Android Studio 또는 VS Code -- iOS 개발 시 Xcode +- **간편한 PDF 추가**: 기기에서 PDF 파일을 선택하면 자동으로 OCR 처리 -### 설치 방법 +### 📚 최근 문서 - 학습 이력 관리 +최근 문서 화면 -1. **저장소 클론** +### 🔗 Figure 매핑 - 스마트 연결 +Figure 매핑 기능 -```bash -git clone https://github.com/CommitBang/Frontend.git -cd Frontend -``` +- **자동 Figure 인식**: OCR 기술로 문서 내 모든 Figure 자동 탐지 +- **참조 텍스트 연결**: "Figure 1.2", "그림 3-4" 등의 참조를 자동으로 해당 Figure와 연결 +- **시각적 하이라이트**: 선택한 Figure와 관련된 텍스트를 시각적으로 강조 표시 -2. **의존성 설치** +### 🤖 AI 어시스턴트 - 실시간 학습 도우미 +AI 어시스턴트 -```bash -flutter pub get -``` - -3. **코드 생성 (Isar 데이터베이스)** +- **다중 AI 프로바이더**: OpenAI GPT-4, Google Gemini 지원 +- **드래그 가능한 채팅창**: 화면을 가리지 않도록 자유롭게 위치 조정 가능 -```bash -flutter packages pub run build_runner build -``` +### 💡 Figure 질의응답 - 심화 학습 +Figure 질의응답 -4. **환경 변수 설정** - 프로젝트 루트에 `.env` 파일 생성: - -```env -OCR_BASE_URL=your_ocr_server_url -``` - -5. **앱 실행** - -```bash -flutter run -``` +- **터치 기반 선택**: Figure 영역을 터치하면 즉시 AI 분석 시작 +- **추가 질문 가능**: "이 그래프에서 x축은 무엇을 의미하나요?" 등 구체적 질문 --- -## ⚙️ 환경 설정 - -### 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)) +## 🏗️ 아키텍처 + +SnapFig은 **Clean Architecture**와 **MVVM 패턴**을 기반으로 설계되어 확장성과 유지보수성을 보장합니다. + +### 📐 전체 아키텍처 구조 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Presentation Layer │ +│ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────┐ │ +│ │ Home Screen │ │ PDF Viewer │ │ Settings │ │ +│ │ (MVVM) │ │ Screen (MVVM) │ │ Screen │ │ +│ └─────────────────┘ └─────────────────┘ └──────────────┘ │ +└─────────────────────────────────────────────────────────────┘ + │ +┌─────────────────────────────────────────────────────────────┐ +│ Business Logic Layer │ +│ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────┐ │ +│ │ PDF Service │ │ OCR Service │ │ AI Service │ │ +│ │ (Provider) │ │ (Provider) │ │ (Provider) │ │ +│ └─────────────────┘ └─────────────────┘ └──────────────┘ │ +└─────────────────────────────────────────────────────────────┘ + │ +┌─────────────────────────────────────────────────────────────┐ +│ Data Layer │ +│ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────┐ │ +│ │ Isar DB │ │ HTTP Client │ │ File System │ │ +│ │ (Local) │ │ (Remote) │ │ (Cache) │ │ +│ └─────────────────┘ └─────────────────┘ └──────────────┘ │ +└─────────────────────────────────────────────────────────────┘ +``` + +### 🔧 핵심 아키텍처 패턴 + +#### **1. MVVM (Model-View-ViewModel)** +- **View**: Flutter Widgets (UI 컴포넌트) +- **ViewModel**: ChangeNotifier 기반 상태 관리 +- **Model**: 데이터 모델 및 비즈니스 로직 + +#### **2. Provider Pattern** +- **PDFProvider**: PDF 문서 상태 및 OCR 처리 관리 +- **AIProvider**: AI 서비스 통합 및 대화 상태 관리 +- **NavigationProvider**: 앱 내 네비게이션 중앙 관리 + +#### **3. Repository Pattern** +- **Local Repository**: Isar 데이터베이스를 통한 로컬 데이터 관리 +- **Remote Repository**: HTTP 클라이언트를 통한 외부 API 통신 +- **Cache Repository**: 파일 시스템 기반 캐시 관리 + +### 📁 모듈별 책임 + +| 모듈 | 책임 | 주요 컴포넌트 | +|------|------|---------------| +| **Core** | 앱 전체 공통 요소 | Constants, Theme, Utils | +| **Features** | 기능별 독립 모듈 | Screens, Widgets, Models | +| **Shared** | 공통 서비스 및 위젯 | Services, Widgets | +| **Data** | 데이터 접근 및 관리 | Repositories, Data Sources | --- -## ✨ 주요 기능 - -### 🔍 OCR 기반 텍스트 추출 - -- **Figure 및 참조 인식**: 문서 내 Figure와 관련 참조를 자동으로 연결 - -### 🤖 AI 기반 Figure 분석 - -- **다중 AI 프로바이더 지원**: OpenAI GPT-4, Google Gemini 연동 -- **인터랙티브 Figure 분석**: 터치로 Figure 선택 시 AI 분석 제공 -- **실시간 질의응답**: Figure에 대한 질문과 AI 답변 - -## 🛠️ 기술 스택 - -### Frontend - -- **Framework**: Flutter 3.7.2+ -- **Architecture**: MVVM (Model-View-ViewModel) -- **State Management**: ChangeNotifier, InheritedWidget -- **Database**: Isar (NoSQL local database) - -### 핵심 의존성 - -```yaml -dependencies: - flutter: sdk - pdfrx: ^1.1.28 # PDF 렌더링 - isar: ^3.1.0+1 # 로컬 데이터베이스 - file_picker: ^10.1.9 # 파일 선택 - http: ^1.4.0 # HTTP 클라이언트 - shared_preferences: ^2.5.3 # 설정 저장 - path_provider: ^2.1.5 # 파일 경로 관리 -``` - -### AI & OCR 연동 - -- **AI 프로바이더**: OpenAI GPT-4, Google Gemini API -- **OCR 서비스**: 커스텀 OCR API 서버 -- **이미지 처리**: Flutter의 dart:ui 라이브러리 - -## 🚀 시작하기 +## 🚀 빠른 시작 ### 필수 요구사항 - -- Flutter SDK 3.7.2 이상 -- Dart SDK 3.0 이상 +- Flutter SDK 3.7.2+ +- Dart SDK 3.0+ - Android Studio / VS Code -- iOS 개발 시 Xcode 필요 - -### 설치 방법 -1. **저장소 클론** +### 5분 만에 시작하기 ```bash +# 1. 저장소 클론 git clone https://github.com/CommitBang/Frontend.git cd Frontend -``` - -2. **의존성 설치** -```bash +# 2. 의존성 설치 flutter pub get -``` -3. **코드 생성 (Isar 데이터베이스)** - -```bash +# 3. 코드 생성 flutter packages pub run build_runner build -``` - -4. **환경 변수 설정** - 프로젝트 루트에 `.env` 파일 생성: -```env -OCR_BASE_URL=your_ocr_server_url -``` - -5. **앱 실행** - -```bash +# 4. 앱 실행 flutter run ``` -## ⚙️ 환경 설정 +> 📖 **자세한 설치 및 설정 가이드**: [docs/GettingStarted.md](docs/GettingStarted.md) -### OCR 서비스 설정 - -OCR 기능을 사용하려면 백엔드 OCR 서버가 필요합니다: - -1. OCR 서버 URL을 `.env` 파일에 설정 -2. 서버는 다음 엔드포인트를 제공해야 합니다: (https://github.com/CommitBang/PDFRecognitionAPI) - - `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)) +--- ## 📁 프로젝트 구조 -### 프로젝트 구조 - ``` 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/ # 테마 및 디자인 시스템 ├── features/ # 기능별 모듈 │ ├── home/ # 홈 화면 및 문서 관리 │ ├── pdf_viewer/ # PDF 뷰어 및 관련 기능 │ └── settings/ # 설정 화면 └── shared/ # 공유 서비스 및 위젯 ├── services/ # 비즈니스 로직 서비스 - │ ├── ai_service/ # AI 프로바이더 관리 - │ ├── ocr_core/ # OCR 서비스 - │ ├── pdf_core/ # PDF 데이터 관리 - │ └── navigation_service/ # 내비게이션 관리 └── widgets/ # 재사용 가능한 위젯 ``` -### 주요 서비스 +> 📖 **상세한 프로젝트 구조**: [docs/ProjectStructure.md](docs/ProjectStructure.md) -- **PDFProvider**: PDF 문서 관리 및 OCR 처리 -- **AIService**: AI 프로바이더 통합 관리 -- **OCRProvider**: OCR 서버와의 통신 -- **NavigationService**: 중앙화된 내비게이션 관리 +--- -## 🎯 사용 방법 +## 🛠️ 기술 스택 -### 1. PDF 문서 추가 +### Frontend +- **Framework**: Flutter 3.7.2+ +- **Language**: Dart 3.0+ +- **Architecture**: Clean Architecture + MVVM +- **State Management**: Provider Pattern +- **Database**: Isar (NoSQL) -- 홈 화면에서 "새 문서 추가" 버튼 클릭 -- 기기에서 PDF 파일 선택 -- 자동으로 OCR 처리 시작 +### 핵심 라이브러리 +```yaml +dependencies: + pdfrx: ^1.1.28 # PDF 렌더링 + isar: ^3.1.0+1 # 로컬 데이터베이스 + file_picker: ^10.1.9 # 파일 선택 + http: ^1.4.0 # HTTP 클라이언트 + provider: ^6.0.5 # 상태 관리 +``` -### 2. Figure 분석 +--- -- PDF 뷰어에서 Figure 영역 터치 -- "Ask AI" 버튼으로 AI 분석 요청 -- 드래그 가능한 채팅 창에서 질의응답 +## 🤝 기여하기 -### 3. 문서 관리 +SnapFig 프로젝트에 기여해주셔서 감사합니다! -- 최근 문서에서 빠른 접근 -- 문서 이름 변경 및 삭제 -- 읽던 페이지 자동 저장 +### 간단한 기여 방법 +1. 이슈 생성 또는 기존 이슈 확인 +2. Fork & 브랜치 생성 (`feature/amazing-feature`) +3. 변경사항 커밋 (`feat: Add amazing feature`) +4. Pull Request 생성 -## 🧪 테스트 +> 📖 **자세한 기여 가이드**: [docs/Contributing.md](docs/Contributing.md) +> 📖 **브랜치 전략**: [docs/Branching.md](docs/Branching.md) -### 단위 테스트 실행 +--- -```bash -flutter test -``` +## 📄 라이선스 -### 통합 테스트 실행 +이 프로젝트는 **MIT License** 하에 배포됩니다. -```bash -flutter test integration_test/ ``` +Copyright 2025 CommitBang -### 브랜치 전략 - -- `main`: 프로덕션 브랜치 -- `develop`: 개발 브랜치 -- `feature/*`: 새로운 기능 개발 -- `bugfix/*`: 버그 수정 -- `hotfix/*`: 긴급 수정 +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: -### 커밋 메시지 규칙 - -| 타입 | 설명 | 예시 | -|----------|-----------|------------------------| -| feat | 새로운 기능 추가 | feat: 로그인 기능 구현 | -| fix | 버그 수정 | fix: 로그인 시 토큰 만료 오류 수정 | -| docs | 문서 수정 | docs: README 업데이트 | -| style | 코드 포맷팅 | style: 코드 들여쓰기 수정 | -| refactor | 코드 리팩토링 | refactor: 로그인 로직 개선 | -| test | 테스트 코드 | test: 로그인 테스트 케이스 추가 | -| chore | 빌드 업무 수정 | chore: 패키지 버전 업데이트 | - -#### 커밋 메시지 형식 +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. ``` -<타입>: <설명> -[선택사항: 본문] -``` - -## 🤝 기여 방법 -1. **Fork & Clone** 저장소 -2. **브랜치 네이밍**: `feature/*`, `bugfix/*` -3. **커밋 메시지**: 위의 커밋메시지 규칙 확인 -4. **PR 전 확인**: +--- -- [CONTRIBUTING.md](./CONTRIBUTING.md) -- `.github/ISSUE_TEMPLATE/` 템플릿 사용 +## 📞 문의 및 지원 -5. **리뷰 프로세스**: 최소 두 명의 리뷰어 승인 후 Merge +- **이슈 리포트**: [GitHub Issues](https://github.com/CommitBang/Frontend/issues) +- **기능 제안**: [GitHub Discussions](https://github.com/CommitBang/Frontend/discussions) +- **문서**: [docs/](docs/) 폴더 참조 --- -## 📄 라이선스 +
+ +**SnapFig과 함께 더 스마트한 학습을 시작하세요! 📚✨** + +[⭐ Star](https://github.com/CommitBang/Frontend) | [🐛 Report Bug](https://github.com/CommitBang/Frontend/issues) | [💡 Request Feature](https://github.com/CommitBang/Frontend/discussions) -이 프로젝트는 Apache License 하에 배포됩니다. 자세한 내용은 [LICENSE](LICENSE) 파일을 참조하세요. +
diff --git a/docs/Branching.md b/docs/Branching.md new file mode 100644 index 0000000..1a7141b --- /dev/null +++ b/docs/Branching.md @@ -0,0 +1,421 @@ +# 🌿 브랜치 전략 + +SnapFig 프로젝트의 Git 워크플로우와 브랜치 관리 전략을 설명합니다. + +## 🎯 브랜치 전략 개요 + +SnapFig은 **GitHub Flow**를 기반으로 한 단순하고 효율적인 브랜치 전략을 사용하여 안정적인 개발과 배포를 보장합니다. + +--- + +## 🌳 브랜치 구조 + +### 메인 브랜치 + +#### `main` 브랜치 +- **목적**: 프로덕션 배포 및 릴리즈 브랜치 +- **특징**: + - 항상 배포 가능한 상태 + - 모든 기능 브랜치의 최종 병합 대상 + - 직접 커밋 금지 (PR을 통해서만 병합) + - 모든 테스트 통과 필수 + - 태그를 통한 버전 관리 +- **보호 규칙**: + - 직접 푸시 금지 + - PR 리뷰 필수 (최소 2명) + - 상태 확인 통과 필수 + +### 지원 브랜치 + +#### `feature/*` 브랜치 +- **목적**: 새로운 기능 개발 +- **네이밍**: `feature/기능명` 또는 `feature/이슈번호-기능명` +- **생성 기준**: `main` 브랜치에서 분기 +- **병합 대상**: `main` 브랜치 +- **예시**: + ```bash + feature/pdf-viewer + feature/123-ai-integration + feature/figure-highlighting + ``` + +#### `bugfix/*` 브랜치 +- **목적**: 버그 수정 +- **네이밍**: `bugfix/버그명` 또는 `bugfix/이슈번호-버그명` +- **생성 기준**: `main` 브랜치에서 분기 +- **병합 대상**: `main` 브랜치 +- **예시**: + ```bash + bugfix/pdf-loading-error + bugfix/456-memory-leak + bugfix/ocr-timeout + ``` + +#### `hotfix/*` 브랜치 +- **목적**: 프로덕션 긴급 수정 +- **네이밍**: `hotfix/버전-수정내용` +- **생성 기준**: `main` 브랜치에서 분기 +- **병합 대상**: `main` 브랜치 +- **예시**: + ```bash + hotfix/1.0.1-critical-crash + hotfix/1.0.2-security-fix + ``` + +--- + +## 🔄 워크플로우 + +### 1. 기능 개발 워크플로우 + +```mermaid +graph LR + A[main] --> B[feature/new-feature] + B --> C[개발 & 테스트] + C --> D[PR 생성] + D --> E[코드 리뷰] + E --> F[main 병합] + F --> G[태그 생성] +``` + +#### 단계별 명령어 + +```bash +# 1. main 브랜치에서 최신 코드 가져오기 +git checkout main +git pull origin main + +# 2. 새 기능 브랜치 생성 +git checkout -b feature/amazing-feature + +# 3. 개발 작업 수행 +# ... 코딩, 테스트 작성 ... + +# 4. 변경사항 커밋 +git add . +git commit -m "feat: Add amazing feature" + +# 5. 원격 저장소에 푸시 +git push origin feature/amazing-feature + +# 6. GitHub에서 PR 생성 +# main <- feature/amazing-feature + +# 7. 리뷰 완료 후 병합 +# 8. 로컬 브랜치 정리 +git checkout main +git pull origin main +git branch -d feature/amazing-feature + +# 9. 릴리즈 시 태그 생성 +git tag -a v1.1.0 -m "Release version 1.1.0" +git push origin v1.1.0 +``` + +### 2. 버그 수정 워크플로우 + +```bash +# 1. main 브랜치에서 분기 +git checkout main +git pull origin main +git checkout -b bugfix/fix-critical-bug + +# 2. 버그 수정 및 테스트 +# ... 수정 작업 ... + +# 3. 커밋 및 푸시 +git add . +git commit -m "fix: Resolve critical bug in PDF loading" +git push origin bugfix/fix-critical-bug + +# 4. PR 생성 및 리뷰 +# main <- bugfix/fix-critical-bug + +# 5. 병합 후 패치 버전 태그 생성 (필요시) +git checkout main +git pull origin main +git tag -a v1.0.1 -m "Patch release 1.0.1" +git push origin v1.0.1 +``` + +### 3. 핫픽스 워크플로우 + +```bash +# 1. main 브랜치에서 분기 +git checkout main +git pull origin main +git checkout -b hotfix/1.0.1-critical-fix + +# 2. 긴급 수정 +# ... 수정 작업 ... + +# 3. 커밋 및 푸시 +git add . +git commit -m "hotfix: Fix critical security vulnerability" +git push origin hotfix/1.0.1-critical-fix + +# 4. main에 PR 생성 및 병합 +# main <- hotfix/1.0.1-critical-fix + +# 5. 핫픽스 태그 생성 +git checkout main +git pull origin main +git tag -a v1.0.1 -m "Hotfix release 1.0.1" +git push origin v1.0.1 +``` + +### 4. 릴리즈 워크플로우 + +main 브랜치를 릴리즈 브랜치로 사용하므로, 별도의 릴리즈 브랜치 없이 태그를 통해 버전을 관리합니다. + +```bash +# 1. main 브랜치에서 릴리즈 준비 +git checkout main +git pull origin main + +# 2. 릴리즈 준비 작업 (버전 업데이트, 문서 정리 등) +# pubspec.yaml의 version 업데이트 +# CHANGELOG.md 업데이트 +# ... 기타 릴리즈 준비 작업 ... + +# 3. 릴리즈 준비 커밋 +git add . +git commit -m "chore: Prepare release 1.1.0" +git push origin main + +# 4. 릴리즈 태그 생성 +git tag -a v1.1.0 -m "Release version 1.1.0" +git push origin v1.1.0 + +# 5. GitHub에서 릴리즈 노트 작성 (선택사항) +``` + +--- + +## 📝 커밋 메시지 규칙 + +### 커밋 메시지 형식 + +``` +<타입>: <제목> + +<본문> + +<푸터> +``` + +### 타입 (Type) + +| 타입 | 설명 | 예시 | +|------|------|------| +| `feat` | 새로운 기능 추가 | `feat: Add zoom functionality` | +| `fix` | 버그 수정 | `fix: Resolve text recognition timeout` | +| `docs` | 문서 수정 | `docs: Update installation guide` | +| `style` | 코드 포맷팅, 세미콜론 누락 등 | `style: Fix code formatting` | +| `refactor` | 코드 리팩토링 | `refactor: Simplify provider logic` | +| `test` | 테스트 추가 또는 수정 | `test: Add unit tests` | +| `chore` | 빌드 프로세스, 보조 도구 변경 | `chore: Update dependencies` | +| `perf` | 성능 개선 | `perf: Optimize page loading` | +| `ci` | CI/CD 설정 변경 | `ci: Add automated testing workflow` | +| `build` | 빌드 시스템 변경 | `build: Update Flutter version` | + + + +### 커밋 메시지 예시 + +#### 좋은 예시 +```bash +feat: Add figure highlighting functionality + +- Implement OCR-based figure detection +- Add visual highlighting for selected figures +- Integrate with AI service for figure analysis + +Closes #123 +``` + +```bash +fix: Resolve API timeout issue + +The OpenAI API calls were timing out due to insufficient +timeout configuration. Increased timeout to 30 seconds +and added retry logic. + +Fixes #456 +``` + +#### 나쁜 예시 +```bash +# 너무 간단함 +fix: bug fix + +# 타입 누락 +Add new feature + +# 의미 불명확 +update code +``` + +--- + +## 🔍 PR (Pull Request) 가이드 + +### PR 생성 전 체크리스트 + +- [ ] 최신 main 브랜치와 동기화 +- [ ] 모든 테스트 통과 +- [ ] 코드 스타일 가이드 준수 +- [ ] 관련 문서 업데이트 +- [ ] 커밋 메시지 규칙 준수 + +### PR 제목 규칙 + +PR 제목은 커밋 메시지와 동일한 형식을 따릅니다: + +``` +<타입>: <제목> +``` + +**예시:** +- `feat: Add figure highlighting functionality` +- `fix: Resolve API timeout issue` +- `docs: Update installation guide` + +### PR 설명 템플릿 + +```markdown +## 📝 변경사항 설명 +이 PR에서 변경된 내용에 대한 명확한 설명 + +## 🔗 관련 이슈 +- Closes #123 +- Related to #456 + +## 🧪 테스트 +- [ ] 단위 테스트 추가/수정 +- [ ] 위젯 테스트 추가/수정 +- [ ] 통합 테스트 추가/수정 +- [ ] 수동 테스트 완료 + +## 📸 스크린샷 (UI 변경사항이 있는 경우) +변경 전후 스크린샷 + +## 📋 체크리스트 +- [ ] 코드 스타일 가이드 준수 +- [ ] 테스트 추가/수정 +- [ ] 문서 업데이트 +- [ ] 브레이킹 체인지 없음 (있다면 설명) + +## 🔄 리뷰어 +@reviewer1 @reviewer2 +``` + +--- + + +## 🔧 유용한 Git 명령어 + +### 브랜치 관리 + +```bash +# 모든 브랜치 확인 +git branch -a + +# 원격 브랜치 확인 +git branch -r + +# 브랜치 삭제 +git branch -d feature/old-feature + +# 원격 브랜치 삭제 +git push origin --delete feature/old-feature + +# 브랜치 이름 변경 +git branch -m old-name new-name +``` + +### 동기화 + +```bash +# 원격 저장소 최신 정보 가져오기 +git fetch origin + +# main 브랜치와 동기화 +git checkout main +git pull origin main + +# 현재 브랜치를 main과 동기화 +git rebase main +``` + +### 히스토리 관리 + +```bash +# 커밋 히스토리 확인 +git log --oneline --graph + +# 특정 파일의 변경 히스토리 +git log --follow -- filename + +# 브랜치 간 차이 확인 +git diff main..feature/new-feature +``` + +--- + +## 📋 자주 묻는 질문 + +### Q: feature 브랜치에서 main의 최신 변경사항을 가져오려면? +```bash +git checkout feature/my-feature +git rebase main +``` + +### Q: 실수로 잘못된 브랜치에 커밋했다면? +```bash +# 커밋을 다른 브랜치로 이동 +git checkout correct-branch +git cherry-pick + +# 원래 브랜치에서 커밋 제거 +git checkout wrong-branch +git reset --hard HEAD~1 +``` + +### Q: PR 병합 후 브랜치 정리는? +```bash +# 로컬 브랜치 삭제 +git branch -d feature/merged-feature + +# 원격 브랜치는 GitHub에서 자동 삭제 설정 권장 +``` + +### Q: 충돌 해결 방법은? +```bash +# 리베이스 중 충돌 발생 시 +git status # 충돌 파일 확인 +# 파일 수정 후 +git add . +git rebase --continue +``` + +--- + +## 🎯 모범 사례 + +### 브랜치 네이밍 +- **명확하고 설명적인 이름** 사용 +- **이슈 번호 포함** (있는 경우) +- **소문자와 하이픈** 사용 + +### 커밋 관리 +- **작은 단위로 자주 커밋** +- **의미 있는 커밋 메시지** 작성 +- **관련 없는 변경사항은 분리** + +### PR 관리 +- **하나의 기능/수정사항당 하나의 PR** +- **명확한 설명과 테스트 결과** 포함 +- **리뷰어 지정** 및 **피드백 적극 반영** + +--- \ No newline at end of file diff --git a/docs/Contributing.md b/docs/Contributing.md new file mode 100644 index 0000000..077d633 --- /dev/null +++ b/docs/Contributing.md @@ -0,0 +1,410 @@ +# 🤝 기여 가이드 + +SnapFig 프로젝트에 기여해주셔서 감사합니다! 이 문서는 프로젝트에 효과적으로 기여하는 방법을 안내합니다. + +## 🎯 기여 방법 개요 + +SnapFig은 오픈소스 프로젝트로, 다양한 형태의 기여를 환영합니다: + +- 🐛 **버그 리포트**: 발견한 문제점 신고 +- 💡 **기능 제안**: 새로운 기능 아이디어 제안 +- 📝 **코드 기여**: 버그 수정, 기능 구현, 성능 개선 +- 📚 **문서 개선**: README, 가이드, 주석 개선 +- 🧪 **테스트 추가**: 테스트 커버리지 향상 +- 🎨 **UI/UX 개선**: 사용자 경험 향상 + +--- + +## 🚀 시작하기 + +### 1. 개발 환경 설정 + +기여를 시작하기 전에 개발 환경을 설정해주세요: + +```bash +# 1. 저장소 Fork 후 클론 +git clone https://github.com/YOUR_USERNAME/Frontend.git +cd Frontend + +# 2. 원본 저장소를 upstream으로 추가 +git remote add upstream https://github.com/CommitBang/Frontend.git + +# 3. 의존성 설치 +flutter pub get + +# 4. 코드 생성 +flutter packages pub run build_runner build + +# 5. 테스트 실행하여 환경 확인 +flutter test +``` + +### 2. 이슈 확인 + +기여하기 전에 다음을 확인해주세요: + +- **기존 이슈 검색**: 동일한 문제나 제안이 있는지 확인 +- **라벨 확인**: `good first issue`, `help wanted` 라벨 확인 +- **할당 상태**: 이미 누군가 작업 중인지 확인 + +--- + +## 🐛 버그 리포트 + +버그를 발견했다면 다음 정보를 포함하여 이슈를 생성해주세요: + +### 버그 리포트 템플릿 + +```markdown +## 🐛 버그 설명 +버그에 대한 명확하고 간결한 설명 + +## 🔄 재현 단계 +1. '...'로 이동 +2. '...'를 클릭 +3. '...'까지 스크롤 +4. 오류 발생 + +## 🎯 예상 동작 +예상했던 동작에 대한 설명 + +## 📱 실제 동작 +실제로 발생한 동작에 대한 설명 + +## 📸 스크린샷 +가능하다면 스크린샷 첨부 + +## 🔧 환경 정보 +- OS: [예: iOS 16.0, Android 13] +- 기기: [예: iPhone 14, Samsung Galaxy S23] +- Flutter 버전: [예: 3.7.2] +- 앱 버전: [예: 1.0.0] + +## 📝 추가 정보 +기타 관련 정보나 컨텍스트 +``` + +--- + +## 💡 기능 제안 + +새로운 기능을 제안할 때는 다음 정보를 포함해주세요: + +### 기능 제안 템플릿 + +```markdown +## 🚀 기능 설명 +제안하는 기능에 대한 명확한 설명 + +## 🎯 문제점 +이 기능이 해결하고자 하는 문제 + +## 💡 해결 방안 +제안하는 해결 방안에 대한 설명 + +## 🔄 대안 +고려해본 다른 대안들 + +## 📝 추가 정보 +기타 관련 정보나 컨텍스트 +``` + +--- + +## 📝 코드 기여 + +### 1. 브랜치 생성 + +작업을 시작하기 전에 적절한 브랜치를 생성해주세요: + +```bash +# 최신 코드로 업데이트 +git checkout main +git pull upstream main + +# 새 브랜치 생성 +git checkout -b feature/amazing-feature +# 또는 +git checkout -b bugfix/fix-critical-bug +``` + +### 2. 코딩 스타일 + +SnapFig은 다음 코딩 스타일을 따릅니다: + +#### Dart 코딩 컨벤션 +- **공식 Dart 스타일 가이드** 준수 +- **dartfmt**를 사용한 자동 포맷팅 +- **dart analyze**를 통한 정적 분석 통과 + +```bash +# 코드 포맷팅 +dart format . + +# 정적 분석 +dart analyze +``` + +#### 네이밍 컨벤션 +```dart +// 클래스: PascalCase +class PDFViewerScreen extends StatefulWidget {} + +// 변수, 함수: camelCase +String documentTitle = ''; +void loadDocument() {} + +// 상수: lowerCamelCase +const String apiBaseUrl = 'https://api.example.com'; + +// 파일명: snake_case +pdf_viewer_screen.dart +document_model.dart +``` + +#### 주석 작성 +```dart +/// PDF 문서를 로드하고 OCR 처리를 수행합니다. +/// +/// [filePath]는 로드할 PDF 파일의 경로입니다. +/// [enableOCR]이 true이면 OCR 처리를 함께 수행합니다. +/// +/// Returns: 로드된 PDF 문서 정보 +/// Throws: [FileNotFoundException] 파일을 찾을 수 없는 경우 +Future loadDocument( + String filePath, { + bool enableOCR = true, +}) async { + // 구현 내용 +} +``` + +### 3. 테스트 작성 + +모든 새로운 기능과 버그 수정에는 적절한 테스트가 포함되어야 합니다: + +#### 단위 테스트 +```dart +// test/unit/services/pdf_service_test.dart +import 'package:flutter_test/flutter_test.dart'; +import 'package:snapfig/shared/services/pdf_service.dart'; + +void main() { + group('PDFService', () { + late PDFService pdfService; + + setUp(() { + pdfService = PDFService(); + }); + + test('should load PDF document successfully', () async { + // Given + const filePath = 'assets/sample/test.pdf'; + + // When + final result = await pdfService.loadDocument(filePath); + + // Then + expect(result, isNotNull); + expect(result.pageCount, greaterThan(0)); + }); + }); +} +``` + +#### 위젯 테스트 +```dart +// test/widget/home/pdf_card_test.dart +import 'package:flutter/material.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:snapfig/features/home/widgets/pdf_card.dart'; + +void main() { + testWidgets('PDFCard should display document title', (tester) async { + // Given + const documentTitle = 'Test Document'; + + // When + await tester.pumpWidget( + MaterialApp( + home: PDFCard(title: documentTitle), + ), + ); + + // Then + expect(find.text(documentTitle), findsOneWidget); + }); +} +``` + +### 4. 커밋 메시지 + +의미 있는 커밋 메시지를 작성해주세요: + +#### 커밋 메시지 형식 +``` +<타입>(<범위>): <설명> + +<본문> + +<푸터> +``` + +#### 타입 +- `feat`: 새로운 기능 추가 +- `fix`: 버그 수정 +- `docs`: 문서 수정 +- `style`: 코드 포맷팅, 세미콜론 누락 등 +- `refactor`: 코드 리팩토링 +- `test`: 테스트 추가 또는 수정 +- `chore`: 빌드 프로세스 또는 보조 도구 변경 + +#### 예시 +```bash +feat(pdf-viewer): Add figure highlighting functionality + +- Implement OCR-based figure detection +- Add visual highlighting for selected figures +- Integrate with AI service for figure analysis + +Closes #123 +``` + +### 5. Pull Request 생성 + +작업이 완료되면 Pull Request를 생성해주세요: + +#### PR 체크리스트 +- [ ] 코드가 프로젝트 스타일 가이드를 따름 +- [ ] 새로운 기능에 대한 테스트 추가 +- [ ] 모든 테스트가 통과 +- [ ] 문서 업데이트 (필요한 경우) +- [ ] 변경사항에 대한 명확한 설명 + +#### PR 템플릿 +```markdown +## 📝 변경사항 설명 +이 PR에서 변경된 내용에 대한 설명 + +## 🔗 관련 이슈 +Closes #123 + +## 🧪 테스트 +- [ ] 단위 테스트 추가/수정 +- [ ] 위젯 테스트 추가/수정 +- [ ] 통합 테스트 추가/수정 +- [ ] 수동 테스트 완료 + +## 📸 스크린샷 (UI 변경사항이 있는 경우) +변경 전후 스크린샷 + +## 📋 체크리스트 +- [ ] 코드 스타일 가이드 준수 +- [ ] 테스트 추가/수정 +- [ ] 문서 업데이트 +- [ ] 브레이킹 체인지 없음 (있다면 설명) +``` + +--- + +## 🔍 코드 리뷰 + +### 리뷰 프로세스 + +1. **자동 검사**: CI/CD 파이프라인에서 자동 테스트 실행 +2. **코드 리뷰**: 최소 2명의 리뷰어가 코드 검토 +3. **피드백 반영**: 리뷰 의견에 따른 수정 +4. **승인 및 머지**: 모든 검토 완료 후 메인 브랜치에 병합 + +### 리뷰 기준 + +- **기능성**: 코드가 의도한 대로 동작하는가? +- **가독성**: 코드가 이해하기 쉬운가? +- **성능**: 성능에 부정적인 영향은 없는가? +- **테스트**: 적절한 테스트가 포함되어 있는가? +- **문서**: 필요한 문서가 업데이트되었는가? + +--- + +## 📚 문서 기여 + +문서 개선도 중요한 기여입니다: + +### 문서 유형 +- **README**: 프로젝트 소개 및 시작 가이드 +- **API 문서**: 코드 주석 및 API 설명 +- **사용자 가이드**: 앱 사용법 안내 +- **개발자 가이드**: 개발 관련 문서 + +### 문서 작성 가이드 +- **명확성**: 이해하기 쉬운 언어 사용 +- **완전성**: 필요한 모든 정보 포함 +- **최신성**: 코드 변경사항과 동기화 +- **예시**: 구체적인 예시 코드 포함 + +--- + +## 🎨 UI/UX 기여 + +디자인 개선에 기여하고 싶다면: + +### 디자인 가이드라인 +- **Material Design 3** 준수 +- **접근성** 고려 (색상 대비, 폰트 크기 등) +- **일관성** 유지 +- **사용성** 우선 + +### 디자인 제안 방법 +1. **Figma** 또는 **Adobe XD**로 목업 제작 +2. **이슈**에 디자인 첨부하여 제안 +3. **피드백** 수렴 후 구현 + +--- + +## 🏆 기여자 인정 + +모든 기여자는 다음과 같이 인정받습니다: + +- **README**의 기여자 섹션에 이름 추가 +- **릴리즈 노트**에 기여 내용 명시 +- **GitHub 프로필**에 기여 배지 표시 + +--- + +## 📞 도움 요청 + +기여 과정에서 도움이 필요하다면: + +- **GitHub Issues**: 기술적 질문 +- **GitHub Discussions**: 일반적인 토론 +- **Discord**: 실시간 채팅 (링크 추후 제공) + +--- + +## 📋 자주 묻는 질문 + +### Q: 처음 기여하는데 어떤 이슈부터 시작하면 좋을까요? +A: `good first issue` 라벨이 붙은 이슈부터 시작하는 것을 추천합니다. + +### Q: 코드 스타일을 자동으로 확인할 수 있나요? +A: 네, `dart format .`과 `dart analyze` 명령어를 사용하세요. + +### Q: 테스트는 어떻게 작성해야 하나요? +A: 기존 테스트 파일을 참고하여 유사한 패턴으로 작성해주세요. + +### Q: PR이 머지되기까지 얼마나 걸리나요? +A: 일반적으로 1-2주 정도 소요되며, 복잡도에 따라 달라질 수 있습니다. + +--- + +## 🎯 다음 단계 + +기여 가이드를 읽었다면: + +1. **[브랜치 전략](Branching.md)** 문서로 Git 워크플로우 학습 +2. **[프로젝트 구조](ProjectStructure.md)** 문서로 코드베이스 이해 +3. **첫 번째 이슈** 선택하여 기여 시작! + +--- + +**SnapFig 프로젝트에 기여해주셔서 다시 한 번 감사드립니다! 🙏** \ No newline at end of file diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md new file mode 100644 index 0000000..30898cb --- /dev/null +++ b/docs/GettingStarted.md @@ -0,0 +1,279 @@ +# 🚀 시작하기 가이드 + +SnapFig을 설치하고 실행하는 상세한 가이드입니다. + +## 📋 필수 요구사항 + +### 개발 환경 +- **Flutter SDK**: 3.7.2 이상 +- **Dart SDK**: 3.0 이상 +- **IDE**: Android Studio, VS Code, 또는 IntelliJ IDEA +- **Git**: 버전 관리를 위해 필요 + +### 플랫폼별 요구사항 + +#### Android 개발 +- **Android Studio**: 최신 버전 권장 +- **Android SDK**: API 레벨 25 (Android 7.1) 이상 + +#### iOS 개발 (macOS만 해당) +- **Xcode**: 14.0 이상 +- **iOS Deployment Target**: iOS 12.0 이상 +- **CocoaPods**: 의존성 관리를 위해 필요 + +--- + +## 🛠️ 설치 과정 + +### 1. Flutter 설치 + +#### macOS +```bash +# Homebrew를 사용한 설치 +brew install flutter + +# 또는 공식 사이트에서 다운로드 +# https://docs.flutter.dev/get-started/install/macos +``` + +#### Windows +```bash +# Chocolatey를 사용한 설치 +choco install flutter + +# 또는 공식 사이트에서 다운로드 +# https://docs.flutter.dev/get-started/install/windows +``` + +#### Linux +```bash +# Snap을 사용한 설치 +sudo snap install flutter --classic + +# 또는 공식 사이트에서 다운로드 +# https://docs.flutter.dev/get-started/install/linux +``` + +### 2. Flutter 설정 확인 + +```bash +# Flutter 설치 상태 확인 +flutter doctor + +# 누락된 의존성이 있다면 안내에 따라 설치 +``` + +### 3. 프로젝트 클론 및 설정 + +```bash +# 저장소 클론 +git clone https://github.com/CommitBang/Frontend.git +cd Frontend + +# 의존성 설치 +flutter pub get + +# 코드 생성 (Isar 데이터베이스용) +flutter packages pub run build_runner build +``` + +--- + +## ⚙️ 환경 설정 + +### OCR 서비스 설정 + +SnapFig의 OCR 기능을 사용하려면 백엔드 OCR 서버가 필요합니다. + +1. **환경 변수 파일 생성** + 프로젝트 루트에 `.env` 파일을 생성하고 다음 내용을 추가: + +```env +# OCR 서버 설정 +OCR_BASE_URL=http://your-ocr-server.com +``` + +2. **OCR 서버 요구사항** + OCR 서버는 다음 엔드포인트를 제공해야 합니다: + - `POST /api/v1/analyze`: PDF 분석 및 Figure 추출 + + > 📖 **OCR 서버 구축**: [PDFRecognitionAPI](https://github.com/CommitBang/PDFRecognitionAPI) 참조 + +### AI 기능 설정 + +AI 기능은 앱 내에서 설정할 수 있습니다. + +#### OpenAI 설정 +1. [OpenAI Platform](https://platform.openai.com/api-keys)에서 API 키 발급 +2. 앱 실행 후 설정 화면에서 API 키 입력 +3. 모델 선택 (GPT-4 권장) + +#### Google Gemini 설정 +1. [Google Cloud Console](https://console.cloud.google.com)에서 API 키 발급 +2. Gemini API 활성화 +3. 앱 설정에서 API 키 입력 + +--- + +## 🏃‍♂️ 앱 실행 + +### 개발 모드 실행 + +```bash +# 연결된 기기 확인 +flutter devices + +# 앱 실행 (기본 기기) +flutter run + +# 특정 기기에서 실행 +flutter run -d + +# 디버그 모드로 실행 +flutter run --debug + +# 릴리즈 모드로 실행 +flutter run --release +``` + +### 플랫폼별 실행 + +#### Android +```bash +# Android 에뮬레이터 실행 +flutter emulators --launch + +# Android 기기에서 실행 +flutter run -d android +``` + +#### iOS (macOS만 해당) +```bash +# iOS 시뮬레이터 실행 +open -a Simulator + +# iOS 기기에서 실행 +flutter run -d ios +``` + +--- + +## 🔧 개발 도구 설정 + +### VS Code 확장 프로그램 +- **Flutter**: Flutter 개발 지원 +- **Dart**: Dart 언어 지원 +- **Flutter Widget Snippets**: 위젯 스니펫 +- **Awesome Flutter Snippets**: 추가 스니펫 + +### Android Studio 플러그인 +- **Flutter Plugin**: Flutter 개발 지원 +- **Dart Plugin**: Dart 언어 지원 + +--- + +## 🧪 테스트 실행 + +### 단위 테스트 +```bash +# 모든 테스트 실행 +flutter test + +# 특정 테스트 파일 실행 +flutter test test/unit/pdf_service_test.dart + +# 커버리지 포함 테스트 +flutter test --coverage +``` + +### 통합 테스트 +```bash +# 통합 테스트 실행 +flutter test integration_test/ + +# 특정 통합 테스트 +flutter test integration_test/app_test.dart +``` + +--- + +## 📱 빌드 및 배포 + +### Android APK 빌드 +```bash +# 디버그 APK 빌드 +flutter build apk --debug + +# 릴리즈 APK 빌드 +flutter build apk --release + +# App Bundle 빌드 (Google Play Store용) +flutter build appbundle --release +``` + +### iOS 빌드 (macOS만 해당) +```bash +# iOS 앱 빌드 +flutter build ios --release + +# Xcode에서 빌드 +open ios/Runner.xcworkspace +``` + +--- + +## 🐛 문제 해결 + +### 일반적인 문제들 + +#### 1. Flutter Doctor 오류 +```bash +# Flutter 설치 상태 재확인 +flutter doctor -v + +# Flutter 업그레이드 +flutter upgrade +``` + +#### 2. 의존성 문제 +```bash +# 의존성 재설치 +flutter clean +flutter pub get +``` + +#### 3. 코드 생성 오류 +```bash +# 빌드 러너 재실행 +flutter packages pub run build_runner clean +flutter packages pub run build_runner build --delete-conflicting-outputs +``` + +#### 4. iOS 빌드 오류 +```bash +# CocoaPods 재설치 +cd ios +pod deintegrate +pod install +cd .. +``` + +--- + +## 📞 추가 도움 + +문제가 지속되면 다음 리소스를 참조하세요: + +- **Flutter 공식 문서**: [flutter.dev](https://flutter.dev) +- **프로젝트 이슈**: [GitHub Issues](https://github.com/CommitBang/Frontend/issues) +- **Flutter 커뮤니티**: [Flutter Discord](https://discord.gg/flutter) + +--- + +## 🎯 다음 단계 + +설치가 완료되었다면: + +1. **[프로젝트 구조](ProjectStructure.md)** 문서로 코드베이스 이해하기 +2. **[기여 가이드](Contributing.md)** 문서로 개발 프로세스 학습하기 +3. **[브랜치 전략](Branching.md)** 문서로 Git 워크플로우 파악하기 \ No newline at end of file diff --git a/docs/ProjectStructure.md b/docs/ProjectStructure.md new file mode 100644 index 0000000..ad824c7 --- /dev/null +++ b/docs/ProjectStructure.md @@ -0,0 +1,314 @@ +# 📁 프로젝트 구조 + +SnapFig의 코드베이스 구조와 각 모듈의 역할을 상세히 설명합니다. + +## 🏗️ 전체 구조 개요 + +SnapFig은 **Clean Architecture**와 **Feature-First** 접근 방식을 채택하여 확장성과 유지보수성을 보장합니다. + +``` +snapfig/ +├── lib/ # 메인 소스 코드 +├── test/ # 단위/위젯/통합 테스트 코드 +├── integration_test/ # 통합 테스트 코드 (Provider 등) +├── assets/ # 리소스 파일 +├── android/ # Android 플랫폼 코드 +├── ios/ # iOS 플랫폼 코드 +├── docs/ # 프로젝트 문서 +``` + +--- + +## 📂 lib/ 디렉토리 상세 구조 + +``` +lib/ +├── main.dart # 앱 진입점 +├── core/ # 앱 전체 공통 요소 +│ ├── constants/ # 상수 정의 +│ ├── theme/ # 테마 및 디자인 시스템 +│ └── utils/ # 유틸리티 함수 +├── features/ # 기능별 모듈 +│ ├── home/ # 홈 화면 및 문서 관리 +│ │ ├── models/ +│ │ ├── screens/ +│ │ └── widgets/ +│ ├── pdf_viewer/ # PDF 뷰어 및 관련 기능 +│ │ ├── models/ +│ │ ├── screens/ +│ │ └── widgets/ +│ │ └── sidebar/ +│ └── settings/ # 설정 화면 +├── shared/ # 공유 서비스 및 위젯 +│ ├── services/ # 비즈니스 로직 서비스 +│ │ ├── ai_service/ +│ │ │ ├── ai_service.dart +│ │ │ ├── ai_service_export.dart +│ │ │ └── models/ +│ │ │ └── ai_provider.dart +│ │ ├── ocr_core/ +│ │ │ ├── ocr_core.dart +│ │ │ ├── ocr_provider.dart +│ │ │ ├── ocr_provider_impl.dart +│ │ │ └── models/ +│ │ │ ├── bounding_box.dart +│ │ │ ├── metadata.dart +│ │ │ ├── ocr_result.dart +│ │ │ └── models.dart +│ │ ├── pdf_core/ +│ │ │ ├── pdf_core.dart +│ │ │ ├── models/ +│ │ │ │ ├── interface/ +│ │ │ │ │ ├── base_pdf.dart +│ │ │ │ │ ├── base_page.dart +│ │ │ │ │ └── base_layout.dart +│ │ │ │ ├── implement/ +│ │ │ │ │ ├── pdf_impl.dart +│ │ │ │ │ ├── page_impl.dart +│ │ │ │ │ └── layout_impl.dart +│ │ │ │ └── models.dart +│ │ │ └── provider/ +│ │ │ ├── pdf_provider.dart +│ │ │ ├── pdf_provider_impl.dart +│ │ │ └── inherited_pdf_provider_widget.dart +│ │ ├── navigation_service/ +│ │ │ ├── navigation_service.dart +│ │ │ └── navigation_view_model.dart +│ │ ├── summarizer_core/ +│ │ │ ├── summarizer_core.dart +│ │ │ ├── summarizer_impl.dart +│ │ │ └── summarizer.dart +│ │ ├── ocr_service.dart +│ │ └── pdf_service.dart +│ └── widgets/ # 재사용 가능한 위젯 +│ └── document_card.dart +``` + +--- + +## 🎯 Core 모듈 + +앱 전체에서 사용되는 공통 요소들을 관리합니다. + +### core/constants/ +``` +constants/ +├── app_constants.dart # 앱 전체 상수 +├── theme_constants.dart # 테마 관련 상수 +``` + +**주요 역할:** +- 앱 전체에서 사용되는 상수 값 정의 +- 하드코딩 방지 및 중앙 관리 +- 설정 변경 시 한 곳에서 수정 가능 + +### core/theme/ +``` +theme/ +├── app_theme.dart # 메인 테마 설정 +├── color_scheme.dart # 색상 체계 +├── text_theme.dart # 텍스트 스타일 +└── theme.dart # 테마 통합 관리 +``` + +**주요 역할:** +- Material Design 3 기반 테마 시스템 +- 다크/라이트 모드 지원 +- 일관된 디자인 시스템 제공 + +--- + +## 🎨 Features 모듈 + +각 기능별로 독립적인 모듈로 구성되어 있습니다. + +--- + +## 🔧 Shared 모듈 + +여러 기능에서 공통으로 사용되는 서비스와 위젯을 관리합니다. + +### shared/services/ +비즈니스 로직과 외부 서비스 연동을 담당합니다. + +#### ai_service/ +``` +ai_service/ +├── ai_service.dart # AI 서비스 메인 클래스 +├── ai_service_export.dart # AI 서비스 export 파일 +└── models/ + └── ai_provider.dart # AI 프로바이더 모델 +``` + +#### ocr_core/ +``` +ocr_core/ +├── ocr_core.dart # OCR 서비스 메인 클래스 +├── ocr_provider.dart # OCR API 인터페이스 +├── ocr_provider_impl.dart # OCR API 구현체 +└── models/ + ├── bounding_box.dart # 바운딩 박스 모델 + ├── metadata.dart # 메타데이터 모델 + ├── ocr_result.dart # OCR 결과 모델 + └── models.dart # 모델 통합 export +``` + +#### pdf_core/ +``` +pdf_core/ +├── pdf_core.dart # PDF 서비스 메인 클래스 +├── models/ +│ ├── interface/ # 인터페이스 정의 +│ │ ├── base_pdf.dart # PDF 기본 인터페이스 +│ │ ├── base_page.dart # 페이지 기본 인터페이스 +│ │ └── base_layout.dart # 레이아웃 기본 인터페이스 +│ ├── implement/ # 구현체 +│ │ ├── pdf_impl.dart # PDF 구현체 +│ │ ├── page_impl.dart # 페이지 구현체 +│ │ └── layout_impl.dart # 레이아웃 구현체 +│ └── models.dart # 모델 통합 export +└── provider/ + ├── pdf_provider.dart # PDF 상태 관리 프로바이더 + ├── pdf_provider_impl.dart # PDF 프로바이더 구현체 + └── inherited_pdf_provider_widget.dart # 상속 위젯 +``` + +#### navigation_service/ +``` +navigation_service/ +├── navigation_service.dart # 네비게이션 서비스 +├── route_generator.dart # 라우트 생성기 +└── app_routes.dart # 앱 라우트 정의 +``` + +### shared/widgets/ +재사용 가능한 공통 위젯들을 관리합니다. + +--- + +## 🧪 Test 구조 + +테스트 코드는 기능별로 체계적으로 구성되어 있습니다. + +``` +test/ +├── unit/ # 단위 테스트 +│ ├── summarizer_test.dart +│ └── calculator_test.dart +├── widget/ # 위젯 테스트 +│ └── widget_test.dart +└── integration/ # 통합 테스트 + └── auth_test.dart + +integration_test/ +├── pdf_provider_test.dart +├── ocr_provider_test.dart +└── assets/ +``` + +--- + +## 📦 Assets 구조 + +앱에서 사용되는 리소스 파일들을 관리합니다. + +``` +assets/ +├── images/ # 이미지 리소스 +├── icons/ # 아이콘 이미지 +│ ├── nofiles_light.png +│ └── nofiles_dark.png +├── fonts/ # 폰트 파일 +│ ├── Pretendard-SemiBold.ttf +│ └── Pretendard-Medium.ttf +├── sample.pdf # 테스트용 PDF +├── sample_ocr_test.pdf # OCR 테스트용 PDF +└── ocr_result.json # OCR 결과 샘플 +``` + +--- + +## 🔄 데이터 흐름 + +### MVVM 패턴 기반 데이터 흐름 + +``` +View (Widget) + ↕️ +ViewModel (Provider/ChangeNotifier) + ↕️ +Model (Service/Repository) + ↕️ +Data Source (API/Database) +``` + +### 주요 데이터 흐름 예시 + +1. **PDF 로딩 흐름** + ``` + PDFViewerScreen → PDFProvider → PDFService → File System + ``` + +2. **OCR 처리 흐름** + ``` + PDFProvider → OCRService → OCR API → OCRResult + ``` + +3. **AI 질의응답 흐름** + ``` + ChatWidget → AIService → AI Provider → AI API + ``` + +--- + +## 📋 코딩 컨벤션 + +### 파일 명명 규칙 +- **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 구조 유지 + +--- + +## 🎯 확장 가이드 + +새로운 기능을 추가할 때 따라야 할 구조: + +### 1. 새로운 Feature 추가 +``` +features/new_feature/ +├── models/ +├── screens/ +└── widgets/ +``` + +### 2. 새로운 Service 추가 +``` +shared/services/new_service/ +├── new_service.dart +├── models/ +└── providers/ +``` + +### 3. 테스트 코드 추가 +``` +test/ +├── unit/new_feature/ +├── widget/new_feature/ +└── integration/new_feature_test.dart +``` \ No newline at end of file diff --git a/docs/api-reference.md b/docs/api-reference.md deleted file mode 100644 index 36e06ac..0000000 --- a/docs/api-reference.md +++ /dev/null @@ -1,3 +0,0 @@ -백엔드(또는 AI 서버) 주요 REST/GraphQL 엔드포인트 정리 - -요청·응답 예시, 인증 방식, 에러 코드 표 \ No newline at end of file diff --git a/docs/architecture.md b/docs/architecture.md deleted file mode 100644 index 7b90002..0000000 --- a/docs/architecture.md +++ /dev/null @@ -1,3 +0,0 @@ -전체 시스템 구조 다이어그램 (클라이언트 ↔ 서버, 모듈 간 데이터 플로우) - -주요 컴포넌트 설명 (PDF 처리, OCR, AI 분석, DB 등) \ No newline at end of file diff --git a/docs/assets/AIAssitant.PNG b/docs/assets/AIAssitant.PNG new file mode 100644 index 0000000..2635fb7 Binary files /dev/null and b/docs/assets/AIAssitant.PNG differ diff --git a/docs/assets/AskFigure.PNG b/docs/assets/AskFigure.PNG new file mode 100644 index 0000000..61ff7a7 Binary files /dev/null and b/docs/assets/AskFigure.PNG differ diff --git a/docs/assets/FigureLink.PNG b/docs/assets/FigureLink.PNG new file mode 100644 index 0000000..09ab22a Binary files /dev/null and b/docs/assets/FigureLink.PNG differ diff --git a/docs/assets/MainView.PNG b/docs/assets/MainView.PNG new file mode 100644 index 0000000..203a778 Binary files /dev/null and b/docs/assets/MainView.PNG differ diff --git a/docs/assets/RecentView.PNG b/docs/assets/RecentView.PNG new file mode 100644 index 0000000..3d235fe Binary files /dev/null and b/docs/assets/RecentView.PNG differ diff --git a/docs/design-decisions.md b/docs/design-decisions.md deleted file mode 100644 index de45361..0000000 --- a/docs/design-decisions.md +++ /dev/null @@ -1,3 +0,0 @@ -주요 설계 선택 배경 (왜 MVVM? 왜 Isar? 왜 FastAPI?) - -대안 검토 및 Trade-off 요약 \ No newline at end of file diff --git a/docs/development-process.md b/docs/development-process.md deleted file mode 100644 index 8b77a86..0000000 --- a/docs/development-process.md +++ /dev/null @@ -1,29 +0,0 @@ -# 개발 프로세스 - -## 개발 방법론 - -- **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 deleted file mode 100644 index 9c4d715..0000000 --- a/docs/faq.md +++ /dev/null @@ -1 +0,0 @@ -자주 묻는 질문과 답변 (설치 오류, 권한 설정, 빌드 시 이슈 등) \ No newline at end of file diff --git a/docs/features.md b/docs/features.md deleted file mode 100644 index 12c5c6e..0000000 --- a/docs/features.md +++ /dev/null @@ -1,25 +0,0 @@ -# 주요 기능 - -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 deleted file mode 100644 index f5c7def..0000000 --- a/docs/glossary.md +++ /dev/null @@ -1 +0,0 @@ -프로젝트 내 용어 정의 (e.g. “Figure 매핑”, “OCR Overlay” 등) \ No newline at end of file diff --git a/docs/roadmap.md b/docs/roadmap.md deleted file mode 100644 index b2fd649..0000000 --- a/docs/roadmap.md +++ /dev/null @@ -1 +0,0 @@ -향후 계획 및 로드맵 \ No newline at end of file diff --git a/docs/tech-stack.md b/docs/tech-stack.md deleted file mode 100644 index 4e54b21..0000000 --- a/docs/tech-stack.md +++ /dev/null @@ -1,23 +0,0 @@ -# 기술 스택 - -## 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