@things-factory/integration-data-go-kr 10.0.0-beta.62 → 10.0.0-beta.63

package/helps/integration/connector/data-go-kr-connector.md

@@ -9,14 +9,13 @@
 
 하나의 ServiceKey 로 등록 앱의 **구독 중인 모든 서비스** 를 호출할 수 있으므로, Connection 은 보통 앱·법인당 1개만 생성한다.
 
-## 파라미터
+## Connection 필드
 
-| 이름 | 필수 | 설명 |
+| 필드 | 필수 | 설명 |
 | --- | --- | --- |
-| `serviceKey` | O | data.go.kr 일반 인증키 (Decoding/Encoding 모두 허용). 도메인 시크릿으로 저장 권장 |
-| `origin` | △ | API 오리진 오버라이드 (모의 서버/사설 프록시). 기본 `https://apis.data.go.kr` |
-
-> Connection 엔티티의 `endpoint` 필드는 무시됩니다. 오리진 변경은 `origin` 파라미터 사용.
+| `name` | O | Connection 이름 (자유) |
+| `endpoint` | △ | API 오리진. 비워두면 기본값 `https://apis.data.go.kr`. 모의 서버/사설 프록시로 라우팅하려면 해당 오리진 입력 (예: `http://localhost:8080`) |
+| `serviceKey` (params) | O | data.go.kr 일반 인증키 (Decoding/Encoding 모두 허용). `useDomainAttribute=true` 로 도메인 시크릿 저장 권장 |
 
 ## 관련 태스크
 
@@ -34,6 +33,6 @@
 
 등록된 서비스 스펙은 코드상 `SpecRegistry.listServices()` 로 확인 가능. 현재 등록된 서비스:
 
-- [`1613000/BldRgstService_v2` — 국토교통부_건축물대장정보 서비스 v2](../services/building-ledger.md)
+- [`1613000/BldRgstHubService` — 국토교통부_건축물대장 허브 서비스](../services/building-ledger.md)
 
 추가 예정 서비스는 [ROADMAP](https://github.com/hatiolab/things-factory/blob/main/packages/integration-data-go-kr/ROADMAP.md) 참조.

package/helps/integration/services/building-ledger.md

@@ -1,8 +1,9 @@
-# 건축물대장정보 서비스 v2 (`1613000/BldRgstService_v2`)
+# 건축물대장 허브 서비스 (`1613000/BldRgstHubService`)
 
-> 세움터(EAIS) 원천의 건축물대장 정보 Open API. 표제부·총괄표제부·층별개요·부속지번·전유공용면적·주택가격·소유자현황·기본개요 등 **8개 오퍼레이션** 제공.
+> 세움터(EAIS) 원천의 건축물대장 통합 Open API. 표제부·총괄표제부·층별개요·부속지번·전유공용면적·주택가격·소유자현황·기본개요 등 **8개 오퍼레이션** 제공.
 
-- **data.go.kr 페이지**: https://www.data.go.kr/data/15044713/openapi.do
+- **data.go.kr 페이지**: https://www.data.go.kr/data/15134735/openapi.do
+- 구버전 `1613000/BldRgstService_v2` (ID 15044713) 는 본 허브 서비스로 통합·승격됨. 신규 사용자는 본 허브 서비스로 활용신청.
 - **원천**: 국토교통부 세움터 DB
 - **비용**: 무료 (활용신청 후 개발 1만건/일)
 
@@ -35,7 +36,7 @@ PNU 조회 방법:
 
 **예시**
 ```
-operationRef: 1613000/BldRgstService_v2.getBrTitleInfo
+operationRef: 1613000/BldRgstHubService.getBrTitleInfo
 params: { sigunguCd: "11680", bjdongCd: "10300", bun: "823" }
 ```
 
@@ -100,7 +101,7 @@ params: { sigunguCd: "11680", bjdongCd: "10300", bun: "823" }
   "task": "data-go-kr-call",
   "connection": "data-go-kr",
   "params": {
-    "operationRef": "1613000/BldRgstService_v2.getBrTitleInfo",
+    "operationRef": "1613000/BldRgstHubService.getBrTitleInfo",
     "params": { "sigunguCd": "...", "bjdongCd": "...", "bun": "..." }
   }
 }

package/helps/integration/services/weather.md

