ipzitalk-building-age-analysis

노후도 분석

tier: L2

반경 내 K-apt 매칭 단지의 사용승인일 분포를 밴드로 나눠 지역 노후도 신호를 만든다.

입력

파라미터	필수	기본값	설명
target	✅	-	기준 주소/단지명/지역명/법정동코드
radius_m	✕	2000	후보 수집 반경
bands	✕	0-10,10-20,20-30,30+	연차 밴드
limit	✕	30	후보 수. 전수 필요 시 offset/grid 반복

필수 도구

도구	용도
resolve-site 규약	기준점 좌표·코드 확보
search_by_nearby_keyword(preset="apartment", grid=true)	후보 단지 수집
enrich_complex_info	use_approval_date, 세대수, 주차 등 1차 확보
get_complex_info	결측/상세 보강
get_map_embed_url	분포 지도 생성

워크플로우

1. 기준점 해소 — 주소/단지명은 exact, 지역/코드는 area_center 경고.
2. 후보 수집 — 반경 내 아파트 후보를 grid mode로 수집. 결과 cap이면 truncated 표기.
3. K-apt 매칭 — enrich로 사용승인일 확보. 미매칭은 제외하되 수량 표기.
4. 연차 계산 — 조회일 기준 만 연차 계산.
5. 밴드 집계 — 010년, 1020년, 20~30년, 30년+ 단지 수와 목록.
6. 연차 순위 — 오래된 순으로 표기.
   • 입력이 단지명/단지 주소이고 해당 단지가 연차 순위에 포함되면 순위표 행을 검색 기준으로 강조한다.
   • 해당 단지의 사용승인일이 결측이면, 순위표와 별도로 검색 기준 단지: 사용승인일 자료없음 카드를 표시한다.
7. 지도/출처/표본 수 — 전수/표본 여부를 명확히 표시.

데모에서 확인한 파라미터

• 입력: 방배롯데캐슬아르떼, 반경 2km
• 원천 후보: 309개 중 샘플 30개 반환 → 최종 데모 표본: K-apt 매칭/보강 8개
• 30년+ 표본: 방배임광1,2차
• 20~30년 표본: 방배1차현대, 방배2차현대홈타운, 방배디오빌, 방배브라운가
• 레이아웃 기준: templates/result.html

출력 포맷

세 블록을 전폭 세로 스택으로 쌓는다: ① 노후도 분포 → ② 지도 → ③ 연차 순위.

• 노후도 분포 바: 010 / 1020 / 20~30 / 30년+
• 밴드별 단지 수와 목록
• 지도 — 분포와 순위 사이. 전폭 카드로 단독 배치하며 2단 그리드에 넣지 않는다.
• 연차 순위 리스트
• 검색 기준 단지가 순위에 포함되면 해당 행은 강조 배경/테두리와 검색 기준 라벨을 붙인다.
• 화면 표기는 사용자용 용어만: 출처는 공동주택관리정보시스템(K-apt) · 카카오맵 · 네이버 지도.

엣지 · 실패 처리

상황	처리
후보 cap/truncated	표본 분석임을 명시. 전수 필요 시 offset/grid 반복
사용승인일 결측	밴드 제외, 결측 수 표시
미입주/예정 단지	신축 예정으로 별도 표기, 현재 노후도 분포와 분리
매칭률 낮음	결과 신뢰도 낮음 표시

필수 단서

• 노후도는 사용승인일 기준의 기계적 분포다.
• 재건축 가능성, 가격 프리미엄, 관리상태를 판단하지 않는다.
• 표본 분석이면 반드시 표본 수와 원천 후보 수를 같이 표시한다.
• 출처 표기에는 공식 명칭 공동주택관리정보시스템(K-apt)과 링크 https://www.k-apt.go.kr/web/main/index.do를 함께 표시한다.

섹션마다 출처를 작게 단다

데이터 블록 하단에 .src 한 줄. 도구·API 이름은 쓰지 않는다. 사용자가 아는 기관명만.

블록	출처 표기
단지 개요·세대수·준공·주차·연차	공동주택관리정보시스템(K-apt)
매매·전세·평당가·거래량	국토교통부 실거래가
학교·교통·생활·상권 등 장소	카카오맵
분양공고·분양가·주택형·입주월	청약홈
지도 (장소 마커)	네이버 지도 · 카카오맵
지도 (분양공고 마커)	네이버 지도 · 청약홈

• 🚨 출처 문자열은 ipzi-data JSON으로 받지 않고 템플릿 마크업에 직접 박는다. 어느 블록이 어디서 왔는지는 실행마다 달라지지 않는다. 데이터로 받으면 채우는 걸 잊거나 틀리게 쓸 여지만 생긴다.
• 🚨 한 블록에 두 출처가 섞이면 병기한다. 예: 세대수·주차 — 공동주택관리정보시스템(K-apt) · 위치 — 카카오맵. 하나로 뭉뚱그리면 어느 숫자가 어디서 왔는지 사용자가 알 수 없다.
• 🚨 쓰지 않은 기관을 출처로 적지 않는다. 우리가 부르는 곳은 위 다섯 곳뿐이다.
• 히어로·유의사항·푸터에는 달지 않는다. 데이터 블록에만.

