부동산 갈아타기 대시보드
보유 아파트와 목표 아파트의 시세 갭, 세금·거래비용, 상승장 확산, 호재 진행, 과열 지표를 한 화면에서 보고
매일 카카오톡으로 요약 브리핑을 받는 개인용 웹 애플리케이션입니다.
Next.js(App Router) + Supabase + Vercel Cron 으로 동작하며, 배포하면 어디서든 접속할 수 있습니다.
무엇을 보여주나
| # | 기능 | 화면 | 데이터 출처 |
|---|
| ① | 보유 ↔ 목표 아파트 시세 갭 | 대시보드 | 국토교통부 실거래가 + 직접 입력 호가 |
| ② | 취득세·양도세·중개보수 등 현실 비용 | 갭 카드 펼치기 | 지방세법·소득세법 기반 자체 계산 |
| ③ | 전국 상승 확산 지도 + 미반등 지역 | 대시보드 | 국토교통부 실거래가 (2023-01=100 지수) |
| ④ | 관심 지역 호재 현황·진행 단계 | 대시보드 | 네이버 뉴스 검색 + 사업 시드 |
| ⑤ | 하락장 갈아타기 시뮬레이션 | /simulation | 자체 시나리오 엔진 |
| ⑥ | 과열 지표·매수심리 (수치별 해설 툴팁) | 대시보드 | 한국부동산원 + 실거래 파생 지표 |
| ⑦ | 신고가·신저가 | 대시보드 | 국토교통부 실거래가 |
| ⑧ | 기준금리·CPI·M2·주담대금리 + 분석 브리핑 + 주요 일정 | 대시보드 | 한국은행 ECOS |
| ⑨ | 일정별 결과 시나리오 → 시장 방향 예측 | /outlook/[일정] | 규칙 기반 시나리오 엔진 |
전국 확산 지도
- 전국 178개 시군구를 대상으로 합니다. 서울 25개구, 6개 광역시 전 자치구, 세종,
경기·인천 전역에 더해 천안·아산·공주·청주·전주·창원·포항 같은 지방 중소도시까지 포함합니다.
- 색은 2023년 1월 대비 변동률입니다. 국내 관행대로 상승은 붉은색, 하락은 파란색이며
농도가 변동 폭을 나타냅니다 (±20%에서 최대 농도).
- 확대·축소:
Ctrl(⌘)+휠로 줌, 확대 상태에서 드래그로 이동. 권역 버튼(수도권·충청·영남·호남·강원·제주)으로
한 번에 이동할 수 있고, 2.6배 이상 확대하면 시군구 이름이 함께 표시됩니다.
- 서울·수도권은 겹침이 심해 별도 탭에서 격자 카토그램으로도 볼 수 있습니다.
일정별 시장 방향 예측
대시보드의 "주요 일정"에서 항목을 누르면 그 일정의 결과별 시나리오를 보여줍니다.
- 금통위·FOMC·소비자물가·부동산원 가격동향·과세기준일·공시가격·보유세 납부까지 이벤트별 전용 분석
- 각 시나리오마다 파급 경로(1→2→3단계), 반영 시차, 가장 크게 영향받는 대상,
내 갈아타기 관점의 행동 지침
- 확률은 현재 CPI·기준금리·과열 점수·확산률을 규칙에 넣어 계산한 가늠치입니다.
맞히는 도구가 아니라 경우의 수를 정리하는 도구로 봐주세요.
자동 채우기
설정에서 단지명·시군구·전용면적·취득일·취득가액만 넣고 "자동 계산"을 누르면 나머지를 오늘 기준으로 채웁니다.
| 채워지는 값 | 계산 방식 |
|---|
| 취득 부대비용 | 현행 세율의 취득세·지방교육세·농특세 + 중개보수·법무비·인지세·채권할인 |
| 실거주 개월 수 | 취득일 ~ 오늘 |
| 대출 금리 | 한국은행 ECOS 예금은행 주택담보대출 신규취급 평균금리 |
| 현재 호가 | 해당 단지·면적의 최근 6개월 실거래 중앙값 |
| 세대 프로필 | 등록된 보유 아파트 수, 조정대상지역 해당 여부, 일시적 2주택 특례 |
채운 값은 전부 직접 수정할 수 있고, 각 값마다 어떤 근거로 계산했는지 함께 보여줍니다.
"이미 입력된 값도 덮어쓰기"를 켜면 직접 넣은 값도 최신 계산으로 다시 채웁니다.
갱신 주기
주요 출처를 1시간 간격으로 확인해 현재 시점 기준 정보를 보여줍니다.
| 계층 | 방식 |
|---|
| 외부 API 캐시 | 실거래·ECOS·부동산원 1시간, 뉴스 30분 TTL |
| 지연 갱신 | 페이지 요청 시 실거래 집계가 1시간 넘게 낡았으면 최근월 재수집 |
| 클라이언트 | 탭이 열려 있으면 1시간마다 자동 새로고침 (헤더 칩을 눌러 즉시도) |
| Cron | 매일 07:00 KST 전국 최근 3개월 증분 갱신 |
크롤링 대신 공식 API만 씁니다 — 같은 정보를 국토교통부·한국부동산원·한국은행·네이버 검색 API로
모두 얻을 수 있고, 스크래핑은 대상 사이트의 이용약관 위반이기 때문입니다.
설계상의 선택 몇 가지
- 네이버 부동산은 쓰지 않습니다. 공식 오픈 API 가 없고 스크래핑은 이용약관 위반입니다.
시세는 국토교통부 실거래가(공공데이터포털)를, 동향·호재는 네이버 검색 API(공식)를 씁니다.
- 지도는 GeoJSON 없이 자체 렌더링합니다. 수 MB짜리 행정경계 데이터나 지도 타일 서비스에
의존하지 않도록, 저해상도 해안선을 내장하고 시군구는 대표 좌표의 원으로 그립니다.
서울·수도권처럼 겹침이 심한 곳은 격자 카토그램 탭을 따로 뒀습니다.
- 호재의 진행 단계는 코드에 박아두지 않습니다. 사업명·성격·공식 출처처럼 변하지 않는 것만 두고,
단계는 최신 뉴스 헤드라인에서 매번 다시 추론합니다. 관련 보도가 없으면 '미확인'으로 표시합니다.
- 카카오는 알림톡이 아니라 "나에게 보내기"(메모 API) 를 씁니다. 알림톡은 사업자등록과 발신프로필
심사가 필요하지만, 본인에게 보내는 용도라면
talk_message 스코프로 즉시 쓸 수 있습니다.
⚠️ 세금·비용 계산은 참고용 추정치입니다. 조정대상지역 지정, 다주택 중과 한시 배제, 감면 특례는
수시로 바뀝니다. 실제 신고 전 홈택스 · 위택스
또는 세무 전문가로 반드시 확인하세요.
빠른 시작 (로컬)
npm install
cp .env.example .env.local # 값은 아래 "API 키 발급" 참고
npm run dev
키가 하나도 없어도 앱은 뜹니다. 각 섹션이 "키 없음"으로 표시될 뿐입니다.
UI 를 먼저 둘러보고 싶다면 개발 서버를 켠 뒤 샘플(합성) 데이터를 넣어보세요.
curl -X POST http://localhost:3000/api/dev/seed
이 데이터는 전부 합성이며 실제 시세가 아닙니다. 운영 환경에서는 동작하지 않습니다.
API 키 발급
1. 국토교통부 실거래가 (필수)
시세·갭·확산지도·신고가 분석의 근간입니다.
- 공공데이터포털 - 아파트 매매 실거래가 상세 자료 활용신청
- 승인 후 마이페이지에서 일반 인증키(Decoding) 복사
DATA_GO_KR_SERVICE_KEY 에 입력
2. 한국은행 ECOS (권장)
기준금리 / 소비자물가 / M2 / 주택담보대출금리.
- ECOS 인증키 신청
ECOS_API_KEY 에 입력
통계표·항목 코드가 ECOS 개편으로 바뀌면 .env.example 의 ECOS_STAT_* / ECOS_ITEM_* 로 덮어쓸 수 있습니다.
3. 한국부동산원 R-ONE (선택)
주간 매매가격지수·매매수급동향. 없어도 됩니다 — 실거래 거래량과 신고가 비중으로
대리지표를 자동 계산합니다(대시보드에 추정치임이 표시됩니다).
- R-ONE OpenAPI 신청
REB_API_KEY 에 입력
4. 네이버 검색 API (권장)
관심 지역 호재·이슈 뉴스 수집.
- 네이버 개발자센터 애플리케이션 등록 → 검색 API 추가
NAVER_CLIENT_ID, NAVER_CLIENT_SECRET 입력
5. Supabase (필수)
설정 저장 / 실거래 캐시 / 카카오 토큰 보관. 없으면 서버 메모리만 써서 재시작 시 초기화되고
자동 브리핑을 쓸 수 없습니다.
- Supabase 프로젝트 생성
- SQL Editor 에
supabase/migrations/0001_init.sql 전체를 붙여넣고 실행
- Project Settings → API 에서 값 복사
NEXT_PUBLIC_SUPABASE_URLNEXT_PUBLIC_SUPABASE_ANON_KEYSUPABASE_SERVICE_ROLE_KEY (⚠️ 절대 클라이언트에 노출 금지)
6. 카카오 (브리핑 발송용)
- 카카오 개발자센터 → 애플리케이션 추가
- 앱 키 → REST API 키를
KAKAO_REST_API_KEY 에 입력
- 카카오 로그인 활성화 ON
- Redirect URI 등록:
https://<배포주소>/api/kakao/callback (로컬은 http://localhost:3000/api/kakao/callback)
- 동의항목 → "카카오톡 메시지 전송(
talk_message)" 활성화
- 앱 실행 후
/settings → 카카오 계정 연결 버튼 클릭 (1회)
7. CRON_SECRET (필수)
Cron 라우트를 아무나 호출하지 못하게 막는 값입니다. 긴 랜덤 문자열이면 됩니다.
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
Vercel 배포
npm i -g vercel
vercel link
vercel env add DATA_GO_KR_SERVICE_KEY # ... 나머지 키도 동일하게
vercel deploy --prod
vercel.json 에 Cron 두 개가 정의돼 있습니다 (Vercel 시간은 UTC 기준).
| 경로 | 스케줄(UTC) | KST | 하는 일 |
|---|
/api/cron/refresh?months=3 | 0 22 * * * | 07:00 | 최근 3개월 실거래 증분 갱신 |
/api/cron/briefing | 0 23 * * * | 08:00 | 카카오톡 브리핑 발송 |
발송 시각을 바꾸려면 vercel.json 의 schedule 을 수정하세요 (설정 화면의 "발송 희망 시각"은
표시용이며 실제 트리거는 Cron 이 결정합니다).
Vercel Hobby 플랜은 Cron 작업 2개, 하루 1회 실행까지 지원합니다. 위 구성이 딱 그 한도입니다.
배포 후 최초 1회: 과거 실거래 백필
실거래 API 는 (시군구 × 월) 단위로만 조회돼서 178개 지역 × 약 55개월 ≈ 9,800회 호출이 필요합니다.
공공데이터포털 기본 일일 트래픽(10,000회)에 가까우므로 하루 이틀에 걸쳐 나눠 받으세요.
한 번의 요청으로는 끝나지 않으므로, 응답의 remaining 이 0이 될 때까지 반복 호출하면 됩니다.
curl "https://<배포주소>/api/cron/backfill?secret=<CRON_SECRET>®ions=6"
# {"ok":true,"remaining":2400,"hint":"남은 작업이 있습니다. 같은 URL 을 다시 호출하세요."}
이미 저장된 (지역, 월)은 자동으로 건너뛰므로 중복 호출해도 안전합니다.
백필이 끝나면 이후에는 매일 Cron 이 최근 3개월만 증분 갱신합니다.
사용 흐름
/settings 에서 보유 아파트를 등록합니다.
최소 입력은 단지명 · 시군구 · 전용면적 · 취득일 · 취득가액 다섯 가지입니다.- 목표 아파트를 등록합니다. 여러 개 넣으면 실소요 자금이 적은 순으로 정렬됩니다.
- 관심 지역을 등록합니다. 여기 등록한 지역만 호재·뉴스 추적과 신고가 분석 대상이 됩니다.
- 맨 위 "전체 자동 계산" 을 누릅니다. 취득 부대비용·실거주 개월·대출 금리·현재 호가와
세대 프로필이 오늘 기준으로 채워지고, 각 값의 계산 근거가 함께 표시됩니다.
- 채워진 값 중 실제와 다른 것(실제 납부한 취득세, 알고 있는 호가 등)을 직접 수정합니다.
- 저장 후 대시보드로 이동하면 전 섹션이 채워집니다.
/simulation 에서 하락장 시나리오별 갭·실소요 자금 변화를 확인합니다.- 대시보드의 주요 일정에서 항목을 눌러 그 결과가 시장을 어느 방향으로 밀지 확인합니다.
시세는 어떻게 정해지나
- 설정에서 현재 호가를 직접 입력했다면 그 값을 씁니다 (실거래는 후행 지표라 호가가 더 현실적입니다).
- 비워두면 해당 단지·면적대의 최근 6개월 실거래 중앙값을 씁니다.
- 둘 다 없으면 "시세 미확인"으로 표시되고 갭 계산에서 제외됩니다.
주요 명령
npm run dev # 개발 서버 (Turbopack)
npm run build # 프로덕션 빌드
npm run typecheck # TypeScript 검사
npm run lint # ESLint
npm run format # Prettier 적용
npm run check-all # 타입 + 린트 + 포맷 검사
구조
src/
app/
page.tsx 대시보드
settings/ 설정 (보유/목표/관심지역/세대/카카오/자동채우기)
simulation/ 하락장 갈아타기 시뮬레이션
outlook/[eventId]/ 일정별 시장 방향 예측
api/
config/ 설정 조회·저장
autofill/ 설정 자동 계산 (저장하지 않고 값만 반환)
dashboard/ 대시보드 데이터 JSON
kakao/ OAuth 연결 · 상태 · 발송
cron/refresh 최근 3개월 증분 갱신
cron/backfill 과거 데이터 백필 (반복 호출)
cron/briefing 일일 브리핑 발송
dev/seed 샘플(합성) 데이터 — 개발 전용
lib/
sources/ 외부 API 어댑터 (molit / ecos / reb / news)
tax/ 취득세 · 양도세 · 거래비용 계산
analysis/ 반등 확산 · 과열지표 · 지표해설 · 호재 · 일정 · 예측 · 자동채움
pipeline/ 수집(refresh) · 지연갱신 · 조립(dashboard) · 브리핑
store/ Supabase 저장소 + 메모리 폴백
regions.ts 전국 법정동코드 + 대표 좌표 + 타일 카토그램
geo.ts 지도 투영 · 해안선 · 색상 스케일
refresh-policy.ts 갱신 주기 정책
supabase/migrations/ DB 스키마
데이터 흐름
공공데이터포털 실거래가 ─┐
├─→ [cron/refresh] ─→ Supabase(region_monthly, trade_cache)
│ │
한국은행 ECOS ───────────┤ ↓
한국부동산원 R-ONE ──────┼─────────────────→ [buildDashboard] ─→ 대시보드 화면
네이버 뉴스 검색 ────────┘ │
↓
[buildBriefing] ─→ 카카오톡 (200자 × N건)
알려진 한계
- 실거래는 후행 지표입니다. 계약일로부터 최대 30일의 신고 기한이 있어 최근 1~2개월 데이터는
계속 채워집니다. 그래서 최근 2개월은 캐시를 짧게 잡고 매일 다시 긁습니다.
- 월 거래량이 적은 지역은 지수가 튑니다. 월 5건 미만인 달은 지수 산출에서 제외하고,
3개월 거래건수 가중 이동평균으로 평활했습니다. 그래도 지방 소도시는 표본 부족으로 나올 수 있습니다.
- 금통위·FOMC 일정은 추정치입니다(개최 월의 n번째 목/수요일). 화면에 "일자 추정"으로 표시되며
정확한 날짜는 공식 공지를 확인하세요.
- 조정대상지역 목록은 자동 갱신되지 않습니다. 자동 채우기는 서울 강남·서초·송파·용산 4개구를
기본 가정으로 쓰며, 정부 공고로 바뀌므로 설정 화면에서 직접 토글해야 합니다.
- 지도는 실제 행정경계가 아닙니다. 내장된 저해상도 해안선 위에 시군구 대표 좌표를 원으로
찍은 것이라, 원의 위치는 시청·구청 부근이고 크기는 도시 규모입니다.
- 일정 예측의 확률은 규칙 기반 가늠치입니다. 시장 컨센서스나 선물시장 반영률이 아니며,
투자 자문이 아닙니다.
- 자동 계산한 취득 부대비용은 현행 세율 기준입니다. 과거에 취득한 주택이라면 그때의 세율·감면이
달랐을 수 있으니, 실제 납부액을 알고 있다면 그 값으로 바꾸는 편이 정확합니다.
- Supabase 없이 쓰면 설정이 서버 메모리에만 남아 배포·재시작 시 사라집니다.
