내방 (Naebang Real Estate)

서울 전월세/매매 매물을 지도 기반으로 탐색하고,
즐겨찾기·시장 동향·커뮤니티까지 한 번에 볼 수 있도록 만든 부동산 웹 서비스입니다.

이 레포지토리는 국비 지원 과정 팀 프로젝트 결과물을 포트폴리오용으로 정리한 것이며,
실제 서비스에 사용하는 API 키 / 대용량 실데이터는 포함하지 않습니다.

---

1. 프로젝트 개요

• 프로젝트명: 내방 (Naebang – ‘내 방을 찾는다’는 의미)

• 설명: 서울 지역 전·월세/매매 매물을 지도에서 직관적으로 탐색하고,
  시장 동향과 커뮤니티까지 한 번에 확인할 수 있는 웹 서비스

• 역할 및 담당 영역

  • 지도 기반 매물 페이지 map/ 전체 설계 및 구현
  • 시장 동향 시각화 페이지 estateData/ 설계 및 구현
  • 찜 목록 페이지 favorites/ 설계 및 구현
  • 서울 부동산 실거래 데이터 전처리(JSON 포맷 통일), 필터/정렬 로직, 공공데이터 정규화 모듈 구현

• 기술 스택

  • Frontend: HTML5, CSS, Vanilla JavaScript (ES6+)
  • 지도/공공데이터
    • Kakao Maps JavaScript SDK
    • VWorld 행정구역 경계 API
    • 공공데이터포털 서울 부동산 실거래 데이터 (전처리 후 JSON 사용)
  • 개발 환경: Git, GitHub, VS Code, Live Server

---

2. 주요 기능

2-1. 지도 기반 매물 탐색 (map/)

• 카카오맵 위에 서울 전역 매물을 마커/클러스터로 표시
• 구/동 선택, 방 종류, 거래 유형(전세/월세/매매), 가격·면적 필터로 실시간 필터링
• VWorld 경계 데이터를 이용해 구/동 폴리곤 시각화
• 리스트와 지도 클릭을 서로 연동하여,
  한쪽에서 매물을 선택하면 다른 쪽에서도 동일 매물이 강조되도록 구현

2-2. 찜(즐겨찾기) 목록 (map/, favorites/)

• 지도/목록에서 하트 아이콘으로 매물 찜/해제
• 브라우저 LocalStorage 기반으로 즐겨찾기 상태 유지
• favorites/ 별도 페이지에서 찜한 매물만 모아보기 지원
• “찜 목록만 보기” 필터 토글 제공 (지도 화면과 연동)

2-3. 시장 동향 페이지 (estateData/)

• 최근 3년간 서울 부동산 실거래/전월세 데이터를 JSON으로 전처리
• 아파트/오피스텔/단독·다가구/연립·다세대 등 주택 유형별 거래량·가격 추이 시각화
• 매매·전월세 구분, 구 단위 필터, 기간 필터를 통해 시장 흐름 파악 가능
• 공공데이터 형식이 제각각인 것을 단일 포맷으로 정규화하는 모듈 작성

2-4. 로그인/회원가입 UI (login/)

• 로그인, 회원가입, 비밀번호 찾기/변경 플로우 프론트엔드 UI 구현
• 향후 백엔드/API 연동을 고려하여 폼 구조와 검증 로직을 분리

2-5. 커뮤니티 & 고객센터 (board/, policy/, 꿀팁 관련 폴더)

• 자유게시판, 1:1 문의 페이지
• 이용약관, 개인정보처리방침, 커뮤니티 가이드라인, 자주 묻는 질문(FAQ)
• 자취/부동산 관련 꿀팁 콘텐츠 페이지 (다수의 정적 HTML/CSS/JS 파일로 구성)

---

3. 폴더 구조 (요약)

실제 레포지토리 전체 파일을 모두 나열하기보다는, 상위 폴더와 직접 구현한 핵심 기능 중심으로 정리했습니다.

