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

package/server/engine/spec/weather/mid-term-forecast.ts

@@ -0,0 +1,56 @@
+import { OperationParamSpec, ServiceSpec } from '../types'
+
+/**
+ * 기상청_중기예보 조회서비스 (data.go.kr 데이터셋 15059468).
+ *
+ * 3~10일 전망. 광역 권역(regId) 단위로 06·18시 발표.
+ */
+const sharedParams: OperationParamSpec[] = [
+  {
+    name: 'regId',
+    required: true,
+    description:
+      '광역 권역 코드. 육상은 `11B00000`(서울/인천/경기) 등, 기온은 `11B10101`(서울) 등 더 세분화. KMA 권역 코드 표 참조.',
+    example: '11B00000'
+  },
+  {
+    name: 'tmFc',
+    required: true,
+    length: 12,
+    description: '발표시각 YYYYMMDDHHMM. 중기예보는 06·18시 발표.',
+    example: '202604250600'
+  }
+]
+
+export const KmaMidTermForecastService: ServiceSpec = {
+  serviceId: '1360000/MidFcstInfoService',
+  label: '기상청_중기예보 조회서비스',
+  description: '3~10일 중기예보. 육상·기온·해상 별 오퍼레이션.',
+  homepage: 'https://www.data.go.kr/data/15059468/openapi.do',
+  operations: {
+    getMidFcst: {
+      operationId: 'getMidFcst',
+      label: '중기예보 종합',
+      description: '중기 전망 텍스트 (해석본).',
+      params: sharedParams
+    },
+    getMidLandFcst: {
+      operationId: 'getMidLandFcst',
+      label: '육상 중기예보',
+      description: '육상 권역의 강수확률·하늘상태 (3~10일).',
+      params: sharedParams
+    },
+    getMidTa: {
+      operationId: 'getMidTa',
+      label: '중기 기온예보',
+      description: '아침 최저·낮 최고 기온 (3~10일).',
+      params: sharedParams
+    },
+    getMidSeaFcst: {
+      operationId: 'getMidSeaFcst',
+      label: '해상 중기예보',
+      description: '해상 권역의 풍향·풍속·파고.',
+      params: sharedParams
+    }
+  }
+}

package/server/engine/spec/weather/short-term-forecast.ts

@@ -0,0 +1,73 @@
+import { OperationParamSpec, ServiceSpec } from '../types'
+
+/**
+ * 기상청_단기예보 조회서비스 v2 (data.go.kr 데이터셋 15084084).
+ *
+ * 동네예보 + 초단기예보 + 초단기실황. 모두 KMA 5km 격자좌표(nx, ny) 기준.
+ */
+const sharedParams: OperationParamSpec[] = [
+  {
+    name: 'base_date',
+    label: 'label.base-date',
+    required: true,
+    length: 8,
+    description: '발표일자 YYYYMMDD',
+    example: '20260425'
+  },
+  {
+    name: 'base_time',
+    label: 'label.base-time',
+    required: true,
+    length: 4,
+    description:
+      '발표시각 HHMM. 단기예보는 0200·0500·0800·1100·1400·1700·2000·2300, 초단기 시리즈는 매시각 정시.',
+    example: '1100'
+  },
+  {
+    name: 'nx',
+    label: 'label.nx',
+    required: true,
+    description: 'KMA 5km 격자 X좌표 (위경도 → 격자 변환은 task/weather/grid-converter 헬퍼).',
+    example: '60'
+  },
+  {
+    name: 'ny',
+    label: 'label.ny',
+    required: true,
+    description: 'KMA 5km 격자 Y좌표.',
+    example: '127'
+  }
+]
+
+export const KmaShortTermForecastService: ServiceSpec = {
+  serviceId: '1360000/VilageFcstInfoService_2.0',
+  label: '기상청_단기예보 조회서비스',
+  description: '동네예보(3일치)·초단기예보(6시간)·초단기실황 3개 오퍼레이션. KMA 5km 격자좌표 기준.',
+  homepage: 'https://www.data.go.kr/data/15084084/openapi.do',
+  operations: {
+    getVilageFcst: {
+      operationId: 'getVilageFcst',
+      label: '단기예보 조회',
+      description:
+        '동네예보. 02·05·08·11·14·17·20·23시 (각 +10분 후 제공) 발표, 3일치 3시간 간격 카테고리 (POP·PCP·SKY·REH·T1H·UUU·VVV·VEC·WSD·TMN·TMX 등).',
+      params: sharedParams,
+      responseNotes:
+        'items.item 이 (카테고리×시점) 조합으로 매우 많이 반환됨 (3일치 약 800+건). numOfRows 를 충분히 크게 (1000+) 잡거나 페이징.',
+      externalDocsUrl: 'https://www.data.go.kr/data/15084084/openapi.do'
+    },
+    getUltraSrtFcst: {
+      operationId: 'getUltraSrtFcst',
+      label: '초단기예보 조회',
+      description: '발표시각 +45분 후 제공. 매시각 발표. 향후 6시간 예보 (1시간 단위).',
+      params: sharedParams,
+      externalDocsUrl: 'https://www.data.go.kr/data/15084084/openapi.do'
+    },
+    getUltraSrtNcst: {
+      operationId: 'getUltraSrtNcst',
+      label: '초단기실황 조회',
+      description: '발표시각 +10분 후 제공. 매시각 발표. 현재 관측값 (T1H·RN1·UUU·VVV·REH·PTY·VEC·WSD).',
+      params: sharedParams,
+      externalDocsUrl: 'https://www.data.go.kr/data/15084084/openapi.do'
+    }
+  }
+}

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

