# 우리 동네 런닝 코스 — 첫 공개 버전 설계

작성: 2026-10-22 · 범위 갱신: 2026-10-23

## 목표

사용자가 **현재 사는 곳과 관계없이** 방문할 지역을 검색해 지도에서 걷기 자료와 쉼터를 살펴보는 웹앱이다. 첫 화면은 특정 지역을 자동 선택하지 않고 전국 지도를 보여준다. 평택 소사벌은 과거 첫 조사 지역이지만 시작 지역이나 우선 지역은 아니다. 지역 검색은 현재 위치 권한 없이 사용할 수 있다.

현재 버전에는 **앱 안의 따라 걷기 내비게이션을 넣지 않는다.** 사용자가 고른 두 지점 사이의 기본 도보 경로는 앱 지도에서 계산해 보여준다. 지도의 OSM 왕복 선은 별도 탐색 초안이며 공공 코스의 원본 선형과도 구분한다. 외부 카카오맵 도보 길찾기는 선택 지점을 넘기는 기능으로 유지한다.

## 사용자 흐름

1. 첫 화면에서 지역 이름을 검색하거나 지도를 이동한 뒤 중심을 탐색 지역으로 선택한다. ‘내 위치 주변 찾기’를 누르면 위치 권한을 요청해 그 주변 OSM 자료를 탐색한다. 특정 지역 자료는 선택 전까지 불러오지 않는다.
2. 선택 지역의 OSM 보행로·쉼터·벤치와 자료 조회 시각을 지도에서 본다. 등록 자료와 현장 상태의 차이를 명시한다.
3. 1·5·10km 탭에서 공공 코스 목록과 연결된 OSM 보행로의 왕복 탐색 초안을 살펴본다. 경기둘레길 코스를 고르면 일치하는 공식 경로선을 지도에 표시한다. 초안에는 **실제 계산한 거리**를 별도로 표시한다.
4. 지도에서 출발점과 도착점을 고르면 도보 경로 서버의 선형·거리를 지도에 표시한다. 걷기 또는 러닝의 가정 속도로 예상 시간을 본다. 필요하면 카카오맵 도보 길찾기도 연다.
5. 검색 지역은 URL로 다시 열 수 있다. URL에는 지역명만 포함하며 현재 위치와 직접 고른 지점은 넣지 않는다.

## 자료와 표시 기준

| 자료 | 현재 쓰임 | 표시 한계 |
| --- | --- | --- |
| 전국길관광정보표준데이터 | 시·군·구별 길명·길이·출발지 주소 목록 | 원본에 코스선 좌표가 없다. 시·군·구 전체 목록이며 현재 지도 중심 주변 목록은 아니다. 서버 비밀키가 필요하다. |
| 경기관광공사 경기둘레길 | 공공 목록의 경기둘레길 이름·번호가 공식 상세 페이지와 일치할 때 코스선을 지도에 표시 | 경기둘레길 이외 코스는 포함하지 않는다. 공식 선도 현재 통행 상태를 보장하지 않는다. |
| OpenStreetMap / Postpass | 선택 지역 약 1.2km의 보행로·쉼터·벤치와 왕복 탐색 초안 | 등록 누락·폐쇄·공사·시설 상태를 확인할 수 없다. 경로는 공식 코스가 아니다. |
| FOSSGIS 도보 경로 서버 | 사용자가 고른 두 점 사이의 기본 보행 경로선·거리 | 시험용 공개 서비스의 초당 1회 제한을 지킨다. 러닝 전용 경로나 원본 공공 코스선, 현재 통행 상태는 제공하지 않는다. |
| Nominatim | 사용자가 입력한 지역명과 공공 코스 출발지·도착지 이름·주소 검색 | 검색 지점은 지역 중심 또는 이름·주소 결과이며 실제 코스 입구·종점으로 확정하지 않는다. |
| 카카오맵 URL | 사용자가 고른 목적지, 수동 출발점 또는 최근 확인 위치의 외부 도보 길찾기 | 앱 안에서 계산한 경로와 카카오맵 경로가 일치한다고 보장하지 않는다. |

