제주 역사문화 답사 스탬프 투어 (2단계)

제주특별자치도 제주역사문화 일반정보 + 위치정보 데이터로 장소를 찾고, 지도(또는 3D)에서 보고, 마음에 드는 곳을 찜해 나만의 답사 코스를 만들고, 다녀온 곳에 스탬프를 찍는 사이트입니다.

• 배포 주소: https://leejeongeun-step2.vercel.app · GitHub: https://github.com/jeongeunlee0/leejeongeun-step2
• 1단계: CSV 파일 데이터를 index.html에 넣어 더블클릭으로 동작
• 2단계(이 폴더): 데이터를 파일 대신 서버 API로 호출하고, 공공데이터포털 오픈 API 키는 환경변수로만 읽습니다. API를 쓰지 못하면 1단계 파일 데이터로 보여 주며 "연습 모드" 를 표시합니다.

1. 사이트 구조 (화면 구성)

화면은 페이지 1개(public/index.html)이고, 그 안이 아래 영역으로 나뉩니다.

영역	무엇을 보여 주나요
상단 바	제목 · 데이터 출처 · 전체 장소 수 · API 상태 배지(🟢 API 연결됨 / 🟠 연습 모드 / ⏳ 불러오는 중) · 검색창
왼쪽 패널 ① 장소 목록	처음 쓰는 사람을 위한 사용법 안내 · 추천 검색어 · 분류/디렉토리 필터 · 정렬(번호순·가나다순·내 위치에서 가까운 순) · 장소 카드(찜 / 지도에서 보기 / 자세히) · 더 보기
왼쪽 패널 ② 나의 답사 코스	찜한 순서 목록 · 직선거리 합계 · 스탬프 진행률 · 순서 변경 · 장소별 메모 · 코스 글/공유 링크 복사 · 가까운 순서로 정리 · 비우기
오른쪽 지도 보기	장소 핀(분류별 색, 겹치면 개수 원으로 묶음) · 핀을 누르면 설명 팝업 · 찜한 순서대로 이어지는 점선과 번호 핀 · 일반/지형/위성 지도 전환
오른쪽 3D 답사 보기 (three.js)	장소를 기둥으로 표시(높이 = 설명 글 길이) · 회전/확대/클릭 선택 · 찜 코스 번호와 선
상세 팝업	설명·초록·목차·참고문헌 · 현재 날씨(Open-Meteo) · 구글 지도/카카오맵 길찾기 · 원문 · 비짓제주 링크

데이터 흐름

브라우저(public/index.html)
   │  fetch
   ▼
/api/places        목록·검색·분류·정렬 (요약 정보)
/api/places/:id    장소 1곳 상세 (설명 전문)
/api/status        지금 live 인지 practice 인지 점검용 (키 값은 내보내지 않음, 설정 여부만)
   │
   ▼  lib/source.js
공공데이터포털 오픈 API 2개 (일반정보 + 위치정보)  ──성공──▶ 🟢 live
   │ 키 없음 / 호출 실패 / 응답 형식 오류
   ▼
data/places.json (1단계 CSV 데이터)                 ──────▶ 🟠 practice (연습 모드)

서버가 아예 응답하지 않으면 브라우저가 public/data/places.json(같은 1단계 데이터)으로 직접 대신 보여 주고 마찬가지로 연습 모드로 표시합니다.

2. 환경변수와 API 키

API 키는 코드·README·프롬프트·GitHub에 넣지 않습니다. 로컬에서는 .env.local에, 배포에서는 Vercel 환경변수에만 넣습니다.

이름	설명
JEJU_CULTURE_INFO_KEY	제주역사문화일반정보 API 인증키 (필수)
JEJU_CULTURE_LOCATION_KEY	제주역사문화위치정보 API 인증키 (필수)
JEJU_CULTURE_INFO_URL · JEJU_CULTURE_LOCATION_URL	요청 주소를 바꿔야 할 때만 (선택, 보통 비워 둠)