@@ -0,0 +1,33 @@
+import { OperationParamSpec, ServiceSpec } from '../types'
+
+/**
+ * 기상청_기상특보 조회서비스 (data.go.kr 데이터셋 15059092).
+ *
+ * 호우·태풍·강풍·풍랑·대설 등 특보의 발효 현황 및 상세 내용.
+ */
+const sharedParams: OperationParamSpec[] = [
+  { name: 'stnId', required: true, description: '발표 관할 지점 ID. 전국=108. KMA 지점 코드 표 참조.', example: '108' },
+  { name: 'fromTmFc', required: true, length: 8, description: '검색시작일 YYYYMMDD', example: '20260425' },
+  { name: 'toTmFc', required: true, length: 8, description: '검색종료일 YYYYMMDD', example: '20260425' }
+]
+
+export const KmaWeatherWarningService: ServiceSpec = {
+  serviceId: '1360000/WthrWrnInfoService',
+  label: '기상청_기상특보 조회서비스',
+  description: '기상특보(호우·태풍·강풍·풍랑·대설 등) 발효 현황 및 상세 내용 조회.',
+  homepage: 'https://www.data.go.kr/data/15059092/openapi.do',
+  operations: {
+    getWthrWrnList: {
+      operationId: 'getWthrWrnList',
+      label: '특보 목록 조회',
+      description: '발표 시각 범위 내의 특보 목록.',
+      params: sharedParams
+    },
+    getWthrWrnInfo: {
+      operationId: 'getWthrWrnInfo',
+      label: '특보 상세 조회',
+      description: '발효 중인 특정 특보의 상세 발표문.',
+      params: sharedParams
+    }
+  }
+}

package/server/engine/task/building-ledger/general.ts

@@ -1,7 +1,7 @@
 import { ConnectionManager, Context, TaskRegistry, evaluateTemplate } from '@things-factory/integration-base'
 
 import { DataGoKrConnectionInstance } from '../../connector/data-go-kr-connector'
