ipzitalk-presale-report

분양 리포트 (ipzitalk-presale-report)

지역 하나를 입력받아 최근 신규와 전체 물량을 한 화면에 낸다. ※ 청약홈에 등록된 공고를 정리한 것이며 실시간 청약 일정이 아니다. 경쟁률·접수·발표 일정은 담지 않는다.

설계 원칙 🚨

전량 1콜로 두 화면을 만든다. "최근 6개월"은 전량의 부분집합이므로 서버에 date_from을 넘길 필요가 없다. 전량을 받아 공고일로 거른다.

0건을 실패가 아니라 정보로 만든다. 최근 신규가 없으면 "최근 신규 공고 없음 · 마지막 공고 2025-08-19" 라고 쓰고, 하단 대시보드는 그대로 낸다. (송파구 실측: 전량 5건, 최근 6개월 0건. 최신 공고가 11개월 전이다.)

입력

파라미터	필수	기본	설명
query(자유형)	✅	-	지역명·주소·단지명·법정동코드 중 1개
recent_months	✕	6	상단 "신규" 블록의 기간(공고일 기준)
radius_km	✕	3	주소·단지명 입력일 때만. 지역명이면 시군구 전량

스코프는 입력이 정한다.

• 지역명/코드 → 시군구 전량
• 주소/단지명 → 좌표 + 반경 3km

⚠️ 지역 필터는 정확 일치다. "김포" → 0건, "김포시" → 18건. raw 지역명을 필터에 그대로 넣지 말고 지역코드 정규화로 정확명을 만든 뒤 쓴다.

필수 도구

도구	용도	콜
get_region_code / get_geocode / get_address	입력 해소	0~1
search_announcement_info(include_units=true, limit=100)	전량 1콜	1
get_map_embed_url	지도	1
		2~3

워크플로우

1. 입력 해소 — 지역명/코드 → 지역코드 정규화로 정확명 확정. 주소·단지명 → 좌표.
2. 전량 1콜 — search_announcement_info(sigungu=정확명, include_units=true, limit=100). has_more이면 offset으로 이어 받는다. 안 받으면 조용히 잘린다.
3. 최근 블록 분리 — 받아온 목록에서 announcement_date >= 오늘-6개월만 고른다. 🚨 서버 날짜 필터를 쓰지 않는다. 아래 §감사장치 부재 참조.
4. 좌표 보완 — unlocated는 지번 지오코딩 → 단지명 주소검색.
5. 집계 — KPI · 입주 타임라인(입주월 연도별) · 공급유형 도넛 · 전용면적 도넛 · 연도별 물량(공고일).
6. 지도 + 렌더 — 최근 공고는 브랜드색, 나머지는 회색. 겹친 좌표는 마커를 합친다.

🚨 units 세대수 합 ≠ total_supply

공공분양은 주택형을 전부 공개하지 않는다. 버그가 아니라 원천 데이터 특성이다.

남양주시 32건 중 11건 불일치. 합계 차이 4,001세대. 불일치 11건은 전부 LH·공공분양.

남양주진접2 A-1 공공분양   total_supply 920  vs  Σ(units) 263   (−657)
왕숙 아테라 공공분양                    812  vs          182   (−630)
덕소역 라온프라이빗 (민간)              348  vs          348   (일치)

• 🚨 도넛(공급유형·전용면적)은 주택형이 공개된 세대 기준임을 화면에 명시한다. 남양주: 총 공급 10,589 중 공개분 6,588세대(62%).
• 🚨 KPI 총 공급세대와 도넛 합계가 다른 것이 정상이다. 억지로 맞추지 말 것. 맞추려 들면 없는 세대를 만들어낸다.
• 두 도넛의 분모는 서로 같아야 한다(공급유형 6,588 == 전용면적 6,588). 이건 검산 가능.

⚠️ 예전 regional-presale-dashboard는 "areaMix 합계 == 총 공급세대. 어긋나면 주택형을 빠뜨린 것" 이라고 적었는데 틀렸다. 민간 위주 지역(송파 5건)에서 우연히 맞았을 뿐이다.

🚨 감사장치 부재 — filters에 date_from이 안 실린다

