mirrors/k-skill
2
0
Fork 0
mirror of https://github.com/NomaDamas/k-skill.git synced 2026-06-24 02:04:11 +00:00
Code Issues Projects Releases Packages Wiki Activity
k-skill/docs/features/korea-weather.md
Jeffrey (Dongkyu) Kim dc9a765e2a
 Feature/#205 (#210) 
* Align proxy defaults for hosted Korean routes

Constraint: Issue #205 requires unset or empty KSKILL_PROXY_BASE_URL to use the hosted proxy consistently while preserving explicit proxy overrides and server-side upstream keys.\nRejected: Keeping Seoul subway and Korea weather as self-host-only routes | it preserves the documented inconsistency and blocks zero-config usage.\nConfidence: high\nScope-risk: narrow\nDirective: Keep client docs pointing to hosted proxy defaults unless a route is intentionally removed from hosted service.\nTested: node --test scripts/skill-docs.test.js; npm run ci; hosted smoke curls for /v1/seoul-subway/arrival and /v1/korea-weather/forecast; architect verification approved.\nNot-tested: Private self-host proxy deployment.

* Preserve hosted proxy fallback in setup guidance

Make self-host proxy examples inactive by default so client setup no longer blocks the hosted proxy resolver contract for Seoul subway and Korea weather skills.

Constraint: PR #210 review required unset and empty KSKILL_PROXY_BASE_URL to fall back to https://k-skill-proxy.nomadamas.org while preserving explicit self-host overrides.\nRejected: Keep active https://your-proxy.example.com placeholder | It creates a non-empty override and prevents hosted fallback for users copying the default secrets file.\nConfidence: high\nScope-risk: narrow\nDirective: Keep upstream API keys documented as proxy-operator/server-side only; do not reintroduce active client-side proxy placeholders for hosted-default flows.\nTested: node --test scripts/skill-docs.test.js; npm run ci; hosted smoke checks for /v1/seoul-subway/arrival?stationName=강남 and /v1/korea-weather/forecast?lat=37.5665&lon=126.9780; resolver smoke for unset, empty, and custom KSKILL_PROXY_BASE_URL; git diff --check; Ralph architect verification CLEAR.\nNot-tested: none

* Clarify proxy guide override boundary

Document the hosted-client default in the proxy guide while keeping the self-host placeholder as an explicitly scoped override, so users do not mistake it for required setup.

Constraint: Issue #205 review round 2 left a WATCH concern on docs/features/k-skill-proxy.md client env-var wording.

Rejected: Leave the proxy guide unchanged | It preserved ambiguity between hosted-client defaults and self-host/operator overrides.

Rejected: Sentence-exact regression assertions | They were too brittle after code review; semantic assertions preserve wording flexibility while locking the policy.

Confidence: high

Scope-risk: narrow

Directive: Keep KSKILL_PROXY_BASE_URL examples inactive or clearly scoped unless documenting a self-host/alternate-proxy override.

Tested: node --test scripts/skill-docs.test.js; npm run ci; resolver smoke for unset empty and custom KSKILL_PROXY_BASE_URL; hosted Seoul subway and Korea weather smokes; git diff --check; code-reviewer APPROVE; architect CLEAR

Not-tested: none

* Keep proxy guide examples on the hosted-default path

Constraint: PR #210 issue #205 follow-up requires KSKILL_PROXY_BASE_URL unset/empty to resolve to hosted while preserving explicit self-host overrides.\nRejected: Labeling the existing 127.0.0.1 examples as operator-only | it would leave the general usage section less aligned with the hosted-client default.\nConfidence: high\nScope-risk: narrow\nDirective: Keep Seoul subway and Korea weather user-facing examples on the resolver pattern unless the section is explicitly scoped to local operator smoke tests.\nTested: node --test scripts/skill-docs.test.js; npm run ci; resolver smoke for unset empty custom KSKILL_PROXY_BASE_URL; hosted Seoul subway and Korea weather smoke; architect verification CLEAR.\nNot-tested: None.
2026-05-06 16:56:40 +09:00

2.8 KiB
Raw Permalink Blame History

한국 날씨 조회 가이드

이 기능으로 할 수 있는 일

  • 한국 기상청 단기예보 조회서비스를 proxy 경유로 호출
  • nx / ny 격자 또는 lat / lon 기준 단기예보 확인
  • 개인 OpenAPI key 없이 TMP, SKY, PTY, POP 같은 핵심 날씨 category 요약

먼저 필요한 것

필요한 환경변수

  • 없음. KSKILL_PROXY_BASE_URL 은 선택 사항이며, 비우면 기본 hosted https://k-skill-proxy.nomadamas.org 를 사용한다.

사용자가 공공데이터포털 기상청 단기예보 API key를 직접 발급할 필요는 없다. /v1/korea-weather/forecast route는 기본 hosted proxy에서 호출하고, upstream KMA_OPEN_API_KEY 는 proxy 서버에서만 관리한다. 별도 proxy를 쓰는 경우에만 KSKILL_PROXY_BASE_URL 을 설정한다.

입력값

  • 격자 좌표 nx, ny
  • 또는 위도/경도 lat, lon
  • 선택 사항: baseDate, baseTime, pageNo, numOfRows

기본 흐름

  1. KSKILL_PROXY_BASE_URL 이 있으면 그 값을 사용하고, 없거나 비어 있으면 기본 hosted proxy https://k-skill-proxy.nomadamas.org 를 사용한다.
  2. /v1/korea-weather/forecast 로 한국 기상청 단기예보를 조회한다.
  3. baseDate / baseTime 을 생략하면 proxy 가 KST 기준 최신 발표 시각을 자동으로 선택한다.
  4. 응답의 item[] 에서 TMP, SKY, PTY, POP, PCP, SNO, REH, WSD 를 우선 요약한다.

예시

위도/경도 기준:

BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
curl -fsS --get "${BASE}/v1/korea-weather/forecast" \
  --data-urlencode 'lat=37.5665' \
  --data-urlencode 'lon=126.9780'

격자 좌표 기준:

BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
curl -fsS --get "${BASE}/v1/korea-weather/forecast" \
  --data-urlencode 'nx=60' \
  --data-urlencode 'ny=127' \
  --data-urlencode 'baseDate=20260405' \
  --data-urlencode 'baseTime=0500'

Category 메모

  • TMP: 기온(℃)
  • SKY: 하늘상태
  • PTY: 강수형태
  • POP: 강수확률(%)
  • PCP: 강수량
  • SNO: 적설
  • REH: 습도(%)
  • WSD: 풍속(m/s)

주의할 점

  • 단기예보는 5km 격자 기반이라 행정구역 경계와 완전히 일치하지 않을 수 있다.
  • 발표 시각 직후에는 최신 baseTime 이 아직 준비되지 않았을 수 있다. proxy 는 보수적으로 직전 발표 시각을 선택한다.
  • self-host proxy 설정은 k-skill 프록시 서버 가이드를 본다.