seoulchi
서울에서 이번 주 / 지금 무슨 행사가 있는지 알려주는 웹앱.
두 공공 API가 하루 1회만 갱신되므로 서버 런타임도 DB도 두지 않습니다.
배치가 데이터를 모아 data/*.json으로 커밋하고, 정적 웹앱이 그걸 읽습니다.
로컬 실행
npm ci
cp .env.example .env.local # API 키 채우기
npm test
npm run batch # data/*.json 생성
npm run batch -- 2026-W33 # 특정 주차 (지난 주차는 거절됨)
.env와 .env.local을 둘 다 읽습니다(나중 것이 이김). 실제 키는 .env.local에 두세요 —
둘 다 .gitignore에 있습니다.
첫 실행은 40분 넘게 걸립니다. 비짓서울 상세 2,199건을 받아야 하고, 그쪽이
레이트 리밋을 500으로 위장해 돌려주기 때문에 400ms 간격이 필요합니다.
캐시(data/cache/visitseoul.json)가 커밋돼 있으므로 이후 실행은 5분 안에 끝납니다.
환경변수
| 이름 | 설명 |
|---|
SEOUL_API_KEY | 서울열린데이터광장 인증키 (발급) |
VISITSEOUL_API_KEY | 비짓서울 API 키 (발급) |
KOPIS_API_KEY | KOPIS 공연예술통합전산망 서비스키 (발급) |
VISITSEOUL_CATEGORIES | 수집 대상 카테고리 (쉼표 구분). 확정 목록은 docs/api-findings.md |
산출물
| 파일 | 내용 |
|---|
data/events/YYYY-Www.json | 그 주에 열리는 행사 |
data/places.json | "언제 가도 좋은 곳" 후보 (주에 묶이지 않음) |
data/meta.json | 갱신 시각, 소스별 건수 |
data/cache/visitseoul.json | 상세 응답 캐시. 변경분만 다시 받기 위한 것 |
data/cache/kopis.json | KOPIS 상세·시설 캐시와 lastRun. 변경분만 다시 받기 위한 것 |
배치
매일 KST 06:00에 GitHub Actions가 돌며 data/를 갱신 커밋합니다.
레포 Settings → Secrets and variables → Actions에 등록해야 합니다:
- Secrets:
SEOUL_API_KEY, VISITSEOUL_API_KEY, KOPIS_API_KEY
- Variables:
VISITSEOUL_CATEGORIES
개발
TDD로 진행합니다. 계획의 각 태스크에 테스트와 구현이 함께 들어 있습니다.
npm test # 전체
npx vitest run tests/lib/week.test.ts # 파일 하나
npx vitest run tests/lib/week.test.ts -t '연말 경계'
npm run probe # API 실측 스파이크
