ipzitalk-retail-proximity

name	ipzitalk-retail-proximity
description	주소 또는 단지명을 입력받아 가장 가까운 백화점·대형마트(대형슈퍼 포함)까지의 직선거리를 기준으로 쇼세권 신호 배지(🟢상권 인접/🟡근접/🟠다소 이격/⬜이격)를 카드 + 지도로 생성한다. "쇼세권", "백화점 가까워", "대형마트 근처", "쇼핑 상권", "마트 가까워?", "생활 인프라 좋아?", "스타필드 가까워", "더현대 근처" 등의 표현이 있을 때 이 스킬을 사용한다. 사용자가 특정 주소/단지의 백화점·대형마트 상권 접근성을 물으면 즉시 트리거한다.
version	1.0.5
license	proprietary

쇼세권 진단

주소/단지명 하나로 최근접 백화점·대형마트까지 직선거리를 재서 쇼세권 신호 배지 + 지도를 만든다. ※ 직선거리 기준. 영업 여부·매장 규모는 미반영. 복합몰(스타필드·더현대)은 명칭 근사(내부 대형마트/백화점으로 포착).

입력

파라미터	필수	기본	설명
address 또는 complex_query	✅(택1)	-	주소 또는 단지명
radius_m	✕	2000	상권 검색 반경

필수 도구

도구	용도
get_geocode / get_address	좌표 확보(주거시설 우선)
search_by_nearby_keyword	백화점: query="백화점" (본체만 남기도록 필터)
search_by_nearby_category	대형마트: categories=['mart_large'](MT1)
get_static_map / get_map_embed_url	지도

워크플로우 (조합 검색 · 검증됨)

1. 좌표 확보 (address→geocode / 단지명→get_address 주거시설 우선).
2. 백화점: search_by_nearby_keyword(center, radius_m=2000, query="백화점", grid=true, category_filter={include_contains:["백화점"]}) → category_name이 "백화점"인 본체만 남김(입점매장·ATM 노이즈 제거). 🚨 grid=true 없이 부르면 입점 매장이 45건 캡을 다 먹어 본체가 0건으로 사라진다(아래 gotcha, 실측). 0건이면 truncated 를 확인한다. truncated:true = "없음"이 아니라 "확인 불가".
3. 대형마트: search_by_nearby_category(center, radius_m=2000, categories=['mart_large']). → 결과에는 대형마트(홈플러스 등)와 대형슈퍼/SSM(이마트에브리데이·롯데슈퍼프레시 등)이 섞여 나온다.
4. 2·3 결과를 합쳐 주소 dedupe → 최근접 1건 + 반경 내 개수.
5. 배지 판정(아래) → 지도 생성.

밴드(직선거리 m): ≤1000 🟢 상권 인접 / 1000–2000 🟡 근접 / 2000–3000 🟠 다소 이격 / >3000 ⬜ 이격

SSM(대형슈퍼) 인정 규칙 (사용자 확정)

• 반경 내 백화점·진짜 대형마트가 멀면(또는 없으면) 대형슈퍼(SSM)도 생활 상권으로 인정한다.
• 단, 이때 hedge에 **"백화점 없음 · 진짜 대형마트는 N km · 근린은 대형슈퍼 위주"**를 반드시 명시한다.
• 최근접이 SSM이면 stat 라벨을 최근접(대형슈퍼)로 구분 표기, POI 명에 (대형슈퍼)/(대형마트)를 병기.

검증된 사항 (방배롯데캐슬아르떼 · 방배동 424-28 · 2026-07-08)

• 백화점: query="백화점" radius 2000 → 0건 (방배동 인근 백화점 없음).
• 대형마트(mart_large, radius 2000): 이마트에브리데이 이수점 320m(대형슈퍼) · 사당동점 736m · 롯데슈퍼프레시 873m · 홈플러스익스프레스 1009m · 홈플러스 남현점 1318m(진짜 대형마트) · 이마트에브리데이 방배그랑자이 1624m.
• 판정: 백화점 0 + 대형마트 1.3km지만 SSM 최근접 320m → 🟢 상권 인접. hedge에 "백화점 없음 · 홈플러스 1.3km · 근린 대형슈퍼 위주" 명시.

