제주 역사문화 답사 스탬프 투어 (2단계)
제주특별자치도 제주역사문화 일반정보 + 위치정보 데이터로 장소를 찾고, 지도(또는 3D)에서 보고, 마음에 드는 곳을 찜해 나만의 답사 코스를 만들고, 다녀온 곳에 스탬프를 찍는 사이트입니다.
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가 동작하는지 점검 (키·주소 값은 출력하지 않음)
.env.local에 키 2개를 채웁니다. (.env.example과 같은 모양)- GitHub 저장소에 올린 뒤 Vercel에서 그 저장소를 Import 해 배포합니다. (Framework Preset: Other,
vercel.json이 public 폴더를 정적 출력으로 지정)
- Vercel → Project Settings → Environment Variables에 키 2개를 넣고 Redeploy 합니다.
- 시크릿 창(
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. 데이터 출처와 사용한 라이브러리
