@things-factory/integration-data-go-kr 10.0.0-beta.95 → 10.0.0-beta.97

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/integration-data-go-kr",
-  "version": "10.0.0-beta.95",
+  "version": "10.0.0-beta.97",
   "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.95"
   },
-  "gitHead": "17291189a406eb17709411200d0dc4acb54d92a2"
+  "gitHead": "465fc49ad3f7838232f36fc0dc82db1e49bf2149"
 }

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

@@ -83,23 +83,55 @@ function zpad(value: string, width: number): string {
   return s.length >= width ? s : '0'.repeat(width - s.length) + s
 }
 
+/*
+ * 컨텍스트 데이터 액세서 사용 예시 (이전 step 의 juso-resolve-address 결과 활용):
+ *   sigunguCd: `${data.pnu.sigunguCd}`
+ *   bjdongCd:  `${data.pnu.bjdongCd}`
+ *   platGbCd:  `${data.pnu.platGbCd}`
+ *   bun:       `${data.pnu.bun}`
+ *   ji:        `${data.pnu.ji}`
+ * 시나리오 흐름: [juso-resolve-address] → data.pnu → [data-go-kr-building-ledger]
+ *
+ * 모든 파라미터는 evaluateTemplate 로 평가되므로 `${...}` 표현식 그대로 입력 가능.
+ */
 BuildingLedgerTask.parameterSpec = [
-  { type: 'string', name: 'sigunguCd', label: 'label.sigungu-cd', placeholder: '예) 11680' },
-  { type: 'string', name: 'bjdongCd', label: 'label.bjdong-cd', placeholder: '예) 10300' },
   {
-    type: 'select',
+    type: 'string',
+    name: 'sigunguCd',
+    label: 'label.sigungu-cd',
+    placeholder: '예) 11680 또는 ${data.pnu.sigunguCd}',
+    description: '시군구코드 5자리. 이전 step 결과 액세서 사용 예: `${data.pnu.sigunguCd}`'
+  },
+  {
+    type: 'string',
+    name: 'bjdongCd',
+    label: 'label.bjdong-cd',
+    placeholder: '예) 10300 또는 ${data.pnu.bjdongCd}',
+    description: '법정동코드 5자리. 이전 step 결과 액세서 사용 예: `${data.pnu.bjdongCd}`'
+  },
+  {
+    type: 'string',
     name: 'platGbCd',
     label: 'label.plat-gb-cd',
-    property: {
-      options: [
-        { value: '0', display: '대지 / Plot' },
-        { value: '1', display: '산 / Mountain' },
-        { value: '2', display: '블록 / Block' }
-      ]
-    }
+    placeholder: '0=대지, 1=산, 2=블록 — 또는 ${data.pnu.platGbCd}',
+    description:
+      '대지구분 1자리. 정적값 0/1/2 또는 액세서 표현식 입력 가능. ' +
+      'juso → PNU 흐름이면 `${data.pnu.platGbCd}`.'
+  },
+  {
+    type: 'string',
+    name: 'bun',
+    label: 'label.bun',
+    placeholder: '예) 223 또는 ${data.pnu.bun}',
+    description: '본번. 자동 4자리 zero-pad. 액세서 사용 예: `${data.pnu.bun}`'
   },
-  { type: 'string', name: 'bun', label: 'label.bun', placeholder: '예) 223' },
-  { type: 'string', name: 'ji', label: 'label.ji', placeholder: '예) 0' }
+  {
+    type: 'string',
+    name: 'ji',
+    label: 'label.ji',
+    placeholder: '예) 0 또는 ${data.pnu.ji}',
+    description: '부번. 없으면 0. 자동 4자리 zero-pad. 액세서 사용 예: `${data.pnu.ji}`'
+  }
 ]
 
 BuildingLedgerTask.help = 'integration/task/building-ledger'

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

@@ -10,3 +10,4 @@
  *  - recap.ts : data-go-kr-building-ledger-recap (총괄표제부 전용 변형)
  */
 import './general'
+import './summary'

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