출력 = 카드 템플릿

templates/result.html 구조의 ipzi-data JSON을 채운다(self-contained, SVG only, CDN·이모지 금지). 값:

• iconId:"i-shopping", badgeTitle:"쇼세권 진단", axisMax:2000, radiusDefault:1000
• signal:{label:"상권 인접(생활밀착)",cls:"g"} (밴드 결과에 맞춰)
• bands:[{max:1000,cls:"g",label:"≤1000 상권 인접"},{max:2000,cls:"a",label:"1000–2000 근접"},{max:3000,cls:"o",label:"2000–3000 다소 이격"},{max:Infinity,cls:"x",label:">3000 이격"}]
• stat:[{n:"320m",l:"최근접(대형슈퍼)",cls:"g"},{n:"__COUNT__",l:"1km 내 마트"},{dot:"g",l:"신호 등급"}]
• pois: 마트 리스트에 (대형슈퍼)/(대형마트) 라벨 병기, d=직선거리(m)
• hedge.verify: null (배정교 개념 없음)

필수 단서 · 금지 표현

• 필수: 직선거리 기준 · 영업/규모 미확인 · 복합몰 명칭 근사 · (SSM 인정 시) 백화점/대형마트 이격 명시
• 금지: "상권 최고" 등 근거 없는 우열 단정, 값 지어내기

엣지

• 지오코딩 실패/AMBIGUOUS → 재입력/후보 제시
• 백화점·대형마트·대형슈퍼 전부 0건 → ⬜ 데이터 부족(반경 넓혀 재시도 제안)

Gotcha

• mart_large(MT1) 카테고리는 대형마트뿐 아니라 대형슈퍼/SSM(이마트에브리데이·롯데슈퍼프레시·홈플러스익스프레스)도 함께 반환한다. 최근접이 SSM일 수 있으니 라벨을 반드시 구분하고, "진짜 대형마트"까지의 거리를 별도로 확인·명시할 것.
• mart_large 단독으로는 백화점·복합몰이 누락될 수 있음 → 백화점은 query="백화점" 키워드로 별도 검색.
• "백화점" 키워드 단독은 입점매장·ATM 노이즈가 섞임 → category_name "백화점" 본체만 남김.

섹션마다 출처를 작게 단다

데이터 블록 하단에 .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이 카드 폭에 짓눌려 지도가 최소 줌(한반도)으로 떨어진다.
• 🚨 지도 링크는 발급 후 7일 만료. 산출물 지도 캡션에 유효기간·재발급 필요를 반드시 적는다. 만료 시 iframe이 빈 화면이 되는데, 원인 표기가 없으면 리포트가 고장난 것처럼 보인다.
• 🚨 반경 눈금 마커를 넣지 않는다. 예전엔 fitBounds가 반경 원을 무시해 원이 잘리는 걸 막으려고 정북·남·동·서에 회색 더미 마커 4개를 심었다. 사용자에게는 정체를 알 수 없는 점으로 보여 혼란만 준다. 원이 잘리더라도 마커는 실제 장소만 찍는다. (근본 해결은 render.ts가 원을 bounds에 포함하도록 고치는 것 — 발견사항 6번)

🚨 상권 시설을 3층으로 구분한다 (실측 2026-07-09)

같은 '상권'이라도 급이 다르다. 하나로 뭉치면 대형슈퍼가 백화점으로 둔갑한다.

층	예 (위례 실측)
대형슈퍼(SSM)	GS더프레시 송파위례점 132m · 롯데슈퍼프레시 · 노브랜드
복합쇼핑몰·대형마트	스타필드시티 위례 673m(트레이더스·이마트 포함) · 롯데마트
백화점	NC백화점 송파점 1.4km — 아울렛형. 롯데·신세계·현대 같은 정통 백화점은 반경 3km 내 부재

