내 마음대로 만드는 제주도 컨셉여행 (2단계: API 버전)

제주특별자치도 제주역사문화 데이터를 파일이 아니라 공공데이터포털 Open API로 받아 오는 화면입니다.

브라우저(index.html) ──/api/places──▶ Vercel 서버 함수 ──▶ api.odcloud.kr (일반정보 + 위치정보)
                      ──/api/place?id=▶                      (인증키는 서버 환경변수에만 있음)

주소	하는 일
GET /api/places	120곳의 가벼운 목록 (지도·카드·검색·컨셉에 사용)
GET /api/place?id=367	한 곳의 긴 글(내용·목차·초록·참고문헌). 상세를 열 때만 호출

화면 구성

화면은 1개입니다. index.html 한 페이지를 위에서 아래로 스크롤하며 쓰고, 그 위에 팝업 2개가 겹쳐 뜹니다. 페이지가 열리면 맨 위에 "불러오는 중" 안내가 잠깐 나오고, API 호출이 실패하면 오류 문구와 다시 시도 버튼이 나옵니다.

순서	영역	보여 주는 것	사용하는 API
맨 위	제목 박스	사이트 이름과 소개 문구	-
①	여행 컨셉 고르기	컨셉 버튼 9개(가족여행·수학여행·자연탐방·바다여행·해안선 드라이브·박물관투어·역사투어·유적지투어·오름투어), 직접 입력, 컨셉을 추천받을래요. 같은 버튼을 다시 누르면 선택이 해제됩니다.	-
②	여행지를 하나씩 골라 루트 만들기	필터 줄(검색, 디렉토리, 지역, 초기화, 컨셉에 어울리는 곳만 보기) · 왼쪽: 내가 고른 여행지 목록(순서 변경·빼기·거리 합계·가까운 순서로 정렬·되돌리기·선택 완료) · 오른쪽: 지도(범례, 핀 120개, 드래그 이동, 확대·축소, 고른 곳을 번호 순서대로 잇는 선) · 여행지 카드(담기, 지도에서 보기)	/api/places (페이지가 열릴 때 1번)
③	여행 컨셉 (결과)	선택 완료를 누르면 나타납니다. 컨셉 이름 → (추천받기를 고른 경우) "이런 컨셉은 어때요?" 이름 3개와 다른 이름 추천 → 내 여행 루트(총 거리·이동 시간 추정, 작은 지도, 장소별 카드와 구간 거리, 링크 복사·일정 복사·인쇄)	- (이미 받은 목록 사용)

겹쳐 뜨는 팝업

팝업	언제	보여 주는 것	사용하는 API
핀 설명창	지도의 핀을 누르면	분류, 장소명, 제목, 주소, 소개글 앞부분, 루트에 담기, 자세히	-
상세 창	자세히 또는 카드의 상세를 누르면	주소·우편번호·좌표·주제·저작자·발행일 등과 내용·목차·초록·참고문헌	/api/place?id=… (열 때만, 한 번 받으면 다시 받지 않음)

API 대비 (연습 모드)

상황	화면
데이터를 받는 중	맨 위에 "📡 여행지를 불러오는 중…"
API 성공	평소 화면
API 실패 (키 없음, 잘못된 키, 서버 오류, 15초 넘게 무응답)	노란 상자 "🧪 연습 모드 — 공공데이터 API에 연결하지 못해 1단계 파일 데이터를 보여 주고 있어요"와 실패 이유, API 다시 연결 버튼. 화면은 1단계 파일 데이터(fallback.json, 120곳)로 그대로 동작하고, 상세 창도 API 호출 없이 열립니다.
API와 파일 모두 실패	"⚠️ 여행지를 불러오지 못했습니다" 와 다시 시도 버튼

fallback.json 은 1단계 CSV 두 개를 API 응답과 같은 모양으로 합친 파일입니다. (API와 120곳 모두 같은 내용인 것을 확인했습니다.)

사용 흐름: ① 컨셉 선택 → ② 지도·카드에서 여행지 담기 → 선택 완료 → ③ 결과 확인

사용자 관점 개선점 10가지

프롬프트: "이 사이트를 처음 쓰는 사용자 입장에서 살펴보고, 추가하거나 고치면 좋을 점을 10가지 제안해줘. 아직 고치지는 말고 목록만 보여줘." (코드와 실제 화면(PC·휴대폰 크기)을 확인해 정리했고, 실제로 없는 기능만 적었습니다.)