• .env.example(값이 빈 예시)만 GitHub에 올라가고, .env.local은 .gitignore로 제외됩니다.
• 인코딩 키·디코딩 키 어느 쪽을 넣어도 한 번만 인코딩되도록 처리합니다.
• 키가 없거나 틀리면 오류 없이 연습 모드로 동작하고, 포털이 돌려준 안내 문구(예: "등록되지 않은 인증키 입니다.")를 이유로 보여 줍니다. 화면 위 배지와 /api/status로 확인할 수 있습니다.

사용하는 오픈 API (공공데이터포털 공개 명세로 확인)

데이터	요청 주소	명세
제주역사문화일반정보	https://api.odcloud.kr/api/15109587/v1/uddi:56c2b3a4-4b4b-46cd-a1fa-f928ef731ffb	Swagger
제주역사문화위치정보	https://api.odcloud.kr/api/15109570/v1/uddi:8781448b-81a8-487c-bc95-d26335bafa82	Swagger

• 인증: serviceKey 쿼리 파라미터 / 쪽 나눔: page, perPage
• 응답: { page, perPage, totalCount, currentCount, matchCount, data: [...] } — data의 열 이름은 CSV 헤더와 같습니다(데이터 고유번호, 장소명, 위도, 경도 …).
• 키 없이 호출하면 401 "인증키는 필수 항목 입니다.", 틀린 키는 401 "등록되지 않은 인증키 입니다."가 오는 것을 실제로 확인했습니다. 발급받은 키로 한 실제 응답은 키를 넣은 뒤 npm run check:live로 확인합니다.

3. 실행·배포·점검

node scripts/build-data.js   # data/source 의 CSV → data/places.json (연습 모드 데이터) 다시 만들기
npm test                     # 가짜 공공데이터포털 서버로 live/practice 전환 점검 (실제 키 불필요)
npm run check:live           # .env.local 의 실제 키로 API가 동작하는지 점검 (키·주소 값은 출력하지 않음)

1. .env.local에 키 2개를 채웁니다. (.env.example과 같은 모양)
2. GitHub 저장소에 올린 뒤 Vercel에서 그 저장소를 Import 해 배포합니다. (Framework Preset: Other, vercel.json이 public 폴더를 정적 출력으로 지정)
3. Vercel → Project Settings → Environment Variables에 키 2개를 넣고 Redeploy 합니다.
4. 시크릿 창(Ctrl + Shift + N)에서 Vercel 링크를 열어 확인합니다.

4. 사용자 관점 개선점 10가지

"처음 쓰는 사용자 입장에서 살펴보고, 추가하거나 고치면 좋을 점 10가지"를 정리하고, 적용 여부를 표시했습니다.

#	개선점 (처음 쓰는 사람이 겪는 불편)	결과
1	무엇을 하는 사이트인지, 어떻게 시작하는지 첫 화면에서 알 수 없다 → 사용법 3단계 안내(닫으면 다시 안 보임)	✅ 적용
2	장소 120곳이 한 번에 길게 나열돼 스크롤이 길다 → 30개씩 "더 보기"	✅ 적용
3	무엇을 검색해야 할지 막막하고, 결과가 없으면 막힌다 → 추천 검색어 버튼(오름·신당·해안·유적·동굴·포구·일제·용천수)과 결과 없음 안내	✅ 적용
4	지금 내 주변에 어떤 곳이 있는지 알기 어렵다 → 내 위치에서 가까운 순 정렬 + 직선거리 표시(위치 허용 시, 거부하면 원래 정렬로 복귀)	✅ 적용
5	만든 코스를 친구에게 보내거나 다시 열기 어렵다 → 공유 링크 복사 / 링크로 코스 불러오기(스탬프·메모 같은 개인 기록은 제외)	✅ 적용
6	찜한 순서가 뒤죽박죽이면 직접 ▲▼로 하나씩 옮겨야 한다 → 가까운 순서로 정리 버튼(첫 장소에서 출발, 직선거리 기준, 최단 경로 보장은 아님)	✅ 적용
7	장소를 골라도 어떻게 가는지 이어지지 않는다 → 상세에서 구글 지도·카카오맵 길찾기(도착지 자동 입력)	✅ 적용
8	핀이 겹쳐 있는 곳은 하나를 고르기 어렵다 → 핀 묶음(클러스터) 표시(겹친 핀은 개수가 적힌 원으로 묶고, 누르거나 확대하면 풀림 · 찜한 코스 핀은 순서 번호가 늘 보이도록 묶지 않음 · "지도에서 보기"는 묶음을 풀고 팝업을 엶)	✅ 적용
9	키보드·화면 낭독 사용자에게 불편하다 → 포커스 표시, 결과 수 자동 안내(aria-live), 메모칸 이름, 장소 카드 Tab 이동 + Enter로 지도에서 보기, 탭 선택 상태(aria-selected) 알림, 상세 창을 닫으면 원래 자리로 포커스 복귀, 색 대비 점검·수정	✅ 적용 (아래 점검 결과)
10	코스에 "몇 시에 가기" 같은 내 생각을 적어 둘 곳이 없다 → 장소별 메모(브라우저에 저장, 코스 글 복사에 포함)	✅ 적용