-import { BldRgstServiceV2 } from '../../spec/building-ledger'
+import { BldRgstHubService } from '../../spec/building-ledger'
 import { BrTitleItem, BuildingLedgerResult } from '../../types'
 
 /**
@@ -48,7 +48,7 @@ async function BuildingLedgerTask(step, context: Context): Promise<{ data: Build
   if (!bjdongCd) throw new Error('data-go-kr-building-ledger: bjdongCd is required')
   if (!bun) throw new Error('data-go-kr-building-ledger: bun is required')
 
-  const servicePath = `${BldRgstServiceV2.serviceId}/getBrTitleInfo`
+  const servicePath = `${BldRgstHubService.serviceId}/getBrTitleInfo`
 
   const normalizedParams = {
     sigunguCd,

package/server/engine/task/call.ts

@@ -11,7 +11,7 @@ import { OperationSpec, SpecRegistry } from '../spec'
  * 수백 개 태스크로 폭발하는 것을 방지하는 핵심 설계.
  *
  * 입력:
- *  - `operationRef` : `"<serviceId>.<operationId>"` 형식 (예: `"1613000/BldRgstService_v2.getBrTitleInfo"`)
+ *  - `operationRef` : `"<serviceId>.<operationId>"` 형식 (예: `"1613000/BldRgstHubService.getBrTitleInfo"`)
  *  - `params`       : 오퍼레이션 파라미터 객체. 스펙 등록된 오퍼레이션이면 자동 검증·기본값·zero-pad 적용
  *
  * 레지스트리에 없는 오퍼레이션도 호출 가능 (스펙 없음 → 검증 스킵). 새 data.go.kr 서비스가
@@ -136,17 +136,37 @@ function normalizeAndValidateParams(operation: OperationSpec, input: Record<stri
   return output
 }
 
+/**
+ * SpecRegistry 에 등록된 모든 오퍼레이션을 (operationRef → display) 옵션으로 펼친다.
+ * 모듈 로딩 시 한 번 평가되며, 이후 register() 로 추가된 spec 은 반영되지 않음
+ * (드문 케이스라 수용 — 향후 동적 parameterSpec 도입 시 해결).
+ */
+function buildOperationRefOptions(): Array<{ value: string; display: string }> {
+  return SpecRegistry.listServices()
+    .flatMap(svc =>
+      Object.values(svc.operations).map(op => ({
+        value: `${svc.serviceId}.${op.operationId}`,
+        display: `[${svc.label}] ${op.label}`
+      }))
+    )
+    .sort((a, b) => a.display.localeCompare(b.display, 'ko'))
+}
+
 DataGoKrCall.parameterSpec = [
   {
-    type: 'string',
+    type: 'select',
     name: 'operationRef',
     label: 'label.operation-ref',
-    placeholder: '<serviceId>.<operationId> (예: 1613000/BldRgstService_v2.getBrTitleInfo)'
+    property: {
+      options: buildOperationRefOptions()
+    }
   },
   {
     type: 'scenario-step-input',
     name: 'params',
-    label: 'label.operation-params'
+    label: 'label.operation-params',
+    placeholder:
+      '오퍼레이션 파라미터를 JSON 객체로. 예) 건축물대장: {"sigunguCd":"11680","bjdongCd":"10300","bun":"223"} · 단기예보: {"base_date":"20260425","base_time":"1100","nx":"60","ny":"127"}. 정확한 키는 helps/integration/services/<domain>.md 참고.'
   }
 ]
 

package/server/engine/task/index.ts

@@ -17,3 +17,4 @@
  */
 import './call'
 import './building-ledger'
+import './weather'

package/server/engine/task/weather/grid-converter.ts

