Add VWorld building footprint quality audit

Author: CJG10040

client/src/static/buildingFootprintQuality.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { auditBuildingFootprints, isUsableBuildingFootprint, usableBuildingFootprintFeatures } from "./buildingFootprintQuality";
+import type { VworldWfsFeature } from "./vworld";
+
+const polygon = (id: string, managementNo?: string): VworldWfsFeature => ({ id, geometry: { type: "Polygon", coordinates: [[[126.9, 35.1], [126.901, 35.1], [126.901, 35.101], [126.9, 35.1]]] }, properties: managementNo ? { BD_MGT_SN: managementNo, USE: "주거" } : { USE: "미확인" } });
+
+describe("building footprint quality", () => {
+  it("accepts valid polygon and multipolygon footprints only", () => {
+    expect(isUsableBuildingFootprint(polygon("b-1").geometry)).toBe(true);
+    expect(isUsableBuildingFootprint({ type: "MultiPolygon", coordinates: [[[[126.9, 35.1], [126.901, 35.1], [126.901, 35.101], [126.9, 35.1]]]] })).toBe(true);
+    expect(isUsableBuildingFootprint({ type: "Point", coordinates: [126.9, 35.1] })).toBe(false);
+    expect(isUsableBuildingFootprint({ type: "Polygon", coordinates: [[[126.9, 35.1], [126.9, 35.1]]] })).toBe(false);
+  });
+
+  it("counts invalid geometry and missing identities without deleting source features", () => {
+    const features = [polygon("b-1", "A-1"), polygon("b-2"), { id: "point-1", geometry: { type: "Point", coordinates: [126.9, 35.1] }, properties: {} } as VworldWfsFeature];
+    const quality = auditBuildingFootprints(features);
+    expect(quality).toMatchObject({ totalFeatures: 3, polygonFeatures: 2, usablePolygonFeatures: 2, invalidGeometryCount: 1, missingIdentityCount: 2 });
+    expect(usableBuildingFootprintFeatures(features)).toHaveLength(2);
+  });
+
+  it("reports duplicate identity and geometry groups separately", () => {
+    const features = [polygon("b-1", "A-1"), { ...polygon("b-2", "A-1"), geometry: { type: "Polygon", coordinates: [[[126.91, 35.1], [126.911, 35.1], [126.911, 35.101], [126.91, 35.1]]] } }, polygon("b-3", "B-1"), { ...polygon("b-4", "B-1") }];
+    const quality = auditBuildingFootprints(features);
+    expect(quality.duplicateIdentityGroups).toEqual(expect.arrayContaining([expect.objectContaining({ key: "buildingManagementNo:A1", count: 2 }), expect.objectContaining({ key: "buildingManagementNo:B1", count: 2 })]));
+    expect(quality.duplicateIdentityFeatureCount).toBe(4);
+    expect(quality.duplicateGeometryCount).toBe(3);
+  });
+
+  it("returns field names and geometry types for source diagnostics", () => {
+    const quality = auditBuildingFootprints([polygon("b-1", "A-1"), { id: "point-1", geometry: { type: "Point", coordinates: [126.9, 35.1] }, properties: { HEIGHT: 12 } }]);
+    expect(quality.propertyFieldNames).toEqual(["BD_MGT_SN", "HEIGHT", "USE"]);
+    expect(quality.geometryTypes).toEqual(["Point", "Polygon"]);
+  });
+});

client/src/static/buildingFootprintQuality.ts

