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

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

@@ -0,0 +1,140 @@
+import { OperationParamSpec, ServiceSpec } from './types'
+
+/**
+ * PNU 5요소 파라미터 스펙 — BldRgstServiceV2 의 모든 오퍼레이션이 공유.
+ * 별도 배열 분리로 작성해두면 타 서비스(예: 건축물대장 허브) 도 재사용 가능.
+ */
+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'
+  }
+]
+
+/**
+ * 국토교통부_건축물대장정보 서비스 v2 (data.go.kr 데이터셋 15044713).
+ *
+ * 세움터(EAIS) DB 를 원천으로 하는 공공 건축물대장 Open API.
+ * 모든 오퍼레이션은 동일한 PNU(필지고유번호) 구성요소로 조회한다:
+ *  - sigunguCd (5) + bjdongCd (5) + platGbCd (1) + bun (4) + ji (4)
+ */
+export const BldRgstServiceV2: ServiceSpec = {
+  serviceId: '1613000/BldRgstService_v2',
+  label: '국토교통부_건축물대장정보 서비스 v2',
+  description:
+    '세움터(EAIS) 원천의 건축물대장 정보를 조회한다. 표제부·총괄표제부·층별개요·부속지번·전유공용면적·주택가격·소유자현황·기본개요 등 8개 오퍼레이션 제공.',
+  homepage: 'https://www.data.go.kr/data/15044713/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/15044713/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/index.ts

@@ -0,0 +1,41 @@
+import { OperationSpec, ServiceSpec, parseOperationRef } from './types'
+import { BldRgstServiceV2 } from './building-ledger'
+
+export { BldRgstServiceV2 } from './building-ledger'
+export * from './types'
+
+const services = new Map<string, ServiceSpec>()
+
+function registerService(spec: ServiceSpec) {
+  services.set(spec.serviceId, spec)
+}
+
+registerService(BldRgstServiceV2)
+
+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/BldRgstService_v2`). */
+  serviceId: string
+  /** 화면 라벨 (예: '국토교통부_건축물대장정보 서비스 v2'). */
+  label: string
+  /** 사람이 읽는 설명. */
+  description: string
+  /** data.go.kr 활용신청 페이지 URL. */
+  homepage?: string
+  /** 오퍼레이션 맵 (operationId → spec). */
+  operations: Record<string, OperationSpec>
+}
+
+/**
+ * 오퍼레이션 참조 문자열 파서.
+ *
+ * 레지스트리 조회 키: `"<serviceId>.<operationId>"` — 점으로 구분.
+ * 예: `"1613000/BldRgstService_v2.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/task/building-ledger/general.ts

@@ -0,0 +1,109 @@
+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 { BrTitleItem, BuildingLedgerResult } from '../../types'
+
+/**
+ * 건축물대장 표제부(`getBrTitleInfo`) 조회 태스크.
+ *
+ * 순수 fetch 만 수행 — 응답 items 를 그대로 반환한다. 다동 필지 집계·단위 변환
+ * 같은 도메인 가공은 소비자 측 후속 스텝(data-mapper / jsonata / 자체 태스크) 에서
+ * 처리하도록 책임을 분리.
+ *
+ * 왜 전용 태스크인가:
+ *  - 범용 `data-go-kr-call` 로도 호출 가능하지만, 필요한 operationRef 와 PNU 5요소
+ *    파라미터를 매번 입력하는 대신 파라미터 폼을 명시적으로 제공해 운영/시나리오
+ *    작성 부담을 줄인다.
+ *  - 건축물대장은 dssp/dkpi·건산연·공인중개·자산관리 등 자주 쓰이는 도메인이므로
+ *    범용보다 한 단계 전용화된 표면을 둘 가치가 충분.
+ */
+async function BuildingLedgerTask(step, context: Context): Promise<{ data: BuildingLedgerResult }> {
+  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(`data-go-kr-building-ledger: failed to evaluate parameter: ${(err as Error).message}`)
+    }
+  }
+
+  const sigunguCd = evalString(params.sigunguCd)
+  const bjdongCd = evalString(params.bjdongCd)
+  const bun = evalString(params.bun)
+
+  if (!sigunguCd) throw new Error('data-go-kr-building-ledger: sigunguCd is required')
+  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 normalizedParams = {
+    sigunguCd,
+    bjdongCd,
+    platGbCd: evalString(params.platGbCd) || '0',
+    bun: zpad(bun, 4),
+    ji: zpad(evalString(params.ji) || '0', 4),
+    numOfRows: 100,
+    pageNo: 1
+  }
+
+  logger?.info?.(`[data-go-kr] ${servicePath} params=${JSON.stringify(normalizedParams)}`)
+
+  const items: BrTitleItem[] = await instance.client.getItems(servicePath, normalizedParams)
+
+  if (items.length === 0) {
+    throw new Error(
+      `data-go-kr-building-ledger: no 표제부 records for PNU ` +
+        `${normalizedParams.sigunguCd}-${normalizedParams.bjdongCd}-${normalizedParams.platGbCd}-` +
+        `${normalizedParams.bun}-${normalizedParams.ji}. ` +
+        `Possible causes: PNU is wrong, building is pre-approval, or the lot has no registered building.`
+    )
+  }
+
+  logger?.info?.(`[data-go-kr] items=${items.length} first.bldNm='${items[0].bldNm || ''}'`)
+
+  return { data: { items } }
+}
+
+function zpad(value: string, width: number): string {
+  const s = String(value)
+  return s.length >= width ? s : '0'.repeat(width - s.length) + s
+}
+
+BuildingLedgerTask.parameterSpec = [
+  { type: 'string', name: 'sigunguCd', label: 'label.sigungu-cd', placeholder: '예) 11680' },
+  { type: 'string', name: 'bjdongCd', label: 'label.bjdong-cd', placeholder: '예) 10300' },
+  {
+    type: 'select',
+    name: 'platGbCd',
+    label: 'label.plat-gb-cd',
+    property: {
+      options: [
+        { value: '0', display: '대지 / Plot' },
+        { value: '1', display: '산 / Mountain' },
+        { value: '2', display: '블록 / Block' }
+      ]
+    }
+  },
+  { type: 'string', name: 'bun', label: 'label.bun', placeholder: '예) 223' },
+  { type: 'string', name: 'ji', label: 'label.ji', placeholder: '예) 0' }
+]
+
+BuildingLedgerTask.help = 'integration/task/building-ledger'
+
+TaskRegistry.registerTaskHandler('data-go-kr-building-ledger', BuildingLedgerTask)
+
+export default BuildingLedgerTask

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