@@ -0,0 +1,79 @@
+/**
+ * KMA(기상청) 5km 격자좌표 ↔ 위경도 변환.
+ *
+ * 동네예보·초단기 시리즈는 위경도가 아닌 KMA 자체 격자(nx, ny) 로 호출하므로,
+ * 일반적으로 알고 있는 위경도 좌표를 격자로 바꿔주는 헬퍼가 필요하다.
+ *
+ * 변환식 출처: 기상청 공식 동네예보 격자 변환 문서 (Lambert Conformal Conic).
+ */
+
+const RE = 6371.00877 /* 지구 반경 (km) */
+const GRID = 5.0 /* 격자 간격 (km) */
+const SLAT1 = 30.0 /* 표준 위도 1 (degree) */
+const SLAT2 = 60.0 /* 표준 위도 2 (degree) */
+const OLON = 126.0 /* 기준점 경도 (degree) */
+const OLAT = 38.0 /* 기준점 위도 (degree) */
+const XO = 43 /* 기준점 X좌표 (격자 단위) */
+const YO = 136 /* 기준점 Y좌표 (격자 단위) */
+
+const DEGRAD = Math.PI / 180.0
+const RADDEG = 180.0 / Math.PI
+
+const re = RE / GRID
+const slat1 = SLAT1 * DEGRAD
+const slat2 = SLAT2 * DEGRAD
+const olon = OLON * DEGRAD
+const olat = OLAT * DEGRAD
+
+const sn =
+  Math.log(Math.cos(slat1) / Math.cos(slat2)) /
+  Math.log(Math.tan(Math.PI * 0.25 + slat2 * 0.5) / Math.tan(Math.PI * 0.25 + slat1 * 0.5))
+const sf = (Math.pow(Math.tan(Math.PI * 0.25 + slat1 * 0.5), sn) * Math.cos(slat1)) / sn
+const ro = (re * sf) / Math.pow(Math.tan(Math.PI * 0.25 + olat * 0.5), sn)
+
+export interface LatLon {
+  /** 위도 (degree). */
+  latitude: number
+  /** 경도 (degree). */
+  longitude: number
+}
+
+export interface KmaGrid {
+  /** 격자 X. */
+  nx: number
+  /** 격자 Y. */
+  ny: number
+}
+
+/** 위경도 → KMA 5km 격자좌표 (nx, ny). */
+export function latLonToGrid(input: LatLon): KmaGrid {
+  const ra = (re * sf) / Math.pow(Math.tan(Math.PI * 0.25 + input.latitude * DEGRAD * 0.5), sn)
+  let theta = input.longitude * DEGRAD - olon
+  if (theta > Math.PI) theta -= 2.0 * Math.PI
+  if (theta < -Math.PI) theta += 2.0 * Math.PI
+  theta *= sn
+  const x = ra * Math.sin(theta) + XO
+  const y = ro - ra * Math.cos(theta) + YO
+  return { nx: Math.floor(x + 1.5), ny: Math.floor(y + 1.5) }
+}
+
+/** KMA 5km 격자좌표 → 위경도 (격자 중심점). */
+export function gridToLatLon(input: KmaGrid): LatLon {
+  const xn = input.nx - XO
+  const yn = ro - (input.ny - YO)
+  let ra = Math.sqrt(xn * xn + yn * yn)
+  if (sn < 0.0) ra = -ra
+  let alat = Math.pow((re * sf) / ra, 1.0 / sn)
+  alat = 2.0 * Math.atan(alat) - Math.PI * 0.5
+  let theta: number
+  if (Math.abs(xn) <= 0.0) {
+    theta = 0.0
+  } else if (Math.abs(yn) <= 0.0) {
+    theta = Math.PI * 0.5
+    if (xn < 0.0) theta = -theta
+  } else {
+    theta = Math.atan2(xn, yn)
+  }
+  const alon = theta / sn + olon
+  return { latitude: alat * RADDEG, longitude: alon * RADDEG }
+}

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

@@ -0,0 +1,14 @@
+/**
+ * 기상청(KMA) 도메인 전용 태스크 그룹.
+ *
+ * 새 KMA 전용 태스크(예: AWS 자동수집, 특보 알림 등) 추가 시:
+ *  - 본 폴더에 `<variant>.ts` 파일 추가 → TaskRegistry 등록
+ *  - 본 index 에 `import './<variant>'` 한 줄 추가
+ *
+ * 단순 조회는 범용 `data-go-kr-call` + 스펙 레지스트리로 충분하므로,
+ * 이 폴더에는 입력 폼·헬퍼·도메인 가공이 가치 있는 태스크만 배치.
+ */
+import './short-term-forecast'
+
+export { latLonToGrid, gridToLatLon } from './grid-converter'
+export type { LatLon, KmaGrid } from './grid-converter'

package/server/engine/task/weather/short-term-forecast.ts

