Add building identity normalization and matching policy

Author: CJG10040

client/src/static/buildingIdentity.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import { buildBuildingIdentityIndex, buildingIdentityFromProperties, buildingRecordMatchState, matchBuildingIdentity, normalizeBuildingAddress, normalizeBuildingIdentity } from "./buildingIdentity";
+
+describe("building identity normalization", () => {
+  it("normalizes identifier formatting without converting identifiers to numbers", () => {
+    expect(normalizeBuildingIdentity(" ab-001_02 ")).toBe("AB00102");
+    expect(normalizeBuildingIdentity("0002911010100100010000")).toBe("0002911010100100010000");
+    expect(normalizeBuildingAddress("  광주광역시   동구 1-1 ")).toBe("광주광역시 동구 1-1");
+  });
+
+  it("extracts known aliases while retaining source values as strings", () => {
+    expect(buildingIdentityFromProperties({ BD_MGT_SN: "A-1", PNU: "0001", 주소: "광주 동구 1-1", GID: 12 }, "source-1")).toMatchObject({ sourceRecordId: "source-1", buildingManagementNo: "A-1", pnu: "0001", address: "광주 동구 1-1", gid: 12 });
+  });
+});
+
+describe("building identity matching", () => {
+  const masters = [
+    { masterBuildingId: "master-a", buildingManagementNo: "A-1", pnu: "0001", address: "광주 동구 1-1" },
+    { masterBuildingId: "master-b", buildingManagementNo: "B-1", pnu: "0002", address: "광주 동구 2-1" },
+  ];
+
+  it("matches one master by a strong identifier and records the evidence", () => {
+    const result = matchBuildingIdentity({ sourceRecordId: "source-a", buildingManagementNo: " a 1 " }, masters);
+    expect(result).toMatchObject({ masterBuildingId: "master-a", status: "matched", confidence: "exact", matchedFields: ["buildingManagementNo"] });
+    expect(result.matchEvidence[0]).toMatchObject({ field: "buildingManagementNo", value: "A1", masterBuildingIds: ["master-a"] });
+    expect(buildingRecordMatchState(result)).toEqual({ matchStatus: "matched", matchConfidence: "exact" });
+  });
+
+  it("does not promote an address-only match to a confirmed building", () => {
+    const result = matchBuildingIdentity({ sourceRecordId: "source-a", address: "광주 동구 1-1" }, masters);
+    expect(result).toMatchObject({ masterBuildingId: "master-a", status: "candidate", confidence: "candidate" });
+    expect(result.notes.join(" ")).toContain("geometry");
+  });
+
+  it("returns unmatched when no identifier or address is found", () => {
+    const result = matchBuildingIdentity({ sourceRecordId: "source-x", pnu: "9999", address: "광주 동구 없음" }, masters);
+    expect(result).toMatchObject({ status: "unmatched", confidence: "unknown", conflictRecordIds: [] });
+    expect(result.unmatchedFields).toContain("pnu");
+  });
+
+  it("returns conflict when identifiers point to different master buildings", () => {
+    const result = matchBuildingIdentity({ sourceRecordId: "source-conflict", buildingManagementNo: "A-1", pnu: "0002" }, masters);
+    expect(result).toMatchObject({ status: "conflict", confidence: "unknown", conflictRecordIds: ["master-a", "master-b"] });
+    expect(result.matchedFields).toEqual(["buildingManagementNo", "pnu"]);
+  });
+
+  it("treats an ambiguous address as a conflict rather than selecting arbitrarily", () => {
+    const ambiguous = [...masters, { masterBuildingId: "master-c", address: "광주 동구 1-1" }];
+    const result = matchBuildingIdentity({ sourceRecordId: "source-ambiguous", address: "광주 동구 1-1" }, ambiguous);
+    expect(result).toMatchObject({ status: "conflict", confidence: "candidate", conflictRecordIds: ["master-a", "master-c"] });
+  });
+
+  it("reuses a prebuilt index for repeated source matching", () => {
+    const index = buildBuildingIdentityIndex(masters);
+    expect(matchBuildingIdentity({ buildingManagementNo: "B-1" }, masters, index).masterBuildingId).toBe("master-b");
+  });
+});

client/src/static/buildingIdentity.ts