PROJECT/
 ┣ main/             # 메인 랜딩 페이지
 ┣ map/              # 지도 기반 매물 탐색
 ┣ estateData/       # 시장 동향 시각화
 ┣ favorites/        # 찜 목록 페이지
 ┣ login/            # 로그인/회원가입/비밀번호 변경 UI
 ┣ board/            # 자유게시판, 1:1 문의
 ┣ policy/           # 이용약관, 개인정보처리방침, FAQ 등
 ┣ 꿀팁css/          # 자취/부동산 꿀팁 페이지 스타일
 ┣ 꿀팁html/         # 자취/부동산 꿀팁 콘텐츠
 ┣ 꿀팁js/           # 일부 꿀팁 페이지 인터랙션 스크립트
 ┣ img/              # 로고, 이미지 등 정적 리소스
 ┗ videos/           # 시연용 영상 (스톡 리소스, .gitignore 처리 가능)

아래는 세 영역의 내부 구조를 간단히 예시로 정리한 것입니다.

map/
 ┣ map.html
 ┣ style.css
 ┗ js/
    ┣ config.js      # 필터 옵션, 전역 상태, Kakao & VWorld 설정
    ┣ map.js         # Kakao 지도 초기화, 마커·클러스터 관리
    ┣ ui.js          # 리스트/지도 연동, 사이드바 UI
    ┣ vworld.js      # VWorld 경계 조회, 폴리곤 렌더링
    ┣ auth-favorites.js
    ┣ filter-modal.js
    ┗ utils.js 등

estateData/
 ┣ estateData.html
 ┣ style.css
 ┗ js/
    ┣ api.js         # 공공데이터 정규화/파싱 모듈
    ┣ config.js      # 구 코드 매핑, 데이터 소스, 단위 변환 상수
    ┣ main.js        # 동향 페이지 메인 로직
    ┗ ui.js          # 필터·차트·통계 UI

favorites/
 ┣ favorites.html
 ┣ favorites-page.js # LocalStorage 기반 찜 목록 렌더링
 ┗ style.css

---

4. 담당 기능 상세

※ 아래 내용은 지도/시장 동향/찜 기능 구현을 중심으로 정리했습니다.

4-1. 지도/매물 페이지 (map/)

map.html

• 헤더/내비게이션, 왼쪽 방 유형 탭
• 중앙 지도 영역 + 우측 매물 리스트, 상단 필터/검색 UI 레이아웃

<!-- 공개 레포용: 실제 키 대신 PLACEHOLDER 사용 -->
<script src="//dapi.kakao.com/v2/maps/sdk.js?appkey=__KAKAO_MAP_KEY__&libraries=clusterer"></script>

js/config.js

• Kakao Maps, VWorld 설정 (도메인, BASE URL, 키 플레이스홀더 등)
• 매물/지역 데이터 파일 경로
• 현재 선택된 구/동, 거래 유형, 가격/면적 범위, 단위(㎡/평) 등 전역 상태 관리
• 보증금·월세·면적 구간 등 필터 옵션 상수 정의 → UI/로직 간 재사용

js/vworld.js

• VWorld 행정구역 경계 API 연동
• 구/동 이름으로 경계를 조회하고, 폴리곤을 캐시하여 지도에 하이라이팅
• 확대 레벨/선택 상태에 따라 폴리곤 스타일 변경

js/map.js, js/main.js, js/ui.js, js/utils.js, js/auth-favorites.js, js/filter-modal.js

• 지도 초기화, 마커/클러스터 생성 및 갱신
• 지역/카테고리/필터 변경 시 매물 리스트와 마커를 동시에 업데이트
• 매물 클릭 시 해당 마커를 강조하고, 사이드바에서 위치로 스크롤
• 찜(즐겨찾기) 추가/삭제 및 “찜 목록만 보기” 토글
• 공통 유틸 함수(숫자 포맷, 평↔㎡ 단위 변환 등)
• 향후 로그인 기능 연동을 고려한 auth-favorites 구조 설계

---

4-2. 시장 동향 페이지 (estateData/)

js/config.js

• 서울 25개 구 코드 ↔ 이름 매핑 (SEOUL_GU_MAP)
• 데이터 파일 목록(DATA_SOURCES), 단위 변환 상수 등 정의

js/api.js

• 공공데이터에서 내려오는 서로 다른 JSON 포맷을 공통 스키마(매물 타입, 거래 타입, 날짜, 가격, 면적, 층수 등)로 정규화
• parsePrice, buildDateStr, extractGuInfo, extractCommonFields 등 유틸 함수 구현
• 매매/전월세 케이스별 가격 계산 로직 분리
• 데이터 로딩 중 일부 파일에서 오류가 발생해도, 그 외 파일은 계속 처리하도록 방어적 예외 처리 적용

js/main.js, js/ui.js, style.css