#	불편한 점	개선 방법	처리
1	새로고침하면 만든 루트가 모두 사라집니다.	고른 여행지와 컨셉을 브라우저에 자동 저장하고 다시 열면 불러옵니다.	✅ 반영
2	핀 색의 뜻을 알려 주지 않습니다. 범례가 없고 "민속/확장분야" 분류 이름도 낯섭니다.	지도 위에 범례를 넣고 "확장분야"를 "자연·사회·역사·관광"처럼 풀어서 보여 줍니다.	✅ 반영
3	고른 순서대로만 이어져 길이 비효율적일 수 있습니다.	"가까운 순서로 정렬" 버튼과 정렬 전후 총 거리 비교를 추가합니다.	✅ 반영
4	거리와 시간이 직선거리 기준의 추정값입니다.	길찾기 API로 실제 도로 거리와 소요 시간을 받아 옵니다.	⏳ 다음 단계 (별도 API 키 필요)
5	지도가 실제 지도가 아닙니다. 섬 윤곽이 대략적이고 도로·지명이 없습니다.	카카오맵·네이버지도·OpenStreetMap 같은 실제 지도로 바꿉니다.	⏳ 다음 단계 (외부 지도 필요)
6	제주시 쪽에서 핀이 겹쳐 누르기 어렵습니다.	가까운 핀을 숫자 묶음으로 보여 주고 확대하면 풀리게 합니다.	⏳ 다음 단계
7	컨셉에 맞는 곳이 적을 때 이유를 알려 주지 않습니다.	어울리는 곳이 20곳 미만이면 곳 수와 해결 방법을 안내합니다.	✅ 반영
8	휴대폰에서 지도를 만지면 페이지 스크롤이 막힙니다. (지도 영역이 터치 스크롤을 막고, 두 손가락 확대도 없음)	손가락 한 개/두 개 동작을 나누고 지도를 접는 버튼을 둡니다.	⏳ 다음 단계
9	사진이 없고 글뿐이라 가고 싶은 마음이 들지 않습니다.	사진 제공 API를 연동하거나 분류별 아이콘을 보여 줍니다.	⏳ 다음 단계 (데이터에 사진 주소가 없음)
10	완성한 루트를 공유하거나 일정표로 쓰기 어렵습니다. (인쇄만 가능)	링크 공유와 텍스트 일정 복사를 추가합니다. (일차별 일정은 다음 단계)	✅ 일부 반영

추가로 발견: 휴대폰에서 제목이 "제주/도"처럼 단어 중간에서 줄바꿈 됨 → ✅ 단어 단위로 줄바꿈 하도록 수정

이번에 고치고 추가한 것 (4단계)

구분	내용	확인한 방법
개선 #1	자동 저장·복원: 고른 여행지, 순서, 컨셉(직접 입력·추천받은 이름 포함)을 브라우저(localStorage)에 저장하고, 다시 열면 "💾 지난번에 만들던 루트 N곳을 불러왔어요"와 함께 복원합니다.	6곳을 담고 새로고침해 루트·컨셉·지도 선이 그대로 복원되는 것을 확인
개선 #2	범례: 지도 위에 주황=민속(생활·신앙·의례), 파랑=확장분야(자연·사회·역사·관광), 분홍=내 루트(번호=순서) 안내	화면과 문구 확인
개선 #3 / 새 기능	🧭 가까운 순서로 정렬: 첫 여행지를 출발지로 고정하고 가까운 곳부터 다시 배열합니다(가까운 곳 잇기 + 꼬인 구간 풀기). 줄어든 거리를 보여 주고 ↩ 되돌리기가 됩니다.	동서로 왔다 갔다 하는 6곳이 327.9km → 92.3km로 줄고, 되돌리면 327.9km로 복귀, 한 번 더 누르면 "이미 가장 가까운 순서예요"
개선 #7	컨셉 안내: 선택한 컨셉에 어울리는 곳이 20곳 미만이면 곳 수와 "어울리는 곳만 보기를 끄면 전체에서 고를 수 있어요" 안내	박물관투어(15곳)에서 안내 문구 확인
개선 #10 / 새 기능	🔗 링크 복사 / 📋 일정 복사: 결과 화면에서 루트가 담긴 링크를 복사하면 받은 사람이 열었을 때 같은 컨셉·루트 결과가 바로 보입니다. 일정 복사는 메신저에 붙여 넣을 텍스트(장소, 구간 거리, 총 거리)를 만듭니다.	링크 주소를 만들어 저장소를 비운 채 열었더니 컨셉과 6곳 결과가 그대로 나옴. 직접 입력·추천 이름도 링크에 담기는 것 확인
추가 수정	휴대폰에서 제목이 단어 중간에서 끊기지 않게 수정	휴대폰 크기 화면 확인

못 한 것: 위 표의 ⏳ 항목(#4, #5, #6, #8, #9와 일차별 일정)은 외부 API·키 또는 큰 변경이 필요해 다음 단계로 남겼습니다. 공유 링크는 배포된 주소(Vercel)에서 열어야 다른 사람이 볼 수 있습니다. (내 컴퓨터의 localhost 주소로 복사한 링크는 나만 열립니다.)

인증키 (파일에 넣지 않습니다)

Vercel 프로젝트 Settings → Environment Variables 에 두 개를 추가합니다.

• JEJU_CULTURE_INFO_KEY
• JEJU_CULTURE_LOCATION_KEY

내 컴퓨터에서 확인할 때는 .env.example 을 .env 로 복사해 값을 채우고 node dev.js 를 실행합니다. .env 는 .gitignore 에 들어 있어 GitHub 에 올라가지 않습니다.

배포 순서

1. GitHub 에 새 저장소를 만들고 이 폴더를 올립니다. (.env 가 올라가지 않았는지 확인)
2. Vercel 에서 Add New → Project 로 그 저장소를 가져옵니다. (Framework: Other, 설정은 그대로)
3. Environment Variables 에 위 두 키를 넣고 Deploy 합니다. (키를 넣은 뒤에 배포/재배포해야 적용됩니다)
4. 시크릿 창(Ctrl + Shift + N)에서 Vercel 링크로 접속해 확인합니다.