scripts/DB/DB_SETUP.md

🚀 SmartEyeSsen Backend 설정 가이드

팀원을 위한 개발 환경 설정 가이드입니다.

---

📋 목차

1. 시스템 요구사항
2. MySQL 설치 및 설정
3. 프로젝트 클론 및 설정
4. 데이터베이스 생성
5. Python 환경 설정
6. 서버 실행
7. 트러블슈팅

---

1. 시스템 요구사항

필수 프로그램

• Python 3.9 이상
• MySQL 8.0 이상
• Git

운영체제별 지원

• ✅ Windows 10/11
• ✅ Windows + WSL2 (Ubuntu 20.04/22.04)
• ✅ macOS
• ✅ Linux (Ubuntu/Debian)

---

2. MySQL 설치 및 설정

MySQL 서비스 시작

# PowerShell (관리자 권한)
Start-Service MySQL80

MySQL 접속 테스트

mysql -u root -p
# 비밀번호 입력 후 접속되면 성공

---

2-2. Windows + WSL2 (Ubuntu)

WSL2 설치 (처음 사용하는 경우)

# PowerShell (관리자 권한)
wsl --install -d Ubuntu-22.04

재부팅 후 Ubuntu 사용자명/비밀번호 설정

MySQL 설치 (WSL 내부)

# WSL Ubuntu 터미널
sudo apt update
sudo apt install mysql-server -y

# MySQL 서비스 시작
sudo service mysql start

# Root 비밀번호 설정
sudo mysql

-- MySQL 콘솔에서
ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'your_password';
FLUSH PRIVILEGES;
EXIT;

MySQL 접속 테스트

mysql -u root -p
# 비밀번호 입력 후 접속되면 성공

---

3. 프로젝트 클론 및 설정

3-2. 환경 변수 설정

# .env 파일 생성 (Backend 폴더 내)
cd Backend
cp .env.example .env

.env 파일 수정

텍스트 에디터로 .env 파일을 열고 다음 항목을 수정:

# 데이터베이스 설정
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_actual_password  # ⚠️ 여기에 실제 MySQL 비밀번호 입력
DB_NAME=smarteyessen_db

# OpenAI API
OPENAI_API_KEY=  # 이건 바꿔야돼!

# 서버 설정
API_HOST=0.0.0.0
API_PORT=8000

---

4. 데이터베이스 생성

4-1. 스키마 적용 (데이터베이스 자동 생성)

erd_schema.sql 파일에는 데이터베이스 생성부터 테이블 생성, 초기 데이터 삽입까지 모든 작업이 포함되어 있습니다.

# 프로젝트 루트 디렉토리에서 실행
# (SmartEye-FrontWeb 폴더)
mysql -u root -p < Project/DB/erd_schema.sql

4-4. 테이블 생성 확인

mysql -u root -p smarteyessen_db

-- 12개 테이블 확인
SHOW TABLES;

-- 예상 결과:
-- +------------------------------+
-- | Tables_in_smarteyessen_db    |
-- +------------------------------+
-- | ai_descriptions              |
-- | combined_results             |
-- | document_types               |
-- | formatting_rules             |
-- | layout_elements              |
-- | pages                        |
-- | projects                     |
-- | question_elements            |
-- | question_groups              |
-- | text_contents                |
-- | text_versions                |
-- | users                        |
-- +------------------------------+

-- 초기 데이터 확인
SELECT * FROM document_types;
-- 2개 행이 조회되어야 함 (worksheet, document)

EXIT;

---

### **5-2. 의존성 설치**

```bash
# Backend 폴더로 이동
cd Backend

# 패키지 설치
pip install -r requirements.txt

---

6. 서버 실행

6-1. 서버 시작

Windows (PowerShell) 관학 실행 방법

# pytorch 환경 활성화
conda activate pytorch

# Backend 폴더로 이동
cd Backend

# 서버 실행
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

WSL/macOS/Linux 종영 실행방법

Backend 폴더로 이동

cd Backend

서버 실행

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

### **6-2. 서버 실행 확인**

다음과 같은 출력이 나타나면 성공:

INFO: Will watch for changes in these directories: ['C:\git\Smart-Eye-OCR\SmartEye-FrontWeb\Backend'] INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit) INFO: Started reloader process [12345] using WatchFiles INFO: Started server process [67890] INFO: Waiting for application startup.

🚀 SmartEyeSsen Backend Starting...

✅ Database connection successful! ✅ Database connection successful ✅ Database tables created successfully! ✅ Database tables initialized

✅ SmartEyeSsen Backend Ready! 📖 API Docs: http://localhost:8000/docs

INFO: Application startup complete.

### **6-3. API 문서 접속**

브라우저에서 다음 URL로 접속:

- 🏠 **메인**: http://localhost:8000
- 📖 **API 문서 (Swagger UI)**: http://localhost:8000/docs
- 📚 **API 문서 (ReDoc)**: http://localhost:8000/redoc
- ❤️ **헬스 체크**: http://localhost:8000/health

**헬스 체크 응답 예시:**

```json
{
  "status": "healthy",
  "message": "SmartEyeSsen Backend is running",
  "database": "connected",
  "timestamp": "2025-01-22T15:30:00.123456"
}