오른 산을 지도에 찍다
산도장은 대한민국의 산을 지도에서 찾고, 오른 산에 도장을 찍고, 등산 기록과 사진을 기기 안에 보관하는 한국어 전용 모바일 앱입니다. 로그인과 백엔드 없이 설치 직후 사용할 수 있습니다.
- 첫 화면에서는 기록과 다음 행동에 집중하고, 산 검색 후 선택한 위치로 이동하는 OpenStreetMap 지도
- 130개 국내 산 로컬 시드 데이터, 검색·지역·완등·거리 필터
- 등산 기록 추가, 수정, 삭제, 사진 첨부, GPS 정상 근처 인증
- 완등 도장판과 첫 도장·5산·10산·30산·100산·명산 배지
- 실제 저장 기록 기반 월별·지역별·누적 고도·최근 기록 통계
- 시작, 일시정지, 재개, 종료, 앱 재실행 복원을 지원하는 등산 라이브 타이머
- 예상 시간 절반, 도착 임박, 초과 시점의 한국어 로컬 알림
- JSON 백업 내보내기·가져오기와 전체 기록 초기화
- SQLite 로컬 우선 저장, 로그인·백엔드·유료 지도 API 키 없음
| 홈 | 산 찾기·지도 | 도장판 | 통계 | 라이브 타이머 |
|---|---|---|---|---|
| 스크린샷 추가 예정 | 스크린샷 추가 예정 | 스크린샷 추가 예정 | 스크린샷 추가 예정 | 스크린샷 추가 예정 |
필요 환경:
- Node.js 20 이상
- npm
- Android Studio 에뮬레이터, iOS Simulator 또는 Expo 개발 빌드
git clone https://github.com/jomebe/Sandojang.git
cd Sandojang
npm install
npx expo start터미널에 표시된 안내에 따라 Android는 a, 웹은 w를 누릅니다. 알림, SQLite, 위치, 사진 기능을 정확히 확인하려면 Expo 개발 빌드 또는 실제 앱 빌드를 권장합니다.
검증 명령:
npm run typecheck
npm run lint
npm test
npx expo install --check환경 변수와 API 키는 필요하지 않습니다. 따라서 .env.example도 두지 않습니다.
app/ Expo Router 화면과 탭 내비게이션
(tabs)/ 지도, 산 목록, 도장판, 통계, 설정
mountain/ 산 상세
record/ 기록 추가·수정
session/ 라이브 세션 시작·진행·종료
src/
components/ 지도, 카드, 폼, 도장, 차트, 라이브 UI
context/ 앱 초기화와 공유 데이터 상태
data/mountains.json 앱에 포함되는 130개 산 시드
services/ 산, 기록, 세션, 권한, 알림, 백업, 통계
storage/database.ts SQLite 스키마와 초기 시드
tests/ 순수 로직 단위 테스트
theme/ 색상, 간격, 모서리, 그림자
types/ 데이터 모델
utils/ 거리, 시간, 날짜, 통계, 백업 검증
scripts/
fetch-mountains.mjs OpenStreetMap 산 데이터 재생성
generate-assets.ps1 앱 아이콘·스플래시 재생성
앱 시작 시 sandojang.db SQLite 파일을 열고 다음 테이블을 생성합니다.
mountains: 앱에 포함된 산 기본 정보climb_records: 날짜, 날씨, 난이도, 메모, 동행자, 시간, 사진 URI, 인증 방식hiking_sessions: 시작·일시정지·종료 시각과 마지막 위치photos: 기록별 사진 메타데이터
완등 상태는 별도 불리언으로 저장하지 않습니다. 해당 산에 유효한 등산 기록이 하나 이상 있는지 매번 계산합니다. 마지막 기록을 삭제하면 지도 핀과 도장판도 즉시 미완등으로 돌아갑니다.
src/data/mountains.json에는 한라산, 지리산, 설악산, 북한산 등 필수 명산을 포함한 130개 산의 이름, 지역, 고도, 실제 위도·경도가 들어 있습니다.
시드를 다시 만들려면:
npm run seed:mountains스크립트는 여러 OpenStreetMap Overpass 서버를 순서대로 시도하고 natural=peak, 한국어 이름, 고도 태그가 있는 실제 좌표를 정규화합니다. 외부 수집이 실패해도 검증된 대표 산 30개는 유지됩니다. 지도와 산 데이터 사용 시 OpenStreetMap 저작자 표시를 유지해야 합니다.
라이브 타이머는 setInterval 값 자체를 기록으로 사용하지 않습니다. 시작 시각, 누적 일시정지 시간, 예상 소요 시간, 도착 예상 시각을 SQLite에 저장하고 현재 시각과 비교해 다음 값을 계산합니다.
- 경과 시간과 남은 시간
- 예상 도착 시각
- 구간 진행률
- 마지막 GPS 위치에서 정상까지의 거리
앱이 종료되거나 운영체제가 프로세스를 정리해도 다음 실행에서 active 또는 paused 세션을 읽어 정확한 시간을 복원합니다. 동시에 하나의 등산 세션만 시작할 수 있습니다.
위치 권한은 선택 사항입니다. 권한이 있으면 가까운 산 정렬, 정상까지 거리, 300m 이내 정상 인증을 사용할 수 있습니다. 권한이 없거나 거리가 멀면 모든 기록 기능은 그대로 동작하고 수동 기록으로 저장됩니다.
모바일 운영체제의 백그라운드 제한 때문에 앱이 닫힌 동안 지속적인 위치 수집은 하지 않습니다. 앱이 열려 있고 세션이 진행 중일 때 일정 간격으로 위치를 갱신합니다.
등산 시작 시 알림 권한을 요청합니다. 허용된 경우 다음 알림을 한 번씩 예약합니다.
- 예상 소요 시간 절반 경과
- 예상 도착 약 10분 전
- 예상 시간을 15분 초과
세션을 종료하면 해당 세션의 예약 알림을 취소합니다. 권한이 거부되어도 라이브 타이머와 수동 기록은 정상 동작합니다.
설정 → 데이터 백업 / 내보내기에서 기록과 세션을 JSON 파일로 공유할 수 있습니다. 데이터 가져오기는 파일 구조와 버전을 검증한 뒤 현재 기록을 백업 내용으로 교체합니다.
사진 파일 자체는 JSON에 포함되지 않고 기기 URI 메타데이터만 들어갑니다. 다른 기기로 옮겨 사진 파일이 없으면 가져오기 완료 메시지에 누락 수를 표시하며 나머지 기록은 유지합니다. 가져오기 전 기존 데이터를 먼저 내보내는 것을 권장합니다.
EAS CLI 로그인 후 내부 배포 APK를 만듭니다.
npm install --global eas-cli
eas login
eas build --platform android --profile preview로컬 Android 네이티브 빌드 환경이 준비되어 있다면 다음 방식도 사용할 수 있습니다.
npx expo prebuild --platform android
cd android
.\gradlew.bat assembleRelease- 지도가 비어 있음: 지도 타일은 OpenStreetMap에서 받아오므로 인터넷 연결을 확인합니다. 기록과 통계 등 로컬 기능은 계속 사용할 수 있습니다.
- 위치를 찾지 못함: 기기 위치 서비스와 산도장 위치 권한을 확인합니다. 권한 없이 수동 기록도 가능합니다.
- 알림이 오지 않음: 운영체제 설정에서 산도장 알림을 허용하고 배터리 절전 예외를 확인합니다.
- JSON 가져오기 실패: 산도장에서 내보낸 버전 1 JSON인지 확인합니다. 손상되거나 다른 형식인 파일은 안전하게 거부됩니다.
- 사진이 보이지 않음: 백업은 사진 파일이 아닌 URI만 저장합니다. 원본 사진이 이동·삭제되었는지 확인합니다.
- 의존성 불일치:
npm install후npx expo install --check를 실행합니다. - 개발 서버 캐시 문제:
npx expo start --clear로 다시 시작합니다.
산도장은 기본적으로 기기 안에 기록을 저장합니다. 계정, 서버, 분석 SDK가 없으며 앱 데이터가 자동 업로드되지 않습니다. 내보내기 파일을 공유할 때는 메모와 위치 관련 기록이 포함될 수 있으므로 수신 대상을 확인하세요.