@@ -0,0 +1,91 @@
+import { buildingIdentityFromProperties, normalizeBuildingIdentity, type BuildingIdentityField } from "./buildingIdentity";
+import type { SpatialGeometry } from "./model";
+import type { VworldWfsFeature } from "./vworld";
+
+export type BuildingFootprintDuplicateGroup = {
+  key: string;
+  featureIds: string[];
+  count: number;
+};
+
+export type BuildingFootprintQuality = {
+  totalFeatures: number;
+  polygonFeatures: number;
+  usablePolygonFeatures: number;
+  invalidGeometryCount: number;
+  missingIdentityCount: number;
+  duplicateIdentityGroups: BuildingFootprintDuplicateGroup[];
+  duplicateIdentityFeatureCount: number;
+  duplicateGeometryCount: number;
+  propertyFieldNames: string[];
+  geometryTypes: string[];
+};
+
+const identityFields: BuildingIdentityField[] = ["buildingManagementNo", "bldrgstPk", "ufid", "pnu", "gid", "featureId"];
+
+function coordinatePair(value: unknown): value is [number, number] {
+  return Array.isArray(value) && value.length >= 2 && Number.isFinite(Number(value[0])) && Number.isFinite(Number(value[1]));
+}
+
+function validRing(value: unknown) {
+  if (!Array.isArray(value) || value.length < 3) return false;
+  const points = value.filter(coordinatePair);
+  return points.length >= 3 && new Set(points.map(point => `${Number(point[0]).toFixed(7)},${Number(point[1]).toFixed(7)}`)).size >= 3;
+}
+
+export function isUsableBuildingFootprint(geometry?: SpatialGeometry) {
+  if (!geometry || !Array.isArray(geometry.coordinates)) return false;
+  if (geometry.type === "Polygon") return validRing(geometry.coordinates[0]);
+  if (geometry.type === "MultiPolygon") return geometry.coordinates.some(polygon => Array.isArray(polygon) && validRing(polygon[0]));
+  return false;
+}
+
+function identityKey(feature: VworldWfsFeature) {
+  const identity = buildingIdentityFromProperties(feature.properties, feature.id);
+  for (const field of identityFields) {
+    const value = normalizeBuildingIdentity(identity[field]);
+    if (value) return `${field}:${value}`;
+  }
+  return "";
+}
+
+function featureId(feature: VworldWfsFeature, index: number) {
+  return feature.id?.trim() || `feature-${index + 1}`;
+}
+
+function geometryKey(geometry?: SpatialGeometry) {
+  if (!geometry || !Array.isArray(geometry.coordinates)) return "";
+  const round = (value: unknown): unknown => Array.isArray(value) ? value.map(round) : typeof value === "number" ? Number(value.toFixed(7)) : value;
+  return `${geometry.type}:${JSON.stringify(round(geometry.coordinates))}`;
+}
+
+export function auditBuildingFootprints(features: VworldWfsFeature[]): BuildingFootprintQuality {
+  const duplicateIdentityMap = new Map<string, string[]>();
+  const duplicateGeometryMap = new Map<string, string[]>();
+  const fields = new Set<string>();
+  const geometryTypes = new Set<string>();
+  let polygonFeatures = 0;
+  let usablePolygonFeatures = 0;
+  let invalidGeometryCount = 0;
+  let missingIdentityCount = 0;
+  features.forEach((feature, index) => {
+    Object.keys(feature.properties).forEach(field => fields.add(field));
+    if (feature.geometry?.type) geometryTypes.add(feature.geometry.type);
+    const isPolygon = feature.geometry?.type === "Polygon" || feature.geometry?.type === "MultiPolygon";
+    if (isPolygon) polygonFeatures += 1;
+    if (isUsableBuildingFootprint(feature.geometry)) usablePolygonFeatures += 1;
+    else invalidGeometryCount += 1;
+    const idKey = identityKey(feature);
+    if (!idKey) missingIdentityCount += 1;
+    else duplicateIdentityMap.set(idKey, [...(duplicateIdentityMap.get(idKey) ?? []), featureId(feature, index)]);
+    const shapeKey = geometryKey(feature.geometry);
+    if (shapeKey) duplicateGeometryMap.set(shapeKey, [...(duplicateGeometryMap.get(shapeKey) ?? []), featureId(feature, index)]);
+  });
+  const duplicateIdentityGroups = Array.from(duplicateIdentityMap.entries()).filter(([, ids]) => ids.length > 1).map(([key, ids]) => ({ key, featureIds: ids, count: ids.length }));
+  const duplicateGeometryGroups = Array.from(duplicateGeometryMap.values()).filter(ids => ids.length > 1);
+  return { totalFeatures: features.length, polygonFeatures, usablePolygonFeatures, invalidGeometryCount, missingIdentityCount, duplicateIdentityGroups, duplicateIdentityFeatureCount: duplicateIdentityGroups.reduce((sum, group) => sum + group.count, 0), duplicateGeometryCount: duplicateGeometryGroups.reduce((sum, ids) => sum + ids.length, 0), propertyFieldNames: Array.from(fields).sort(), geometryTypes: Array.from(geometryTypes).sort() };
+}
+
+export function usableBuildingFootprintFeatures(features: VworldWfsFeature[]) {
+  return features.filter(feature => isUsableBuildingFootprint(feature.geometry));
+}

