v4.9.1 — 원작자 출처 명시 + 라이브 검증 안내

🙏 원작자 Credits 섹션 추가

두 버스 모듈의 원작자분들께 README 에 명시적으로 감사 표시:

모듈	원작자	원본
🚍 한국 버스 (korea_bus/)	luiseok	https://github.com/luiseok/ha-korea-bus-arrival
🚌 서울버스 (seoul_bus/) 원조	miumida	https://github.com/miumida/seoul_bus
🚌 서울버스 (seoul_bus/) 패턴	Murianwind	https://github.com/Murianwind/seoul_bus

원작이 없었다면 이 통합도 없었습니다. 🙏

함께 "본 통합이 추가한 가치" 섹션도 추가 — 단일 통합 메뉴, 마이그레이션 안전망, TIMESTAMP 기반 sensor, stale-data 보존, 저상/만차 binary_sensor, 8개 자동화 블루프린트, 4 lang i18n 등 위로 얹은 부분 명시.

한국어 README + 영문 README 양쪽 적용.

✅ 라이브 검증 (2026-05-18)

홍보 직전 마지막 확인 — 사용자 실제 HA 인스턴스에서 한국 버스 라이브 검증:

• 2개 정류장 동시 등록:
  • 서울 신도림동.구로역(중) ARS 17003 (busStopId 12170511030) — 노선 10/5200/660
  • 경기 시흥 은계우미린더퍼스트.제일풍경채 ARS 25842 (busStopId BS451656) — 노선 12/2/3-A/500/5200
• 모든 entity 정상 동작:
  • 노선당 도착 sensor 2개 (now/next, TIMESTAMP) — 실제 도착시간 표시
  • 새로고침 버튼
  • 업데이트 활성화 스위치 (state: on)
• 모든 attribute 라이브 응답에서 확인:
  • vehicle_number (예: 경기75바3206), current_stop, message (예: "약 19분 후 도착예정"), direction (예: 은행고 방향), bus_type (GENERAL), first_time/last_time/intervals (예: 05:40 / 22:30 / 20~30분), next_stop, remaining_seconds (예: 1170), status (예: 19분 후)
• 3-A 같은 hybrid 노선 슬러그도 정상 처리 (3-A → 3_a)

서울버스 사용자가 키 활성화 24시간 대기 중일 때 한국 버스로 동일 정류장 등록 → 즉시 동작 — README 추천 시나리오가 그대로 작동 확인됨.

READMEs 의 버스 비교표 상단에 "✅ Live-verified (2026-05-18)" 안내 callout 추가. 처음 읽는 사용자가 문서 신뢰감 높음.

v4.9.0 — notify action selector + 한국 버스 호환성 명시

🎁 블루프린트 UX 개선 + 한국 버스 호환성 표

1️⃣ notify 입력을 action selector 로

이전: text selector — 사용자가 mobile_app_my_phone 같이 직접 타이핑
이제: action selector — HA UI 에서 notify 서비스 드롭다운 선택

• 가장 많이 쓰는 케이스: import 시 default notify.notify 를 본인의 notify.mobile_app_<폰_이름> 으로 변경 (드롭다운에서 클릭) → 끝
• title/message 는 default 로 {{ alert_title }} / {{ alert_message }} template 가 들어가 있어요. 블루프린트 내부에서 알아서 채움
• 다른 알림 채널로 자유롭게 변경 가능:
  • notify.telegram → 텔레그램 봇으로
  • media_player.tts.google_say → 스마트 스피커로 음성 안내
  • script.my_custom_alert → 본인의 커스텀 스크립트
  • 여러 액션 시퀀스로 묶기 (예: 푸시 + TTS 동시)

알림 emit 하는 6개 블루프린트 모두 적용 (출발/하차/막차/만차/집떠날때/목적지도착). 다른 2개(정류장 근처 토글, 출퇴근 모드)는 switch 만 토글하므로 변경 없음.

2️⃣ 한국 버스 호환성 — 솔직한 표