@@ -0,0 +1,128 @@
+export type BuildingIdentityField = "buildingManagementNo" | "bldrgstPk" | "ufid" | "pnu" | "gid" | "featureId";
+
+export type BuildingIdentityInput = {
+  sourceRecordId?: string;
+  buildingManagementNo?: unknown;
+  bldrgstPk?: unknown;
+  ufid?: unknown;
+  pnu?: unknown;
+  gid?: unknown;
+  featureId?: unknown;
+  address?: unknown;
+};
+
+export type MasterBuildingIdentity = BuildingIdentityInput & { masterBuildingId: string };
+export type BuildingMatchStatus = "matched" | "candidate" | "unmatched" | "conflict";
+export type BuildingMatchConfidence = "unknown" | "candidate" | "partial" | "strong" | "exact";
+
+export type BuildingMatchEvidence = {
+  field: BuildingIdentityField | "address";
+  value: string;
+  masterBuildingIds: string[];
+};
+
+export type BuildingMatchDecision = {
+  sourceRecordId?: string;
+  masterBuildingId?: string;
+  status: BuildingMatchStatus;
+  confidence: BuildingMatchConfidence;
+  matchedFields: BuildingIdentityField[];
+  matchEvidence: BuildingMatchEvidence[];
+  conflictRecordIds: string[];
+  unmatchedFields: BuildingIdentityField[];
+  notes: string[];
+};
+
+export const buildingIdentityPriority: BuildingIdentityField[] = ["buildingManagementNo", "bldrgstPk", "ufid", "pnu", "gid", "featureId"];
+const exactIdentityFields: BuildingIdentityField[] = ["buildingManagementNo", "bldrgstPk", "ufid"];
+
+function normalizedKey(value: unknown) {
+  if (value === undefined || value === null) return "";
+  return String(value).trim().toUpperCase().replace(/[\s_-]/g, "");
+}
+
+export function normalizeBuildingIdentity(value: unknown) {
+  return normalizedKey(value);
+}
+
+export function normalizeBuildingAddress(value: unknown) {
+  if (value === undefined || value === null) return "";
+  return String(value).trim().replace(/\s+/g, " ");
+}
+
+export function buildingIdentityFromProperties(properties: Record<string, unknown>, sourceRecordId?: string): BuildingIdentityInput {
+  const aliases: Record<BuildingIdentityField | "address", string[]> = {
+    buildingManagementNo: ["buildingManagementNo", "bd_mgt_sn", "bld_mng_no", "bldg_mng_no", "building_management_no", "건축물대장관리번호"],
+    bldrgstPk: ["bldrgst_pk", "bldrgstPk", "건축물대장pk"],
+    ufid: ["ufid", "UFID"],
+    pnu: ["pnu", "PNU"],
+    gid: ["gid", "GID"],
+    featureId: ["featureId", "feature_id", "id"],
+    address: ["address", "addr", "jibun_addr", "road_addr", "주소", "소재지"],
+  };
+  const normalizedProperties = Object.entries(properties).map(([key, value]) => [key.toLowerCase().replace(/[\s_-]/g, ""), value] as const);
+  const read = (field: keyof typeof aliases) => {
+    const keys = aliases[field].map(key => key.toLowerCase().replace(/[\s_-]/g, ""));
+    return normalizedProperties.find(([key, value]) => keys.includes(key) && String(value ?? "").trim() !== "")?.[1];
+  };
+  return { sourceRecordId, buildingManagementNo: read("buildingManagementNo"), bldrgstPk: read("bldrgstPk"), ufid: read("ufid"), pnu: read("pnu"), gid: read("gid"), featureId: read("featureId"), address: read("address") };
+}
+
+export function buildBuildingIdentityIndex(records: MasterBuildingIdentity[]) {
+  const identityIndex = new Map<string, Set<string>>();
+  const addressIndex = new Map<string, Set<string>>();
+  records.forEach(record => {
+    buildingIdentityPriority.forEach(field => {
+      const value = normalizeBuildingIdentity(record[field]);
+      if (!value) return;
+      const key = `${field}:${value}`;
+      const ids = identityIndex.get(key) ?? new Set<string>();
+      ids.add(record.masterBuildingId);
+      identityIndex.set(key, ids);
+    });
+    const address = normalizeBuildingAddress(record.address);
+    if (address) {
+      const ids = addressIndex.get(address) ?? new Set<string>();
+      ids.add(record.masterBuildingId);
+      addressIndex.set(address, ids);
+    }
+  });
+  return { identityIndex, addressIndex };
+}
+
+export function buildingRecordMatchState(decision: BuildingMatchDecision) {
+  return { matchStatus: decision.status === "matched" ? "matched" as const : decision.status, matchConfidence: decision.confidence };
+}
+
+export function matchBuildingIdentity(source: BuildingIdentityInput, masters: MasterBuildingIdentity[], indexes = buildBuildingIdentityIndex(masters)): BuildingMatchDecision {
+  const sourceFields = buildingIdentityPriority.filter(field => normalizeBuildingIdentity(source[field]));
+  const matchedByMaster = new Map<string, BuildingIdentityField[]>();
+  const evidence: BuildingMatchEvidence[] = [];
+  sourceFields.forEach(field => {
+    const value = normalizeBuildingIdentity(source[field]);
+    const ids = Array.from(indexes.identityIndex.get(`${field}:${value}`) ?? []);
+    if (!ids.length) return;
+    ids.forEach(id => matchedByMaster.set(id, [...(matchedByMaster.get(id) ?? []), field]));
+    evidence.push({ field, value, masterBuildingIds: ids });
+  });
+  const matchedIds = Array.from(matchedByMaster.keys());
+  const unmatchedFields = sourceFields.filter(field => !evidence.some(item => item.field === field));
+  if (matchedIds.length > 1) {
+    return { sourceRecordId: source.sourceRecordId, status: "conflict", confidence: "unknown", matchedFields: Array.from(new Set(matchedIds.flatMap(id => matchedByMaster.get(id) ?? []))), matchEvidence: evidence, conflictRecordIds: matchedIds, unmatchedFields, notes: ["서로 다른 식별자가 여러 master 건축물에 연결됩니다.", "어느 건축물로도 자동 확정하지 않았습니다."] };
+  }
+  if (matchedIds.length === 1) {
+    const matchedFields = matchedByMaster.get(matchedIds[0]) ?? [];
+    const exact = matchedFields.some(field => exactIdentityFields.includes(field));
+    const confidence: BuildingMatchConfidence = exact ? "exact" : matchedFields.length >= 2 ? "strong" : "partial";
+    return { sourceRecordId: source.sourceRecordId, masterBuildingId: matchedIds[0], status: "matched", confidence, matchedFields, matchEvidence: evidence, conflictRecordIds: [], unmatchedFields, notes: exact ? ["강한 건축물 식별자가 하나의 master에 정확히 일치합니다."] : ["보조 식별자로 일치했으며 주 식별자 확인이 필요합니다."] };
+  }
+  const address = normalizeBuildingAddress(source.address);
+  const addressIds = address ? Array.from(indexes.addressIndex.get(address) ?? []) : [];
+  if (addressIds.length > 1) {
+    return { sourceRecordId: source.sourceRecordId, status: "conflict", confidence: "candidate", matchedFields: [], matchEvidence: [{ field: "address", value: address, masterBuildingIds: addressIds }], conflictRecordIds: addressIds, unmatchedFields, notes: ["동일 주소에 여러 master 건축물 후보가 있어 주소만으로 확정할 수 없습니다."] };
+  }
+  if (addressIds.length === 1) {
+    return { sourceRecordId: source.sourceRecordId, masterBuildingId: addressIds[0], status: "candidate", confidence: "candidate", matchedFields: [], matchEvidence: [{ field: "address", value: address, masterBuildingIds: addressIds }], conflictRecordIds: [], unmatchedFields, notes: ["주소만 일치한 후보입니다.", "geometry 또는 주 식별자 검증 전에는 확정하지 않습니다."] };
+  }
+  return { sourceRecordId: source.sourceRecordId, status: "unmatched", confidence: "unknown", matchedFields: [], matchEvidence: [], conflictRecordIds: [], unmatchedFields, notes: ["일치하는 master 건축물을 찾지 못했습니다."] };
+}