색 대비 점검 (WCAG AA: 본문 4.5:1, 큰 글자 3:1) — 화면의 글자색과 실제 배경색을 계산해 자동 점검했습니다.

• 처음 점검: 기준 미달 6곳 — 금색 배경 위 흰 글자(코스 개수 배지, "★ 찜함" 버튼, 코스 번호: 1.86:1), 선택 안 된 탭 글자(3.54:1), 안내 닫기 ×(3.54:1), 구간 거리 안내(4.07:1). (비활성 버튼 2곳은 기준 예외)
• 수정: 금색 배경 글자를 진한 색으로, 회색 글자를 #595959로 변경 (지도 번호 핀·3D 번호도 같이)
• 다시 점검: 목록·코스·상세 화면의 글자 요소 402개 모두 통과(미달 0) — 예: 코스 배지 8.84:1, 선택 안 된 탭 7.00:1, 구간 거리 6.36:1

5. 이번 단계에서 고치고 추가한 것

필수 (안내서 ③)

• API 대비: 데이터를 불러오는 동안 "불러오는 중"(스피너·목록 흐림) 표시, 실패하면 1단계 파일 데이터로 보여 주고 상단 배지와 안내 문구에 연습 모드 표시 + 이유 표시
• 키 없이도 안 깨짐: 환경변수를 비운 상태, 잘못된 키(401), API 서버 다운, JSON이 아닌 응답, 형식이 다른 JSON 모두 연습 모드로 전환 (npm test로 점검)
• 키 보호: 키는 서버 함수에서만 읽고 화면·응답·오류 메시지에 값이 나오지 않음, .env.local은 Git 제외, .env.example은 값이 빔
• README: 화면 구성, 개선점 10가지, 변경·추가 기록 정리

구조 변경

• 파일 임베드 → 서버리스 API(/api/places, /api/places/:id, /api/status) 호출로 변경, 검색·분류·정렬은 서버가 처리
• 화면 파일을 public/으로 분리해 서버 코드(lib/, scripts/)가 공개되지 않게 함

기능 추가 (1단계에서 이어짐)

• 지도 보기 + 3D 답사 보기(three.js), 상세의 현재 날씨(Open-Meteo, 키 불필요)
• 위 개선점 10가지 모두 (사용법 안내, 더 보기, 추천 검색어, 가까운 순 정렬, 공유 링크, 가까운 순서 정리, 길찾기, 핀 묶음, 키보드·색 대비 접근성, 메모)

6. 데이터 출처와 사용한 라이브러리

• 제주특별자치도_제주역사문화일반정보 · 위치정보 (공공데이터포털 파일데이터, 2022-12-09 기준)
• 지도: Leaflet + Leaflet.markercluster(핀 묶음) + Esri 지도 타일 · 3D: three.js
• 날씨: Open-Meteo.com (CC BY 4.0)
• 참고: 원본 데이터의 "내용"은 장소 자체의 설명이 아니라 관련 보고서의 발췌문인 경우가 많습니다. 화면에는 원본 그대로 표시합니다.