client/src/static/research.ts

@@ -1,5 +1,6 @@
 import type { PublicServiceSettings, ResearchNote, SiteRecord } from "./model";
 import { enrichVworldParcelCandidates, fetchVworldBrowserParcel, fetchVworldBuildingUseWfs, fetchVworldDataFeatures, fetchVworldWfs, mergeBuildingUseFeatures } from "./vworld";
+import { auditBuildingFootprints } from "./buildingFootprintQuality";
 import { fetchOsmHydrology, osmHydrologyQuery } from "./osm";
 
 export type SourceId = "terrain" | "air" | "vworldParcel" | "cityParks" | "vworldBuildings" | "vworldRoads" | "vworldZoning" | "landRegulation" | "vworldWelfare" | "vworldTransit" | "vworldBusiness" | "vworldCulture" | "sgisPopulation" | "sgisBusiness" | "osmHydrology";
@@ -111,6 +112,7 @@ export async function collectSource(source: SourceDefinition, site: SiteRecord,
   if (source.id === "vworldBuildings" || source.id === "vworldRoads") {
     const typename = source.id === "vworldBuildings" ? "lt_c_spbd" : "lt_l_moctlink";
     const result = await fetchVworldWfs({ key: settings.vworldKey, domain: settings.vworldDomain, typename, latitude: site.latitude, longitude: site.longitude, radiusMeters: siteRadius(radiusMeters) });
+    const footprintQuality = source.id === "vworldBuildings" ? auditBuildingFootprints(result.features) : undefined;
     let features = result.features;
     let useFeatures = [] as typeof result.features;
     let useStatus = "";
@@ -120,7 +122,8 @@ export async function collectSource(source: SourceDefinition, site: SiteRecord,
     }
     const propertyNames = Array.from(new Set(features.flatMap(feature => Object.keys(feature.properties)))).slice(0, 16).join(", ");
     const spatialFeatures = features.filter(feature => feature.geometry).slice(0, 300).map((feature, index) => ({ id: feature.id ?? `${source.id}-${index + 1}`, geometry: feature.geometry!, properties: feature.properties }));
-    const record = note(source.source, source.title, `조사 반경 ${siteRadius(radiusMeters)}m 내 WFS 객체 ${features.length.toLocaleString("ko-KR")}개. 지도에는 공간자료 ${spatialFeatures.length.toLocaleString("ko-KR")}개를 표시합니다. 속성 표본: ${propertyNames || "응답 속성 없음"}. ${useStatus ? `${useStatus}. ` : ""}${source.limitation}`, source.id === "vworldBuildings" ? "https://www.data.go.kr/data/15123458/openapi.do" : "https://www.its.go.kr/nodelink/", { latitude: site.latitude, longitude: site.longitude }, { catalogId: source.catalogId, detail: `footprint WFS 원본 feature의 속성·geometry 상세입니다.\n${JSON.stringify(features, null, 2)}${useFeatures.length ? `\n\n용도별건물정보 WFS 원본 feature입니다.\n${JSON.stringify(useFeatures, null, 2)}` : ""}`, ...serializeDetail({ footprint: features, buildingUse: useFeatures, useStatus }) });
+    const qualitySummary = footprintQuality ? ` 유효 footprint ${footprintQuality.usablePolygonFeatures.toLocaleString("ko-KR")}개, geometry 오류 ${footprintQuality.invalidGeometryCount.toLocaleString("ko-KR")}개, 식별자 누락 ${footprintQuality.missingIdentityCount.toLocaleString("ko-KR")}개, 식별자 중복 그룹 ${footprintQuality.duplicateIdentityGroups.length.toLocaleString("ko-KR")}개입니다.` : "";
+    const record = note(source.source, source.title, `조사 반경 ${siteRadius(radiusMeters)}m 내 WFS 객체 ${features.length.toLocaleString("ko-KR")}개. 지도에는 공간자료 ${spatialFeatures.length.toLocaleString("ko-KR")}개를 표시합니다.${qualitySummary} 속성 표본: ${propertyNames || "응답 속성 없음"}. ${useStatus ? `${useStatus}. ` : ""}${source.limitation}`, source.id === "vworldBuildings" ? "https://www.data.go.kr/data/15123458/openapi.do" : "https://www.its.go.kr/nodelink/", { latitude: site.latitude, longitude: site.longitude }, { catalogId: source.catalogId, detail: `footprint WFS 원본 feature의 속성·geometry 상세입니다.\n${JSON.stringify(features, null, 2)}${useFeatures.length ? `\n\n용도별건물정보 WFS 원본 feature입니다.\n${JSON.stringify(useFeatures, null, 2)}` : ""}`, ...serializeDetail({ footprint: features, footprintQuality, buildingUse: useFeatures, useStatus }) });
     record.spatialLayer = { id: source.id, title: source.title, source: source.source, fetchedAt: record.createdAt, features: spatialFeatures, totalFeatureCount: result.features.length, truncated: result.features.length > spatialFeatures.length };
     return record;
   }

development/TODO.md

@@ -23,7 +23,7 @@
 
 ## C. 주변 건축물 데이터 연결·정규화
 
-- [ ] C-01. VWorld footprint 원자료 수집·보존·품질검사
+- [x] C-01. VWorld footprint 원자료 수집·보존·품질검사
 - [ ] C-02. 용도별건물정보·건축HUB 속성자료 연결
 - [ ] C-03. 건축인허가·사용승인·폐쇄말소·건축연도 자료 연결
 - [ ] C-04. 높이·층수·면적·구조·용도 필드 정규화
@@ -77,3 +77,4 @@
 | 2026-08-29 | B-02 거시·중간·대지·미시 조사 범위와 자료량 정책 | 완료 | 범위 정책 함수·필드 정책·테스트 통과 | B-03 데이터 구조에서 적용 |
 | 2026-08-29 | B-03 원본·정규화·현장관찰·분석결과 데이터 구조 | 완료 | 데이터 타입·프로젝트 연결·역호환 테스트 통과 | B-04 식별자 결합에서 적용 |
 | 2026-08-29 | B-04 건축물 식별자와 자료 간 결합 정책 | 완료 | 정규화·인덱스·일치·후보·충돌 테스트 통과 | C 단계 실제 원자료에서 적용 |
+| 2026-08-29 | C-01 VWorld footprint 원자료 수집·보존·품질검사 | 완료 | 품질 요약·유효 geometry·중복·누락 테스트 통과 | C-02 속성자료 연결에서 적용 |

development/research/building-footprint-quality.md

@@ -0,0 +1,144 @@
+# VWorld 건축물 footprint 품질검사 정책
+
+작성일: 2026-08-29
+상위 작업: `development/tasks/C-01-building-footprint-quality.md`
+
+## 1. 목적
+
+VWorld `lt_c_spbd` 등 건축물 footprint 응답을 분석하기 전에 유효 geometry·식별자·중복·필드 목록을 진단한다.
+
+```text
+원자료 전체
+→ 품질 요약
+→ 유효 footprint 분석 후보
+→ 지도 표시·공간분석
+```
+
+품질검사에서 제외된 feature도 원자료에서는 삭제하지 않는다.
+
+## 2. 유효 footprint
+
+분석 가능한 footprint는 다음 조건을 만족해야 한다.
+
+```text
+Polygon 또는 MultiPolygon
+외곽 ring에 유효 좌표 3개 이상
+서로 다른 좌표 3개 이상
+```
+
+다음 feature는 footprint 분석 후보에서 제외한다.
+
+```text
+geometry 없음
+Point
+LineString
+좌표 부족
+좌표가 모두 동일
+```
+
+단, 제외 feature의 원본 속성과 geometry는 보존한다.
+
+## 3. 품질 요약
+
+```text
+totalFeatures
+polygonFeatures
+usablePolygonFeatures
+invalidGeometryCount
+missingIdentityCount
+duplicateIdentityGroups
+duplicateIdentityFeatureCount
+duplicateGeometryCount
+propertyFieldNames
+geometryTypes
+```
+
+이 값은 실제 건축물 부재를 의미하지 않는다. API 오류·CORS 실패·빈 응답은 품질 요약에 넣지 않고 별도 수집 상태로 기록해야 한다.
+
+## 4. 식별자 진단
+
+B-04 결합 정책의 별칭을 사용한다.
+
+```text
+buildingManagementNo
+bd_mgt_sn
+bld_mng_no
+bldg_mng_no
+bldrgst_pk
+UFID
+PNU
+GID
+feature id
+```
+
+feature ID만 있는 경우 내부 feature 식별자로 보관하며, 건축물관리번호로 해석하지 않는다.
+
+## 5. 중복 진단
+
+### 식별자 중복
+
+동일 정규화 식별자가 여러 feature에 나타나는 경우 중복 그룹으로 기록한다.
+
+```text
+원본 feature 모두 보존
+중복 그룹 ID 기록
+속성·geometry·기준일 비교 대상으로 전달
+자동 삭제하지 않음
+```
+
+### geometry 중복
+
+좌표를 소수점 7자리로 정규화했을 때 동일한 geometry가 여러 feature에 나타나는 경우 geometry 중복 후보로 기록한다.
+
+geometry가 같아도 다음이 다를 수 있으므로 자동 삭제하지 않는다.
+
+```text
+출처
+기준일
+식별자
+속성
+자료 갱신 상태
+```
+
+## 6. 지도 표시와 분석 보존 구분
+
+```text
+전체 원자료
+: 품질검사 결과와 함께 프로젝트에 보존
+
+유효 분석 후보
+: Polygon·MultiPolygon 조건을 통과한 feature
+
+지도 표시
+: 성능을 위해 최대 300개까지 제한 가능
+
+통계·공간분석
+: 지도 표시 300개가 아니라 전체 유효 분석 후보 기준
+```
+
+따라서 지도에 300개만 표시되었다고 전체 건축물이 300개라는 의미가 아니다.
+
+## 7. 구현 파일
+
+```text
+client/src/static/buildingFootprintQuality.ts
+client/src/static/buildingFootprintQuality.test.ts
+```
+
+제공 함수:
+
+```text
+isUsableBuildingFootprint()
+auditBuildingFootprints()
+usableBuildingFootprintFeatures()
+```
+
+## 8. 다음 작업에서 사용할 것
+
+```text
+C-02 용도별건물정보·건축HUB 속성자료 연결
+C-05 건축물별 통합 마스터와 결합 신뢰도 생성
+D-01~D-05 범위별 건축물 분석
+```
+
+품질 요약의 중복·누락·geometry 상태는 이후 결합 신뢰도와 AI 입력의 데이터 한계에 전달한다.