development/TODO.md

@@ -19,7 +19,7 @@
 - [-] B-01. 현재 건축물 자료원과 QGIS 처리 방식 조사
 - [x] B-02. 거시·중간·대지·미시 조사 범위와 자료량 정책 확정
 - [x] B-03. 원본·정규화·현장관찰·분석결과 데이터 구조 확정
-- [ ] B-04. 건축물 식별자와 자료 간 결합 정책 확정
+- [x] B-04. 건축물 식별자와 자료 간 결합 정책 확정
 
 ## C. 주변 건축물 데이터 연결·정규화
 
@@ -76,3 +76,4 @@
 | 2026-08-29 | B-01 현재 건축물 자료원·QGIS 처리 방식 조사 | 완료 | 감사 문서 작성·검증 완료 | B-02·B-03에서 결합·범위 정책 설계 |
 | 2026-08-29 | B-02 거시·중간·대지·미시 조사 범위와 자료량 정책 | 완료 | 범위 정책 함수·필드 정책·테스트 통과 | B-03 데이터 구조에서 적용 |
 | 2026-08-29 | B-03 원본·정규화·현장관찰·분석결과 데이터 구조 | 완료 | 데이터 타입·프로젝트 연결·역호환 테스트 통과 | B-04 식별자 결합에서 적용 |
+| 2026-08-29 | B-04 건축물 식별자와 자료 간 결합 정책 | 완료 | 정규화·인덱스·일치·후보·충돌 테스트 통과 | C 단계 실제 원자료에서 적용 |

