diff --git a/README.md b/README.md index ebdea66..a0a7a2b 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,229 @@ -# SEMOSAN_BE +# SEMOSAN - 세모산 Backend -세모산 백엔드 레포지토리입니다. +세모산 앱 소개 + +
+ +> 등산이 처음이어도 괜찮아요. +> 내 체력과 취향에 맞는 코스를 찾고, 실시간 안내와 기록, 후기까지 +> 더 가볍고 안전한 등산을 세모산과 함께 시작하세요. + +
+ +## Architecture + +```mermaid +flowchart LR + APP[React Native App] --> API[Spring Boot API] + + API --> DB[(PostgreSQL + PostGIS)] + API --> REDIS[(Redis Stream)] + API --> MINIO[(MinIO)] + + API --> KAKAO[Kakao OAuth] + API --> FCM[Firebase FCM] + + PROM[Prometheus] -->|Scrape /actuator/prometheus| API +``` + +
+ +## API Docs + +| 구분 | URL | +|------|-----| +| Swagger UI | `http://localhost:8080/swagger-ui.html` | +| Health Check | `http://localhost:9090/actuator/health` | +| Prometheus | `http://localhost:9090/actuator/prometheus` | + +
+ +## 주요 기능 + + + + + + + + + + + + +
+ 정복 지도 +

+ 정복 지도 +
+ 사용자의 등산 기록과 정복한 산 데이터 제공 + 		+ 세모피드 +

+ 세모피드 +
+ 등산 후기 피드, 이모지 반응, 알림 API 제공 + 		+ 산 탐색 +

+ 산 목록 +
+ 산/코스 조회, 거리, 고도, 소요 시간 데이터 제공 +
+ GPS 트래킹 +

+ 실시간 GPS 트래킹 +
+ WebSocket 기반 위치 수집 및 트래킹 세션 관리 + 		+ 커뮤니티 +

+ 커뮤니티 +
+ 게시글, 댓글, 좋아요, 신고, 차단 기능 제공 + 		+ 내 기록 +

