@things-factory/integration-data-go-kr 10.0.0-beta.108

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

@@ -0,0 +1,38 @@
+# data.go.kr Connector
+
+대한민국 공공데이터포털 **[data.go.kr](https://www.data.go.kr)** 의 모든 Open API 에 대한 공용 커넥터.
+
+- **원천**: 각 부처·공공기관 DB (세움터·대법원·통계청·국세청·교통·에너지 등)
+- **공용 URL 체계**: `https://apis.data.go.kr/<기관코드>/<서비스명>/<오퍼레이션>`
+- **인증**: 발급받은 `ServiceKey` 를 쿼리 파라미터로 전달 (Encoding/Decoding 두 형태 모두 수용)
+- **비용**: 무료 (서비스별 활용신청 후 승인)
+
+하나의 ServiceKey 로 등록 앱의 **구독 중인 모든 서비스** 를 호출할 수 있으므로, Connection 은 보통 앱·법인당 1개만 생성한다.
+
+## Connection 필드
+
+| 필드 | 필수 | 설명 |
+| --- | --- | --- |
+| `name` | O | Connection 이름 (자유) |
+| `endpoint` | △ | API 오리진. 비워두면 기본값 `https://apis.data.go.kr`. 모의 서버/사설 프록시로 라우팅하려면 해당 오리진 입력 (예: `http://localhost:8080`) |
+| `serviceKey` (params) | O | data.go.kr 일반 인증키 (Decoding/Encoding 모두 허용). `useDomainAttribute=true` 로 도메인 시크릿 저장 권장 |
+
+## 관련 태스크
+
+- [`data-go-kr-call`](../task/data-go-kr-call.md) — 범용 오퍼레이션 호출 태스크
+- [`data-go-kr-building-ledger`](../task/building-ledger.md) — 건축물대장 표제부 조회
+
+## ServiceKey 발급 (요약)
+
+1. [https://www.data.go.kr](https://www.data.go.kr) 가입
+2. 사용하려는 **서비스 상세 페이지** → 활용신청 (1~3영업일 자동 승인)
+3. 마이페이지 → 개발계정 → **일반 인증키 (Decoding)** 복사 → Connection 의 `serviceKey`
+4. 개발계정 일 한도(기본 10,000건) 초과 시 운영계정 신청
+
+## 서비스 카탈로그
+
+등록된 서비스 스펙은 코드상 `SpecRegistry.listServices()` 로 확인 가능. 현재 등록된 서비스:
+
+- [`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

@@ -0,0 +1,110 @@
+# 건축물대장 허브 서비스 (`1613000/BldRgstHubService`)
+
+> 세움터(EAIS) 원천의 건축물대장 통합 Open API. 표제부·총괄표제부·층별개요·부속지번·전유공용면적·주택가격·소유자현황·기본개요 등 **8개 오퍼레이션** 제공.
+
+- **data.go.kr 페이지**: https://www.data.go.kr/data/15134735/openapi.do
+- 구버전 `1613000/BldRgstService_v2` (ID 15044713) 는 본 허브 서비스로 통합·승격됨. 신규 사용자는 본 허브 서비스로 활용신청.
+- **원천**: 국토교통부 세움터 DB
+- **비용**: 무료 (활용신청 후 개발 1만건/일)
+
+## 공통 파라미터 — PNU 5요소
+
+모든 오퍼레이션이 동일한 PNU 구성요소로 조회한다:
+
+| 파라미터 | 설명 | 예시 |
+| --- | --- | --- |
+| `sigunguCd` | 시군구코드 5자리 (법정동코드 앞 5자리) | `11680` |
+| `bjdongCd` | 법정동코드 5자리 (법정동코드 뒤 5자리) | `10300` |
+| `platGbCd` | 대지구분 (`0` 대지 / `1` 산 / `2` 블록, 기본 `0`) | `0` |
+| `bun` | 본번 (4자리 zero-pad) | `0223` |
+| `ji` | 부번 (4자리 zero-pad, 없으면 `0000`) | `0000` |
+
+PNU 조회 방법:
+- [행정표준코드관리시스템 (code.go.kr)](https://www.code.go.kr) — 법정동코드
+- [V-World 공간정보 오픈플랫폼](https://www.vworld.kr) — 주소→PNU 변환 API
+- 건축물대장 원본 상단의 "고유번호" 19자리 = `[법정동코드 10][platGbCd 1][bun 4][ji 4]`
+
+## 오퍼레이션 카탈로그
+
+### `getBrTitleInfo` — 표제부 조회
+
+건축물대장 표제부(건물 본문) 조회. 연면적·용적률·지상층수·지하층수·주구조·주용도 등 **건물 개요**. 한 필지에 동이 여러 개이면 복수 레코드.
+
+**응답 주요 필드**: `totArea`, `vlRat`, `grndFlrCnt`, `ugrndFlrCnt`, `strctCdNm`, `mainPurpsCdNm`, `useAprDay`, `bldNm`, `dongNm`
+
+**주의**: 응답의 `items.item` 이 배열 또는 단일 객체로 올 수 있음. 숫자 필드는 문자열(`"114000.00"`)로 내려옴. 집합건축물은 `regstrKindCd=3`, 일반은 `2`.
+
+**예시**
+```
+operationRef: 1613000/BldRgstHubService.getBrTitleInfo
+params: { sigunguCd: "11680", bjdongCd: "10300", bun: "823" }
+```
+
+→ PNU 5요소 파라미터 폼이 필요하면 [`data-go-kr-building-ledger`](../task/building-ledger.md) 전용 태스크를 이용.
+
+---
+
+### `getBrRecapTitleInfo` — 총괄표제부 조회
+
+집합건축물(아파트 단지 등) 의 총괄표제부. 단지 전체 연면적·대지면적·동 수·세대수 등.
+
+**주의**: 일반건축물대장(단동) 에는 레코드 없음. 집합건축물일 때만 유효.
+
+---
+
+### `getBrFlrOulnInfo` — 층별개요 조회
+
+층별로 주용도·구조·면적. 지하 N층부터 지상 M층까지 각 층의 상세 구성.
+
+**주의**: 한 필지에 동이 여러 개이면 각 동의 각 층이 모두 나옴 → 건수 多.
+
+---
+
+### `getBrExposPubuseAreaInfo` — 전유공용면적 조회
+
+집합건축물의 호(세대) 별 전유면적·공용면적. 아파트 세대별 실제 면적 산출.
+
+**주의**: 집합건축물일 때만 레코드 존재.
+
+---
+
+### `getBrAtchJibunInfo` — 부속지번 조회
+
+대장에 연결된 부속지번(인접 필지 등) 목록.
+
+---
+
+### `getBrHsprcInfo` — 주택가격 조회
+
+공동주택/단독주택 공시가격 이력. 연도별 개별주택가격·공동주택가격.
+
+---
+
+### `getBrBasisOulnInfo` — 기본개요 조회
+
+대장의 기본개요(대장 구분, 대장 종류, 변동일, 변동원인). 변동 이력 추적.
+
+---
+
+### `getBrExposInfo` — 전유부 조회
+
+집합건축물의 호(세대) 목록과 호별 개요. 전유공용면적보다 상위 요약 수준.
+
+---
+
+## 호출 방법
+
+모두 범용 태스크 [`data-go-kr-call`](../task/data-go-kr-call.md) 에 `operationRef` 로 지정해서 호출:
+
+```json
+{
+  "task": "data-go-kr-call",
+  "connection": "data-go-kr",
+  "params": {
+    "operationRef": "1613000/BldRgstHubService.getBrTitleInfo",
+    "params": { "sigunguCd": "...", "bjdongCd": "...", "bun": "..." }
+  }
+}
+```
+
+표제부를 자주 호출한다면 PNU 5요소 폼이 명시된 전용 태스크 `data-go-kr-building-ledger` 사용.

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

@@ -0,0 +1,135 @@
+# data-go-kr-building-ledger
+
+국토교통부 건축물대장 **표제부**(`getBrTitleInfo`) 를 조회하는 전용 태스크.
+
+순수 **fetch** 만 수행합니다 — 집계·변환·요약 같은 도메인 가공은 소비자 스텝에서 처리하세요.
+
+## 입력 파라미터
+
+PNU(필지고유번호) 5요소로 조회:
+
+| 이름 | 필수 | 설명 | 예시 |
+| --- | --- | --- | --- |
+| `sigunguCd` | O | 시군구코드 5자리 (법정동코드 앞 5자리) | `11680` |
+| `bjdongCd` | O | 법정동코드 5자리 (법정동코드 뒤 5자리) | `10300` |
+| `platGbCd` | △ | 대지구분 (`0` 대지 / `1` 산 / `2` 블록, 기본 `0`) | `0` |
+| `bun` | O | 본번 (자동 4자리 zero-pad) | `223` |
+| `ji` | △ | 부번 (없으면 `0`, 자동 4자리 zero-pad) | `0` |
+
+## 데이터 바인딩
+
+각 입력 필드에 **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}` |
+
+## 출력
+
+```jsonc
+{
+  "items": [
+    {
+      "mgmBldrgstPk":  "...",
+      "platPlc":       "...",
+      "bldNm":         "...",
+      "dongNm":        "",
+      "totArea":       "114000.00",  // 연면적 (문자열)
+      "vlRat":         "250",        // 용적률 (문자열)
+      "grndFlrCnt":    "25",         // 지상층수 (문자열)
+      "ugrndFlrCnt":   "3",          // 지하층수 (문자열)
+      "strctCdNm":     "철근콘크리트구조",
+      "mainPurpsCdNm": "공동주택",
+      "useAprDay":     "20230801"
+      // ... 기타 20+ 필드
+    }
+    /* 다동 필지이면 여러 레코드 */
+  ]
+}
+```
+
+### 중요 — 모든 숫자는 문자열
+
+data.go.kr 공통 특성입니다. 숫자로 쓰려면 **후속 스텝** 에서 변환하세요.
+
+### 단동 vs 다동
+
+- **단동 필지**: `items.length === 1`. `items[0]` 이 대표값.
+- **다동 필지**: `items` 에 각 동이 한 레코드씩. `dongNm` 으로 식별.
+
+## 후속 스텝 예시 — 집계는 여기서
+
+### 단건 필드 바인딩 (data-mapper)
+
+```json
+{
+  "task": "data-mapper",
+  "params": {
+    "mapping": {
+      "totalFloorArea":    "items[0].totArea",
+      "floorAreaRatio":    "items[0].vlRat",
+      "aboveGroundFloors": "items[0].grndFlrCnt",
+      "belowGroundFloors": "items[0].ugrndFlrCnt"
+    }
+  }
+}
+```
+
+### 다동 필지 집계 (jsonata)
+
+```json
+{
+  "task": "jsonata",
+  "params": {
+    "expression": "{ 'totalFloorArea': $sum(items.totArea.$number()), 'aboveGroundFloors': $max(items.grndFlrCnt.$number()), 'belowGroundFloors': $max(items.ugrndFlrCnt.$number()), 'floorAreaRatio': items[0].vlRat.$number() }"
+  }
+}
+```
+
+### 도메인 전용 태스크
+
+소비자 도메인에서 반복 사용된다면 전용 태스크로 감싸세요. 예를 들어 dkpi 라면:
+
+```
+dkpi/server/scenario-task/summarize-building-ledger.ts
+  → input: { items: BrTitleItem[] }
+  → output: { totalFloorArea, floorAreaRatio, ... }  // KPI 4속성
+```
+
+이렇게 하면 "KPI" 어휘가 소비자 측에만 머물고 통합 모듈은 순수한 데이터 조회 레이어로 유지됩니다.
+
+## 트러블슈팅
+
+### "no 표제부 records" 에러
+
+- **신축 공사 중**: 사용승인 전에는 대장이 없음. 프로젝트 시작 시점 입력 후 사용승인 후 재조회.
+- **PNU 오타**: `sigunguCd`(앞 5자리) / `bjdongCd`(뒤 5자리) 가 뒤바뀌지 않았는지 확인.
+- **지번 구조**: "산 N-M" 지번이면 `platGbCd=1` 필요.
+
+### 집합건축물(아파트)
+
+`items[0].regstrKindCd === '3'` 이면 집합건축물. 더 정확한 단지 전체 연면적은 `getBrRecapTitleInfo`(총괄표제부) + `getBrExposPubuseAreaInfo`(전유공용면적) 조합이 필요합니다. 이 경우 범용 [`data-go-kr-call`](./data-go-kr-call.md) 로 호출하거나 ROADMAP Phase 4 의 집합건축물 전용 태스크를 기다리세요.
+
+## 관련
+
+- [`data-go-kr-connector`](../connector/data-go-kr-connector.md) — Connection 설정
+- [`data-go-kr-call`](./data-go-kr-call.md) — 범용 호출 (표제부 외 7개 오퍼레이션)
+- [서비스: 건축물대장 v2](../services/building-ledger.md) — 전체 오퍼레이션 카탈로그

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

@@ -0,0 +1,114 @@
+# data-go-kr-call
+
+공공데이터포털 **모든 오퍼레이션** 을 호출하는 범용 태스크. 서비스·오퍼레이션별 전용 태스크를 만들지 않아도 되도록 단일 태스크 + 스펙 레지스트리 구조로 동작.
+
+## 입력 파라미터
+
+| 이름 | 필수 | 설명 | 예시 |
+| --- | --- | --- | --- |
+| `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` 선택 시 입력 폼이 자동 생성됩니다.
+
+## 출력
+
+원 응답 봉투를 그대로 반환:
+
+```jsonc
+{
+  "response": {
+    "header": { "resultCode": "00", "resultMsg": "NORMAL SERVICE." },
+    "body": {
+      "items": { "item": [ /* ... */ ] },
+      "numOfRows": 100,
+      "pageNo": 1,
+      "totalCount": 1
+    }
+  }
+}
+```
+
+이후 스텝에서 `data.response.body.items.item` 에 접근하면 레코드. 단건/다건이 `item` 이 객체 혹은 배열로 갈리므로 후속 `data-mapper` 로 정규화 권장.
+
+## 사용 예시
+
+### 건축물대장 표제부 조회
+
+```json
+{
+  "task": "data-go-kr-call",
+  "connection": "data-go-kr",
+  "params": {
+    "operationRef": "1613000/BldRgstHubService.getBrTitleInfo",
+    "params": {
+      "sigunguCd": "11680",
+      "bjdongCd": "10300",
+      "bun": "223"
+    }
+  }
+}
+```
+
+> `platGbCd` 는 기본 `0`, `ji` 는 기본 `0000` 으로 스펙이 채워줍니다.
+
+### 새 서비스 즉시 호출 (스펙 등록 전)
+
+예를 들어 부동산실거래가 API 가 아직 스펙 등록되지 않았어도:
+
+```json
+{
+  "task": "data-go-kr-call",
+  "params": {
+    "operationRef": "1613000/RTMSOBJSvc.getRTMSDataSvcAptTrade",
+    "params": {
+      "LAWD_CD": "11680",
+      "DEAL_YMD": "202504"
+    }
+  }
+}
+```
+
+검증은 없지만 호출은 정상 동작. 정식으로 쓰려면 `server/engine/spec/rtms-trade.ts` 로 스펙을 추가해주세요.
+
+## 자주 쓰는 경우는 전용 태스크
+
+자주 쓰이는 오퍼레이션은 파라미터 폼이 명시된 전용 태스크로 감싸면 운영 UX 가 좋습니다:
+
+- [`data-go-kr-building-ledger`](./building-ledger.md) — 건축물대장 표제부 조회 (PNU 폼 제공)
+
+## 관련
+
+- [`data-go-kr-connector`](../connector/data-go-kr-connector.md) — Connection 설정
+- [서비스: 건축물대장 v2](../services/building-ledger.md) — 8개 오퍼레이션 카탈로그

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/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@things-factory/integration-data-go-kr",
+  "version": "10.0.0-beta.108",
+  "main": "dist-server/index.js",
+  "things-factory": true,
+  "author": "heartyoh <heartyoh@hatiolab.com>",
+  "description": "Korean public data portal (data.go.kr) connector for Things-Factory integration engine. Includes generic invocation task and service-specific helpers (e.g., building ledger / 건축물대장).",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "@things-factory:registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hatiolab/things-factory.git",
+    "directory": "packages/integration-data-go-kr"
+  },
+  "scripts": {
+    "build": "tsc --p tsconfig.json",
+    "build:server": "npm run clean:server && tsc",
+    "clean:server": "rm -rf dist-server",
+    "clean": "npm run clean:server"
+  },
+  "dependencies": {
+    "@things-factory/integration-base": "^10.0.0-beta.108"
+  },
+  "gitHead": "7de47925ebd3f39dc232d4dbfa43f9687f3603c4"
+}