1·5·10km는 **산책 코스 또는 왕복 초안 자체의 길이**다. 현재 위치에서 시작점까지의 접근 거리와 섞지 않는다. OSM 초안은 연결된 보행로 그래프에서 목표 거리 ±20%의 원점회귀 선을 계산한다. 같은 5km 왕복길을 두 번 사용하는 10km 초안은 반복 사실을 표시한다. 초안 주변 쉼터는 선에서 60m 이내의 **직선거리** 기준이다.

공공 코스 API 조회와 OSM 조회는 앱 서버에서 수행한다. 브라우저에 서비스 키를 넣지 않는다. 서버는 조회 시각과 원본 자료의 기준일을 구분한다. 마지막 성공 응답은 OSM 10분, 공공 코스 6시간 캐시하며 수동 새로고침에도 최소 재조회 간격을 둔다. 이 방식은 조회 시점의 등록 자료를 보여줄 뿐 현장의 실시간 통행 상태를 뜻하지 않는다.

## 위치와 개인정보

현재 위치는 사용자가 위치 버튼을 눌렀을 때만 브라우저에서 읽는다. `내 위치 표시`만으로는 정확한 좌표를 앱 서버에 보내지 않는다. `내 위치 주변 찾기`는 좌표를 소수점 셋째 자리로 반올림해 앱 서버에 보내고, 서버가 OSM 자료 공급원과 Nominatim에 전달해 주변 자료와 시·군·구를 확인한다. 경로 지점 두 개를 고르면 좌표를 소수점 다섯째 자리로 반올림해 서버에 보내고 서버는 FOSSGIS에 전달한다. `내 위치를 출발점으로`를 명시적으로 누른 경우 최근 위치가 경로 요청에 포함된다. 해당 시·군·구의 공공 코스 목록은 현재 위치 반경이 아닌 행정구역 전체 목록으로 명시한다. 정확한 좌표와 마커는 5분 뒤 지우고, 반올림한 탐색 중심은 다른 지역을 선택할 때까지 유지한다. 좌표를 지역 공유 링크에 넣지 않는다. 수동 출발점과 도착점은 현재 탭에서만 유지하고 지역을 바꾸면 지운다. 카카오맵 링크를 열면 길찾기에 필요한 좌표가 카카오맵으로 전달된다. 지역명과 코스 출발지·도착지 이름·주소 검색어는 앱 서버를 거쳐 Nominatim에 전달된다.

## 첫 공개 버전의 완료 기준

- 특정 지역에 치우치지 않은 첫 화면과 지역 검색·지도·쉼터·거리 탭·외부 길찾기가 모바일과 데스크톱에서 동작한다.
- API 키가 없거나 지도 자료 제공자가 실패할 때 빈 자료인 척하지 않고 상태를 표시한다.
- 공공 코스 목록과 OSM 탐색 초안을 명확히 구분한다. 미검증 선을 실제 통행 안내로 표시하지 않는다.
- Node 서버와 정적 파일을 HTTPS 공개 주소에서 제공하고, 비밀키는 호스팅 환경변수로만 설정한다.
- [Roky Studio 기본 틀](../Roky%20Studio/PROJECT_BASELINE.md)에 따라 복귀 링크·개선 의견·업데이트 내역을 확인하고 공개 시 홈페이지의 프로젝트 카드와 의견 폼 선택지를 갱신한다.

현재 구현·검증·남은 작업은 [개발 기록](DEVELOPMENT_LOG.md), 배포 구조는 [배포 안내](DEPLOYMENT.md)에 기록한다. [처음 작성한 설계](DESIGN_ORIGINAL.md)는 범위 변경 기록으로 보존한다. 공식 코스 원본 자료 검증은 [소사벌 검증 계획](SOSABEOL_FIELD_CHECK.md)에 남겨 두되 첫 공개 버전의 앱 내 내비게이션 작업은 범위에서 제외한다.

