어디살지 — 주소·건축물 증강 파이프라인 개선 설계서

1. 진단 (실측 결과 정정)

2. 개선 작업 마스터 매트릭스

3. 코드 개선 — building_registry_adapter

(N2.1) JUSO 1차 + Kakao b_code 폴백 정식화

# 현재 (dead path on E0014)
async def _search_address(self, address):
    response = await self._juso_client.get(self.JUSO_API_URL, params={...})
    if common.get("errorCode") != "0": return None
    ...

# 개선 (폴백 내장)
async def _search_address(self, address):
    parsed = await self._try_juso(address)
    if parsed is None:
        parsed = await self._try_kakao_bcode(address)
    return parsed

async def _try_juso(self, address): ...
async def _try_kakao_bcode(self, address):
    resp = await self._kakao_client.get(
        "https://dapi.kakao.com/v2/local/search/address.json",
        params={"query": address},
        headers={"Authorization": f"KakaoAK {self._kakao_api_key}"},
    )
    docs = resp.data.get("documents", [])
    if not docs: return None
    addr = docs[0].get("address") or {}
    b_code = addr.get("b_code", "")
    if len(b_code) < 10: return None
    return {
        "sigunguCd": b_code[:5],
        "bjdongCd": b_code[5:10],
        "bun": (addr.get("main_address_no") or "0").zfill(4),
        "ji":  (addr.get("sub_address_no")  or "0").zfill(4),
    }

(N2.2) 총괄표제부 머지 — 주차·대지·건폐·용적 회복

async def get_building_info(self, address):
    ...
    title = await self._get_building_data(...)         # getBrTitleInfo
    recap = await self._get_recap_data(sigungu, bjdong, bun, ji)
    merged = {**(recap or {}), **title}                 # 표제부 우선, 총괄로 보강
    return Ok(self._parse_building_info(merged, units, ...))

async def _get_recap_data(self, sigungu, bjdong, bun, ji):
    # getBrRecapTitleInfo — platArea·bcRat·vlRat·indrMechUtcnt 등 채움
    response = await self._building_client.get(
        "https://apis.data.go.kr/1613000/BldRgstHubService/getBrRecapTitleInfo",
        params={"serviceKey": self._data_go_kr_api_key, ...},
    )
    items = response.data.get("response", {}).get("body", {}).get("items", {})
    item = items.get("item", [])
    if isinstance(item, dict): item = [item]
    return item[0] if item else None

(N2.3) 용도구역 파싱

async def _get_land_use_zone(...):
    ...
    land_use_district = None
    land_use_district = None
    for item in item_list:
        if item.get("jijiguGbCd") == "2" or item.get("jijiguGbCdNm") == "용도구역코드":
            v = (item.get("jijiguCdNm") or "").strip()
            if v: land_use_district = v; break
    return zone, land_use_district  # 반환 시그니처 변경

4. Infisical 작업 (N1.1 ~ N1.3)

N1.1 — JUSO 운영키 갱신 (3개 env)

# 활용신청 후 발급된 새 키를 모든 환경에 동기화
NEW_KEY="prodUxxx..."  # 운영키 (prod 접두)
PRJ=c08a58ef-000b-409d-a6f1-5bde4e3e84eb
PATH=/ai-real-estate-backend

for env in local alpha beta; do
  infisical secrets set "JUSO_API_KEY=$NEW_KEY" \
    --env=$env --path=$PATH --projectId=$PRJ
done

N1.2 — local 폴더 채우기

현재 /ai-real-estate-backend local 폴더는 0건. 운영자가 alpha 값 export → local import 한 번만 수행하면 됨.

infisical export --env=alpha --path=/ai-real-estate-backend \
  --projectId=$PRJ > /tmp/alpha.env
infisical import /tmp/alpha.env --env=local --path=/ai-real-estate-backend \
  --projectId=$PRJ
rm /tmp/alpha.env  # 평문 시크릿 즉시 삭제

신규 등록 권장 키 (N2.4 / N2.5 의존)

5. 테스트 정비

• N3.1 test_building_registry_live.py: _resolve_via_kakao 폴백 함수와 _kakao_resolve_to_bcode monkey-patch 제거 → JUSO 정상 경로만 검증. 운영키 후 JUSO 그대로 동작하면 폴백 코드는 어댑터에 있어도 호출 안 됨.
• N3.2 새 회귀 테스트 test_building_info_field_coverage.py — 가정동 277 로 호출 후 build_year·total_area·main_purpose·floors·structure· building_area·land_area(N2.2)·coverage_ratio(N2.2)·floor_area_ratio(N2.2)· parking.total_count(N2.2)·land_use_zone·land_use_district(N2.3) 12 핵심 필드 모두 not-None 확인.
• N3.3 CodeRabbit 리뷰 통과 후 main 머지 (이번부터 --admin 우회 금지)

6. 운영 모니터링 (N4.1)

# ResilientHttpClient 에 hook 추가
async def _on_response(self, response):
    body = response.json() if "application/json" in response.headers.get("content-type", "") else {}
    err = body.get("results", {}).get("common", {}).get("errorCode")
    if err and err != "0":
        sentry_sdk.capture_message(
            f"[{self._service_name}] errorCode={err}",
            level="warning",
            extras={"endpoint": str(response.url), "body": body},
        )
        await self._slack_alert(f":warning: {self._service_name} {err}")

같은 hook 으로 일별 호출량 카운터를 Redis INCR 로 집계 → Grafana datasource (N4.2).

7. 실행 타임라인

Critical Path = N0.1(JUSO 신청 대기 1-3d) — 그 외 코드 작업은 모두 병렬화 가능. 운영키 받기 전에도 어댑터 폴백 PR(N2.1)은 작성·머지 가능 → 발급 즉시 무중단 전환.

8. 위험 / 완화

9. 완료 지표

참고

• 실측 검증 결과: field-validation-live.pages.dev
• 필드 카탈로그 38종: property-enrichment-fields.pages.dev
• 건축물대장 totalCount 검증: building-registry-report.pages.dev
• 증강 전략 분석: address-augmentation-strategy.pages.dev
• JUSO 활용신청: business.juso.go.kr
• data.go.kr 1613000: openapi.do
• data.go.kr 15057511 (RTMS): openapi.do