@@ -0,0 +1,82 @@
+# 기상청 (KMA) 조회 서비스 묶음
+
+기상청 산하 5개 조회 서비스. 모두 기관코드 `1360000` 산하 data.go.kr Open API.
+
+| 서비스 | serviceId | 데이터셋 ID |
+| --- | --- | --- |
+| 단기예보 (동네예보 + 초단기) | `1360000/VilageFcstInfoService_2.0` | 15084084 |
+| 중기예보 (3~10일) | `1360000/MidFcstInfoService` | 15059468 |
+| 기상특보 | `1360000/WthrWrnInfoService` | 15059092 |
+| 종관기상관측 (ASOS, 시간자료) | `1360000/AsosHourlyInfoService` | 15057210 |
+| 방재기상관측 (AWS, 시간자료) | `1360000/AwsHrInfoService` | 15059093 |
+
+대부분의 KMA 서비스가 **하나의 ServiceKey** 로 호출 가능하지만, 데이터셋별로 활용신청을 따로 해야 하는 경우가 있습니다. 마이페이지에서 각 데이터셋의 신청 상태 확인 필요.
+
+---
+
+## 1. 단기예보 (`VilageFcstInfoService_2.0`)
+
+| 오퍼레이션 | 설명 | 발표시각 |
+| --- | --- | --- |
+| `getVilageFcst` | 동네예보 (3일치, 3시간 간격) | 02·05·08·11·14·17·20·23시 (+10분) |
+| `getUltraSrtFcst` | 초단기예보 (6시간) | 매시각 (+45분) |
+| `getUltraSrtNcst` | 초단기실황 (현재 관측) | 매시각 (+10분) |
+
+공통 파라미터: `base_date`(YYYYMMDD), `base_time`(HHMM), `nx`, `ny` (KMA 5km 격자좌표).
+
+**위경도 → 격자**: `latLonToGrid({ latitude, longitude })` 헬퍼 사용 (export 됨). 또는 전용 태스크 [`data-go-kr-weather-short-term-forecast`](../task/weather-short-term-forecast.md) 가 위경도 입력을 자동 변환.
+
+## 2. 중기예보 (`MidFcstInfoService`)
+
+| 오퍼레이션 | 설명 |
+| --- | --- |
+| `getMidFcst` | 중기 전망 (텍스트 해석본) |
+| `getMidLandFcst` | 육상 중기예보 (강수확률·하늘상태) |
+| `getMidTa` | 중기 기온예보 (아침 최저·낮 최고) |
+| `getMidSeaFcst` | 해상 중기예보 |
+
+공통 파라미터: `regId` (광역 권역 코드), `tmFc` (발표시각 YYYYMMDDHHMM, 06·18시 발표).
+
+## 3. 기상특보 (`WthrWrnInfoService`)
+
+| 오퍼레이션 | 설명 |
+| --- | --- |
+| `getWthrWrnList` | 특보 목록 |
+| `getWthrWrnInfo` | 특보 상세 (발표문 본문) |
+
+공통 파라미터: `stnId`(지점 ID, 전국=108), `fromTmFc`/`toTmFc`(YYYYMMDD).
+
+## 4. 종관기상관측 (`AsosHourlyInfoService`)
+
+| 오퍼레이션 | 설명 |
+| --- | --- |
+| `getWthrDataList` | 시간단위 관측 자료 |
+
+파라미터: `dataCd='ASOS'`, `dateCd='HR'`, `startDt`/`startHh`/`endDt`/`endHh`, `stnIds`(서울=108, 부산=159 등).
+
+## 5. 방재기상관측 (`AwsHrInfoService`)
+
+| 오퍼레이션 | 설명 |
+| --- | --- |
+| `getAwsRltmList` | AWS 시간자료 |
+
+파라미터: `tm`(YYYYMMDDHHMM), `stn`(지점 번호, 생략 시 전국).
+
+---
+
+## 호출 방법
+
+전용 태스크가 제공되지 않는 오퍼레이션은 모두 [`data-go-kr-call`](../task/data-go-kr-call.md) 로 호출:
+
+```jsonc
+{
+  "task": "data-go-kr-call",
+  "connection": "data-go-kr",
+  "params": {
+    "operationRef": "1360000/MidFcstInfoService.getMidLandFcst",
+    "params": { "regId": "11B00000", "tmFc": "202604250600" }
+  }
+}
+```
+
+단기예보(`getVilageFcst`)는 자주 쓰이고 격자 변환이 필요하므로 **전용 태스크** [`data-go-kr-weather-short-term-forecast`](../task/weather-short-term-forecast.md) 사용 권장.