@@ -0,0 +1,110 @@
+import { ConnectionManager, Context, TaskRegistry, evaluateTemplate } from '@things-factory/integration-base'
+
+import { DataGoKrConnectionInstance } from '../../connector/data-go-kr-connector'
+import { KmaShortTermForecastService } from '../../spec/weather/short-term-forecast'
+import { latLonToGrid } from './grid-converter'
+
+/**
+ * 기상청 단기예보 (`getVilageFcst`) 조회 태스크.
+ *
+ * 입력 폼이 명시된 전용 태스크. 위경도 입력 시 KMA 격자로 자동 변환.
+ *
+ * 입력 (둘 중 하나):
+ *  - `nx`, `ny`             : KMA 5km 격자좌표
+ *  - `latitude`, `longitude`: 위경도 (자동으로 nx/ny 로 변환)
+ *
+ * 추가:
+ *  - `baseDate`  : 발표일자 YYYYMMDD (필수)
+ *  - `baseTime`  : 발표시각 HHMM (필수, 0200/0500/0800/1100/1400/1700/2000/2300)
+ *  - `numOfRows` : 페이지당 결과수 (기본 1000 — 3일치 카테고리×시점 합계 약 800+)
+ *
+ * 다른 단기예보 오퍼레이션(getUltraSrtFcst, getUltraSrtNcst) 은 동일 서비스 안에 있으므로
+ * 범용 `data-go-kr-call` 로 호출 권장.
+ */
+async function ShortTermForecastTask(step, context: Context): Promise<{ data: { items: any[] } }> {
+  const { connection: connectionName, params } = step
+  const { domain, user, data, variables, lng, logger } = context
+
+  const instance: DataGoKrConnectionInstance = await ConnectionManager.getConnectionInstanceByName(
+    domain,
+    connectionName
+  )
+  if (!instance?.client) {
+    throw new Error(`data-go-kr connection '${connectionName}' is not established.`)
+  }
+
+  const scope = { domain, user, lng, data, variables, console }
+  const evalString = (value: string | undefined) => {
+    if (value === undefined || value === null || value === '') return undefined
+    try {
+      return evaluateTemplate(String(value), scope)
+    } catch (err) {
+      throw new Error(`weather-short-term-forecast: failed to evaluate parameter: ${(err as Error).message}`)
+    }
+  }
+  const evalNumber = (value: any): number | undefined => {
+    const s = evalString(value as string | undefined)
+    if (s === undefined) return undefined
+    const n = Number(s)
+    return Number.isFinite(n) ? n : undefined
+  }
+
+  const baseDate = evalString(params.baseDate)
+  const baseTime = evalString(params.baseTime)
+  if (!baseDate) throw new Error('weather-short-term-forecast: baseDate is required')
+  if (!baseTime) throw new Error('weather-short-term-forecast: baseTime is required')
+
+  const explicitNx = evalNumber(params.nx)
+  const explicitNy = evalNumber(params.ny)
+  const lat = evalNumber(params.latitude)
+  const lon = evalNumber(params.longitude)
+
+  let nx: number
+  let ny: number
+  if (explicitNx !== undefined && explicitNy !== undefined) {
+    nx = explicitNx
+    ny = explicitNy
+  } else if (lat !== undefined && lon !== undefined) {
+    const grid = latLonToGrid({ latitude: lat, longitude: lon })
+    nx = grid.nx
+    ny = grid.ny
+    logger?.info?.(`[data-go-kr] latLonToGrid lat=${lat} lon=${lon} → nx=${nx} ny=${ny}`)
+  } else {
+    throw new Error(
+      'weather-short-term-forecast: provide either (nx, ny) or (latitude, longitude). 둘 다 비어있음.'
+    )
+  }
+
+  const servicePath = `${KmaShortTermForecastService.serviceId}/getVilageFcst`
+  const queryParams = {
+    base_date: baseDate,
+    base_time: baseTime,
+    nx,
+    ny,
+    numOfRows: evalNumber(params.numOfRows) ?? 1000,
+    pageNo: evalNumber(params.pageNo) ?? 1
+  }
+
+  logger?.info?.(`[data-go-kr] ${servicePath} params=${JSON.stringify(queryParams)}`)
+
+  const items = await instance.client.getItems<any>(servicePath, queryParams)
+
+  return { data: { items } }
+}
+
+ShortTermForecastTask.parameterSpec = [
+  { type: 'string', name: 'baseDate', label: 'label.base-date', placeholder: '예) 20260425' },
+  { type: 'string', name: 'baseTime', label: 'label.base-time', placeholder: '예) 1100' },
+  { type: 'string', name: 'nx', label: 'label.nx', placeholder: '예) 60' },
+  { type: 'string', name: 'ny', label: 'label.ny', placeholder: '예) 127' },
+  { type: 'string', name: 'latitude', label: 'label.latitude', placeholder: '위경도 입력 시 nx/ny 자동 계산' },
+  { type: 'string', name: 'longitude', label: 'label.longitude' },
+  { type: 'string', name: 'numOfRows', label: 'label.num-of-rows', placeholder: '기본 1000' },
+  { type: 'string', name: 'pageNo', label: 'label.page-no', placeholder: '기본 1' }
+]
+
+ShortTermForecastTask.help = 'integration/task/weather-short-term-forecast'
+
+TaskRegistry.registerTaskHandler('data-go-kr-weather-short-term-forecast', ShortTermForecastTask)
+
+export default ShortTermForecastTask

package/server/index.ts

@@ -3,3 +3,5 @@ import './engine'
 export * from './engine/types'
 export * from './engine/spec'
 export { DataGoKrClient } from './engine/connector/data-go-kr-client'
