🚕 taxi-pitstopmap
택시 기사를 위한 주정차 가능 식당·화장실 안내 서비스
📌 프로젝트 소개
택시 기사는 식사와 화장실이 급해도, 근처에 식당이나 화장실이 있더라도 차를 세울 곳이 없어 헤매거나 주정차 단속을 걱정해야 합니다.
기존 지도 앱은 "장소"는 알려주지만 "그 앞에 차를 세울 수 있는지"는 알려주지 않습니다.
taxi-pitstopmap은 현재 위치에서 차를 세우고 바로 이용할 수 있는 식당과 화장실을 보여줍니다.
🎯 프로젝트 목표
- 실제 택시 기사의 불편을 해결하는 서비스 구현
- 바이브 코딩(AI 활용 개발) 학습 및 개발 과정 기록
- 동작하는 데모와 실사용자 피드백 확보
✨ 주요 기능
MVP
예정
🧠 핵심 아이디어: 주정차 점수
주정차 가능 여부를 직접 제공하는 무료 API는 없기 때문에, 세 가지 데이터를 조합합니다.
| 데이터 층 | 출처 | 신뢰도 |
|---|
| 공식 데이터 | 공공주차장, 주정차 허용/금지 구간 | 높음 (커버리지 낮음) |
| 추정 데이터 | 자체 주차장 여부, 인근 공영주차장 거리, 도로 유형 | 중간 |
| 사용자 제보 | 기사들의 "세울 수 있음 / 단속됨" 제보 | 시간이 갈수록 높아짐 |
설계상 점수 예시: 자체 주차장(+40) + 100m 내 공영주차장(+30) + 최근 30일 내 "가능" 제보(+30) − "단속됨" 제보(−40)
현재 구현된 점수 — 택시 기사는 공영주차장을 잘 쓰지 않으므로 "주차 자리 제공 → 도로변 주차" 순으로 봅니다.
| 구분 | 근거 | 점수 |
|---|
| 주차 자리 제공 (가장 큰 값 하나) | 제보 2명 이상 / 1명 | 60 / 50 |
| 가게와 이름이 겹치는 민영주차장 150m 이내 (추정) | 40 |
| 같은 건물(주소 끝 일치)이거나 30m 이내 민영주차장 (추정) | 30 |
| 도로변 주차 (최대 45) | 노상주차장 100m 이내 | +30 |
| '도로변에 세움' 제보 1명 / 2명 이상 | +15 / +30 |
| 보조 | 공영주차장 200m 이내 / 다른 민영주차장 100m 이내 / 주변 주차장 10곳 이상 | 각 +5 |
| 감점 | 🔴 단속됨 1명 / 2명 이상 | −20 / −40 |
| ⚪ 세울 곳 없었음 1명 / 2명 이상 | −10 / −15 |
합계는 0100점으로 제한, 🟢 60 이상 · 🟡 3059 · 🔴 30 미만. 그래서 🟡 이상은 주차 자리 제공이나 도로변 주차의 근거가 있는 곳이고, 주변에 주차장이 많다는 것만으로는 🟡이 되지 않습니다. "주차 가능" 필터는 🟡 이상(30점 이상)입니다. 이름에 '거주자'가 들어간 주차장(거주자우선·전용)은 외부 차량이 쓸 수 없어 뺍니다. 규칙은 supabase/migrations/0008_store_and_roadside_parking.sql의 score_places() 한 곳에서 조정합니다.
제보 종류: 🟢 주차 자리 제공됨 · 🟢 도로변에 세움 · 🔴 단속됨 · ⚪ 세울 곳 없었음 (최근 30일, 서로 다른 사용자 수 기준). 제보가 쌓이면 이름·주소로 한 추정보다 제보가 우선합니다.
한계 (중요): 가게가 주차 자리를 제공하는지 알려 주는 공공데이터는 없습니다. 현재는 카카오 주차장 데이터의 이름·주소·거리로 "추정"만 하며, 서울 식당 약 1,400곳을 살펴보니 추정 근거가 있는 곳이 약 48%, 근거가 없는 곳이 약 52%였습니다. 도로변도 주정차 허용·금지 구간 데이터가 없어서 노상주차장(도로에 그어진 주차구획)과 제보만 씁니다. 실제로 세울 수 있는지는 제보가 쌓여야 정확해지며, 화면에도 "추정, 현장 확인 필요"라고 안내합니다. 가중치는 가정값이고 실제 기사 피드백으로 검증되지 않았습니다.
데이터가 없는 지역은 "점수 없음"(⚪): 장소 반경 500m 안에 주차장 데이터가 하나도 없으면 🔴가 아니라 점수 없음으로 표시하고 안내를 띄웁니다. (현재 주차장 데이터는 서울 전역(카카오 주차장 약 9,300곳)이고, 서울 밖은 "세울 수 없음"이 아니라 "알 수 없음"입니다. 화장실도 서울 전역입니다: 공공데이터 약 5,400곳 + OSM 보강.) 이런 지역에 제보가 있으면 중립 30점에서 제보만큼 가감합니다.
🏗 아키텍처
[모바일 웹앱 (PWA)]
│
▼
[백엔드 API] ──► [PostgreSQL + PostGIS (Supabase)]
│
├─► 카카오 로컬 API (식당·장소 검색)
├─► 공공데이터포털 (공중화장실, 주차장)
├─► OpenStreetMap / Overpass API
└─► 카카오맵 JS SDK
🛠 기술 스택
| 영역 | 기술 |
|---|
| Frontend | Next.js 16, React 19, TypeScript, Tailwind CSS 4 |
| Map | Kakao Map JS SDK |
| Backend / DB | Supabase (PostgreSQL, PostGIS, Auth) |
| Deploy | Vercel |
| Data | Python (공공데이터 전처리) |
| Dev | GitHub, 바이브 코딩 도구 (Claude 등) |
🚀 시작하기
개발 초기 단계로, 아래 내용은 구현 진행에 따라 업데이트됩니다.
요구 사항
- Node.js 20 이상 (LTS 권장)
- Python 3.11 이상 (데이터 적재 스크립트용)
- 카카오 개발자 계정: JavaScript 키, REST API 키, 웹 플랫폼에
http://localhost:3000 등록, 카카오맵 사용 설정
- Supabase 프로젝트 (PostGIS 사용, 제보 기능은 Authentication → Sign In / Providers 에서 Allow anonymous sign-ins 활성화 필요)
설치 및 실행
git clone https://github.com/jeongsemin/taxi-pitstopmap.git
cd taxi-pitstopmap
npm install
cp .env.example .env.local # 환경변수 입력
npm run dev
환경변수
NEXT_PUBLIC_KAKAO_MAP_KEY= # 카카오 JavaScript 키
KAKAO_REST_API_KEY= # 카카오 REST API 키 (서버 전용)
NEXT_PUBLIC_SUPABASE_URL= # https://<프로젝트ID>.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY= # publishable(anon) 키
SUPABASE_DB_PASSWORD= # 데이터 적재 스크립트 전용
SUPABASE_DB_HOST= # IPv4 환경에서 Session pooler 호스트 (선택)
⚠️ .env 파일은 절대 커밋하지 말것. SUPABASE_DB_PASSWORD에는 NEXT_PUBLIC_ 접두사를 붙이지 않습니다.
데이터 준비
앱은 Supabase DB에 적재된 화장실·주차장 데이터를 사용합니다. 프로젝트 루트에서 실행합니다.
pip install -r data/requirements.txt
python data/scripts/apply_migrations.py # 테이블·함수 생성
python data/scripts/load_osm_toilets.py --area 서울특별시 --level 4 # OSM 화장실 (서울 전체)
python data/scripts/load_public_toilets.py --csv data/raw/공중화장실정보_서울특별시.csv # 공공데이터 화장실 (CSV 필요, 카카오 주소 변환)
python data/scripts/load_parking_lots.py --region seoul # 카카오 주차장 (서울, 카카오 호출 약 2천 회)
- 공공 화장실 CSV는 localdata.go.kr에서 지역별로 내려받아
data/raw/gangnam_restroom.csv로 저장합니다. (data/raw/는 커밋되지 않습니다)
- 원천 데이터에 좌표가 없어 카카오 주소 검색으로 지오코딩합니다.
- Supabase 직접 접속은 IPv6 전용이라 IPv4 환경에서는
SUPABASE_DB_HOST에 Session pooler 호스트를 지정합니다.
🧪 테스트
| 명령 | 내용 | 필요한 것 |
|---|
npm test | 호출 제한, 점수 등급, 거리 계산, 지도 앱 주소, 카카오 캐시·호출 상한·한도 초과 보호, 점수 결과 캐시, 오류 알림 메일, 공개 API(/api/places, /api/log, /api/consent)의 입력 검증·호출 제한 (54개) | Node 22.18 이상 (Node 24 로 확인). 새 패키지 없이 Node 내장 테스트 도구를 씁니다. |
npm run test:db | 점수 규칙(가게 주차·도로변·보조·제보 가감·100점 상한·30일), 제보 입력 검증과 중복·하루 한도, 오류·동의·호출량 기록 함수, 오류 알림 제한 (32개) | .env.local 의 DB 접속 정보, Python 데이터 환경(data/requirements.txt) |
npm run test:all | 위 둘을 차례로 | 위 둘 |
test:db 는 운영 DB 에 연결하지만 데이터를 남기지 않습니다. 시험마다 가짜 주차장·제보·계정을 트랜잭션 안에 넣고 끝나면 모두 되돌립니다. 가짜 주차장은 서해 한가운데(북위 36, 동경 125)에 두며, 실제 주차장이 근처에 있으면 시험을 시작하지 않습니다. 접속 정보가 없으면 건너뜁니다.- 점수 가중치나 제보 규칙을 바꾸면
tests/test_database.py 의 기대 점수도 같이 고치세요. 그래야 규칙이 의도와 다르게 바뀌는 것을 잡을 수 있습니다.
- 화면(지도 조작, 터치, 위치 권한, 지도 앱 실행, 홈 화면 설치)은 자동 테스트로 확인하지 않습니다. 폰에서 직접 확인하세요. 카카오·Supabase 는 가짜로 바꿔서 시험하므로 실제 서비스와의 연결 자체는 확인하지 못합니다.
🗺 로드맵
| 단계 | 내용 | 상태 |
|---|
| 0 | 저장소·프로젝트 세팅, 데이터 조사 | ✅ 완료 |
| 1 | 지도 표시 + 주변 식당 검색 | ✅ 완료 |
| 2 | 공중화장실 데이터 적재 | ✅ 완료 |
| 3 | 주정차 점수 로직 | ✅ 완료 |
| 4 | 사용자 제보 기능 | ✅ 완료 |
| 5 | PWA 설정 및 배포 | ⬜ |
| 6 | 실사용 테스트 (택시 기사 3~5명) | ⬜ |
초기 대상 지역은 한 개 구 단위로 한정해 데이터 품질과 테스트를 관리합니다.
📂 문서
🌿 브랜치 및 커밋 규칙
- 브랜치:
main(배포) / dev(개발) / feature/*
- 커밋:
feat: fix: docs: chore:
📝 개발 기록
- 공중화장실 좌표 제거: 공공데이터 원천에서 2025년 2월부터 위·경도가 빠져 카카오 주소 검색으로 지오코딩했습니다. 390건 중 381건(98%)이 변환되었습니다.
- Supabase IPv6: 직접 접속 주소가 IPv6 전용이라 IPv4 환경에서는 Session pooler 호스트로 접속합니다.
- 카카오 45건 한도: 카테고리 검색은 한 번에 최대 45건이라 주차장은 영역을 타일로 나눠 조회하고, 한도에 걸리면 4등분해 재조회합니다.
- 식당 조회와 한도: 반경 안 식당이 매우 많아(강남역 500m 826곳, 1km 1,980곳, 2km 5,376곳) 45건만 받으면 중심 주변만 보였습니다. 이제 반경을 격자 칸으로 나눠 가까운 칸부터 한 번에 최대 24회까지 호출해 약 320곳까지 받아 오고, 전부 받지 못하면 실제 개수와 함께 화면에 안내합니다. 반경이 커도 호출 상한 때문에 중심 약 400m까지만 채워지는 한계가 있습니다. 같은 위치 조회는 서버에서 1분간 캐시합니다.
- 조회 실패 표시: 장소를 불러오지 못하면 지도·목록에 오류 문구와 "다시 시도" 버튼을 보여 주고, 이전 결과가 남아 있으면 그 사실도 알립니다.
- 위치정보 이용 동의: 위치를 읽기 전에 동의 화면(
LocationConsent)을 보여 주고, 동의 버튼을 눌러야만 위치를 요청합니다. 동의하지 않아도 강남역 기준으로 쓸 수 있고, 설정 탭에서 언제든 철회·재동의할 수 있습니다. 동의 문구를 바꾸면 src/lib/legal.ts의 LOCATION_CONSENT_VERSION을 올려야 모두에게 다시 동의를 받습니다. 동의·거부·철회 기록은 consent_logs에 무작위 번호·문구 버전·시각만 남깁니다(법적 충분성은 보증되지 않음, 아래 배포 가이드 8번 참고).
- 자동 테스트:
npm test(핵심 로직 54개, 몇 초, 외부 연결 없음)와 npm run test:db(점수 규칙·제보 검증 등 DB 규칙 32개)로 돌립니다. 자세한 내용은 아래 "테스트" 절을 참고하세요.
- 개인정보·위치정보 안내: 설정 탭과 제보 영역에서 연결되는
/privacy 화면입니다. 앱이 실제로 하는 일(위치는 한 번만 읽고 저장하지 않음, 제보는 익명 계정으로 저장, 오류 기록 30일 보관 등)을 그대로 적었으니, 동작을 바꾸면 src/app/privacy/page.tsx도 함께 고치세요.
- 카카오 API 한도 대비: 서울에서는 새 조회 한 번이 카카오 로컬 API를 20번 부릅니다(측정). CDN 2분·서버 30분 캐시, 카카오 실패 시 옛 결과 대체, 한도 초과(429) 시 10분 호출 중단과 안내, 호출량 기록(
show_usage.py), 호출 상한 조절(KAKAO_MAX_CALLS)을 넣었습니다. 자세한 내용은 배포 가이드 9번을 참고하세요.
- 오류 모니터링: 서버·화면 오류를 외부 서비스 없이 Supabase
error_logs 에 쌓습니다(좌표·IP·계정 미저장). python data/scripts/show_errors.py 로 봅니다. 오류가 나면 메일로 알려 줍니다(Resend 키와 받는 주소를 환경변수에 넣어야 켜지고, 같은 종류는 60분에 한 번·하루 20통까지). 자세한 내용은 배포 가이드를 참고하세요.
- 마커 겹침과 터치 영역: 식당이 수백 곳이라 마커가 겹쳐서, 카카오맵 클러스터 라이브러리로 멀리서 볼 때 식당을 숫자 원으로 묶습니다(묶음을 누르면 확대, 더 확대하면 개별 마커). 🟢 주차 가능 식당, 화장실, 선택한 장소는 묶지 않고 항상 개별로 보입니다. 마커의 보이는 크기는 23px로 두고, 투명 여백으로 눌리는 영역만 40px로 넓혔습니다.
- 뒤로가기: 장소 상세를 열 때, 그리고 지도에서 목록·설정 탭으로 갈 때 브라우저 기록을 한 칸 쌓아, 모바일 뒤로가기 버튼이 사이트를 벗어나지 않고 상세 → 목록/설정 → 지도 순으로 한 단계씩 돌아갑니다. 목록↔설정 이동은 기록을 쌓지 않고 바꿔 끼웁니다.
- 일부만 실패해도 보여 주기: 식당(카카오)과 화장실(DB) 중 한쪽이 실패해도 나머지는 보여 주고 "나머지만 보여 드려요" 안내와 재시도 버튼을 띄웁니다. 점수 계산만 실패한 경우도 안내합니다. 요청한 종류가 전부 실패할 때만 오류로 처리합니다.
📄 라이선스
Copyright © 2026 jungsemin. All Rights Reserved.
본 저장소의 코드는 저작권자의 허락 없이 복제, 수정, 배포, 상업적 이용을 할 수 없습니다.
🙏 데이터 출처
- 카카오 로컬 API / 카카오맵 (식당, 주차장, 주소 검색)
- 공공데이터포털·행정안전부 공중화장실정보 (localdata.go.kr)
- © OpenStreetMap contributors
각 데이터의 이용약관을 준수합니다.
