Skip to content

README.md

Latest commit

 

History

History
246 lines (204 loc) · 8.49 KB

README.md

File metadata and controls

246 lines (204 loc) · 8.49 KB

K-Mate

한국의 다양한 매력을 공유하는 소셜 플랫폼

🚀 주요 기능

🗺️ K-Map - 한국 관광지 지도 서비스

  • Google Maps API 기반 인터랙티브 지도
  • Google Places API 연동 장소 검색
  • 카테고리별 장소 필터링 (여행지, 맛집, 카페)
  • 장소 상세 정보 조회 (운영시간, 전화번호, 웹사이트)
  • 장소 북마크 기능
  • 위치 기반 근처 장소 검색

📱 K-Buzz - 소셜 커뮤니티 플랫폼

  • community: 사용자 자유 게시판
    • 게시글 작성/수정/삭제
    • 댓글 시스템
    • 좋아요/스크랩 기능
    • 카테고리별 분류 (여행팁, 맛집리뷰, 카페리뷰, 일반)
  • trend: 트렌드 게시글 (관리자 전용)
    • 관리자만 작성/수정 가능
    • 좋아요/스크랩 기능
  • tips: 여행 팁 게시글 (관리자 전용)
    • 관리자만 작성/수정 가능
    • 댓글 기능 없음

👤 마이페이지 - 개인 활동 관리

  • 사용자 활동 통계 (게시글, 댓글, 좋아요, 스크랩 수)
  • 북마크한 장소 목록 조회
  • 스크랩한 게시글 목록 조회
  • 작성한 게시글 목록 조회
  • 작성한 댓글 목록 조회

🔐 인증 시스템

  • Google OAuth 2.0 소셜 로그인
  • JWT 토큰 기반 인증
  • HttpOnly 쿠키 보안
  • 역할 기반 접근 제어 (user/admin)
  • 자동 토큰 갱신 지원

🛠️ 기술 스택

Backend

  • NestJS 11 - Node.js 프레임워크
  • TypeORM - ORM (MySQL)
  • Passport - 인증 미들웨어
  • JWT - 토큰 기반 인증
  • Google OAuth 2.0 - 소셜 로그인
  • Swagger - API 문서화
  • MySQL 8.0 - 데이터베이스

Frontend

  • React 19 - UI 라이브러리
  • TypeScript - 타입 안전성
  • Vite - 빌드 도구
  • Tailwind CSS 4 - 스타일링
  • React Router 7 - 라우팅
  • Zustand - 상태 관리
  • TanStack Query - 서버 상태 관리
  • Google Maps API - 지도 서비스

📁 프로젝트 구조

K-Mate/
├── server/                     # NestJS 백엔드
│   ├── src/
│   │   ├── features/           # 기능별 모듈
│   │   │   ├── auth/           # 인증 모듈 (Google OAuth + JWT)
│   │   │   ├── places/         # 장소 관리 모듈
│   │   │   ├── posts/          # 게시글 관리 모듈
│   │   │   ├── comments/       # 댓글 관리 모듈
│   │   │   ├── interactions/   # 상호작용 관리 모듈
│   │   │   └── mypage/         # 마이페이지 모듈
│   │   ├── database/           # DB 설정
│   │   ├── common/             # 공통 유틸리티
│   │   │   ├── decorators/     # 커스텀 데코레이터
│   │   │   └── guards/         # 인증/권한 가드
│   │   └── main.ts             # 애플리케이션 진입점
│   └── database/
│       └── migrations/         # DB 마이그레이션
│           ├── 001_create_initial_schema.sql
│           ├── 002_create_triggers.sql
│           ├── 003_create_views.sql
│           └── 004_insert_sample_data.sql
├── client/                     # React 프론트엔드
│   ├── src/
│   │   ├── features/           # 기능별 훅/스토어
│   │   │   └── auth/           # 인증 관련 상태 관리
│   │   ├── components/         # UI 컴포넌트
│   │   │   ├── common/         # 공통 컴포넌트
│   │   │   ├── layout/         # 레이아웃 컴포넌트
│   │   │   └── places/         # 장소 관련 컴포넌트
│   │   ├── pages/              # 페이지 컴포넌트
│   │   │   ├── KBuzz/          # K-Buzz 관련 페이지
│   │   │   ├── KmapPage.tsx    # K-Map 페이지
│   │   │   ├── KBuzzPage.tsx   # K-Buzz 메인 페이지
│   │   │   └── LoginPage.tsx   # 로그인 페이지
│   │   ├── api/                # API 클라이언트
│   │   ├── types/              # TypeScript 타입 정의
│   │   └── styles/             # 스타일 파일
│   └── public/
├── infrastructure/             # 배포 인프라
│   ├── nginx/                  # Nginx 설정
│   ├── scripts/                # 배포 스크립트
│   └── systemd/                # 서비스 설정
└── report/                     # 프로젝트 문서
    ├── requirements_specification.md
    └── README.md

