내집로그 (MyHomeLog)

국토교통부 실거래가 기반 부동산 정보 정리 도구
도메인: myhomelog.vercel.app

⚠ 이 서비스는 매수·매도를 추천하지 않고, 미래 가격을 예측하지 않습니다.
투자자문·유사투자자문 서비스가 아닙니다. 공식 통계 수치를 정리해 보여줄 뿐이며, 의사결정과 그 책임은 이용자 본인에게 있습니다.

---

서비스 소개

• 2025.10.15 규제 기준 LTV·DSR 대출 한도 계산 (공식 고시 기준값 정리)
• 국토부 실거래가 API 기반 조건 부합 단지 찾기 (입력한 조건에 맞는 단지를 걸러 보여줍니다 — 추천이 아닙니다)
• 네이버 지도(기본 엔진, NAVER_MAPS_CLIENT_ID) — 키 미설정·인증 실패 시 Leaflet + OpenStreetMap 자동 폴백 + 카카오 지오코딩으로 위치 표시
• 맞춤 보고서 (실거래 요약 / 비용 / 리스크 체크 / 특약 초안)
• 지역별 공식 통계 정리 (거래량 · 가격지수 · 미분양 · 인구 순이동 · 규제 상태)

데이터 출처

국토교통부 실거래가 · 한국부동산원 R-ONE · KOSIS(미분양·인구이동) · 한국은행 ECOS · 한국주택금융공사(정책자금) · KAPT 공동주택 정보 · 금융위원회 고시. 값이 없는 항목은 추정하지 않고 비워둡니다.

---

빠른 시작

1. 환경변수 설정

cd backend
cp .env.example .env

backend/.env.example 이 유일한 환경변수 선언 목록입니다:

• 필수 — PORT, NODE_ENV, ANTHROPIC_API_KEY, MOLIT_API_KEY, KAKAO_REST_API_KEY, SUPABASE_*, DATABASE_URL, JWT_SECRET, ALLOWED_ORIGINS
• 결제 — TOSS_SECRET_KEY, TOSS_CLIENT_KEY, TOSS_WEBHOOK_SECRET, PAYMENTS_LIVE_ENABLED
• 관측 — SENTRY_DSN, UPSTASH_REDIS_*, ECOS_API_KEY, KOSIS_API_KEY, LAW_GO_KR_OC
• 알림 — VAPID_, KAKAO_
• 선택 — NAVER_MAPS_CLIENT_ID, NEIS_API_KEY, NAVER_CLIENT_ID/SECRET, HEALTH_API_KEY, ADMIN_EMAILS, SUPPORT_EMAIL, 캐시/레이트리밋

2. API 키 발급

API	발급처	무료 여부
국토부 실거래가	data.go.kr 검색: "아파트매매 실거래가 상세자료"	✅ 무료
카카오 지오코딩	developers.kakao.com → REST API 키	✅ 무료 (월 30만건)
Anthropic Claude	console.anthropic.com	유료 (사용량 기반)
네이버 지도	console.ncloud.com → Maps	월 100만건 무료 (기본 지도 엔진 — NAVER_MAPS_CLIENT_ID 설정 시. 미설정·인증 실패 시 Leaflet/OSM 자동 폴백)

3. 백엔드 실행

cd backend
npm install
node server.js
# → http://localhost:3001

4. 프론트엔드 실행

⚠ 먼저 알아야 할 것: 프론트는 API 를 상대경로(/api)로만 호출하고(frontend/index.html 의 DEFAULT_API = '/api'), 백엔드는 정적 파일을 서빙하지 않는다(backend/server.js 에 express.static 없음). 그래서 아래처럼 프론트만 다른 포트로 띄우면 모든 API 호출이 404 된다 — 같은 오리진이라 CORS 에러조차 뜨지 않고 화면만 비어 보인다.

정적 화면(레이아웃·스타일)만 확인할 때:

cd frontend
python3 -m http.server 3000
# → http://localhost:3000  (API 연동 기능은 동작하지 않음)

또는 VS Code Live Server / npx serve 사용 — 위 제약은 동일하다.