사용자가 한국 버스 선호 (API 키 불필요, 전국 지원). v4.7.0 / v4.8.0 업그레이드가 한국 버스에도 적용됐는지 정직하게 점검:

블루프린트	🚌 서울버스	🚍 한국 버스
출발 알람	✅	✅
하차 알람	✅	✅
막차 알람	✅	✅
만차 / 혼잡 알람	✅	❌ (카카오맵 응답에 만차 필드 없음)
정류장 근처 자동 활성화	✅	✅
집 떠날 때 알림	✅	✅
목적지 도착 하차 알람	✅	✅
출퇴근 자동 모드	✅	✅

→ 8개 중 7개 호환. 한국 버스 사용자도 자동화 도구 95% 그대로 활용 가능. 만차 알람만 서울버스 전용 (카카오맵 모바일 응답 한계).

README.md / README.en.md 양쪽에 호환성 표 + action selector 안내 섹션 추가.

변경 사항

• 6개 블루프린트 (bus_departure_alert, bus_alight_alert, bus_lastride_alert, bus_crowded_alert, leaving_home_alert, arrival_alight_alert) notify input 패턴 변경
• README.md + README.en.md 호환성 매트릭스 + selector 안내
• 8개 블루프린트 YAML 재검증 통과

코드(custom_components) 변경 없음. 사용자가 import 후 default action 만 본인 서비스로 한 번 바꾸시면 됩니다.

v4.8.0 — 위치 기반 블루프린트 4종 (device_tracker 활용)

📱 HA Companion App 핸드폰 위치 추적 + 블루프린트 = 일반 버스앱 못 하는 자동화

v4.7.0 의 sensor + binary_sensor + 활성화 스위치 위에 device_tracker 위치 신호를 결합한 블루프린트 4종 추가. 블루프린트 총 8종 으로 확장.

🌟 위치 기반 블루프린트 4종

블루프린트	핵심 동작
🚏 정류장 근처 자동 활성화	폰이 정류장 zone 진입 → 활성화 스위치 ON, 떠나면 N분 후 OFF
🏠 집 떠날 때 버스 시간 알림	zone.home 떠나는 순간 다음 버스 ETA 푸시
📍 목적지 도착 시 하차 알람	폰이 목적지 zone 진입 → 푸시. 버스에서 잠들어도 위치로 깨움 (일반 버스앱이 못 하는 강점)
🌍 출퇴근 자동 모드	시간 + 위치 → 활성화 스위치 자동 ON/OFF. 원본 개발자 자동화 패턴 단순화 + 평일만 옵션

Import URL

정류장 근처 자동 활성화: https://github.com/redchupa/kr_component_kit/blob/main/blueprints/automation/kr_component_kit/stop_proximity_toggle.yaml
집 떠날 때 버스 알림:    https://github.com/redchupa/kr_component_kit/blob/main/blueprints/automation/kr_component_kit/leaving_home_alert.yaml
목적지 도착 하차 알람:  https://github.com/redchupa/kr_component_kit/blob/main/blueprints/automation/kr_component_kit/arrival_alight_alert.yaml
출퇴근 자동 모드:        https://github.com/redchupa/kr_component_kit/blob/main/blueprints/automation/kr_component_kit/commute_auto_mode.yaml

HA → 자동화 → 블루프린트 → 블루프린트 가져오기 → 위 URL 붙여넣기.

선행 단계

1. HA → 설정 → 영역(Zone) → 추가
2. 정류장 좌표 입력 (카카오맵에서 우클릭 → 좌표 복사)
3. 반경: 정류장 100200m, 회사/학교 200300m 권장

조합 예시

🏃 외출 자동화 (정류장 근처 + 집 떠날 때)

• 집 떠나면 → 다음 버스 ETA 푸시
• 정류장 근처 도착 → 활성화 스위치 자동 ON → 60초마다 폴링 갱신
• 정류장 떠나면 → N분 후 자동 OFF (API 호출 절감)

