📱 StudySpot Android

📘 프로젝트 개요

기분·목적·상황에 맞게 최적의 공부 장소를 추천하고, 공부 시간을 관리하는 Android 앱

웹 기반 StudySpot 서비스에
네이티브 타이머 기능 / 기록 관리 / 모바일 최적화된 WebView 라우팅을 추가한 형태의 하이브리드 앱입니다.

• 홈/검색 화면 → WebView 기반 (studyspot.kr 연동)
• 타이머/로그 기능 → Android Native (Jetpack Compose)

---

🚀 다운로드 / 배포

• Play Store(예정)
• APK 다운로드(개발 중)

테스트 환경에 따라 WebView는 다음과 연결됨:

구분	URL
FE-Live	https://studyspot.kr
FE-Test	https://test.studyspot.kr

---

🖼 주요 화면

타이머 리스트	타이머 설정	타이머 실행	기록 상세 1	기록 상세 2

---

📱 Android 기술 스택

구분	기술
UI	Jetpack Compose
언어	Kotlin
아키텍처	MVVM, Clean Architecture
DI	Hilt
Navigation	Jetpack Navigation Compose
Network	Retrofit2 + OkHttp3
Async	Kotlin Coroutines + Flow
Storage	DataStore
Web	Android WebView + React Router DeepLink
Style	Material3
CI/CD(예정)	GitHub Actions
Collaboration	GitHub, Notion, Discord

---

✨ 주요 기능

🧭 WebView 기반 홈 / 검색

• studyspot.kr 자동 로딩
• React Router 경로(/timer) 감지하여 Native Timer 탭 전환
• 하단 바는 WebView 내/외 중복되지 않도록 조건부 렌더링

⏱ 타이머 기능 (Native)

• 타이머 생성
• 타이머 수정
• 타이머 삭제
• 타이머 실행 및 UI 애니메이션
• 여러 개 타이머 리스트업
• 타이머 색상 변경 기능
• 타이머 상세 화면

📝 로그 기능 (Native)

• 타이머 수행 기록 저장
• 날짜별 기록 조회
• 타이머 기록 상세 보기

🔗 하이브리드 내비게이션

• 홈 / 검색은 WebView
• 타이머는 Android 네이티브
• /timer 접근 시 → Native 화면으로 전환

---

📁 폴더 구조

StudySpot_Android/
├── app/
│   ├── src/
│   │   ├── main/
│   │   │   ├── java/com/sprinter/studyspot/
│   │   │   │   ├── navigation/
│   │   │   │   ├── timer/
│   │   │   │   │   ├── ui/
│   │   │   │   │   ├── viewmodel/
│   │   │   │   │   ├── model/
│   │   │   │   │   └── data/
│   │   │   │   ├── webview/
│   │   │   │   ├── core/
│   │   │   │   └── util/
│   │   │   └── res/
│   │   └── test/
├── build.gradle.kts
├── settings.gradle.kts
└── README.md

---

🔌 실행 방법

1. 프로젝트 클론

git clone https://github.com/sprinter-wtc/StudySpot_Android.git

2. Android Studio 실행

• Android Studio Hedgehog 이상 권장
• Gradle Sync 자동 실행

3. 앱 실행

• 실제 기기 또는 Emulator 실행
• WebView는 Android WebView(System WebView) 최신 버전 필요

---

🔗 API 연동 (Native Timer API)

✔ Timer 조회

GET /api/timers
Header: Authorization: Bearer {token}

✔ Sample Response

{
  "data": {
    "timers": [
      {
        "id": 1,
        "name": "자바스크립트",
        "color": "#12231",
        "duration": 2000
      }
    ]
  },
  "status": "success"
}

✔ 사용 기술

• RetrofitClient(Hilt)
• TimerService
• TimerRepository
• TimerViewModel(Compose StateFlow)

---

🔄 하이브리드 라우팅 구조

Web → App	처리 방식
/timer 진입	WebViewClient에서 URL intercept → navController.navigate("timer")
App 내 BottomBar	Compose Navigation → home, search, timer 라우팅
WebView 하단바	Android 하단바와 중복되지 않도록 화면 조건부 렌더링

---

🤝 협업 규칙

Git Branch 전략

브랜치	설명
main	운영 배포
develop	개발 통합
feature/*	기능 개발 브랜치

Commit Convention

태그	설명
feat	새로운 기능 추가
fix	버그 수정
refactor	코드 리팩토링
style	UI/스타일
docs	문서
chore	설정 및 기타

---

📢 협업 도구

• GitHub
• Notion
• Discord

---

📅 Last Updated: 2025.11.24

✍️ Android maintained by sprinter-wtc team