@@ -0,0 +1,277 @@
+import { ConnectionManager, Context, TaskRegistry, evaluateTemplate } from '@things-factory/integration-base'
+
+import { DataGoKrConnectionInstance } from '../../connector/data-go-kr-connector'
+import { BldRgstHubService } from '../../spec/building-ledger'
+import { BrTitleItem } from '../../types'
+
+/**
+ * 건축물 4 핵심 KPI (연면적·용적률·지상층수·지하층수) 만 **단일 객체** 로 반환하는
+ * 요약 태스크. PNU 한 번 입력으로 케이스 (집합·단동) 자동 분기 + 단일값 보장.
+ *
+ * 내부 흐름:
+ *   1) `getBrRecapTitleInfo` (총괄표제부) 호출
+ *      - 응답 items 가 1건 이상이면 단지 단위 row 그대로 사용 (source='recap')
+ *      - 0건이면 일반건축물 가능성 → 2 단계로
+ *   2) `getBrTitleInfo` (표제부) 호출
+ *      - items[0] 사용 (source='title')
+ *      - 단동이면 1건, 다동이면 첫 동 (일반건축물 분기라 보통 단동)
+ *   3) 둘 다 0건이면 에러
+ *
+ * 출력 (`data`):
+ *   {
+ *     totArea:    number | null,   // 연면적 (㎡)
+ *     vlRat:      number | null,   // 용적률 (%)
+ *     grndFlrCnt: number | null,   // 지상층수
+ *     ugrndFlrCnt:number | null,   // 지하층수
+ *     bldNm:      string | null,
+ *     useAprDay:  string | null,   // 사용승인일 YYYYMMDD
+ *     source:     'recap' | 'title',
+ *     raw:        BrTitleItem     // 원본 (집합·단동 케이스 모두의 단일 row)
+ *   }
+ *
+ * 시나리오 사용 예 (juso 결합):
+ *   [juso-resolve-address] → data.pnu
+ *   [data-go-kr-building-summary]
+ *       sigunguCd = ${data.pnu.sigunguCd}
+ *       bjdongCd  = ${data.pnu.bjdongCd}
+ *       platGbCd  = ${data.pnu.platGbCd}
+ *       bun       = ${data.pnu.bun}
+ *       ji        = ${data.pnu.ji}
+ *   다음 step 에서 ${data.totArea}, ${data.vlRat} 등 직접 접근.
+ */
+
+export interface BuildingSummary {
+  totArea: number | null
+  /** 대지면적 (㎡) — 집합건축물 총괄표제부에 있음 */
+  platArea: number | null
+  /** 건축면적 (㎡) */
+  archArea: number | null
+  /** 건폐율 (%) */
+  bcRat: number | null
+  vlRat: number | null
+  grndFlrCnt: number | null
+  ugrndFlrCnt: number | null
+  /** 주구조 코드 (예: '21'=철근콘크리트구조, '22'=철골철근콘크리트구조(SRC), '14'=프리캐스트콘크리트(PC) …) */
+  strctCd: string | null
+  /** 주구조 이름 (예: '철근콘크리트구조', '철골철근콘크리트구조') */
+  strctCdNm: string | null
+  /** 기타구조 자유텍스트 (도면상 상세 표기) */
+  etcStrct: string | null
+  /** 주용도 코드 (예: '02000'=공동주택, '03000'=제1종근린생활시설 …) */
+  mainPurpsCd: string | null
+  /** 주용도 이름 (예: '공동주택', '제1종근린생활시설') — DSSP SiteType 매핑 원천 */
+  mainPurpsCdNm: string | null
+  /** 기타용도 자유텍스트 (도면상 상세 표기) */
+  etcPurps: string | null
+  /** 세대수 — 집합건축물 */
+  hhldCnt: number | null
+  /** 가구수 */
+  fmlyCnt: number | null
+  /** 호수 (상가/근린 등) */
+  hoCnt: number | null
+  /** 주건축물수 (단지 동 수) — recap 에서 노출 */
+  mainBldCnt: number | null
+  /** 부속건축물수 */
+  atchBldCnt: number | null
+  /** 건물 높이 (m) */
+  heit: number | null
+  bldNm: string | null
+  useAprDay: string | null
+  /** 건축허가일 YYYYMMDD */
+  pmsDay: string | null
+  /** 착공일 YYYYMMDD */
+  stcnsDay: string | null
+  source: 'recap' | 'title'
+  raw: BrTitleItem
+}
+
+async function BuildingSummaryTask(step, context: Context): Promise<{ data: BuildingSummary }> {
+  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-summary: 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-summary: sigunguCd is required')
+  if (!bjdongCd) throw new Error('data-go-kr-building-summary: bjdongCd is required')
+  if (!bun) throw new Error('data-go-kr-building-summary: bun is required')
+
+  const pnu = {
+    sigunguCd,
+    bjdongCd,
+    platGbCd: evalString(params.platGbCd) || '0',
+    bun: zpad(bun, 4),
+    ji: zpad(evalString(params.ji) || '0', 4),
+    numOfRows: 100,
+    pageNo: 1
+  }
+
+  // 두 API 모두 호출 — recap 결과가 있어도 strctCdNm 등 동 단위 정보는
+  // 표제부의 주건축물 row 에서 보완.
+  const recapPath = `${BldRgstHubService.serviceId}/getBrRecapTitleInfo`
+  const titlePath = `${BldRgstHubService.serviceId}/getBrTitleInfo`
+  logger?.info?.(`[data-go-kr] fetch recap + title params=${JSON.stringify(pnu)}`)
+
+  const [recapItems, titleItems] = await Promise.all([
+    instance.client
+      .getItems<BrTitleItem>(recapPath, pnu)
+      .catch(err => {
+        logger?.warn?.(`[data-go-kr] recap call failed: ${(err as Error).message}`)
+        return [] as BrTitleItem[]
+      }),
+    instance.client
+      .getItems<BrTitleItem>(titlePath, pnu)
+      .catch(err => {
+        logger?.warn?.(`[data-go-kr] title call failed: ${(err as Error).message}`)
+        return [] as BrTitleItem[]
+      })
+  ])
+
+  if (recapItems.length === 0 && titleItems.length === 0) {
+    throw new Error(
+      `data-go-kr-building-summary: PNU ${pnu.sigunguCd}-${pnu.bjdongCd}-${pnu.platGbCd}-${pnu.bun}-${pnu.ji} ` +
+        `에 대해 총괄표제부·표제부 모두 0건. PNU 오류, 미준공 건물, 또는 미등록 필지 가능성.`
+    )
+  }
+
+  // 집합건축물 = recap 있음 → 단지 단위 4 KPI 정확.
+  // 일반건축물 = recap 없음 → title 첫 row 가 답.
+  // 두 경우 모두 구조정보(strctCdNm 등) 는 title 의 **주건축물** row 에서 가져오는
+  // 게 정확. recap 에는 단지 대표 구조가 노출 안 될 수 있음.
+  const recap = recapItems[0]
+  const mainTitle =
+    titleItems.find(t => (t as any).mainAtchGbCd === '0') || // 주건축물 우선
+    titleItems[0]
+  const source: 'recap' | 'title' = recap ? 'recap' : 'title'
+  logger?.info?.(
+    `[data-go-kr] summary source=${source} recap=${recapItems.length} title=${titleItems.length} mainBldNm='${(mainTitle as any)?.bldNm || ''}'`
+  )
+
+  return { data: toSummary(recap, mainTitle, source) }
+}
+
+/**
+ * 4 KPI + 구조 정보 + 메타를 단일 객체로 추출.
+ *
+ * - 4 KPI (totArea/vlRat/grndFlrCnt/ugrndFlrCnt) : 집합이면 recap 우선, 단동이면 title.
+ * - 구조 정보 (strctCd/Nm/etcStrct) : 동 단위라 title 의 주건축물 row 에서 가져옴.
+ *   title 에 정보 없으면 recap 에서 fallback.
+ */
+function toSummary(
+  recap: BrTitleItem | undefined,
+  mainTitle: BrTitleItem | undefined,
+  source: 'recap' | 'title'
+): BuildingSummary {
+  const num = (v: any): number | null => {
+    if (v === undefined || v === null || v === '' || v === ' ') return null
+    const n = Number(v)
+    return Number.isFinite(n) ? n : null
+  }
+  const str = (v: any): string | null => {
+    if (v === undefined || v === null) return null
+    const s = String(v).trim()
+    return s ? s : null
+  }
+  // KPI 베이스 — 집합이면 recap, 아니면 title
+  const base = recap || mainTitle || ({} as BrTitleItem)
+  // 구조 — title 의 주건축물 우선, 없으면 recap
+  const structSrc = mainTitle || recap || ({} as BrTitleItem)
+
+  // 단지 차원 수치 (대지면적/건폐율/세대수/동수 등) 는 recap 에 명시. 단동이면 title.
+  return {
+    totArea: num(base.totArea),
+    platArea: num((base as any).platArea) || num((structSrc as any).platArea),
+    archArea: num((base as any).archArea) || num((structSrc as any).archArea),
+    bcRat: num((base as any).bcRat) || num((structSrc as any).bcRat),
+    vlRat: num(base.vlRat),
+    grndFlrCnt: num(base.grndFlrCnt),
+    ugrndFlrCnt: num(base.ugrndFlrCnt),
+    strctCd: str(structSrc.strctCd) || str(base.strctCd),
+    strctCdNm: str(structSrc.strctCdNm) || str(base.strctCdNm),
+    etcStrct: str((structSrc as any).etcStrct) || str((base as any).etcStrct),
+    // 주용도도 구조와 같이 title 의 주건축물 row 가 신뢰할 만함 — 단지 단위 recap
+    // 에 단일값으로 노출 안 되는 경우가 있음.
+    mainPurpsCd: str((structSrc as any).mainPurpsCd) || str((base as any).mainPurpsCd),
+    mainPurpsCdNm: str(structSrc.mainPurpsCdNm) || str(base.mainPurpsCdNm),
+    etcPurps: str((structSrc as any).etcPurps) || str((base as any).etcPurps),
+    hhldCnt: num((base as any).hhldCnt) || num((structSrc as any).hhldCnt),
+    fmlyCnt: num((base as any).fmlyCnt) || num((structSrc as any).fmlyCnt),
+    hoCnt: num((base as any).hoCnt) || num((structSrc as any).hoCnt),
+    mainBldCnt: num((base as any).mainBldCnt) || num((structSrc as any).mainBldCnt),
+    atchBldCnt: num((base as any).atchBldCnt) || num((structSrc as any).atchBldCnt),
+    heit: num((structSrc as any).heit) || num((base as any).heit),
+    bldNm: str(base.bldNm) || str(structSrc.bldNm),
+    useAprDay: str(base.useAprDay) || str(structSrc.useAprDay),
+    pmsDay: str((base as any).pmsDay) || str((structSrc as any).pmsDay),
+    stcnsDay: str((base as any).stcnsDay) || str((structSrc as any).stcnsDay),
+    source,
+    raw: base
+  }
+}
+
+function zpad(value: string, width: number): string {
+  const s = String(value)
+  return s.length >= width ? s : '0'.repeat(width - s.length) + s
+}
+
+BuildingSummaryTask.parameterSpec = [
+  {
+    type: 'string',
+    name: 'sigunguCd',
+    label: 'label.sigungu-cd',
+    placeholder: '예) 11680 또는 ${data.pnu.sigunguCd}',
+    description: '시군구코드 5자리. 이전 step 결과 액세서 사용 예: `${data.pnu.sigunguCd}`'
+  },
+  {
+    type: 'string',
+    name: 'bjdongCd',
+    label: 'label.bjdong-cd',
+    placeholder: '예) 10300 또는 ${data.pnu.bjdongCd}',
+    description: '법정동코드 5자리. 이전 step 결과 액세서 사용 예: `${data.pnu.bjdongCd}`'
+  },
+  {
+    type: 'string',
+    name: 'platGbCd',
+    label: 'label.plat-gb-cd',
+    placeholder: '0=대지, 1=산, 2=블록 — 또는 ${data.pnu.platGbCd}',
+    description: '대지구분 1자리. 정적값 0/1/2 또는 액세서 표현식.'
+  },
+  {
+    type: 'string',
+    name: 'bun',
+    label: 'label.bun',
+    placeholder: '예) 223 또는 ${data.pnu.bun}',
+    description: '본번. 자동 4자리 zero-pad. 액세서 사용 예: `${data.pnu.bun}`'
+  },
+  {
+    type: 'string',
+    name: 'ji',
+    label: 'label.ji',
+    placeholder: '예) 0 또는 ${data.pnu.ji}',
+    description: '부번. 없으면 0. 자동 4자리 zero-pad. 액세서 사용 예: `${data.pnu.ji}`'
+  }
+]
+
+BuildingSummaryTask.help = 'integration/task/building-summary'
+
+TaskRegistry.registerTaskHandler('data-go-kr-building-summary', BuildingSummaryTask)
+
+export default BuildingSummaryTask

package/logs/.5e5d741d8b7784a2fbad65eedc0fd46946aaf6f2-audit.json

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