+export { latLonToGrid, gridToLatLon } from './engine/task/weather'
+export type { LatLon, KmaGrid } from './engine/task/weather'

package/translations/en.json

@@ -1,11 +1,18 @@
 {
   "label.service-key": "Service Key (data.go.kr)",
-  "label.api-origin": "API Origin (optional)",
   "label.operation-ref": "Operation Reference",
   "label.operation-params": "Operation Parameters",
   "label.sigungu-cd": "Sigungu Code",
   "label.bjdong-cd": "Beopjeongdong Code",
   "label.plat-gb-cd": "Plot Type",
   "label.bun": "Parcel Bun (main)",
-  "label.ji": "Parcel Ji (sub)"
+  "label.ji": "Parcel Ji (sub)",
+  "label.base-date": "Base Date (YYYYMMDD)",
+  "label.base-time": "Base Time (HHMM)",
+  "label.nx": "Grid X (KMA 5km)",
+  "label.ny": "Grid Y (KMA 5km)",
+  "label.latitude": "Latitude (auto-converts to grid if filled)",
+  "label.longitude": "Longitude",
+  "label.num-of-rows": "Results per page",
+  "label.page-no": "Page number"
 }

package/translations/ja.json

@@ -1,11 +1,18 @@
 {
   "label.service-key": "サービスキー (data.go.kr)",
-  "label.api-origin": "APIオリジン（任意）",
   "label.operation-ref": "オペレーション参照",
   "label.operation-params": "オペレーションパラメータ",
   "label.sigungu-cd": "市郡区コード",
   "label.bjdong-cd": "法定洞コード",
   "label.plat-gb-cd": "土地区分",
   "label.bun": "本番",
-  "label.ji": "副番"
+  "label.ji": "副番",
+  "label.base-date": "発表日付 (YYYYMMDD)",
+  "label.base-time": "発表時刻 (HHMM)",
+  "label.nx": "格子 X (KMA 5km)",
+  "label.ny": "格子 Y (KMA 5km)",
+  "label.latitude": "緯度 (緯経度入力時は自動格子変換)",
+  "label.longitude": "経度",
+  "label.num-of-rows": "ページあたり件数",
+  "label.page-no": "ページ番号"
 }

package/translations/ko.json

@@ -1,11 +1,18 @@
 {
   "label.service-key": "서비스키 (data.go.kr)",
-  "label.api-origin": "API 오리진 (선택)",
   "label.operation-ref": "오퍼레이션 참조",
   "label.operation-params": "오퍼레이션 파라미터",
   "label.sigungu-cd": "시군구코드",
   "label.bjdong-cd": "법정동코드",
   "label.plat-gb-cd": "대지 구분",
   "label.bun": "본번",
-  "label.ji": "부번"
+  "label.ji": "부번",
+  "label.base-date": "발표일자 (YYYYMMDD)",
+  "label.base-time": "발표시각 (HHMM)",
+  "label.nx": "격자 X (KMA 5km)",
+  "label.ny": "격자 Y (KMA 5km)",
+  "label.latitude": "위도 (위경도 입력 시 자동 격자 변환)",
+  "label.longitude": "경도",
+  "label.num-of-rows": "페이지당 결과수",
+  "label.page-no": "페이지 번호"
 }

package/translations/ms.json

@@ -1,11 +1,18 @@
 {
   "label.service-key": "Service Key (data.go.kr)",
-  "label.api-origin": "Asal API (pilihan)",
   "label.operation-ref": "Rujukan Operasi",
   "label.operation-params": "Parameter Operasi",
   "label.sigungu-cd": "Kod Sigungu",
   "label.bjdong-cd": "Kod Beopjeongdong",
   "label.plat-gb-cd": "Jenis Lot",
   "label.bun": "No. Bun",
-  "label.ji": "No. Ji"
+  "label.ji": "No. Ji",
+  "label.base-date": "Tarikh Asas (YYYYMMDD)",
+  "label.base-time": "Masa Asas (HHMM)",
+  "label.nx": "Grid X (KMA 5km)",
+  "label.ny": "Grid Y (KMA 5km)",
+  "label.latitude": "Latitud (auto-tukar ke grid bila diisi)",
+  "label.longitude": "Longitud",
+  "label.num-of-rows": "Bilangan rekod per muka",
+  "label.page-no": "No. muka surat"
 }