package/helps/integration/task/building-ledger.md

@@ -16,7 +16,31 @@ PNU(필지고유번호) 5요소로 조회:
 | `bun` | O | 본번 (자동 4자리 zero-pad) | `223` |
 | `ji` | △ | 부번 (없으면 `0`, 자동 4자리 zero-pad) | `0` |
 
-시나리오 변수 치환 지원 — `{{data.project.sigunguCd}}` 바인딩 가능.
+## 데이터 바인딩
+
+각 입력 필드에 **JS 템플릿 리터럴 문법** `${...}` 으로 이전 step 결과나 변수를 참조할 수 있습니다 (Things-Factory `evaluateTemplate` 표준).
+
+| 표현식 | 의미 |
+| --- | --- |
+| `${data.<path>}` | 직전 step 의 출력 (예: `${data.pnu.sigunguCd}`) |
+| `${variables.<name>}` | 시나리오 시작 시 주입된 변수 |
+| `${user.email}` / `${domain.subdomain}` | 실행 컨텍스트 |
+| `${data.pnu.bun}-${data.pnu.ji}` | 일반 문자열 + 표현식 혼합 |
+| `${Number(data.items[0].totArea) || 0}` | 임의 JS 표현식 가능 |
+
+> ⚠️ `{{...}}` 문법이 **아닙니다**. JS 백틱 템플릿 리터럴 그대로의 `${...}` 입니다.
+
+### 예시 — juso-resolve-address 와 체이닝
+
+이전 step 의 출력 (`{ pnu: {...} }`) 을 본 task 입력에 바인딩:
+
+| 필드 | 값 |
+| --- | --- |
+| `sigunguCd` | `${data.pnu.sigunguCd}` |
+| `bjdongCd` | `${data.pnu.bjdongCd}` |
+| `platGbCd` | `${data.pnu.platGbCd}` |
+| `bun` | `${data.pnu.bun}` |
+| `ji` | `${data.pnu.ji}` |
 
 ## 출력
 

package/helps/integration/task/data-go-kr-call.md

@@ -6,14 +6,41 @@
 
 | 이름 | 필수 | 설명 | 예시 |
 | --- | --- | --- | --- |
-| `operationRef` | O | `<serviceId>.<operationId>` 형식 | `1613000/BldRgstService_v2.getBrTitleInfo` |
-| `params` | △ | 오퍼레이션 파라미터 객체 | `{ "sigunguCd": "11680", "bjdongCd": "10300", "bun": "223" }` |
+| `operationRef` | O | 등록된 모든 오퍼레이션이 **드롭다운**으로 표시됨. 직접 입력도 가능 (스펙 없는 오퍼레이션 호출 시) | `1613000/BldRgstHubService.getBrTitleInfo` |
+| `params` | △ | 해당 오퍼레이션의 파라미터를 JSON 객체로 입력 | `{ "sigunguCd": "11680", "bjdongCd": "10300", "bun": "223" }` |
 
 `operationRef` 가 **등록된 스펙** 을 가리키면:
 - 필수 파라미터 검증 / 기본값 주입 / zero-pad / 길이 검증 / enum 검증이 자동 적용
 - 실패 시 친절한 에러 메시지 (어떤 파라미터가 왜 실패했는지)
 
-스펙에 **없는 오퍼레이션** 도 호출 가능 (검증 스킵). 새 서비스가 추가되어 아직 스펙이 없어도 즉시 사용 가능.
+스펙에 **없는 오퍼레이션** 도 호출 가능 (검증 스킵). 새 서비스가 추가되어 아직 스펙이 없어도 직접 입력으로 즉시 호출 가능.
+
+### 데이터 바인딩
+
+`params` 객체의 각 값은 **JS 템플릿 리터럴 `${...}`** 표현식 지원. 예:
+
+```jsonc
+{
+  "operationRef": "1613000/BldRgstHubService.getBrTitleInfo",
+  "params": {
+    "sigunguCd": "${data.pnu.sigunguCd}",
+    "bjdongCd":  "${data.pnu.bjdongCd}",
+    "bun":       "${data.pnu.bun}",
+    "ji":        "${data.pnu.ji}"
+  }
+}
+```
+
+`{{...}}` 가 **아닙니다**. JS 백틱 템플릿 리터럴 그대로의 `${...}` 표현식.
+
+### ⚠️ 현재 UX 한계
+
+`params` 필드는 현재 **freeform JSON** 으로 받습니다. 선택한 `operationRef` 에 맞춰 폼이 자동 생성되지 않으니, 어떤 키를 써야 하는지는 **서비스 카탈로그 markdown** 또는 코드의 `OperationSpec.params` 를 참고해야 합니다:
+
+- [건축물대장 카탈로그](../services/building-ledger.md)
+- [기상청 카탈로그](../services/weather.md)
+
+이 한계는 ROADMAP Phase 3 (`integration-base` upstream 의 동적 parameterSpec 지원) 에서 해결 예정 — 그때부터는 `operationRef` 선택 시 입력 폼이 자동 생성됩니다.
 
 ## 출력
 
