Skip to content

README.md

Latest commit

 

History

History
257 lines (187 loc) · 7.6 KB

README.md

File metadata and controls

257 lines (187 loc) · 7.6 KB

Running Tracker 🏃‍♂️

Running Tracker는 사용자의 러닝 활동을 기록하고 시각적으로 확인할 수 있는
안드로이드 러닝 트래커 애플리케이션입니다.
Kotlin과 Jetpack Compose를 기반으로 MVVM 아키텍처를 적용해 개발되었습니다.

러닝 중 경과 시간과 이동 경로를 실시간으로 확인할 수 있으며,
단순하고 직관적인 UI를 목표로 설계되었습니다.

✨ 주요 기능 (Key Features)

  • 러닝 타이머

    • ViewModel에서 직접 관리되는 코루틴 기반 타이머
    • Start / Pause / Stop 동작 분리
    • Pause 후 Start 시 시간 유지, Stop 시에만 초기화

  • 실시간 위치 경로 표시

    • Google Maps Compose를 활용한 러닝 경로 시각화
    • 러닝 중 이동한 경로를 Polyline으로 지도에 표시

  • 상태 기반 UI

    • UI는 ViewModel의 StateFlow만 구독
    • 비즈니스 로직과 UI 로직을 명확히 분리

  • 의존성 주입

    • Koin을 활용한 ViewModel 및 위치 클라이언트 주입
    • 테스트 및 확장에 용이한 구조

🛠 기술 스택 (Tech Stack)

  • Language: Kotlin
  • UI: Jetpack Compose (Material3)
  • Architecture: MVVM
  • State Management: StateFlow
  • Asynchronous: Kotlin Coroutines
  • Dependency Injection: Koin
  • Maps: Google Maps Compose
  • Location: FusedLocationProviderClient

🚀 설치 및 실행 (Getting Started)

1) 사전 준비

  • Android Studio (최신 안정 버전 권장)
  • JDK 17 (Android Studio 내장 JDK 사용 가능)
  • Google Maps API Key

2) 프로젝트 클론

git clone <repo-url>
cd RunningTracker

3) Google Maps API 키 설정

app/src/main/res/values/google_maps_key.xml 파일을 생성하고 아래 내용을 추가하세요.

<resources>
    <string name="google_maps_key" translatable="false">YOUR_API_KEY</string>
</resources>

출시 기준 권장 설정:

  • 디버그/릴리스 API 키를 분리해서 사용
  • Google Cloud Console에서 Maps SDK for Android 활성화
  • API 키 제한(Application restrictions) 설정:
    • Android apps
    • 패키지명: com.example.runningtracker
    • SHA-1 인증서 지문: 디버그/릴리스 각각 등록
  • API restrictions에서 Maps 관련 API만 허용

참고:

  • google_maps_key.xml은 .gitignore에 포함되어 있으므로 저장소에 커밋되지 않습니다.
  • 릴리스 빌드 전 실제 릴리스 keystore 기준 SHA-1로 동작 확인이 필요합니다.

4) 앱 실행

  • Android Studio에서 프로젝트를 연 뒤 에뮬레이터 또는 실제 기기에서 실행
  • 또는 터미널에서 디버그 빌드:
./gradlew assembleDebug

Windows:

gradlew.bat assembleDebug

🔐 권한 및 개인정보 처리 (출시 기준)

권한 사용 목적

  • ACCESS_FINE_LOCATION, ACCESS_COARSE_LOCATION: 러닝 중 위치 추적 및 경로 표시
  • FOREGROUND_SERVICE, FOREGROUND_SERVICE_LOCATION: 러닝 중 백그라운드 위치 추적 유지
  • POST_NOTIFICATIONS (Android 13+): 포그라운드 서비스 알림 표시

수집/저장 데이터 (현재 구현 기준)

  • 러닝 기록: 시작 시각, 총 운동 시간, 평균 속도, 이동 거리
  • 위치 데이터: 러닝 경로 표시를 위해 실시간 사용
  • 저장 위치: 기기 내부 Room DB (running_database)

외부 전송 및 제3자 제공 (현재 구현 기준)

  • 별도 백엔드 서버로 러닝 기록을 전송하지 않음
  • Google Maps SDK 사용으로 지도 표시 관련 네트워크 통신이 발생할 수 있음