디자인 정본

스킬 폴더 밖 문서에 의존하지 않도록 규칙을 여기 인라인으로 둔다.

• CDN·외부 폰트·이모지 금지. 아이콘은 <symbol> 인라인 + <use> 참조로 self-contained.
• 라이트/다크 양쪽. prefers-color-scheme + :root[data-theme] 모두 대응.
• 토큰만 사용: --g/--y/--o/--r/--x/--brand/--up/--down/--zebra (+ -s 배경 변형).
• 예외 상태: null은 "정보없음"(0 아님) · 표본 부족은 판정 유보 · 45건 캡 도달은 "목록 불완전" 표기.
• ★·☆는 활자 기호이며 이모지가 아니다. 등급 표기에 사용 가능.
• 지도 카드 CSS: .map{overflow-x:auto; overflow-y:hidden} + .map iframe{display:block; min-width:720px}. overflow:hidden만 주면 iframe이 카드 폭에 짓눌려 지도가 최소 줌(한반도)으로 떨어진다.
• 🚨 지도는 전폭 카드로 단독 배치한다. .g2(1.1fr/0.9fr) 우측 칸에 넣으면 카드 폭이 약 500px이 되는데, 위 min-width:720px 때문에 지도가 가로 스크롤 안으로 밀려 들어가 대부분 잘린 채 보인다. 두 규칙은 세트다 — min-width를 지키려면 지도 칸은 반드시 전폭이어야 한다. 형제 스킬(ipzitalk-parking-ranking·ipzitalk-transit-complex-ranking·ipzitalk-complex-overview)도 모두 전폭 단독 카드다.
• 🚨 푸터는 성격이 다른 4개를 각각 분리한다. <br> 하나로 이어붙이지 않는다. ① 표본 고지(.warn) → ② 표본 제외 목록(.exbox 박스) → ③ 필수 단서(.hedges) → ④ 출처(.srcline). 제외 목록은 "이 단지가 왜 빠졌나"(개별 단지의 사실)이고 필수 단서는 "이 수치를 어떻게 읽나"(해석 규약)다. 한 흐름에 섞으면 13줄짜리 제외 목록에 단서가 파묻혀, 읽는 사람이 둘을 같은 종류의 각주로 착각한다. .exbox는 표본 제외 N곳 헤더를 달고 단지명(강조)과 사유를 2열로 정렬한다.
• 🚨 지도 링크는 발급 후 7일 만료. 산출물 지도 캡션에 유효기간·재발급 필요를 반드시 적는다. 만료 시 iframe이 빈 화면이 되는데, 원인 표기가 없으면 리포트가 고장난 것처럼 보인다.
• 🚨 반경 눈금 마커를 넣지 않는다. 예전엔 fitBounds가 반경 원을 무시해 원이 잘리는 걸 막으려고 정북·남·동·서에 회색 더미 마커 4개를 심었다. 사용자에게는 정체를 알 수 없는 점으로 보여 혼란만 준다. 원이 잘리더라도 마커는 실제 장소만 찍는다. (근본 해결은 render.ts가 원을 bounds에 포함하도록 고치는 것 — 발견사항 6번)

표본 규칙

• 반경 후보가 많으면 전수가 아니라 표본이다. 표본 수와 원천 후보 수를 함께 표기한다.
• 카카오 검색은 쿼리당 45건 캡이 있다. 캡에 도달하면 "목록 불완전"으로 표기한다.

🚨 0건 과 정보없음 을 구분한다 (실측 2026-07-09)

위례 반경 3km 실측(표본 9곳):

0~10년 4 · 10~20년 5 · 20~30년 0 · 30년+ 0

20~30년·30년+ 는 진짜 0건이다(신도시 신축 밀집). 정보없음이 아니다.

• 밴드 건수 0 은 0 으로 표시한다. 비워두거나 정보없음 으로 쓰지 않는다.
• 반대로 사용승인일이 결측인 단지는 밴드 집계에서 제외하고 excluded[] 에 사유를 남긴다. 0으로 세지 않는다. 위례 실측 제외 3곳: 위례2차아이파크 · 위례스타힐스 · 위례심포니아 (K-apt 미등록/미확인).
• 밴드 경계값은 원값을 함께 보인다(예: 만 9.97년 → 0~10년 소속임을 투명하게).

🚨 enrich_complex_info 는 이름이 같은 단지도 떨어뜨린다 (실측 2026-07-10)

"K-apt 미매칭 = 그 단지가 없다"가 아니다. 좌표가 어긋나면 이름이 글자까지 같아도 제외된다.

위례2차아이파크아파트 실측 — K-apt 에 분명히 있다(A10027553 · 495세대 · 세대당 주차 1.76):