search_announcement_info(sigungu="송파구")                        → matched_count 5
search_announcement_info(sigungu="송파구", date_from="2026-01-10") → matched_count 0
두 응답의 summary.filters 는 {"sigungu":"송파구"} 로 글자 그대로 같다.

서버 필터는 정상 동작하지만 적용 여부가 응답에 드러나지 않는다. 필터를 빠뜨려도 응답이 항의하지 않아, 예전 브리핑이 조용히 틀렸다.

이 스킬은 서버 날짜 필터를 아예 쓰지 않으므로 이 함정에 걸리지 않는다.

🚨 좌표 결측과 중복 좌표

남양주 32건: exact 21 · dong_fallback 6 · unlocated 5.

• dong_fallback은 여러 공고가 같은 좌표를 갖는다. 왕숙 4건이 한 점에 겹친다. → 마커를 합치고 (같은 지점 N건)으로 표기한다. 따로 찍으면 서로를 가린다.
• unlocated는 반경 판정이 불가능하다. 지도에서 빼고 별도 회색 블록으로 분리, "위치가 확인되지 않음"이라고 적는다. 반경 스코프면 "반경 확인 불가".

표본 규칙

공고 수	처리
≥ 20	도넛·타임라인 정상
5 ~ 19	구성 비율만. 추세 언급 금지
< 5	표만. 도넛·타임라인 생략

• 등급(★)을 매기지 않는다. 지역 우열 단정 금지.
• 84㎡ 분양가는 주택형별 최고분양가 기준이다. 평균가·최저가와 다르다. 공공분양과 민간이 섞이면 편차가 크다 → 범위로 제시한다.

화면 문구는 일반인 언어로

쓰지 않는 말	대신
적재분 · REF_DB	청약홈에 등록된
미측위 · unlocated	위치가 확인되지 않음
특별공급 비중	특별공급 비율
상한제	분양가 상한제 적용
표본 부족	자료가 적어 참고용

• 세대수는 1,615세대처럼 단위를 붙인다. 분양가는 7.09억처럼 억 단위로.
• 안내문은 결과만. "왜 주택형 합이 다른가"의 내부 사정은 화면에 쓰지 않는다. 도넛 캡션에 "주택형이 공개된 6,588세대 기준" 한 줄이면 된다.
• 🚨 줄인다고 사실을 감추면 안 된다. "총 공급세대와 다르다"는 판단을 바꾸는 정보라 반드시 남긴다.

섹션마다 출처를 작게 단다

블록	출처
최근 신규 · KPI · 도넛 · 타임라인 · 공고 목록	청약홈
지도	네이버 지도 · 청약홈

• 도구·API 이름은 화면에 쓰지 않는다.

실행 감사 sidecar 🚨

• 첫 조회 전에 out/ipzitalk-presale-report/audit.json을 만들고 skillBaseDirectory, shellUsed, webUsed, generatedFiles를 기록한다.
• 각 MCP 호출 직후 baseToolName, 입력 요약, resultCount, truncated, provenance, 조건부 호출 reason을 누적한다. 페이지네이션·좌표 보완·지도 호출도 실제 행 수에 포함한다.
• 감사 누락을 복구하려고 MCP를 재호출하지 않는다. 기존 반환으로 복구할 수 없으면 auditIncomplete:true로 남기고 완료 처리하지 않는다.
• 최종 응답은 audit.json에서 도구별 호출 횟수, Remote provenance, Skill base directory, shell/web 사용 여부, 생성 파일을 계산해 보고한다.

출력 = 공통 템플릿

templates/result.html의 비실행 ipzi-data JSON 블록을 채운다(스킬 폴더 내부, self-contained). 마크업·CSS·렌더 JS는 고정이다. 실행마다 바뀌는 것은 ipzi-data 블록 하나뿐.

HTML 산출물 계약 🚨