사용자 안내

  • 위치 권한이 없으면 위치 기반 기능이 동작하지 않음
  • 권한은 기기 설정에서 언제든 변경 가능

실제 스토어 출시 시에는 별도의 Privacy Policy 문서(URL)와 Play Console 데이터 보안 양식 내용을 본 섹션과 일치시키세요.

📄 Privacy Policy

  • 정책 URL: https://example.com/running-tracker/privacy
  • 출시 전 위 URL을 실제 공개 문서 주소로 교체하세요.
  • 앱 내 설정 화면/온보딩, Play Store 등록 정보(개인정보처리방침)와 동일한 URL을 사용하세요.

📦 지원 범위 (Compatibility)

  • minSdk: 24 (Android 7.0)
  • targetSdk: 36
  • compileSdk: 36
  • 언어/런타임: Kotlin + JVM 11 타겟

실행 요구사항:

  • 위치 서비스(GPS) 사용 가능 기기
  • 지도 로딩 및 위치 처리 시 네트워크 연결 권장

검증 권장 범위(출시 전):

  • Android 7/8/10/13 이상 버전별 기본 동작 점검
  • 권한 거부/재허용, 백그라운드 전환, 배터리 절전 모드 시나리오 점검

🏗 릴리스 빌드 가이드 (Release)

현재 설정 기준:

  • release 빌드 타입 존재
  • 코드 축소/난독화: isMinifyEnabled = false
  • Google Maps API 키는 릴리스 키(SHA-1) 기준으로 별도 검증 필요

빌드 명령:

./gradlew bundleRelease

Windows:

gradlew.bat bundleRelease

출력 경로:

  • app/build/outputs/bundle/release/

스토어 배포 전 필수 체크:

  • 업로드용 서명 키(keystore)로 서명된 AAB 생성
  • versionCode/versionName 업데이트
  • 릴리스 빌드에서 지도/위치/알림 권한 흐름 최종 점검
  • ProGuard/R8 적용 계획이 있다면 난독화 후 회귀 테스트 수행

🧱 프로젝트 구조 (간략)

app/
├─ presentation/
│ ├─ running/
│ │ ├─ RunningScreen.kt
│ │ ├─ RunningViewModel.kt
│ │ └─ RunningUiState.kt
│ ├─ ButtonControls.kt
│ └─ RunningMap.kt
├─ location/
│ └─ LocationClient.kt
├─ di/
│ └─ appModule.kt
└─ util/
└─ TimeFormatter.kt

📱 실행 화면

러닝 화면

초기 화면 러닝 시작

상태 변화 / 기록

일시정지 러닝 기록

🆕 업데이트 (2026.01.07)

1. 러닝 로직 분리 (리팩토링)

서비스 코드 복잡도를 줄이기 위해 핵심 로직을 역할 단위로 분리했습니다.

  • RunTimer

    • 시간 측정 전용 컴포넌트

    • 코루틴 기반, 순수 비즈니스 로직

  • RunLocationTracker

    • 위치 수집 전용 컴포넌트

    • LocationClient를 통해 Flow 기반 위치 스트림 처리

RunningService
├─ RunTimer (시간 측정)
└─ RunLocationTracker (위치 수집)
  • 서비스는 오케스트레이션 역할만 담당하도록 정리
  • 테스트 및 유지보수 용이성 향상

2. 배터리 상태 기반 러닝 제어

  • BroadcastReceiver 기반 배터리 상태 감지

  • Android 시스템 브로드캐스트(ACTION_BATTERY_CHANGED) 활용

동작 규칙:

러닝 시작 시

  • 배터리 30% 이하 → 경고 메시지 표시 (운동은 시작 가능)

러닝 중

  • 배터리 20% 이하 → 자동으로 러닝 종료 + 기록 저장

사용자 경험을 해치지 않으면서 안정성 확보

3. 테스트 코드 추가 (JVM 단위 테스트)

  • Robolectric + coroutines-test 기반 단위 테스트 작성

  • Android 의존성이 없는 핵심 로직 위주로 테스트

테스트 대상: RunTimer

  • start / pause / stop 동작 검증

  • 시간 증가 및 초기화 로직 확인