package/translations/zh.json

@@ -1,11 +1,18 @@
 {
   "label.service-key": "服务密钥 (data.go.kr)",
-  "label.api-origin": "API 源（可选）",
   "label.operation-ref": "操作引用",
   "label.operation-params": "操作参数",
   "label.sigungu-cd": "市郡区代码",
   "label.bjdong-cd": "法定洞代码",
   "label.plat-gb-cd": "用地类型",
   "label.bun": "本番",
-  "label.ji": "副番"
+  "label.ji": "副番",
+  "label.base-date": "发布日期 (YYYYMMDD)",
+  "label.base-time": "发布时刻 (HHMM)",
+  "label.nx": "网格 X (KMA 5km)",
+  "label.ny": "网格 Y (KMA 5km)",
+  "label.latitude": "纬度 (输入经纬度自动转换为网格)",
+  "label.longitude": "经度",
+  "label.num-of-rows": "每页条数",
+  "label.page-no": "页码"
 }

package/dist-server/engine/spec/building-ledger.d.ts

@@ -1,9 +0,0 @@
-import { ServiceSpec } from './types';
-/**
- * 국토교통부_건축물대장정보 서비스 v2 (data.go.kr 데이터셋 15044713).
- *
- * 세움터(EAIS) DB 를 원천으로 하는 공공 건축물대장 Open API.
- * 모든 오퍼레이션은 동일한 PNU(필지고유번호) 구성요소로 조회한다:
- *  - sigunguCd (5) + bjdongCd (5) + platGbCd (1) + bun (4) + ji (4)
- */
-export declare const BldRgstServiceV2: ServiceSpec;

package/dist-server/engine/spec/building-ledger.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"building-ledger.js","sourceRoot":"","sources":["../../../server/engine/spec/building-ledger.ts"],"names":[],"mappings":"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","sourcesContent":["import { OperationParamSpec, ServiceSpec } from './types'\n\n/**\n * PNU 5요소 파라미터 스펙 — BldRgstServiceV2 의 모든 오퍼레이션이 공유.\n * 별도 배열 분리로 작성해두면 타 서비스(예: 건축물대장 허브) 도 재사용 가능.\n */\nconst pnuParams: OperationParamSpec[] = [\n  {\n    name: 'sigunguCd',\n    label: 'label.sigungu-cd',\n    required: true,\n    length: 5,\n    description: '시군구코드 5자리 (법정동코드 10자리의 앞 5자리).',\n    example: '11680'\n  },\n  {\n    name: 'bjdongCd',\n    label: 'label.bjdong-cd',\n    required: true,\n    length: 5,\n    description: '법정동코드 5자리 (법정동코드 10자리의 뒤 5자리).',\n    example: '10300'\n  },\n  {\n    name: 'platGbCd',\n    label: 'label.plat-gb-cd',\n    default: '0',\n    length: 1,\n    description: '대지구분 1자리. `0` 대지 / `1` 산 / `2` 블록.',\n    example: '0',\n    enum: [\n      { value: '0', label: '대지' },\n      { value: '1', label: '산' },\n      { value: '2', label: '블록' }\n    ]\n  },\n  {\n    name: 'bun',\n    label: 'label.bun',\n    required: true,\n    pad: 4,\n    description: '본번. 자동으로 4자리 zero-pad 됨 (예: `6` → `0006`). 하이픈 포함 지번은 본번/부번을 각각 입력.',\n    example: '223'\n  },\n  {\n    name: 'ji',\n    label: 'label.ji',\n    default: '0',\n    pad: 4,\n    description: '부번. 없으면 `0`. 자동 4자리 zero-pad.',\n    example: '0'\n  }\n]\n\n/**\n * 국토교통부_건축물대장정보 서비스 v2 (data.go.kr 데이터셋 15044713).\n *\n * 세움터(EAIS) DB 를 원천으로 하는 공공 건축물대장 Open API.\n * 모든 오퍼레이션은 동일한 PNU(필지고유번호) 구성요소로 조회한다:\n *  - sigunguCd (5) + bjdongCd (5) + platGbCd (1) + bun (4) + ji (4)\n */\nexport const BldRgstServiceV2: ServiceSpec = {\n  serviceId: '1613000/BldRgstService_v2',\n  label: '국토교통부_건축물대장정보 서비스 v2',\n  description:\n    '세움터(EAIS) 원천의 건축물대장 정보를 조회한다. 표제부·총괄표제부·층별개요·부속지번·전유공용면적·주택가격·소유자현황·기본개요 등 8개 오퍼레이션 제공.',\n  homepage: 'https://www.data.go.kr/data/15044713/openapi.do',\n  operations: {\n    getBrTitleInfo: {\n      operationId: 'getBrTitleInfo',\n      label: '표제부 조회',\n      description:\n        '건축물대장 표제부 (건물 본문) 를 조회한다. 연면적·용적률·지상층수·지하층수·주구조·주용도 등 건물 개요를 반환. 한 필지에 동이 여러 개이면 복수 레코드로 내려온다.',\n      params: [...pnuParams],\n      responseNotes:\n        '응답 `response.body.items.item` 이 배열 또는 단일 객체로 올 수 있음. 모든 숫자 필드가 문자열(`\"114000.00\"`)로 내려옴. 집합건축물은 `regstrKindCd=3`, 일반건축물은 `regstrKindCd=2`.',\n      externalDocsUrl: 'https://www.data.go.kr/data/15044713/openapi.do',\n      examples: [\n        {\n          label: '서울 강남구 역삼동 823',\n          params: { sigunguCd: '11680', bjdongCd: '10300', bun: '823', ji: '0' }\n        }\n      ]\n    },\n    getBrRecapTitleInfo: {\n      operationId: 'getBrRecapTitleInfo',\n      label: '총괄표제부 조회',\n      description:\n        '집합건축물(아파트 단지 등) 의 총괄표제부를 조회한다. 단지 전체 연면적·대지면적·동 수·세대수 등을 반환. 일반건축물에는 없음.',\n      params: [...pnuParams],\n      responseNotes: '일반건축물대장(단동) 의 경우 레코드가 없음. 집합건축물일 때만 유효.',\n      examples: [\n        {\n          label: '아파트 단지 (예시)',\n          params: { sigunguCd: '11680', bjdongCd: '10300', bun: '823', ji: '0' }\n        }\n      ]\n    },\n    getBrFlrOulnInfo: {\n      operationId: 'getBrFlrOulnInfo',\n      label: '층별개요 조회',\n      description:\n        '층별로 주용도·구조·면적을 조회. 지하 N층부터 지상 M층까지 각 층의 상세 구성을 반환. `regstrKindCd`, `regstrGbCd` 로 어느 대장의 층인지 구분.',\n      params: [...pnuParams],\n      responseNotes: '한 필지에 동이 여러 개이면 각 동의 각 층이 모두 나옴 → 결과 건수가 많을 수 있음.'\n    },\n    getBrExposPubuseAreaInfo: {\n      operationId: 'getBrExposPubuseAreaInfo',\n      label: '전유공용면적 조회',\n      description:\n        '집합건축물의 호(세대) 별 전유면적·공용면적을 조회. 아파트 세대별 실제 면적 산출에 사용.',\n      params: [...pnuParams],\n      responseNotes: '집합건축물일 때만 레코드 존재. 일반건축물에는 해당 없음.'\n    },\n    getBrAtchJibunInfo: {\n      operationId: 'getBrAtchJibunInfo',\n      label: '부속지번 조회',\n      description: '대장에 연결된 부속지번(인접 필지 등) 목록을 조회.',\n      params: [...pnuParams]\n    },\n    getBrHsprcInfo: {\n      operationId: 'getBrHsprcInfo',\n      label: '주택가격 조회',\n      description: '공동주택/단독주택 공시가격 이력을 조회. 연도별 개별주택가격·공동주택가격 제공.',\n      params: [...pnuParams]\n    },\n    getBrBasisOulnInfo: {\n      operationId: 'getBrBasisOulnInfo',\n      label: '기본개요 조회',\n      description: '대장의 기본개요(대장 구분, 대장 종류, 변동일, 변동원인) 를 조회. 변동 이력 추적 용도.',\n      params: [...pnuParams]\n    },\n    getBrExposInfo: {\n      operationId: 'getBrExposInfo',\n      label: '전유부 조회',\n      description: '집합건축물의 호(세대) 목록과 호별 개요를 조회. 전유공용면적보다 상위 요약 수준.',\n      params: [...pnuParams]\n    }\n  }\n}\n"]}