육전 (육아정보전쟁)

전국 학원/교습소를 아이 나이에 맞게 찾고, AI로 추천받는 모바일 교육정보 플랫폼

주요 기능

• 전국 32,000+ 교육기관 검색 (카카오맵 지도 + 카드/리스트)
• 14개 카테고리 (영유아 4개 포함), 복수 선택 + 반경 필터
• 자녀 나이 기반 카테고리 자동 정렬
• AI 맞춤 추천 (6단계 설문, OpenAI GPT-4o-mini)
• 리뷰/평점 + 댓글, 블로그 후기 링크
• 카카오 OAuth 로그인
• 학원 원장 인증 + 셀프 정보 등록
• 관리자 대시보드 (교육기관/리뷰/블로그/업체요청/원장인증 관리)
• 자동 크롤링 스케줄러 (APScheduler)

기술 스택

영역	기술
프론트엔드	Vite + React + TypeScript + Tailwind CSS + Zustand + TanStack Query
백엔드	FastAPI + SQLAlchemy + PostgreSQL
지도	카카오맵 API
AI	OpenAI GPT-4o-mini
인증	카카오 OAuth
크롤링	httpx + BeautifulSoup + APScheduler
배포	Cloudflare Tunnel + Docker

프로젝트 구조

dbrwjs/
├── client/              # 프론트엔드 (Vite + React)
│   ├── src/
│   │   ├── features/    # 기능별 모듈 (home, search, academy, ai, auth, my, admin)
│   │   ├── stores/      # Zustand 스토어
│   │   ├── api/         # API 클라이언트
│   │   └── shared/      # 공용 컴포넌트/훅/유틸
│   └── public/          # 정적 파일 (로고, favicon, robots.txt)
├── server/              # 백엔드 (FastAPI)
│   ├── app/
│   │   ├── domains/     # 도메인별 모듈 (academy, review, auth, ai, admin, owner, blog_review)
│   │   ├── common/      # 공통 (예외, 페이지네이션, 보안)
│   │   └── scheduler.py # APScheduler 크롤링 스케줄러
│   ├── crawlers/        # 크롤링 파이프라인
│   │   ├── sources/     # 카카오, 네이버, NEIS 크롤러
│   │   ├── parsers/     # 주소, 전화, 카테고리, 비용 파서
│   │   └── services/    # 지오코더, 중복감지, 신뢰도 점수
│   └── alembic/         # DB 마이그레이션
├── docs/                # 기획/설계 문서
├── docker-compose.yml   # PostgreSQL
└── cloudflared-config.yml # Cloudflare Tunnel

로컬 개발 환경 설정

1. 사전 요구사항

• Node.js 20+
• Python 3.12+
• Docker & Docker Compose
• uv (Python 패키지 매니저)
• pnpm (Node.js 패키지 매니저)

2. 저장소 클론

git clone https://github.com/work-jack/dbrwjs.git
cd dbrwjs

3. PostgreSQL 시작

docker compose up -d

포트: 5434 (기본 5432와 충돌 방지)

4. DB 복원 (덤프 파일 사용)

# 덤프 파일을 서버에서 복사한 경우
docker exec -i yukjeon-db psql -U yukjeon yukjeon < yukjeon_dump.sql

또는 빈 DB로 시작하려면:

cd server
cp .env.example .env
# .env에 API 키 설정 (아래 참고)
uv sync
uv run alembic upgrade head

5. 백엔드 설정

cd server
cp .env.example .env
# .env 파일 편집하여 API 키 입력
uv sync
uv run uvicorn app.main:app --port 8006 --reload

6. 프론트엔드 설정

cd client
cp .env.example .env
# .env 파일 편집
pnpm install  # 또는 npm install
npx vite --port 5173

7. 빌드 (프로덕션)

cd client
npx vite build
# 빌드된 파일은 client/dist/에 생성
# FastAPI가 자동으로 정적 파일 서빙

환경 변수

server/.env

# Database
DATABASE_URL=postgresql+asyncpg://yukjeon:yukjeon_dev@localhost:5434/yukjeon

# Security
SECRET_KEY=랜덤문자열

# CORS
CORS_ORIGINS=["http://localhost:5173"]

# OAuth - Kakao
KAKAO_CLIENT_ID=카카오_REST_API_키
KAKAO_CLIENT_SECRET=카카오_Client_Secret

# Crawling
KAKAO_REST_API_KEY=카카오_REST_API_키
NEIS_API_KEY=나이스_인증키

# AI
OPENAI_API_KEY=sk-...

# Scheduler
SCHEDULER_ENABLED=false

client/.env

VITE_API_BASE_URL=/api/v1
VITE_KAKAO_MAP_KEY=카카오_JavaScript_키
VITE_KAKAO_CLIENT_ID=카카오_REST_API_키

포트 구성

서비스	포트
PostgreSQL	5434
FastAPI	8006
Vite dev	5173

DB 덤프/복원

덤프 (서버에서)

docker exec yukjeon-db pg_dump -U yukjeon yukjeon > yukjeon_dump.sql

복원 (PC에서)

# 1. Docker Compose로 PostgreSQL 시작
docker compose up -d

# 2. DB가 준비될 때까지 대기
sleep 5

# 3. 덤프 파일 복원
docker exec -i yukjeon-db psql -U yukjeon yukjeon < yukjeon_dump.sql

데이터 확인

docker exec yukjeon-db psql -U yukjeon yukjeon -c "SELECT count(*) FROM academies;"
# 예상: 32,000+ 건

크롤링

cd server

# 카카오맵 크롤링 (지역별)
uv run python -m crawlers.runner --source kakao --region 서울특별시

# 네이버 크롤링
uv run python -m crawlers.runner --source naver --region 서울특별시

# NEIS 공공데이터 보강 (학원비, 대상 연령)
uv run python -m crawlers.neis_runner --all

# 전체 지역 목록: docs/crawling-regions.md 참고

Cloudflare Tunnel 배포

# 터널 설정 (최초 1회)
cloudflared tunnel login
cloudflared tunnel create yukjeon
cloudflared tunnel route dns yukjeon yukjeon.over-bit.com

# 실행
cloudflared tunnel --config ./cloudflared-config.yml --protocol http2 run yukjeon

테스트

cd server
uv run pytest tests/ -v

라이선스

Private - All rights reserved