@@ -0,0 +1,12 @@
+/**
+ * 건축물대장 도메인 전용 태스크 그룹.
+ *
+ * 공통 경로(`data-go-kr-call` + SpecRegistry) 로 커버 가능한 호출은 굳이 전용 태스크를
+ * 만들지 말 것 — 이 폴더는 **공통으로 표현하기 어려운 도메인 특화 로직** 이 필요한
+ * 태스크만 들어가는 자리이다.
+ *
+ * 향후 추가 예시:
+ *  - apt.ts   : data-go-kr-building-ledger-apt   (집합건축물/아파트 전용)
+ *  - recap.ts : data-go-kr-building-ledger-recap (총괄표제부 전용 변형)
+ */
+import './general'

package/server/engine/task/call.ts

@@ -0,0 +1,157 @@
+import { ConnectionManager, Context, TaskRegistry, evaluateTemplate } from '@things-factory/integration-base'
+
+import { DataGoKrConnectionInstance } from '../connector/data-go-kr-connector'
+import { DataGoKrResponse } from '../types'
+import { OperationSpec, SpecRegistry } from '../spec'
+
+/**
+ * 범용 공공데이터포털 호출 태스크.
+ *
+ * 하나의 태스크가 등록된 레지스트리의 **모든 오퍼레이션** 을 커버한다. TaskRegistry 가
+ * 수백 개 태스크로 폭발하는 것을 방지하는 핵심 설계.
+ *
+ * 입력:
+ *  - `operationRef` : `"<serviceId>.<operationId>"` 형식 (예: `"1613000/BldRgstService_v2.getBrTitleInfo"`)
+ *  - `params`       : 오퍼레이션 파라미터 객체. 스펙 등록된 오퍼레이션이면 자동 검증·기본값·zero-pad 적용
+ *
+ * 레지스트리에 없는 오퍼레이션도 호출 가능 (스펙 없음 → 검증 스킵). 새 data.go.kr 서비스가
+ * 등장해도 스펙 추가 전까지 범용 호출로 즉시 사용 가능하다는 장점.
+ */
+async function DataGoKrCall(step, context: Context): Promise<{ data: DataGoKrResponse<any> }> {
+  const { connection: connectionName, params: stepParams } = 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 operationRef = stepParams?.operationRef
+  if (!operationRef || typeof operationRef !== 'string') {
+    throw new Error('data-go-kr-call: operationRef is required (format: "<serviceId>.<operationId>")')
+  }
+
+  const resolved = SpecRegistry.resolve(operationRef)
+  const rawParams = stepParams?.params || {}
+
+  const scope = { domain, user, lng, data, variables, console }
+  const evalValue = (value: any) => {
+    if (value === undefined || value === null) return value
+    if (typeof value !== 'string') return value
+    try {
+      return evaluateTemplate(value, scope)
+    } catch (err) {
+      throw new Error(`data-go-kr-call: failed to evaluate parameter: ${(err as Error).message}`)
+    }
+  }
+
+  const evaluatedParams: Record<string, any> = {}
+  for (const [k, v] of Object.entries(rawParams)) {
+    evaluatedParams[k] = evalValue(v)
+  }
+
+  const { service, operation } = resolved || { service: null, operation: null }
+  const finalParams = operation
+    ? normalizeAndValidateParams(operation, evaluatedParams)
+    : evaluatedParams
+
+  const servicePath = resolved
+    ? `${service!.serviceId}/${operation!.operationId}`
+    : operationRef.replace('.', '/')
+
+  logger?.info?.(`[data-go-kr] call ${servicePath} params=${JSON.stringify(finalParams)}`)
+
+  const response = await instance.client.get(servicePath, finalParams)
+  return { data: response }
+}
+
+/**
+ * 스펙 기반 파라미터 정규화·검증.
+ *
+ *  1. required 필수값 체크
+ *  2. default 기본값 주입
+ *  3. pad zero-padding (예: bun=6 → "0006")
+ *  4. length 정확 길이 검증
+ *  5. enum 허용 값 검증
+ */
+function normalizeAndValidateParams(operation: OperationSpec, input: Record<string, any>): Record<string, any> {
+  const output: Record<string, any> = {}
+  const errors: string[] = []
+
+  for (const p of operation.params) {
+    let value = input[p.name]
+
+    if (value === undefined || value === null || value === '') {
+      if (p.default !== undefined) {
+        value = p.default
+      } else if (p.required) {
+        errors.push(`'${p.name}' is required (${p.description})`)
+        continue
+      } else {
+        continue
+      }
+    }
+
+    value = String(value)
+
+    if (p.pad && value.length < p.pad) {
+      value = '0'.repeat(p.pad - value.length) + value
+    }
+
+    if (p.length !== undefined && value.length !== p.length) {
+      errors.push(
+        `'${p.name}' must be exactly ${p.length} characters (got "${value}", length ${value.length})`
+      )
+      continue
+    }
+
+    if (p.enum && !p.enum.some(e => e.value === value)) {
+      errors.push(
+        `'${p.name}' must be one of [${p.enum.map(e => e.value).join(', ')}] (got "${value}")`
+      )
+      continue
+    }
+
+    output[p.name] = value
+  }
+
+  /* 스펙에 없는 파라미터도 pass-through (미등록 필드 허용) */
+  for (const [k, v] of Object.entries(input)) {
+    if (!(k in output) && !operation.params.find(p => p.name === k)) {
+      if (v !== undefined && v !== null && v !== '') {
+        output[k] = v
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(
+      `data-go-kr-call parameter validation failed for ${operation.operationId}:\n  - ${errors.join('\n  - ')}`
+    )
+  }
+
+  return output
+}
+
+DataGoKrCall.parameterSpec = [
+  {
+    type: 'string',
+    name: 'operationRef',
+    label: 'label.operation-ref',
+    placeholder: '<serviceId>.<operationId> (예: 1613000/BldRgstService_v2.getBrTitleInfo)'
+  },
+  {
+    type: 'scenario-step-input',
+    name: 'params',
+    label: 'label.operation-params'
+  }
+]
+
+DataGoKrCall.help = 'integration/task/data-go-kr-call'
+
+TaskRegistry.registerTaskHandler('data-go-kr-call', DataGoKrCall)
+
+export default DataGoKrCall

package/server/engine/task/index.ts

@@ -0,0 +1,19 @@
+/**
+ * 태스크 배럴.
+ *
+ * 구성 규약:
+ *  - 범용 태스크 (여러 서비스에 공통 적용) 는 이 폴더 **최상단** 에 파일로 배치
+ *    예) call.ts → data-go-kr-call
+ *
+ *  - 특정 도메인/서비스의 전용 태스크는 **도메인 이름 폴더** 아래 배치
+ *    예) building-ledger/ , (향후) property-trade/ , address/ ...
+ *
+ * 새 서비스 지원 우선순위:
+ *  1) 먼저 SpecRegistry 에 서비스 스펙을 등록 → `data-go-kr-call` 로 즉시 호출 가능
+ *  2) 그래도 불충분한 경우(입력 폼 필요, 응답 구조가 비표준, 도메인 가공 필수 등)만
+ *     도메인 폴더를 새로 만들고 전용 태스크 작성
+ *
+ * 즉 이 폴더에 새 파일/폴더가 추가되는 것은 "공통 경로로 풀 수 없는 예외" 뿐이다.
+ */
+import './call'
+import './building-ledger'

package/server/engine/types.ts

@@ -0,0 +1,64 @@
+/**
+ * 공공데이터포털(data.go.kr) 공용 응답 타입.
+ *
+ * 대부분의 data.go.kr 서비스가 동일한 봉투(envelope) 구조를 사용한다:
+ *   { response: { header: { resultCode, resultMsg }, body: { items: { item[] }, numOfRows, pageNo, totalCount } } }
+ */
+
+/** 공공데이터포털 공용 응답 봉투. */
+export interface DataGoKrResponse<T> {
+  response: {
+    header: {
+      resultCode: string /* '00' = 정상 */
+      resultMsg: string
+    }
+    body: {
+      items?: { item?: T | T[] } | ''
+      numOfRows: number
+      pageNo: number
+      totalCount: number
+    }
+  }
+}
+
+/**
+ * 건축물대장 서비스 표제부(`getBrTitleInfo`) 레코드.
+ *
+ * 총 30+ 필드이지만 도메인에서 자주 쓰는 필드만 명시하고 나머지는 인덱스 시그니처.
+ */
+export interface BrTitleItem {
+  mgmBldrgstPk: string /* 관리건축물대장PK */
+  platPlc?: string /* 대지위치 */
+  newPlatPlc?: string /* 도로명대지위치 */
+  bldNm?: string /* 건물명 */
+  dongNm?: string /* 동명칭 */
+  platArea?: string /* 대지면적 */
+  archArea?: string /* 건축면적 */
+  bcRat?: string /* 건폐율(%) */
+  totArea?: string /* 연면적 ★ */
+  vlRatEstmTotArea?: string
+  vlRat?: string /* 용적률(%) ★ */
+  strctCd?: string
+  strctCdNm?: string
+  mainPurpsCd?: string
+  mainPurpsCdNm?: string
+  grndFlrCnt?: string /* 지상층수 ★ */
+  ugrndFlrCnt?: string /* 지하층수 ★ */
+  regstrKindCd?: string /* 2=일반 / 3=집합 */
+  regstrGbCd?: string
+  useAprDay?: string
+  mainBldCnt?: string
+  atchBldCnt?: string
+  totPkngCnt?: string
+  [key: string]: any
+}
+
+/**
+ * 건축물대장 표제부(`getBrTitleInfo`) 조회 결과.
+ *
+ * 다동(多棟) 필지는 items 가 여러 건, 단동 필지는 1건.
+ * 집계·요약은 소비자 스텝(data-mapper / jsonata / 도메인 전용 태스크) 에서 수행한다.
+ */
+export interface BuildingLedgerResult {
+  items: BrTitleItem[]
+}

package/server/index.ts

@@ -0,0 +1,5 @@
+import './engine'
+
+export * from './engine/types'
+export * from './engine/spec'
+export { DataGoKrClient } from './engine/connector/data-go-kr-client'

package/things-factory.config.js

@@ -0,0 +1 @@
+export default {}

package/translations/en.json

@@ -0,0 +1,11 @@
+{
+  "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)"
+}

package/translations/ja.json

@@ -0,0 +1,11 @@
+{
+  "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": "副番"
+}

package/translations/ko.json

@@ -0,0 +1,11 @@
+{
+  "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": "부번"
+}