• 최근접 라벨에 시설 종류를 병기한다(예: 최근접(대형슈퍼) 132m).
• 🚨 대형슈퍼 132m 를 근거로 "상권 우수"라고 쓰지 않는다. hedge 에 급 차이를 명시한다.
• 정통 백화점이 없으면 없다고 쓴다.

🚨 생활잡화(다이소)는 목록에만 — 판정 제외 (2026-07-10 결정)

다이소를 찾아서 보여주되, 신호 등급과 개수 산정에는 넣지 않는다.

검색

search_by_nearby_keyword(center, radius_m=2000, query="다이소")

• 카테고리가 깔끔하다: 가정,생활 > 생활용품점 > 다이소
• 위례 실측 2km 내 8곳.

시설 4층 구분

층	판정	예 (위례 실측)
백화점	✅	NC백화점 송파점 1.4km (아울렛형)
복합쇼핑몰·대형마트	✅	스타필드시티 위례 673m · 이마트 가든파이브점
대형슈퍼(SSM)	✅	GS더프레시 송파위례점 132m · 롯데슈퍼프레시
생활잡화	❌ 참고만	다이소 위례본점 598m

왜 판정에서 빼나

밴드가 ≤1000m → 상권 인접(초록)이다. 다이소를 그대로 넣으면 다이소 하나만 있는 동네도 초록이 된다. 다이소는 생필품 잡화점이지 식료품·대형 상권이 아니다.

구현

ipzi-data.pois 에 aux: true 로 넣는다.

{n:"다이소 위례본점 (생활잡화)", d:598, aux:true}

템플릿이 aux 항목을 이렇게 처리한다.

• 목록·지도에는 보인다. 참고 배지 + 회색 핀.
• 1km 내 상권시설 개수에서 제외. 밴드 색도 회색 고정.
• 최근접 판정(stat[0])에도 쓰지 않는다.

위례 검증: 다이소 8곳을 넣어도 1km 내 상권시설 = 4, 신호 상권 인접(생활밀착) 불변.

복합몰 안의 다이소

다이소 스타필드위례점 683m(스타필드시티 위례 673m 내), 다이소 현대시티몰가든파이브점 1,497m(NC백화점 내)처럼 몰 안에 있는 지점도 그대로 표시한다. 거리가 거의 같아 같은 건물임이 드러난다. 별도 제외 처리 없음.

🚨 화면 문구는 일반인 언어로 (2026-07-10 결정)

진단 시리즈(초품아·역세권·병세권·쇼세권·숲세권)의 독자는 부동산 전문가가 아니다. 내부 용어를 그대로 화면에 쓰지 않는다. 임계값·색(cls)은 그대로 두고 라벨만 바꾼다.

쓰지 않는 말	대신
최근접 · (최근접·판정 기준)	제일 가까운 곳 · (제일 가까움)
판정 밴드 · 판정 기준	등급 기준
신호 등급	등급
인접 / 근접	아주 가까움 / 가까움
다소 이격	조금 먼 편
이격 · 역 이격	먼 편 · 역이 먼 편
보도권	가까움
판정 유보	자료 부족
판정창	기준 범위
참고 신호(진단 아님)	참고용이며 확정 판단이 아닙니다
1km 내 · 슬라이더 반경 내	1km 안 · 선택한 반경 안
미확인	확인되지 않음
판정에서 제외	등급에서 제외

거리도 읽기 쉽게: 1313m → 1.3km.

문장도 사람 말로

✕  SITE(파랑) · 반경 3km 원 · 판정 기준 경찰병원(주황, 2.3km) · 서울세계로병원(회색)은 등급에 미반영
✓  파란 점이 우리 집, 주황 점이 등급 기준이 된 경찰병원(2.3km)입니다.
   회색 서울세계로병원(645m)은 종합병원이 아니라 등급에 넣지 않았습니다.

