KIA 타이거즈 서울 원정 예매 도우미
비상업·개인 구매용 GitHub Pages 사이트입니다. 기아 타이거즈 서울 원정(잠실 LG·두산, 고척 키움) 예매 오픈 시각만 계산하고, 그 경우에만 알림을 보냅니다. 오픈 시각에는 상대 구단 공식 예매처(NOL 또는 티켓링크)로 안내합니다.
광주 홈경기와 서울 밖 원정(창원·대전·수원 등)은 일정 계산·문자·브라우저 알림 대상이 아닙니다.
실제 좌석 점유·결제·매크로는 포함하지 않습니다. 구매는 항상 아래 공식 채널에서 완료하세요.
배포 주소: https://ticket.bravecat.studio/ (GitHub Pages 커스텀 도메인, CNAME)
무엇을 하나요
- 서울 원정만: 상대 구단 정책으로 선예매·일반예매 오픈 시각을 한국 시간으로 계산
- 키움 고척: 일반예매 D-7 14:00 (연간회원 11:00, 멤버십 12:00) · NOL
- LG 잠실: 일반예매 D-7 11:00 (연간회원 D-9 11:00) · 티켓링크
- 두산 잠실: 일반예매 D-7 11:00 (베어스클럽 10:00) · NOL
- 대기 모드: 오픈 시각에 알림·효과음 후 상대 구단 공식 예매 탭 열기
- 관심 경기, 좌석 1·2순위, 준비 체크리스트 (브라우저 localStorage)
- 서울 원정 예매 오픈 1시간 전 문자 알림 (GitHub Actions + 솔라피/웹훅)
- 잔여 경기 일정 자동 갱신 (우천 재편성 포함, GitHub Actions + 네이버 스포츠 KBO)
- 오픈 일정 ICS 다운로드 (1시간 전 캘린더 알림 포함)
- 구장별 좌석·요금 참고표 (홈 구단 안내 기준, 예매 시점 표시가 최종)
GitHub Pages
권장: 저장소 Settings → Pages → GitHub Actions 를 소스로 선택합니다. main에 푸시하거나 Actions에서 github-pages 워크플로를 실행하면 커스텀 도메인 루트(https://ticket.bravecat.studio/)로 배포됩니다 (BASE_PATH=/). 도메인은 저장소 루트와 client/public/ 의 CNAME 파일로 지정합니다.
소스가 Deploy from a branch (main /) 로 남아 있으면 Jekyll이 README를 홈으로 렌더링합니다. 그 경우를 대비해 저장소 루트의 index.html·assets/ 이 앱 빌드 결과입니다. main에 푸시하면 github-pages가 어긋난 폴백을 자동으로 맞춥니다. 로컬에서 미리 맞추려면:
npm run pages:sync
로컬 미리보기:
npm install
npm run dev:client
http://localhost:5173 을 엽니다. 선택 API(npm run dev:server)는 예전 메모 트래커용이며 Pages 사이트에는 필요 없습니다.
오픈 1시간 전 문자
정적 GitHub Pages는 문자를 직접 보내지 못합니다. sms-reminder 워크플로가 매일 10:00·13:00 KST에 일정을 확인하고, 서울 원정 일반예매 오픈 1시간 전부터 오픈 직전 사이에만 발송합니다. 홈경기·서울 밖 원정 창은 건너뜁니다.
- 10:00 KST → LG·두산 일반예매(11:00 오픈) 1시간 전
- 13:00 KST → 키움 일반예매(14:00 오픈) 1시간 전
스케줄러 on/off
문자 발송은 기본이 켜짐입니다. GitHub Actions 워크플로에서 켜고 끕니다.
- Actions →
sms-reminder → Run workflow
scheduler에서 on(켜기) 또는 off(끄기)를 고른 뒤 실행- 기본값
run은 설정을 바꾸지 않고 지금 한 번만 검사/발송합니다
이 선택은 sms.config.json의 enabled에 저장되어 이후 매일 10:00·13:00 KST 실행에 적용됩니다. 같은 실행에서 홈페이지 ON/OFF 표시(Pages 폴백)도 함께 맞춥니다.
잔여 서울 원정이 없으면 sms-reminder와 update-schedule이 스케줄러를 자동으로 끕니다. 우천 재편성으로 서울 원정이 다시 생기면 자동으로 켜집니다. Actions에서 수동으로 끈 경우에는 경기가 돌아와도 자동으로 켜지지 않습니다.
커밋 없이 긴급히 끄려면 Settings → Secrets and variables → Actions → Variables에 SMS_REMINDER_ENABLED=false를 넣습니다. 다시 켜려면 변수를 true로 바꾸거나 삭제합니다.
수동 실행에서 force를 켜면 스케줄러가 꺼져 있어도 이번만 보낼 수 있습니다.
설정
- 저장소 Settings → Secrets에 다음을 넣습니다.
SMS_TO: 수신 번호 (예: 01012345678)- 솔라피:
SOLAPI_API_KEY, SOLAPI_API_SECRET, SOLAPI_SENDER (사전등록 발신번호)
- 또는 직접 문자 게이트:
SMS_WEBHOOK_URL (JSON { to, text, events } POST)
- 솔라피 API Key는 허용 IP를 "모든 IP 허용" 으로 발급해야 합니다. GitHub 호스팅 러너는 실행마다 IP가 바뀌어서 특정 IP만 허용하면 발송이 차단됩니다.
sms.config.json에서 kinds(기본 general)와 필요하면 watchIds를 지정합니다. watchIds가 있어도 서울 원정이 아니면 보내지 않습니다.- 워크플로는 기본 브랜치(
main) 에서만 스케줄 실행됩니다. Actions에서 sms-reminder를 수동 실행하면 테스트할 수 있습니다.
발송이 실패하면
발송 경로가 막혀도 알림 자체를 놓치지 않도록 이렇게 동작합니다.
- 매 실행 전에 솔라피 잔액 조회로 발송 경로를 미리 점검합니다. 막혀 있으면 발송 대상이 없는 시각에도 원인을 미리 알려 줍니다.
- 일시적 오류(429·5xx, 서명 시각 오차)는 두 번까지 재시도합니다.
- 설정 문제(허용 IP 차단, 키 불일치 등)는 재시도해도 소용없으므로 곧바로 원인과 해결 방법을 로그·실행 요약에 남깁니다.
- 문자가 어느 채널로도 나가지 않으면 같은 내용을 GitHub 이슈로 남깁니다. 이슈 알림(메일·앱 푸시)으로 예매 오픈 정보를 그대로 받습니다. 같은 경기·예매 구분에는 이슈를 하나만 만들고, 발송 경로가 복구되면 원인 알림 이슈는 자동으로 닫힙니다.
- 이슈 대체 알림까지 실패하면 워크플로가 실패(빨간 X)로 끝납니다. 대체 알림을 쓰고 싶지 않으면
sms.config.json의 issueFallback을 false로 둡니다(이 경우 발송 실패는 곧 워크플로 실패입니다).
자주 보는 실패 원인
| 로그 | 원인 | 해결 |
|---|
solapi 403 ... 허용되지 않은 IP(...)로 접근하고 있습니다 | 솔라피 API Key에 허용 IP가 지정되어 있음 | 솔라피 콘솔 → API Key 관리에서 해당 키를 모든 IP 허용으로 변경(또는 키 재발급). 제한을 유지해야 하면 고정 IP 서버에 게이트를 두고 SMS_WEBHOOK_URL로 연결 |
solapi 403 InvalidAPIKey / SignatureDoesNotMatch | 키·시크릿이 짝이 맞지 않거나 폐기됨 | 콘솔에서 재발급 후 SOLAPI_API_KEY·SOLAPI_API_SECRET 시크릿 갱신 |
문자 발송 수단이 설정되지 않았습니다 | 시크릿 미등록 | 위 설정 항목대로 시크릿 등록 |
탭을 열어 두면 같은 시각에 브라우저 알림도 뜹니다. 로컬 점검:
npm test
NOW=2026-08-16T13:05:00+09:00 DRY_RUN=1 npm run sms:reminder
정책 요약 (2026 서울 원정)
| 상대(구장) | 일반예매 | 선예매 | 채널 |
|---|
| 키움 (고척) | 경기일 D-7 14:00 | 연간회원 D-7 11:00 / 멤버십 D-7 12:00 | NOL |
| LG (잠실) | 경기일 D-7 11:00 | 연간회원 D-9 11:00 | 티켓링크 |
| 두산 (잠실) | 경기일 D-7 11:00 | 베어스클럽 D-7 10:00 | NOL |
우천·재편성 시 홈 구단/KBO 공지가 우선입니다.
포스트시즌 예매
와일드카드 결정전~한국시리즈의 서울(잠실·고척) KIA 원정 경기도 예매 오픈·문자 알림 대상입니다. 광주 홈 포스트시즌 경기는 정규시즌과 마찬가지로 대상이 아닙니다.
포스트시즌 입장권은 구단이 아니라 KBO가 NOL에서 단독 판매합니다(1인 4매, 선예매 없음). 오픈 시각은 대진이 확정된 뒤 KBO가 공지하므로 고정 규칙이 없습니다. 2025년 실제 공지는 다음과 같습니다.
| 라운드 | 첫 경기 | 예매 오픈 |
|---|
| 와일드카드 결정전 | 10/6 | 10/5 14:00 (D-1) |
| 준플레이오프 | 10/9 | 10/8 14:00 (D-1) |
| 플레이오프 | 10/18 | 10/15 14:00 (D-3) |
| 한국시리즈 | 10/26 | 10/25 11:00부터 차전별 1시간 간격 (D-1) |
그래서 이 사이트는 시리즈 1차전 하루 전 14:00을 예상 오픈 시각으로 잡고, 같은 상대와의 시리즈 전체를 그 시각에 묶습니다. 화면과 문자에는 "예상 · KBO 공지 확인"이 붙습니다. 실제 시각은 KBO 공지를 확인하세요.
포스트시즌 경기는 네이버 스포츠 일정의 라운드 코드 kbo_ps_*로 구분합니다(2024·2025 실제 데이터로 확인).
진출 판별
포스트시즌은 정규시즌 1~5위 5개 팀만 나갑니다. update-schedule은 두 출처를 함께 보고 schedule-meta.json의 postseason에 결과를 저장합니다.
- 순위: 이미 받는 네이버 일정의 정규시즌 경기 결과(
winner)로 팀별 경기·승·패·무를 직접 계산합니다(2026-09-30 기준 KBO 공식 순위표와 10개 팀 모두 일치). KBO 홈페이지는 robots.txt에서 사전 승인 없는 자동 수집을 금지하므로 읽지 않습니다. 남은 경기는 144경기 기준입니다.
- 진출 확정: KIA가 남은 경기를 다 져도(최저 승률) 그 승률에 닿을 수 있는 팀이 4개 이하
- 탈락 확정: KIA가 남은 경기를 다 이겨도(최고 승률) 5개 팀이 남은 경기를 다 져도 더 높음
- 5위 동률은 5위 결정전이 있으므로 미확정으로 둡니다.
- 네이버 포스트시즌 일정: 라운드 코드
kbo_ps_wd(와일드카드)·kbo_ps_sp(준PO)·kbo_ps_po(PO)·kbo_ps_ks(KS)에 올라온 팀을 모읍니다. 5위 결정전(kbo_p)은 제외합니다.
| 값 | 조건 | 시즌 종료 |
|---|
out | 순위상 탈락 확정, 또는 KIA 없이 다른 팀 5개가 포스트시즌 일정에 올라옴 | 남은 정규시즌 KIA 경기가 끝나는 즉시 |
in + 일정에 KIA 있음 | 포스트시즌 경기에 KIA 등장 | 탈락·우승 뒤 KIA 경기가 7일 연속 없을 때 |
in(순위로 확정) / unknown | KIA 첫 시리즈가 아직 일정에 없음 | 리그 마지막 경기 뒤 7일 (정규시즌 1위는 한국시리즈까지 3주 가까이 기다림) |
실제 데이터 확인: 2025년(KIA 65승 75패 4무, 8위)은 out, 2024년(KIA 87승 55패 2무, 우승)은 in, 2026년 9/30(KIA 4위 72승 60패 2무, 잔여 10경기)은 진출 확정 in입니다.
잔여 일정 자동 갱신
games.json은 손으로 고치지 않습니다. update-schedule 워크플로가 매일 10:20·22:20 KST에 네이버 스포츠 KBO 일정을 가져와 잔여 KIA 경기를 덮어씁니다. 우천 취소는 빠지고, 재편성(잠실·고척 포함)이 공지되면 예매 오픈·문자 알람 대상에 다시 들어갑니다.
- Actions →
update-schedule → Run workflow 로 지금 한 번 돌릴 수 있습니다.
dry_run을 켜면 커밋하지 않고 로그만 남깁니다.- 로컬:
npm run schedule:sync (미리보기 npm run schedule:sync:dry)
- 예매 정책·구장 URL은 그대로
client/src/data/hosts.json 을 수정하세요.
시즌 종료·시작 시 자동 스케줄
비시즌에는 워크플로가 돌지 않도록, 시즌이 끝나면 예약 실행을 모두 끄고 시즌 시작 예상 시점에 다시 켭니다. 시즌 상태는 client/src/data/season.json(active / ended)에 저장됩니다.
| 시점 | 무엇이 일어나나 |
|---|
| 시즌 종료 | 잔여 KIA 경기가 없을 때 update-schedule이 아래 순서로 판단하고, 종료하면 season.json을 ended로 바꾸고 sms-reminder·update-schedule을 비활성화합니다. 홈페이지에 시즌 종료 안내(사유 포함)가 뜹니다.① 포스트시즌 미진출 → 즉시 종료: KBO 순위상 탈락이 확정되거나, 포스트시즌 일정에 KIA 없이 5개 팀이 올라오면 바로 끕니다.② 진출 후 탈락·우승: KIA 경기가 7일 연속 없으면 종료합니다(라운드 사이 공백 대비).③ 진출했지만 첫 시리즈 대기 중 / 미확정: 리그 마지막 경기가 끝날 때까지 기다린 뒤 7일 뒤 종료합니다. 자세한 기준은 진출 판별을 보세요. |
| 비시즌 | 일정 조회·문자 확인을 하지 않습니다. season-scheduler만 켜져 있고, 11/15·1/10에 한 번씩 자신을 다시 활성화만 합니다(공개 저장소는 60일 동안 활동이 없으면 GitHub이 예약 실행을 자동으로 끄기 때문). |
| 시즌 시작 | season-scheduler가 3월 1일 09:50 KST부터 네이버 스포츠 KBO 일정을 확인합니다. KIA 경기가 보이면 games.json을 갱신하고 season.json을 active로 바꾼 뒤 sms-reminder·update-schedule을 다시 활성화하고, season-scheduler는 스스로 꺼집니다. 일정이 아직 없으면 4월 말까지 매일 다시 확인합니다. |
비시즌 실행 횟수는 시즌당 보통 3번(11/15, 1/10, 3/1)입니다.
3월 1일로 정한 근거
| 시즌 | KBO 일정 발표 | 개막 |
|---|
| 2023 | 2022-12-20 | 4월 1일 |
| 2024 | 2024-01-03 | 3월 23일 |
| 2025 | 2024-12-20 | 3월 22일 |
| 2026 | 2025-12-19 | 3월 28일 |
한국시리즈 종료는 2024년 10월 28일(KIA 우승), 2025년 10월 31일이었습니다.
일정은 매년 12월 중순1월 초에 발표되고, 개막은 3월 22일4월 1일입니다. 서울 원정 예매는 경기 79일 전에 열리므로 가장 빠른 오픈도 3월 13일 무렵입니다. 3월 1일이면 일정이 이미 나와 있고, 첫 예매 오픈 전 2주 정도 여유가 있습니다. 시즌 종료는 **한국시리즈 종료(10월 말11월 중순) 뒤 7일**입니다. KIA가 정규시즌 1위로 한국시리즈에 직행하면 3주 가까이 경기가 없기 때문에, KIA가 일찍 탈락해도 리그 포스트시즌이 끝날 때까지 스케줄을 유지합니다.
수동으로 끄고 켜기
- 지금 시즌 종료: Actions →
update-schedule → Run workflow → season을 end로 실행. 이번 시즌에 경기가 남아 있어도 자동으로 다시 켜지지 않고, 다음 해 3월에 새 시즌 일정이 확인되면 다시 시작합니다.
- 지금 시즌 시작: Actions →
season-scheduler → Run workflow → season을 start로 실행. 잔여 경기가 없으면 7일 뒤 다시 자동 종료됩니다. auto는 지금 일정을 확인해 자동으로 판단합니다.
현재 상태는 npm run season:status 로 확인합니다.
개발 스크립트
| 명령 | 설명 |
|---|
npm run dev:client | Vite 개발 서버 (5173) |
npm run test | 예매 오픈 시각 단위 테스트 + 문자 발송·재시도·대체 알림 통합 테스트 + 일정 동기화 테스트 |
npm run build | 서버+클라이언트 빌드 |
npm run schedule:sync | 네이버 스포츠에서 잔여 일정을 가져와 games.json 갱신 |
npm run season:status | 시즌 상태(season.json) 확인 |
npm run pages:sync | Pages 브랜치 배포용으로 클라이언트 빌드를 저장소 루트에 복사 |
npm run sms:reminder:dry | 지금 시각 기준 문자 대상 로그 (미발송). 서울 원정이 아니면 대상 없음 |
