내집로그 (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 키 발급
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부동산 | 시세 조회 | 내집로그: 가구 조건별 비용 정리 + 특약 초안 |