• 🚨 부드럽게 쓰되 사실은 그대로. "가까움"이 "좋음"이 되면 안 된다. 등급은 거리 밴드가 정한다.
• 🚨 숫자는 화면 전체에서 일치해야 한다. aux 항목을 개수에서 뺐으면 본문 문장의 개수도 함께 고친다. 실제로 목록은 5곳인데 본문이 6곳이라고 적힌 적이 있다.
• 익숙한 말은 남긴다: 역세권·준역세권·초품아·상권.

🚨 운영 상태는 장소명 문자열에만 있다 — 폐점·오픈예정 (2026-07-10)

카카오는 운영 상태 필드를 주지 않는다. 상태를 장소명에 괄호로 붙인다. 학교 "서울반포초등학교 (휴교)", 역 "위례호수공원역 (2026년12월예정)" 이 실측으로 확인됐다.

• 장소명에 폐점·폐업·휴업·임시휴업·오픈예정·개점예정·(20NN년 이 있으면 신호 등급·최근접·개수에서 제외하고, 목록에만 꼬리표를 단다.
• 재개장 시점·연도를 지어내지 말 것. 장소명에 있는 문자열만 화면에 쓴다.
• ✅ 상업시설에서도 관측 확정 (잠실 실측 2026-07-10). 더 이상 예방 규칙이 아니다. categories:['mart_large'] r2500 응답에 그대로 섞여 나왔다.

홈플러스 잠실점 (폐점)     774m   가정,생활 > 대형마트 > 홈플러스
롯데마트 월드타워점        799m   가정,생활 > 대형마트 > 롯데마트   ← 운영 중 최근접

25m 차이로 문 닫은 점포가 최근접 대형마트를 가로챈다. category_name·거리 모두 정상 시설과 같아 응답만 보고는 구분할 수 없다. 같은 실측에서 공공기관(풍납2동주민센터 (2027년 예정))에서도 관측됐다.

🚨 query="백화점" 은 입점 매장이 45건 캡을 다 먹는다 (실측 2026-07-10)

카카오는 백화점 입점 매장 장소명에 지점명을 붙인다. 거리순 정렬이라 본체보다 매장이 먼저 온다.

반포래미안아이파크 · radius_m=4000 · query="백화점"
→ 45건 전부 입점 매장. 백화점 본체 0건. truncated: true
   신세계 본사              736m  서비스,산업 > 기업          ← 최근접
   르메르 신세계백화점 강남점 757m  가정,생활 > 패션 > 여성의류
   미가훠궈 신세계백화점 강남점 778m  음식점 > 중식
   룰루레몬 · 커피스니퍼 · 노스페이스키즈 · 키친툴 …

category_name == "백화점" 인 본체만 남기는 후처리는 이 경우 0건을 반환한다. "백화점 없음"이 아니라 캡에 잘려 안 보이는 것이다. park 카테고리가 죽은 것과 같은 구조다.

해결 검색식 (실측 검증 2026-07-10)

search_by_nearby_keyword(center, radius_m=2000, query="백화점",
                         grid=true, category_filter={include_contains:["백화점"]})

→ total_found 68 → after_filter 2 → after_dedupe 1 · truncated: false
   신세계백화점 강남점   888m   가정,생활 > 백화점 > 신세계백화점   ← 본체 복구

• 🚨 grid=true 와 include_contains:["백화점"] 을 함께 준다. 하나만으로는 안 된다. include 필터는 서버 후처리라 캡 이후에 걸린다 → grid 로 캡을 우회해야 본체가 필터에 도달한다.
• 반경을 넓히면 오히려 나빠진다. grid 없이 4km = 본체 0건 / grid로 2km = 본체 1건. 입점 매장이 거리순 상위를 채우기 때문이다. 넓은 반경이 필요하면 반드시 grid.
• 🚨 0건 이라고 쓰기 전에 truncated 를 본다. truncated:true 면 "백화점 없음"이 아니라 "확인 불가".
• ⚠️ 아래 방배 검증(2026-07-08)의 백화점 0건 은 이 규칙 이전 결과다 → 재검증 필요.

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