시흥 커뮤니케이션 웹사이트

시흥시민을 위한 통합 커뮤니케이션 플랫폼입니다. 지역 정보, 커뮤니티, 실시간 채팅, 분실물 센터 등 다양한 기능을 제공합니다.

📋 목차

• 기술 스택
• 주요 기능
• 프로젝트 구조
• 시작하기
• 개발 가이드
• 빌드 및 배포
• 문제 해결

🛠 기술 스택

핵심 기술

• React 18.3.1 - UI 라이브러리
• TypeScript - 타입 안정성
• Vite 6.3.5 - 빌드 도구 및 개발 서버
• React SWC - 빠른 컴파일러

상태 관리

• Zustand - 경량 상태 관리 라이브러리

UI 컴포넌트

• Radix UI - 접근성 우선 UI 컴포넌트 라이브러리
• Tailwind CSS - 유틸리티 기반 CSS 프레임워크
• Lucide React - 아이콘 라이브러리
• shadcn/ui - 재사용 가능한 UI 컴포넌트

통신 및 데이터

• Axios - HTTP 클라이언트
• STOMP.js - WebSocket 통신 (실시간 채팅)
• SockJS - WebSocket 폴백

기타 라이브러리

• React Hook Form - 폼 관리
• Recharts - 차트 및 데이터 시각화
• React Day Picker - 날짜 선택기
• Sonner - 토스트 알림

✨ 주요 기능

1. 홈 화면

• 대시보드 형태의 메인 페이지
• 주요 기능 카드 네비게이션
• 문화행사 캘린더 미리보기
• 공개 통계 (게시글 수, 진행중인 축제 수)

2. 인증 시스템

• 회원가입 / 로그인
• 아이디 / 비밀번호 찾기
• JWT 토큰 기반 인증
• 자동 토큰 만료 처리
• 프로필 관리 (이미지 업로드 포함)

3. 문화행사 정보

• 경기 지역 문화행사 목록 조회
• 캘린더를 통한 행사 일정 확인
• 행사 상세 정보 (날짜, 장소, 시간, 비용 등)
• 날짜별 필터링

4. 시흥 관광 지도

• 카카오맵 연동
• 관광지 및 명소 표시
• 지도 기반 정보 탐색

5. 커뮤니티

• 게시글 작성/수정/삭제
• 카테고리별 게시글 분류
• 댓글 기능
• 좋아요 기능
• 이미지 업로드 지원
• 검색 기능

6. 실시간 채팅

• 1:1 개인 채팅
• 그룹 채팅
• WebSocket 기반 실시간 메시징
• 이미지 전송 지원
• 읽음 확인 기능

7. 분실물 센터

• 분실물 / 습득물 등록
• 카테고리별 분류
• 이미지 업로드
• 상태 관리 (검색중/발견됨/반환됨)
• 채팅 연동 (습득자와 연락)

8. 마이페이지

• 사용자 프로필 관리
• 프로필 이미지 업로드
• 개인 정보 수정
• 통계 정보

📁 프로젝트 구조

frontend/
├── build/                  # 빌드 결과물
├── node_modules/           # 의존성 패키지
├── public/                 # 정적 파일
├── src/
│   ├── components/         # React 컴포넌트
│   │   ├── auth/          # 인증 관련 컴포넌트
│   │   │   ├── SignUp.tsx
│   │   │   └── FindAccount.tsx
│   │   ├── map/           # 지도 관련 컴포넌트
│   │   │   ├── KakaoMap.tsx
│   │   │   ├── SimpleMap.tsx
│   │   │   └── SnackReportModal.tsx
│   │   ├── ui/            # 재사용 가능한 UI 컴포넌트 (shadcn/ui)
│   │   ├── Chat.tsx
│   │   ├── Community.tsx
│   │   ├── FestivalInfo.tsx
│   │   ├── LostAndFound.tsx
│   │   ├── MapView.tsx
│   │   └── MyPage.tsx
│   ├── data/              # 정적 데이터
│   │   ├── festivals.ts
│   │   └── touristPlaces.ts
│   ├── services/          # API 서비스
│   │   ├── api.ts         # REST API 클라이언트
│   │   └── websocket.ts   # WebSocket 클라이언트
│   ├── store/             # 상태 관리
│   │   └── authStore.ts   # 인증 상태 관리
│   ├── styles/            # 스타일 파일
│   │   └── globals.css
│   ├── App.tsx            # 메인 앱 컴포넌트
│   ├── main.tsx           # 진입점
│   └── index.css          # 전역 스타일
├── index.html             # HTML 템플릿
├── package.json           # 프로젝트 설정 및 의존성
├── vite.config.ts         # Vite 설정
├── README.md              # 프로젝트 문서
└── FRONTEND_START.md      # 빠른 시작 가이드

🚀 시작하기

필수 요구사항

• Node.js 18.x 이상
• npm 또는 yarn
• 백엔드 서버 실행 중 (기본 포트: 3001)

설치 및 실행

1. 의존성 설치

cd frontend
npm install

2. 개발 서버 실행

npm run dev

개발 서버는 기본적으로 http://localhost:3000에서 실행됩니다.

3. 네트워크 접근 허용 (다른 기기에서 접근 시)

npm run dev -- --host

💻 개발 가이드

API 설정

API 기본 URL은 src/services/api.ts에서 설정됩니다:

const API_BASE_URL = 'http://localhost:3001/api';

배포 환경에서는 환경 변수를 사용하도록 수정하는 것을 권장합니다.

상태 관리

인증 상태는 Zustand를 사용하여 관리됩니다:

• src/store/authStore.ts - 인증 관련 상태 및 액션

스타일링

• Tailwind CSS를 사용한 유틸리티 기반 스타일링
• 커스텀 색상:
  • Primary Blue: #0F4187
  • Primary Orange: #EE7500

주요 컴포넌트

• App.tsx: 메인 라우팅 및 페이지 관리
• 각 기능별 컴포넌트: 독립적인 페이지 컴포넌트
• UI 컴포넌트: src/components/ui/ - 재사용 가능한 UI 컴포넌트