✅ 백엔드 구조 개선: - DatabaseService: 공통 DB 쿼리 로직 통합 - FileUploadService: 파일 업로드 로직 모듈화 및 트랜잭션 관리 개선 - 서비스 레이어 패턴 도입으로 코드 재사용성 향상 ✅ 프론트엔드 컴포넌트 개선: - LoadingSpinner, ErrorMessage, ConfirmDialog 공통 컴포넌트 생성 - 재사용 가능한 컴포넌트 라이브러리 구축 - deprecated/backup 파일들 완전 제거 ✅ 성능 최적화: - optimize_database.py: 핵심 DB 인덱스 자동 생성 - 쿼리 최적화 및 통계 업데이트 자동화 - VACUUM ANALYZE 자동 실행 ✅ 코드 정리: - 개별 SQL 마이그레이션 파일들을 legacy/ 폴더로 정리 - 중복된 마이그레이션 스크립트 정리 - 깔끔하고 체계적인 프로젝트 구조 완성 ✅ 자동 마이그레이션 시스템 강화: - complete_migrate.py: SQLAlchemy 기반 완전한 마이그레이션 - analyze_and_fix_schema.py: 백엔드 코드 분석 기반 스키마 수정 - fix_missing_tables.py: 누락된 테이블/컬럼 자동 생성 - start.sh: 배포 시 자동 실행 순서 최적화
This commit is contained in:
Hyungi Ahn
253
RULES.md
253
RULES.md
@@ -45,6 +45,7 @@
|
||||
- **Database Admin**: pgAdmin4
|
||||
- **Version Control**: Git
|
||||
- **Development**: VS Code + Python 확장
|
||||
- **Database Migration**: SQLAlchemy + 자동 마이그레이션 시스템
|
||||
|
||||
---
|
||||
|
||||
@@ -2325,4 +2326,254 @@ psql -U tkmp_user -d tk_mp_bom -f backend/scripts/PRODUCTION_MIGRATION.sql
|
||||
|
||||
---
|
||||
|
||||
**마지막 업데이트**: 2025년 9월 28일 (메인 서버 배포 가이드 추가)
|
||||
## 🔄 **시스템 리팩토링 완료 (2025-01-19)**
|
||||
|
||||
### ✅ **완료된 리팩토링 영역**
|
||||
|
||||
1. **백엔드 구조 개선** ✅
|
||||
- `DatabaseService`: 공통 DB 쿼리 로직 통합
|
||||
- `FileUploadService`: 파일 업로드 로직 모듈화
|
||||
- 중복 코드 제거 및 서비스 레이어 분리
|
||||
|
||||
2. **프론트엔드 컴포넌트 개선** ✅
|
||||
- 공통 컴포넌트 생성: `LoadingSpinner`, `ErrorMessage`, `ConfirmDialog`
|
||||
- 재사용 가능한 컴포넌트 라이브러리 구축
|
||||
- 사용하지 않는 deprecated/backup 파일들 정리
|
||||
|
||||
3. **성능 최적화** ✅
|
||||
- 핵심 DB 인덱스 자동 생성 (`optimize_database.py`)
|
||||
- 쿼리 최적화 및 통계 업데이트
|
||||
- 자동 VACUUM ANALYZE 실행
|
||||
|
||||
4. **코드 정리** ✅
|
||||
- 사용하지 않는 개별 SQL 마이그레이션 파일들 `legacy/` 폴더로 이동
|
||||
- 중복된 마이그레이션 스크립트 정리
|
||||
- 깔끔한 프로젝트 구조 완성
|
||||
|
||||
### 🚀 **리팩토링 후 시스템 구조**
|
||||
|
||||
```
|
||||
backend/
|
||||
├── services/
|
||||
│ ├── database_service.py # 🆕 공통 DB 서비스
|
||||
│ ├── file_upload_service.py # 🆕 파일 업로드 서비스
|
||||
│ └── ...
|
||||
├── scripts/
|
||||
│ ├── complete_migrate.py # 완전한 자동 마이그레이션
|
||||
│ ├── analyze_and_fix_schema.py # 스키마 분석 및 수정
|
||||
│ ├── optimize_database.py # 🆕 성능 최적화
|
||||
│ └── legacy/ # 기존 개별 마이그레이션 파일들
|
||||
└── ...
|
||||
|
||||
frontend/
|
||||
├── components/
|
||||
│ ├── common/
|
||||
│ │ ├── LoadingSpinner.jsx # 🆕 공통 로딩 컴포넌트
|
||||
│ │ ├── ErrorMessage.jsx # 🆕 공통 에러 컴포넌트
|
||||
│ │ ├── ConfirmDialog.jsx # 🆕 공통 확인 다이얼로그
|
||||
│ │ └── index.js # 🆕 공통 컴포넌트 export
|
||||
│ └── ...
|
||||
└── ...
|
||||
```
|
||||
|
||||
## 🗄️ 데이터베이스 자동 관리 시스템
|
||||
|
||||
### 📋 **개요**
|
||||
TK-MP-Project는 SQLAlchemy 모델 기반 자동 DB 마이그레이션 시스템을 사용합니다. 배포 시 백엔드 코드와 DB 스키마가 자동으로 동기화됩니다.
|
||||
|
||||
### 🔄 **자동 마이그레이션 프로세스**
|
||||
|
||||
#### **1. 시스템 구성**
|
||||
```
|
||||
backend/
|
||||
├── models.py # 메인 데이터 모델
|
||||
├── auth/models.py # 인증 관련 모델
|
||||
├── scripts/
|
||||
│ ├── simple_migrate.py # 간단하고 안정적인 마이그레이션 스크립트
|
||||
│ ├── auto_migrate.py # 복잡한 SQLAlchemy 기반 (백업용)
|
||||
│ └── generate_complete_schema.py # 스키마 생성 도구
|
||||
├── start.sh # 간단 마이그레이션 + 서버 시작
|
||||
└── Dockerfile # 자동화된 컨테이너 빌드
|
||||
```
|
||||
|
||||
#### **2. 배포 시 자동 실행 순서**
|
||||
1. **Docker 컨테이너 시작**
|
||||
2. **환경 변수 확인** (DB 설정 출력)
|
||||
3. **DB 연결 대기** (최대 120초, 2초 간격)
|
||||
4. **간단 SQL 마이그레이션 실행** (psycopg2 직접 사용)
|
||||
5. **필수 데이터 확인/생성** (관리자 계정, 인덱스)
|
||||
6. **FastAPI 서버 시작**
|
||||
|
||||
#### **3. 핵심 파일들**
|
||||
|
||||
**`backend/scripts/complete_migrate.py`** ⭐ **완전한 자동 마이그레이션**
|
||||
```python
|
||||
# SQLAlchemy 모델 기반 완전한 자동 마이그레이션
|
||||
# - 모든 테이블 자동 생성
|
||||
# - 기존 테이블에 누락된 컬럼 자동 추가
|
||||
# - 성능 인덱스 자동 생성
|
||||
# - 초기 사용자 데이터 자동 삽입
|
||||
# - macOS Docker와 Synology Container Manager 모두 지원
|
||||
# - 60초 DB 연결 대기 (2초 간격)
|
||||
```
|
||||
|
||||
**`backend/scripts/simple_migrate.py`** 🔄 **백업용 간단 방식**
|
||||
```python
|
||||
# psycopg2를 직접 사용하는 간단하고 안정적인 마이그레이션
|
||||
# - 기본 테이블 생성만 수행
|
||||
# - 메모리 사용량 최소화
|
||||
# - 명확한 에러 메시지
|
||||
```
|
||||
|
||||
**`backend/start.sh`**
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# 1. 환경 정보 출력 (디버깅용)
|
||||
echo "🖥️ 환경: $(uname -s) $(uname -m)"
|
||||
echo "🔧 DB 설정 확인:"
|
||||
|
||||
# 2. 완전한 DB 마이그레이션 실행
|
||||
python scripts/complete_migrate.py
|
||||
|
||||
# 3. 마이그레이션 실패해도 서버 시작 (기존 스키마 있을 수 있음)
|
||||
exec uvicorn app.main:app --host 0.0.0.0 --port 8000 --log-level info
|
||||
```
|
||||
|
||||
### 🛠️ **개발자 가이드**
|
||||
|
||||
#### **새로운 모델 추가 시**
|
||||
1. `backend/app/models.py` 또는 관련 모델 파일에 SQLAlchemy 모델 추가
|
||||
2. Docker 컨테이너 재시작 → **자동으로 테이블 생성됨**
|
||||
3. 추가 작업 불필요!
|
||||
|
||||
#### **기존 모델 수정 시**
|
||||
- **컬럼 추가**: 자동으로 추가됨
|
||||
- **컬럼 삭제**: 수동 마이그레이션 필요 (데이터 보호)
|
||||
- **컬럼 타입 변경**: 수동 마이그레이션 필요
|
||||
|
||||
#### **수동 마이그레이션이 필요한 경우**
|
||||
```sql
|
||||
-- 컬럼 삭제 (데이터 손실 주의)
|
||||
ALTER TABLE materials DROP COLUMN old_column;
|
||||
|
||||
-- 컬럼 타입 변경
|
||||
ALTER TABLE materials ALTER COLUMN quantity TYPE DECIMAL(12,3);
|
||||
|
||||
-- 데이터 마이그레이션
|
||||
UPDATE materials SET new_column = old_column WHERE condition;
|
||||
```
|
||||
|
||||
### 🚀 **배포 가이드**
|
||||
|
||||
#### **신규 배포 (완전 초기화)**
|
||||
```bash
|
||||
# 1. 컨테이너 완전 삭제
|
||||
docker-compose down -v
|
||||
|
||||
# 2. 새로 빌드 및 시작
|
||||
docker-compose up -d --build
|
||||
|
||||
# 3. 자동 마이그레이션 확인
|
||||
docker-compose logs backend | grep "마이그레이션"
|
||||
```
|
||||
|
||||
#### **기존 서버 업데이트**
|
||||
```bash
|
||||
# 1. 코드 업데이트
|
||||
git pull origin main
|
||||
|
||||
# 2. 백엔드 재빌드 및 재시작
|
||||
docker-compose up -d --build backend
|
||||
|
||||
# 3. 마이그레이션 로그 확인
|
||||
docker-compose logs backend | tail -20
|
||||
```
|
||||
|
||||
#### **Synology Container Manager 배포**
|
||||
```bash
|
||||
# 1. Synology 전용 설정 사용
|
||||
docker-compose -f docker-compose.synology.yml up -d --build
|
||||
|
||||
# 2. 컨테이너 상태 확인
|
||||
docker-compose -f docker-compose.synology.yml ps
|
||||
|
||||
# 3. 마이그레이션 로그 확인
|
||||
docker-compose -f docker-compose.synology.yml logs backend | grep -E "🚀|✅|❌"
|
||||
```
|
||||
|
||||
#### **마이그레이션 상태 확인**
|
||||
```bash
|
||||
# DB 연결 및 테이블 확인
|
||||
docker-compose exec postgres psql -U tkmp_user -d tk_mp_bom -c "\dt"
|
||||
|
||||
# 특정 테이블 구조 확인
|
||||
docker-compose exec postgres psql -U tkmp_user -d tk_mp_bom -c "\d materials"
|
||||
|
||||
# 관리자 계정 확인
|
||||
docker-compose exec postgres psql -U tkmp_user -d tk_mp_bom -c "SELECT username, role FROM users;"
|
||||
```
|
||||
|
||||
### 🔧 **트러블슈팅**
|
||||
|
||||
#### **마이그레이션 실패 시**
|
||||
```bash
|
||||
# 1. 백엔드 로그 확인
|
||||
docker-compose logs backend | grep -E "ERROR|마이그레이션"
|
||||
|
||||
# 2. DB 연결 상태 확인
|
||||
docker-compose exec backend python -c "from app.database import engine; print(engine.execute('SELECT 1').scalar())"
|
||||
|
||||
# 3. 수동 마이그레이션 실행
|
||||
docker-compose exec backend python scripts/auto_migrate.py
|
||||
```
|
||||
|
||||
#### **스키마 불일치 해결**
|
||||
```bash
|
||||
# 1. 현재 스키마 백업
|
||||
docker-compose exec postgres pg_dump -U tkmp_user tk_mp_bom > backup.sql
|
||||
|
||||
# 2. 완전 재생성 (주의: 데이터 손실)
|
||||
docker-compose down -v
|
||||
docker-compose up -d --build
|
||||
|
||||
# 3. 데이터 복원 (필요시)
|
||||
docker-compose exec postgres psql -U tkmp_user tk_mp_bom < backup.sql
|
||||
```
|
||||
|
||||
### 📊 **모니터링**
|
||||
|
||||
#### **자동 마이그레이션 로그 확인**
|
||||
```bash
|
||||
# 성공 로그
|
||||
docker-compose logs backend | grep "✅"
|
||||
|
||||
# 실패 로그
|
||||
docker-compose logs backend | grep "❌"
|
||||
|
||||
# 전체 마이그레이션 프로세스
|
||||
docker-compose logs backend | grep "🚀\|🔄\|✅\|❌"
|
||||
```
|
||||
|
||||
### ⚠️ **주의사항**
|
||||
|
||||
1. **데이터 백업**: 프로덕션 배포 전 반드시 DB 백업
|
||||
2. **점진적 배포**: 대규모 스키마 변경 시 단계별 배포 권장
|
||||
3. **롤백 계획**: 마이그레이션 실패 시 롤백 방법 사전 준비
|
||||
4. **모니터링**: 배포 후 시스템 정상 작동 확인
|
||||
|
||||
### 🎯 **장점**
|
||||
|
||||
- ✅ **완전 자동화**: 개발자 개입 없이 스키마 동기화
|
||||
- ✅ **크로스 플랫폼**: macOS Docker와 Synology Container Manager 모두 지원
|
||||
- ✅ **지능형 마이그레이션**: 기존 테이블에 누락된 컬럼 자동 추가
|
||||
- ✅ **안정성**: SQLAlchemy 모델 기반으로 타입 안전성 보장
|
||||
- ✅ **실수 방지**: 수동 SQL 작성으로 인한 오류 제거
|
||||
- ✅ **일관성 보장**: 모든 환경에서 동일한 스키마 적용
|
||||
- ✅ **빠른 배포**: 복잡한 마이그레이션 과정 자동화
|
||||
- ✅ **복원력**: 마이그레이션 실패해도 서버 시작 (기존 스키마 보호)
|
||||
- ✅ **성능 최적화**: 필요한 인덱스 자동 생성
|
||||
- ✅ **디버깅 친화적**: 명확한 로그 메시지와 환경 정보 출력
|
||||
|
||||
---
|
||||
|
||||
**마지막 업데이트**: 2025년 10월 19일 (자동 DB 마이그레이션 시스템 추가)
|
||||
|
||||
Reference in New Issue
Block a user