• result.json·audit.json은 내부 계약용 고정 이름으로 유지하고, 사용자 전달 HTML만 대상 기반 이름을 쓴다.
• 지역 스코프는 정규화한 시군구명으로 <지역>_분양리포트, 주소·단지 반경 스코프는 resolver가 확정한 단지명 또는 정규화 주소로 <단지명>_인근_분양리포트를 만든다. 예: 송파구_분양리포트.html, 헬리오시티_인근_분양리포트.html. 대상값이 없으면 이름을 지어내지 말고 ipzitalk-presale-report.html로 폴백한다.
• 최종 HTML 경로는 out/ipzitalk-presale-report/<대상>_분양리포트.html이다.
• 셸 사용이 허용된 환경에서는 스킬 기준 ../../scripts/html_artifact_contract.mjs 검증기를 --file-name "<대상>_분양리포트"와 함께 사용한다. --skill-dir에는 이 스킬의 base directory, --data에는 완성한 JSON 파일, --output-root에는 작업공간의 out 디렉터리를 전달한다.
• shell-free 또는 셸 금지 환경에서는 File Read/Write로 templates/result.html을 직접 읽고 ipzi-data JSON 블록만 교체한다. 교체 전후의 fixed template region(고정 영역: 데이터 블록 앞 prefix와 뒤 suffix)이 원본과 같은지 비교한다.
• audit.json.generatedFiles에는 예시 이름이 아니라 실제 최종 파일명과 경로를 기록한다.
• 검증기가 통과하기 전에는 완료로 주장하지 않는다. File Read/Write나 고정 영역 비교를 수행할 수 없거나 금지된 도구를 사용했다면 완료 처리하지 말고 제약과 실제 사용 도구를 보고한다.

섹션 순서(고정)

1. 히어로 + 칩(지역·기간)
2. 최근 N개월 신규 — 공고 카드. 0건이면 "최근 신규 공고 없음 · 마지막 공고 YYYY-MM-DD"
3. 전량 KPI 4칸 (공고 수 · 총 공급세대 · 84㎡ 최고분양가 범위 · 특별공급 비율)
4. 지도
5. (2단) 입주 타임라인 + 연도별 물량 표
6. (2단) 공급유형 도넛 + 전용면적 도넛 — 같은 단에 나란히
7. 공고 목록 표
8. 출처·안내 푸터

공고 목록 표 사양

열	내용
공고명	굵게 + 신규 배지. 아랫줄에 작게 읍면동 · 공공/민간 · 상한제
공고일	YYYY-MM-DD
주택형	units[].exclusive_area_sqm의 정수부만 중복 제거해 59·74·84㎡
최고 분양가	그 공고의 max_price_10k 최댓값을 억 단위로
공급세대	total_supply
입주 예정	YYYY.MM
원문	detail_url을 공고문 링크로

• 🚨 detail_url을 반드시 건다. 우리가 가진 건 요약이고, 경쟁률·접수일정·평면은 원문에만 있다. 링크 없이 표만 주면 사용자가 다음 행동을 할 수 없다.
• 🚨 동적 링크는 https만 허용한다. 아니면 걸지 않는다. target="_blank" rel="noopener noreferrer".
• 표는 열이 7개라 좁은 화면에서 넘친다 → .tbl-wrap{overflow-x:auto} + table{min-width:760px}.
• 전량이 10건을 넘으면 최신 10건만 싣고 캡션에 32건 중 10건을 적는다.

필수 단서 · 금지 표현

• 필수: 청약홈 등록 기준(실시간 아님) · 최고분양가 기준 · 도넛은 주택형 공개분 기준 · 위치 미확인 공고 수 · 경쟁률·접수·발표일정 미포함 · 조회일.
• 금지: "이번주 청약 마감/오픈" 확정 · 최고가를 평균처럼 · 지역 우열 단정 · 도넛 합계를 총 공급세대에 억지로 맞추기 · 내부 테이블명 노출.

엣지 · 실패 처리

상황	처리
최근 N개월 신규 0건	정상. "최근 신규 없음 + 마지막 공고일" 카드. 하단 대시보드는 그대로
전량 0건	"청약홈에 등록된 공고가 없습니다". 리포트 생성 중단
지역 해소 실패	후보 나열 후 선택. raw 지역명 그대로 넣지 말 것
has_more: true	offset으로 이어 받는다
좌표 겹침(dong_fallback)	마커 합치고 (같은 지점 N건)
unlocated 존재	지도에서 빼고 별도 회색 블록
공고 < 5건	도넛·타임라인 생략. 표만

검증된 사항 (남양주시 · 조회 2026-07-10)

