TK-FB-Project/docs/guides/SETUP.md

# 개발 환경 설정 가이드

> TK-FB-Project 로컬 개발 환경 구축 가이드

## 📋 목차

1. [시스템 요구사항](#시스템-요구사항)
2. [필수 도구 설치](#필수-도구-설치)
3. [프로젝트 설정](#프로젝트-설정)
4. [데이터베이스 설정](#데이터베이스-설정)
5. [애플리케이션 실행](#애플리케이션-실행)
6. [개발 도구](#개발-도구)
7. [문제 해결](#문제-해결)

---

## 시스템 요구사항

### 최소 사양
- **OS**: macOS, Linux, Windows 10+
- **CPU**: 2 Core 이상
- **RAM**: 4GB 이상
- **디스크**: 10GB 이상 여유 공간

### 권장 사양
- **OS**: macOS (Apple Silicon) 또는 Ubuntu 22.04 LTS
- **CPU**: 4 Core 이상
- **RAM**: 8GB 이상
- **디스크**: SSD 20GB 이상

---

## 필수 도구 설치

### 1. Node.js & npm

**macOS (Homebrew)**:
```bash
# Homebrew 설치 (없는 경우)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Node.js 설치
brew install node@20

# 버전 확인
node --version  # v20.x.x
npm --version   # 10.x.x
```

**Ubuntu/Debian**:
```bash
# NodeSource repository 추가
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

# Node.js 설치
sudo apt-get install -y nodejs

# 버전 확인
node --version
npm --version
```

**Windows**:
- [Node.js 공식 사이트](https://nodejs.org/)에서 LTS 버전 다운로드 및 설치

### 2. Git

**macOS**:
```bash
brew install git
```

**Ubuntu/Debian**:
```bash
sudo apt-get install git
```

**Windows**:
- [Git for Windows](https://git-scm.com/download/win) 다운로드

**설정**:
```bash
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
```

### 3. Docker & Docker Compose

**macOS**:
```bash
# Docker Desktop 설치
brew install --cask docker

# Docker Desktop 실행 후 확인
docker --version
docker-compose --version
```

**Ubuntu/Debian**:
```bash
# Docker 설치
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Docker Compose 설치
sudo apt-get install docker-compose-plugin

# 사용자를 docker 그룹에 추가
sudo usermod -aG docker $USER
newgrp docker

# 버전 확인
docker --version
docker compose version
```

**Windows**:
- [Docker Desktop for Windows](https://docs.docker.com/desktop/install/windows-install/) 설치

### 4. MySQL Client (선택사항)

**macOS**:
```bash
brew install mysql-client
```

**Ubuntu/Debian**:
```bash
sudo apt-get install mysql-client
```

---

## 프로젝트 설정

### 1. 저장소 클론

```bash
# HTTPS
git clone https://github.com/your-org/TK-FB-Project.git

# 또는 SSH
git clone git@github.com:your-org/TK-FB-Project.git

# 프로젝트 디렉토리로 이동
cd TK-FB-Project
```

### 2. 환경 변수 설정

```bash
# .env.example 복사
cp .env.example .env

# .env 파일 편집
nano .env  # 또는 vi, code 등
```

**.env 파일 설정**:
```bash
# Database
DB_HOST=localhost
DB_PORT=3306
DB_NAME=hyungi
DB_USER=hyungi
DB_PASSWORD=your_secure_password_here
DB_ROOT_PASSWORD=your_root_password_here

# API
API_PORT=20005
NODE_ENV=development

# JWT
JWT_SECRET=your_jwt_secret_key_at_least_32_characters
JWT_REFRESH_SECRET=your_refresh_secret_key_at_least_32_characters

# Email (선택사항)
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=your-email@gmail.com
EMAIL_PASSWORD=your-app-password

# OpenAI (선택사항)
OPENAI_API_KEY=your_openai_api_key
```

**보안 참고**:
```bash
# 강력한 랜덤 비밀번호 생성
openssl rand -base64 32

# 또는
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

### 3. 백엔드 의존성 설치

```bash
cd api.hyungi.net
npm install
```

**주요 의존성**:
- express: 웹 프레임워크
- mysql2: MySQL 드라이버
- jsonwebtoken: JWT 인증
- bcryptjs: 비밀번호 해싱
- cors: CORS 미들웨어
- dotenv: 환경변수 관리

### 4. 프론트엔드 설정

```bash
cd ../web-ui
# 프론트엔드는 Vanilla JS이므로 별도 빌드 불필요
```

---

## 데이터베이스 설정

### 방법 1: Docker Compose (권장)

```bash
# 프로젝트 루트에서
cd /path/to/TK-FB-Project

# Docker 컨테이너 시작
docker-compose up -d db

# 로그 확인
docker-compose logs -f db

# MySQL 준비 확인 (약 30초 소요)
docker-compose exec db mysqladmin ping -h localhost
```

**초기 데이터 로드**:
```bash
# SQL 파일 임포트
docker-compose exec -T db mysql -u hyungi -p hyungi < hyungi.sql

# 비밀번호 입력: .env 파일의 DB_PASSWORD
```

### 방법 2: 로컬 MySQL 설치

**macOS**:
```bash
# MySQL 설치
brew install mysql@8.0

# MySQL 시작
brew services start mysql@8.0

# 보안 설정
mysql_secure_installation
```

**Ubuntu/Debian**:
```bash
# MySQL 설치
sudo apt-get install mysql-server

# MySQL 시작
sudo systemctl start mysql
sudo systemctl enable mysql

# 보안 설정
sudo mysql_secure_installation
```

**데이터베이스 생성**:
```bash
# MySQL 접속
mysql -u root -p

# SQL 실행
CREATE DATABASE hyungi CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'hyungi'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON hyungi.* TO 'hyungi'@'localhost';
FLUSH PRIVILEGES;
EXIT;

# 데이터 임포트
mysql -u hyungi -p hyungi < hyungi.sql
```

### 데이터베이스 확인

```bash
# Docker 사용 시
docker-compose exec db mysql -u hyungi -p hyungi

# 로컬 MySQL 사용 시
mysql -u hyungi -p hyungi
```

```sql
-- 테이블 확인
SHOW TABLES;

-- 사용자 확인
SELECT * FROM users LIMIT 5;

-- 데이터 확인
SELECT COUNT(*) FROM daily_work_reports;
```

---

## 애플리케이션 실행

### 개발 모드 (Docker Compose)

```bash
# 전체 서비스 시작
docker-compose up

# 백그라운드 실행
docker-compose up -d

# 로그 확인
docker-compose logs -f

# 특정 서비스 로그
docker-compose logs -f api
docker-compose logs -f web

# 서비스 중지
docker-compose down

# 볼륨 포함 완전 삭제
docker-compose down -v
```

### 개발 모드 (로컬 실행)

**터미널 1 - 백엔드**:
```bash
cd api.hyungi.net

# 개발 모드 (nodemon 사용)
npm run dev

# 또는 일반 실행
npm start
```

**터미널 2 - 프론트엔드**:
```bash
cd web-ui

# 간단한 HTTP 서버 실행
python3 -m http.server 8080

# 또는 Node.js http-server
npx http-server -p 8080

# 또는 PHP
php -S localhost:8080
```

### 접속 확인

- **프론트엔드**: http://localhost:8080
- **백엔드 API**: http://localhost:20005/api
- **데이터베이스**: localhost:3306

**API 테스트**:
```bash
# Health check
curl http://localhost:20005/api/health

# 로그인 테스트
curl -X POST http://localhost:20005/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your_password"}'
```

---

## 개발 도구

### 1. VSCode 확장 프로그램

**필수**:
- ESLint
- Prettier - Code formatter
- MySQL (cweijan.vscode-mysql-client2)
- Docker

**권장**:
- GitLens
- Thunder Client (API 테스트)
- Live Server
- JavaScript (ES6) code snippets

**설치**:
```bash
# VSCode에서
Cmd/Ctrl + Shift + X → 확장 프로그램 검색 및 설치
```

### 2. VSCode 설정

`.vscode/settings.json`:
```json
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "javascript.suggest.autoImports": true,
  "javascript.updateImportsOnFileMove.enabled": "always",
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}
```

### 3. 디버깅 설정

`.vscode/launch.json`:
```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch API Server",
      "skipFiles": ["<node_internals>/**"],
      "program": "${workspaceFolder}/api.hyungi.net/index.js",
      "env": {
        "NODE_ENV": "development"
      }
    }
  ]
}
```

### 4. 유용한 명령어

```bash
# 패키지 업데이트 확인
npm outdated

# 보안 취약점 확인
npm audit

# 보안 취약점 자동 수정
npm audit fix

# 캐시 정리
npm cache clean --force

# node_modules 재설치
rm -rf node_modules package-lock.json
npm install
```

---

## 문제 해결

### 일반적인 문제

#### 1. Port already in use

**증상**:
```
Error: listen EADDRINUSE: address already in use :::20005
```

**해결**:
```bash
# 포트 사용 중인 프로세스 확인
lsof -i :20005

# 프로세스 종료
kill -9 <PID>

# 또는 다른 포트 사용
# .env 파일에서 API_PORT 변경
```

#### 2. MySQL 연결 실패

**증상**:
```
Error: connect ECONNREFUSED 127.0.0.1:3306
```

**해결**:
```bash
# Docker 사용 시
docker-compose ps  # db 컨테이너 상태 확인
docker-compose up -d db  # db 재시작

# 로컬 MySQL 사용 시
sudo systemctl status mysql  # 상태 확인
sudo systemctl start mysql   # MySQL 시작

# 연결 테스트
mysql -h localhost -u hyungi -p
```

#### 3. Permission denied

**증상**:
```
Error: EACCES: permission denied
```

**해결**:
```bash
# Docker 권한 문제
sudo usermod -aG docker $USER
newgrp docker

# 파일 권한 문제
sudo chown -R $USER:$USER /path/to/project
```

#### 4. Module not found

**증상**:
```
Error: Cannot find module 'express'
```

**해결**:
```bash
# node_modules 재설치
cd api.hyungi.net
rm -rf node_modules package-lock.json
npm install
```

#### 5. JWT 토큰 오류

**증상**:
```
Error: jwt malformed
Error: invalid signature
```

**해결**:
```bash
# .env 파일 확인
# JWT_SECRET이 올바르게 설정되어 있는지 확인

# 토큰 재발급
# 로그아웃 후 다시 로그인
```

### 데이터베이스 문제

#### MySQL 8.0 호환성

**증상**:
```
Error: ER_NOT_SUPPORTED_AUTH_MODE
```

**해결**:
```sql
-- MySQL 접속
mysql -u root -p

-- 인증 방식 변경
ALTER USER 'hyungi'@'localhost' IDENTIFIED WITH mysql_native_password BY 'your_password';
FLUSH PRIVILEGES;
```

#### 한글 깨짐

**해결**:
```sql
-- 데이터베이스 문자셋 확인
SHOW VARIABLES LIKE 'character_set%';

-- 테이블 문자셋 변경
ALTER TABLE daily_work_reports CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

### Docker 문제

#### 컨테이너 재시작

```bash
# 컨테이너 재시작
docker-compose restart

# 특정 서비스만
docker-compose restart api

# 완전 재빌드
docker-compose down
docker-compose build --no-cache
docker-compose up -d
```

#### 볼륨 문제

```bash
# 볼륨 확인
docker volume ls

# 볼륨 삭제 (주의: 데이터 손실)
docker-compose down -v

# 특정 볼륨만 삭제
docker volume rm tk-fb-project_mysql_data
```

---

## 추가 리소스

### 공식 문서
- [Node.js](https://nodejs.org/docs)
- [Express](https://expressjs.com/)
- [MySQL](https://dev.mysql.com/doc/)
- [Docker](https://docs.docker.com/)

### 내부 문서
- [아키텍처 개요](../architecture/OVERVIEW.md)
- [API 문서](../api/ENDPOINTS.md)
- [코딩 스타일 가이드](CODING_STYLE.md)
- [문제 해결 가이드](TROUBLESHOOTING.md)

### 커뮤니티
- [Node.js GitHub](https://github.com/nodejs/node)
- [Stack Overflow](https://stackoverflow.com/questions/tagged/node.js)

---

## 체크리스트

설정 완료 확인:

- [ ] Node.js 설치 (v20+)
- [ ] Git 설치 및 설정
- [ ] Docker 설치 및 실행
- [ ] 프로젝트 클론
- [ ] .env 파일 생성 및 설정
- [ ] npm install 완료
- [ ] 데이터베이스 생성 및 데이터 로드
- [ ] 백엔드 서버 실행 확인
- [ ] 프론트엔드 서버 실행 확인
- [ ] API 테스트 성공
- [ ] 로그인 성공
- [ ] VSCode 확장 프로그램 설치

---

**도움이 필요하면**: 프로젝트 관리자에게 문의하세요.

*마지막 업데이트: 2025-12-11*