@@ -44,7 +71,7 @@
   "task": "data-go-kr-call",
   "connection": "data-go-kr",
   "params": {
-    "operationRef": "1613000/BldRgstService_v2.getBrTitleInfo",
+    "operationRef": "1613000/BldRgstHubService.getBrTitleInfo",
     "params": {
       "sigunguCd": "11680",
       "bjdongCd": "10300",

package/helps/integration/task/weather-short-term-forecast.md

@@ -0,0 +1,96 @@
+# data-go-kr-weather-short-term-forecast
+
+기상청 단기예보(`getVilageFcst`) 조회 전용 태스크. KMA 격자좌표(nx, ny) 또는 위경도 입력을 받아 동네예보(3일치, 3시간 간격) items 를 반환한다.
+
+## 입력 파라미터
+
+| 이름 | 필수 | 설명 |
+| --- | --- | --- |
+| `baseDate` | O | 발표일자 YYYYMMDD |
+| `baseTime` | O | 발표시각 HHMM. **단기예보 발표시각**: 0200·0500·0800·1100·1400·1700·2000·2300 (+10분 후 제공) |
+| `nx`, `ny` | △ | KMA 5km 격자좌표. 위경도와 둘 중 하나 필수 |
+| `latitude`, `longitude` | △ | 위경도 (입력 시 자동으로 nx/ny 로 변환) |
+| `numOfRows` | △ | 페이지당 결과수. 기본 1000 (3일치 카테고리×시점 합계 약 800+) |
+| `pageNo` | △ | 페이지 번호. 기본 1 |
+
+`(nx, ny)` 와 `(latitude, longitude)` 둘 다 비어있으면 에러. 둘 다 있으면 `(nx, ny)` 우선.
+
+### 데이터 바인딩
+
+모든 필드는 **JS 템플릿 리터럴 `${...}`** 으로 이전 step 결과나 변수를 참조 가능. 예:
+
+```
+latitude:  ${data.coord.latitude}
+longitude: ${data.coord.longitude}
+baseDate:  ${(new Date()).toISOString().slice(0,10).replace(/-/g,'')}
+```
+
+`{{...}}` 가 **아닙니다**. JS 백틱 템플릿 리터럴 그대로의 `${...}` 표현식.
+
+## 출력
+
+```jsonc
+{
+  "items": [
+    {
+      "baseDate": "20260425",
+      "baseTime": "1100",
+      "category": "TMP",      // 카테고리 코드
+      "fcstDate": "20260425",
+      "fcstTime": "1200",
+      "fcstValue": "23",      // 예보값
+      "nx": 60,
+      "ny": 127
+    }
+    /* (카테고리×시점) 조합으로 약 800+ 건 */
+  ]
+}
+```
+
+### 주요 카테고리 코드
+
+| 코드 | 항목 | 단위 |
+| --- | --- | --- |
+| TMP | 1시간 기온 | °C |
+| TMN | 일 최저기온 | °C |
+| TMX | 일 최고기온 | °C |
+| POP | 강수확률 | % |
+| PTY | 강수형태 | 0=없음 / 1=비 / 2=비/눈 / 3=눈 / 4=소나기 |
+| PCP | 1시간 강수량 | mm |
+| SNO | 1시간 신적설 | cm |
+| REH | 습도 | % |
+| SKY | 하늘상태 | 1=맑음 / 3=구름많음 / 4=흐림 |
+| WSD | 풍속 | m/s |
+| VEC | 풍향 | deg |
+
+## 위경도 → 격자 변환
+
+태스크 내부에서 KMA 표준 변환식 (Lambert Conformal Conic) 적용. 모듈 export `latLonToGrid` 를 직접 import 하여 사용 가능:
+
+```ts
+import { latLonToGrid } from '@things-factory/integration-data-go-kr'
+
+const { nx, ny } = latLonToGrid({ latitude: 37.5665, longitude: 126.9780 })
+// 서울시청 → { nx: 60, ny: 127 }
+```
+
+## 다른 단기예보 오퍼레이션 호출
+
+`getUltraSrtFcst` (초단기예보), `getUltraSrtNcst` (초단기실황) 은 동일 서비스 내에 있으므로 [`data-go-kr-call`](./data-go-kr-call.md) 로 호출하세요. 발표시각 규칙이 다르니 [서비스 카탈로그](../services/weather.md) 참조.
+
+```jsonc
+{
+  "task": "data-go-kr-call",
+  "connection": "data-go-kr",
+  "params": {
+    "operationRef": "1360000/VilageFcstInfoService_2.0.getUltraSrtNcst",
+    "params": { "base_date": "20260425", "base_time": "1100", "nx": "60", "ny": "127" }
+  }
+}
+```
+
+## 관련
+
+- [`data-go-kr-connector`](../connector/data-go-kr-connector.md)
+- [`data-go-kr-call`](./data-go-kr-call.md)
+- [기상청 서비스 카탈로그](../services/weather.md)

package/logs/.5e5d741d8b7784a2fbad65eedc0fd46946aaf6f2-audit.json

@@ -0,0 +1,15 @@
+{
+    "keep": {
+        "days": true,
+        "amount": 14
+    },
+    "auditLog": "logs/.5e5d741d8b7784a2fbad65eedc0fd46946aaf6f2-audit.json",
+    "files": [
+        {
+            "date": 1777076185165,
+            "name": "logs/connections-2026-04-25-09.log",
+            "hash": "e3a2bbfa80736f8ffb8cb0effb0f787d4c97d7a571ab5ed50feba08ea9c75b05"
+        }
+    ],
+    "hashType": "sha256"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/integration-data-go-kr",
-  "version": "10.0.0-beta.62",
+  "version": "10.0.0-beta.63",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh <heartyoh@hatiolab.com>",
@@ -24,5 +24,5 @@
   "dependencies": {
     "@things-factory/integration-base": "^10.0.0-beta.57"
   },
-  "gitHead": "5aaec8a7509b2c486e92fba2fd9d893fa5dc2d20"
+  "gitHead": "fd00344470c9d3d25275d9a3e6da227f5b80539e"
 }

package/server/engine/connector/data-go-kr-client.ts

@@ -32,13 +32,13 @@ export class DataGoKrClient {
     /* Encoding 키(%2B 포함)를 붙여넣어도 Decoding 키처럼 동작하도록 정규화.
        base64 키는 `%` 를 포함하지 않으므로 raw Decoding 키는 영향 없음. */
     this.serviceKey = normalizeServiceKey(options.serviceKey.trim())
-    this.origin = (options.origin || DEFAULT_ORIGIN).replace(/\/$/, '')
+    this.origin = resolveOrigin(options.origin)
   }
 
   /**
    * 범용 GET 호출.
    *
-   * @param servicePath `<agency>/<service>/<operation>` (예: `1613000/BldRgstService_v2/getBrTitleInfo`)
+   * @param servicePath `<agency>/<service>/<operation>` (예: `1613000/BldRgstHubService/getBrTitleInfo`)
    * @param params 쿼리 파라미터 (serviceKey / _type 은 자동 추가)
    */
   async get<T>(servicePath: string, params: Record<string, any>): Promise<DataGoKrResponse<T>> {
@@ -114,6 +114,30 @@ export class DataGoKrClient {
   }
 }
 
+/**
+ * Connection.endpoint 값을 검증하여 유효한 origin URL 로 정규화한다.
+ *
+ * - 비어있거나 공백만: 기본 오리진 사용
+ * - 유효한 절대 URL: trailing slash 제거 후 사용
+ * - 유효하지 않은 값: 친절한 에러 throw (단순 오타·누락 방지)
+ */
+function resolveOrigin(value: string | undefined): string {
+  if (!value || !value.trim()) return DEFAULT_ORIGIN
+  const trimmed = value.trim()
+  try {
+    const parsed = new URL(trimmed)
+    if (!parsed.protocol.startsWith('http')) {
+      throw new Error('protocol must be http or https')
+    }
+    return trimmed.replace(/\/$/, '')
+  } catch (err) {
+    throw new Error(
+      `Invalid Connection.endpoint value '${value}': must be a full URL (예: https://apis.data.go.kr) ` +
+        `or empty (기본값 ${DEFAULT_ORIGIN} 사용). Reason: ${(err as Error).message}`
+    )
+  }
+}
+
 /** Encoding 키(%2B) 를 붙여넣어도 Decoding 키로 정규화. */
 function normalizeServiceKey(key: string): string {
   if (!key.includes('%')) return key

package/server/engine/connector/data-go-kr-connector.ts

@@ -8,8 +8,9 @@ import { DataGoKrClient } from './data-go-kr-client'
  * 하나의 ServiceKey 로 data.go.kr 산하 **모든 오퍼레이션** 을 호출할 수 있으므로,
  * 사용자는 Connection 을 보통 한 개만 만들고 (앱·법인별로 1개) 여러 태스크에서 재사용한다.
  *
- * Connection 의 `endpoint` 필드는 무시된다. 오리진 오버라이드가 필요하면 `origin`
- * 파라미터 사용 (모의 서버/사설 프록시).
+ * Connection 의 `endpoint` 필드를 API 오리진(host) 으로 사용한다. 비워두면 기본값
+ * `https://apis.data.go.kr` 가 사용되며, 모의 서버/사설 프록시로 라우팅하려면
+ * 해당 오리진을 endpoint 에 입력한다.
  */
 export interface DataGoKrConnectionInstance {
   client: DataGoKrClient
@@ -22,15 +23,17 @@ export class DataGoKrConnector implements Connector {
   }
 
   async connect(connection) {
-    const { params } = connection
+    const { endpoint, params } = connection
     try {
       const client = new DataGoKrClient({
         serviceKey: params.serviceKey,
-        origin: params.origin
+        origin: endpoint
       })
       const instance: DataGoKrConnectionInstance = { client }
       ConnectionManager.addConnectionInstance(connection, instance)
-      ConnectionManager.logger.info(`data-go-kr-connector connection(${connection.name}) is connected`)
+      ConnectionManager.logger.info(
+        `data-go-kr-connector connection(${connection.name}) is connected (endpoint: ${endpoint || '(default)'})`
+      )
     } catch (ex) {
       ConnectionManager.logger.error(`data-go-kr-connector connection(${connection.name}) failed`, ex)
       throw ex
@@ -49,12 +52,6 @@ export class DataGoKrConnector implements Connector {
         name: 'serviceKey',
         label: 'label.service-key',
         useDomainAttribute: true
-      },
-      {
-        type: 'string',
-        name: 'origin',
-        label: 'label.api-origin',
-        placeholder: 'https://apis.data.go.kr'
       }
     ]
   }

package/server/engine/spec/{building-ledger.ts → building-ledger/hub.ts}

@@ -1,7 +1,7 @@
-import { OperationParamSpec, ServiceSpec } from './types'
+import { OperationParamSpec, ServiceSpec } from '../types'
 
 /**
- * PNU 5요소 파라미터 스펙 — BldRgstServiceV2 의 모든 오퍼레이션이 공유.
+ * PNU 5요소 파라미터 스펙 — BldRgstHubService 의 모든 오퍼레이션이 공유.
  * 별도 배열 분리로 작성해두면 타 서비스(예: 건축물대장 허브) 도 재사용 가능.
  */
 const pnuParams: OperationParamSpec[] = [
@@ -53,18 +53,21 @@ const pnuParams: OperationParamSpec[] = [
 ]
 
 /**
- * 국토교통부_건축물대장정보 서비스 v2 (data.go.kr 데이터셋 15044713).
+ * 국토교통부_건축물대장 허브 서비스 (data.go.kr 데이터셋 15134735).
  *
- * 세움터(EAIS) DB 를 원천으로 하는 공공 건축물대장 Open API.
+ * 세움터(EAIS) DB 를 원천으로 하는 공공 건축물대장 통합 Hub Open API.
  * 모든 오퍼레이션은 동일한 PNU(필지고유번호) 구성요소로 조회한다:
  *  - sigunguCd (5) + bjdongCd (5) + platGbCd (1) + bun (4) + ji (4)
+ *
+ * 구버전 `BldRgstService_v2` (`1613000/BldRgstService_v2/`) 는 본 허브 서비스로
+ * 사실상 통합·승격되었다. 신규 사용자는 허브 서비스 활용신청을 권장.
  */
-export const BldRgstServiceV2: ServiceSpec = {
-  serviceId: '1613000/BldRgstService_v2',
-  label: '국토교통부_건축물대장정보 서비스 v2',
+export const BldRgstHubService: ServiceSpec = {
+  serviceId: '1613000/BldRgstHubService',
+  label: '국토교통부_건축물대장 허브 서비스',
   description:
     '세움터(EAIS) 원천의 건축물대장 정보를 조회한다. 표제부·총괄표제부·층별개요·부속지번·전유공용면적·주택가격·소유자현황·기본개요 등 8개 오퍼레이션 제공.',
-  homepage: 'https://www.data.go.kr/data/15044713/openapi.do',
+  homepage: 'https://www.data.go.kr/data/15134735/openapi.do',
   operations: {
     getBrTitleInfo: {
       operationId: 'getBrTitleInfo',
@@ -74,7 +77,7 @@ export const BldRgstServiceV2: ServiceSpec = {
       params: [...pnuParams],
       responseNotes:
         '응답 `response.body.items.item` 이 배열 또는 단일 객체로 올 수 있음. 모든 숫자 필드가 문자열(`"114000.00"`)로 내려옴. 집합건축물은 `regstrKindCd=3`, 일반건축물은 `regstrKindCd=2`.',
-      externalDocsUrl: 'https://www.data.go.kr/data/15044713/openapi.do',
+      externalDocsUrl: 'https://www.data.go.kr/data/15134735/openapi.do',
       examples: [
         {
           label: '서울 강남구 역삼동 823',

package/server/engine/spec/building-ledger/index.ts

@@ -0,0 +1,7 @@
+/**
+ * 건축물대장 도메인 서비스 스펙 묶음.
+ *
+ * 새 변종(예: BldRgstService_v2 호환 유지, 멸실대장 서비스 등) 추가 시
+ * 이 폴더 안에 새 파일을 만들고 본 index 에 export + 아래로 SpecRegistry 에 등록.
+ */
+export { BldRgstHubService } from './hub'

package/server/engine/spec/index.ts

@@ -1,8 +1,12 @@
 import { OperationSpec, ServiceSpec, parseOperationRef } from './types'
-import { BldRgstServiceV2 } from './building-ledger'
 
-export { BldRgstServiceV2 } from './building-ledger'
+/* 도메인별 서비스 스펙 — 새 도메인 추가 시 폴더 추가 + 본 import 한 줄 */
+import * as buildingLedger from './building-ledger'
+import * as weather from './weather'
+
 export * from './types'
+export * from './building-ledger'
+export * from './weather'
 
 const services = new Map<string, ServiceSpec>()
 
@@ -10,7 +14,24 @@ function registerService(spec: ServiceSpec) {
   services.set(spec.serviceId, spec)
 }
 
-registerService(BldRgstServiceV2)
+/* 도메인 모듈에서 export 된 모든 ServiceSpec 인스턴스를 자동 등록.
+   추가 도메인 import 만 늘리면 이하 코드는 그대로. */
+function registerDomain(domain: Record<string, unknown>) {
+  for (const value of Object.values(domain)) {
+    if (isServiceSpec(value)) registerService(value)
+  }
+}
+function isServiceSpec(value: unknown): value is ServiceSpec {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as any).serviceId === 'string' &&
+    typeof (value as any).operations === 'object'
+  )
+}
+
+registerDomain(buildingLedger)
+registerDomain(weather)
 
 export const SpecRegistry = {
   /** 등록된 모든 서비스 스펙을 반환. */

package/server/engine/spec/types.ts

@@ -56,9 +56,9 @@ export interface OperationSpec {
 
 /** 서비스 스펙 (오퍼레이션 묶음). */
 export interface ServiceSpec {
-  /** 서비스 경로 (예: `1613000/BldRgstService_v2`). */
+  /** 서비스 경로 (예: `1613000/BldRgstHubService`). */
   serviceId: string
-  /** 화면 라벨 (예: '국토교통부_건축물대장정보 서비스 v2'). */
+  /** 화면 라벨 (예: '국토교통부_건축물대장 허브 서비스'). */
   label: string
   /** 사람이 읽는 설명. */
   description: string
@@ -72,7 +72,7 @@ export interface ServiceSpec {
  * 오퍼레이션 참조 문자열 파서.
  *
  * 레지스트리 조회 키: `"<serviceId>.<operationId>"` — 점으로 구분.
- * 예: `"1613000/BldRgstService_v2.getBrTitleInfo"`
+ * 예: `"1613000/BldRgstHubService.getBrTitleInfo"`
  */
 export function parseOperationRef(ref: string): { serviceId: string; operationId: string } | null {
   const idx = ref.lastIndexOf('.')

package/server/engine/spec/weather/asos.ts

@@ -0,0 +1,32 @@
+import { OperationParamSpec, ServiceSpec } from '../types'
+
+/**
+ * 기상청_종관기상관측 시간자료 (ASOS) (data.go.kr 데이터셋 15057210).
+ *
+ * 지상 종관기상관측 (Automated Surface Observing System) 의 시간단위 관측 자료.
+ * 전국 약 100개 지점에서 표준화된 정밀 관측. 기온·강수량·풍향풍속·습도·기압 등.
+ */
+const params: OperationParamSpec[] = [
+  { name: 'dataCd', required: true, description: "자료 코드. 'ASOS' 고정.", example: 'ASOS' },
+  { name: 'dateCd', required: true, description: "자료 단위. 시간자료='HR'.", example: 'HR' },
+  { name: 'startDt', required: true, length: 8, description: '검색 시작일 YYYYMMDD', example: '20260420' },
+  { name: 'startHh', required: true, length: 2, description: '검색 시작시 HH', example: '00' },
+  { name: 'endDt', required: true, length: 8, description: '검색 종료일 YYYYMMDD', example: '20260425' },
+  { name: 'endHh', required: true, length: 2, description: '검색 종료시 HH', example: '23' },
+  { name: 'stnIds', required: true, description: 'KMA ASOS 지점 코드. 서울=108, 부산=159 등.', example: '108' }
+]
+
+export const KmaAsosHourlyService: ServiceSpec = {
+  serviceId: '1360000/AsosHourlyInfoService',
+  label: '기상청_종관기상관측 시간자료 (ASOS)',
+  description: '지상 종관기상관측(ASOS) 의 시간단위 관측 자료.',
+  homepage: 'https://www.data.go.kr/data/15057210/openapi.do',
+  operations: {
+    getWthrDataList: {
+      operationId: 'getWthrDataList',
+      label: '시간자료 조회',
+      description: '특정 지점·기간의 시간단위 관측 데이터.',
+      params
+    }
+  }
+}

package/server/engine/spec/weather/aws.ts

@@ -0,0 +1,27 @@
+import { OperationParamSpec, ServiceSpec } from '../types'
+
+/**
+ * 기상청_방재기상관측 시간자료 (AWS) (data.go.kr 데이터셋 15059093).
+ *
+ * 자동기상관측장비(AWS) 의 시간단위 관측 자료. ASOS 보다 조밀한 격자 (전국 500+ 지점).
+ * 강수·기온·풍향풍속·습도 등을 시간 단위로 제공.
+ */
+const params: OperationParamSpec[] = [
+  { name: 'tm', required: true, length: 12, description: '관측 시각 YYYYMMDDHHMM', example: '202604251200' },
+  { name: 'stn', description: '지점 번호 (생략 시 전국).', example: '108' }
+]
+
+export const KmaAwsHourlyService: ServiceSpec = {
+  serviceId: '1360000/AwsHrInfoService',
+  label: '기상청_방재기상관측 시간자료 (AWS)',
+  description: '자동기상관측장비(AWS) 의 시간단위 관측 자료. ASOS 대비 조밀한 격자.',
+  homepage: 'https://www.data.go.kr/data/15059093/openapi.do',
+  operations: {
+    getAwsRltmList: {
+      operationId: 'getAwsRltmList',
+      label: 'AWS 시간자료 조회',
+      description: 'AWS 지점의 시간단위 관측 자료. 강수·기온·풍향풍속·습도 등.',
+      params
+    }
+  }
+}

package/server/engine/spec/weather/index.ts

@@ -0,0 +1,14 @@
+/**
+ * 기상청(KMA) 도메인 서비스 스펙 묶음.
+ *
+ * 새 KMA 서비스(예: 황사·자외선·미세먼지·해양 등) 추가 시:
+ *  1. 본 폴더에 `<service-slug>.ts` 파일을 만들어 ServiceSpec export
+ *  2. 본 index 의 export 와 (필요 시) 외부 SpecRegistry 등록만 추가
+ *
+ * 한 파일에 여러 서비스를 합치지 말 것 — 확장성 보호.
+ */
+export { KmaShortTermForecastService } from './short-term-forecast'
+export { KmaMidTermForecastService } from './mid-term-forecast'
+export { KmaWeatherWarningService } from './warning'
+export { KmaAsosHourlyService } from './asos'
+export { KmaAwsHourlyService } from './aws'