사이길 — 장소 사이의 거리 측정

출발지와 도착지를 Nominatim에서 검색하고 결과를 선택하면, OSRM 자동차 경로의 총거리와 예상 시간을 표시합니다. 거리 아래 지도에서 보기를 누르면 선택한 좌표의 OpenStreetMap 길찾기를 새 탭에서 엽니다. 화면 지도에도 선택한 장소와 실제 경로를 표시합니다.

로컬 실행

Node.js 22.12 이상을 설치하고 프로젝트 폴더에서 실행합니다.

npm install
npm run dev

http://localhost:5173 에서 확인합니다. Windows PowerShell에서 npm 스크립트 실행이 차단되면 npm.cmd install, npm.cmd run dev를 사용합니다. 로컬 개발에서는 메모리 캐시와 단일 프로세스 요청 제한을 사용하므로 별도 키 없이 테스트할 수 있습니다. 환경변수는 .env.example을 .env.local로 복사하여 설정합니다. 로컬 개발 서버는 한 개만 실행하세요.

GitHub → Vercel 배포

1. 이 폴더의 소스를 GitHub 저장소에 올립니다. node_modules, dist, .env.local, .npm-cache는 제외됩니다. package-lock.json은 포함하세요.
2. Vercel에서 Add New → Project → GitHub 저장소 Import를 선택합니다.
3. Framework Preset은 Vite, Build Command는 npm run build, Output Directory는 dist입니다. Root Directory는 이 프로젝트 루트입니다. API는 루트 api/의 Vercel Functions로 배포됩니다.
4. Vercel Marketplace에서 Upstash Redis 데이터베이스를 생성해 연결하거나, 기존 Upstash 데이터베이스의 REST URL과 토큰을 아래 환경변수에 설정합니다. 하나의 앱에 연결된 모든 배포는 같은 Redis를 사용하세요.
5. 아래의 필수 환경변수를 Production과 Preview에 설정하고 Deploy합니다. 이미 배포한 뒤 설정했다면 Redeploy합니다.

환경변수	설정	용도
UPSTASH_REDIS_REST_URL	필수	Upstash Redis REST URL
UPSTASH_REDIS_REST_TOKEN	필수	Upstash Redis REST Token (서버 전용 비밀값)
NOMINATIM_USER_AGENT	배포 전에 설정	Saigil/1.0 (https://실제앱주소.vercel.app; 연락용이메일)처럼 앱 식별 및 연락 정보
NOMINATIM_URL	선택	기본 https://nominatim.openstreetmap.org
OSRM_URL	선택	기본 https://router.project-osrm.org

Vercel 공개 배포에서는 Redis가 없으면 장소 검색 API가 503으로 응답합니다. 여러 서버 인스턴스의 요청을 합산해 Nominatim의 앱 전체 제한을 지키기 위한 동작입니다. 환경변수에 VITE_ 접두사를 붙이지 마세요. API 키와 Redis 토큰은 브라우저에 전달하지 않습니다. GitHub 저장소 생성 및 Vercel 배포는 사용자가 진행하며, 이 프로젝트는 자동 게시하지 않습니다.

거리 기준과 API 정책

• Nominatim은 장소명 → 좌표 검색을 담당합니다. 등록되지 않은 장소는 검색되지 않을 수 있으므로 지역명 또는 주소로 다시 검색하세요.
• 입력 중 자동완성 요청을 보내지 않습니다. 검색 버튼 또는 Enter를 눌렀을 때만 검색합니다.
• 공개 Nominatim 요청은 공유 잠금으로 직렬화하고 완료 후 1.2초 간격을 둡니다. 같은 검색어 결과는 Redis에 24시간 보관합니다. 혼잡할 때는 사용자가 다시 검색하도록 안내합니다.
• 총거리는 OSRM이 반환한 자동차 도로 경로 거리입니다. 최단거리·실시간 교통·도보·대중교통 경로를 보장하지 않습니다. 연결 불가 시 직선거리로 바꾸지 않고 오류를 표시합니다. 도로 스냅 지점이 선택 장소에서 2 km보다 멀면 재선택을 안내합니다.
• 지도 링크는 같은 두 좌표로 OpenStreetMap 길찾기를 엽니다. 지도 서비스 데이터나 계산 시점에 따라 그곳의 거리 표시는 달라질 수 있습니다.
• 개인 정보 또는 기밀 주소를 입력하지 마세요. 검색어와 좌표는 각각 외부 지도 서비스로 전송됩니다. 지도 타일과 글꼴도 외부 서비스에서 불러옵니다.
• 공개 Nominatim 및 OSRM 서버는 외부 공용 서비스입니다. 상용·대규모 서비스로 확장할 때는 서비스 제공자 정책을 확인하고 전용 인스턴스나 적절한 제공자로 변경하세요. 사용자 입력은 외부 API 호스트로 사용하지 않으며 서버 환경변수로만 제공자를 변경합니다.

참고: Nominatim 사용 정책, OSRM API, OSM 타일 사용 정책, Vite on Vercel

검증과 구조

npm test
npm run build

npm test는 실제 공용 API에 요청하지 않고 입력 검증, 거리 표시, 지도 링크, 경로 성공·실패 처리, 공유 캐시 및 요청 제한을 검사합니다. npm run preview는 빌드된 정적 화면만 제공하므로 API를 포함한 로컬 확인에는 npm run dev를 사용하세요.

api/geocode.js    Vercel 장소 검색 API
api/route.js      Vercel 자동차 경로 API
lib/services.js  공유 캐시·요청 제한·외부 API 처리
src/             화면 및 Leaflet 지도
server.mjs       로컬 Vite + API 개발 서버
tests/           Node.js 내장 테스트
vercel.json      Vercel 빌드 설정