🎣 해루핸 (Haeruhand) - 안전한 해루질 서비스

공통프로젝트 진행상황 요약

핵심 기능의 개발이 프론트/백엔드 각자 완료되었으며, 연동작업을 진행중입니다.
이번주 주말까지 핵심 기능의 MVP 개발을 완료하고 테스트를 진행할 예정입니다.

해루핸 소개 영상

클릭하세요

해루핸 확인 링크

앱 다운로드(apk, android 전용)
Mobile Web -> 크롬 환경 권장

📋 목차

프로젝트 소개
핵심 기능
시스템 아키텍처
기술 스택
API 명세

🎯 프로젝트 소개

해루핸(Haeruhand)는 해루질을 하고 싶어하는 초보자를 위한 종합 스마트 서비스 플랫폼입니다. 실시간 위치 공유, AI 기반 어종 판별, 금어기 정보 제공, 해양 기상 정보 등 해루질에 필요한 모든 정보를 한 곳에서 제공합니다.

프로젝트 목표

안전한 해루질 활동 지원을 위한 실시간 위치 공유 시스템
AI 기술을 활용한 즉각적인 어종 판별 및 금어기 정보 제공
해양 기상 특보 알림을 통한 사고 예방
해루질 관련 법규 준수를 위한 정보 제공

🚀 핵심 기능

시연 영상

해루핸 야외 시연 영상

1. 🗺️ 실시간 위치 공유 시스템

WebSocket/STOMP 기반 실시간 통신
최대 4명까지 동시 위치 공유
호스트 기반 방 관리 시스템
딥링크를 통한 간편한 방 참가
멤버별 색상 구분 시스템

동영상 보기

2. 🤖 AI 어종 판별 시스템

FastAPI AI 서버 연동
이미지 업로드 → 어종 자동 판별
판별된 어종의 금어기 정보 즉시 제공

3. 🚫 금어기 정보 관리

어종별 포획 금지 기간 DB
지역별(권역별) 차별화된 금어기 적용
최소 체장/체중 제한 정보 제공
실시간 금어기 위반 여부 판별

4. 📱 푸시 알림 시스템

Firebase Cloud Messaging (FCM) 기반
동료 이탈 알림
해양 기상 특보 알림
다중 디바이스 지원

5. 🌊 해양 정보 제공

조수 정보 (만조/간조 시간)
기상 특보 (강풍, 풍랑 등)
어장 정보 (위치, 편의시설)

6. 🔐 보안 인증 시스템

Kakao OAuth 2.0 소셜 로그인
JWT 기반 인증 (Access Token + Refresh Token)
Redis 기반 토큰 관리

🏗️ 시스템 아키텍처

백엔드 아키텍처 - 도메인 중심 설계 (DDD)

backend/spring-business/haeruhand/
└── src/main/java/com/ssafy/haeruhand/
    ├── domain/
    │   ├── user/          # 사용자 관리
    │   ├── location/      # 실시간 위치 공유
    │   ├── fish/          # 어종 및 금어기
    │   ├── ai/            # AI 어종 판별
    │   ├── notification/  # 푸시 알림
    │   ├── fishery/       # 어장 정보
    │   ├── marine/        # 해양 정보
    │   └── weather/       # 날씨 정보
    └── global/            # 공통 설정 및 유틸리티
        ├── config/        # 설정 클래스
        ├── jwt/           # JWT 관련
        ├── websocket/     # WebSocket 설정
        └── exception/     # 예외 처리

프론트엔드 아키텍처 - Atomic Design Pattern

frontend/
└── src/
    ├── components/
    │   ├── atoms/          # 기본 UI 요소
    │   │   ├── Button/
    │   │   ├── Input/
    │   │   ├── Text/
    │   │   └── Icon/
    │   └── molecules/      # 복합 컴포넌트
    │       ├── Card/
    │       ├── Form/
    │       ├── Header/
    │       └── Modal/
    ├── pages/              # 페이지 컴포넌트
    │   ├── MainPage/       # 메인 화면
    │   ├── LoginPage/      # 로그인
    │   ├── WeatherAlertPage/ # 날씨 알림
    │   ├── LocationSharePage/ # 위치 공유
    │   ├── FishDetectPage/ # 어종 판별
    │   ├── FisheryMapPage/ # 어장 지도
    │   └── NotificationPage/ # 알림 설정
    ├── routes/             # 라우팅 설정
    ├── api/                # API 통신
    ├── hooks/              # 커스텀 훅
    ├── stores/             # 전역 상태 관리
    ├── types/              # TypeScript 타입 정의
    └── utils/              # 유틸리티 함수

🛠️ 기술 스택

Backend

Spring Boot 3.5.4 - 최신 버전 적용
Java 17 - LTS 버전
Spring Data JPA - ORM
Spring Security - 보안
Spring WebSocket - 실시간 통신
MySQL - 주 데이터베이스
Redis - 캐싱 및 세션 관리
Firebase Admin SDK - FCM 푸시 알림
Google Cloud Storage - 이미지 저장소
Kakao OAuth 2.0 - 소셜 로그인
FastAPI - AI 서버 연동
Swagger/OpenAPI 3.0 - API 문서화
Lombok - 코드 간소화
JWT (io.jsonwebtoken) - 토큰 관리

Frontend