• 구/유형/기간 선택에 따라 차트·통계 영역을 동적으로 갱신
• 거래량·평균가 등 핵심 지표를 카드/테이블로 요약
• 다양한 화면 크기를 고려한 반응형 레이아웃 구성

---

4-3. 찜 목록 페이지 (favorites/)

favorites.html, favorites-page.js, style.css

• map/에서 설정한 LocalStorage 기반 찜 데이터를 그대로 사용
• 찜한 매물만 리스트로 렌더링하고, 필요시 정렬/필터(가격, 면적, 지역 등)를 적용할 수 있도록 구성
• 지도 페이지와 찜 상태가 일관되게 유지되도록 설계

---

5. 보안/데이터 관련 안내

5-1. API 키

• Kakao Maps, VWorld API 키는 소스 코드에 직접 포함하지 않습니다.
• 레포지토리에는 __KAKAO_MAP_KEY__, __VWORLD_KEY__ 와 같은 플레이스홀더만 남겨두었습니다.
• 실제 로컬 실행 시에는 개인 키를 별도 로컬 스크립트에서 window.KAKAO_MAP_KEY, window.VWORLD_KEY 등으로 주입해 사용할 수 있습니다.

5-2. 부동산 원본 데이터

• 용량이 크고 공개에 민감할 수 있어, 실제 실거래 JSON/매물 전체 데이터는 GitHub에 포함하지 않았습니다.
• .gitignore로 아래 경로를 제외하도록 설정했습니다.

map/rooms-all.json
map/region-tree-seoul.json
estateData/data/
videos/

• 개발 시에는 위와 같은 경로 구조로 JSON 파일을 로컬에 두고 지도·차트 기능을 구현했습니다.
  공개 레포지토리에는 보안을 위해 해당 데이터 파일을 포함하지 않았습니다.

---

6. 설계/구현 포인트

6-1. 모듈 분리 & 상태 관리

• config.js에서 전역 상태와 상수를 관리하고, 지도 로직(map.js), UI 로직(ui.js), 데이터 로딩(vworld.js, api.js, utils.js)을 분리하여 역할이 명확한 구조를 만들었습니다.
• 필터 조건, 단위 변환, 구/동 정보 등은 한 곳에서 관리해 유지보수성을 높였습니다.

6-2. 이질적인 공공데이터 정규화

• 공공데이터 API/파일 형식이 제각각이라, api.js에서 카테고리별 공통 포맷으로 정리하는 모듈을 직접 설계·구현했습니다.
• 잘못된 숫자/날짜/코드를 방어적으로 처리하여, 차트/필터에서 안전하게 사용할 수 있도록 했습니다.

6-3. 사용자 경험(UX)

• 지도와 리스트가 양방향으로 연동되도록 설계하여, 지도를 클릭해도, 리스트를 클릭해도 항상 같은 매물이 강조되도록 구현했습니다.
• 필터 모달에서 지역/거래유형/가격/면적 필터를 한 번에 설정하고 적용할 수 있게 하여, 실제 부동산 앱과 유사한 UX를 목표로 했습니다.
• 찜 목록을 별도 페이지로 분리하면서도, 지도 페이지와 찜 상태가 자연스럽게 이어지도록 데이터 구조를 맞춰 두었습니다.

6-4. 실무를 의식한 코드 스타일

• 'use strict' 사용, 의미 있는 변수/함수명, 한글 주석 정리
• 예외 상황(데이터 누락, API 실패 등)에서 전체 앱이 멈추지 않도록 try/catch와 콘솔 로그로 오류를 방어적으로 처리
• 나중에 백엔드(API 서버)와 연동하기 쉬운 형태로 데이터 포맷, 상태 구조, 파일 분리를 설계했습니다.

---

7. 앞으로의 확장 아이디어

• 백엔드(API 서버)와 DB(MySQL/PostgreSQL 등)를 연동하여 실제 회원/매물/게시글 데이터를 관리
• JWT 기반 인증, 소셜 로그인 연동
• 반응형 모바일 UI 고도화 및 접근성(Accessibility) 개선
• 매물 상세 페이지(사진, 옵션, 주변 편의시설 등)와 추천 알고리즘 추가
• 실시간 채팅/문의, 중개사 전용 대시보드 등으로 기능 확장
• 데이터 업데이트 자동화(크론 잡/스케줄러) 및 실시간 가격 알림 기능 추가