docs: comprehensive README rewrite for first-time users#15
Merged
Conversation
- Add 👋 onboarding section with situation-based reading order - Add 🚀 5-minute quickstart using API-key-free safety alert path - Enrich every service box with "what entities get created" examples grounded in actual code (sensor.py / translations/ko.json) - Add 🔑 API key issuance guide with portal map, common-mistake callouts, and pharmacy/disaster step-by-step - Add ❓ FAQ section (12 items) covering free/paid, multi-region, mobile push, voice queries, reconfigure, delete, updates - Clarify entity_id slug behavior (Korean → romanized) and friendly-name lookup workflow - Document gasapp token extraction caveat, KakaoMap busstopid extraction, NEIS auto school search, earthquake default coordinates - Fix inaccuracies: disaster portal (safetydata.go.kr ≠ data.go.kr), Arisu field name (수용가번호), HA search name (한국 컴포넌트 키트), KEPCO sensor list (no 누진단계), fuel attribute (ranking[] not low_price_stations), gasapp update interval (20m) - Add stable automation YAML examples with unknown/unavailable guards - Note HACS Default registration is in progress (currently Custom Repository) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…+ endpoints
Previously, README listed several data.go.kr dataset names that were inferred
from endpoint URL paths rather than verified against the actual portal listings.
Cross-referencing with a real user's data.go.kr 활용신청 list revealed mismatches:
- Pharmacy: "응급의료기관/약국 정보 조회 서비스" (inferred from URL) was
presented as the primary search keyword, but the actual registered dataset name
is "국립중앙의료원_전국 약국 정보 조회 서비스". Search keyword 응급의료 leads
users astray when 전국 약국 / 약국 정보 is the correct hit.
- Weather warning: "통보문" was an added word not in actual registered name
("기상청_기상특보 조회서비스").
- Short-term forecast: "((구)_동네예보)" parenthetical was unverified
(actual name is just "기상청_단기예보 조회서비스").
- AirKorea: README mentioned only 대기오염정보 as required, but the integration
also calls MsrstnInfoInqireSvc, so 측정소정보 is a separate required
활용신청 — missed in original guide.
- Living index: "기상청_생활기상지수 조회서비스 V4" — V4 dataset does not
appear to be separately registered on the portal; the dataset shown as "(3.0)"
actually serves a V5 endpoint, while our code still calls V4. Documented this
as a known compatibility issue rather than a clean activation path.
- Disaster alert: "재난문자방송 정보 조회 서비스" — name not independently
verified; switched guidance to endpoint URL (DSSP-IF-00247) which is verified
from the source code.
Restructured the master table to clearly separate:
- ✅ Verified facts (endpoint URLs from source code, operator codes)
- 🔎 Search keywords (what to type into portal search)
- dataset registration names (mutable, no longer treated as authoritative)
Added explicit note that 활용신청 must be done per-dataset (same key, different
datasets each need separate 신청).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…badge Per-service⚠️ lines added so users know fragility before registering: - KEPCO: login marker hardcoded, no 2FA support - Arisu: HTML scraping, 9-digit customer number regex assumed - Safety Alert: HTML scraping + TLS profile fragility; old-schema orphan entity pattern documented (17-sensor pattern seen in real HA — entry recreation recommended if seen) - School (NEIS): INFO-200 (no-data) currently treated as error — log noise expected on empty days Bus transit guide split into 3 scenarios (subway-only / bus-only no key / +transfer-search) reflecting actual code behavior: - Bus arrivals use KakaoMap unofficial endpoint (no API key) - bus_api_key is ONLY for transfer path search (transfer_api.py) Pharmacy box marked ✅ "작동 검증 완료" — verified via live HA query showing sensor.yaggug_siheungsi_unyeong_yaggug_su state=20 with full pharmacies[] attribute populated. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Merged
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
신규 사용자가 README만 보고 설치·설정·문제 해결까지 자력으로 가능한 가이드로 전면 재작성.
sensor.py,translations/ko.json)에서 검증한 친화 이름·attribute 목록 + 입력값 추출 방법 (가스앱 토큰, 카카오맵 정류장 ID 등)정확성 교정 (코드 검증 기반)
data.go.kr→safetydata.go.kr(별도 포털, 식별번호 DSSP-IF-00247)low_price_stations[]→ 실제ranking[]15분"이라 잘못 적힌 부분 → **2030분** (표와 일치)curl_cffi외에beautifulsoup4>=4.12.0도 자동 설치됨을 명시Test plan
#-면책조항variation selector 이슈는 일반 텍스트로 회피)unknown/unavailable가드 포함된 안정 패턴🤖 Generated with Claude Code