fix(k-skill-proxy): 상위 연결 실패를 503/504로 구분 (#700)

[vkehfdl1]

Refs #700 (원인 일부는 gpu01 egress 밖 상위/경로 문제라 이 PR만으로 라우트가 복구되지는 않습니다)

진단 결과

이슈의 실패 라우트는 모두 같은 상위 네트워크를 공유합니다.

Route	상위 호스트	확인된 응답
/v1/korea-weather/forecast	apis.data.go.kr (27.101.236.63)	500 proxy_error / "fetch failed"
/v1/korean-holiday/calendar	apis.data.go.kr	500 fetch failed
/v1/kosis/search	kosis.kr (27.101.194.203)	500 fetch failed
/v1/fine-dust/report	apis.data.go.kr	502 upstream_fetch_failed
/v1/fsc/corp-outline	apis.data.go.kr	504 upstream_timeout

• Mac과 gpu01에서 27.101.0.0/16(KMA·AirKorea·MOLIT·KOSIS 호스트)로의 TCP 443/80 연결이 모두 timeout(DNS는 1.1.1.1/KT DNS 모두 정상 해석).
• api.odcloud.kr(NTS, Naver Cloud)는 정상 → 일반 네트워크 장애 아님.
• 독립 경로(r.jina.ai)에서 www.data.go.kr는 응답 → 프록시 설정 문제 아님.
• 따라서 라우트 복구는 상위/ISP 경로 복구가 필요하며, 프록시 코드로 고칠 수 있는 부분은 오류 구분입니다(이슈 요청 3번).

변경

• packages/k-skill-proxy/src/upstream-errors.js 신규: classifyUpstreamFailure()가 DNS/connect 실패를 503 upstream_unreachable, connect/response timeout을 504 upstream_timeout으로 매핑.
• setErrorHandler가 이 분류를 사용해 upstream.cause(소켓 코드)와 upstream.route를 함께 응답. 기존 error.code/statusCode(예: AirKorea upstream_fetch_failed 502, FSC upstream_timeout 504)는 그대로 유지.
• docs/deploy-k-skill-proxy.md에 "Upstream connectivity triage" 절차 추가.

검증

• packages/k-skill-proxy/test/server.test.js: 분류기 단위 테스트 + weather/KOSIS/holiday 라우트가 fetch 실패 시 503 upstream_unreachable(cause ECONNREFUSED), timeout 시 504 upstream_timeout(cause ABORT_ERR)을 반환하는 통합 테스트. node --test 430 pass / 0 fail.
• live QA(로컬 프록시 + 현재 죽어 있는 상위):

GET /v1/korea-weather/forecast?nx=60&ny=127
{"error":"upstream_timeout","message":"fetch failed","upstream":{"failure":"upstream_timeout","cause":"UND_ERR_CONNECT_TIMEOUT","route":"/v1/korea-weather/forecast?nx=60&ny=127"}}  HTTP=504
GET /v1/kosis/search?q=인구            → 504 upstream_timeout (cause UND_ERR_CONNECT_TIMEOUT)
GET /v1/korean-holiday/calendar?...    → 504 upstream_timeout
GET /v1/fine-dust/report?...           → 502 upstream_fetch_failed (기존 분류 유지)
GET /v1/fsc/corp-outline?...           → 504 upstream_timeout (기존 분류 유지)

• npm run lint 통과.

남은 작업 (이 PR 범위 밖)

• gpu01에서 27.101.0.0/16 도달성/라우팅과 ISP 경로 확인, 상위 복구 후 재현 명령·/health·/privacy 재실행. 복구 전까지 #700은 열어 둡니다.