🗿 제주 역사문화 스탬프 투어

제주의 역사문화 장소 120곳을 찾아 스탬프를 모으고, 마음에 드는 곳을 찜해 나만의 답사 코스를 만드는 웹 사이트입니다. 장소 자료는 공공데이터포털 API에서 불러오고, 날씨는 기상청 초단기실황을 보여 줍니다.

실행 방법

Node.js LTS가 필요합니다.

npm install
copy .env.example .env.local     # 그리고 .env.local 에 인증키 입력
npm run dev                      # http://localhost:5173

명령	설명
npm run dev	개발 서버 실행
npm run build	dist/ 로 빌드 (상대 경로라 하위 주소에 올려도 동작)
npm run update-weather	기상청 API로 날씨 스냅샷(src/data/weather-data.js) 갱신

인증키 (.env.local)

VITE_DATA_API_KEY=공공데이터포털_일반_인증키

• 제주특별자치도_제주역사문화 위치정보/일반정보 API 활용 신청이 승인된 키여야 합니다.
• .env.local 은 Git에 올라가지 않습니다(.gitignore).
• ⚠️ VITE_ 로 시작하는 값은 브라우저로 전달되는 코드에 포함됩니다. 개인 학습·로컬 실행용으로만 쓰고, npm run build 결과를 인터넷에 공개하면 키가 노출되니 주의하세요.
• 키가 없거나 틀려도 화면은 깨지지 않고 연습 모드로 동작합니다. (아래 참고)

데이터는 이렇게 불러옵니다

접속 ──▶ "불러오는 중" 표시 ──▶ API 호출 ─┬─ 성공 ─▶ 실시간 자료로 화면 표시
                                          └─ 실패 ─▶ 1단계 파일 데이터 + "연습 모드" 안내

상황	화면에 나오는 것
불러오는 동안	회전 표시와 "장소 정보를 불러오는 중이에요…"
성공	하단에 📡 장소 자료: 공공데이터포털 API 실시간 조회 (시각)
실패	맨 위 노란 🧪 연습 모드 배너 + 실패 이유 + 다시 시도 버튼, 하단에 🧪 장소 자료: 1단계 파일 데이터 (연습 모드)

실패 이유는 인증키 없음 / 인증키가 올바르지 않거나 승인되지 않음(HTTP 401) / 서버 오류 / 10초 안에 응답 없음 / 네트워크 오류 / 자료 형식 오류로 구분해 보여 줍니다. (인증키 값은 어디에도 출력하지 않습니다.)

• API: 위치정보 15109570 + 일반정보 15109587 을 데이터 고유번호로 합칩니다.
• 연습 모드의 1단계 파일 데이터(src/data/step1-data.js)는 같은 120곳이라 화면은 똑같이 쓸 수 있습니다.
• 연습 모드 확인: .env.local 의 키를 지우고 새로고침 (확인 후 키를 다시 넣어 두세요).

화면 구성

화면은 2개(메인 화면, 장소 상세 화면)이고, 자료를 불러오는 상태에 따라 상태 화면 2개(불러오는 중, 연습 모드)가 더해집니다.

1. 메인 화면 — 스탬프 투어

위에서 아래로 다음 순서입니다.

영역	보여 주는 것
① 헤더	사이트 제목과 한 줄 설명
② 연습 모드 배너	API 실패 시에만 표시. 이유와 다시 시도 버튼
③ 내 스탬프 현황	등급(7단계), 전체 진행률 n / 120, 다음 등급까지 남은 개수, 제주시·서귀포시별 진행률
④ 제주 지역 날씨	제주시·서귀포시의 기온·습도·강수·바람, 관측 시각, 오늘 투어 안내 한 줄
⑤ 검색 조건	검색어, 테마 투어, 분류, 지역, 스탬프 상태, 정렬(내 위치에서 가까운 순 포함), 찜만 보기, 초기화
⑥ 장소 카드 목록	장소 120곳 카드: 분류, 코스 번호, ♡ 찜, 장소명, 제목, 주소, 스탬프 찍기 또는 방문 도장
⑦ 오른쪽 패널 (모바일은 목록 위)	스탬프 지도 (제주도 윤곽, 확대·이동, 코스 선) · 테마 투어 (9개, 진행률·완주 배지) · 나만의 답사 코스 (순서 변경, 구간 거리, 길찾기·복사) · 최근 스탬프 (내 기록 백업)
⑧ 하단	장소 자료가 API 실시간인지 연습 모드인지, 자료 출처

2. 장소 상세 화면 (팝업)

카드, 지도의 점, 코스 목록, 최근 스탬프를 누르면 열립니다.

영역	보여 주는 것
상단 버튼	스탬프 찍기/취소, 찜하기/해제, 닫기
스탬프 투어	스탬프 상태(날짜, 현장 인증/직접 체크), 소속 테마 투어
방문 메모	스탬프를 찍은 곳에서만 보임. 200자까지 기록
위치정보	장소명, 주소, 우편번호, 위도·경도, 구글 지도 링크, 원본 상세 보기 링크
일반정보	분류, 제목, 저작자, 주제, 발행 정보 등
내용	내용, 초록, 목차, 참고문헌

