ipzitalk-announcement-search

모집공고 검색 (ipzitalk-announcement-search)

tier: L1

지역/주소/단지명 하나로 청약홈 적재 분양공고 전량을 표와 지도로 훑는다. ※ 데이터 = 청약홈 분양정보 적재분만(실시간 청약홈 아님). 경쟁률·신청/당첨·접수일정 없음(공고일·입주월만). ※ 분양가 = 주택형별 최고가(평균 아님).

입력 (영역형 — 지역/주소/단지명/코드 아무거나 1개)

파라미터	필수	기본	설명
query(자유형)	✅	-	지역명·주소·단지명·법정동코드 중 1개. 입력 해소 1단계에서 표준화.
radius_km	✕	5	좌표(주소·단지) 검색 시 반경(0.1~20)
date_from/date_to	✕	-	모집공고일 YYYY-MM-DD
move_in_from/move_in_to	✕	-	입주예정월 YYYY-MM
exclusive_area_sqm	✕	-	전용면적 필터(주택형 파싱값 ±1㎡)
include_units	✕	true	주택형·분양가 JOIN
limit / offset	✕	30 / 0	페이지네이션(limit 최대 100)

⚠️ raw 입력을 지역 필터에 바로 꽂지 말 것. 지역 필터는 정확 일치라 "김포"→0건("김포시"만 매칭). 반드시 지역코드 정규화로 "○○시" 정확명을 얻어 사용한다. 매핑: 지역명은 정확명 또는 좌표+radius_km, 주소·단지명은 좌표+radius_km, 세부동은 읍면동 필터. 좁히는 필터 없이 호출하면 과광범위 오류.

워크플로우 (검증됨 · 김포시 2026-07-09)

1. 입력 해소 — 자유형 입력 1개 → 표준 번들(좌표·지역코드):
   • 지역명("김포"·"경기 김포") → 지역코드 정규화 → "김포시"+코드+좌표. raw명을 지역 필터에 바로 넣지 말 것(정확 일치라 "김포"→0건 실증).
   • 주소 → 지오코딩 → 좌표 → 좌표+radius_km.
   • 단지명 → 주소검색(주거시설 우선) → 좌표 → 반경. 후보 다수면 선택.
   • 법정동코드 → 지역코드 정규화 → 시군구/좌표.
   • 정밀도: 주소·단지=exact / 지역·코드=중심 근사(반경 검색 정상).
