| name | ipzitalk-announcement-search |
| description | 지역(시군구/읍면동)·주소·반경·단지명 중 하나로 청약홈 적재 분양공고를 조회해 단지·주택형·최고분양가·공급세대·입주월·상한제·원문링크를 표와 지도로 정리한다. "모집공고 검색", "이 지역 분양공고 찾아줘", "OO 청약공고", "분양공고 목록", "이 APT 모집공고" 등의 표현이 있으면 이 스킬을 사용한다.
|
| version | 1.0.0 |
| license | proprietary |
모집공고 검색 (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개 → 표준 번들(좌표·지역코드):
- 지역명("김포"·"경기 김포") → 지역코드 정규화 → "김포시"+코드+좌표. raw명을 지역 필터에 바로 넣지 말 것(정확 일치라 "김포"→0건 실증).
- 주소 → 지오코딩 → 좌표 → 좌표+
radius_km.
- 단지명 → 주소검색(주거시설 우선) → 좌표 → 반경. 후보 다수면 선택.
- 법정동코드 → 지역코드 정규화 → 시군구/좌표.
- 정밀도: 주소·단지=exact / 지역·코드=중심 근사(반경 검색 정상).
- 공고 조회 — 필터 + 주택형(units) 포함, limit=100, offset=0.
더 있으면 다음 offset으로 이어 조회(전량 수집).
- 🚨 미측위 좌표 보완(핵심) — 좌표가 비었다고 바로 "위치 확인 필요"로 넘기지 말 것.
주소에서 지번(예:
사우동 527-1) 파싱 → 지오코딩 → confidence exact면 "주소 보완좌표"로 사용.
실패 시 단지명 주소검색. 둘 다 실패해야만 위치 미상.
→ 실증: 김포 사우동 4건(호반써밋 풍무Ⅱ·수자인 그라센트 1·2차·B5블록 호반써밋) 전부 exact 좌표 복구 → 위치 확인 필요 0건.
- 지도 — located+보완 전량을 마커로 지도 발급(DB좌표 파랑
#2563eb · 보완좌표 주황 #e56f1f). 반환 URL을 ipzi-data.mapUrl.
- 렌더 — 고정 템플릿
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.