3. 상태 화면

• 불러오는 중: API 응답을 기다리는 동안 전체 화면에 회전 표시를 보여 줍니다.
• 연습 모드: 메인 화면 맨 위의 노란 배너입니다. 나머지 기능은 모두 그대로 쓸 수 있습니다.

폴더 구조

index.html              진입 페이지 (불러오는 중 / 연습 모드 영역 포함)
vite.config.js          Vite 설정
.env.example            인증키 예시 (복사해서 .env.local 로 사용)
update-weather.mjs      기상청 날씨 스냅샷 갱신 스크립트
src/
  main.js               자료 불러오기 → 성공/실패 분기 → 화면 시작
  api.js                공공데이터포털 API 호출, 오류 종류 구분
  app.js                화면 동작 (카드, 지도, 스탬프, 코스, 상세, 백업 등)
  style.css
  data/
    step1-data.js       1단계 파일 데이터 (연습 모드용)
    jeju-outline.js     제주도 행정구역 경계 (통계청 2013, 간략화)
    weather-data.js     기상청 초단기실황 스냅샷

사용자 관점 개선점 10가지

스탬프 투어를 실제로 쓰는 사람의 입장에서 불편할 만한 점을 정리했습니다.

#	개선점 (사용자가 느끼는 불편)	해결 방법	상태
1	지금 내가 있는 곳 근처 장소부터 보고 싶다	정렬에 내 위치에서 가까운 순 추가, 카드에 거리 표시	✅ 구현
2	브라우저 데이터를 지우거나 기기를 바꾸면 스탬프가 모두 사라진다	내 기록 내보내기·불러오기(JSON 파일)	✅ 구현
3	만든 코스를 내비 앱으로 열거나 친구에게 보내고 싶다	구글 지도 길찾기 열기, 코스 복사(글)	✅ 구현
4	다녀온 곳에 느낌을 짧게 남기고 싶다	스탬프 찍은 장소에 방문 메모, 카드에 📝 표시	✅ 구현
5	카드 120장을 한 번에 훑기에 길다	24개씩 더 보기 또는 페이지 나누기	💡 후보
6	휴대폰에서 지도·코스를 보려면 많이 스크롤해야 한다	화면 아래 탭(목록 / 지도 / 내 코스 / 스탬프북)	💡 후보
7	오늘 날씨에 맞는 곳을 추천받고 싶다 (비 오는 날은 실내 위주)	날씨와 장소 성격을 연결한 추천	💡 후보
8	검색했을 때 검색어가 어디에 들어 있는지 한눈에 보이면 좋겠다	검색어 하이라이트, 최근 검색어	💡 후보
9	밝은/어두운 화면과 글자 크기를 내가 고르고 싶다	화면 테마·글자 크기 설정	💡 후보
10	인터넷이 약한 곳(오름, 해안)에서도 쓰고 싶다	오프라인 지원(PWA), 한 번 본 자료 저장	💡 후보

이미 반영한 안전장치: 자료를 불러오지 못해도 연습 모드로 계속 쓸 수 있고, 어떤 이유로 실패했는지 화면에서 알려 줍니다.

이번에 추가한 개선 기능

• 내 위치에서 가까운 순 정렬: 위치 권한을 허용하면 가까운 장소부터 보여 주고 카드에 직선거리를 표시합니다. 위치를 확인할 수 없으면 기본 정렬로 돌아갑니다.
• 내 기록 백업·복원: 스탬프·찜·방문 메모를 JSON 파일로 저장하고 불러옵니다. 불러올 때는 현재 장소 목록에 있는 값만 규칙에 맞게 걸러서 적용하고, 덮어쓰기 전에 확인을 받습니다.
• 코스 길찾기·복사: 찜한 순서대로 구글 지도 길찾기를 열고(최대 11곳), 코스를 메신저에 붙여넣기 좋은 글로 복사합니다.
• 방문 메모: 스탬프를 찍은 곳의 상세 화면에서 200자까지 메모하면 자동 저장됩니다.

알려진 한계

• 스탬프·찜·메모는 이 브라우저(localStorage)에만 저장됩니다. 백업 기능으로 옮길 수 있습니다.
• 현장 인증(GPS)은 https:// 주소나 localhost 에서만 동작하며, 위치를 확인할 수 없으면 "직접 체크"로 찍을 수 있습니다.
• 지도 윤곽은 간략화된 행정구역 경계라 실제 해안선과 최대 약 0.5km 차이가 날 수 있습니다.
• 날씨는 실시간이 아니라 npm run update-weather 로 저장한 시점의 값입니다. 3시간이 지나면 "오래된 자료"로 표시됩니다.
• 코스 거리는 직선거리 기준이며 실제 도로 거리와 다릅니다.
• 경계 데이터 출처: 통계청 2013 행정구역 (southkorea/southkorea-maps).