운영 MCP 실호출. search_announcement_info(sigungu="남양주시", include_units=true, limit=100) 1콜.

• 전량 32건 · 총 공급 10,589세대 · has_more: false
• 최근 6개월 신규 3건 · 1,615세대
  • 오남역 서희스타힐스 여의재 3단지 (2026-05-13 · 117세대 · 입주 2029-01 · 민간)
  • 남양주왕숙2 A-3블록 공공분양 (2026-04-30 · 686세대 · 입주 2030-05 · 상한제)
  • 왕숙 아테라 공공분양 (2026-04-30 · 812세대 · 입주 2029-02 · 상한제)
• 84㎡ 최고분양가(최근 3건): 6.94억 ~ 7.32억 (평당 2,708~2,883만원)
• 입주 피크: 2028년 4,424세대. 2027년은 0세대
• 공급유형(공개분 6,588세대): 일반 3,232 · 특별 3,356 → 특별공급 51%
• 전용면적(같은 분모): 60㎡ 이하 3,414(52%) · 60~85㎡ 2,791(42%) · 85㎡ 초과 383(6%)
• 좌표: exact 21 · dong_fallback 6 · unlocated 5
• 🚨 주택형 합 6,588 ≠ 총 공급 10,589. 불일치 11건 전부 LH·공공분양.

다른 지역 대조

시군구	전량	최근 6개월	마지막 공고
남양주시	32	3	2026-05-13
김포시	18	2	2026-05-22
송파구	5	0	2025-08-19

디자인 정본

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

• CDN·외부 폰트·이모지 금지. 아이콘은 <symbol> 인라인 + <use> 참조로 self-contained. (인라인 렌더 JS는 허용. 외부 스크립트만 금지.)
• 라이트/다크 양쪽. prefers-color-scheme + :root[data-theme] 모두 대응.
• 토큰만 사용: --g/--y/--o/--r/--x/--brand/--up/--down/--zebra (+ -s 배경 변형).
• 예외 상태: null은 확인되지 않음(0 아님) · 공고 부족은 도넛 생략.
• ★·☆는 활자 기호이며 이모지가 아니다.
• 도넛은 같은 단에 나란히 둔다. 위아래로 흩어놓으면 두 비율을 눈으로 비교할 수 없다.
• 숫자 열은 th.n·td.n 양쪽에 우측 정렬을 준다. th.n을 빠뜨리면 헤더만 좌측에 남는다.
• 지도 카드 CSS: .map{overflow-x:auto; overflow-y:hidden} + .map iframe{display:block; min-width:720px}.
• 🚨 지도 링크는 발급 후 7일 만료. 캡션에 유효기간을 반드시 적는다.
• 🚨 컨테이너 svg 규칙은 직계 자식으로 한정한다.

  .box > svg{width:100%}                     /* 차트만 */
  .box svg.ic{width:1.05em;height:1.05em}    /* 가드 */
  

  자손 선택자(.box svg)로 쓰면 특이도가 .ic(0,1,0)보다 높아(0,1,1) 제목 옆 아이콘까지 카드 폭으로 부푼다. 그 아이콘이 flex 공간을 다 먹어 제목이 세로로 접힌다. 실제로 두 스킬에서 같은 버그가 났다. 새 카드 컨테이너를 만들 때마다 확인할 것.

이 스킬이 대체하는 것 ⚠️

• regional-presale-dashboard (지역 분양현황 대시보드) — 보류
• presale-briefing (분양 브리핑) — 보류

합친 이유는 "결과가 같아서"가 아니다. 브리핑이 date_from을 제대로 걸면 송파구는 0건, 대시보드는 5건이다. 합친 진짜 이유는 ① 전량 1콜로 둘 다 만든다 ② 브리핑 단독은 대부분 지역에서 0건(빈 화면) ③ 사용자는 "최근 신규"와 "전체 물량"을 같이 보고 싶어한다.

ipzitalk-announcement-search(조건 검색·목록만)와는 여전히 별개다.

분석 목적 맞춤 요약

목적을 확보하는 방법