React 19.1.0 - 최신 버전 UI 라이브러리
TypeScript 5.8.3 - 타입 안정성
Vite 7.0.4 - 빠른 빌드 도구
Capacitor 7.4.2 - 크로스 플랫폼 모바일 앱
TanStack Router - 타입 안전 라우팅
TanStack Query - 서버 상태 관리
Zustand - 클라이언트 상태 관리
Axios - HTTP 클라이언트
CSS Modules - 스타일 캡슐화
React Hook Form - 폼 관리
Framer Motion - 애니메이션
Socket.io Client - WebSocket 통신

📡 API 명세

인증 관련 API

Method	Endpoint	Description
POST	`/v1/user/issue/kakao`	카카오 OAuth 로그인
POST	`/v1/user/reissue`	토큰 재발급
GET	`/v1/user/userinfo`	사용자 정보 조회

위치 공유 API

Method	Endpoint	Description
POST	`/v1/location/rooms`	위치 공유 방 생성
GET	`/v1/location/rooms/{roomCode}`	방 정보 조회
DELETE	`/v1/location/rooms/{roomCode}`	방 강제 종료

WebSocket 엔드포인트

Endpoint	Description
`/v1/ws`	WebSocket 연결
`/pub/location.join`	방 참가
`/pub/location.update`	위치 업데이트
`/pub/location.leave`	방 퇴장
`/sub/location.{roomCode}`	방 구독

AI 어종 판별 API

Method	Endpoint	Description
POST	`/v1/seafood-detect`	어종 판별 요청
POST	`/v1/storage/signed-urls`	이미지 업로드 URL 생성

알림 관련 API

Method	Endpoint	Description
POST	`/v1/notifications/tokens`	FCM 토큰 등록
PUT	`/v1/notifications/tokens/{tokenId}`	FCM 토큰 갱신
DELETE	`/v1/notifications/tokens/{tokenId}`	FCM 토큰 삭제

🔐 보안 및 인증

JWT 토큰 구조

{
  "accessToken": {
    "expiry": "1시간",
    "usage": "API 요청 인증"
  },
  "refreshToken": {
    "expiry": "7일",
    "usage": "Access Token 갱신",
    "storage": "Redis"
  },
  "joinToken": {
    "expiry": "30분",
    "usage": "위치 공유 방 참가"
  }
}

보안 특징

Redis 기반 Refresh Token 관리

API 문서

서버 실행 후 Swagger UI 접속:

http://haeruhand.o-r.kr/api/swagger-ui/index.html

📱 모바일 앱 지원

크로스 플랫폼 지원

Capacitor 7.4.2 기반 하이브리드 앱
iOS/Android 네이티브 앱 빌드 지원
Progressive Web App (PWA) 대응

네이티브 기능 연동

GPS/위치 서비스 - 실시간 위치 추적
카메라 - 어종 촬영 및 판별
푸시 알림 - FCM 연동
딥링크 - 앱 간 연동 (seafeet://)
로컬 스토리지 - 오프라인 데이터 저장

📊 성능 최적화

백엔드 최적화

STOMP 프로토콜 사용으로 메시지 라우팅 효율화
배치 처리를 통한 위치 데이터 저장 최적화
@Async 어노테이션을 통한 FCM 알림 비동기 전송

프론트엔드 최적화

Code Splitting - 라우트 기반 코드 분할
Lazy Loading - 컴포넌트 지연 로딩
이미지 최적화 - WebP 포맷 및 responsive images
Virtual Scrolling - 대량 데이터 렌더링 최적화
React.memo - 불필요한 리렌더링 방지

Name		Name	Last commit message	Last commit date
Latest commit History 658 Commits
.gitlab/merge_request_templates		.gitlab/merge_request_templates
.vscode		.vscode
backend		backend
docker		docker
exec		exec
frontend		frontend
sub_pjt_1		sub_pjt_1
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitlab-ci.yml		.gitlab-ci.yml
Jenkinsfile		Jenkinsfile
README.md		README.md
image.png		image.png
optimized_gemini_review.py		optimized_gemini_review.py

Folders and files

Latest commit

History

Repository files navigation

🎣 해루핸 (Haeruhand) - 안전한 해루질 서비스

공통프로젝트 진행상황 요약

해루핸 소개 영상

해루핸 확인 링크

📋 목차

🎯 프로젝트 소개

프로젝트 목표

🚀 핵심 기능

시연 영상

1. 🗺️ 실시간 위치 공유 시스템

2. 🤖 AI 어종 판별 시스템

3. 🚫 금어기 정보 관리

4. 📱 푸시 알림 시스템

5. 🌊 해양 정보 제공

6. 🔐 보안 인증 시스템

🏗️ 시스템 아키텍처

백엔드 아키텍처 - 도메인 중심 설계 (DDD)

프론트엔드 아키텍처 - Atomic Design Pattern

🛠️ 기술 스택

Backend

Frontend

📡 API 명세

인증 관련 API

위치 공유 API

WebSocket 엔드포인트

AI 어종 판별 API

알림 관련 API

🔐 보안 및 인증

JWT 토큰 구조

보안 특징

API 문서

📱 모바일 앱 지원

크로스 플랫폼 지원

네이티브 기능 연동

📊 성능 최적화

백엔드 최적화

프론트엔드 최적화

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages