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

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

@@ -0,0 +1,157 @@
+import { DataGoKrResponse } from '../types'
+
+/**
+ * 공공데이터포털(data.go.kr) 공용 HTTP 클라이언트.
+ *
+ * 모든 data.go.kr Open API 는 아래 공통 규약을 따른다:
+ *  - URL: `https://apis.data.go.kr/<agency>/<service>/<operation>`
+ *  - 인증: `serviceKey` 쿼리 파라미터 (Encoding/Decoding 두 형태 모두 수용)
+ *  - 포맷: `_type=json` 없으면 XML
+ *  - 에러: `<OpenAPI_ServiceResponse>` XML 또는 `response.header.resultCode !== '00'`
+ *
+ * 본 클라이언트는 서비스·오퍼레이션에 독립적으로 동작하며, 경로를 파라미터로 받는다.
+ * 서비스별 도메인 로직(파라미터 검증, 응답 매핑) 은 task 레이어에서 처리.
+ */
+
+const DEFAULT_ORIGIN = 'https://apis.data.go.kr'
+
+export interface DataGoKrClientOptions {
+  serviceKey: string
+  /** 오리진 오버라이드 (모의 서버/사설 프록시 용도). 기본 `https://apis.data.go.kr`. */
+  origin?: string
+}
+
+export class DataGoKrClient {
+  private readonly serviceKey: string
+  private readonly origin: string
+
+  constructor(options: DataGoKrClientOptions) {
+    if (!options.serviceKey) {
+      throw new Error('DataGoKrClient requires serviceKey')
+    }
+    /* Encoding 키(%2B 포함)를 붙여넣어도 Decoding 키처럼 동작하도록 정규화.
+       base64 키는 `%` 를 포함하지 않으므로 raw Decoding 키는 영향 없음. */
+    this.serviceKey = normalizeServiceKey(options.serviceKey.trim())
+    this.origin = resolveOrigin(options.origin)
+  }
+
+  /**
+   * 범용 GET 호출.
+   *
+   * @param servicePath `<agency>/<service>/<operation>` (예: `1613000/BldRgstHubService/getBrTitleInfo`)
+   * @param params 쿼리 파라미터 (serviceKey / _type 은 자동 추가)
+   */
+  async get<T>(servicePath: string, params: Record<string, any>): Promise<DataGoKrResponse<T>> {
+    const path = servicePath.startsWith('/') ? servicePath : `/${servicePath}`
+    const url = new URL(`${this.origin}${path}`)
+    url.searchParams.set('serviceKey', this.serviceKey)
+    url.searchParams.set('_type', 'json')
+    for (const [k, v] of Object.entries(params)) {
+      if (v === undefined || v === null || v === '') continue
+      url.searchParams.set(k, String(v))
+    }
+
+    const response = await fetch(url.toString(), {
+      method: 'GET',
+      headers: {
+        'User-Agent': '@things-factory/integration-data-go-kr',
+        Accept: 'application/json'
+      }
+    })
+    const raw = await response.text()
+
+    const nonSensitiveParams = Object.entries(params)
+      .filter(([, v]) => v !== undefined && v !== null && v !== '')
+      .map(([k, v]) => `${k}=${v}`)
+      .join(' ')
+
+    if (!response.ok) {
+      throw new Error(
+        `data.go.kr ${servicePath} failed (${response.status}): ${raw.slice(0, 300)} — params: ${nonSensitiveParams}`
+      )
+    }
+
+    let parsed: DataGoKrResponse<T>
+    try {
+      parsed = JSON.parse(raw) as DataGoKrResponse<T>
+    } catch (err) {
+      if (raw.includes('<OpenAPI_ServiceResponse') || raw.includes('<returnReasonCode>')) {
+        throw new Error(`data.go.kr ${servicePath}: ${parseOpenApiError(raw)} — params: ${nonSensitiveParams}`)
+      }
+      throw new Error(
+        `data.go.kr ${servicePath}: non-JSON response: ${raw.slice(0, 300)} — params: ${nonSensitiveParams}`
+      )
+    }
+
+    const header = parsed?.response?.header
+    if (!header) {
+      throw new Error(`data.go.kr ${servicePath}: response missing header — body: ${raw.slice(0, 300)}`)
+    }
+    if (header.resultCode !== '00') {
+      throw new Error(
+        `data.go.kr ${servicePath}: resultCode=${header.resultCode} msg=${header.resultMsg} — params: ${nonSensitiveParams}`
+      )
+    }
+
+    return parsed
+  }
+
+  /**
+   * 단건 또는 복수 items 를 배열로 정규화해서 반환한다.
+   *
+   * data.go.kr 공통 특성으로, body.items 가 아래 세 가지 형태로 올 수 있다:
+   *  - `""` (빈 문자열, 결과 없음)
+   *  - `{ item: { ... } }` (단건)
+   *  - `{ item: [ ... ] }` (복수)
+   */
+  async getItems<T>(servicePath: string, params: Record<string, any>): Promise<T[]> {
+    const response = await this.get<T>(servicePath, params)
+    const items = response.response?.body?.items
+    if (!items) return []
+    const arr = (items as any).item
+    if (!arr) return []
+    return Array.isArray(arr) ? arr : [arr]
+  }
+}
+
+/**
+ * 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
+  try {
+    return decodeURIComponent(key)
+  } catch {
+    return key
+  }
+}
+
+/** data.go.kr 공용 OpenAPI 에러 XML 에서 원인 추출. */
+function parseOpenApiError(xml: string): string {
+  const code = /<returnReasonCode>([^<]+)<\/returnReasonCode>/.exec(xml)?.[1]
+  const msg = /<errMsg>([^<]+)<\/errMsg>/.exec(xml)?.[1]
+  const auth = /<returnAuthMsg>([^<]+)<\/returnAuthMsg>/.exec(xml)?.[1]
+  return `code=${code} msg=${msg} auth=${auth}`
+}

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

@@ -0,0 +1,72 @@
+import { ConnectionManager, Connector } from '@things-factory/integration-base'
+
+import { DataGoKrClient } from './data-go-kr-client'
+
+/**
+ * 공공데이터포털(data.go.kr) Open API 커넥터.
+ *
+ * 하나의 ServiceKey 로 data.go.kr 산하 **모든 오퍼레이션** 을 호출할 수 있으므로,
+ * 사용자는 Connection 을 보통 한 개만 만들고 (앱·법인별로 1개) 여러 태스크에서 재사용한다.
+ *
+ * Connection 의 `endpoint` 필드를 API 오리진(host) 으로 사용한다. 비워두면 기본값
+ * `https://apis.data.go.kr` 가 사용되며, 모의 서버/사설 프록시로 라우팅하려면
+ * 해당 오리진을 endpoint 에 입력한다.
+ */
+export interface DataGoKrConnectionInstance {
+  client: DataGoKrClient
+}
+
+export class DataGoKrConnector implements Connector {
+  async ready(connectionConfigs) {
+    await Promise.all(connectionConfigs.map(this.connect.bind(this)))
+    ConnectionManager.logger.info('data-go-kr-connector connections are ready')
+  }
+
+  async connect(connection) {
+    const { endpoint, params } = connection
+    try {
+      const client = new DataGoKrClient({
+        serviceKey: params.serviceKey,
+        origin: endpoint
+      })
+      const instance: DataGoKrConnectionInstance = { client }
+      ConnectionManager.addConnectionInstance(connection, instance)
+      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
+    }
+  }
+
+  async disconnect(connection) {
+    ConnectionManager.removeConnectionInstance(connection)
+    ConnectionManager.logger.info(`data-go-kr-connector connection(${connection.name}) is disconnected`)
+  }
+
+  get parameterSpec() {
+    return [
+      {
+        type: 'secret',
+        name: 'serviceKey',
+        label: 'label.service-key',
+        useDomainAttribute: true
+      }
+    ]
+  }
+
+  get taskPrefixes() {
+    return ['data-go-kr']
+  }
+
+  get help() {
+    return 'integration/connector/data-go-kr-connector'
+  }
+
+  get description() {
+    return 'Korean Public Data Portal (data.go.kr) Connector'
+  }
+}
+
+ConnectionManager.registerConnector('data-go-kr-connector', new DataGoKrConnector())

package/server/engine/connector/index.ts

@@ -0,0 +1 @@
+import './data-go-kr-connector'

package/server/engine/index.ts

@@ -0,0 +1,2 @@
+import './connector'
+import './task'

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

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

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

@@ -0,0 +1,62 @@
+import { OperationSpec, ServiceSpec, parseOperationRef } from './types'
+
+/* 도메인별 서비스 스펙 — 새 도메인 추가 시 폴더 추가 + 본 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>()
+
+function registerService(spec: ServiceSpec) {
+  services.set(spec.serviceId, spec)
+}
+
+/* 도메인 모듈에서 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 = {
+  /** 등록된 모든 서비스 스펙을 반환. */
+  listServices(): ServiceSpec[] {
+    return Array.from(services.values())
+  },
+
+  /** 서비스 ID 로 서비스 스펙 조회. */
+  getService(serviceId: string): ServiceSpec | undefined {
+    return services.get(serviceId)
+  },
+
+  /** `<serviceId>.<operationId>` 참조 문자열로 오퍼레이션 스펙 조회. */
+  resolve(operationRef: string): { service: ServiceSpec; operation: OperationSpec } | undefined {
+    const parts = parseOperationRef(operationRef)
+    if (!parts) return undefined
+    const service = services.get(parts.serviceId)
+    if (!service) return undefined
+    const operation = service.operations[parts.operationId]
+    if (!operation) return undefined
+    return { service, operation }
+  },
+
+  /** (확장용) 외부에서 서비스 스펙을 추가 등록. */
+  register(spec: ServiceSpec) {
+    registerService(spec)
+  }
+}

package/server/engine/spec/types.ts

@@ -0,0 +1,84 @@
+/**
+ * 공공데이터포털(data.go.kr) Open API 오퍼레이션 스펙 타입.
+ *
+ * "선언적 레지스트리 + 단일 범용 태스크" 패턴의 핵심.
+ *
+ * - 런타임에는 `data-go-kr-call` 태스크가 이 스펙으로 파라미터 검증·정규화
+ * - 빌드/CI 에서는 이 스펙으로부터 서비스 카탈로그 markdown 을 자동 생성 가능
+ * - (장기) 통합 UI 가 이 스펙을 읽어 오퍼레이션 선택 시 **동적 폼 + 인라인 도움말** 을 렌더
+ *
+ * 즉 스펙 하나가 검증·문서·UI 3가지의 진실의 원천(single source of truth) 이다.
+ */
+
+/** 단일 파라미터 스펙 (도움말용 메타 포함). */
+export interface OperationParamSpec {
+  /** 쿼리 파라미터 이름 (예: `sigunguCd`). */
+  name: string
+  /** 화면 라벨 키 (i18n). 생략 시 `name` 사용. */
+  label?: string
+  /** 필수 여부. */
+  required?: boolean
+  /** 기본값 (입력 생략 시 적용). */
+  default?: string
+  /** zero-pad 길이. 예: `bun=6` + pad=4 → `"0006"`. */
+  pad?: number
+  /** 정확히 이 길이여야 함. 위반 시 태스크가 ValidationError 던짐. */
+  length?: number
+  /** 사람이 읽는 파라미터 설명 (도움말·UI 툴팁). */
+  description: string
+  /** 예시 값. */
+  example?: string | number
+  /** enum 선택지. 제공 시 태스크가 해당 값만 허용. */
+  enum?: Array<{ value: string; label: string }>
+}
+
+/** 오퍼레이션(엔드포인트) 스펙. */
+export interface OperationSpec {
+  /** 오퍼레이션 경로명 (예: `getBrTitleInfo`). */
+  operationId: string
+  /** 화면 라벨 (예: '표제부 조회'). */
+  label: string
+  /** 사람이 읽는 설명 — 이 오퍼레이션이 무엇을 돌려주는지. */
+  description: string
+  /** 파라미터 목록 (검증 + 문서). */
+  params: OperationParamSpec[]
+  /** 응답 구조 주의사항 (예: 다동 필지는 items 복수, 숫자는 문자열 등). */
+  responseNotes?: string
+  /** data.go.kr 원문 상세 페이지 URL. */
+  externalDocsUrl?: string
+  /** 자주 쓰는 예시 호출. */
+  examples?: Array<{
+    label: string
+    params: Record<string, any>
+    comment?: string
+  }>
+}
+
+/** 서비스 스펙 (오퍼레이션 묶음). */
+export interface ServiceSpec {
+  /** 서비스 경로 (예: `1613000/BldRgstHubService`). */
+  serviceId: string
+  /** 화면 라벨 (예: '국토교통부_건축물대장 허브 서비스'). */
+  label: string
+  /** 사람이 읽는 설명. */
+  description: string
+  /** data.go.kr 활용신청 페이지 URL. */
+  homepage?: string
+  /** 오퍼레이션 맵 (operationId → spec). */
+  operations: Record<string, OperationSpec>
+}
+
+/**
+ * 오퍼레이션 참조 문자열 파서.
+ *
+ * 레지스트리 조회 키: `"<serviceId>.<operationId>"` — 점으로 구분.
+ * 예: `"1613000/BldRgstHubService.getBrTitleInfo"`
+ */
+export function parseOperationRef(ref: string): { serviceId: string; operationId: string } | null {
+  const idx = ref.lastIndexOf('.')
+  if (idx < 0) return null
+  return {
+    serviceId: ref.substring(0, idx),
+    operationId: ref.substring(idx + 1)
+  }
+}

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'

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
+    }
+  }
+}