+ 마이페이지 +
+ 회원 정보, 등산 이력, 난이도 피드백 관리 +
+ +
## 기술 스택 +### Backend +- **Java 21** +- **Spring Boot 3.5.13** +- **Spring Web MVC** - REST API +- **Spring Security** - 인증/인가 +- **Spring Data JPA** - ORM +- **Spring Validation** - 요청 검증 + +### Database & Storage +- **PostgreSQL** +- **PostGIS** - 위치/공간 데이터 처리 +- **Flyway** - DB 마이그레이션 +- **Redis** - 캐시 및 트래킹 스트림 +- **MinIO** - 이미지 객체 스토리지 + +### 인증 & 외부 연동 +- **Kakao OAuth** +- **JWT** (`jjwt`) +- **Firebase Admin SDK** - FCM 푸시 알림 +- **Spring WebFlux WebClient** - 외부 API 호출 + +### 실시간 & 모니터링 +- **Spring WebSocket** + **STOMP** - 실시간 GPS 데이터 수신 +- **Spring Boot Actuator** +- **Prometheus** +- **Logstash Logback Encoder** - Loki 연동용 JSON 로그 + +### API 문서 +- **Springdoc OpenAPI / Swagger UI** + +
+ +## 프로젝트 구조 + +```text +src/main/java/com/semosan/api/ + ApiApplication.java + common/ # 공통 설정, 응답, 예외, JWT, FCM + domain/ + appversion/ # 앱 버전 관리 + auth/ # 인증, 회원 탈퇴 정리 + oauth/ # 카카오 OAuth 연동 + user/ # 회원, 온보딩, 차단 + mountain/ # 산/코스 조회, 코스 좋아요 + tracking/ # GPS 트래킹, WebSocket, 스케줄러 + hiking/ # 등산 기록, 난이도 피드백 + semofeed/ # 세모피드, 이모지, 알림 + community/ # 게시글, 댓글, 좋아요, 신고, 알림 + notification/ # 앱 알림 + image/ # 이미지 업로드 + review/ # 리뷰 도메인 + +src/main/resources/ + application.yaml # 공통 설정 + application-local.yaml # 로컬 프로필 설정 + application-prod.yaml # 운영 프로필 설정 + db/migration/ # Flyway 마이그레이션 + firebase/ # Firebase 서비스 계정 파일 + +k8s/ # Kubernetes 배포 리소스 +.github/workflows/ # GitHub Actions +``` + +
+ +## 시작하기 + +### 요구사항 + - Java 21 -- Spring Boot 3.5.13 - PostgreSQL + PostGIS - Redis +- MinIO +- Gradle Wrapper 사용 권장 ---- +### 설치 -## 브랜치 전략 +```bash +git clone https://github.com/SEMOSAN/SEMOSAN_BE.git +cd SEMOSAN_BE +``` + +### 로컬 실행 + +로컬 프로필은 기본값으로 활성화됩니다. + +```bash +./gradlew bootRun +``` + +### 테스트 + +```bash +./gradlew test +``` + +특정 테스트만 실행할 때는 다음 형식을 사용합니다. +```bash +./gradlew test --tests com.semosan.api.domain.mountain.service.MountainServiceTest ``` + +
+ +## 개발 규칙 + +- Java 21, Spring Boot 3.5.x 기준으로 개발합니다. +- 기능은 기존 `domain/*` 패키지 구조를 따릅니다. +- 공통 응답, 예외, 상태 코드는 `common/`의 기존 규칙을 우선 사용합니다. +- DB 스키마 변경은 `src/main/resources/db/migration/`에 Flyway 마이그레이션으로 추가합니다. +- 비즈니스 규칙, payload 생성, 검증 로직을 중복 작성하지 않습니다. +- 좁은 변경은 관련 테스트를 먼저 실행하고, 필요 시 전체 테스트를 실행합니다. +- 민감한 값은 커밋하지 않고 환경 변수 또는 배포 Secret으로 관리합니다. + +
+ +## 브랜치 전략 + +```text feat/#이슈번호-기능명 fix/#이슈번호-버그명 ``` -**예시** -``` +예시: + +```text feat/#12-mountain-search fix/#34-trail-query-bug ``` ---- +
## 커밋 컨벤션 @@ -37,50 +236,16 @@ fix/#34-trail-query-bug | `test` | 테스트 코드 | | `chore` | 빌드, 설정 변경 | -**예시** -``` +예시: + +```text feat: 산 검색 API 추가 fix: 등산로 조회 쿼리 오류 수정 ``` ---- +
## PR 규칙 - 리뷰어: 본인 제외 **2명 전원 승인** 후 머지 - 셀프 머지 금지 - ---- - -## Claude Code 사용 가이드 - -### 팀 공유 스킬 위치 - -팀에서 공유하는 커스텀 명령어(스킬)는 `.claude/commands/` 폴더에서 관리합니다. - -``` -.claude/ -└── commands/ - └── {스킬명}.md -``` - -### 스킬 추가하는 법 - -1. `.claude/commands/` 폴더에 `스킬명.md` 파일 생성 -2. 파일 안에 프롬프트 작성 -3. git에 커밋 후 push → 팀원들이 pull하면 자동으로 공유됨 - -**예시** `.claude/commands/review.md` -```markdown -이 PR의 코드를 리뷰해줘. -- 보안 취약점 확인 -- 네이밍 컨벤션 확인 -- 불필요한 코드 확인 -``` - -터미널에서 `/review` 로 호출 가능. - -### CLAUDE.md 관리 - -프로젝트 루트의 `CLAUDE.md`는 Claude Code가 자동으로 읽는 팀 공통 가이드입니다. -기술 스택, 컨벤션, 주의사항 등 Claude에게 알려줄 내용을 여기에 작성합니다. diff --git a/assets/screenshots/community.png b/assets/screenshots/community.png new file mode 100644 index 0000000..1bd7694 Binary files /dev/null and b/assets/screenshots/community.png differ diff --git a/assets/screenshots/home-feed.png b/assets/screenshots/home-feed.png new file mode 100644 index 0000000..2874f21 Binary files /dev/null and b/assets/screenshots/home-feed.png differ diff --git a/assets/screenshots/home-semofeed.png b/assets/screenshots/home-semofeed.png new file mode 100644 index 0000000..b094c0c Binary files /dev/null and b/assets/screenshots/home-semofeed.png differ diff --git a/assets/screenshots/mountains.png b/assets/screenshots/mountains.png new file mode 100644 index 0000000..4380f27 Binary files /dev/null and b/assets/screenshots/mountains.png differ diff --git a/assets/screenshots/mypage.png b/assets/screenshots/mypage.png new file mode 100644 index 0000000..6a67faa Binary files /dev/null and b/assets/screenshots/mypage.png differ diff --git a/assets/screenshots/semofeed.png b/assets/screenshots/semofeed.png new file mode 100644 index 0000000..b094c0c Binary files /dev/null and b/assets/screenshots/semofeed.png differ diff --git a/assets/screenshots/semosan.png b/assets/screenshots/semosan.png new file mode 100644 index 0000000..c35076d Binary files /dev/null and b/assets/screenshots/semosan.png differ diff --git a/assets/screenshots/tracking.png b/assets/screenshots/tracking.png new file mode 100644 index 0000000..4fb817f Binary files /dev/null and b/assets/screenshots/tracking.png differ