숲가자 — 전국 자연휴양림 빈자리 찾기
숲나들e(foresttrip.go.kr) 월별 예약현황을 3시간마다 모아서 전국 자연휴양림 숙소·야영장의 빈자리를
목록 · 지도 · 달력 · 월간 그리드로 한 번에 보여 주는 정적 웹사이트입니다.
구조
GitHub Actions (3시간마다)
└─ collector/crawl.mjs ── 숲나들e 공개 API (비로그인) ──▶ web/public/data/*.json 커밋
└─ Vercel 자동 배포 (CDN 정적 서빙)
로그인된 Aside 브라우저 (월 1회, 수동)
└─ collector/refresh-master.sh ──▶ data/master.json (휴양림·객실 ID, 좌표)
로컬 (월 1회, 수동)
├─ node collector/naver-reviews.mjs ──▶ data/naver.json (네이버 방문자·블로그 리뷰 수)
└─ node collector/prices.mjs ──▶ data/prices.json (객실별 비수기·성수기 평일·주말 1박 요금)
- DB, 서버 없이 운영합니다. 데이터는 하나의 JSON(약 1MB, gzip 약 150KB)이고, 필터링은 브라우저에서 합니다.
- 날짜별 상태 API는 로그인 없이 호출할 수 있습니다. 객실 목록 API만 로그인이 필요해서, 객실 마스터는 따로 갱신합니다.
| 경로 | 역할 |
|---|
collector/crawl.mjs | 상태 수집. 의존성 없음, Node 20+ |
collector/master.repl.js / master.poll.js | Aside REPL로 시도별 객실 ID 수집 (로그인 세션) |
collector/build-master.mjs | 마스터 병합, 공식 좌표·주소·전화번호 보강 |
collector/naver-reviews.mjs | 네이버 모바일 검색의 플레이스 정보에서 리뷰 수·별점 수집. 기존 값은 건너뛰고 --force로 전체 갱신 |
collector/prices.mjs | 숲나들e 객실 상세(selectFcltsArmpDtlView.do, 비로그인)의 요금표 수집. 기존 값은 건너뛰고 --force로 전체 갱신. 웹은 비수기 주말 요금으로 휴양림별 주말 평균을 낸다 |
data/master.json | 휴양림 185곳 · 객실 7,464개 (2026-10-26 기준) |
web/ | Vite + React + TS, MapLibre(OpenFreeMap), TanStack Virtual |
web/scripts/build-static.mjs | 빌드 마지막 단계. status.json 으로 빈자리 알림 피드(/alerts-feed.json), 휴양림별 페이지(/forest/<id>), 지역·시기 랜딩(/vacancy/...), sitemap 생성 |
.github/workflows/crawl.yml | 정기 수집 → 커밋 → Vercel 배포 |
상태 코드 (status.json의 s 문자열, 날짜당 1글자)
A 예약가능 · 1~9 대기(다음 대기 순번) · F 완료 · C 휴무 · R 공사/점검 · P 추첨·우선예약 기간 · . 기간 밖
숲나들e 응답 매핑: rsrvtAvail=Y이고 rsrvtCnt=0이면 A. 예약이 있고 wtngCnt < goodsMxmmWtngCnt이면 대기, 그 밖은 F.
PRNSL_DAY는 C, REPAIR는 R, DRLTS/PRIOR는 P, BEFORE_DATE/OVER_DATE는 ..
예약률
collector/stats.mjs가 수집할 때마다 휴양림·시설(숙소/야영장)별로 booking: {"01": {we: [예약된 날, 예약 받는 날], wd: [...]}}를 계산합니다.
예약 받는 날은 A·대기·F이고, 그중 대기·F를 예약된 날로 셉니다. 주말은 체크인 다음 날이 토·일·공휴일인 숙박입니다.
공휴일 목록은 web/src/lib/holidays.json 하나를 웹과 수집기가 같이 씁니다.
오픈 전 QC 자동 점검
qa/qc.mjs는 Chromium·WebKit(Safari)·Firefox에서 PC 4종, 125% 배율, 휴대폰 6종, 태블릿 2종, 가로 모드를 대상으로 4개 탭을 모두 점검합니다.
- 화면: 가로 스크롤, 화면 밖으로 넘치는 요소, 터치 영역 44px, 콘솔 오류
- 접근성: axe(WCAG 2.1 AA, 라이트·다크), 본문 바로가기, 탭 방향키, 드롭다운과 상세 팝업의 초점 가두기·복귀
- 사용성: 뒤로가기, 특수문자 검색, 빈 결과, 데이터 실패와 로딩 상태, 404
- 검색·보안: 메타·OG·robots·sitemap, 링크 전수 검사, 혼합 콘텐츠
cd qa && npm i && npm run setup # 최초 1회
npm run qc # 배포 사이트 점검, 결과와 캡처는 qa/out/
로컬 실행
node collector/crawl.mjs # 전체 수집 (약 20~30분), LIMIT_FORESTS=3 으로 일부만
cd web && npm i && npm run dev
수집 정책
- 요청 간격 0.35초 이상(무작위), 동시 2건, 실패하면 지수 백오프로 재시도
- 실패율이 30%를 넘으면 기존 데이터를 덮어쓰지 않습니다.
- 숲나들e 서버 부담을 줄이기 위해 3시간 주기로 수집합니다. 운영기관이 요청하면 즉시 중단합니다.
본 서비스는 비공식 참고용이며 국립자연휴양림관리소·지자체와 제휴하지 않았습니다. 예약은 숲나들e에서 진행하세요.