development/research/building-identity-matching.md

@@ -0,0 +1,139 @@
+# 건축물 식별자·자료 결합 정책
+
+작성일: 2026-08-29
+상위 작업: `development/tasks/B-04-building-identity-matching.md`
+
+## 1. 원칙
+
+서로 다른 자료의 feature를 하나의 건축물로 결합할 때, 주소·geometry·용도만으로 확정하지 않는다. 강한 식별자와 보조 식별자를 구분하고, 결합 근거와 충돌을 함께 저장한다.
+
+```text
+원본 feature
+→ 식별자 정규화
+→ master index 조회
+→ 일치·후보·미결합·충돌 판정
+→ matchEvidence 저장
+```
+
+## 2. 식별자 우선순위
+
+```text
+1. buildingManagementNo
+   bd_mgt_sn, bld_mng_no, bldg_mng_no
+
+2. bldrgstPk
+   bldrgst_pk, 건축물대장 PK
+
+3. ufid
+
+4. pnu
+
+5. gid 또는 featureId
+```
+
+주소는 별도 후보 검색에만 사용한다.
+
+## 3. 정규화
+
+### 식별자
+
+```text
+문자열 변환
+앞뒤 공백 제거
+대문자 통일
+공백·하이픈·밑줄 제거
+빈 값은 식별자로 사용하지 않음
+```
+
+PNU는 숫자로 변환하지 않는다. 앞자리 0이 사라지지 않도록 문자열로 보존한다.
+
+### 주소
+
+```text
+앞뒤 공백 제거
+연속 공백을 하나로 통합
+원본 주소와 비교용 주소를 분리
+```
+
+현재 주소 비교는 기본적인 공백 정규화만 수행한다. 도로명·지번 주소 변환은 후속 데이터 연결 작업에서 별도 검토한다.
+
+## 4. 판정 기준
+
+| 상태 | 조건 | 해석 |
+|---|---|---|
+| `matched / exact` | 관리번호·건축물대장 PK·UFID 중 하나가 하나의 master에 일치 | 자동 결합 가능 |
+| `matched / partial` | PNU·GID·feature ID 하나만 일치 | 보조 식별자 확인 필요 |
+| `matched / strong` | 보조 식별자 2개 이상이 하나의 master에 일치 | 강한 후보지만 원자료 확인 필요 |
+| `candidate / candidate` | 주소만 하나의 master에 일치 | geometry·주 식별자 검증 전 확정 금지 |
+| `unmatched / unknown` | 일치하는 식별자·주소가 없음 | 새 master 또는 자료 공백 |
+| `conflict` | 식별자가 서로 다른 master에 연결되거나 주소 후보가 여러 개 | 어느 값도 자동 확정 금지 |
+
+## 5. 충돌 처리
+
+다음 사례는 `conflict`로 저장한다.
+
+```text
+source 관리번호 → master A
+source PNU → master B
+
+같은 관리번호 → master A와 master B
+
+동일 주소 → master A와 master B
+```
+
+충돌 시 보존하는 값:
+
+```text
+conflictRecordIds
+conflictingFields
+matchEvidence
+unmatchedFields
+notes
+```
+
+## 6. 구현 파일
+
+```text
+client/src/static/buildingIdentity.ts
+client/src/static/buildingIdentity.test.ts
+```
+
+제공 함수:
+
+```text
+normalizeBuildingIdentity()
+normalizeBuildingAddress()
+buildingIdentityFromProperties()
+buildBuildingIdentityIndex()
+matchBuildingIdentity()
+buildingRecordMatchState()
+```
+
+`buildingIdentityFromProperties()`는 VWorld에서 사용될 수 있는 필드 별칭을 공통 식별자 구조로 변환한다.
+
+## 7. 현재 결합의 한계
+
+이번 단계는 결합 정책과 판정 함수만 구현했다.
+
+아직 다음은 하지 않았다.
+
+```text
+실제 API 응답별 필드 확정
+geometry overlap 기반 재검증
+건축HUB PK 변환
+주소 표준화
+용도·층수·면적 값 병합
+실제 building_master 생성
+```
+
+따라서 현재 `exact`라도 실제 자료원에서 동일 식별자의 의미를 확인하는 C 단계가 필요하다.
+
+## 8. 다음 단계 연결
+
+```text
+C-01 VWorld footprint 원자료 수집·품질검사
+C-02 용도별건물정보·건축HUB 속성자료 연결
+C-05 건축물별 통합 마스터와 결합 신뢰도 생성
+```
+
+이번 정책은 이후 실제 응답에서 확인한 필드명과 식별자 의미를 반영해 확장한다.