💤 안전한 하차 (목적지 도착 알람)

• 버스에서 잠들어도 폰 위치 기반 알람
• 만차/우회/지연으로 sensor 정보 부정확해도 알람 작동

🌍 평일 자동 폴링 (출퇴근 자동 모드)

• 평일 06:30 + 집 안 → ON
• 회사 도착 → 자동 OFF
• 평일 17:30 + 회사 안 → ON
• 집 도착 → 자동 OFF
• 주말/외출 → 자동화 무시 → API 0회

변경 사항

• 4개 신규 블루프린트 (blueprints/automation/kr_component_kit/*.yaml)
• README.md / README.en.md 위치 기반 섹션 추가
• 모든 8개 블루프린트 YAML 검증 통과 (!input → variables: → template 패턴)

코드 변경 없음 — 사용자가 v4.7.0의 entity 들과 본인 폰 device_tracker 만 있으면 즉시 자동화 완성.

v4.7.0 — 활용사례 패턴 흡수: 혼잡도/만차 + 4개 블루프린트

📊 공공데이터 활용사례 45개 → HA 기본 도구로

서울버스 도착정보 API 가 이미 응답에 담아주는 신호들을 사용자가 자동화에 활용할 수 있는 형태 로 노출했습니다. 그리고 활용사례 빈도 1~4위인 알람 패턴을 블루프린트 로 제공합니다.

🌟 Tier 1 — 데이터 노출

서울버스 sensor attributes 6개 추가

이미 API 응답에 있던 필드를 attribute 로 처음 노출:

attribute	의미
is_full	만차 여부 (boolean)
is_low_floor	저상버스 여부 (boolean — 휠체어/유모차 접근)
bus_type	차종 (일반 / 저상 / 굴절)
congestion	혼잡도 (여유 / 보통 / 혼잡)
passengers_aboard	재차 인원
remaining_seats	잔여좌석 (광역버스용)

서울버스 binary_sensor 2종 신규

노선당 자동 생성, 자동화 트리거로 직접 사용 가능:

• binary_sensor.seoul_bus_<id>_<route>_low_floor — 다음 버스가 저상버스면 ON
• binary_sensor.seoul_bus_<id>_<route>_full — 다음 버스가 만차면 ON (congestion / passengers / seats attribute 동반)

한국버스는 카카오맵 응답에 만차/혼잡 필드가 없어서 binary_sensor 미지원 — 다른 attribute 만 동일하게 노출.

🎁 Tier 2 — 4개 블루프린트 (즉시 import 가능)

블루프린트	트리거	용도
🚌 출발 알람	TIMESTAMP 가 N분 이내 진입	"지금 출발하세요" 푸시
🔔 하차 알람	current_stop 변화 + 목적지 매칭	내릴 정거장 알람
🌙 막차 알람	last_vehicle / is_last flip	"이번이 막차입니다"
🚨 만차/혼잡 알람	만차 binary_sensor + 혼잡도	다음 차 도착시간 추천

Import URL — HA → 자동화 → 블루프린트 → 가져오기 → 아래 URL 붙여넣기:

출발: https://github.com/redchupa/kr_component_kit/blob/main/blueprints/automation/kr_component_kit/bus_departure_alert.yaml
하차: https://github.com/redchupa/kr_component_kit/blob/main/blueprints/automation/kr_component_kit/bus_alight_alert.yaml
막차: https://github.com/redchupa/kr_component_kit/blob/main/blueprints/automation/kr_component_kit/bus_lastride_alert.yaml
만차: https://github.com/redchupa/kr_component_kit/blob/main/blueprints/automation/kr_component_kit/bus_crowded_alert.yaml

각 블루프린트는 UI에서 sensor + 알림 디바이스 + 분 만 선택하면 자동화 완성. 모바일 푸시는 HA Companion App 의 notify.mobile_app_<phone> 서비스 활용.

코드 변경 통계

10 files changed · 469 insertions · 7 deletions

카테고리	파일
Tier 1	seoul_bus/sensor.py, seoul_bus/binary_sensor.py (신규), binary_sensor.py (분기 추가), __init__.py (Platform.BINARY_SENSOR 등록)
Tier 2	blueprints/automation/kr_component_kit/*.yaml 4개
문서	README.md, README.en.md 새 섹션

알려진 한계

• 블루프린트의 알림 서비스 입력은 text selector — 사용자가 notify. 접두사 제외하고 입력 (mobile_app_my_phone). 향후 service selector 로 개선 가능.
• 한국버스는 카카오맵 응답 구조 한계로 만차/혼잡 binary_sensor 없음 — 서울버스 전용 기능.

v4.6.2 — 홍보 직전 최종 검토: invalid_auth 번역 누락 수정

🔍 홍보 직전 풀스택 검토 — 1가지 진짜 버그 발견 + 패치

서울버스 + 한국버스 양쪽 흐름을 코드부터 라이브 API 까지 깊이 검토했고, 그 김에 다른 entry type 들도 i18n 일관성을 cross-check 했어요.

✅ 검증 통과

• config_flow.py 49개 step_id 모두 4개 lang 파일 (strings + en + ko + ja) 에 라벨 존재
• abort reason 3개 (no_options / no_stations / no_stops) 모두 커버
• seoul_bus 라이브 API: 코드는 정상 동작 (사용자 키만 아직 활성화 안 됨 — 외부 시스템 이슈)
• korea_bus 라이브 API: 사당역 검색 → 15개 정류장 → 첫 정류장 도착정보 → 350번 버스 320초 후 도착, 모든 attribute 매핑 정상
• manifest.json + hacs.json: HACS Default 심사 통과 메타데이터 완비
• 시나리오 walkthrough: 첫 설치 / 옵션 변경 / X 닫기 cancel / RestoreEntity 복원 / switch ON-OFF / 마이그레이션 v1→v2→v3 모두 정상

🐛 발견 + 패치

invalid_auth 에러 키가 4개 lang 모두에서 누락 — config_flow.py 5곳에서 사용 중인데 번역 파일 어디에도 없었음:

• KEPCO 로그인 실패 (line 513)
• GasApp 인증 실패 (line 542)
• GasApp validation false (line 550)
• Arisu connection error (line 582)
• Arisu 빈 청구 데이터 (line 590)

→ 사용자가 잘못된 ID/비밀번호 입력 시 친절한 안내 대신 영문 키 invalid_auth 가 UI에 그대로 노출되는 상황이었어요. 버스 흐름엔 직접 영향 없지만 홍보 시 같이 노출되는 다른 entry types 사용자가 부딪힘. 4개 lang 모두에 적절한 메시지 추가:

언어	메시지
🇰🇷	"로그인 실패. 입력하신 아이디·비밀번호·토큰을 다시 확인하고 시도해주세요. (한전·아리수·가스앱 통합에 해당)"
🇺🇸	"Login failed. Double-check your username/password/token and try again."
🇯🇵	"ログインに失敗しました。ID・パスワード・トークンを確認して再試行してください。"

부차 정리

• seoul_bus/api.py validate_api_key docstring 의 "~1h" → "~24h" (v4.5.3 에서 user-facing 메시지는 24h로 정정했는데 docstring 잔재 — 일관성)

알려진 corner case (이번엔 패치 안 함)

• 옵션에서 정류장 셋을 변경해도 entry unique_id 는 첫 등록 시점 그대로. 사용자가 같은 정류장 셋으로 별개 통합 추가 시도 시 이론적 중복 가능. 일반 사용자 corner case 라 우선순위 낮음, 추후 별도 PR.

이제 홍보 가셔도 됩니다. 서울버스는 키 활성화만 외부 의존이고, 한국버스는 키 불필요 + 라이브 정상 동작 확인됨.

v4.6.1 — README 보강 (처음 사용자 가이드)

📚 README 4가지 누락 채움

처음 설치하는 사용자가 README 만 보고 설정을 끝낼 수 있도록 누락된 부분을 채웠습니다 (한국어 + 영문 동시).

1. 🚌 서울버스 API 키 발급 가이드

다른 data.go.kr 서비스 (약국, 재난문자, 기상특보, 에어코리아, 유가, 학교) 는 단계별 카드가 있는데 서울버스만 빠져 있었어요. 동일 포맷으로 추가:

• 정확한 dataset 이름 (서울특별시_정류소정보조회 서비스)
• 포털 바로가기 링크
• endpoint, 일일 호출 한도
• 신청 단계

2. ⚠️ 24시간 키 활성화 대기 안내

설정 시 가장 큰 걸림돌 — 마이페이지에 "승인 + 활용기간 오늘부터" 로 표시되어도 실제 API gateway 등록까지 ~24시간 추가 대기 필요. 사용자가 발급 직후 등록 시도하다 "API 키가 유효하지 않습니다" 메시지에 막혀 하루를 헛쓰는 케이스가 흔해서, 키 발급 가이드 안에 명확히 명시.

3. 🔌 활성화 스위치 사용법 + 자동화 예시

v4.5.0 에서 추가, v4.6.0 에서 이름 변경된 이 기능을 README 에 처음으로 문서화:

• 용도 (API 호출 한도 절감, 새벽 폴링 회피)
• default 동작 (신규 설치 ON, 재시작 시 마지막 상태 복원)
• 완성된 자동화 YAML — 시간 + 거리 조건 조합으로 출퇴근 시간에만 폴링
• HACS state-switch 카드로 대시보드 조건부 표시

4. ⚙️ 정류장 관리 옵션 메뉴

삭제·재등록 없이 정류장 추가/삭제/노선 편집 가능한 옵션 메뉴를 표로 정리. transactional 패턴 (X 닫기 = 변경 무효) 도 명시.

v4.6.0 — 활성화 스위치 이름 정리 (_api_active → _update_active)

🏷 스위치 entity_id 정리 — _api_active → _update_active

기존 이름의 문제점:

"한국 버스는 API 키가 필요 없는데 switch.korea_bus_bs451656_api_active 라는 이름은 헷갈려요."

맞는 지적. 한국 버스는 카카오맵 모바일 사이트를 스크래핑하는 방식이라 API 키가 아예 없습니다. 스위치의 진짜 역할은 폴링 게이트 (켜져 있을 때만 갱신 호출) — 그래서 이름을 _update_active 로 통일했어요. 한국어 entity name "업데이트 활성화" 와도 일치.

변경 사항

항목	이전	새로움
서울버스 스위치	switch.seoul_bus_<ars>_api_active	switch.seoul_bus_<ars>_update_active
한국버스 스위치	switch.korea_bus_<stop>_api_active	switch.korea_bus_<stop>_update_active
unique_id	..._api_active	..._update_active
아이콘	mdi:api	mdi:autorenew (자동 갱신 화살표 — 폴링 의미에 맞음)

🛡 자동 마이그레이션 (기존 사용자 손상 없음)

ConfigFlow.VERSION 2 → 3 bump. async_migrate_entry v2→v3 블록이 entity_registry 를 순회해서:

• unique_id 의 _api_active 접미사 → _update_active 로 자동 변환
• entity_id 의 동일 접미사도 함께 변환
• statistics / device_id 연결은 unique_id 기반이라 끊김 없음

업데이트만 하시면 자동으로 새 이름으로 이전됩니다.

⚠️ 자동화 / 대시보드 YAML 수정 필요

옛 entity_id 를 참조하던 자동화 / 대시보드는 사용자가 직접 수정해야 합니다 (HA 가 entity_id 자체는 옮기지만, YAML 안의 텍스트 참조는 못 바꿔요):

찾아서 바꿀 문자열:

switch.seoul_bus_*****_api_active   →   switch.seoul_bus_*****_update_active
switch.korea_bus_*****_api_active   →   switch.korea_bus_*****_update_active

일괄 변경 팁 (대시보드 RAW 편집기 또는 자동화 YAML 에디터에서):

• 찾기: _api_active
• 바꾸기: _update_active

이미 자동화가 작동하던 사용자분께는 한 번의 일괄 치환이 필요한 점 양해 부탁드립니다. 의미 정확성을 위한 일회성 비용입니다.

v4.5.4 — 활성화 스위치 default ON + OFF/한국버스 라이브 검증

🌟 활성화 스위치 default ON

신규 설치 시 활성화 스위치가 default ON 으로 시작합니다. 사용자가 정류장 등록 후 데이터를 즉시 보고 싶은 게 자연스러운데, 기존 default OFF 는 "왜 데이터가 안 보이지" 혼란을 유발했어요.

기존 설치는 영향 없음 — RestoreEntity 가 이 default 를 사용자의 마지막 ON/OFF 상태로 덮어쓰기 때문에, 이전에 OFF 로 두셨다면 재시작 후에도 OFF 그대로 유지됩니다.

✅ OFF 동작 검증 (서울버스 + 한국버스 모두)

시점	코드	OFF 시 동작
폴링 cycle (60s/scan_interval)	_async_update_data 첫 줄 if not self.api_enabled: return self.data or {}	early return, fetch 함수 호출 없음 ✓
새로고침 버튼 클릭	if not getattr(self._coordinator, "api_enabled", True): return	no-op + warning log ✓
사용자 switch OFF 토글	coordinator.api_enabled = False 즉시 적용	다음 cycle부터 skip ✓
사용자 switch ON 토글	coordinator.api_enabled = True + async_request_refresh()	즉시 1회 fetch + 이후 cycle 폴링 ✓

🔍 한국 버스 라이브 검증

KakaoMap mobile API 를 실제 호출해서 우리 sensor 가 읽는 필드 셋이 라이브 응답과 정말 일치하는지 검증했습니다:

• searchView → 강남역 권역에서 진짜 정류장 15개 추출 ✓
• 그 중 첫 정류장의 busesInBusStopJson 응답 → HTTP 200 + 정상 JSON ✓
• 우리 sensor 가 읽는 모든 key (slot 0/1 의 arrivalTime, vehicleNumber, currentBusStopName, vehicleStateMessage, remainSeat, collectDateTime, lastVehicle, busStopCount + slot 0 의 direction, typeName, first, last, intervals, nextBusStopName) 가 라이브 응답에 100% 존재 ✓
• "Missing from API: []" — sensor 매핑이 현재 API 와 완전 동기

한국 버스 흐름은 패치 없이 그대로 정상 동작합니다.

향후 개선 여지 (이번엔 패치 안 함)

라이브 응답에는 우리가 안 읽는 필드도 있어요:

• busName1, busName2 — 노선 명시
• realtimeState — "운행중" / "운행종료"
• endPoints, startPoints — 기점/종점
• nextBusStopId — 다음 정류장 ID
• cpName — 통신사 명

추후 attribute 보강 시 활용 가능. 현재 동작에 영향 없음.

v4.5.3 — data.go.kr 활성화 지연 24시간 안내 정정

📝 한국어 안내 메시지 정정 — 1시간 → 24시간

사용자 확인 사실: data.go.kr 키는 활용신청 승인 직후 마이페이지에 "승인 + 활용기간 = 오늘부터" 로 표시되지만, 실제 API gateway 인증모듈에 키가 등록되기까지 약 24시간 소요. 그 사이엔 headerCd=7 + Key인증실패: SERVICE KEY IS NOT REGISTERED ERROR 응답이 옵니다.

기존 안내 메시지는 "1시간 정도 후 재시도" 였는데 이게 부정확해서 사용자가 1~2시간 단위로 반복 시도하며 혼란을 겪었습니다. 정정합니다.

변경 위치

• config/error/invalid_api_key + options/error/invalid_api_key (동일 메시지, 두 곳):

  "API 키가 유효하지 않거나 아직 활성화되지 않았습니다. data.go.kr 키는 신청 승인 후 인증모듈 등록까지 24시간 정도 걸립니다 (포털 화면에 '승인'으로 표시되어도 그 시점부터 24시간). 마이페이지에서 활용기간이 오늘부터인지 확인하고 24시간 경과 후 재시도하세요. 24시간 지나도 같은 에러면 data.go.kr 고객센터 1566-0025 또는 활용신청 해제 후 재신청."

• config/step/seoul_bus/description (첫 등록 화면):

  "공공데이터포털(data.go.kr)에서 서울특별시_정류소정보조회 서비스를 신청해 발급받은 인증키를 입력하세요.

  ⚠️ 중요: data.go.kr 키는 활용신청 승인 후 인증모듈 등록까지 약 24시간 소요됩니다. 발급 직후 등록 시 'API 키가 유효하지 않다'고 나오면 24시간 후 다시 시도하세요."

코드는 그대로

v4.5.2 의 키워드 매칭 fix 가 이미 SERVICE_KEY_IS_NOT_REGISTERED 응답을 invalid_api_key 로 정확히 분류하고 있어요. 이번 release 는 사용자에게 보이는 안내 텍스트만 정정. 24시간 후엔 같은 화면에 정류장 등록이 정상 진행됩니다.

v4.5.2 — 라이브 API 검증 후 인증 에러 메시지 매칭 fix

🎯 이번엔 추측 없이, 라이브 API 응답을 직접 확인 후 fix

사용자 키 + ARS 17003 로 실제 endpoint 호출:

<headerCd>7</headerCd>
<headerMsg>Key인증실패: SERVICE KEY IS NOT REGISTERED ERROR.[인증모듈 에러코드(30)]</headerMsg>

두 가지 사실

1. 사용자 키가 아직 활성화 안 됐어요 — data.go.kr 키는 발급 직후 ~1시간 대기. 활용기간이 오늘(2026-05-18) 시작이라 정상적인 시간 지연.
2. 우리 코드 버그도 같이 발견 — validate_api_key 의 인증 에러 키워드 화이트리스트가 underscore 형식만 갖고 있었어요. 실제 API는 공백 형식 + 한국어 프리픽스 로 응답:
   • 우리 패턴: SERVICE_KEY_IS_NOT_REGISTERED ❌ 매치 안 됨
   • 실제 메시지: Key인증실패: SERVICE KEY IS NOT REGISTERED ERROR ✓
   • → 결과: invalid_api_key 대신 cannot_connect 로 잘못 분류

Fix

관찰된 실제 응답 shape 모두 매칭하도록 화이트리스트 확장:

• SERVICE KEY IS NOT REGISTERED (공백, 오늘 라이브 관찰됨)
• SERVICE_KEY_IS_NOT_REGISTERED (underscore, 원래 가정)
• 키인증 / 인증실패 (한국어 프리픽스)
• • 할당량 초과 / 만료 / unauthorized shape 들 (공백/underscore 양쪽)

Commit 전에 captured response string 으로 simulation 실행 → SERVICE KEY IS NOT REGISTERED 와 인증실패 둘 다 매칭 확인.

사용자 입장에서 무엇이 바뀌나

이제 동일 ARS-ID 다시 입력 → "API에 연결할 수 없습니다" 가 아니라:

"API 키가 유효하지 않습니다. 발급 직후라면 data.go.kr 마이페이지 → 활용신청 현황에서 승인됨 상태인지 + 활용기간이 오늘부터인지 확인 후 1시간 정도 후 재시도하세요 (활성화 지연)."

→ 정확한 원인 + 정확한 안내. 사용자는 그냥 1시간 정도 기다리시면 됩니다.

교훈

지난 며칠 시행착오의 진짜 교훈: 코드 패치 전에 라이브 API를 직접 호출해 응답 shape 부터 확인. curl 한 번이면 끝나는 일을 추측만으로 여러 번 헛다리 짚었음. 향후 작업에선 이 순서로 진행합니다.