• 사용자가 처음부터 목적을 밝혔으면 다시 묻지 않고 사용자 문장을 goal.purpose에 그대로 보존한다.
• 목적이 없고 현재 클라이언트가 4개 선택지와 직접 입력(Other/기타)을 함께 지원하는 네이티브 사용자 입력 UI를 제공하면 그 UI를 정확히 한 번 사용한다.
  • 4인가족 실거주 검토
  • 투자 심의 회의 자료
  • 분양 제안서용 자료
  • 건너뛰기
  • UI가 자동 제공하는 기타(직접 입력)으로 자유 입력도 허용한다.
• 네이티브 UI가 직접 입력을 지원하고 지원 가능한 수가 2~3개이면, 그 수만큼 위 목적 프리셋을 앞에서부터 선택지로 제시한다. 질문에는 건너뛰기를 기타(직접 입력)에 입력해도 된다고 알린다.
• 네이티브 사용자 입력 UI가 없거나 직접 입력을 지원하지 않으면 다음 질문만 출력하고 그 턴을 종료해 답을 기다린다:

  원하는 분석 목적을 한 문장으로 알려주세요. (예: "4인가족 실거주 검토", "투자 심의 회의 자료", "분양 제안서용 자료") 건너뛰셔도 됩니다.

• 질문 단계에서는 목적 입력 UI 또는 위 텍스트 질문 외의 도구를 사용하지 않는다.
• 사용자가 목적 또는 명시적인 건너뛰기로 답변하기 전에는 MCP·웹·파일·셸 도구를 호출하지 않는다.
• 프리셋을 고르면 해당 문구를 goal.purpose에 그대로 저장하고, 직접 입력을 고르면 사용자가 입력한 원문을 그대로 저장한다.
• 건너뛰기를 고르거나 사용자가 건너뛰겠다고 답한 경우에만 goal:null로 두고 목적 섹션 없이 진행한다. 목적을 지어내지 않는다.

데이터 수집 후 맞춤 요약

• purpose에는 사용자 문장을 그대로 보존한다.
• 데이터 조회·수집이 완료된 후에만 conclusions(결론)·evidence(근거)·cautions(주의사항)·nextActions(다음 행동 제안)를 작성한다. 조회 전에 문구나 결론을 미리 만들지 않는다.
• goal은 사용자 표현을 그대로 보존한 purpose, conclusions(35), evidence(13), cautions(02), nextActions(13)로 구성한다.
• conclusions는 실제 조회·판정 결과만 목적에 맞춰 요약하고, 각 결론에 실제 evidence를 최소 1개 연결한다.
• evidence에는 이번 실행에서 확보한 필드·수치·비교 결과만 쓴다. 예시·검증값·모델 지식으로 빈 값을 채우지 않는다.
• 새 데이터나 없는 수치를 창작하지 않는다.
• 조회일과 각 공고의 입주월(YYYY.MM)을 연월 단위로 비교해 과거·당월·미래를 판정한다.
• 입주월이 조회일과 같거나 이전이면 입주 예정, 앞으로 입주, 입주 대기 물량으로 쓰지 않는다. 이미 입주 시점 경과 또는 확인된 사실만 쓴다.
• 위 금지는 부정문에도 적용한다. 앞으로 입주할 신규 물량은 확인되지 않습니다처럼 금지 표현을 부정해 쓰지 말고, 반경 내 등록 공고 중 조회일 이후 입주월이 확인된 공고는 없습니다처럼 비교 기준과 확인 범위를 직접 쓴다.
• 최근 6개월 공고가 0건이어도 성숙 시장, 공급 소진이라고 단정하거나 추론하지 않는다. 확인된 반경·기간 안에 신규 등록 공고가 없다는 사실까지만 쓴다.
• cautions는 실제로 확인된 데이터 누락·표본 한계·시점 차이·방법상 제약만 쓴다. 본문 경고를 약화하거나 새 위험을 지어내지 않는다.
• nextActions는 실제 발견사항·누락·사용자 목적에서 이어지는 검토 행동만 제안한다. URL이나 원시 Skill ID 대신 한글 Skill 이름과 자연어 질의 예시를 쓰며, 단지 거래 후속 예시는 최근 실거래가 추이로 표현한다.
• 템플릿은 배열 상한을 잘라내고 빈 단계는 숨긴다. goal:null이면 goal-box 전체를 숨긴다.

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 연결 상태를 확인하도록 안내한 뒤 중단한다.