2. 공고 조회 — 필터 + 주택형(units) 포함, limit=100, offset=0. 더 있으면 다음 offset으로 이어 조회(전량 수집).
3. 🚨 미측위 좌표 보완(핵심) — 좌표가 비었다고 바로 "위치 확인 필요"로 넘기지 말 것. 주소에서 지번(예: 사우동 527-1) 파싱 → 지오코딩 → confidence exact면 "주소 보완좌표"로 사용. 실패 시 단지명 주소검색. 둘 다 실패해야만 위치 미상. → 실증: 김포 사우동 4건(호반써밋 풍무Ⅱ·수자인 그라센트 1·2차·B5블록 호반써밋) 전부 exact 좌표 복구 → 위치 확인 필요 0건.
4. 지도 — located+보완 전량을 마커로 지도 발급(DB좌표 파랑 #2563eb · 보완좌표 주황 #e56f1f). 반환 URL을 ipzi-data.mapUrl.
5. 렌더 — 고정 템플릿 templates/result.html에 ipzi-data JSON 주입. 표는 listings[].units[]로 rowspan 자동 병합.

재사용 로직 (메커니즘)

• 입력 해소: 자유형 입력 1개 → 표준 번들(좌표·지역코드). 모든 스킬 1단계 · 입력 유연성의 핵심.
• 좌표 보완(3단계): DB좌표 → 주소 지번 지오코딩 → 단지명 주소검색.
• 출처 라벨 매핑: 화면에는 내부 테이블명이 아니라 사용자 표시 문구를 쓴다 — 분양공고=「청약홈」, 주택형=「청약홈」, 실거래=「국토교통부 실거래가」, 관리정보=「공동주택관리정보시스템(K-apt)」, 지도=「네이버 지도」. 내부 테이블명 HTML 노출 금지.
• 카카오 검색 계열은 「카카오 로컬 API」로 표기.

섹션마다 출처를 작게 단다

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

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

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

디자인 정본 (템플릿에 인라인)

산출물 HTML은 스킬 폴더 밖 문서에 의존하지 않는다. 규칙은 templates/result.html에 인라인돼 있다.

• CDN·외부 폰트·이모지 금지. 아이콘은 <symbol> 인라인 + <use> 참조로 self-contained. ICONS 화이트리스트에 없는 id는 렌더하지 않고 console.warn.
• 라이트/다크 양쪽: prefers-color-scheme + :root[data-theme] 모두 대응.
• 토큰만 사용: --bg --card --ink --sub --line --chip --g --y --o --r --x --brand(+ -s 배경 변형) · --mono.
• ★·☆는 활자 기호이며 이모지가 아니다.
• 결측 셀은 정보없음(0으로 채우지 않는다). 값 추정 금지.
• 분양가는 주택형별 최고가 기준 — priceNote를 항상 표기한다.
• 🚨 반경 눈금 마커를 넣지 않는다. 예전엔 fitBounds가 반경 원을 무시해 원이 잘리는 걸 막으려고 정북·남·동·서에 회색 더미 마커 4개를 심었다. 사용자에게는 정체를 알 수 없는 점으로 보여 혼란만 준다. 원이 잘리더라도 마커는 실제 장소만 찍는다. (근본 해결은 render.ts가 원을 bounds에 포함하도록 고치는 것 — 발견사항 6번)
• 지도: mapUrl이 null이면 지도 패널을 숨긴다. 지도 링크는 발급 후 7일간 유효하므로 캡션에 유효기간을 적는다.
• 실행마다 바뀌는 것은 ipzi-data 비실행 JSON 블록 하나뿐 — 마크업·CSS·렌더 JS는 고정.

출력 포맷

• 채팅(먼저): 지역·공고수·총공급·84㎡ 최고가 중위·상한제 비율 요약 + 최근 공고 md 표.
• HTML(선택): 히어로 → KPI 4 → 지도 iframe → 최근 공고순 카드 → 주택형 비교표(rowspan) → 출처·hedge 푸터.
  • 레이아웃 기준: templates/result.html
  • ipzi-data JSON: title/desc/chips/kpis/mapUrl/unlocated/listings(units[])/priceNote/footNote/sourceNote.

필수 단서 · 금지 표현

• 필수: 청약홈 적재 기준일 · 분양가=주택형 최고가(평균 아님) · 주소 보완좌표 표기 · 경쟁률/신청·당첨/접수일정 미포함 · 직선거리(반경형).
• 금지: 내부 테이블명 HTML 노출 · 최고가를 평균가처럼 제시 · 실시간 청약홈처럼 단정 · 적정분양가 판단(=분양가 검증 스킬 몫).

엣지 · 실패 처리

상황	처리
필터 없음 → 과광범위	지역/주소/단지명/좌표 좁히도록 안내
더 있음(has_more)	다음 offset으로 이어 조회(전량 수집)
좌표 null	지오코딩→단지명 주소검색 보완 후에만 위치 미상 판정
주택형 0건	공고만 표시, 분양가 "-"(지어내지 않음)
적재 0건	"적재된 분양공고 없음(실시간 아님)" 명시

검증된 사항 (김포시 · 조회 2026-07-09)

• 지역 정확명 조회 + 주택형 포함: matched 18건 전량, 4건 미측위.
• 좌표 보완: 사우동 4개 지번(527-1/167-1/173-1/475-2) 전부 confidence=exact → 위치 확인 필요 0건.
• 지도 18마커 발급(만료 7일).
• 렌더: rowspan 병합·억 포맷 정확(84A 71,000만 → 7.10억). 브라우저 렌더 확인.
• KPI: 18건 · 총공급 13,969 · 84㎡ 최고가 중위 6.92억 · 상한제 10/18.