카카오 좌표  37.479738, 127.143743
K-apt 좌표   └─ 261m 떨어져 있음     ← 기본 radius_m=250 을 11m 넘긴다

radius_m	이름 완전일치 후보	이름 무관 후보(힐스테이트)	결과
250 (기본)	후보에 없음	104m	NEARBY_BUT_NAME_MISMATCH
400	0.543	0.558 ← 더 높다	NEARBY_BUT_NAME_MISMATCH
500	0.635 (임계 0.65에 0.015 부족)	0.594	LOW_CONFIDENCE_MATCH

점수가 radius_m 에 따라 움직이고, 이름 완전일치가 거리에 밀린다. 반경을 늘려도 해결되지 않는다.

• 🚨 not_found 를 "K-apt 미매칭"으로 뭉뚱그려 적지 않는다. 도구가 주는 reason 을 그대로 구분해 쓴다. NO_COMPLEX_WITHIN_RADIUS(반경 안에 후보 없음) · NEARBY_BUT_NAME_MISMATCH(후보는 있으나 이름 불일치) · LOW_CONFIDENCE_MATCH(임계 미달). 사유가 다르면 사용자가 할 일도 다르다.
• 🚨 candidates[] 에 입력과 이름이 사실상 같은 후보가 있으면 화면에 보인다. 조용히 버리면 "반경 내 전수"라고 읽힌다. 표본 수를 인용할 때 누락 가능성을 함께 적는다.
• 🚨 반대 방향 오류도 있다. 거리가 0이면 이름이 아무리 달라도 matched(score 0.75)가 난다. → 후보 좌표는 반드시 그 단지의 카카오 좌표를 넣는다. 기준 단지 좌표를 돌려쓰면 엉뚱한 단지로 바뀐다.

복구 절차 (코드 수정 없이 지금 가능)

not_found 여도 candidates[] 는 kapt_code 를 함께 준다. 반경만 넓히면 이름 완전일치 후보가 그 안에 나타난다.

1. enrich_complex_info(complexes, radius_m=500)      ← 기본 250 으로는 후보에조차 안 뜬다
2. status != "matched" 인 항목의 candidates[] 를 훑는다
3. 정규화한 이름이 입력과 같으면(공백·'아파트' 꼬리 제거 후 일치) 그 kapt_code 를 채택
4. get_complex_info(kapt_code, detail=true) 로 값을 직접 가져와 랭킹에 넣는다
5. 화면에 "좌표 불일치로 자동 매칭 실패 → 이름 일치로 복구" 를 명시한다

실측: 위례2차아이파크아파트 는 radius_m=500 에서 candidates[0] 으로 나오고(A10027553, 261m, score 0.635), get_complex_info 는 parking_per_unit 1.76 을 정상 반환한다.

• 🚨 이름이 "사실상 같다"의 기준을 느슨하게 잡지 말 것. 공백·아파트 꼬리 제거 후 완전일치만 복구한다. 위례아이파크 와 위례2차아이파크 는 다른 단지다. 애매하면 복구하지 말고 제외 사유를 적는다.
• 근본 해결은 MCP 몫이다(점수에서 반경 정규화 제거 · 이름 완전일치 가산 · 사유 코드 정정) — 발견사항 30번. 고쳐지면 이 복구 절차는 불필요해진다. 그때까지는 스킬이 직접 메운다.

MCP 도구 네임스페이스와 출처

ipzitalk MCP 도구의 네임스페이스는 실행 환경(Codex, Claude Code, Hermes, claude.ai 커넥터 등)에 따라 다르다. 이 문서에 적힌 도구 이름(search_announcement_info, get_geocode, get_map_embed_url 등)은 접두사 없는 기본 도구명(base tool name) 이다.

1. 먼저 연결된 도구 목록에서 같은 기본 도구명을 찾는다.
2. 그중 ipzitalk-remote 플러그인의 ipzitalk 서버 provenance가 확인되는 도구만 우선 사용한다. Codex에서는 실제 도구 호출 이벤트의 server: ipzitalk과 기본 도구명을 기준으로 확인한다.
3. presale-mcp 또는 다른 로컬 MCP provenance의 동명 도구는 Remote Skill의 대체 수단으로 사용하지 않는다.
4. provenance를 확인할 수 없거나 같은 기본 도구명이 여러 서버에 있어 모호하면 임의 선택하지 말고 중단하여 필요한 Remote 도구명을 안내한다.

클라이언트가 연결 도구 목록에 plugin/server provenance를 구조적으로 제공하지 않을 때만 다음 명시적 fallback을 사용한다.

1. mcp__plugin_ipzitalk-remote_ipzitalk__<도구명>
2. mcp__ipzitalk_mcp__<도구명>
3. mcp__ipzitalk__<도구명>
4. mcp__claude_ai_ipzitalk__<도구명>

fallback으로도 Remote 출처를 유일하게 확인할 수 없으면 값을 추정하지 말고, 사용자에게 ipzitalk Remote MCP 연결 상태를 확인하도록 안내한 뒤 중단한다.