🔧 설치 및 실행

환경 설정

# 서버 환경변수 설정
cp server/.env.example server/.env

# 클라이언트 환경변수 설정
cp client/.env.example client/.env

데이터베이스 설정

# MySQL 데이터베이스 생성
mysql -u root -p
CREATE DATABASE kmate_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# 마이그레이션 실행
mysql -u root -p kmate_db < server/database/migrations/001_create_initial_schema.sql
mysql -u root -p kmate_db < server/database/migrations/002_create_triggers.sql
mysql -u root -p kmate_db < server/database/migrations/003_create_views.sql
mysql -u root -p kmate_db < server/database/migrations/004_insert_sample_data.sql

개발 서버 실행

# 백엔드 서버 실행
cd server
npm install
npm run start:dev

# 프론트엔드 서버 실행 (새 터미널)
cd client
npm install
npm run dev

🔐 인증 시스템

  • Google OAuth 2.0 기반 소셜 로그인
  • JWT 토큰 기반 인증
  • HttpOnly 쿠키 보안
  • 자동 토큰 갱신 지원
  • 역할 기반 접근 제어 (user/admin)

📊 K-Buzz 기능

게시글 타입

  • community: 모든 사용자 자유 게시판
  • trend: 트렌드 게시글 (관리자만 작성/수정)
  • tips: 여행 팁 게시글 (관리자만 작성/수정)

주요 기능

  • 게시글 CRUD: 타입별 권한 제어
  • 댓글 시스템: community/trend 게시글에만 허용
  • 상호작용: 좋아요/스크랩 토글 기능
  • 카테고리 분류: 여행, 맛집, 카페, 일반
  • 검색 및 필터링: 게시글 검색 기능
  • 페이지네이션: 대용량 데이터 처리

🗺️ K-Map 기능

  • Google Maps API 연동
  • Google Places API 장소 검색
  • 관광지 마커 표시
  • 장소 상세 정보 조회
  • 장소 북마크 기능
  • 위치 기반 서비스
  • 지도 스타일링

📱 마이페이지 기능

  • 사용자 활동 통계 조회
  • 북마크한 장소 목록
  • 스크랩한 게시글 목록
  • 작성한 게시글 목록
  • 작성한 댓글 목록

🗄️ 데이터베이스 구조

주요 테이블

  • users: 사용자 정보 (Google OAuth)
  • places: 장소 정보 (Google Places API 연동)
  • posts: 게시글 (community/trend/tips 통합)
  • comments: 댓글
  • interactions: 상호작용 (like/scrap/bookmark)

데이터베이스 뷰

  • community_posts: 커뮤니티 게시글 뷰
  • tips_posts: 팁 게시글 뷰
  • trend_posts: 트렌드 게시글 뷰
  • user_interaction_stats: 사용자 활동 통계
  • post_interaction_stats: 게시글 상호작용 통계

비즈니스 규칙 트리거

  • 게시글 작성 권한: tips/trend는 관리자만 작성/수정
  • 댓글 작성 제한: community/trend 게시글에만 허용
  • 상호작용 정책: like/scrap은 community/trend 게시글에만 허용

🚀 배포

AWS Amplify 배포

# amplify.yml 설정 확인
# 자동 배포 설정됨

인프라 구성

  • Nginx: 리버스 프록시 및 정적 파일 서빙
  • Systemd: 서비스 관리
  • 배포 스크립트: 자동화된 배포 프로세스

📝 API 문서

개발 서버 실행 후 http://localhost:3000/docs에서 Swagger API 문서 확인 가능

주요 API 엔드포인트

  • 인증: /auth/* - Google OAuth, JWT 토큰 관리
  • 장소: /places/* - 장소 검색, 상세 정보, 북마크
  • 게시글: /posts/* - 게시글 CRUD, 검색, 필터링
  • 댓글: /comments/* - 댓글 CRUD
  • 상호작용: /interactions/* - 좋아요/스크랩 토글
  • 마이페이지: /mypage/* - 사용자 활동 통계 및 목록

🤝 기여하기

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request