내 근처 토익 시험장 찾기
토익 시험장, 신청할 때 마다 근처 시험장을 찾느라 고생하셨나요?
현재 위치 기준 고사장 위치를 정렬해주는 웹사이트를 만나보세요!
내 근처 토익 시험장 찾으러 가기!
https://toeic.roundtable02.com/
토익 홈페이지가 점검 중인 경우 오류가 발생할 수 있습니다.
기술 스택
[ 해당 웹사이트는 AI와 함께 개발하였습니다. ]
[개발 여행기1 - 내 근처에 있는 토익 시험장이 궁금하다]
[개발 여행기2 - 도메인 네임이 맘에 안들어서 어쩌지 (EC2 인스턴스 + nginx 도입기)]
[개발 여행기3 - EC2 인스턴스에 React 도커로 배포하기]
[개발 여행기4 - Functions 대신 Express.js 서버로 CORS 해결하기]
- Next.js App Router
- React 19
- TypeScript
- styled-components
- Leaflet / react-leaflet
- Playwright
- Vercel
로컬 실행
npm install
npm run dev
앱은 기본적으로 http://127.0.0.1:3000 에서 실행됩니다.
환경변수
.env.example 기준:
NEXT_PUBLIC_SITE_URL=https://toeic.roundtable02.com
TOEIC_UPSTREAM_BASE_URL=https://m.exam.toeic.co.kr/receipt/centerMapProc.php
TOEIC_PROXY_TIMEOUT_MS=15000
NEXT_PUBLIC_SITE_URL: canonical, OG, sitemap, robots 기준 URLTOEIC_UPSTREAM_BASE_URL: TOEIC 프록시 대상 엔드포인트TOEIC_PROXY_TIMEOUT_MS: 프록시 타임아웃(ms)
검증
기본 검증은 mock upstream 기반 Playwright E2E입니다.
npm run test:centers
npm run build
npm run test:e2e
실서비스 스모크는 수동 실행용입니다.
PLAYWRIGHT_BASE_URL=http://127.0.0.1:3000 npm run test:e2e:live
test:e2e:live 실행 전에는 실제 upstream 을 바라보는 앱 서버가 이미 떠 있어야 합니다.
시험장 CSV 자동 갱신
정적 CSV는 자동 갱신 스크립트로 유지합니다.
npm run centers:check
npm run centers:refresh
centers:check
- 현재 CSV, 리포트, 상태 파일과 비교만 수행합니다.
- 저장소 파일은 수정하지 않고, 변경이 있으면 종료 코드
1 을 반환합니다.
centers:refresh
- 공식 TOEIC upstream 을 기준으로
public/toeic_centers.csv 를 갱신합니다.
- 검색 랜딩 페이지의 장애 대비 스냅샷인
data/toeic-landings.json 을 누적 갱신합니다.
- 리포트와 상태 파일도 함께 갱신합니다.
CLI 옵션:
node scripts/update-toeic-centers.mjs --check
node scripts/update-toeic-centers.mjs --csv public/toeic_centers.csv
node scripts/update-toeic-centers.mjs --report reports/toeic-centers-report.json
node scripts/update-toeic-centers.mjs --landing-archive data/toeic-landings.json
--check: 쓰기 없이 비교만 수행--csv <path>: 대상 CSV 경로--report <path>: JSON 리포트 경로
- 같은 basename 으로 Markdown 리포트도 함께 생성됩니다.
--landing-archive <path>: 날짜·지역별 공식 시험장 스냅샷 경로
리포트 파일:
reports/toeic-centers-report.json
newCenters[], staleCenters[], changedMetadata[], manualReview[] 포함
reports/toeic-centers-report.md
reports/toeic-centers-state.json
- 다음 실행에서 이름/주소 변경을 감지하기 위한 내부 상태 파일
정책:
- 기준 범위는 앱 드롭다운에 실제로 노출되는 모든 시험일입니다.
- 신규 센터는 CSV 끝에 자동 append 합니다.
- 공식 목록에서 사라진 센터는 CSV에서 삭제하지 않고
stale candidate 로만 보고합니다.
- 공식 좌표가 비어 있거나 비정상 형식이면 CSV에 자동 추가하지 않고
manualReview 로 남깁니다.
Vercel 배포
- Vercel 프로젝트 루트는 저장소 루트(
/Users/tak/toeic-center-finder)입니다.
- Framework Preset 은 Next.js 를 사용합니다.
- 프로덕션 환경변수
NEXT_PUBLIC_SITE_URL 은 반드시 https://toeic.roundtable02.com 으로 설정합니다.
- 필요 시
TOEIC_PROXY_TIMEOUT_MS 를 운영 환경에 맞춰 조정합니다.
- 로컬 CLI 링크 기준 프로젝트 정보는
.vercel/project.json 에 생성되며, GitHub Actions 에서는 같은 값을 시크릿으로 사용합니다.
- 과거 보조 도메인을 다시 연결하더라도 canonical, sitemap, robots, OG 기준 URL은 항상
https://toeic.roundtable02.com 하나만 사용합니다.
GitHub Actions Vercel 자동 배포
.github/workflows/vercel-preview.yml
- PR 오픈/업데이트 시 preview 배포
- draft PR 과 포크 PR 은 시크릿 보호를 위해 자동 배포하지 않음
.github/workflows/vercel-production.yml
main 브랜치 push 시 production 배포- 수동 실행(
workflow_dispatch) 가능
GitHub repository secrets:
VERCEL_TOKEN=...
VERCEL_ORG_ID=...
VERCEL_PROJECT_ID=...
설정 순서:
- Vercel에서 access token 을 발급합니다.
- 로컬에서
vercel link 를 실행해 프로젝트를 연결합니다.
- 생성된
.vercel/project.json 에서 orgId, projectId 값을 확인합니다.
- GitHub 저장소의
Settings > Secrets and variables > Actions 에 VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID 를 등록합니다.
- Vercel 프로젝트 환경변수에도
NEXT_PUBLIC_SITE_URL, 필요 시 TOEIC_PROXY_TIMEOUT_MS 를 등록합니다.
운영 메모:
- 이 자동화는 Vercel 공식 GitHub Actions 방식인
vercel pull + vercel build + vercel deploy --prebuilt 흐름을 사용합니다.
- 나중에 Vercel Git Integration 을 연결하면 GitHub Actions 와 중복 배포가 생길 수 있으니 한쪽만 활성화하는 편이 안전합니다.
main 브랜치에는 GitHub Branch Protection 을 걸고 CI 워크플로 성공을 필수 status check 로 두는 편이 안전합니다.
GitHub Actions 자동 갱신
.github/workflows/refresh-toeic-centers.yml
- 주 1회 실행
- 수동 실행(
workflow_dispatch) 가능
- 변경이 있으면 CSV/리포트/상태 파일을 담은 PR을 자동 생성
참고 문서