API 까지 붙여서 확인하려면 프론트와 API 가 같은 오리진이어야 한다. 프로덕션에서는 Vercel 이 그 역할을 한다(vercel.json route 룰). 로컬에서 같은 구성을 만드는 방법으로 vercel dev 가 있으나 이 저장소에서 실제로 돌려 확인한 적은 없다(확인되지 않음). 현재 전체 동작을 확실히 보려면 배포된 프리뷰/프로덕션 URL 에서 확인하는 것이 가장 확실하다.

5. 네이버 지도 (기본 지도 엔진)

프로덕션 기본 지도는 네이버 지도(NCP Web Dynamic Map) 다 — /api/health 가 내려주는 NAVER_MAPS_CLIENT_ID 로 SDK 를 로드한다(frontend NAVER-MAPS-2026-05-13 주석 참고). 키 미설정·SDK 인증 실패 시 Leaflet + OpenStreetMap 으로 자동 폴백하므로 키 없이도 로컬 개발이 가능하다(위성지도는 Esri World Imagery tile).

좌표는 엔진과 무관하게 카카오 좌표 검색/캐시(backend/services/geocodeCacheService.js)로 해석한다.

---

Vercel 배포 (frontend + backend 단일 함수)

운영 구조: Vercel single project. api/index.js 가 backend/server.js (Express 앱) 을 그대로 export → /api/*, /share/* 처리. 정적 자산 (frontend/*.html 등) 은 vercel.json route 룰로 직접 서빙. 즉, 프론트엔드와 백엔드가 같은 Vercel 함수 에서 동작 — 별도 백엔드 호스트 불필요.

npm i -g vercel
cd myhomelog
vercel              # 첫 배포 (preview)
vercel --prod       # 프로덕션 배포

# 커스텀 도메인 연결 (선택)
vercel domains add myhomelog.com

Vercel Dashboard → Settings → Environment Variables 등록 키:

• 필수 — ANTHROPIC_API_KEY, MOLIT_API_KEY, KAKAO_REST_API_KEY
• Supabase — SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY, SUPABASE_SERVICE_ROLE_KEY
• 선택 — UPSTASH_REDIS_REST_URL, UPSTASH_REDIS_REST_TOKEN (분산 rate-limit. 미설정 시 in-memory fallback)
• 운영 — CRON_SECRET (cron 인증), ADMIN_EMAILS (admin endpoint 화이트리스트), HEALTH_API_KEY, ALLOWED_ORIGINS
• 로컬 개발에서 frontend/index.html 의 API 상수는 /api 상대 경로 사용 — 별도 백엔드 URL 교체 불필요.

cron 은 vercel.json 의 crons 배열로 자동 등록됩니다 — retention · molit-ingest(3슬롯 분할) · apt-master-sync(월요일) · regulations-check · regulations-auto-fetch · audit-prune · geocache-backfill · facility-backfill · building-register-backfill · push-notify(관심단지 웹푸시·카톡 발송) · warm-interest · warm-rent. 목록은 vercel.json 을 참고하세요. (Hobby plan: daily 만 — hourly 미지원)

Railway 배포 (현재 미사용 — 옵션 메모)

⚠ 현재 운영 구조는 위 Vercel 단일 함수. 코드·설정에 Railway 흔적은 없으며 (railway.json 검사 시 fallback noop), 백엔드만 별도로 띄울 필요가 없습니다. 본 섹션은 향후 Vercel 함수 limit·cold start 등 사유로 백엔드를 분리하는 경우의 메모이며, 그대로 따라 하면 단일 배포가 깨집니다 — 이 sprint 시점엔 사용하지 마세요.

# (옵션) 백엔드 분리 시 — 현재 미사용
npm i -g @railway/cli
cd backend
railway login && railway init && railway up
railway variables set ANTHROPIC_API_KEY=sk-ant-... MOLIT_API_KEY=... KAKAO_REST_API_KEY=...
railway variables set ALLOWED_ORIGINS=https://myhomelog.vercel.app

---

API 엔드포인트

모든 마운트는 backend/server.js 에 정의됩니다. JWT = requireAuth (Supabase access_token 필수) · optional = 비로그인 허용 (로그인 시 daily limit bonus)

헬스

Method	Path	Auth	설명
GET	/api/health	optional	서버 상태
GET	/api/health/apis	x-health-key 헤더	외부 API 활성화 진단 (운영자 전용)

AI 비용 경로 (chat scope rate-limit + daily limit)

Method	Path	Auth	설명
POST	/api/chat	optional	AI 채팅 (PII 차단 + filterAdviceOutput)
POST	/api/clause	optional	맞춤 특약 + 리스크 통합 (Phase B-3)
POST	/api/clause/risk	optional	리스크 시나리오 (legacy)
POST	/api/report/generate	optional (비로그인 0/일 차단)	1Page 정리 보고서. server.js mount = optionalAuth + chatLimiter + dailyLimit{limit:0,scope:'report',loggedInBonus:1} — 비로그인은 0/일 → 사실상 로그인 필수, 로그인 시 dailyLimit 모듈이 plan별 한도 적용
POST	/api/feedback/ai	optional	답변 👍/👎

부동산 데이터

Method	Path	Auth	설명
POST	/api/properties/recommend	optional	조건 부합 단지 찾기 (추천 아님 — 입력 조건 필터링)
GET	/api/properties/nearby	optional	주변 단지
POST	/api/properties/transit	optional	교통 분석
GET	/api/transactions(?...)	—	실거래가 조회
GET	/api/transactions/analyze	—	실거래 통계
GET	/api/transactions/codes	—	시군구 코드
GET	/api/regulations	—	현행 규제 (LTV·DSR snapshot)
POST	/api/geocode, /api/geocode/batch	—	카카오 지오코딩
GET	/api/analysis	—	분석 결과
GET	/api/news, /api/news/summary	optional	부동산 뉴스
GET	/api/search/{apt,popular,in-bounds,facility}	—	단지 검색
POST·GET·DELETE	/api/search/history	JWT	본인 검색 이력

결제·구독·즐겨찾기

Method	Path	Auth	설명
GET	/api/billing/config, /api/billing/plans	—	Toss SDK 설정 / 플랜
GET·POST	/api/billing/{me,checkout,confirm,cancel}	JWT	결제 흐름
POST	/api/billing/webhook	Toss 서명	결제 webhook
GET	/api/subscription	—	구독 정보
GET·POST·PATCH·DELETE	/api/bookmarks(/...)	JWT	즐겨찾기
GET·PUT·DELETE	/api/field-notes(/...)	JWT	임장노트
GET·POST·PATCH·DELETE	/api/chat/sessions(/...)	JWT	채팅 세션·메시지

계정·자동화 결정 (PIPA / GDPR)

Method	Path	Auth	설명
POST	/api/account/consent	optional (비로그인 허용)	4 flag (만 14세·약관·개인정보·국외이전) 동의 시각/버전 audit_log 기록 — OAuth 시작 전 호출. 4 flag 모두 true 검증 실패 시 400
GET	/api/account/export	JWT	PIPA 35조 데이터 다운로드
GET	/api/account/deletion-status	JWT	삭제 예약 상태
POST	/api/account/delete	JWT	30일 유예 소프트 삭제
POST	/api/account/restore	JWT	유예기간 내 철회
GET	/api/account/automated-decision/explain	JWT	GDPR Art.22 / PIPA 37조의2 설명

운영자 전용

Method	Path	Auth	설명
GET·POST	/api/admin/run-geocache-backfill	JWT + ADMIN_EMAILS	백필 즉시 trigger
GET·POST	/api/cron/{...}	CRON_SECRET	vercel.json crons 자동 등록 (molit-ingest 는 3슬롯 분할, Hobby plan: daily 만) — 목록은 vercel.json 참조
GET	/share?...	—	공유 딥링크 (OG 메타 치환 HTML)

---

공개 페이지 (SSR · 정적 제공)

경로	설명
/apt/:seq	단지 상세 정보 페이지 (OG 메타 포함)
/region/:lawdCd	지역 시장 분석 페이지
/region	지역 선택 허브
/briefing	지역 시장 브리핑
/sitemap.xml	Google / Naver 사이트맵
/api/og/*	동적 OG 이미지 생성 (Open Graph)
/share	공유 링크 정적 HTML (메타 치환)

---

레퍼런스 & 차별화

서비스	타겟	차별화
호갱노노 / 네이버부동산	정보 탐색	내집로그: 판단 근거 정리(추천 아님)
내집스캔	전세 임차인	내집로그: 매수 검토자용 데이터 정리
KB부동산	시세 조회	내집로그: 가구 조건별 비용 정리 + 특약 초안